@holt-os/holt 0.5.2 → 0.7.0

package/README.md

@@ -63,6 +63,8 @@ The point of `/brain`: Holt owns the transcript, so you can start a thread on on
 
 Every exchange is saved to `<folder>/.holt/memory/turns.jsonl`, private and local. On each message, Holt recalls the most relevant moments from your *past* sessions in that folder and hands them to the brain, so it remembers what you told it last week.
 
+When you end a chat, Holt asks the brain to distill 1 to 5 durable facts from the session (decisions, preferences, key names, numbers) and writes them to a human-readable `<folder>/.holt/memory/facts.md` you can read and edit. Those facts are also embedded and ranked slightly higher than raw turns during recall, so the signal rises to the top over time. See them with `holt memory facts`. Turn it off by setting `memory.extractFacts` to `false` in `config.json`.
+
 Two recall modes, picked automatically:
 
 - **Semantic** (best): a local [Ollama](https://ollama.com) with an embedding model, which `holt init` offers to set up for you. Recall matches by meaning: asking "who owns my apartment" finds "my landlord is called Pieter". No API keys, nothing leaves your machine.
@@ -72,6 +74,7 @@ Inspect it any time:
 
 ```bash
 holt memory                    # stats for this folder
+holt memory facts              # show the distilled facts (facts.md)
 holt memory search <query>     # find remembered moments
 holt memory embed              # embed older moments for semantic recall
 holt memory clear              # wipe this folder's memory
@@ -124,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.
@@ -134,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
@@ -155,7 +192,7 @@ Small strongly-typed **TypeScript core**, zero runtime dependencies: command dis
 Built in always-shippable phases toward a full-vision v1:
 
 0. **Skeleton and chat**: trust, init with install and sign-in, chat, brain switching with kept context *(shipped)*
-1. **Memory**: per-folder store, semantic recall via local embeddings with keyword fallback, streaming replies *(shipped)*
+1. **Memory**: per-folder store, semantic recall, streaming replies, and distilled facts per session *(shipped)*
 2. **Any LLM directly**: API brains with your own key, HTML or Markdown output *(shipped)*
 3. **Skills**: portable SKILL.md skills, create/add/run *(shipped)*
 4. **Knowledge graph**: see and navigate your own memory with `holt graph` *(shipped)*

package/dist/cli.js

@@ -121,7 +121,7 @@ function defaultConfig() {
     const d = BRAIN_DEFS[id];
     brains[id] = { id, label: d.label, command: d.command, args: [...d.args], enabled: false };
   }
-  return { version: 3, defaultBrain: null, brains, apiBrains: [], outputFormat: "markdown" };
+  return { version: 4, defaultBrain: null, brains, apiBrains: [], outputFormat: "markdown", memory: { extractFacts: true } };
 }
 function loadConfig() {
   const path = wsConfigPath();
@@ -132,11 +132,14 @@ function loadConfig() {
     const brains = cfg.brains ?? {};
     for (const id of BRAIN_IDS) if (!brains[id]) brains[id] = base.brains[id];
     return {
-      version: 3,
+      version: 4,
       defaultBrain: cfg.defaultBrain ?? null,
       brains,
       apiBrains: Array.isArray(cfg.apiBrains) ? cfg.apiBrains : [],
-      outputFormat: cfg.outputFormat === "html" ? "html" : "markdown"
+      outputFormat: cfg.outputFormat === "html" ? "html" : "markdown",
+      memory: {
+        extractFacts: cfg.memory && typeof cfg.memory.extractFacts === "boolean" ? cfg.memory.extractFacts : true
+      }
     };
   } catch {
     return null;
@@ -228,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}` });
     });
   });
 }
@@ -415,6 +418,9 @@ function memDir() {
 function memPath() {
   return join4(memDir(), "turns.jsonl");
 }
+function factsMdPath() {
+  return join4(memDir(), "facts.md");
+}
 function newSessionId() {
   return randomUUID().slice(0, 8);
 }
@@ -470,12 +476,58 @@ function appendTurn(t) {
 function clearMemory() {
   if (existsSync4(memPath())) rmSync2(memPath());
 }
+function normalizeFact(s) {
+  return s.toLowerCase().replace(/\s+/g, " ").trim().replace(/[.,;:!?]+$/, "");
+}
+var FACTS_HEADER = "# Holt facts\n\nDistilled memories for this folder. Safe to edit by hand.\n";
+async function saveFact(content, session) {
+  const clean = content.trim();
+  if (!clean) return false;
+  const norm2 = normalizeFact(clean);
+  for (const t of loadTurns()) {
+    if (t.role === "fact" && normalizeFact(t.content) === norm2) return false;
+  }
+  if (existsSync4(factsMdPath())) {
+    for (const line of readFileSync4(factsMdPath(), "utf8").split("\n")) {
+      const l = line.trim();
+      if (!l.startsWith("- ")) continue;
+      if (normalizeFact(l.slice(2)) === norm2) return false;
+    }
+  }
+  mkdirSync4(memDir(), { recursive: true });
+  const today = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
+  let existing = existsSync4(factsMdPath()) ? readFileSync4(factsMdPath(), "utf8") : "";
+  if (!existing) existing = FACTS_HEADER;
+  const headings = existing.match(/^## (\d{4}-\d{2}-\d{2})/gm);
+  const lastHeading = headings && headings.length ? headings[headings.length - 1] : null;
+  const needsHeading = lastHeading !== `## ${today}`;
+  let addition = "";
+  if (needsHeading) {
+    if (!existing.endsWith("\n")) addition += "\n";
+    addition += `
+## ${today}
+`;
+  }
+  addition += `- ${clean}
+`;
+  writeFileSync4(factsMdPath(), existing + addition, "utf8");
+  appendTurn({
+    id: randomUUID().slice(0, 8),
+    ts: Date.now(),
+    session,
+    role: "fact",
+    content: clean,
+    emb: await embed(clean) ?? void 0
+  });
+  return true;
+}
 function memStats() {
   const turns = loadTurns();
   const sessions = new Set(turns.map((t) => t.session)).size;
   const withEmbeddings = turns.filter((t) => Array.isArray(t.emb)).length;
+  const facts = turns.filter((t) => t.role === "fact").length;
   const bytes = existsSync4(memPath()) ? statSync(memPath()).size : 0;
-  return { turns: turns.length, sessions, withEmbeddings, bytes };
+  return { turns: turns.length, facts, sessions, withEmbeddings, bytes };
 }
 function cosine(a, b) {
   let dot = 0;
@@ -503,6 +555,7 @@ function keywordScore(q, text) {
   for (const w of q) if (t.has(w)) hit++;
   return hit / q.size;
 }
+var FACT_BOOST = 1.15;
 async function recall(query, currentSession, k = 4) {
   const past = loadTurns().filter((t) => t.session !== currentSession);
   if (past.length === 0) return [];
@@ -513,7 +566,10 @@ async function recall(query, currentSession, k = 4) {
     let score = 0;
     if (qEmb && Array.isArray(turn.emb)) score = cosine(qEmb, turn.emb);
     else score = keywordScore(qTok, turn.content);
-    if (score > (qEmb && Array.isArray(turn.emb) ? 0.35 : 0.15)) scored.push({ turn, score });
+    if (score > (qEmb && Array.isArray(turn.emb) ? 0.35 : 0.15)) {
+      if (turn.role === "fact") score *= FACT_BOOST;
+      scored.push({ turn, score });
+    }
   }
   scored.sort((a, b) => b.score - a.score);
   return scored.slice(0, k);
@@ -709,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(
@@ -975,6 +1031,115 @@ async function runApiBrain(brain, prompt, onChunk) {
   return { ok: false, text: `${brain.provider} returned an empty reply.` };
 }
 
+// src/facts.ts
+var MIN_EXCHANGES_FOR_EXTRACTION = 3;
+var MAX_TRANSCRIPT_TURNS = 20;
+var MAX_TURN_CHARS = 1e3;
+function buildExtractionPrompt(history) {
+  const recent = history.slice(-MAX_TRANSCRIPT_TURNS);
+  const transcript = recent.map((t) => `${t.role === "user" ? "USER" : "ASSISTANT"}: ${t.content.slice(0, MAX_TURN_CHARS)}`).join("\n\n");
+  const lines = [
+    "Given this conversation, extract 1 to 5 durable facts worth remembering long-term.",
+    "Output ONLY a JSON array of strings, no prose, no code fences.",
+    "",
+    "Rules:",
+    "- Keep decisions, outcomes, stable preferences, key names, dates, and numbers.",
+    "- Skip pleasantries, one-off questions, and generic advice.",
+    "- Make each fact self-contained so it reads on its own in a future session.",
+    "- If nothing is worth saving, output exactly []",
+    "",
+    "Good examples:",
+    '- "User decided to target the Netherlands as the primary job market, HSM visa route."',
+    '- "HDFC EMI is 17,394 rupees per month with 29 payments remaining as of March 2026."',
+    "",
+    "Bad examples (do NOT output these):",
+    '- "User asked a question about their finances."',
+    '- "The assistant gave some helpful advice."',
+    "",
+    "Conversation:",
+    transcript,
+    "",
+    "JSON array:"
+  ];
+  return lines.join("\n");
+}
+function firstBalancedArray(s) {
+  const start = s.indexOf("[");
+  if (start < 0) return null;
+  let depth = 0;
+  let inStr = false;
+  let esc = false;
+  for (let i = start; i < s.length; i++) {
+    const ch = s[i];
+    if (inStr) {
+      if (esc) esc = false;
+      else if (ch === "\\") esc = true;
+      else if (ch === '"') inStr = false;
+      continue;
+    }
+    if (ch === '"') inStr = true;
+    else if (ch === "[") depth++;
+    else if (ch === "]") {
+      depth--;
+      if (depth === 0) {
+        const slice = s.slice(start, i + 1);
+        try {
+          const parsed = JSON.parse(slice);
+          return Array.isArray(parsed) ? parsed : null;
+        } catch {
+          return null;
+        }
+      }
+    }
+  }
+  return null;
+}
+function norm(s) {
+  return s.toLowerCase().replace(/\s+/g, " ").trim().replace(/[.,;:!?]+$/, "");
+}
+function parseFacts(raw) {
+  let s = (raw || "").trim();
+  s = s.replace(/^```(?:json)?\s*/i, "").replace(/```\s*$/i, "").trim();
+  const m = s.match(/\[[\s\S]*\]/);
+  if (!m) return [];
+  let arr = null;
+  try {
+    arr = JSON.parse(m[0]);
+  } catch {
+    arr = firstBalancedArray(s);
+  }
+  if (!Array.isArray(arr)) return [];
+  const seen = /* @__PURE__ */ new Set();
+  const out = [];
+  for (const item of arr) {
+    if (typeof item !== "string") continue;
+    const v = String(item).trim();
+    if (v.length <= 10) continue;
+    const key = norm(v);
+    if (seen.has(key)) continue;
+    seen.add(key);
+    out.push(v);
+    if (out.length >= 5) break;
+  }
+  return out;
+}
+async function extractAndSaveFacts(active, cfg, history, session) {
+  try {
+    if (Math.floor(history.length / 2) < MIN_EXCHANGES_FOR_EXTRACTION) return 0;
+    const prompt = buildExtractionPrompt(history);
+    const res = active.kind === "cli" ? await runBrain(cfg.brains[active.id], prompt) : await runApiBrain(active.brain, prompt);
+    if (!res.ok) return 0;
+    const facts = parseFacts(res.text);
+    let saved = 0;
+    for (const f of facts) {
+      if (await saveFact(f, session)) saved++;
+    }
+    return saved;
+  } catch {
+    return 0;
+  }
+}
+
 // src/output.ts
 import { writeFileSync as writeFileSync5 } from "fs";
 import { join as join5 } from "path";
@@ -1301,7 +1466,7 @@ async function chat() {
   const stats = memStats();
   console.log("\n" + c.accent("Holt") + c.dim(`  brain: ${active.label}`));
   console.log(c.dim(
-    `Memory: ${stats.turns} moments from ${stats.sessions} session${stats.sessions === 1 ? "" : "s"} in this folder (recall: ${embedOk ? "embeddings via local Ollama" : "keyword match"}).`
+    `Memory: ${stats.turns} moments (${stats.facts} facts) from ${stats.sessions} session${stats.sessions === 1 ? "" : "s"} in this folder (recall: ${embedOk ? "embeddings via local Ollama" : "keyword match"}).`
   ));
   if (embedOk && stats.withEmbeddings < stats.turns) {
     console.log(c.dim(`  ${stats.turns - stats.withEmbeddings} older moments lack embeddings. Run "holt memory embed" to upgrade them.`));
@@ -1343,7 +1508,7 @@ async function chat() {
           else for (const h of hits) console.log(c.dim(`  ${h.score.toFixed(2)}  (${h.turn.role}) ${h.turn.content.slice(0, 110).replace(/\s+/g, " ")}`));
         } else {
           const s = memStats();
-          console.log(c.dim(`  ${s.turns} moments, ${s.sessions} sessions, ${s.withEmbeddings} embedded, ${(s.bytes / 1024).toFixed(1)} KB in ./.holt/memory/`));
+          console.log(c.dim(`  ${s.turns} moments, ${s.facts} facts, ${s.sessions} sessions, ${s.withEmbeddings} embedded, ${(s.bytes / 1024).toFixed(1)} KB in ./.holt/memory/`));
           console.log(c.dim('  usage: /memory <query> to preview recall, or "holt memory clear" to wipe.'));
         }
         continue;
@@ -1451,6 +1616,14 @@ async function chat() {
       console.log(c.red("\n  " + res.text + "\n"));
     }
   }
+  if (cfg.memory?.extractFacts !== false) {
+    try {
+      const arg = active.kind === "cli" ? { kind: "cli", id: active.id } : { kind: "api", brain: active.brain };
+      const n = await extractAndSaveFacts(arg, cfg, history, session);
+      if (n > 0) console.log(c.dim(`  distilled ${n} fact${n === 1 ? "" : "s"} from this session.`));
+    } catch {
+    }
+  }
   close();
   console.log(c.dim("\nBye.\n"));
 }
@@ -1472,6 +1645,7 @@ async function login(which) {
 }
 
 // src/commands/memory.ts
+import { existsSync as existsSync6, readFileSync as readFileSync6 } from "fs";
 async function memoryCmd(sub, rest = []) {
   const { ask, close } = createReader();
   if (!await ensureTrusted(ask)) {
@@ -1505,7 +1679,7 @@ async function memoryCmd(sub, rest = []) {
     }
     const missing = loadTurns().filter((t) => !Array.isArray(t.emb)).length;
     if (missing === 0) {
-      console.log(c.dim("\n  All moments already have embeddings.\n"));
+      console.log(c.dim("\n  All memories already have embeddings.\n"));
       close();
       return;
     }
@@ -1513,7 +1687,18 @@ async function memoryCmd(sub, rest = []) {
     const r = await backfillEmbeddings((done, total) => {
       process.stdout.write(`\r  embedding ${done}/${total}...`);
     });
-    console.log("\n" + c.green(`  Done. ${r.embedded} of ${r.total} moments embedded.`) + "\n");
+    console.log("\n" + c.green(`  Done. ${r.embedded} of ${r.total} memories embedded.`) + "\n");
+    close();
+    return;
+  }
+  if (action === "facts") {
+    if (!existsSync6(factsMdPath())) {
+      console.log(c.dim("\n  No facts distilled yet. They form when you end a chat session.\n"));
+      close();
+      return;
+    }
+    const body = readFileSync6(factsMdPath(), "utf8").trim();
+    console.log("\n" + body + "\n");
     close();
     return;
   }
@@ -1540,6 +1725,7 @@ async function memoryCmd(sub, rest = []) {
   const sessions = new Set(loadTurns().map((t) => t.session)).size;
   console.log("\n" + c.accent("Holt memory") + c.dim("  (this folder)"));
   console.log(`  moments     ${s.turns}`);
+  console.log(`  facts       ${s.facts}  (./.holt/memory/facts.md)`);
   console.log(`  sessions    ${sessions}`);
   console.log(`  embedded    ${s.withEmbeddings} of ${s.turns}`);
   console.log(`  size        ${(s.bytes / 1024).toFixed(1)} KB  (./.holt/memory/turns.jsonl)`);
@@ -1549,7 +1735,8 @@ async function memoryCmd(sub, rest = []) {
   ${s.turns - s.withEmbeddings} moments lack embeddings. Run "holt memory embed" to upgrade them to semantic recall.`));
   }
   console.log(c.dim("\n  holt memory search <query>   find remembered moments"));
-  console.log(c.dim("  holt memory embed            embed older moments for semantic recall"));
+  console.log(c.dim("  holt memory facts            show distilled facts (facts.md)"));
+  console.log(c.dim("  holt memory embed            embed older memories for semantic recall"));
   console.log(c.dim("  holt memory clear            wipe this folder's memory\n"));
   close();
 }
@@ -1558,8 +1745,8 @@ async function memoryCmd(sub, rest = []) {
 import {
   mkdirSync as mkdirSync5,
   writeFileSync as writeFileSync6,
-  readFileSync as readFileSync6,
-  existsSync as existsSync6,
+  readFileSync as readFileSync7,
+  existsSync as existsSync7,
   readdirSync as readdirSync2,
   statSync as statSync3,
   rmSync as rmSync3,
@@ -1612,7 +1799,7 @@ function isGitUrl(s) {
   return s.includes("://") || s.endsWith(".git") || s.startsWith("git@");
 }
 function findSkillDir(root) {
-  if (existsSync6(join7(root, "SKILL.md"))) return root;
+  if (existsSync7(join7(root, "SKILL.md"))) return root;
   let subs = [];
   try {
     subs = readdirSync2(root).filter((f) => {
@@ -1625,7 +1812,7 @@ function findSkillDir(root) {
   } catch {
     return null;
   }
-  const withSkill = subs.filter((f) => existsSync6(join7(root, f, "SKILL.md")));
+  const withSkill = subs.filter((f) => existsSync7(join7(root, f, "SKILL.md")));
   if (withSkill.length === 1) return join7(root, withSkill[0]);
   return null;
 }
@@ -1678,7 +1865,7 @@ function cmdCreate(name, global) {
   }
   const scope = global ? "global" : "workspace";
   const dir = join7(skillsRoot(scope), clean);
-  if (existsSync6(dir)) {
+  if (existsSync7(dir)) {
     console.log(c.red(`
   A ${scope} skill named "${clean}" already exists.`));
     console.log(c.dim("  " + dir + "\n"));
@@ -1712,7 +1899,7 @@ function cmdAdd(source, global) {
       fetched = tempDir;
     } else {
       fetched = resolve(source);
-      if (!existsSync6(fetched)) {
+      if (!existsSync7(fetched)) {
         console.log(c.red(`
   No such path: ${fetched}
 `));
@@ -1726,7 +1913,7 @@ function cmdAdd(source, global) {
     }
     let skillName = "";
     try {
-      const { data } = parseFrontmatter(readFileSync6(join7(skillDir, "SKILL.md"), "utf8"));
+      const { data } = parseFrontmatter(readFileSync7(join7(skillDir, "SKILL.md"), "utf8"));
       skillName = sanitizeName(data.name || "");
     } catch {
       skillName = "";
@@ -1737,7 +1924,7 @@ function cmdAdd(source, global) {
       return;
     }
     const dest = join7(skillsRoot(scope), skillName);
-    if (existsSync6(dest)) {
+    if (existsSync7(dest)) {
       console.log(c.red(`
   A ${scope} skill named "${skillName}" already exists.`));
       console.log(c.dim("  " + dest + "\n"));
@@ -1746,12 +1933,12 @@ function cmdAdd(source, global) {
     mkdirSync5(skillsRoot(scope), { recursive: true });
     cpSync(skillDir, dest, { recursive: true });
     const nestedGit = join7(dest, ".git");
-    if (existsSync6(nestedGit)) rmSync3(nestedGit, { recursive: true, force: true });
+    if (existsSync7(nestedGit)) rmSync3(nestedGit, { recursive: true, force: true });
     console.log(c.green(`
   Installed ${scope} skill "${skillName}".`));
     console.log(c.dim("  " + join7(dest, "SKILL.md") + "\n"));
   } finally {
-    if (tempDir && existsSync6(tempDir)) {
+    if (tempDir && existsSync7(tempDir)) {
       try {
         rmSync3(tempDir, { recursive: true, force: true });
       } catch {
@@ -1767,7 +1954,7 @@ async function cmdRemove(name, ask) {
   }
   const wsDir = join7(skillsRoot("workspace"), clean);
   const globalDir = join7(skillsRoot("global"), clean);
-  const target = existsSync6(wsDir) ? wsDir : existsSync6(globalDir) ? globalDir : "";
+  const target = existsSync7(wsDir) ? wsDir : existsSync7(globalDir) ? globalDir : "";
   if (!target) {
     console.log(c.dim(`
   No skill named "${clean}" found.
@@ -2505,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.5.2";
+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
@@ -2525,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
@@ -2574,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.5.2",
+  "version": "0.7.0",
   "description": "An open-source personal agent OS: any LLM, private memory you can see and walk.",
   "type": "module",
   "license": "MIT",