zmemory 0.1.0

package/src/bus/server.js

@@ -0,0 +1,51 @@
+import http from "http";
+import fs from "fs";
+
+// Very lightweight event bus using Server Sent Events
+export function startEventBus() {
+  const port = 4322;
+  const clients = [];
+
+  const server = http.createServer((req, res) => {
+    if (req.url === "/events") {
+      res.writeHead(200, {
+        "Content-Type": "text/event-stream",
+        "Cache-Control": "no-cache",
+        Connection: "keep-alive"
+      });
+
+      clients.push(res);
+      return;
+    }
+
+    res.writeHead(404);
+    res.end();
+  });
+
+  server.listen(port);
+  console.log("ZMemory event bus running http://localhost:" + port);
+
+  const log = ".zmemory/logs/events.jsonl";
+  let size = fs.existsSync(log) ? fs.statSync(log).size : 0;
+
+  setInterval(() => {
+    if (!fs.existsSync(log)) return;
+    const stats = fs.statSync(log);
+
+    if (stats.size > size) {
+      const stream = fs.createReadStream(log, { start: size, end: stats.size });
+
+      let data = "";
+      stream.on("data", (c) => (data += c));
+
+      stream.on("end", () => {
+        clients.forEach((c) => {
+          c.write(`data: ${data}\n\n`);
+        });
+      });
+
+      size = stats.size;
+    }
+  }, 1000);
+}
+

package/src/commands/agent.js

@@ -0,0 +1,42 @@
+import { registerAgent, listAgents } from "../lib/coordination/agents.js";
+
+export async function agentCommand(args) {
+  const sub = args[0];
+
+  if (sub === "register") {
+    const get = (f) => {
+      const i = args.indexOf(f);
+      return i !== -1 ? args[i + 1] : null;
+    };
+
+    const agent = get("--agent");
+    const session = get("--session");
+    const task = get("--task") || "";
+
+    if (!agent || !session) {
+      console.log("usage: zmemory agent register --agent <name> --session <id>");
+      return;
+    }
+
+    registerAgent({ agent, session, task });
+    console.log("agent registered", session);
+    return;
+  }
+
+  if (sub === "list" || sub === "agents") {
+    const agents = listAgents();
+
+    if (!agents.length) {
+      console.log("no active agents");
+      return;
+    }
+
+    console.log("Active agents\n");
+
+    for (const a of agents) {
+      console.log(a.session);
+      if (a.task) console.log("  task:", a.task);
+      console.log();
+    }
+  }
+}

package/src/commands/archive.js

@@ -0,0 +1,32 @@
+import fs from "fs";
+import path from "path";
+import { getRunBase, getArchivedRunBase } from "../lib/run.js";
+
+export async function archiveRun(args) {
+  const i = args.indexOf("--run");
+  const run = i !== -1 ? args[i + 1] : null;
+
+  if (!run) {
+    console.log("missing --run");
+    return;
+  }
+
+  let active, archived;
+  try {
+    active = getRunBase(run);
+    archived = getArchivedRunBase(run);
+  } catch {
+    console.log("invalid run id");
+    return;
+  }
+
+  if (!fs.existsSync(active)) {
+    console.log("run not found");
+    return;
+  }
+
+  fs.mkdirSync(path.dirname(archived), { recursive: true });
+  fs.renameSync(active, archived);
+
+  console.log(`run archived: ${run}`);
+}

package/src/commands/bootstrap.js

@@ -0,0 +1,7 @@
+import { ensureZMemory } from "../integrations/auto-bootstrap.js";
+
+export async function bootstrapCommand() {
+  ensureZMemory();
+  console.log("ZMemory bootstrap complete");
+}
+

package/src/commands/bus.js

@@ -0,0 +1,6 @@
+import { startEventBus } from "../bus/server.js";
+
+export async function busCommand() {
+  startEventBus();
+}
+

package/src/commands/claim.js

@@ -0,0 +1,66 @@
+import { claimPattern, listClaims, releaseClaims } from "../lib/coordination/claims.js";
+
+export async function claimCommand(args) {
+  const sub = args[0];
+
+  // NEW UX: zmemory claim <pattern> --session <id>
+  // Backward compatible with old: zmemory claim claim <pattern>
+  if (sub && sub !== "claims" && sub !== "release") {
+    const pattern = sub === "claim" ? args[1] : sub;
+    const get = (f) => {
+      const i = args.indexOf(f);
+      return i !== -1 ? args[i + 1] : null;
+    };
+
+    const session = get("--session");
+    const task = get("--task") || "";
+
+    if (!pattern || !session) {
+      console.log("usage: zmemory claim <pattern> --session <id>");
+      return;
+    }
+
+    const res = claimPattern(pattern, { session, task });
+
+    if (res.agents.length > 1) {
+      console.log("warning: pattern already claimed\n");
+    }
+
+    console.log("claimed", pattern);
+    return;
+  }
+
+  if (sub === "claims") {
+    const claims = listClaims();
+
+    if (!claims.length) {
+      console.log("no claims");
+      return;
+    }
+
+    for (const c of claims) {
+      console.log(c.pattern);
+      for (const a of c.agents || []) {
+        console.log("  ", a.session, a.task || "");
+      }
+      console.log();
+    }
+    return;
+  }
+
+  if (sub === "release") {
+    const get = (f) => {
+      const i = args.indexOf(f);
+      return i !== -1 ? args[i + 1] : null;
+    };
+
+    const session = get("--session");
+    if (!session) {
+      console.log("usage: zmemory release --session <id>");
+      return;
+    }
+
+    releaseClaims(session);
+    console.log("claims released", session);
+  }
+}

package/src/commands/config.js

@@ -0,0 +1,29 @@
+import { readConfig, writeConfig } from "../lib/config.js";
+
+export async function configCommand(args) {
+  const sub = args[0];
+
+  if (sub === "show") {
+    console.log(JSON.stringify(readConfig(), null, 2));
+    return;
+  }
+
+  if (sub === "set") {
+    const key = args[1];
+    const value = args[2];
+
+    if (!key || !value || !key.trim() || !value.trim()) {
+      console.log("usage: zmemory config set <key> <value>");
+      return;
+    }
+
+    const cfg = readConfig();
+    cfg[key] = value;
+    writeConfig(cfg);
+
+    console.log("config updated", key, "=", value);
+    return;
+  }
+
+  console.log("usage: zmemory config show|set");
+}

package/src/commands/context.js

@@ -0,0 +1,269 @@
+import fs from "fs";
+import path from "path";
+import { assertValidRunId, getRunFile, readRunState } from "../lib/run.js";
+
+export async function generateContext(args) {
+  const r = args.indexOf("--run");
+  const roleIndex = args.indexOf("--role");
+  const eventsIndex = args.indexOf("--include-events");
+  const budgetIndex = args.indexOf("--budget");
+
+  const run = r !== -1 ? args[r + 1] : null;
+  const role = roleIndex !== -1 ? args[roleIndex + 1] : "executor";
+  const includeEvents = eventsIndex !== -1 ? Number(args[eventsIndex + 1]) : 0;
+  const budget = budgetIndex !== -1 ? Number(args[budgetIndex + 1]) : null;
+
+  if (!run) {
+    console.log("missing --run");
+    return;
+  }
+
+  try {
+    assertValidRunId(run);
+  } catch {
+    console.log("invalid run id");
+    return;
+  }
+
+  if (typeof role !== "string" || role.trim() === "" || !/^[A-Za-z0-9_-]+$/.test(role)) {
+    console.log("invalid role");
+    return;
+  }
+
+  let state;
+  try {
+    state = readRunState(run);
+  } catch (e) {
+    console.log(e.message === "run not found" ? "run not found" : "invalid run id");
+    return;
+  }
+
+  const taskPath = getRunFile(run, "task.md");
+  if (!fs.existsSync(taskPath)) {
+    console.log("run not found");
+    return;
+  }
+  const task = fs.readFileSync(taskPath, "utf8");
+
+  let projectFacts = "";
+  const projectFile = `.zmemory/project.md`;
+  if (fs.existsSync(projectFile)) {
+    projectFacts = fs.readFileSync(projectFile, "utf8");
+  }
+
+  let patternsFacts = "";
+  const patternsFile = `.zmemory/patterns.md`;
+  if (fs.existsSync(patternsFile)) {
+    patternsFacts = fs.readFileSync(patternsFile, "utf8");
+  }
+
+  let commandFacts = "";
+  const commandsFile = `.zmemory/commands.md`;
+  if (fs.existsSync(commandsFile)) {
+    commandFacts = fs.readFileSync(commandsFile, "utf8");
+  }
+
+  let configFacts = "";
+  const configFile = `.zmemory/config.json`;
+  if (fs.existsSync(configFile)) {
+    try {
+      const cfg = JSON.parse(fs.readFileSync(configFile, "utf8"));
+      configFacts = `Project: ${cfg.project_name}\nMemory Mode: ${cfg.memory_mode}`;
+    } catch {}
+  }
+
+  let events = [];
+  if (includeEvents > 0) {
+    const p = getRunFile(run, "events.jsonl");
+    if (fs.existsSync(p)) {
+      events = fs
+        .readFileSync(p, "utf8")
+        .split("\n")
+        .filter(Boolean)
+        .slice(-includeEvents);
+    }
+  }
+
+  let body = "";
+
+  if (role === "executor") {
+    const attempts = state.attempts || {};
+    const allowed = Array.isArray(state.allowed_files) ? state.allowed_files : [];
+    const forbidden = Array.isArray(state.forbidden_files) ? state.forbidden_files : [];
+    body = `## Role
+Executor
+
+## Task
+${task}
+
+## Current Run State
+Status: ${state.status}
+Current Step: ${state.current_step}
+Next Action: ${state.next_action}
+
+## Scope
+Allowed files:
+${allowed.join("\n")}
+
+Forbidden files:
+${forbidden.join("\n")}
+
+## Acceptance Criteria
+- Implement the requested task
+- Do not modify forbidden files
+- Keep changes minimal and scoped
+
+## Previous Attempts
+Current error signature: ${attempts.current_error_signature || "none"}
+Repeated count: ${attempts.repeated_count || 0}
+
+## Stop Conditions
+- Scope expands beyond allowed files
+- Same failure repeats twice
+- Task requirements become ambiguous
+
+## Required Output
+- Files changed
+- Commands executed
+- Test results
+- Remaining blockers (if any)
+`;
+  } else if (role === "reviewer") {
+    body = `## Role
+Reviewer
+
+## Task
+Review executor output for task:
+${task}
+
+## Review Checklist
+- Scope respected
+- Minimal patch
+- Tests sufficient
+- No hidden behavior change
+`;
+  } else if (role === "tester") {
+    body = `## Role
+Tester
+
+## Task
+Validate implementation for:
+${task}
+
+## Required Output
+- Commands executed
+- Test results
+- Failures if any
+`;
+  } else if (role === "brain") {
+    body = `## Role
+Brain
+
+## Task
+${task}
+
+## Responsibilities
+- Plan solution steps
+- Decide next role
+- Define safe scope
+`;
+  } else if (role === "router") {
+    const attempts = state.attempts || {};
+    const blockers = state.blockers || [];
+    let suggestion = "executor";
+
+    if (blockers.length > 0) suggestion = "brain";
+    else if ((attempts.repeated_count || 0) >= 3) suggestion = "brain";
+    else if ((attempts.repeated_count || 0) >= 2) suggestion = "reviewer";
+
+    body = `## Role
+Router
+
+## Task
+Route next action for:
+${task}
+
+## Run Signals
+Repeated failures: ${attempts.repeated_count || 0}
+Current error: ${attempts.current_error_signature || "none"}
+Blockers: ${blockers.join(", ")}
+
+## Suggested Next Role
+${suggestion}
+
+## Available Roles
+- executor
+- reviewer
+- tester
+- brain
+`;
+  } else {
+    if (role === "handoff_receiver") {
+      body = `## Role
+Handoff Receiver
+
+## Task
+Continue work for:
+${task}
+
+## Instructions
+- Read the handoff packet
+- Continue from the next action
+- Do not repeat previous failed attempts
+`;
+    } else {
+      body = `## Role
+${role}
+
+## Task
+${task}
+`;
+    }
+  }
+
+  const ctx = `# ZMemory Context Packet
+
+${body}
+
+## Run Status
+Status: ${state.status}
+Step: ${state.current_step}
+Next Action: ${state.next_action}
+
+## Project Facts
+${configFacts}
+
+${projectFacts}
+
+## Important Decisions
+${fs.existsSync('.zmemory/decisions.md') ? fs.readFileSync('.zmemory/decisions.md','utf8') : ''}
+
+## Known Failures
+${fs.existsSync('.zmemory/failures.md') ? fs.readFileSync('.zmemory/failures.md','utf8') : ''}
+
+## Known Patterns
+${patternsFacts}
+
+## Useful Commands
+${commandFacts}
+
+## Recent Events
+${events.join("\n")}
+`;
+
+  let finalCtx = ctx;
+
+  if (budget && ctx.length > budget) {
+    finalCtx = ctx.slice(0, budget) + "\n...truncated...";
+  }
+
+  const packetPath = `.zmemory/packets/latest-context.md`;
+  fs.mkdirSync(path.dirname(packetPath), { recursive: true });
+  fs.writeFileSync(packetPath, finalCtx);
+
+  // also write role-specific packet inside run directory
+  const rolePacket = getRunFile(run, `context.${role}.md`);
+  fs.writeFileSync(rolePacket, finalCtx);
+
+  console.log(finalCtx);
+}

package/src/commands/daemon.js

@@ -0,0 +1,6 @@
+import { startDaemon } from "../daemon/zmemoryd.js";
+
+export async function daemonCommand() {
+  startDaemon();
+}
+

package/src/commands/decision.js

@@ -0,0 +1,12 @@
+import { appendFile, now } from "../lib/fs.js";
+
+export async function decisionAdd(args) {
+  const text = args.join(" ").trim();
+  if (!text) {
+    console.log("usage: zmemory decision <text>");
+    return;
+  }
+  const entry = `\n## ${now()}\n${text}\n`;
+  appendFile(`.zmemory/decisions.md`, entry);
+  console.log("decision recorded");
+}

package/src/commands/doctor.js

@@ -0,0 +1,100 @@
+import fs from "fs";
+
+export async function doctor() {
+  const issues = [];
+  const warnings = [];
+
+  if (!fs.existsSync(".zmemory")) {
+    console.log("ZMemory not initialized");
+    return;
+  }
+
+  const required = [
+    ".zmemory/config.json",
+    ".zmemory/project.md",
+    ".zmemory/decisions.md",
+    ".zmemory/failures.md",
+    ".zmemory/logs/events.jsonl",
+    ".zmemory/runs/active",
+    ".zmemory/agents",
+    ".zmemory/claims"
+  ];
+
+  required.forEach((p) => {
+    if (!fs.existsSync(p)) issues.push(`missing: ${p}`);
+  });
+
+  const runsDir = ".zmemory/runs/active";
+  if (fs.existsSync(runsDir)) {
+    const runs = fs.readdirSync(runsDir);
+
+    runs.forEach((r) => {
+      const base = `${runsDir}/${r}`;
+      const requiredRunFiles = ["state.json", "task.md", "events.jsonl"];
+
+      requiredRunFiles.forEach((f) => {
+        const p = `${base}/${f}`;
+        if (!fs.existsSync(p)) {
+          issues.push(`run ${r} missing ${f}`);
+        }
+      });
+    });
+  }
+
+  // check logs writable
+  try {
+    const testFile = ".zmemory/logs/.doctor-write-test";
+    fs.writeFileSync(testFile, "ok");
+    fs.unlinkSync(testFile);
+  } catch {
+    issues.push("logs directory not writable");
+  }
+
+  // check claims health
+  const claimsDir = ".zmemory/claims";
+  if (fs.existsSync(claimsDir)) {
+    const files = fs.readdirSync(claimsDir);
+    for (const f of files) {
+      try {
+        JSON.parse(fs.readFileSync(`${claimsDir}/${f}`, "utf8"));
+      } catch {
+        issues.push(`corrupted claim file: ${f}`);
+      }
+    }
+  }
+
+  // check agents
+  const agentsDir = ".zmemory/agents";
+  if (fs.existsSync(agentsDir)) {
+    const agents = fs.readdirSync(agentsDir);
+    if (!agents.length) {
+      warnings.push("no active agents registered");
+    }
+  }
+
+  // check event log size (suggest rotation if large)
+  const eventsFile = ".zmemory/logs/events.jsonl";
+  if (fs.existsSync(eventsFile)) {
+    const size = fs.statSync(eventsFile).size;
+    if (size > 5 * 1024 * 1024) {
+      warnings.push("events.jsonl larger than 5MB (consider rotation)");
+    }
+  }
+
+  if (!issues.length) {
+    console.log("ZMemory doctor: OK");
+    if (warnings.length) {
+      console.log("\nWarnings:\n");
+      warnings.forEach((w) => console.log("-", w));
+    }
+    return;
+  }
+
+  console.log("ZMemory doctor found issues:\n");
+  issues.forEach((i) => console.log("-", i));
+
+  if (warnings.length) {
+    console.log("\nWarnings:\n");
+    warnings.forEach((w) => console.log("-", w));
+  }
+}