zmemory 0.1.0

package/src/commands/state.js

@@ -0,0 +1,68 @@
+import fs from "fs";
+import { getRunFile } from "../lib/run.js";
+import { now, readJSON, writeJSON } from "../lib/fs.js";
+import { acquireLock, releaseLock } from "../lib/lock.js";
+
+export async function updateState(args) {
+  const get = (flag) => {
+    const i = args.indexOf(flag);
+    return i !== -1 ? args[i + 1] : null;
+  };
+
+  const run = get("--run");
+  if (!run) {
+    console.log("missing --run");
+    return;
+  }
+
+  let path;
+  try {
+    path = getRunFile(run, "state.json");
+  } catch {
+    console.log("invalid run id");
+    return;
+  }
+  if (!fs.existsSync(path)) {
+    console.log("run not found");
+    return;
+  }
+
+  try {
+    acquireLock(run);
+  } catch (e) {
+    console.log("run locked by another agent");
+    return;
+  }
+
+  let state;
+  try {
+    state = readJSON(path);
+
+  const status = get("--status");
+  const step = get("--current-step");
+  const next = get("--next-action");
+  const completed = get("--completed");
+  const blockers = get("--blockers");
+
+  if (status) state.status = status;
+  if (step) state.current_step = Number(step);
+  if (next) state.next_action = next;
+
+  if (completed) {
+    const items = completed.split(",").map((s) => s.trim()).filter(Boolean);
+    state.completed = [...(state.completed || []), ...items];
+  }
+
+  if (blockers) {
+    state.blockers = blockers.split(",").map((s) => s.trim());
+  }
+
+  state.updated_at = now();
+
+    writeJSON(path, state);
+  } finally {
+    releaseLock(run);
+  }
+
+  console.log("state updated");
+}

package/src/commands/status.js

@@ -0,0 +1,51 @@
+import fs from "fs";
+import { getRunFile, isValidRunId } from "../lib/run.js";
+
+function readLastEntry(file) {
+  if (!fs.existsSync(file)) return null;
+  const lines = fs.readFileSync(file, "utf8").split("\n").filter(Boolean);
+  return lines.length ? lines[lines.length - 1] : null;
+}
+
+export async function status() {
+  if (!fs.existsSync(".zmemory")) {
+    console.log("ZMemory not initialized");
+    return;
+  }
+
+  const cfgPath = ".zmemory/config.json";
+  let project = "unknown";
+  if (fs.existsSync(cfgPath)) {
+    try {
+      const cfg = JSON.parse(fs.readFileSync(cfgPath, "utf8"));
+      project = cfg.project_name || project;
+    } catch {}
+  }
+
+  const runsPath = ".zmemory/runs/active";
+  const runs = fs.existsSync(runsPath) ? fs.readdirSync(runsPath) : [];
+
+  console.log("Project:", project);
+  console.log("\nActive Runs:");
+
+  runs.forEach((r) => {
+    if (!isValidRunId(r)) return;
+    let statePath;
+    try { statePath = getRunFile(r, "state.json"); } catch { return; }
+    if (fs.existsSync(statePath)) {
+      const state = JSON.parse(fs.readFileSync(statePath, "utf8"));
+      console.log(`- ${r} | status=${state.status} | next=${state.next_action || "none"}`);
+    } else {
+      console.log("-", r);
+    }
+  });
+
+  const lastDecision = readLastEntry(".zmemory/decisions.md");
+  const lastFailure = readLastEntry(".zmemory/failures.md");
+
+  console.log("\nLatest Decision:");
+  console.log(lastDecision || "none");
+
+  console.log("\nLatest Failure:");
+  console.log(lastFailure || "none");
+}

package/src/commands/stream.js

@@ -0,0 +1,27 @@
+import fs from "fs";
+
+export async function streamEvents() {
+  const file = ".zmemory/logs/events.jsonl";
+
+  if (!fs.existsSync(file)) {
+    console.log("no event log");
+    return;
+  }
+
+  console.log("Streaming events (Ctrl+C to stop)...\n");
+
+  let size = fs.statSync(file).size;
+
+  setInterval(() => {
+    const stats = fs.statSync(file);
+    if (stats.size > size) {
+      const stream = fs.createReadStream(file, {
+        start: size,
+        end: stats.size
+      });
+      stream.pipe(process.stdout);
+      size = stats.size;
+    }
+  }, 1000);
+}
+

package/src/commands/summary.js

@@ -0,0 +1,65 @@
+import fs from "fs";
+import { getRunBase } from "../lib/run.js";
+
+export async function summary(args = []) {
+  const i = args.indexOf("--run");
+  const run = i !== -1 ? args[i + 1] : null;
+
+  if (!run) {
+    console.log("missing --run");
+    return;
+  }
+
+  let base;
+  try { base = getRunBase(run); } catch { console.log("invalid run id"); return; }
+  const statePath = `${base}/state.json`;
+  const taskPath = `${base}/task.md`;
+  const eventsPath = `${base}/events.jsonl`;
+
+  if (!fs.existsSync(statePath)) {
+    console.log("run not found");
+    return;
+  }
+
+  const state = JSON.parse(fs.readFileSync(statePath, "utf8"));
+
+  let task = "";
+  if (fs.existsSync(taskPath)) {
+    task = fs.readFileSync(taskPath, "utf8").trim();
+  }
+
+  console.log("Run:", run);
+  console.log("Status:", state.status);
+  console.log("Current Step:", state.current_step);
+
+  console.log("\nTask:");
+  console.log(task);
+
+  const completed = state.completed || [];
+  if (completed.length) {
+    console.log("\nCompleted Steps:");
+    completed.forEach((c) => console.log("-", c));
+  }
+
+  const blockers = state.blockers || [];
+  if (blockers.length) {
+    console.log("\nBlockers:");
+    blockers.forEach((b) => console.log("-", b));
+  }
+
+  if (fs.existsSync(eventsPath)) {
+    const events = fs
+      .readFileSync(eventsPath, "utf8")
+      .split("\n")
+      .filter(Boolean)
+      .slice(-10);
+
+    if (events.length) {
+      console.log("\nRecent Events:");
+      events.forEach((e) => console.log(e));
+    }
+  }
+
+  console.log("\nNext Action:");
+  console.log(state.next_action || "none");
+}

package/src/commands/sync.js

@@ -0,0 +1,20 @@
+import { syncPush, syncPull } from "../lib/teamSync.js";
+
+export async function syncCommand(args) {
+  const sub = args[0];
+
+  if (sub === "push") {
+    syncPush();
+    console.log("zmemory pushed to remote directory");
+    return;
+  }
+
+  if (sub === "pull") {
+    syncPull();
+    console.log("zmemory pulled from remote directory");
+    return;
+  }
+
+  console.log("usage: zmemory sync push|pull");
+}
+

package/src/commands/tasks.js

@@ -0,0 +1,89 @@
+import { addTask, addTaskWithDeps, listTasks, claimTask, completeTask } from "../lib/tasks.js";
+
+export async function tasksCommand(args) {
+  const sub = args[0];
+
+  if (sub === "add") {
+    const usage = () => console.log("usage: zmemory tasks add <title> [--after id1,id2] [--files f1,f2]");
+
+    let deps = [];
+    let files = [];
+    const titleParts = [];
+
+    for (let i = 1; i < args.length; i++) {
+      const a = args[i];
+
+      if (a === "--after" || a === "--files") {
+        const val = args[i + 1];
+        if (typeof val !== "string" || !val.trim() || val.startsWith("--")) {
+          usage();
+          return;
+        }
+
+        const parts = val.split(",").map(s => s.trim()).filter(Boolean);
+        if (parts.length === 0) {
+          usage();
+          return;
+        }
+
+        if (a === "--after") deps = parts;
+        else files = parts;
+
+        i++;
+        continue;
+      }
+
+      titleParts.push(a);
+    }
+
+    const title = titleParts.join(" ").trim();
+    if (!title) {
+      usage();
+      return;
+    }
+
+    const task = deps.length
+      ? addTaskWithDeps(title, deps)
+      : addTask(title, files);
+    console.log("task created:", task.id);
+    return;
+  }
+
+  if (sub === "list") {
+    const tasks = listTasks();
+    tasks.forEach((t) => {
+      console.log(t.id, t.status, t.worker || "-");
+      if (t.depends_on && t.depends_on.length)
+        console.log("  depends_on:", t.depends_on.join(","));
+      console.log(" ", t.title);
+    });
+    return;
+  }
+
+  if (sub === "claim") {
+    const id = args[1];
+    const worker = args[2] || "agent";
+    if (!id || !String(id).trim()) {
+      console.log("usage: zmemory tasks claim <id> [worker]");
+      return;
+    }
+    const t = claimTask(id, worker);
+    if (!t) console.log("cannot claim task");
+    else console.log("task claimed:", id);
+    return;
+  }
+
+  if (sub === "done") {
+    const id = args[1];
+    if (!id || !String(id).trim()) {
+      console.log("usage: zmemory tasks done <id>");
+      return;
+    }
+    const t = completeTask(id);
+    if (!t) console.log("task not found");
+    else console.log("task completed:", id);
+    return;
+  }
+
+  console.log("usage: zmemory tasks add|list|claim|done");
+}

package/src/commands/timeline.js

@@ -0,0 +1,75 @@
+import fs from "fs";
+import { getRunFile, isValidRunId, ensureRunExists } from "../lib/run.js";
+
+export async function runTimeline(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;
+  }
+
+  const eventsPath = getRunFile(run, "events.jsonl");
+
+  if (!fs.existsSync(eventsPath)) {
+    console.log("no events");
+    return;
+  }
+
+  const lines = fs
+    .readFileSync(eventsPath, "utf8")
+    .split("\n")
+    .filter(Boolean);
+
+  if (!lines.length) {
+    console.log("no events");
+    return;
+  }
+
+  const events = [];
+
+  for (const l of lines) {
+    try {
+      const e = JSON.parse(l);
+      events.push(e);
+    } catch {}
+  }
+
+  events.sort((a, b) => (a.ts || "").localeCompare(b.ts || ""));
+
+  console.log(`# Run Timeline`);
+  console.log(`Run: ${run}\n`);
+
+  for (const e of events) {
+    const ts = e.ts || "unknown";
+    const role = e.role || "unknown";
+    const type = e.type || "event";
+    const summary = e.summary || "";
+
+    console.log(`${ts}  [${role}] (${type})`);
+    if (summary) console.log(`  ${summary}`);
+
+    if (Array.isArray(e.files) && e.files.length) {
+      console.log(`  files: ${e.files.join(", ")}`);
+    }
+
+    if (e.error_signature) {
+      console.log(`  error: ${e.error_signature}`);
+    }
+
+    console.log();
+  }
+}

package/src/commands/upgrade.js

@@ -0,0 +1,19 @@
+import { execSync } from "child_process";
+
+export async function upgradeCommand() {
+  console.log("Checking for ZMemory updates...\n");
+
+  try {
+    execSync("npm install -g zmemory@latest", { stdio: "inherit" });
+  } catch {
+    console.log("\nUpgrade failed. Try manually:");
+    console.log("npm install -g zmemory@latest");
+    return;
+  }
+
+  try {
+    const { doctor } = await import("./doctor.js");
+    console.log("\nRunning diagnostics...\n");
+    await doctor();
+  } catch {}
+}

package/src/commands/version.js

@@ -0,0 +1,12 @@
+import fs from "fs";
+import { fileURLToPath } from "url";
+import path from "path";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const pkgPath = path.resolve(__dirname, "../../package.json");
+const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
+
+export async function versionCommand() {
+  console.log(`zmemory v${pkg.version}`);
+}

package/src/commands/who.js

@@ -0,0 +1,26 @@
+import { who } from "../lib/coordination/who.js";
+
+export async function whoCommand(args) {
+  const file = args[0];
+
+  if (!file) {
+    console.log("usage: zmemory who <file>");
+    return;
+  }
+
+  const matches = who(file);
+
+  if (!matches.length) {
+    console.log("no claims for", file);
+    return;
+  }
+
+  for (const m of matches) {
+    console.log(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();
+  }
+}

package/src/commands/worker.js

@@ -0,0 +1,71 @@
+import http from "http";
+import { claimTask, listTasks, completeTask } from "../lib/tasks.js";
+import { lockFiles, releaseFiles } from "../lib/fileLocks.js";
+import { appendFile, now } from "../lib/fs.js";
+
+// Simple autonomous worker that listens to the event bus
+// and attempts to claim pending tasks.
+
+export async function workerCommand(args) {
+  const name = args[0] || "worker";
+
+  console.log("Starting worker:", name);
+
+  setInterval(() => {
+    const tasks = listTasks();
+    const pending = tasks.find((t) => {
+      if (t.status !== "pending") return false;
+
+      if (!t.depends_on || !t.depends_on.length) return true;
+
+      return t.depends_on.every((d) => {
+        const dep = tasks.find((x) => x.id === d);
+        return dep && dep.status === "done";
+      });
+    });
+
+    if (!pending) return;
+
+    const claimed = claimTask(pending.id, name);
+
+    if (!claimed) return;
+
+    if (claimed.file_scope && claimed.file_scope.length) {
+      try {
+        lockFiles(name, claimed.file_scope);
+      } catch {
+        return;
+      }
+    }
+
+    console.log("claimed task", claimed.id);
+
+    // simulate work
+    setTimeout(() => {
+      completeTask(claimed.id);
+
+      if (claimed.file_scope && claimed.file_scope.length) {
+        releaseFiles(name);
+      }
+
+      const evt = {
+        ts: now(),
+        role: "worker",
+        type: "task_completed",
+        summary: claimed.title,
+        task: claimed.id
+      };
+
+      appendFile(".zmemory/logs/events.jsonl", JSON.stringify(evt) + "\n");
+
+      console.log("completed task", claimed.id);
+    }, 2000);
+  }, 2000);
+
+  // keep process alive
+  http
+    .createServer((_, res) => {
+      res.end("worker alive");
+    })
+    .listen(0);
+}

package/src/commands/workspaces.js

@@ -0,0 +1,25 @@
+import { addWorkspace, listWorkspaces } from "../lib/workspaces.js";
+
+export async function workspacesCommand(args) {
+  const sub = args[0];
+
+  if (sub === "add") {
+    const p = args[1];
+    if (typeof p !== "string" || p.trim().length === 0) {
+      console.log("usage: zmemory workspaces add <path>");
+      return;
+    }
+    const pathClean = p.trim();
+    addWorkspace(pathClean);
+    console.log("workspace added:", pathClean);
+    return;
+  }
+
+  if (sub === "list") {
+    const ws = listWorkspaces();
+    ws.forEach((w) => console.log(w));
+    return;
+  }
+
+  console.log("usage: zmemory workspaces add|list");
+}

package/src/daemon/orchestrator.js

@@ -0,0 +1,34 @@
+import { listTasks, claimTask, completeTask } from "../lib/tasks.js";
+import { appendFile, now } from "../lib/fs.js";
+
+// Very small orchestration loop that can coordinate workers
+export function startOrchestrator() {
+  console.log("ZMemory orchestrator started");
+
+  setInterval(() => {
+    const tasks = listTasks();
+
+    const runnable = tasks.filter(
+      (t) => t.status === "pending" && (!t.depends_on || !t.depends_on.length)
+    );
+
+    runnable.forEach((task) => {
+      const claimed = claimTask(task.id, "orchestrator");
+      if (!claimed) return;
+
+      const evt = {
+        ts: now(),
+        role: "orchestrator",
+        type: "task_scheduled",
+        summary: task.title,
+        task: task.id
+      };
+
+      appendFile(".zmemory/logs/events.jsonl", JSON.stringify(evt) + "\n");
+
+      // immediately mark complete for prototype scheduling
+      completeTask(task.id);
+    });
+  }, 3000);
+}
+

package/src/daemon/zmemoryd.js

@@ -0,0 +1,17 @@
+import { startDashboard } from "../dashboard/server.js";
+import { startEventBus } from "../bus/server.js";
+import { startOrchestrator } from "./orchestrator.js";
+import { ensureZMemory } from "../integrations/auto-bootstrap.js";
+import "../mcp/server.js"; // start MCP stdio server
+
+// Unified daemon so harnesses only start one process
+export function startDaemon() {
+  console.log("Starting ZMemory daemon...");
+  // ensure memory + autoloaded skill exist for harnesses
+  ensureZMemory();
+  startEventBus();
+  startOrchestrator();
+  startDashboard();
+  console.log("MCP interface ready (stdio)");
+  console.log("ZMemory daemon ready");
+}

package/src/dashboard/server.js

@@ -0,0 +1,40 @@
+import http from "http";
+import fs from "fs";
+
+export function startDashboard() {
+  const port = 4321;
+
+  const server = http.createServer((req, res) => {
+    if (req.url === "/events") {
+      const data = fs.existsSync(".zmemory/logs/events.jsonl")
+        ? fs.readFileSync(".zmemory/logs/events.jsonl", "utf8")
+        : "";
+      res.writeHead(200, { "Content-Type": "text/plain" });
+      res.end(data);
+      return;
+    }
+
+    res.writeHead(200, { "Content-Type": "text/html" });
+    res.end(`
+      <html>
+      <body>
+        <h1>ZMemory Dashboard</h1>
+        <pre id="log"></pre>
+        <script>
+          async function load(){
+            const r = await fetch('/events');
+            const t = await r.text();
+            document.getElementById('log').textContent = t;
+          }
+          setInterval(load,1000);
+          load();
+        </script>
+      </body>
+      </html>
+    `);
+  });
+
+  server.listen(port);
+  console.log("dashboard running http://localhost:" + port);
+}
+

package/src/integrations/agent-hooks.md

@@ -0,0 +1,39 @@
+# ZMemory Agent Hooks
+
+This document explains how external AI coding agents should integrate with
+ZMemory automatically.
+
+Recommended workflow for agents:
+
+1. On startup
+
+   ```
+   zmemory resume
+   ```
+
+2. Before executing a task
+
+   ```
+   zmemory context --role executor --run <run_id>
+   ```
+
+3. After modifying files
+
+   ```
+   zmemory event --run <run_id> --role executor --type file_changed --summary "<change>"
+   ```
+
+4. After finishing a step
+
+   ```
+   zmemory state update --run <run_id> --next-action "<next step>"
+   ```
+
+5. Before terminating
+
+   ```
+   zmemory handoff --run <run_id>
+   ```
+
+Agents can embed these commands directly in their execution loop.
+