zmemory 0.1.0 → 0.1.1

package/README.md

@@ -19,6 +19,10 @@ ZMemory stores all coordination state inside the project in a `.zmemory/` folder
 
 # Install
 
+Requirements:
+
+- Node.js >=20
+
 ```
 npm install -g zmemory
 ```

package/bin/zmemory-mcp.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+await import("../src/mcp/server.js");

package/bin/zmemory.js

@@ -49,12 +49,12 @@ const args = process.argv.slice(2);
 const cmd = args[0];
 
 // Global flags
-if (args.includes("-v") || args.includes("--version")) {
+if (args.length === 1 && (args[0] === "-v" || args[0] === "--version")) {
   await versionCommand();
   process.exit(0);
 }
 
-if (args.includes("-h") || args.includes("--help")) {
+if (args.length === 1 && (args[0] === "-h" || args[0] === "--help")) {
   await helpCommand();
   process.exit(0);
 }
@@ -414,12 +414,10 @@ async function main() {
       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");
+      await helpCommand();
   }
 }
 

package/package.json

@@ -1,9 +1,10 @@
 {
   "name": "zmemory",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Local-first shared memory layer for AI coding agents",
   "bin": {
-    "zmemory": "bin/zmemory.js"
+    "zmemory": "bin/zmemory.js",
+    "zmemory-mcp": "bin/zmemory-mcp.js"
   },
   "keywords": [
     "ai",
@@ -36,7 +37,6 @@
     "prepare": "node scripts/prepare.js"
   },
   "dependencies": {
-    "picomatch": "^4.0.0",
     "@clack/prompts": "^0.7.0"
   }
 }

package/src/commands/help.js

@@ -1,7 +1,12 @@
 export async function helpCommand() {
-  console.log("ZMemory");
+  console.log("ZMemory CLI");
   console.log("Shared project memory for AI agents\n");
 
+  console.log("Common commands:");
+  console.log("  zmemory setup               Interactive platform setup");
+  console.log("  zmemory init                Initialize .zmemory in this repo");
+  console.log("  zmemory bootstrap           Ensure .zmemory structure exists\n");
+
   console.log("Core:");
   console.log("  zmemory setup               Interactive platform setup");
   console.log("  zmemory init                Initialize .zmemory in this repo");

package/src/commands/init.js

@@ -10,6 +10,8 @@ export async function initProject() {
   ensureDir(path.join(base, "logs"));
   ensureDir(path.join(base, "packets"));
   ensureDir(path.join(base, "skills"));
+  ensureDir(path.join(base, "agents"));
+  ensureDir(path.join(base, "claims"));
 
   writeJSON(path.join(base, "config.json"), {
     project_name: "project",

package/src/commands/setup.js

@@ -1,7 +1,8 @@
 import fs from "fs";
 import os from "os";
 import path from "path";
-import { multiselect, confirm, intro, outro } from "@clack/prompts";
+
+const MCP_COMMAND = "zmemory-mcp";
 
 function ensureDir(p) {
   fs.mkdirSync(path.dirname(p), { recursive: true });
@@ -12,11 +13,31 @@ function writeJSONMerge(file, patch) {
   try {
     if (fs.existsSync(file)) data = JSON.parse(fs.readFileSync(file, "utf8"));
   } catch {}
-  const merged = { ...data, ...patch };
+
+  const merged = deepMerge(data, patch);
   ensureDir(file);
   fs.writeFileSync(file, JSON.stringify(merged, null, 2));
 }
 
+function deepMerge(base, patch) {
+  const out = { ...base };
+  for (const [key, value] of Object.entries(patch)) {
+    if (value && typeof value === "object" && !Array.isArray(value)) {
+      out[key] = deepMerge(out[key] && typeof out[key] === "object" && !Array.isArray(out[key]) ? out[key] : {}, value);
+    } else {
+      out[key] = value;
+    }
+  }
+  return out;
+}
+
+function removePluginValue(data, value) {
+  if (Array.isArray(data.plugin)) {
+    data.plugin = data.plugin.filter((p) => p !== value);
+    if (!data.plugin.length) delete data.plugin;
+  }
+}
+
 function installClaude() {
   const file = path.join(os.homedir(), ".claude", "settings.json");
   let data = {};
@@ -25,7 +46,7 @@ function installClaude() {
   } catch {}
 
   data.mcpServers = data.mcpServers || {};
-  data.mcpServers.zmemory = { command: "zmemory mcp" };
+  data.mcpServers.zmemory = { command: MCP_COMMAND };
 
   ensureDir(file);
   fs.writeFileSync(file, JSON.stringify(data, null, 2));
@@ -38,8 +59,11 @@ function installCodex() {
     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`;
+  const block = `[mcp_servers.zmemory]\ncommand = "${MCP_COMMAND}"\n`;
+  if (content.includes("[mcp_servers.zmemory]")) {
+    content = content.replace(/\n?\[mcp_servers\.zmemory\][\s\S]*?(?=\n\[|$)/, `\n${block}`);
+  } else {
+    content += `\n${block}`;
   }
 
   ensureDir(file);
@@ -54,7 +78,7 @@ function installCursor() {
   } catch {}
 
   data.mcpServers = data.mcpServers || {};
-  data.mcpServers.zmemory = { command: "zmemory mcp" };
+  data.mcpServers.zmemory = { command: MCP_COMMAND };
 
   ensureDir(file);
   fs.writeFileSync(file, JSON.stringify(data, null, 2));
@@ -67,8 +91,12 @@ function installOpenCode() {
     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");
+  removePluginValue(data, "zmemory");
+  data.mcp = data.mcp || {};
+  data.mcp.zmemory = {
+    type: "local",
+    command: [MCP_COMMAND]
+  };
 
   ensureDir(file);
   fs.writeFileSync(file, JSON.stringify(data, null, 2));
@@ -81,28 +109,36 @@ function installKilo() {
     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");
+  data.$schema = "https://app.kilo.ai/config.json";
+  removePluginValue(data, "zmemory");
+  if (data.mcpServers?.zmemory) delete data.mcpServers.zmemory;
+  if (data.mcpServers && !Object.keys(data.mcpServers).length) delete data.mcpServers;
+  data.mcp = data.mcp || {};
+  data.mcp.zmemory = {
+    type: "local",
+    command: [MCP_COMMAND]
+  };
 
   ensureDir(file);
   fs.writeFileSync(file, JSON.stringify(data, null, 2));
 }
 
 function installAGY() {
-  const file = path.join(os.homedir(), ".copilot", "mcp-config.json");
+  const file = path.join(os.homedir(), ".gemini", "config", "mcp_config.json");
   writeJSONMerge(file, {
-    mcpServers: { zmemory: { command: "zmemory mcp" } }
+    mcpServers: { zmemory: { command: MCP_COMMAND } }
   });
 }
 
 function installKimi() {
   const file = path.join(os.homedir(), ".kimi-code", "mcp.json");
   writeJSONMerge(file, {
-    mcpServers: { zmemory: { command: "zmemory mcp" } }
+    mcpServers: { zmemory: { command: MCP_COMMAND, args: [] } }
   });
 }
 
 export async function setupCommand() {
+  const { multiselect, confirm, intro, outro, isCancel } = await import("@clack/prompts");
   intro("ZMemory Setup");
 
   const selected = await multiselect({
@@ -118,7 +154,7 @@ export async function setupCommand() {
     ]
   });
 
-  if (!selected || !selected.length) {
+  if (isCancel(selected) || !selected || !selected.length) {
     outro("No platforms selected.");
     return;
   }
@@ -132,7 +168,7 @@ export async function setupCommand() {
   if (selected.includes("kimi")) installKimi();
 
   const initRepo = await confirm({ message: "Initialize .zmemory in this repo?" });
-  if (initRepo) {
+  if (!isCancel(initRepo) && initRepo) {
     const { initProject } = await import("./init.js");
     await initProject();
   }

package/src/integrations/auto-bootstrap.js

@@ -14,9 +14,14 @@ export function ensureZMemory() {
     fs.mkdirSync(path.join(dir, "runs/active"), { recursive: true });
     fs.mkdirSync(path.join(dir, "runs/archived"), { recursive: true });
     fs.mkdirSync(path.join(dir, "logs"), { recursive: true });
+    fs.mkdirSync(path.join(dir, "agents"), { recursive: true });
+    fs.mkdirSync(path.join(dir, "claims"), { recursive: true });
     fs.writeFileSync(path.join(dir, "logs/events.jsonl"), "");
   }
 
+  fs.mkdirSync(path.join(dir, "agents"), { recursive: true });
+  fs.mkdirSync(path.join(dir, "claims"), { recursive: true });
+
   const skillsDir = path.join(dir, "skills");
   fs.mkdirSync(skillsDir, { recursive: true });
   const skillFile = path.join(skillsDir, "coordination.md");

package/src/mcp/server.js

@@ -9,12 +9,14 @@ import { planCommand } from "../commands/plan.js";
 import { routeRun } from "../commands/route.js";
 import { readJSON, writeJSON } from "../lib/fs.js";
 import { acquireLock, releaseLock } from "../lib/lock.js";
+import { claimPattern, listClaims, releaseClaims } from "../lib/coordination/claims.js";
+import { who as whoLookup } from "../lib/coordination/who.js";
+
 const EVENTS_FILE = `.zmemory/logs/events.jsonl`;
 const ARCHIVE_DIR = `.zmemory/logs/archive`;
 const MAX_ACTIVE_EVENTS = 5000;
 const ARCHIVE_BATCH = 2000;
-import { claimPattern, listClaims, releaseClaims } from "../lib/coordination/claims.js";
-import { who as whoLookup } from "../lib/coordination/who.js";
+const SERVER_VERSION = JSON.parse(fs.readFileSync(new URL("../../package.json", import.meta.url), "utf8")).version;
 
 // ---- Tool Contracts (source of truth) ----
 const toolContracts = {
@@ -324,6 +326,139 @@ try {
 let buffer = "";
 let lineQueue = Promise.resolve();
 
+function writeProtocolJSON(value) {
+  process.stdout.write(JSON.stringify(value) + "\n");
+}
+
+function typeToJSONSchema(type) {
+  if (type === "number") return { type: "number" };
+  if (type === "boolean") return { type: "boolean" };
+  if (type === "array:string") return { type: "array", items: { type: "string", minLength: 1 } };
+  if (type === "run_id" || type === "nonempty:string") return { type: "string", minLength: 1 };
+  return { type: "string" };
+}
+
+function contractToMCPTool(name, contract) {
+  const required = Object.keys(contract.input.required || {});
+  const properties = {};
+  for (const [key, type] of Object.entries(contract.input.required || {})) {
+    properties[key] = typeToJSONSchema(type);
+  }
+  for (const [key, type] of Object.entries(contract.input.optional || {})) {
+    properties[key] = typeToJSONSchema(type);
+  }
+
+  return {
+    name,
+    description: contract.description,
+    inputSchema: {
+      type: "object",
+      properties,
+      required,
+      additionalProperties: false
+    }
+  };
+}
+
+async function invokeTool(toolName, input) {
+  const fn = tools[toolName];
+  if (!fn) throw new Error("unknown tool");
+
+  let capturedOut = "";
+  let capturedErr = "";
+  const origLog = console.log;
+  const origErr = console.error;
+
+  console.log = (...a) => {
+    capturedOut += a.map(v => String(v)).join(" ") + "\n";
+  };
+  console.error = (...a) => {
+    capturedErr += a.map(v => String(v)).join(" ") + "\n";
+  };
+
+  try {
+    validateInput(toolName, input);
+    const raw = await fn(input);
+    return {
+      result: raw === undefined ? null : raw,
+      stdout: capturedOut,
+      stderr: capturedErr
+    };
+  } finally {
+    console.log = origLog;
+    console.error = origErr;
+  }
+}
+
+function jsonRpcResult(id, result) {
+  writeProtocolJSON({ jsonrpc: "2.0", id, result });
+}
+
+function jsonRpcError(id, code, message) {
+  writeProtocolJSON({ jsonrpc: "2.0", id, error: { code, message } });
+}
+
+function mcpToolContent(payload) {
+  const hasOnlyResult = !payload.stdout && !payload.stderr;
+  const value = hasOnlyResult ? payload.result : payload;
+  const text = typeof value === "string" ? value : JSON.stringify(value, null, 2);
+  return { content: [{ type: "text", text }] };
+}
+
+async function handleJsonRpcMessage(msg) {
+  const id = msg.id ?? null;
+  const method = msg.method;
+
+  if (method === "notifications/initialized" || method === "initialized") return;
+
+  if (method === "initialize") {
+    jsonRpcResult(id, {
+      protocolVersion: msg.params?.protocolVersion || "2024-11-05",
+      capabilities: { tools: {} },
+      serverInfo: { name: "zmemory", version: SERVER_VERSION }
+    });
+    return;
+  }
+
+  if (method === "ping") {
+    jsonRpcResult(id, {});
+    return;
+  }
+
+  if (method === "tools/list") {
+    jsonRpcResult(id, {
+      tools: Object.entries(toolContracts).map(([name, contract]) => contractToMCPTool(name, contract))
+    });
+    return;
+  }
+
+  if (method === "tools/call") {
+    const name = msg.params?.name;
+    const input = msg.params?.arguments || {};
+    if (typeof name !== "string" || !name.trim()) {
+      jsonRpcError(id, -32602, "invalid tool name");
+      return;
+    }
+    if (input === null || typeof input !== "object" || Array.isArray(input)) {
+      jsonRpcError(id, -32602, "invalid tool arguments");
+      return;
+    }
+
+    try {
+      const payload = await invokeTool(name.trim(), input);
+      jsonRpcResult(id, mcpToolContent(payload));
+    } catch (e) {
+      jsonRpcResult(id, {
+        isError: true,
+        content: [{ type: "text", text: e?.message || String(e) }]
+      });
+    }
+    return;
+  }
+
+  jsonRpcError(id, -32601, "method not found");
+}
+
 
 
 async function handleLine(line) {
@@ -333,7 +468,7 @@ async function handleLine(line) {
   try {
     msg = JSON.parse(line);
   } catch {
-    process.stdout.write(JSON.stringify({ error: "malformed json" }) + "\n");
+    writeProtocolJSON({ error: "malformed json" });
     return;
   }
 
@@ -341,64 +476,42 @@ async function handleLine(line) {
   if (!msg || typeof msg !== "object" || Array.isArray(msg)) {
     const out = { error: "invalid message" };
     if (id !== undefined) out.id = id;
-    process.stdout.write(JSON.stringify(out) + "\n");
+    writeProtocolJSON(out);
+    return;
+  }
+
+  if (typeof msg.method === "string") {
+    await handleJsonRpcMessage(msg);
     return;
   }
 
   if (typeof msg.tool !== "string" || !msg.tool.trim()) {
     const out = { error: "invalid message: tool" };
     if (id !== undefined) out.id = id;
-    process.stdout.write(JSON.stringify(out) + "\n");
+    writeProtocolJSON(out);
     return;
   }
 
   if (msg.input !== undefined && (msg.input === null || typeof msg.input !== "object" || Array.isArray(msg.input))) {
     const out = { error: "invalid message: input" };
     if (id !== undefined) out.id = id;
-    process.stdout.write(JSON.stringify(out) + "\n");
+    writeProtocolJSON(out);
     return;
   }
   const toolName = msg.tool.trim();
-  const fn = tools[toolName];
-  if (!fn) {
-    const out = { error: "unknown tool" };
-    if (id !== undefined) out.id = id;
-    process.stdout.write(JSON.stringify(out) + "\n");
-    return;
-  }
-
-  let capturedOut = "";
-  let capturedErr = "";
-
-  const origLog = console.log;
-  const origErr = console.error;
-
-  console.log = (...a) => {
-    capturedOut += a.map(v => String(v)).join(" ") + "\n";
-  };
-  console.error = (...a) => {
-    capturedErr += a.map(v => String(v)).join(" ") + "\n";
-  };
 
   try {
     const input = msg.input || {};
-    validateInput(toolName, input);
-    const raw = await fn(input);
-    const result = raw === undefined ? null : raw;
-    const out = { result };
+    const payload = await invokeTool(toolName, input);
+    const out = { result: payload.result };
     if (id !== undefined) out.id = id;
-    if (capturedOut) out.stdout = capturedOut;
-    if (capturedErr) out.stderr = capturedErr;
-    process.stdout.write(JSON.stringify(out) + "\n");
+    if (payload.stdout) out.stdout = payload.stdout;
+    if (payload.stderr) out.stderr = payload.stderr;
+    writeProtocolJSON(out);
   } catch (e) {
     const out = { error: e?.message || String(e) };
     if (id !== undefined) out.id = id;
-    if (capturedOut) out.stdout = capturedOut;
-    if (capturedErr) out.stderr = capturedErr;
-    process.stdout.write(JSON.stringify(out) + "\n");
-  } finally {
-    console.log = origLog;
-    console.error = origErr;
+    writeProtocolJSON(out);
   }
 }