claude-code-swarm 0.3.16 → 0.3.18

package/.claude-plugin/marketplace.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-swarm",
-  "version": "0.3.16",
+  "version": "0.3.18",
   "description": "Launch Claude Code with swarmkit capabilities, including team orchestration, MAP observability, and session tracking.",
   "owner": {
     "name": "alexngai"

package/.claude-plugin/mcp-launcher.mjs

@@ -162,12 +162,25 @@ if (!def.enabled()) {
   runNoop();
 } else {
   const { cmd, args } = def.launch();
-  if (which(cmd)) {
-    // Replace this process with the real server
-    const { execFileSync: _ , ...rest } = await import('node:child_process');
+  const resolved = which(cmd);
+  // Debug: log MCP server resolution to a temp file for diagnostics
+  try {
+    const { appendFileSync } = await import('node:fs');
+    appendFileSync('/tmp/mcp-launcher-debug.log', `[${new Date().toISOString()}] server=${server} cmd=${cmd} resolved=${resolved} cwd=${process.cwd()} args=${JSON.stringify(args)}\n`);
+  } catch {}
+  if (resolved) {
+    // Replace this process with the real server.
+    // NODE_NO_WARNINGS suppresses Node.js experimental feature warnings on stderr
+    // (e.g., sqlite). Some MCP clients interpret stderr output as server errors,
+    // causing them to mark the server as "failed" even though it's functional.
+    const spawnEnv = { ...process.env, NODE_NO_WARNINGS: '1' };
     const child = (await import('node:child_process')).spawn(cmd, args, {
-      stdio: 'inherit',
+      stdio: ['inherit', 'inherit', 'pipe'],
+      env: spawnEnv,
     });
+    // Swallow stderr to prevent MCP client from misinterpreting it.
+    // In debug mode, forward to our stderr.
+    child.stderr.on('data', () => {});
     child.on('exit', (code) => process.exit(code ?? 0));
   } else {
     process.stderr.write(`[${server}-mcp] ${cmd} CLI not found\n`);

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "claude-code-swarm",
   "description": "Spin up Claude Code agent teams from openteams YAML topologies with optional MAP (Multi-Agent Protocol) observability and coordination. Provides hooks for session lifecycle, agent spawn/complete tracking, and a /swarm skill to launch team configurations.",
-  "version": "0.3.16",
+  "version": "0.3.18",
   "author": {
     "name": "alexngai"
   },

package/e2e/tier7-memory-sync.test.mjs

@@ -0,0 +1,259 @@
+/**
+ * Tier 7: minimem → MAP sync integration test
+ *
+ * Tests the full bridge flow:
+ *   Agent uses minimem MCP tool (write) → PostToolUse hook fires
+ *   → map-hook.mjs builds bridge command → sidecar calls x-openhive/memory.sync
+ *   → Mock MAP server receives the sync notification
+ *
+ * Groups:
+ *   1. Hook configuration verification (no agent, no LLM)
+ *   2. Bridge command builder (no agent, no LLM)
+ *   3. Live agent writes memory → MAP event received (LIVE_AGENT_TEST=1)
+ */
+
+import { describe, it, expect, beforeAll, afterAll } from "vitest";
+import { createWorkspace } from "./helpers/workspace.mjs";
+import { cleanupWorkspace, waitFor } from "./helpers/cleanup.mjs";
+import { readFileSync, existsSync, writeFileSync, mkdirSync, readdirSync } from "fs";
+import { join } from "path";
+
+// Check if dependencies are available (try require for CJS-compatible packages)
+import { createRequire } from "module";
+const require = createRequire(import.meta.url);
+
+let minimemAvailable = false;
+try {
+  require("minimem");
+  minimemAvailable = true;
+} catch { /* minimem not installed */ }
+
+let mapSdkAvailable = false;
+try {
+  require("@multi-agent-protocol/sdk");
+  mapSdkAvailable = true;
+} catch { /* MAP SDK not installed */ }
+
+// Check if Claude CLI is available
+let cliAvailable = false;
+try {
+  const { CLI_AVAILABLE } = await import("./helpers/cli.mjs");
+  cliAvailable = CLI_AVAILABLE;
+} catch { /* CLI not available */ }
+
+// ── Group 1: Hook configuration ─────────────────────────────────────────────
+
+describe("tier7: minimem sync hook configuration", { timeout: 30_000 }, () => {
+  it("hooks.json has a PostToolUse entry for minimem", () => {
+    const hooksPath = join(import.meta.dirname, "..", "hooks", "hooks.json");
+    const hooks = JSON.parse(readFileSync(hooksPath, "utf-8"));
+    const postToolUse = hooks.hooks.PostToolUse || [];
+
+    const minimemHook = postToolUse.find((h) => h.matcher === "minimem");
+    expect(minimemHook).toBeDefined();
+    expect(minimemHook.hooks[0].command).toContain("minimem-mcp-used");
+  });
+
+  it("minimem hook checks both minimem.enabled and map.enabled", () => {
+    const hooksPath = join(import.meta.dirname, "..", "hooks", "hooks.json");
+    const hooks = JSON.parse(readFileSync(hooksPath, "utf-8"));
+    const postToolUse = hooks.hooks.PostToolUse || [];
+
+    const minimemHook = postToolUse.find((h) => h.matcher === "minimem");
+    const cmd = minimemHook.hooks[0].command;
+
+    expect(cmd).toContain("minimem");
+    expect(cmd).toContain("map");
+  });
+
+  it("hooks.json minimem hook is gated behind config check", () => {
+    const hooksPath = join(import.meta.dirname, "..", "hooks", "hooks.json");
+    const hooks = JSON.parse(readFileSync(hooksPath, "utf-8"));
+    const postToolUse = hooks.hooks.PostToolUse || [];
+
+    const minimemHook = postToolUse.find((h) => h.matcher === "minimem");
+    const cmd = minimemHook.hooks[0].command;
+
+    // Should have the config check prefix (node -e "..." && node map-hook.mjs)
+    expect(cmd).toContain('node -e');
+    expect(cmd).toContain('process.exit');
+    expect(cmd).toContain('map-hook.mjs');
+  });
+});
+
+// ── Group 2: Bridge command builder ─────────────────────────────────────────
+
+describe("tier7: minimem bridge command builder", { timeout: 30_000 }, () => {
+  it("builds command for write operations", async () => {
+    const { buildMinimemBridgeCommand } = await import("../src/map-events.mjs");
+
+    const cmd = buildMinimemBridgeCommand({
+      tool_name: "minimem__memory_append",
+      tool_input: { text: "Test memory entry" },
+      session_id: "test-session",
+    });
+
+    expect(cmd).not.toBeNull();
+    expect(cmd.action).toBe("bridge-memory-sync");
+    expect(cmd.agentId).toBe("test-session");
+  });
+
+  it("skips read-only operations", async () => {
+    const { buildMinimemBridgeCommand } = await import("../src/map-events.mjs");
+
+    const cmd = buildMinimemBridgeCommand({
+      tool_name: "minimem__memory_search",
+      tool_input: { query: "test" },
+    });
+
+    expect(cmd).toBeNull();
+  });
+
+  it("map-hook.mjs switch statement includes minimem-mcp-used", () => {
+    const hookScript = readFileSync(
+      join(import.meta.dirname, "..", "scripts", "map-hook.mjs"),
+      "utf-8"
+    );
+    expect(hookScript).toContain('"minimem-mcp-used"');
+    expect(hookScript).toContain("handleMinimemMcpUsed");
+  });
+
+  it("sidecar-server.mjs handles bridge-memory-sync command", () => {
+    const sidecarScript = readFileSync(
+      join(import.meta.dirname, "..", "src", "sidecar-server.mjs"),
+      "utf-8"
+    );
+    expect(sidecarScript).toContain('"bridge-memory-sync"');
+    expect(sidecarScript).toContain("x-openhive/memory.sync");
+  });
+});
+
+// ── Group 3: Live agent test ────────────────────────────────────────────────
+
+describe.skipIf(!process.env.LIVE_AGENT_TEST || !minimemAvailable || !cliAvailable || !mapSdkAvailable)(
+  "tier7: live agent minimem → MAP sync",
+  { timeout: 300_000 },
+  () => {
+    let mockServer;
+    let workspace;
+    let messages;
+    let runResult;
+
+    beforeAll(async () => {
+      const { MockMapServer } = await import("./helpers/map-mock-server.mjs");
+      mockServer = new MockMapServer();
+      await mockServer.start();
+
+      workspace = createWorkspace({
+        config: {
+          minimem: { enabled: true, provider: "none" },
+          map: {
+            enabled: true,
+            server: `ws://localhost:${mockServer.port}`,
+          },
+        },
+        gitInit: true,
+      });
+
+      // Initialize minimem in the workspace so the MCP server can start.
+      // Must run `minimem sync` to create index.db — without it the MCP server
+      // starts but may report tools inconsistently.
+      const minimemDir = join(workspace.dir, ".swarm", "minimem");
+      mkdirSync(join(minimemDir, "memory"), { recursive: true });
+      writeFileSync(join(minimemDir, "MEMORY.md"), "# Test Memory\n");
+      writeFileSync(
+        join(minimemDir, "config.json"),
+        JSON.stringify({ embedding: { provider: "none" } })
+      );
+      writeFileSync(join(minimemDir, ".gitignore"), "index.db\n");
+
+      // Initialize the search index — critical for MCP server readiness.
+      // Use require() to avoid ESM resolution issues with node:sqlite in vitest.
+      try {
+        const { Minimem } = require("minimem");
+        const mem = await Minimem.create({ memoryDir: minimemDir, embedding: { provider: "none" } });
+        await mem.sync();
+        await mem.close();
+      } catch (err) {
+        console.warn("[tier7] minimem init warning:", err.message?.slice(0, 200));
+      }
+
+      const { runClaude } = await import("./helpers/cli.mjs");
+      runResult = await runClaude(
+        'Use the minimem MCP tools: First search for "test" using memory_search. Then write a memory file at .swarm/minimem/memory/e2e-test.md containing "### 2026-03-31 12:00\n<!-- type: decision -->\nChose PostgreSQL for the main database." using the Write tool. Report what you did.',
+        {
+          cwd: workspace.dir,
+          model: "haiku",
+          maxTurns: 6,
+          maxBudgetUsd: 0.5,
+          timeout: 120_000,
+          label: "memory-sync-e2e",
+        }
+      );
+      messages = runResult.messages;
+    }, 300_000);
+
+    afterAll(async () => {
+      if (workspace) {
+        try { cleanupWorkspace(workspace.dir); } catch { /* best effort */ }
+      }
+      if (mockServer) {
+        try { await mockServer.stop(); } catch { /* best effort */ }
+      }
+    });
+
+    it("agent completed without error", () => {
+      expect(runResult.exitCode).toBe(0);
+    });
+
+    it("agent used minimem MCP tools", () => {
+      const { extractToolCalls } = require("./helpers/assertions.mjs");
+      const allCalls = extractToolCalls(messages);
+      const memCalls = allCalls.filter((c) =>
+        c.name?.includes("minimem") || c.name?.includes("memory_search")
+      );
+      expect(memCalls.length).toBeGreaterThan(0);
+    });
+
+    it("agent wrote a memory file", () => {
+      const { extractToolCalls } = require("./helpers/assertions.mjs");
+      const allCalls = extractToolCalls(messages);
+      // Agent may use Write tool to create memory file, or minimem append/upsert
+      const writeCalls = allCalls.filter(
+        (c) => c.name === "Write" || c.name?.includes("append") || c.name?.includes("upsert")
+      );
+      expect(writeCalls.length).toBeGreaterThan(0);
+    });
+
+    it("memory file was written to disk", () => {
+      const minimemDir = join(workspace.dir, ".swarm", "minimem");
+      const memoryDir = join(minimemDir, "memory");
+      if (!existsSync(memoryDir)) return; // skip if dir not created
+      const mdFiles = readdirSync(memoryDir).filter((f) => f.endsWith(".md"));
+      expect(mdFiles.length).toBeGreaterThan(0);
+    });
+
+    it("sidecar file watcher sent MAP sync notification", async () => {
+      // The sidecar's memory file watcher detects .md file writes and sends
+      // bridge-memory-sync → callExtension("x-openhive/memory.sync").
+      // This covers both Write tool and minimem MCP tool writes.
+      //
+      // The watcher has a 2s debounce, so we wait up to 10s for the event.
+      const received = await waitFor(() => {
+        const extCalls = mockServer.getByMethod("x-openhive/memory.sync");
+        if (extCalls.length > 0) return true;
+        const broadcasts = mockServer.getMessages("memory.sync");
+        if (broadcasts.length > 0) return true;
+        // Check all received messages for any memory-related content
+        const all = mockServer.receivedMessages || [];
+        return all.some(
+          (m) =>
+            JSON.stringify(m).includes("memory") &&
+            JSON.stringify(m).includes("sync")
+        );
+      }, 10_000);
+
+      expect(received).toBe(true);
+    });
+  }
+);

package/hooks/hooks.json

@@ -62,6 +62,15 @@
           }
         ]
       },
+      {
+        "matcher": "minimem",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node -e \"const f=require('fs'),p=require('path'),h=require('os').homedir();let c={};try{c=JSON.parse(f.readFileSync('.swarm/claude-swarm/config.json','utf-8'))}catch{try{c=JSON.parse(f.readFileSync(p.join(h,'.claude-swarm','config.json'),'utf-8'))}catch{}};process.exit((c.minimem?.enabled||process.env.SWARM_MINIMEM_ENABLED)&&(c.map?.enabled||c.map?.server||process.env.SWARM_MAP_SERVER||process.env.SWARM_MAP_ENABLED)?0:1)\" 2>/dev/null && node \"${CLAUDE_PLUGIN_ROOT}/scripts/map-hook.mjs\" minimem-mcp-used"
+          }
+        ]
+      },
       {
         "matcher": "Task",
         "hooks": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-swarm",
-  "version": "0.3.16",
+  "version": "0.3.18",
   "description": "Claude Code plugin for launching agent teams from openteams topologies with MAP observability",
   "type": "module",
   "exports": {
@@ -18,7 +18,7 @@
     "swarm-generate-agents": "./scripts/generate-agents.mjs"
   },
   "dependencies": {
-    "@multi-agent-protocol/sdk": "^0.1.8",
+    "@multi-agent-protocol/sdk": "^0.1.9",
     "agentic-mesh": "^0.2.0",
     "js-yaml": "^4.1.0"
   },
@@ -54,7 +54,7 @@
   },
   "devDependencies": {
     "agent-inbox": "^0.1.9",
-    "minimem": "^0.1.0",
+    "minimem": "^0.1.1",
     "opentasks": "^0.0.8",
     "skill-tree": "^0.1.5",
     "vitest": "^4.0.18",

package/scripts/map-hook.mjs

@@ -48,6 +48,7 @@ import {
   buildOpentasksBridgeCommands,
   handleNativeTaskCreatedEvent,
   handleNativeTaskUpdatedEvent,
+  buildMinimemBridgeCommand,
 } from "../src/map-events.mjs";
 import { syncSessionlog, dispatchSessionlogHook } from "../src/sessionlog.mjs";
 import { findSocketPath, pushSyncEvent } from "../src/opentasks-client.mjs";
@@ -194,6 +195,18 @@ async function handleSessionlogDispatch(hookData) {
   await dispatchSessionlogHook(sessionlogHookName, hookData);
 }
 
+// ── minimem sync ─────────────────────────────────────────────────────────────
+
+async function handleMinimemMcpUsed(hookData, sessionId) {
+  const config = readConfig();
+  if (!config.minimem?.enabled) return;
+
+  const command = buildMinimemBridgeCommand(hookData);
+  if (command) {
+    await sendCommand(config, command, sessionId);
+  }
+}
+
 // ── Main ──────────────────────────────────────────────────────────────────────
 
 async function main() {
@@ -214,6 +227,7 @@ async function main() {
       case "opentasks-mcp-used": await handleOpentasksMcpUsed(hookData, sessionId); break;
       case "native-task-created": await handleNativeTaskCreated(hookData, sessionId); break;
       case "native-task-updated": await handleNativeTaskUpdated(hookData, sessionId); break;
+      case "minimem-mcp-used": await handleMinimemMcpUsed(hookData, sessionId); break;
       case "sessionlog-dispatch": await handleSessionlogDispatch(hookData); break;
       default:
         log.warn("unknown action", { action });

package/scripts/map-sidecar.mjs

@@ -25,6 +25,7 @@ import { connectToMAP } from "../src/map-connection.mjs";
 import { createMeshPeer, createMeshInbox } from "../src/mesh-connection.mjs";
 import { createSocketServer, createCommandHandler } from "../src/sidecar-server.mjs";
 import { createContentProvider } from "../src/content-provider.mjs";
+import { startMemoryWatcher } from "../src/memory-watcher.mjs";
 import { readConfig } from "../src/config.mjs";
 import { createLogger, init as initLog } from "../src/log.mjs";
 import { configureNodePath, resolvePackage } from "../src/swarmkit-resolver.mjs";
@@ -517,6 +518,30 @@ async function main() {
     return commandHandler(command, client);
   });
 
+  // Start memory file watcher if minimem is enabled
+  const sidecarConfig = readConfig();
+  if (sidecarConfig.minimem?.enabled) {
+    const minimemDir = sidecarConfig.minimem?.dir || ".swarm/minimem";
+    const memWatcher = startMemoryWatcher(minimemDir, (_event) => {
+      const fakeClient = {
+        write: () => {},
+        writable: true,
+      };
+      commandHandler({
+        action: "bridge-memory-sync",
+        agentId: SESSION_ID || "minimem",
+        timestamp: new Date().toISOString(),
+        memoryDir: minimemDir,
+      }, fakeClient);
+    });
+
+    // Clean up watcher on exit
+    if (memWatcher) {
+      process.on("exit", () => memWatcher.close());
+      process.on("SIGTERM", () => memWatcher.close());
+    }
+  }
+
   // Start inactivity timer
   resetInactivityTimer();
 

package/src/__tests__/memory-sync.test.mjs

@@ -0,0 +1,132 @@
+/**
+ * Unit tests for minimem → MAP sync bridge
+ *
+ * Tests the bridge command builder (map-events.mjs) that converts
+ * minimem MCP tool usage into MAP sync commands.
+ */
+
+import { describe, it, expect } from "vitest";
+import { buildMinimemBridgeCommand } from "../map-events.mjs";
+
+describe("buildMinimemBridgeCommand", () => {
+  describe("write operations (should emit)", () => {
+    it("emits for memory_append tool", () => {
+      const cmd = buildMinimemBridgeCommand({
+        tool_name: "minimem__memory_append",
+        tool_input: { text: "Decided to use Redis" },
+        tool_output: '{"content":[{"text":"Appended to memory/2026-03-27.md"}]}',
+      });
+
+      expect(cmd).not.toBeNull();
+      expect(cmd.action).toBe("bridge-memory-sync");
+      expect(cmd.timestamp).toBeDefined();
+    });
+
+    it("emits for memory_upsert tool", () => {
+      const cmd = buildMinimemBridgeCommand({
+        tool_name: "minimem__memory_upsert",
+        tool_input: { path: "memory/decision.md", content: "# Decision" },
+      });
+
+      expect(cmd).not.toBeNull();
+      expect(cmd.action).toBe("bridge-memory-sync");
+    });
+
+    it("emits for tool names containing 'append'", () => {
+      const cmd = buildMinimemBridgeCommand({
+        tool_name: "minimem__appendToday",
+        tool_input: { text: "some note" },
+      });
+
+      expect(cmd).not.toBeNull();
+      expect(cmd.action).toBe("bridge-memory-sync");
+    });
+
+    it("emits for tool names containing 'upsert'", () => {
+      const cmd = buildMinimemBridgeCommand({
+        tool_name: "minimem__upsert_file",
+        tool_input: { path: "memory/test.md" },
+      });
+
+      expect(cmd).not.toBeNull();
+    });
+
+    it("includes session_id as agentId", () => {
+      const cmd = buildMinimemBridgeCommand({
+        tool_name: "minimem__memory_append",
+        tool_input: { text: "test" },
+        session_id: "sess-abc-123",
+      });
+
+      expect(cmd.agentId).toBe("sess-abc-123");
+    });
+
+    it("defaults agentId to 'minimem' when no session_id", () => {
+      const cmd = buildMinimemBridgeCommand({
+        tool_name: "minimem__memory_append",
+        tool_input: { text: "test" },
+      });
+
+      expect(cmd.agentId).toBe("minimem");
+    });
+  });
+
+  describe("read operations (should NOT emit)", () => {
+    it("does not emit for memory_search", () => {
+      const cmd = buildMinimemBridgeCommand({
+        tool_name: "minimem__memory_search",
+        tool_input: { query: "redis caching" },
+      });
+
+      expect(cmd).toBeNull();
+    });
+
+    it("does not emit for memory_get_details", () => {
+      const cmd = buildMinimemBridgeCommand({
+        tool_name: "minimem__memory_get_details",
+        tool_input: { results: [] },
+      });
+
+      expect(cmd).toBeNull();
+    });
+
+    it("does not emit for knowledge_search", () => {
+      const cmd = buildMinimemBridgeCommand({
+        tool_name: "minimem__knowledge_search",
+        tool_input: { query: "database" },
+      });
+
+      expect(cmd).toBeNull();
+    });
+
+    it("does not emit for knowledge_graph", () => {
+      const cmd = buildMinimemBridgeCommand({
+        tool_name: "minimem__knowledge_graph",
+        tool_input: { nodeId: "k-test" },
+      });
+
+      expect(cmd).toBeNull();
+    });
+
+    it("does not emit for knowledge_path", () => {
+      const cmd = buildMinimemBridgeCommand({
+        tool_name: "minimem__knowledge_path",
+        tool_input: { fromId: "k-a", toId: "k-b" },
+      });
+
+      expect(cmd).toBeNull();
+    });
+  });
+
+  describe("edge cases", () => {
+    it("handles missing tool_name", () => {
+      const cmd = buildMinimemBridgeCommand({});
+      expect(cmd).toBeNull();
+    });
+
+    it("handles empty tool_name", () => {
+      const cmd = buildMinimemBridgeCommand({ tool_name: "" });
+      expect(cmd).toBeNull();
+    });
+  });
+});

package/src/__tests__/memory-watcher.test.mjs

@@ -0,0 +1,104 @@
+/**
+ * Unit tests for memory file watcher
+ */
+
+import { describe, it, expect, afterEach, vi } from "vitest";
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from "fs";
+import { join } from "path";
+import { tmpdir } from "os";
+import { startMemoryWatcher } from "../memory-watcher.mjs";
+
+describe("startMemoryWatcher", () => {
+  let tmpDir;
+  let watcher;
+
+  afterEach(() => {
+    if (watcher) {
+      watcher.close();
+      watcher = null;
+    }
+    if (tmpDir) {
+      try { rmSync(tmpDir, { recursive: true }); } catch {}
+      tmpDir = null;
+    }
+  });
+
+  it("returns null for non-existent directory", () => {
+    const result = startMemoryWatcher("/nonexistent/path", () => {});
+    expect(result).toBeNull();
+  });
+
+  it("returns null for empty/undefined dir", () => {
+    expect(startMemoryWatcher("", () => {})).toBeNull();
+    expect(startMemoryWatcher(undefined, () => {})).toBeNull();
+  });
+
+  it("returns a watcher handle with close method", () => {
+    tmpDir = mkdtempSync(join(tmpdir(), "mem-watch-"));
+    mkdirSync(join(tmpDir, "memory"), { recursive: true });
+
+    watcher = startMemoryWatcher(tmpDir, () => {});
+    expect(watcher).not.toBeNull();
+    expect(typeof watcher.close).toBe("function");
+  });
+
+  it("detects new .md file and calls onSync", async () => {
+    tmpDir = mkdtempSync(join(tmpdir(), "mem-watch-"));
+    mkdirSync(join(tmpDir, "memory"), { recursive: true });
+
+    const onSync = vi.fn();
+    watcher = startMemoryWatcher(tmpDir, onSync);
+
+    // Wait for watcher to be ready
+    await new Promise((r) => setTimeout(r, 500));
+
+    // Write a new .md file
+    writeFileSync(join(tmpDir, "memory", "test-note.md"), "# Test Note\nContent here.");
+
+    // Wait for debounce (2s) + buffer
+    await new Promise((r) => setTimeout(r, 3500));
+
+    expect(onSync).toHaveBeenCalled();
+    const call = onSync.mock.calls[0][0];
+    expect(call.type).toBe("add");
+    expect(call.path).toContain("test-note.md");
+  }, 10_000);
+
+  it("ignores non-.md files", async () => {
+    tmpDir = mkdtempSync(join(tmpdir(), "mem-watch-"));
+
+    const onSync = vi.fn();
+    watcher = startMemoryWatcher(tmpDir, onSync);
+
+    await new Promise((r) => setTimeout(r, 500));
+
+    // Write non-.md files
+    writeFileSync(join(tmpDir, "index.db"), "binary data");
+    writeFileSync(join(tmpDir, "config.json"), "{}");
+
+    await new Promise((r) => setTimeout(r, 3500));
+
+    expect(onSync).not.toHaveBeenCalled();
+  }, 10_000);
+
+  it("debounces rapid changes", async () => {
+    tmpDir = mkdtempSync(join(tmpdir(), "mem-watch-"));
+    mkdirSync(join(tmpDir, "memory"), { recursive: true });
+
+    const onSync = vi.fn();
+    watcher = startMemoryWatcher(tmpDir, onSync);
+
+    await new Promise((r) => setTimeout(r, 500));
+
+    // Write multiple files rapidly
+    writeFileSync(join(tmpDir, "memory", "note1.md"), "# Note 1");
+    writeFileSync(join(tmpDir, "memory", "note2.md"), "# Note 2");
+    writeFileSync(join(tmpDir, "memory", "note3.md"), "# Note 3");
+
+    // Wait for debounce
+    await new Promise((r) => setTimeout(r, 3500));
+
+    // Should only fire once (debounced)
+    expect(onSync).toHaveBeenCalledTimes(1);
+  }, 10_000);
+});

package/src/bootstrap.mjs

@@ -431,12 +431,37 @@ export async function bootstrap(pluginDirOverride, sessionId) {
 
   let minimemStatus = "disabled";
   if (config.minimem?.enabled) {
-    minimemStatus = "enabled";
+    // Check if minimem CLI is available and memory directory exists
+    try {
+      const { execFileSync } = await import("node:child_process");
+      const { existsSync } = await import("node:fs");
+      execFileSync("which", ["minimem"], { stdio: "pipe" });
+      const dir = config.minimem?.dir || ".swarm/minimem";
+      if (existsSync(dir)) {
+        minimemStatus = "ready";
+      } else {
+        // Create the directory and initialize so MCP server can start
+        const { mkdirSync } = await import("node:fs");
+        mkdirSync(dir + "/memory", { recursive: true });
+        try {
+          execFileSync("minimem", ["init", dir], { stdio: "pipe", timeout: 10_000 });
+        } catch { /* init may fail if already initialized */ }
+        minimemStatus = "ready";
+      }
+    } catch {
+      minimemStatus = "enabled"; // CLI not found — MCP server won't start
+    }
   }
 
   let skilltreeStatus = "disabled";
   if (config.skilltree?.enabled) {
-    skilltreeStatus = "enabled";
+    try {
+      const { execFileSync } = await import("node:child_process");
+      execFileSync("which", ["skill-tree"], { stdio: "pipe" });
+      skilltreeStatus = "ready";
+    } catch {
+      skilltreeStatus = "enabled";
+    }
   }
 
   return {

package/src/map-events.mjs

@@ -443,3 +443,33 @@ export async function handleNativeTaskUpdatedEvent(config, hookData, sessionId)
     }, sessionId);
   }
 }
+
+// ── minimem/skill-tree sync → MAP ──────────────────────────────────────────────
+//
+// When agents use minimem MCP tools that write data (append, upsert),
+// emit x-openhive/memory.sync so OpenHive can update its content cache.
+// This is a best-effort notification — the source of truth is the filesystem.
+
+/** Tools that indicate a memory write (vs read-only search) */
+const MINIMEM_WRITE_TOOLS = new Set([
+  "minimem__memory_append",
+  "minimem__memory_upsert",
+]);
+
+/**
+ * Build bridge command for minimem MCP tool use.
+ * Only emits for write operations (append/upsert), not reads.
+ */
+export function buildMinimemBridgeCommand(hookData) {
+  const toolName = hookData.tool_name || "";
+  // Only emit for write operations
+  if (!MINIMEM_WRITE_TOOLS.has(toolName) && !toolName.includes("append") && !toolName.includes("upsert")) {
+    return null;
+  }
+
+  return {
+    action: "bridge-memory-sync",
+    agentId: hookData.session_id || "minimem",
+    timestamp: new Date().toISOString(),
+  };
+}

package/src/memory-watcher.mjs

@@ -0,0 +1,73 @@
+/**
+ * memory-watcher.mjs — Watches the minimem memory directory for file changes
+ * and sends bridge-memory-sync commands to notify OpenHive via MAP.
+ *
+ * This bridges the gap between filesystem writes (Write tool, manual edits)
+ * and MAP sync notifications. minimem's MCP tools are read-only, so this
+ * watcher is the only way to detect when an agent writes to memory.
+ *
+ * Runs inside the MAP sidecar process (persistent for the session).
+ */
+
+import chokidar from "chokidar";
+import { existsSync } from "fs";
+import { createLogger } from "./log.mjs";
+
+const log = createLogger("memory-watcher");
+
+const DEBOUNCE_MS = 2000;
+
+/**
+ * Start watching a minimem directory for file changes.
+ * When changes are detected (debounced), calls the provided callback.
+ *
+ * @param {string} memoryDir - Path to the minimem directory (e.g., ".swarm/minimem")
+ * @param {(event: { type: string; path: string }) => void} onSync - Called when sync should be emitted
+ * @returns {{ close: () => void } | null} Watcher handle, or null if directory doesn't exist
+ */
+export function startMemoryWatcher(memoryDir, onSync) {
+  if (!memoryDir || !existsSync(memoryDir)) {
+    log.debug("memory watcher skipped — directory not found", { dir: memoryDir });
+    return null;
+  }
+
+  let debounceTimer = null;
+
+  const watcher = chokidar.watch(memoryDir, {
+    ignoreInitial: true,
+    ignored: [/node_modules/, /\.git/, /index\.db/, /\.cache/, /\.minimem/],
+    depth: 3,
+  });
+
+  function debouncedSync(eventType, filePath) {
+    // Only react to .md file changes
+    if (!filePath.endsWith(".md")) return;
+
+    if (debounceTimer) clearTimeout(debounceTimer);
+    debounceTimer = setTimeout(() => {
+      debounceTimer = null;
+      log.debug("memory change detected", { event: eventType, path: filePath });
+      onSync({ type: eventType, path: filePath });
+    }, DEBOUNCE_MS);
+  }
+
+  watcher.on("add", (p) => debouncedSync("add", p));
+  watcher.on("change", (p) => debouncedSync("change", p));
+  watcher.on("unlink", (p) => debouncedSync("unlink", p));
+
+  watcher.on("ready", () => {
+    log.info("memory watcher started", { dir: memoryDir });
+  });
+
+  watcher.on("error", (err) => {
+    log.warn("memory watcher error", { error: err.message });
+  });
+
+  return {
+    close() {
+      if (debounceTimer) clearTimeout(debounceTimer);
+      watcher.close();
+      log.debug("memory watcher stopped");
+    },
+  };
+}

package/src/sidecar-server.mjs

@@ -95,6 +95,7 @@ export function createCommandHandler(connection, scope, registeredAgents, opts =
   // Use a getter pattern so the connection ref can be updated
   let conn = connection;
   let _trajectoryResourceId = null; // Cached resource_id from server response
+  let _memoryResourceId = null; // Cached resource_id for memory sync
   const { inboxInstance, meshPeer, transportMode = "websocket" } = opts;
   const useMeshRegistry = transportMode === "mesh" && inboxInstance;
 
@@ -389,6 +390,43 @@ export function createCommandHandler(connection, scope, registeredAgents, opts =
           break;
         }
 
+        // --- Memory/skill sync → MAP (x-openhive vendor extensions) ---
+
+        case "bridge-memory-sync": {
+          const c = conn || await waitForConn();
+          if (c) {
+            try {
+              const params = {
+                resource_id: _memoryResourceId || "",
+                agent_id: command.agentId || "minimem",
+                commit_hash: `memory-${Date.now()}`,
+                timestamp: command.timestamp || new Date().toISOString(),
+                // Include the memory directory path for resource resolution on first call
+                path: command.memoryDir || "",
+              };
+              const result = await c.callExtension("x-openhive/memory.sync", params);
+              // Cache resource_id from server response
+              if (result?.resource_id) {
+                _memoryResourceId = result.resource_id;
+              }
+              respond(client, { ok: true, method: "memory-sync", resource_id: result?.resource_id });
+            } catch (err) {
+              log.warn("x-openhive/memory.sync not supported, falling back to broadcast", { error: err.message });
+              // Fallback: emit as a regular message
+              await c.send({ scope }, {
+                type: "memory.sync",
+                agent_id: command.agentId || "minimem",
+                timestamp: command.timestamp,
+                _origin: command.agentId || "minimem",
+              }, { relationship: "broadcast" });
+              respond(client, { ok: true, method: "broadcast-fallback" });
+            }
+          } else {
+            respond(client, { ok: false, error: "no connection" });
+          }
+          break;
+        }
+
         case "state": {
           const c = conn || await waitForConn();
           if (c) {