zmemory 0.1.0

package/src/commands/resume.js

@@ -0,0 +1,79 @@
+import fs from "fs";
+import { generateContext } from "./context.js";
+import { isValidRunId } from "../lib/run.js";
+import { listAgents } from "../lib/coordination/agents.js";
+import { listClaims } from "../lib/coordination/claims.js";
+
+export async function resumeRun() {
+  const base = ".zmemory/runs/active";
+
+  if (!fs.existsSync(base)) {
+    console.log("no active runs");
+    return;
+  }
+
+  const runs = fs.readdirSync(base).filter((r) => {
+    if (!isValidRunId(r)) return false;
+    try {
+      return fs.statSync(`${base}/${r}`).isDirectory();
+    } catch {
+      return false;
+    }
+  });
+
+  if (!runs.length) {
+    console.log("no active runs");
+    return;
+  }
+
+  const latest = runs.sort().reverse()[0];
+
+  console.log("# ZMemory Resume\n");
+
+  // Active agents
+  const agents = listAgents();
+  console.log("Active agents");
+  if (!agents.length) console.log("  none");
+  for (const a of agents) {
+    console.log(`  ${a.session}`);
+    if (a.task) console.log(`    task: ${a.task}`);
+  }
+  console.log();
+
+  // Claims
+  const claims = listClaims();
+  console.log("Open claims");
+  if (!claims.length) console.log("  none");
+  for (const c of claims) {
+    console.log(`  ${c.pattern}`);
+    for (const ag of c.agents || []) {
+      console.log(`    ${ag.session} ${ag.task || ""}`);
+    }
+  }
+  console.log();
+
+  // Recent events
+  const eventsFile = ".zmemory/logs/events.jsonl";
+  console.log("Recent events");
+  if (fs.existsSync(eventsFile)) {
+    const lines = fs
+      .readFileSync(eventsFile, "utf8")
+      .split("\n")
+      .filter(Boolean)
+      .slice(-5);
+
+    for (const l of lines) {
+      try {
+        const e = JSON.parse(l);
+        console.log(`  ${e.role || "agent"}: ${e.summary || ""}`);
+      } catch {}
+    }
+  } else {
+    console.log("  none");
+  }
+  console.log();
+
+  console.log("Resuming run:", latest, "\n");
+
+  await generateContext(["--run", latest, "--role", "executor"]);
+}

package/src/commands/route.js

@@ -0,0 +1,67 @@
+import fs from "fs";
+import { getRunFile, isValidRunId, ensureRunExists } from "../lib/run.js";
+import { listAgents } from "../lib/agents.js";
+
+export async function routeRun(args) {
+  const i = args.indexOf("--run");
+  const run = i !== -1 ? args[i + 1] : null;
+
+  if (!run) {
+    console.log("missing --run");
+    return;
+  }
+
+  if (!isValidRunId(run)) {
+    console.log("invalid run id");
+    return;
+  }
+
+  try {
+    ensureRunExists(run);
+  } catch {
+    console.log("run not found");
+    return;
+  }
+
+  let state;
+  try {
+    state = JSON.parse(fs.readFileSync(getRunFile(run, "state.json"), "utf8"));
+  } catch {
+    console.log("run not found");
+    return;
+  }
+
+  const attempts = state.attempts || {};
+  const repeated = attempts.repeated_count || 0;
+  const blockers = Array.isArray(state.blockers) ? state.blockers : [];
+
+  let role = "executor";
+  let reason = "continue execution";
+
+  const agents = listAgents();
+  const activeRoles = Object.values(agents).map((a) => a.role);
+
+  if (blockers.length) {
+    role = "brain";
+    reason = "blockers present";
+  } else if (repeated >= 3) {
+    role = "brain";
+    reason = "repeated failures >=3";
+  } else if (repeated >= 2) {
+    role = "reviewer";
+    reason = "repeated failures >=2";
+  }
+
+  if (role === "executor" && activeRoles.includes("executor")) {
+    reason = "executor already active, waiting";
+  }
+
+  const result = `# ZMemory Router\n\nRun: ${run}\nNext Role: ${role}\nReason: ${reason}\nRepeated Failures: ${repeated}\nBlockers: ${blockers.join(", ") || "none"}\n\nSuggested Command:\nzmemory context --run ${run} --role ${role}\n`;
+
+  try {
+    const p = getRunFile(run, "router.md");
+    fs.writeFileSync(p, result);
+  } catch {}
+
+  console.log(result);
+}

package/src/commands/runs.js

@@ -0,0 +1,47 @@
+import fs from "fs";
+import path from "path";
+
+export async function listRuns() {
+  const base = ".zmemory/runs/active";
+
+  if (!fs.existsSync(base)) {
+    console.log("No runs directory. Run `zmemory start-run` first.");
+    return;
+  }
+
+  const runs = fs.readdirSync(base).filter((r) => r.startsWith("run_"));
+
+  if (!runs.length) {
+    console.log("No active runs.");
+    return;
+  }
+
+  console.log("Active Runs");
+  console.log("-----------");
+
+  runs.forEach((runId) => {
+    const runDir = path.join(base, runId);
+    const statePath = path.join(runDir, "state.json");
+    const taskPath = path.join(runDir, "task.md");
+
+    let task = "(unknown task)";
+    let status = "unknown";
+
+    if (fs.existsSync(taskPath)) {
+      const txt = fs.readFileSync(taskPath, "utf8");
+      const line = txt.split("\n").slice(1).join(" ").trim();
+      if (line) task = line;
+    }
+
+    if (fs.existsSync(statePath)) {
+      try {
+        const state = JSON.parse(fs.readFileSync(statePath, "utf8"));
+        status = state.status || "unknown";
+      } catch {}
+    }
+
+    console.log(`${runId}  ${task}`);
+    console.log(`  status: ${status}`);
+    console.log();
+  });
+}

package/src/commands/search.js

@@ -0,0 +1,159 @@
+import fs from "fs";
+import path from "path";
+
+const INDEX_PATH = ".zmemory/index.json";
+
+function loadIgnore() {
+  const p = ".zmemoryignore";
+  if (!fs.existsSync(p)) return [];
+  return fs.readFileSync(p, "utf8").split("\n").filter(Boolean);
+}
+
+function buildIndex(base, ignore = []) {
+  const index = [];
+
+  function walk(dir) {
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+
+    for (const e of entries) {
+      const p = path.join(dir, e.name);
+      if (ignore.some((i) => p.includes(i))) continue;
+
+      if (e.isDirectory()) {
+        walk(p);
+        continue;
+      }
+
+      if (!/\.(md|json|jsonl|txt)$/i.test(e.name)) continue;
+
+      try {
+        const content = fs.readFileSync(p, "utf8");
+        index.push({ path: p, content: content.toLowerCase() });
+      } catch {}
+    }
+  }
+
+  walk(base);
+
+  fs.mkdirSync(path.dirname(INDEX_PATH), { recursive: true });
+  fs.writeFileSync(INDEX_PATH, JSON.stringify(index));
+
+  return index;
+}
+
+function loadIndex(base, ignore) {
+  if (!fs.existsSync(INDEX_PATH)) {
+    return buildIndex(base, ignore);
+  }
+
+  try {
+    const raw = JSON.parse(fs.readFileSync(INDEX_PATH, "utf8"));
+    if (Array.isArray(raw)) return raw;
+  } catch {}
+
+  return buildIndex(base, ignore);
+}
+
+function scan(dir, query, results = [], ignore = []) {
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+
+  for (const e of entries) {
+    const p = path.join(dir, e.name);
+    if (ignore.some((i) => p.includes(i))) continue;
+
+    if (e.isDirectory()) {
+      scan(p, query, results, ignore);
+      continue;
+    }
+
+    // Only search typical text files in zmemory
+    if (!/\.(md|json|jsonl|txt)$/i.test(e.name)) continue;
+
+    let content;
+    try {
+      content = fs.readFileSync(p, "utf8");
+    } catch {
+      continue; // skip unreadable files
+    }
+
+    const lower = content.toLowerCase();
+    const q = query.toLowerCase();
+
+    if (!lower.includes(q)) continue;
+
+    // Extract short preview around match
+    const idx = lower.indexOf(q);
+    const start = Math.max(0, idx - 60);
+    const end = Math.min(content.length, idx + 60);
+    const snippet = content.slice(start, end).replace(/\n/g, " ");
+
+    results.push({ path: p, snippet });
+  }
+
+  return results;
+}
+
+export async function searchMemory(args) {
+  const scopeIndex = args.indexOf("--scope");
+  const scope = scopeIndex !== -1 ? args[scopeIndex + 1] : "all";
+
+  const query = args
+    .filter((a, i) => a !== "--scope" && args[i - 1] !== "--scope")
+    .join(" ");
+  if (!query) {
+    console.log("missing query");
+    return;
+  }
+
+  let base = ".zmemory";
+
+  if (scope === "runs") base = ".zmemory/runs";
+  if (scope === "decisions") base = ".zmemory/decisions.md";
+  if (scope === "failures") base = ".zmemory/failures.md";
+  if (!fs.existsSync(base)) {
+    console.log("zmemory not initialized");
+    return;
+  }
+
+  let results = [];
+  const ignore = loadIgnore();
+
+  if (fs.existsSync(base) && fs.statSync(base).isDirectory()) {
+    const index = loadIndex(base, ignore);
+    const q = query.toLowerCase();
+
+    for (const entry of index) {
+      if (!entry.content.includes(q)) continue;
+
+      const idx = entry.content.indexOf(q);
+      let snippet = "";
+
+      try {
+        const original = fs.readFileSync(entry.path, "utf8");
+        const start = Math.max(0, idx - 60);
+        const end = Math.min(original.length, idx + 60);
+        snippet = original.slice(start, end).replace(/\n/g, " ");
+      } catch {}
+
+      results.push({ path: entry.path, snippet });
+    }
+  } else if (fs.existsSync(base)) {
+    const content = fs.readFileSync(base, "utf8");
+    if (content.toLowerCase().includes(query.toLowerCase())) {
+      const idx = content.toLowerCase().indexOf(query.toLowerCase());
+      const snippet = content.slice(Math.max(0, idx - 60), idx + 60).replace(/\n/g, " ");
+      results = [{ path: base, snippet }];
+    }
+  }
+
+  if (!results.length) {
+    console.log("no results");
+    return;
+  }
+
+  results.forEach((r) => {
+    console.log(r.path);
+    if (r.snippet) console.log("  ", r.snippet.trim());
+    console.log();
+  });
+}

package/src/commands/setup.js

@@ -0,0 +1,148 @@
+import fs from "fs";
+import os from "os";
+import path from "path";
+import { multiselect, confirm, intro, outro } from "@clack/prompts";
+
+function ensureDir(p) {
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+}
+
+function writeJSONMerge(file, patch) {
+  let data = {};
+  try {
+    if (fs.existsSync(file)) data = JSON.parse(fs.readFileSync(file, "utf8"));
+  } catch {}
+  const merged = { ...data, ...patch };
+  ensureDir(file);
+  fs.writeFileSync(file, JSON.stringify(merged, null, 2));
+}
+
+function installClaude() {
+  const file = path.join(os.homedir(), ".claude", "settings.json");
+  let data = {};
+  try {
+    if (fs.existsSync(file)) data = JSON.parse(fs.readFileSync(file, "utf8"));
+  } catch {}
+
+  data.mcpServers = data.mcpServers || {};
+  data.mcpServers.zmemory = { command: "zmemory mcp" };
+
+  ensureDir(file);
+  fs.writeFileSync(file, JSON.stringify(data, null, 2));
+}
+
+function installCodex() {
+  const file = path.join(os.homedir(), ".codex", "config.toml");
+  let content = "";
+  try {
+    if (fs.existsSync(file)) content = fs.readFileSync(file, "utf8");
+  } catch {}
+
+  if (!content.includes("[mcp_servers.zmemory]")) {
+    content += `\n[mcp_servers.zmemory]\ncommand = "zmemory mcp"\n`;
+  }
+
+  ensureDir(file);
+  fs.writeFileSync(file, content);
+}
+
+function installCursor() {
+  const file = path.join(process.cwd(), ".cursor", "mcp.json");
+  let data = { mcpServers: {} };
+  try {
+    if (fs.existsSync(file)) data = JSON.parse(fs.readFileSync(file, "utf8"));
+  } catch {}
+
+  data.mcpServers = data.mcpServers || {};
+  data.mcpServers.zmemory = { command: "zmemory mcp" };
+
+  ensureDir(file);
+  fs.writeFileSync(file, JSON.stringify(data, null, 2));
+}
+
+function installOpenCode() {
+  const file = path.join(process.cwd(), "opencode.json");
+  let data = {};
+  try {
+    if (fs.existsSync(file)) data = JSON.parse(fs.readFileSync(file, "utf8"));
+  } catch {}
+
+  data.plugin = data.plugin || [];
+  if (!data.plugin.includes("zmemory")) data.plugin.push("zmemory");
+
+  ensureDir(file);
+  fs.writeFileSync(file, JSON.stringify(data, null, 2));
+}
+
+function installKilo() {
+  const file = path.join(process.cwd(), "kilo.json");
+  let data = {};
+  try {
+    if (fs.existsSync(file)) data = JSON.parse(fs.readFileSync(file, "utf8"));
+  } catch {}
+
+  data.plugin = data.plugin || [];
+  if (!data.plugin.includes("zmemory")) data.plugin.push("zmemory");
+
+  ensureDir(file);
+  fs.writeFileSync(file, JSON.stringify(data, null, 2));
+}
+
+function installAGY() {
+  const file = path.join(os.homedir(), ".copilot", "mcp-config.json");
+  writeJSONMerge(file, {
+    mcpServers: { zmemory: { command: "zmemory mcp" } }
+  });
+}
+
+function installKimi() {
+  const file = path.join(os.homedir(), ".kimi-code", "mcp.json");
+  writeJSONMerge(file, {
+    mcpServers: { zmemory: { command: "zmemory mcp" } }
+  });
+}
+
+export async function setupCommand() {
+  intro("ZMemory Setup");
+
+  const selected = await multiselect({
+    message: "Select platforms to configure",
+    options: [
+      { value: "opencode", label: "OpenCode" },
+      { value: "codex", label: "Codex CLI" },
+      { value: "claude", label: "Claude Code" },
+      { value: "agy", label: "Antigravity CLI (agy)" },
+      { value: "kilo", label: "Kilo Code" },
+      { value: "cursor", label: "Cursor" },
+      { value: "kimi", label: "Kimi Code" }
+    ]
+  });
+
+  if (!selected || !selected.length) {
+    outro("No platforms selected.");
+    return;
+  }
+
+  if (selected.includes("claude")) installClaude();
+  if (selected.includes("codex")) installCodex();
+  if (selected.includes("cursor")) installCursor();
+  if (selected.includes("opencode")) installOpenCode();
+  if (selected.includes("kilo")) installKilo();
+  if (selected.includes("agy")) installAGY();
+  if (selected.includes("kimi")) installKimi();
+
+  const initRepo = await confirm({ message: "Initialize .zmemory in this repo?" });
+  if (initRepo) {
+    const { initProject } = await import("./init.js");
+    await initProject();
+  }
+
+  // Run diagnostics automatically after setup
+  try {
+    const { doctor } = await import("./doctor.js");
+    console.log("\nRunning diagnostics...\n");
+    await doctor();
+  } catch {}
+
+  outro("ZMemory setup complete.");
+}

package/src/commands/skill.js

@@ -0,0 +1,103 @@
+import fs from "fs";
+
+function baseInstructions() {
+  return `ZMemory Integration Protocol
+
+Goal:
+Maintain shared operational memory between coding agents and sessions.
+
+Standard workflow:
+
+1. Read project status
+   zmemory status
+
+2. Fetch role context
+   zmemory context --role <role> --run <run_id>
+
+3. Execute task
+
+4. Record event
+   zmemory event --run <run_id> --role <role> --type <type> --summary "<summary>"
+
+5. Update state if needed
+   zmemory state update --run <run_id> --next-action "<next step>"
+
+6. Before stopping
+   zmemory handoff --run <run_id>
+`;
+}
+
+function codexSkill() {
+  return `# ZMemory Skill (Codex)
+
+Codex agents should treat ZMemory as the shared run-state layer.
+
+${baseInstructions()}
+
+Codex guidelines:
+
+- Always read context before modifying code
+- Record file changes with zmemory event
+- Avoid repeating failures recorded in events
+- Generate handoff before ending session
+`;
+}
+
+function claudeSkill() {
+  return `# ZMemory Skill (Claude Code)
+
+Claude Code should use ZMemory to coordinate tasks between sessions.
+
+${baseInstructions()}
+
+Claude Code guidelines:
+
+- Read executor context before implementing
+- Write reviewer verdicts using events
+- Escalate repeated failures to brain role
+`;
+}
+
+function opencodeSkill() {
+  return `# ZMemory Skill (OpenCode)
+
+OpenCode agents integrate with ZMemory for shared memory and handoffs.
+
+${baseInstructions()}
+
+OpenCode guidelines:
+
+- Use context packets to reduce prompt size
+- Log important actions as events
+- Generate handoff packets when switching models
+`;
+}
+
+export async function generateSkill(args) {
+  const i = args.indexOf("--target");
+  const target = i !== -1 ? args[i + 1] : "generic";
+
+  let content;
+
+  switch (target) {
+    case "codex":
+      content = codexSkill();
+      break;
+    case "claude-code":
+      content = claudeSkill();
+      break;
+    case "opencode":
+      content = opencodeSkill();
+      break;
+    default:
+      content = `# ZMemory Skill (Generic)
+
+${baseInstructions()}`;
+  }
+
+  const path = `.zmemory/skills/zmemory-${target}.md`;
+  fs.mkdirSync(`.zmemory/skills`, { recursive: true });
+  fs.writeFileSync(path, content);
+
+  console.log(`skill generated: ${path}`);
+}

package/src/commands/startRun.js

@@ -0,0 +1,82 @@
+import { ensureDir, writeFile, writeJSON, now } from "../lib/fs.js";
+import path from "path";
+import fs from "fs";
+
+const ACTIVE_ROOT = ".zmemory/runs/active";
+const ARCHIVE_ROOT = ".zmemory/runs/archived";
+
+function ensureRunRoots() {
+  ensureDir(ACTIVE_ROOT);
+  ensureDir(ARCHIVE_ROOT);
+}
+
+function todayPrefix() {
+  const d = new Date();
+  const y = d.getFullYear();
+  const m = d.getMonth() + 1;
+  const day = d.getDate();
+  return `run_${y}_${m}_${day}`;
+}
+
+function nextIndex(prefix) {
+  let max = 0;
+
+  for (const root of [ACTIVE_ROOT, ARCHIVE_ROOT]) {
+    if (!fs.existsSync(root)) continue;
+    for (const e of fs.readdirSync(root)) {
+      if (!e.startsWith(prefix + "_")) continue;
+      const parts = e.split("_");
+      const n = Number(parts[parts.length - 1]);
+      if (!Number.isNaN(n)) max = Math.max(max, n);
+    }
+  }
+
+  return max + 1;
+}
+
+function generateRunId() {
+  const prefix = todayPrefix();
+  const idx = nextIndex(prefix);
+  return `${prefix}_${String(idx).padStart(3, "0")}`;
+}
+
+export async function startRun(task) {
+  ensureRunRoots();
+
+  const id = generateRunId();
+  const base = path.join(ACTIVE_ROOT, id);
+
+  ensureDir(base);
+
+  writeFile(path.join(base, "task.md"), `# Task\n${task}\n`);
+  writeFile(path.join(base, "plan.md"), "# Plan\n");
+  writeFile(path.join(base, "events.jsonl"), "");
+
+  writeJSON(path.join(base, "state.json"), {
+    run_id: id,
+    project: path.basename(process.cwd()),
+    task,
+    status: "created",
+    current_step: 0,
+    completed: [],
+    blockers: [],
+    next_action: null,
+    attempts: { current_error_signature: null, repeated_count: 0 },
+    allowed_files: [],
+    forbidden_files: [],
+    updated_at: now()
+  });
+
+  // initial event
+  const evt = JSON.stringify({
+    ts: now(),
+    run_id: id,
+    role: "system",
+    type: "run_created",
+    summary: "Run created"
+  }) + "\n";
+
+  fs.appendFileSync(path.join(base, "events.jsonl"), evt);
+
+  console.log(id);
+}