zmemory 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ZMemory contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,167 @@
+# ZMemory
+
+**Shared project memory for AI agents.**
+
+ZMemory is a lightweight coordination layer that allows multiple AI coding agents
+(Codex, Claude Code, OpenCode, Cursor, Kilo, Kimi, etc.) to safely collaborate
+inside the same repository.
+
+It provides a shared operational memory where agents can:
+
+- see who is working on which files
+- coordinate edits
+- track activity and decisions
+- recover context across sessions
+
+ZMemory stores all coordination state inside the project in a `.zmemory/` folder.
+
+---
+
+# Install
+
+```
+npm install -g zmemory
+```
+
+Then run the interactive setup:
+
+```
+zmemory setup
+```
+
+This configures ZMemory for supported AI coding tools (Codex CLI, Claude Code,
+OpenCode, Cursor, Kilo Code, etc.) and optionally initializes the repository.
+
+---
+
+# Initialize a Repository
+
+Inside a project:
+
+```
+zmemory init
+```
+
+This creates:
+
+```
+.zmemory/
+  agents/
+  claims/
+  logs/
+  runs/
+  skills/
+```
+
+The `.zmemory` directory contains all coordination state for the project.
+
+---
+
+# Typical Agent Workflow
+
+When an agent starts working in a repository:
+
+```
+zmemory resume
+```
+
+This returns:
+
+- active agents
+- open file claims
+- recent activity
+- current run state
+
+Before editing files:
+
+```
+zmemory who <file>
+```
+
+When beginning work on a module:
+
+```
+zmemory claim src/auth/* --session <agent-session>
+```
+
+Record meaningful work:
+
+```
+zmemory event --summary "implemented auth middleware" --files src/auth/middleware.js
+```
+
+Release ownership when done:
+
+```
+zmemory release --session <agent-session>
+```
+
+---
+
+# Debugging Coordination
+
+To understand why a file is claimed:
+
+```
+zmemory explain <file>
+```
+
+Example output:
+
+```
+Active claims
+  src/auth/*
+    codex‑a1 implement auth middleware (expires in: 7m)
+
+Recent related activity
+  executor: implementing middleware
+  reviewer: reviewing middleware
+```
+
+---
+
+# Diagnostics
+
+Check system health:
+
+```
+zmemory doctor
+```
+
+---
+
+# Updating
+
+```
+zmemory update
+```
+
+or
+
+```
+zmemory upgrade
+```
+
+Both install the latest version and run diagnostics.
+
+---
+
+# Commands
+
+```
+zmemory setup
+zmemory init
+zmemory resume
+zmemory claim
+zmemory who
+zmemory event
+zmemory explain
+zmemory doctor
+zmemory update
+```
+
+---
+
+# License
+
+MIT

package/adapters/claude-code-adapter.sh

@@ -0,0 +1,11 @@
+#!/bin/sh
+# Adapter for Claude Code harness
+
+zmemory bootstrap >/dev/null 2>&1
+if ! pgrep -f "zmemory daemon" >/dev/null 2>&1; then
+  (zmemory daemon >/dev/null 2>&1 &) 
+fi
+zmemory resume
+
+# Claude can call context before work
+# zmemory context --role reviewer

package/adapters/codex-adapter.sh

@@ -0,0 +1,12 @@
+#!/bin/sh
+# Minimal adapter so Codex sessions automatically use ZMemory
+
+zmemory bootstrap >/dev/null 2>&1
+# ensure daemon + MCP runtime are running
+if ! pgrep -f "zmemory daemon" >/dev/null 2>&1; then
+  (zmemory daemon >/dev/null 2>&1 &) 
+fi
+zmemory resume
+
+# After Codex modifies files, user/automation can run:
+# zmemory event --role executor --type file_changed --summary "codex update"

package/adapters/cursor-adapter.sh

@@ -0,0 +1,14 @@
+#!/bin/sh
+# Cursor adapter for ZMemory
+
+# Ensure runtime exists
+zmemory bootstrap >/dev/null 2>&1
+
+# Start daemon if not running
+if ! pgrep -f "zmemory daemon" >/dev/null 2>&1; then
+  (zmemory daemon >/dev/null 2>&1 &)
+fi
+
+# Load latest context
+zmemory resume
+

package/adapters/opencode-adapter.sh

@@ -0,0 +1,9 @@
+#!/bin/sh
+# Adapter for OpenCode harness
+
+zmemory bootstrap >/dev/null 2>&1
+zmemory resume
+
+# Example usage after command execution
+# zmemory exec <command>
+

package/bin/zmemory.js

@@ -0,0 +1,426 @@
+#!/usr/bin/env node
+import { initProject } from "../src/commands/init.js";
+import { status } from "../src/commands/status.js";
+import { startRun } from "../src/commands/startRun.js";
+import { appendEvent } from "../src/commands/event.js";
+import { nextAction } from "../src/commands/next.js";
+import { decisionAdd } from "../src/commands/decision.js";
+import { failureAdd } from "../src/commands/failure.js";
+import { generateContext } from "../src/commands/context.js";
+import { generateHandoff } from "../src/commands/handoff.js";
+import { summary } from "../src/commands/summary.js";
+import { updateState } from "../src/commands/state.js";
+import { searchMemory } from "../src/commands/search.js";
+import { generateSkill } from "../src/commands/skill.js";
+import { archiveRun } from "../src/commands/archive.js";
+import { doctor } from "../src/commands/doctor.js";
+import { listRuns } from "../src/commands/runs.js";
+import { resumeRun } from "../src/commands/resume.js";
+import { routeRun } from "../src/commands/route.js";
+import { agentCommand } from "../src/commands/agent.js";
+import { claimCommand } from "../src/commands/claim.js";
+import { whoCommand } from "../src/commands/who.js";
+import { explainCommand } from "../src/commands/explain.js";
+import { setupCommand } from "../src/commands/setup.js";
+import { execCommand } from "../src/commands/exec.js";
+import { tasksCommand } from "../src/commands/tasks.js";
+import { locksCommand } from "../src/commands/locks.js";
+import { bootstrapCommand } from "../src/commands/bootstrap.js";
+import { streamEvents } from "../src/commands/stream.js";
+import { installGitHook } from "../src/commands/gitHook.js";
+import { startDashboard } from "../src/dashboard/server.js";
+import { busCommand } from "../src/commands/bus.js";
+import { workerCommand } from "../src/commands/worker.js";
+import { planCommand } from "../src/commands/plan.js";
+import { indexCommand } from "../src/commands/index.js";
+import { syncCommand } from "../src/commands/sync.js";
+import { configCommand } from "../src/commands/config.js";
+import { healthCommand } from "../src/commands/health.js";
+import { helpCommand } from "../src/commands/help.js";
+import { upgradeCommand } from "../src/commands/upgrade.js";
+import { ensureZMemory } from "../src/integrations/auto-bootstrap.js";
+import { installCommand } from "../src/commands/install.js";
+import { versionCommand } from "../src/commands/version.js";
+import { orchestratorCommand } from "../src/commands/orchestrator.js";
+import { workspacesCommand } from "../src/commands/workspaces.js";
+import { isValidRunId } from "../src/lib/run.js";
+
+const args = process.argv.slice(2);
+const cmd = args[0];
+
+// Global flags
+if (args.includes("-v") || args.includes("--version")) {
+  await versionCommand();
+  process.exit(0);
+}
+
+if (args.includes("-h") || args.includes("--help")) {
+  await helpCommand();
+  process.exit(0);
+}
+
+function getRunArg(args) {
+  const i = args.indexOf("--run");
+  if (i === -1) return { present: false, value: null };
+  const v = args[i + 1];
+  if (typeof v !== "string" || v.startsWith("--")) return { present: true, value: null };
+  return { present: true, value: v };
+}
+
+function shouldBootstrap(cmd, args) {
+  if (!cmd) return false;
+
+  const readOnly = new Set([
+    "help",
+    "version",
+    "doctor",
+    "status",
+    "health",
+    "runs",
+    "search",
+    "locks",
+    "next",
+    "summary",
+    "route",
+    "stream",
+    "resume",
+    "who",
+    "claims"
+  ]);
+
+  if (readOnly.has(cmd)) return false;
+  const stateful = new Set([
+    "bootstrap",
+    "mcp",
+    "daemon",
+    "init",
+    "start-run",
+    "event",
+    "decision",
+    "failure",
+    "context",
+    "handoff",
+    "skill",
+    "archive",
+    "exec",
+    "git-hook",
+    "dashboard",
+    "bus",
+    "worker",
+    "plan",
+    "install",
+    "orchestrator",
+    "workspaces"
+  ]);
+
+  if (cmd === "config") {
+    if (args[1] !== "set") return false;
+    const key = args[2];
+    const value = args[3];
+    return (
+      typeof key === "string" && key.trim().length > 0 &&
+      typeof value === "string" && value.trim().length > 0
+    );
+  }
+
+  if (cmd === "tasks") {
+    const sub = args[1];
+    if (sub === "add") {
+      const rest = args.slice(2);
+      let titleParts = [];
+      let deps = [];
+      let files = [];
+
+      for (let i = 0; i < rest.length; i++) {
+        const a = rest[i];
+        if (a === "--after" || a === "--files") {
+          const val = rest[i + 1];
+          if (typeof val !== "string" || !val.trim() || val.startsWith("--")) return false;
+          const parts = val.split(",").map(s => s.trim()).filter(Boolean);
+          if (parts.length === 0) return false;
+          if (a === "--after") deps = parts;
+          else files = parts;
+          i++;
+          continue;
+        }
+        titleParts.push(a);
+      }
+
+      const title = titleParts.join(" ").trim();
+      if (!title) return false;
+      return true;
+    }
+    if (sub === "claim" || sub === "done") {
+      const id = args[2];
+      return typeof id === "string" && id.trim().length > 0;
+    }
+    return false;
+  }
+
+  if (cmd === "agent") {
+    const sub = args[1];
+    if (sub === "register") {
+      const name = args[2];
+      return typeof name === "string" && name.trim().length > 0;
+    }
+    if (sub === "heartbeat") {
+      const name = args[2];
+      return typeof name === "string" && name.trim().length > 0;
+    }
+    return false;
+  }
+
+  if (cmd === "state") {
+    if (args[1] !== "update") return false;
+    const idx = args.indexOf("--run");
+    if (idx === -1) return false;
+    const runId = args[idx + 1];
+    if (!runId || typeof runId !== "string") return false;
+    if (!isValidRunId(runId)) return false;
+    return true;
+  }
+
+  if (cmd === "context" || cmd === "handoff" || cmd === "archive") {
+    const r = getRunArg(args);
+    if (!r.present) return false;
+    if (!r.value) return false;
+    return isValidRunId(r.value);
+  }
+
+  if (cmd === "event") {
+    const get = (flag) => {
+      const i = args.indexOf(flag);
+      if (i === -1) return { present: false, value: null };
+      const v = args[i + 1];
+      if (typeof v !== "string" || v.startsWith("--")) return { present: true, value: null };
+      return { present: true, value: v };
+    };
+
+    const role = get("--role");
+    const type = get("--type");
+    const summary = get("--summary");
+    if (!role.present || !type.present || !summary.present) return false;
+    if (!role.value || !role.value.trim()) return false;
+    if (!type.value || !type.value.trim()) return false;
+    if (!summary.value || !summary.value.trim()) return false;
+
+    const r = get("--run");
+    if (!r.present) return true; // valid global event
+    if (!r.value) return false;
+    return isValidRunId(r.value);
+  }
+
+  if (cmd === "skill") {
+    return args[1] === "generate";
+  }
+
+  if (cmd === "plan") {
+    const goal = args.slice(1).join(" ").trim();
+    return goal.length > 0;
+  }
+
+  if (cmd === "exec") {
+    const command = args.slice(1).join(" ").trim();
+    return command.length > 0;
+  }
+
+  if (cmd === "decision") {
+    const text = args.slice(1).join(" ").trim();
+    return text.length > 0;
+  }
+
+  if (cmd === "failure") {
+    const text = args.slice(1).join(" ").trim();
+    return text.length > 0;
+  }
+
+  if (cmd === "workspaces") {
+    const sub = args[1];
+    if (sub === "add") {
+      const p = args[2];
+      return typeof p === "string" && p.trim().length > 0;
+    }
+    return false;
+  }
+
+  if (cmd === "index") {
+    const sub = args[1];
+    return sub === "build";
+  }
+
+  if (cmd === "sync") {
+    const sub = args[1];
+    return sub === "push" || sub === "pull";
+  }
+
+  return stateful.has(cmd);
+}
+
+async function main() {
+  if (shouldBootstrap(cmd, args)) {
+    try {
+      ensureZMemory();
+    } catch (err) {
+      console.error("ZMemory bootstrap failed:", err?.message || err);
+      process.exitCode = 1;
+      return;
+    }
+  }
+  switch (cmd) {
+    case "init":
+      await initProject();
+      break;
+    case "status":
+      await status();
+      break;
+    case "start-run":
+      await startRun(args.slice(1).join(" "));
+      break;
+    case "event":
+      await appendEvent(args.slice(1));
+      break;
+    case "next":
+      await nextAction(args.slice(1));
+      break;
+    case "decision":
+      await decisionAdd(args.slice(1));
+      break;
+    case "failure":
+      await failureAdd(args.slice(1));
+      break;
+    case "context":
+      await generateContext(args.slice(1));
+      break;
+    case "state":
+      if (args[1] === "update") {
+        await updateState(args.slice(2));
+      }
+      break;
+    case "handoff":
+      await generateHandoff(args.slice(1));
+      break;
+    case "summary":
+      await summary(args.slice(1));
+      break;
+    case "search":
+      await searchMemory(args.slice(1));
+      break;
+    case "skill":
+      if (args[1] === "generate") {
+        await generateSkill(args.slice(2));
+      }
+      break;
+    case "archive":
+      await archiveRun(args.slice(1));
+      break;
+    case "runs":
+      await listRuns();
+      break;
+    case "resume":
+      await resumeRun();
+      break;
+    case "route":
+      await routeRun(args.slice(1));
+      break;
+    case "agent":
+      await agentCommand(args.slice(1));
+      break;
+    case "claim":
+      await claimCommand(args.slice(1));
+      break;
+    case "claims":
+      await claimCommand(["claims"]);
+      break;
+    case "release":
+      await claimCommand(["release", ...args.slice(1)]);
+      break;
+    case "who":
+      await whoCommand(args.slice(1));
+      break;
+    case "explain":
+      await explainCommand(args.slice(1));
+      break;
+    case "setup":
+      await setupCommand();
+      break;
+    case "exec":
+      await execCommand(args.slice(1));
+      break;
+    case "tasks":
+      await tasksCommand(args.slice(1));
+      break;
+    case "locks":
+      await locksCommand();
+      break;
+    case "bootstrap":
+      await bootstrapCommand();
+      break;
+    case "stream":
+      await streamEvents();
+      break;
+    case "git-hook":
+      await installGitHook();
+      break;
+    case "dashboard":
+      startDashboard();
+      break;
+    case "bus":
+      await busCommand();
+      break;
+    case "worker":
+      await workerCommand(args.slice(1));
+      break;
+    case "plan":
+      await planCommand(args.slice(1));
+      break;
+    case "index":
+      await indexCommand(args.slice(1));
+      break;
+    case "sync":
+      await syncCommand(args.slice(1));
+      break;
+    case "config":
+      await configCommand(args.slice(1));
+      break;
+    case "health":
+      await healthCommand();
+      break;
+    case "help":
+      await helpCommand();
+      break;
+    case "install":
+      await installCommand();
+      break;
+    case "version":
+      await versionCommand();
+      break;
+    case "update":
+    case "upgrade":
+      await upgradeCommand();
+      break;
+    case "orchestrator":
+      await orchestratorCommand();
+      break;
+    case "daemon":
+      {
+        const mod = await import("../src/commands/daemon.js");
+        await mod.daemonCommand();
+      }
+      break;
+    case "workspaces":
+      await workspacesCommand(args.slice(1));
+      break;
+    case "doctor":
+      await doctor();
+      break;
+    case "mcp":
+      console.error("ZMemory MCP server started (stdio mode)");
+      await import("../src/mcp/server.js");
+      break;
+    default:
+      console.log("ZMemory CLI");
+      console.log("Commands: init status start-run context event handoff decision failure next summary");
+  }
+}
+
+main();

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "zmemory",
+  "version": "0.1.0",
+  "description": "Local-first shared memory layer for AI coding agents",
+  "bin": {
+    "zmemory": "bin/zmemory.js"
+  },
+  "keywords": [
+    "ai",
+    "agents",
+    "coordination",
+    "developer-tools",
+    "workflow"
+  ],
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "adapters/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "start": "node bin/zmemory.js",
+    "mcp": "node bin/zmemory.js mcp",
+    "check:syntax": "node scripts/check-syntax.js",
+    "test:cli": "node test/cli-smoke.js",
+    "test:scripts": "node test/script-cwd-smoke.js",
+    "test:mcp": "node test/mcp-contract-smoke.js",
+    "test:package": "node test/package-smoke.js",
+    "test": "npm run check:syntax && npm run test:cli && npm run test:scripts && npm run test:mcp && npm run test:package",
+    "prepare": "node scripts/prepare.js"
+  },
+  "dependencies": {
+    "picomatch": "^4.0.0",
+    "@clack/prompts": "^0.7.0"
+  }
+}