@holt-os/holt 0.5.2 → 0.6.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
@@ -155,7 +158,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;
@@ -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);
@@ -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.
@@ -2506,7 +2693,7 @@ async function graph(args = []) {
 }
 
 // src/cli.ts
-var VERSION = "0.5.2";
+var VERSION = "0.6.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

package/package.json

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