zmemory 0.1.0

package/src/commands/event.js

@@ -0,0 +1,149 @@
+import { appendFile, now, readJSON, writeJSON } from "../lib/fs.js";
+import fs from "fs";
+import { getRunFile, isValidRunId, ensureRunExists } from "../lib/run.js";
+import { acquireLock, releaseLock } from "../lib/lock.js";
+
+const INDEX_PATH = ".zmemory/index.json";
+const EVENTS_FILE = ".zmemory/logs/events.jsonl";
+const ARCHIVE_DIR = ".zmemory/logs/archive";
+const MAX_ACTIVE_EVENTS = 5000;
+const ARCHIVE_BATCH = 2000;
+
+function updateIndex(filePath, contentLine) {
+  if (!fs.existsSync(INDEX_PATH)) return; // index built lazily by search
+  try {
+    const raw = JSON.parse(fs.readFileSync(INDEX_PATH, "utf8"));
+    if (!Array.isArray(raw)) return;
+
+    const lower = contentLine.toLowerCase();
+    let entry = raw.find((e) => e.path === filePath);
+
+    if (!entry) {
+      entry = { path: filePath, content: lower };
+      raw.push(entry);
+    } else {
+      entry.content += lower;
+    }
+
+    fs.writeFileSync(INDEX_PATH, JSON.stringify(raw));
+  } catch {}
+}
+
+function rotateEventsIfNeeded() {
+  try {
+    if (!fs.existsSync(EVENTS_FILE)) return;
+    const lines = fs.readFileSync(EVENTS_FILE, "utf8").split("\n").filter(Boolean);
+    if (lines.length <= MAX_ACTIVE_EVENTS) return;
+
+    fs.mkdirSync(ARCHIVE_DIR, { recursive: true });
+
+    const archive = lines.slice(0, ARCHIVE_BATCH);
+    const keep = lines.slice(ARCHIVE_BATCH);
+
+    const existing = fs.readdirSync(ARCHIVE_DIR).filter(f => f.startsWith("events-") && f.endsWith(".jsonl"));
+    const next = String(existing.length + 1).padStart(5, "0");
+    const archivePath = `${ARCHIVE_DIR}/events-${next}.jsonl`;
+
+    fs.writeFileSync(archivePath, archive.join("\n") + "\n");
+    fs.writeFileSync(EVENTS_FILE, keep.join("\n") + (keep.length ? "\n" : ""));
+  } catch {}
+}
+
+export async function appendEvent(args) {
+  const get = (flag) => {
+    const i = args.indexOf(flag);
+    if (i === -1) return null;
+    const v = args[i + 1];
+    if (typeof v !== "string" || v.startsWith("--")) return null;
+    return v;
+  };
+
+  const run = get("--run");
+  const runFlagPresent = args.includes("--run");
+  const role = get("--role");
+  const type = get("--type");
+  const summary = get("--summary");
+  const files = get("--files");
+  const evidence = get("--evidence");
+  const errorSig = get("--error-signature");
+
+  const usage = "usage: zmemory event --role <role> --type <type> --summary <text> [--run <id>]";
+
+  if (!role || !role.trim() || !type || !type.trim() || !summary || !summary.trim()) {
+    console.log(usage);
+    return;
+  }
+
+  const evt = {
+    ts: now(),
+    run_id: run,
+    role,
+    type,
+    summary,
+    files: files ? files.split(",") : undefined,
+    evidence: evidence || undefined,
+    error_signature: errorSig || undefined
+  };
+
+  if (runFlagPresent) {
+    if (!run) {
+      console.log(usage);
+      return;
+    }
+    if (!isValidRunId(run)) {
+      console.log(usage);
+      return;
+    }
+    try {
+      ensureRunExists(run);
+    } catch (e) {
+      console.log(e.message === "run not found" ? "run not found" : "invalid run id");
+      return;
+    }
+  }
+
+  const line = JSON.stringify(evt) + "\n";
+
+  if (run) {
+    try {
+      acquireLock(run);
+    } catch {
+      console.log("run locked by another agent");
+      return;
+    }
+    try {
+      appendFile(EVENTS_FILE, line);
+      const p = getRunFile(run, "events.jsonl");
+      appendFile(p, line);
+      updateIndex(p, line);
+      updateIndex(EVENTS_FILE, line);
+      rotateEventsIfNeeded();
+
+      if (errorSig) {
+        const statePath = getRunFile(run, "state.json");
+        if (fs.existsSync(statePath)) {
+          const state = readJSON(statePath);
+          const prev = state.attempts?.current_error_signature;
+          if (!state.attempts) state.attempts = { current_error_signature: null, repeated_count: 0 };
+
+          if (prev === errorSig) {
+            state.attempts.repeated_count = (state.attempts.repeated_count || 0) + 1;
+          } else {
+            state.attempts.current_error_signature = errorSig;
+            state.attempts.repeated_count = 1;
+          }
+
+          writeJSON(statePath, state);
+        }
+      }
+    } finally {
+      releaseLock(run);
+    }
+  } else {
+    appendFile(EVENTS_FILE, line);
+    updateIndex(EVENTS_FILE, line);
+    rotateEventsIfNeeded();
+  }
+
+  console.log("event appended");
+}

package/src/commands/exec.js

@@ -0,0 +1,25 @@
+import { spawnSync } from "child_process";
+import { appendFile, now } from "../lib/fs.js";
+
+export async function execCommand(args) {
+  const cmd = args.join(" ");
+  if (!cmd || !cmd.trim()) {
+    console.log("empty command");
+    return;
+  }
+
+  const result = spawnSync(cmd, { shell: true, encoding: "utf8" });
+
+  const evt = {
+    ts: now(),
+    role: "executor",
+    type: "command_run",
+    summary: cmd,
+    success: result.status === 0
+  };
+
+  appendFile(".zmemory/logs/events.jsonl", JSON.stringify(evt) + "\n");
+
+  console.log(result.stdout);
+  if (result.stderr) console.error(result.stderr);
+}

package/src/commands/explain.js

@@ -0,0 +1,68 @@
+import fs from "fs";
+import { who } from "../lib/coordination/who.js";
+
+export async function explainCommand(args) {
+  const file = args[0];
+
+  if (!file) {
+    console.log("usage: zmemory explain <file>");
+    return;
+  }
+
+  console.log(`# ZMemory Explain\n`);
+  console.log(`File: ${file}\n`);
+
+  const matches = who(file);
+
+  console.log("Active claims");
+  if (!matches.length) {
+    console.log("  none");
+  } else {
+    for (const m of matches) {
+      console.log(`  pattern: ${m.pattern}`);
+      for (const a of m.agents || []) {
+        const mins = typeof a.expires_in_minutes === "number" ? `${a.expires_in_minutes}m` : "?";
+        console.log(`    ${a.session} ${a.task || ""} (expires in: ${mins})`);
+      }
+    }
+  }
+
+  console.log();
+
+  const eventsFile = ".zmemory/logs/events.jsonl";
+  console.log("Recent related activity");
+
+  if (!fs.existsSync(eventsFile)) {
+    console.log("  none");
+    return;
+  }
+
+  const lines = fs
+    .readFileSync(eventsFile, "utf8")
+    .split("\n")
+    .filter(Boolean)
+    .slice(-50);
+
+  const related = [];
+
+  for (const l of lines) {
+    try {
+      const e = JSON.parse(l);
+      const files = e.files || [];
+      if (files.find(f => file.includes(f) || f.includes(file))) {
+        related.push(e);
+      }
+    } catch {}
+  }
+
+  if (!related.length) {
+    console.log("  none");
+    return;
+  }
+
+  for (const e of related.slice(-5)) {
+    const role = e.role || "agent";
+    const ts = e.ts || "";
+    console.log(`  ${ts} ${role}: ${e.summary || ""}`);
+  }
+}

package/src/commands/failure.js

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

package/src/commands/gitHook.js

@@ -0,0 +1,22 @@
+import fs from "fs";
+import path from "path";
+
+export async function installGitHook() {
+  const hookDir = ".git/hooks";
+
+  if (!fs.existsSync(hookDir)) {
+    console.log("not a git repo");
+    return;
+  }
+
+  const hook = `#!/bin/sh
+node bin/zmemory.js event --role executor --type git_commit --summary "git commit"
+`;
+
+  const file = path.join(hookDir, "post-commit");
+  fs.writeFileSync(file, hook);
+  fs.chmodSync(file, 0o755);
+
+  console.log("git hook installed");
+}
+

package/src/commands/handoff.js

@@ -0,0 +1,101 @@
+import fs from "fs";
+import { getRunFile, isValidRunId, ensureRunExists } from "../lib/run.js";
+
+export async function generateHandoff(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;
+  }
+
+  let task;
+  try {
+    task = fs.readFileSync(getRunFile(run, "task.md"), "utf8");
+  } catch {
+    console.log("run not found");
+    return;
+  }
+
+  // normalize task text (strip leading heading if present)
+  const taskText = task.split("\n").slice(1).join(" ").trim() || task.trim();
+
+  let events = [];
+  const eventsPath = getRunFile(run, "events.jsonl");
+  if (fs.existsSync(eventsPath)) {
+    events = fs
+      .readFileSync(eventsPath, "utf8")
+      .split("\n")
+      .filter(Boolean)
+      .slice(-5);
+  }
+
+  const filesTouched = new Set();
+  events.forEach((l) => {
+    try {
+      const e = JSON.parse(l);
+      (e.files || []).forEach((f) => filesTouched.add(f));
+    } catch {}
+  });
+
+  const completed = Array.isArray(state.completed) ? state.completed : [];
+  const blockers = Array.isArray(state.blockers) ? state.blockers : [];
+  const attempts = state.attempts || {};
+
+  const handoff = `# ZMemory Handoff
+
+## Task
+${taskText}
+
+## Status
+${state.status}
+
+## Attempts
+Error signature: ${attempts.current_error_signature || "none"}
+Repeated count: ${attempts.repeated_count || 0}
+
+## Completed Steps
+${completed.join("\n")}
+
+## Blockers
+${blockers.join("\n")}
+
+## Files Touched
+${Array.from(filesTouched).join("\n")}
+
+## Recent Events
+${events.join("\n")}
+
+## Next Action
+${state.next_action}
+
+## Stop Conditions
+- Escalate to reviewer if repeated failures >=2
+- Escalate to brain if repeated failures >=3
+`;
+
+  fs.writeFileSync(getRunFile(run, "handoff.md"), handoff);
+
+  console.log(handoff);
+}

package/src/commands/health.js

@@ -0,0 +1,18 @@
+import fs from "fs";
+
+export async function healthCommand() {
+  const report = {
+    zmemory_exists: fs.existsSync(".zmemory"),
+    runs_dir: fs.existsSync(".zmemory/runs"),
+    events_log: fs.existsSync(".zmemory/logs/events.jsonl"),
+    tasks: fs.existsSync(".zmemory/tasks.json"),
+    agents: fs.existsSync(".zmemory/agents.json")
+  };
+
+  console.log("ZMemory health check\n");
+
+  Object.entries(report).forEach(([k, v]) => {
+    console.log(k.padEnd(20), v ? "OK" : "missing");
+  });
+}
+

package/src/commands/help.js

@@ -0,0 +1,33 @@
+export async function helpCommand() {
+  console.log("ZMemory");
+  console.log("Shared project memory for AI agents\n");
+
+  console.log("Core:");
+  console.log("  zmemory setup               Interactive platform setup");
+  console.log("  zmemory init                Initialize .zmemory in this repo");
+  console.log("  zmemory resume              Bootstrap agent context\n");
+
+  console.log("Coordination:");
+  console.log("  zmemory claim <pattern>     Claim files or modules");
+  console.log("  zmemory who <file>          See who is working on a file");
+  console.log("  zmemory release --session   Release claims\n");
+
+  console.log("Activity:");
+  console.log("  zmemory event               Append activity event");
+  console.log("  zmemory explain <file>      Explain activity around a file\n");
+
+  console.log("Agents:");
+  console.log("  zmemory agent register");
+  console.log("  zmemory agent list\n");
+
+  console.log("Diagnostics:");
+  console.log("  zmemory doctor\n");
+
+  console.log("Updates:");
+  console.log("  zmemory update");
+  console.log("  zmemory upgrade\n");
+
+  console.log("Flags:");
+  console.log("  zmemory -v | --version");
+  console.log("  zmemory -h | --help\n");
+}

package/src/commands/index.js

@@ -0,0 +1,21 @@
+import { buildFileIndex, readFileIndex } from "../lib/fileIndex.js";
+
+export async function indexCommand(args) {
+  const sub = args[0];
+
+  if (sub === "build") {
+    const files = buildFileIndex();
+    console.log("indexed", files.length, "files");
+    return;
+  }
+
+  if (sub === "show") {
+    const files = readFileIndex();
+    files.slice(0, 50).forEach((f) => console.log(f));
+    console.log("total:", files.length);
+    return;
+  }
+
+  console.log("usage: zmemory index build|show");
+}
+

package/src/commands/init.js

@@ -0,0 +1,38 @@
+import { ensureDir, writeFile, writeJSON } from "../lib/fs.js";
+import path from "path";
+
+export async function initProject() {
+  const base = ".zmemory";
+
+  ensureDir(base);
+  ensureDir(path.join(base, "runs/active"));
+  ensureDir(path.join(base, "runs/archived"));
+  ensureDir(path.join(base, "logs"));
+  ensureDir(path.join(base, "packets"));
+  ensureDir(path.join(base, "skills"));
+
+  writeJSON(path.join(base, "config.json"), {
+    project_name: "project",
+    memory_mode: "local",
+    default_context_budget_tokens: 8000,
+    default_roles: ["brain", "executor", "reviewer", "tester"],
+    event_log_format: "jsonl",
+    allow_mcp: true
+  });
+
+  writeFile(path.join(base, "project.md"), "# Project Memory\n");
+  writeFile(path.join(base, "decisions.md"), "# Decisions\n");
+  writeFile(path.join(base, "failures.md"), "# Failures\n");
+  writeFile(path.join(base, "patterns.md"), "# Patterns\n");
+  writeFile(path.join(base, "commands.md"), "# Useful Commands\n");
+
+  writeFile(path.join(base, "logs/events.jsonl"), "");
+
+  // create ignore template
+  writeFile(
+    ".zmemoryignore",
+    "node_modules\ndist\n.git\n"
+  );
+
+  console.log("ZMemory initialized");
+}

package/src/commands/install.js

@@ -0,0 +1,28 @@
+import fs from "fs";
+
+// Simple installer that prepares a repo to use ZMemory
+export async function installCommand() {
+  if (!fs.existsSync(".zmemory")) {
+    fs.mkdirSync(".zmemory", { recursive: true });
+  }
+
+  // ensure bootstrap so skills + logs exist
+  const bootstrap = await import("./bootstrap.js");
+  await bootstrap.bootstrapCommand?.();
+
+  const readme = `# ZMemory Integration
+
+This repository uses ZMemory for AI agent coordination.
+
+Common commands:
+
+zmemory bootstrap
+zmemory plan "goal"
+zmemory worker codex
+zmemory dashboard
+`;
+
+  fs.writeFileSync(".zmemory/README.md", readme);
+
+  console.log("ZMemory installed in repository");
+}

package/src/commands/locks.js

@@ -0,0 +1,9 @@
+import { listLocks } from "../lib/fileLocks.js";
+
+export async function locksCommand() {
+  const locks = listLocks();
+  Object.entries(locks).forEach(([file, worker]) => {
+    console.log(file, "locked by", worker);
+  });
+}
+

package/src/commands/next.js

@@ -0,0 +1,59 @@
+import fs from "fs";
+import path from "path";
+import { getRunFile, getRunBase } from "../lib/run.js";
+
+export async function nextAction(args) {
+  const i = args.indexOf("--run");
+  const run = i !== -1 ? args[i + 1] : null;
+
+  if (!run) {
+    console.log("missing --run");
+    return;
+  }
+
+  let statePath;
+  try {
+    statePath = getRunFile(run, "state.json");
+  } catch {
+    console.log("invalid run id");
+    return;
+  }
+
+  if (!fs.existsSync(statePath)) {
+    console.log("run not found");
+    return;
+  }
+
+  const state = JSON.parse(fs.readFileSync(statePath, "utf8"));
+
+  console.log("Run:", run);
+  try {
+    const base = getRunBase(run);
+    const taskPath = path.join(base, "task.md");
+    if (fs.existsSync(taskPath)) {
+      const txt = fs.readFileSync(taskPath, "utf8");
+      const task = txt.split("\n").slice(1).join(" ").trim();
+      if (task) console.log("Task:", task);
+    }
+  } catch {}
+  console.log("Status:", state.status);
+  console.log("Current Step:", state.current_step);
+
+  console.log("\nNext Action:");
+  console.log(state.next_action || "none");
+
+  const blockers = state.blockers || [];
+  if (blockers.length) {
+    console.log("\nBlockers:");
+    blockers.forEach((b) => console.log("-", b));
+  }
+
+  const attempts = state.attempts || {};
+  const repeated = attempts.repeated_count || 0;
+
+  if (repeated >= 3) {
+    console.log("\nSuggestion: escalate to brain (repeated failures >=3)");
+  } else if (repeated >= 2) {
+    console.log("\nSuggestion: request reviewer (repeated failures >=2)");
+  }
+}

package/src/commands/orchestrator.js

@@ -0,0 +1,6 @@
+import { startOrchestrator } from "../daemon/orchestrator.js";
+
+export async function orchestratorCommand() {
+  startOrchestrator();
+}
+

package/src/commands/plan.js

@@ -0,0 +1,30 @@
+import { addTask } from "../lib/tasks.js";
+import { scanModules } from "../lib/repoScan.js";
+
+// Very simple deterministic planner.
+// Splits a large goal into multiple tasks heuristically.
+
+export async function planCommand(args) {
+  const goal = args.join(" ");
+
+  if (!goal) {
+    console.log("usage: zmemory plan <goal>");
+    return;
+  }
+
+  console.log("Planning goal:", goal);
+
+  const modules = scanModules();
+
+  if (!modules.length) {
+    const t = addTask(`Implement: ${goal}`);
+    console.log("created task:", t.id, "-", t.title);
+    return;
+  }
+
+  modules.forEach((m) => {
+    const title = `${goal} in ${m}`;
+    const task = addTask(title, [m]);
+    console.log("created task:", task.id, "-", title);
+  });
+}