@holt-os/holt 0.6.0 → 0.7.0

package/README.md

@@ -127,6 +127,39 @@ holt skill remove <name>              delete a skill
 
 In chat, run one with `/skill <name> [your input]`. Available skills are also listed to the brain each turn, so it knows what it can be asked to follow.
 
+## Use Holt from your other tools (MCP)
+
+Holt can run as an [MCP](https://modelcontextprotocol.io) server, so Claude Code, Cursor, and Codex can recall and remember from Holt's memory for the folder without leaving those tools.
+
+```bash
+holt mcp        # run the MCP server for the current folder (talks JSON-RPC over stdio)
+holt mcp setup  # print the config snippets for each client
+```
+
+The server serves the memory of whatever folder it is launched in. Because MCP is non-interactive (stdin carries the protocol), it cannot prompt for trust, so it **auto-trusts the launch folder** and adds it to `~/.holt/trust.json`. Startup logging goes to stderr; stdout is reserved for the protocol.
+
+Tools it exposes:
+
+- `recall` (`query`, optional `k`): search this folder's memory for relevant moments and facts.
+- `remember` (`content`): save a durable fact to this folder's memory.
+- `list_skills`: list the skills installed for this folder.
+- `get_skill` (`name`): get a skill's full instructions.
+- `memory_stats`: memory statistics for this folder.
+
+**Claude Code**
+
+```bash
+claude mcp add holt -- holt mcp
+```
+
+**Cursor / Codex** (JSON config):
+
+```json
+{ "mcpServers": { "holt": { "command": "holt", "args": ["mcp"] } } }
+```
+
+Point the client at the folder whose memory you want it to use; Holt serves whatever folder the server process starts in.
+
 ## Output format
 
 Replies print as markdown. `/output html` (or `markdown`) switches the save format and persists it. `/save [name]` writes the last reply to the current folder: `.md`, or a small self-contained dark-theme `.html` page.
@@ -137,6 +170,7 @@ Replies print as markdown. `/output html` (or `markdown`) switches the save form
 holt init            set up (trust, brains, sign-in, defaults) for this folder
 holt chat            start a session that remembers past ones
 holt graph           see your memory as an interactive knowledge graph
+holt mcp             run an MCP server so other tools use this folder's memory (holt mcp setup for config)
 holt skill           manage skills: list | show | create | add | remove
 holt memory          inspect memory: holt memory [search <query> | embed | clear]
 holt setting         configure brains, API brains, and launch command

package/dist/cli.js

@@ -231,20 +231,20 @@ function runBrain(brain, prompt, onChunk) {
       return;
     }
     let out = "";
-    let err = "";
+    let err2 = "";
     child.stdout.on("data", (d) => {
       const s = d.toString();
       out += s;
       if (onChunk) onChunk(s);
     });
     child.stderr.on("data", (d) => {
-      err += d.toString();
+      err2 += d.toString();
     });
     child.on("error", (e) => resolve3({ ok: false, text: `Could not run "${brain.command}": ${e.message}` }));
     child.on("close", (code) => {
       const text = out.trim();
       if (code === 0 && text) resolve3({ ok: true, text });
-      else resolve3({ ok: false, text: err.trim() || text || `"${brain.command}" exited with code ${code}` });
+      else resolve3({ ok: false, text: err2.trim() || text || `"${brain.command}" exited with code ${code}` });
     });
   });
 }
@@ -765,9 +765,9 @@ async function init() {
   console.log("Looking for agent CLIs on your machine...\n");
   const found = [];
   for (const id of BRAIN_IDS) {
-    const ok = isInstalled(BRAIN_DEFS[id].command);
-    console.log(`  ${ok ? c.green("found  ") : c.dim("missing")}  ${BRAIN_DEFS[id].label} (${BRAIN_DEFS[id].command})`);
-    if (ok) found.push(id);
+    const ok2 = isInstalled(BRAIN_DEFS[id].command);
+    console.log(`  ${ok2 ? c.green("found  ") : c.dim("missing")}  ${BRAIN_DEFS[id].label} (${BRAIN_DEFS[id].command})`);
+    if (ok2) found.push(id);
   }
   console.log("");
   const chosen = parseBrains(
@@ -2692,8 +2692,315 @@ async function graph(args = []) {
   }
 }
 
+// src/mcp/server.ts
+var DEFAULT_PROTOCOL_VERSION = "2025-06-18";
+function isObject(v) {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function ok(id, result) {
+  return { jsonrpc: "2.0", id: id ?? null, result };
+}
+function err(id, code, message) {
+  return { jsonrpc: "2.0", id: id ?? null, error: { code, message } };
+}
+async function handleMcpMessage(msg, opts) {
+  if (!isObject(msg)) {
+    console.error("[mcp] ignoring non-object message");
+    return null;
+  }
+  const message = msg;
+  const method = typeof message.method === "string" ? message.method : void 0;
+  const hasId = "id" in message && message.id !== void 0 && message.id !== null;
+  const id = message.id;
+  if (method === void 0) {
+    if (hasId) return err(id, -32600, "Invalid Request: missing method");
+    console.error("[mcp] ignoring message with no method");
+    return null;
+  }
+  if (!hasId) {
+    if (!method.startsWith("notifications/")) {
+      console.error(`[mcp] ignoring notification-shaped message: ${method}`);
+    }
+    return null;
+  }
+  const params = isObject(message.params) ? message.params : {};
+  try {
+    switch (method) {
+      case "initialize": {
+        const requested = params["protocolVersion"];
+        const protocolVersion = typeof requested === "string" ? requested : DEFAULT_PROTOCOL_VERSION;
+        return ok(id, {
+          protocolVersion,
+          capabilities: { tools: {} },
+          serverInfo: { name: opts.name, version: opts.version }
+        });
+      }
+      case "ping":
+        return ok(id, {});
+      case "tools/list":
+        return ok(id, {
+          tools: opts.tools.map((t) => ({
+            name: t.name,
+            description: t.description,
+            inputSchema: t.inputSchema
+          }))
+        });
+      case "tools/call": {
+        const name = typeof params["name"] === "string" ? params["name"] : "";
+        const rawArgs = params["arguments"];
+        const args = isObject(rawArgs) ? rawArgs : {};
+        const tool = opts.tools.find((t) => t.name === name);
+        if (!tool) {
+          return ok(id, {
+            content: [{ type: "text", text: "Unknown tool: " + name }],
+            isError: true
+          });
+        }
+        try {
+          const text = await tool.handler(args);
+          return ok(id, { content: [{ type: "text", text }] });
+        } catch (e) {
+          const emsg = e instanceof Error ? e.message : String(e);
+          return ok(id, {
+            content: [{ type: "text", text: "Tool error: " + emsg }],
+            isError: true
+          });
+        }
+      }
+      default:
+        return err(id, -32601, "Method not found: " + method);
+    }
+  } catch (e) {
+    const emsg = e instanceof Error ? e.message : String(e);
+    console.error(`[mcp] internal error handling ${method}: ${emsg}`);
+    return err(id, -32603, "Internal error: " + emsg);
+  }
+}
+function recoverId(line) {
+  const num = line.match(/"id"\s*:\s*(-?\d+(?:\.\d+)?)/);
+  if (num && num[1] !== void 0) {
+    const n = Number(num[1]);
+    if (Number.isFinite(n)) return n;
+  }
+  const str = line.match(/"id"\s*:\s*"((?:[^"\\]|\\.)*)"/);
+  if (str && str[1] !== void 0) return str[1];
+  return null;
+}
+function runMcpServer(opts) {
+  return new Promise((resolve3) => {
+    const stdin = process.stdin;
+    let buffer = "";
+    let chain = Promise.resolve();
+    const send = (response) => {
+      process.stdout.write(JSON.stringify(response) + "\n");
+    };
+    const processLine = (rawLine) => {
+      const line = rawLine.trim();
+      if (line === "") return;
+      let parsed;
+      try {
+        parsed = JSON.parse(line);
+      } catch {
+        const id = recoverId(line);
+        if (id !== null) {
+          send(err(id, -32700, "Parse error"));
+        } else {
+          console.error("[mcp] parse error on line, no id to recover, skipping");
+        }
+        return;
+      }
+      if (Array.isArray(parsed)) {
+        chain = chain.then(async () => {
+          for (const entry of parsed) {
+            const response = await handleMcpMessage(entry, opts);
+            if (response !== null) send(response);
+          }
+        });
+        return;
+      }
+      chain = chain.then(async () => {
+        const response = await handleMcpMessage(parsed, opts);
+        if (response !== null) send(response);
+      });
+    };
+    stdin.setEncoding("utf8");
+    stdin.on("data", (chunk) => {
+      buffer += chunk;
+      let nl = buffer.indexOf("\n");
+      while (nl !== -1) {
+        const line = buffer.slice(0, nl);
+        buffer = buffer.slice(nl + 1);
+        processLine(line);
+        nl = buffer.indexOf("\n");
+      }
+    });
+    stdin.on("end", () => {
+      if (buffer.length > 0) {
+        processLine(buffer);
+        buffer = "";
+      }
+      chain.then(() => resolve3()).catch(() => resolve3());
+    });
+    stdin.on("error", (e) => {
+      console.error(`[mcp] stdin error: ${e.message}`);
+      chain.then(() => resolve3()).catch(() => resolve3());
+    });
+    stdin.resume();
+  });
+}
+
+// src/mcp/tools.ts
+var MCP_SESSION = "__mcp__";
+function holtTools() {
+  return [
+    {
+      name: "recall",
+      description: "Search Holt's memory for this folder and return the most relevant remembered moments and distilled facts.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          query: { type: "string", description: "What to recall." },
+          k: { type: "number", description: "Max results to return (default 5)." }
+        },
+        required: ["query"]
+      },
+      handler: async (args) => {
+        try {
+          const query = String(args.query || "").trim();
+          if (!query) return "Provide a query to recall.";
+          const k = Number(args.k) || 5;
+          const hits = await recall(query, MCP_SESSION, k);
+          if (hits.length === 0) return "No relevant memory found.";
+          const lines = hits.map(
+            (h) => `${h.score.toFixed(2)}  (${h.turn.role})  ${h.turn.content.replace(/\s+/g, " ").trim()}`
+          );
+          return [`Recalled ${hits.length} relevant memory item(s):`, ...lines].join("\n");
+        } catch (err2) {
+          return `Could not recall right now: ${err2 instanceof Error ? err2.message : String(err2)}`;
+        }
+      }
+    },
+    {
+      name: "remember",
+      description: "Save a durable fact to Holt's memory for this folder.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          content: { type: "string", description: "The fact to remember." }
+        },
+        required: ["content"]
+      },
+      handler: async (args) => {
+        try {
+          const content = String(args.content || "").trim();
+          if (!content) return "Nothing to remember: content was empty.";
+          const ok2 = await saveFact(content, MCP_SESSION);
+          return ok2 ? "Remembered." : "Already known (duplicate).";
+        } catch (err2) {
+          return `Could not remember right now: ${err2 instanceof Error ? err2.message : String(err2)}`;
+        }
+      }
+    },
+    {
+      name: "list_skills",
+      description: "List the skills installed for this folder (workspace and global).",
+      inputSchema: { type: "object", properties: {} },
+      handler: async () => {
+        try {
+          const skills = listSkills();
+          if (skills.length === 0) return "No skills installed.";
+          const lines = skills.map((s) => `${s.name}: ${s.description || "(no description)"}`);
+          return ["Installed skills:", ...lines].join("\n");
+        } catch (err2) {
+          return `Could not list skills right now: ${err2 instanceof Error ? err2.message : String(err2)}`;
+        }
+      }
+    },
+    {
+      name: "get_skill",
+      description: "Get the full instructions (body) of a skill by name.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          name: { type: "string", description: "The skill name." }
+        },
+        required: ["name"]
+      },
+      handler: async (args) => {
+        try {
+          const name = String(args.name || "").trim();
+          if (!name) return "Provide a skill name.";
+          const loaded = loadSkill(name);
+          if (!loaded) return `No skill named "${name}".`;
+          return [`Skill: ${loaded.skill.name}`, "", loaded.body].join("\n");
+        } catch (err2) {
+          return `Could not load that skill right now: ${err2 instanceof Error ? err2.message : String(err2)}`;
+        }
+      }
+    },
+    {
+      name: "memory_stats",
+      description: "Show statistics for Holt's memory in this folder.",
+      inputSchema: { type: "object", properties: {} },
+      handler: async () => {
+        try {
+          const s = memStats();
+          return [
+            "Holt memory (this folder):",
+            `moments    ${s.turns}`,
+            `facts      ${s.facts}`,
+            `sessions   ${s.sessions}`,
+            `embedded   ${s.withEmbeddings} of ${s.turns}`,
+            `size       ${(s.bytes / 1024).toFixed(1)} KB`
+          ].join("\n");
+        } catch (err2) {
+          return `Could not read memory stats right now: ${err2 instanceof Error ? err2.message : String(err2)}`;
+        }
+      }
+    }
+  ];
+}
+
+// src/commands/mcp.ts
+function printSetup() {
+  const config = JSON.stringify(
+    { mcpServers: { holt: { command: "holt", args: ["mcp"] } } },
+    null,
+    2
+  );
+  const out = [
+    "Add Holt as an MCP server to your other tools.",
+    "",
+    "The server serves the memory of whatever folder it is launched in, and",
+    "auto-trusts that folder on first run.",
+    "",
+    "Claude Code:",
+    "  claude mcp add holt -- holt mcp",
+    "",
+    "Cursor / Codex (JSON config):",
+    config,
+    ""
+  ].join("\n");
+  console.log(out);
+}
+async function mcp(sub, rest = []) {
+  void rest;
+  if (sub === "setup") {
+    printSetup();
+    return;
+  }
+  try {
+    if (!isTrusted()) trustDir();
+    console.error("Holt MCP: serving memory for " + workspace());
+    await runMcpServer({ name: "holt", version: "0.7.0", tools: holtTools() });
+  } catch (err2) {
+    console.error("Holt MCP failed: " + (err2 instanceof Error ? err2.message : String(err2)));
+    process.exitCode = 1;
+  }
+}
+
 // src/cli.ts
-var VERSION = "0.6.0";
+var VERSION = "0.7.0";
 var BANNER = `
   \u2588\u2588\u2557  \u2588\u2588\u2557 \u2588\u2588\u2588\u2588\u2588\u2588\u2557 \u2588\u2588\u2557  \u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2557
   \u2588\u2588\u2551  \u2588\u2588\u2551\u2588\u2588\u2554\u2550\u2550\u2550\u2588\u2588\u2557\u2588\u2588\u2551  \u255A\u2550\u2550\u2588\u2588\u2554\u2550\u2550\u255D
@@ -2712,6 +3019,7 @@ Commands:
   memory          Inspect memory: holt memory [search <query> | embed | clear]
   graph           See your memory as an interactive knowledge graph in the browser
   skill           Manage skills: holt skill [list | show | create | add | remove]
+  mcp             Serve this folder's memory to Claude Code, Cursor, Codex (holt mcp setup)
   setting         Configure brains, API brains, and your launch command (per folder)
   login <brain>   Sign in to a brain: claude, codex, or gemini
   version         Print the Holt version
@@ -2761,6 +3069,9 @@ async function main() {
     case "graph":
       await graph(process.argv.slice(3));
       break;
+    case "mcp":
+      await mcp(process.argv[3], process.argv.slice(4));
+      break;
     default:
       console.log(`
   Unknown command: "${cmd}"`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@holt-os/holt",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "An open-source personal agent OS: any LLM, private memory you can see and walk.",
   "type": "module",
   "license": "MIT",