zmemory 0.1.0

package/src/integrations/auto-bootstrap.js

@@ -0,0 +1,90 @@
+import fs from "fs";
+import path from "path";
+import crypto from "crypto";
+import { registerAgent } from "../lib/coordination/agents.js";
+
+// Automatically ensure ZMemory is initialized when a repo is opened
+export function ensureZMemory() {
+  const dir = ".zmemory";
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(path.join(dir, "project.md"), "# Project Memory\n");
+    fs.writeFileSync(path.join(dir, "decisions.md"), "# Decisions\n");
+    fs.writeFileSync(path.join(dir, "failures.md"), "# Failures\n");
+    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.writeFileSync(path.join(dir, "logs/events.jsonl"), "");
+  }
+
+  const skillsDir = path.join(dir, "skills");
+  fs.mkdirSync(skillsDir, { recursive: true });
+  const skillFile = path.join(skillsDir, "coordination.md");
+  if (!fs.existsSync(skillFile)) {
+    const skill = `# ZMemory Coordination
+
+This repository uses **ZMemory** for multi‑agent coordination.
+
+Workflow:
+
+1. Inspect project state
+   zmemory resume
+
+2. Before editing a file
+   zmemory who <file>
+
+3. When starting work on a module
+   zmemory claim <pattern> --session <id>
+
+4. Log meaningful work
+   zmemory event --summary "what you did" --files <file>
+
+5. When work is complete
+   zmemory release --session <id>
+
+ZMemory provides shared awareness across agents so avoid editing files
+that are actively claimed unless coordination is intentional.
+`;
+    fs.writeFileSync(skillFile, skill);
+  }
+
+  // Ensure MCP manifest exists so harnesses can discover tools automatically
+  const mcpDir = path.join(dir, "mcp");
+  fs.mkdirSync(mcpDir, { recursive: true });
+  const manifest = path.join(mcpDir, "manifest.json");
+  if (!fs.existsSync(manifest)) {
+    const m = {
+      name: "zmemory",
+      protocol: "mcp",
+      transport: "stdio",
+      command: "zmemory mcp",
+      description: "Shared memory + coordination layer for AI coding agents"
+    };
+    fs.writeFileSync(manifest, JSON.stringify(m, null, 2));
+  }
+
+  // --- Optional auto agent bootstrap ---
+  // Enabled when environment variable is provided by the agent runtime
+  const agentName = process.env.ZMEMORY_AGENT;
+  if (agentName) {
+    try {
+      let session = process.env.ZMEMORY_SESSION;
+
+      if (!session) {
+        const id = crypto.randomBytes(3).toString("hex");
+        session = `${agentName}-${id}`;
+      }
+
+      registerAgent({
+        agent: agentName,
+        session,
+        task: process.env.ZMEMORY_TASK || ""
+      });
+
+      // expose session id for child tools if needed
+      if (!process.env.ZMEMORY_SESSION) {
+        process.env.ZMEMORY_SESSION = session;
+      }
+    } catch {}
+  }
+}

package/src/integrations/harness-adapter.md

@@ -0,0 +1,39 @@
+# ZMemory Harness Adapter
+
+This file explains how coding tools can automatically integrate with ZMemory.
+
+Suggested adapter loop for harnesses:
+
+1. On start
+
+```
+zmemory bootstrap
+zmemory resume
+```
+
+2. Before executing a task
+
+```
+zmemory context --role executor
+```
+
+3. After writing files
+
+```
+zmemory event --role executor --type file_changed
+```
+
+4. After running commands
+
+```
+zmemory exec <command>
+```
+
+5. On completion
+
+```
+zmemory handoff
+```
+
+Adapters can wrap these calls automatically so users do not need to run them manually.
+

package/src/lib/agents.js

@@ -0,0 +1,36 @@
+import { readJSON, writeJSON, withFileLock } from "./fs.js";
+
+const AGENTS_FILE = ".zmemory/agents.json";
+const LOCK = ".zmemory/agents.json.lock";
+
+function readAgents() {
+  return readJSON(AGENTS_FILE) || {};
+}
+
+function writeAgents(data) {
+  writeJSON(AGENTS_FILE, data);
+}
+
+export function registerAgent(name, role) {
+  return withFileLock(LOCK, () => {
+    const agents = readAgents();
+    agents[name] = {
+      role,
+      last_heartbeat: new Date().toISOString()
+    };
+    writeAgents(agents);
+  });
+}
+
+export function heartbeat(name) {
+  return withFileLock(LOCK, () => {
+    const agents = readAgents();
+    if (!agents[name]) return;
+    agents[name].last_heartbeat = new Date().toISOString();
+    writeAgents(agents);
+  });
+}
+
+export function listAgents() {
+  return readAgents();
+}

package/src/lib/config.js

@@ -0,0 +1,15 @@
+import { readJSON, writeJSON } from "./fs.js";
+
+const CONFIG = ".zmemory/config.json";
+
+export function readConfig() {
+  try {
+    return readJSON(CONFIG, {}) || {};
+  } catch {
+    return {};
+  }
+}
+
+export function writeConfig(cfg) {
+  writeJSON(CONFIG, cfg);
+}

package/src/lib/coordination/agents.js

@@ -0,0 +1,49 @@
+import fs from "fs";
+import path from "path";
+
+const BASE = ".zmemory/agents";
+
+function ensureDir() {
+  fs.mkdirSync(BASE, { recursive: true });
+}
+
+function agentPath(session) {
+  return path.join(BASE, `${session}.json`);
+}
+
+export function registerAgent({ agent, session, task = "", files = [], cwd = process.cwd() }) {
+  ensureDir();
+
+  const data = {
+    agent,
+    session,
+    task,
+    files,
+    cwd,
+    started_at: new Date().toISOString()
+  };
+
+  fs.writeFileSync(agentPath(session), JSON.stringify(data, null, 2));
+  return data;
+}
+
+export function listAgents() {
+  if (!fs.existsSync(BASE)) return [];
+
+  const files = fs.readdirSync(BASE);
+  const agents = [];
+
+  for (const f of files) {
+    try {
+      const raw = fs.readFileSync(path.join(BASE, f), "utf8");
+      agents.push(JSON.parse(raw));
+    } catch {}
+  }
+
+  return agents;
+}
+
+export function removeAgent(session) {
+  const p = agentPath(session);
+  if (fs.existsSync(p)) fs.unlinkSync(p);
+}

package/src/lib/coordination/claims.js

@@ -0,0 +1,127 @@
+import fs from "fs";
+import path from "path";
+import crypto from "crypto";
+
+const BASE = ".zmemory/claims";
+const DEFAULT_TTL = 600; // seconds
+
+function ensureDir() {
+  fs.mkdirSync(BASE, { recursive: true });
+}
+
+function hash(pattern) {
+  return crypto.createHash("sha1").update(pattern).digest("hex").slice(0, 8);
+}
+
+function claimPath(pattern) {
+  return path.join(BASE, `${hash(pattern)}.json`);
+}
+
+function isExpired(agent) {
+  if (!agent?.ts) return false;
+  const ttl = agent.ttl || DEFAULT_TTL;
+  const t = new Date(agent.ts).getTime() + ttl * 1000;
+  return Date.now() > t;
+}
+
+function pruneExpired(data) {
+  data.agents = (data.agents || []).filter(a => !isExpired(a));
+  return data;
+}
+
+export function claimPattern(pattern, { session, task = "" }) {
+  ensureDir();
+
+  const p = claimPath(pattern);
+  let data = { pattern, agents: [] };
+
+  if (fs.existsSync(p)) {
+    try {
+      data = JSON.parse(fs.readFileSync(p, "utf8"));
+    } catch {}
+  }
+
+  data = pruneExpired(data);
+
+  const existing = data.agents.find((a) => a.session === session);
+  if (!existing) {
+    data.agents.push({
+      session,
+      task,
+      ts: new Date().toISOString(),
+      ttl: DEFAULT_TTL
+    });
+  } else {
+    // refresh lease
+    existing.ts = new Date().toISOString();
+  }
+
+  fs.writeFileSync(p, JSON.stringify(data, null, 2));
+  return data;
+}
+
+export function listClaims() {
+  if (!fs.existsSync(BASE)) return [];
+
+  const files = fs.readdirSync(BASE);
+  const claims = [];
+
+  for (const f of files) {
+    try {
+      const raw = fs.readFileSync(path.join(BASE, f), "utf8");
+      const data = pruneExpired(JSON.parse(raw));
+      if ((data.agents || []).length) claims.push(data);
+    } catch {}
+  }
+
+  return claims;
+}
+
+export function releaseClaims(session) {
+  if (!fs.existsSync(BASE)) return;
+
+  const files = fs.readdirSync(BASE);
+
+  for (const f of files) {
+    const p = path.join(BASE, f);
+    try {
+      const data = JSON.parse(fs.readFileSync(p, "utf8"));
+      data.agents = (data.agents || []).filter((a) => a.session !== session && !isExpired(a));
+
+      if (!data.agents.length) {
+        fs.unlinkSync(p);
+      } else {
+        fs.writeFileSync(p, JSON.stringify(data, null, 2));
+      }
+    } catch {}
+  }
+}
+
+export function refreshClaims(session) {
+  if (!fs.existsSync(BASE)) return;
+  const files = fs.readdirSync(BASE);
+
+  for (const f of files) {
+    const p = path.join(BASE, f);
+    try {
+      const data = JSON.parse(fs.readFileSync(p, "utf8"));
+      let changed = false;
+
+      for (const a of data.agents || []) {
+        if (a.session === session) {
+          a.ts = new Date().toISOString();
+          if (!a.ttl) a.ttl = DEFAULT_TTL;
+          changed = true;
+        }
+      }
+
+      const pruned = pruneExpired(data);
+
+      if (!pruned.agents.length) {
+        fs.unlinkSync(p);
+      } else if (changed) {
+        fs.writeFileSync(p, JSON.stringify(pruned, null, 2));
+      }
+    } catch {}
+  }
+}

package/src/lib/coordination/who.js

@@ -0,0 +1,49 @@
+import { listClaims } from "./claims.js";
+// Minimal glob matcher to avoid external deps. Supports "*" wildcard only.
+function globMatch(pattern, file) {
+  if (!pattern.includes("*")) return pattern === file;
+  const parts = pattern.split("*");
+  if (parts.length === 2) {
+    const [start, end] = parts;
+    return file.startsWith(start) && file.endsWith(end || "");
+  }
+  // fallback: simple contains sequence check
+  let idx = 0;
+  for (const p of parts) {
+    if (!p) continue;
+    const i = file.indexOf(p, idx);
+    if (i === -1) return false;
+    idx = i + p.length;
+  }
+  return true;
+}
+
+function withExpiry(agent) {
+  if (!agent?.ts) return agent;
+  const ttl = agent.ttl || 600;
+  const expireAt = new Date(agent.ts).getTime() + ttl * 1000;
+  const remaining = Math.max(0, Math.floor((expireAt - Date.now()) / 1000));
+  return {
+    ...agent,
+    expires_in_seconds: remaining,
+    expires_in_minutes: Math.floor(remaining / 60)
+  };
+}
+
+export function who(filePath) {
+  const claims = listClaims();
+  const matches = [];
+
+  for (const c of claims) {
+    try {
+      if (globMatch(c.pattern, filePath)) {
+        matches.push({
+          pattern: c.pattern,
+          agents: (c.agents || []).map(withExpiry)
+        });
+      }
+    } catch {}
+  }
+
+  return matches;
+}

package/src/lib/fileIndex.js

@@ -0,0 +1,36 @@
+import fs from "fs";
+import path from "path";
+import { writeJSON, readJSON } from "./fs.js";
+
+const INDEX_FILE = ".zmemory/fileindex.json";
+
+function walk(dir, ignore = ["node_modules", ".git", ".zmemory"]) {
+  const results = [];
+  if (!fs.existsSync(dir)) return results;
+
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+
+  for (const e of entries) {
+    if (ignore.includes(e.name)) continue;
+
+    const full = path.join(dir, e.name);
+
+    if (e.isDirectory()) {
+      results.push(...walk(full, ignore));
+    } else {
+      results.push(full);
+    }
+  }
+
+  return results;
+}
+
+export function buildFileIndex(root = ".") {
+  const files = walk(root);
+  writeJSON(INDEX_FILE, files);
+  return files;
+}
+
+export function readFileIndex() {
+  return readJSON(INDEX_FILE) || [];
+}

package/src/lib/fileLocks.js

@@ -0,0 +1,44 @@
+import { readJSON, writeJSON, withFileLock } from "./fs.js";
+
+const LOCK_FILE = ".zmemory/filelocks.json";
+const MUTEX = ".zmemory/filelocks.json.lock";
+
+function readLocks() {
+  return readJSON(LOCK_FILE) || {};
+}
+
+function writeLocks(data) {
+  writeJSON(LOCK_FILE, data);
+}
+
+export function lockFiles(worker, files) {
+  return withFileLock(MUTEX, () => {
+    const locks = readLocks();
+
+    for (const f of files) {
+      if (locks[f] && locks[f] !== worker) {
+        throw new Error(`file locked: ${f}`);
+      }
+    }
+
+    files.forEach((f) => {
+      locks[f] = worker;
+    });
+
+    writeLocks(locks);
+  });
+}
+
+export function releaseFiles(worker) {
+  return withFileLock(MUTEX, () => {
+    const locks = readLocks();
+    Object.keys(locks).forEach((f) => {
+      if (locks[f] === worker) delete locks[f];
+    });
+    writeLocks(locks);
+  });
+}
+
+export function listLocks() {
+  return readLocks();
+}

package/src/lib/fs.js

@@ -0,0 +1,140 @@
+import fs from "fs";
+import path from "path";
+
+export const ZMEMORY_DIR = ".zmemory";
+
+export function ensureDir(p) {
+  if (!fs.existsSync(p)) fs.mkdirSync(p, { recursive: true });
+}
+
+export function writeFile(p, data) {
+  atomicWriteFile(p, data);
+}
+
+export function appendFile(p, data) {
+  ensureDir(path.dirname(p));
+  fs.appendFileSync(p, data);
+}
+
+export function readJSON(p, fallback = null) {
+  if (!fs.existsSync(p)) return fallback;
+  const raw = fs.readFileSync(p, "utf8");
+  return JSON.parse(raw);
+}
+
+export function writeJSON(p, obj) {
+  writeFile(p, JSON.stringify(obj, null, 2));
+}
+
+export function now() {
+  return new Date().toISOString();
+}
+
+export function atomicWriteFile(filePath, data) {
+  ensureDir(path.dirname(filePath));
+  const tmp = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+  try {
+    fs.writeFileSync(tmp, data);
+    fs.renameSync(tmp, filePath);
+  } catch (e) {
+    try { if (fs.existsSync(tmp)) fs.unlinkSync(tmp); } catch {}
+    throw e;
+  }
+}
+
+function processAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    if (err && err.code === "EPERM") return true;
+    return false;
+  }
+}
+
+export function withFileLock(lockPath, fn, options = {}) {
+  const ttl = options.ttl || 30 * 60 * 1000;
+  ensureDir(path.dirname(lockPath));
+  let owned = false;
+
+  function acquire() {
+    try {
+      const fd = fs.openSync(lockPath, "wx");
+      try {
+        const meta = { pid: process.pid, created_at: Date.now() };
+        fs.writeFileSync(fd, JSON.stringify(meta));
+      } catch (e) {
+        try { fs.closeSync(fd); } catch {}
+        try { if (fs.existsSync(lockPath)) fs.unlinkSync(lockPath); } catch {}
+        throw e;
+      }
+      fs.closeSync(fd);
+      owned = true;
+      return true;
+    } catch (err) {
+      if (err && err.code !== "EEXIST") throw err;
+
+      if (!fs.existsSync(lockPath)) return false;
+      try {
+        const stat = fs.statSync(lockPath);
+        const raw = fs.readFileSync(lockPath, "utf8").trim();
+
+        let stale = false;
+
+        if (/^\d+$/.test(raw)) {
+          const pid = Number(raw);
+          if (Number.isSafeInteger(pid) && pid > 0) {
+            if (!processAlive(pid)) stale = true;
+          } else {
+            const age = Date.now() - stat.mtimeMs;
+            if (age > ttl) stale = true;
+          }
+        } else {
+          let parsed = false;
+          try {
+            const meta = JSON.parse(raw);
+            if (
+              meta &&
+              typeof meta === "object" &&
+              !Array.isArray(meta) &&
+              typeof meta.pid === "number" &&
+              meta.pid > 0 &&
+              typeof meta.created_at === "number"
+            ) {
+              parsed = true;
+              const age = Date.now() - meta.created_at;
+              if (!processAlive(meta.pid) || age > ttl) stale = true;
+            }
+          } catch {}
+
+          if (!parsed) {
+            const age = Date.now() - stat.mtimeMs;
+            if (age > ttl) stale = true;
+          }
+        }
+
+        if (stale) {
+          fs.unlinkSync(lockPath);
+          return acquire();
+        }
+      } catch {}
+      return false;
+    }
+  }
+
+  if (!acquire()) throw new Error("file lock busy");
+
+  try {
+    return fn();
+  } finally {
+    if (owned) {
+      try {
+        if (fs.existsSync(lockPath)) {
+          const raw = fs.readFileSync(lockPath, "utf8");
+          const meta = JSON.parse(raw);
+          if (meta.pid === process.pid) fs.unlinkSync(lockPath);
+        }
+      } catch {}
+    }
+  }
+}