@holt-os/holt 0.2.0 → 0.3.0

package/README.md

@@ -6,7 +6,7 @@ Holt is an open-source, self-hosted personal agent OS. Clone it, pick your skill
 
 > A *holt* is a small wood: a sheltered place where things are kept and grow. That's the idea. A private home for your knowledge that compounds over time.
 
-> **Status: early but usable.** `holt init` and `holt chat` work today. A "brain" is an agent CLI (Claude Code, Codex, or Gemini). Holt can install a missing one for you and hand off to its sign-in, and you can switch brains mid-conversation without losing context. Memory, skills, and the knowledge graph are the next phases.
+> **Status: early but usable, and it remembers now.** `holt init`, `holt chat`, and persistent memory work today. A "brain" is an agent CLI (Claude Code, Codex, or Gemini). Holt can install a missing one for you and hand off to its sign-in, you can switch brains mid-conversation without losing context, and every session adds to a private memory in that folder that future sessions recall from. Skills and the knowledge graph view are the next phases.
 
 ---
 
@@ -46,14 +46,34 @@ Inside `holt chat`:
 ```
 /brain            list your brains and see which is active
 /brain gemini     switch brain. your conversation context is kept
+/memory           memory stats. /memory <query> previews what recall would surface
 /setting          configure brains and your launch command
-/clear            forget the conversation so far
+/clear            forget this session (saved memory stays)
 /help             show commands
 /exit             leave
 ```
 
 The point of `/brain`: Holt owns the transcript, so you can start a thread on one model and hand it to another mid-conversation. The new brain picks up with the full context.
 
+## Memory
+
+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.
+
+Two recall modes, picked automatically:
+
+- **Semantic** (best): if a local [Ollama](https://ollama.com) is running with an embedding model (`ollama pull nomic-embed-text`), recall matches by meaning. Asking "who owns my apartment" finds "my landlord is called Pieter". No API keys, nothing leaves your machine.
+- **Keyword** (fallback): with no Ollama, recall matches by word overlap. Still useful, zero setup.
+
+Inspect it any time:
+
+```bash
+holt memory                    # stats for this folder
+holt memory search <query>     # find remembered moments
+holt memory clear              # wipe this folder's memory
+```
+
+Long conversations stay cheap: only recent turns are replayed verbatim, older context comes back through recall.
+
 ## Brains
 
 A brain is an agent CLI installed and logged in on your machine. No API keys to paste.
@@ -70,7 +90,8 @@ A brain is an agent CLI installed and logged in on your machine. No API keys to
 
 ```
 holt init            set up (trust, brains, sign-in, defaults) for this folder
-holt chat            start a session
+holt chat            start a session that remembers past ones
+holt memory          inspect memory: holt memory [search <query> | clear]
 holt setting         configure brains and launch command
 holt login <brain>   sign in to claude, codex, or gemini
 holt version         print version
@@ -90,7 +111,7 @@ Small strongly-typed **TypeScript core** (command dispatch, brain router, transc
 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**: sqlite-vec store, local or cloud embeddings, recall across sessions
+1. **Memory**: per-folder store, semantic recall via local embeddings with keyword fallback, streaming replies *(shipped)*
 2. **Any LLM directly**: raw provider brains and an HTML or Markdown output toggle
 3. **Skills**: install, search, and publish in the agentskills.io format
 4. **Knowledge graph**: a view where you can see and navigate your own memory

package/dist/cli.js

@@ -130,25 +130,35 @@ function saveConfig(cfg) {
 
 // src/brains.ts
 import { spawn, spawnSync } from "child_process";
+var MAX_REPLAY_TURNS = 12;
 function isInstalled(command) {
   const finder = process.platform === "win32" ? "where" : "which";
   const res = spawnSync(finder, [command], { stdio: "ignore" });
   return res.status === 0;
 }
-function renderPrompt(history, message) {
-  if (history.length === 0) return message;
-  const lines = history.map((t) => `${t.role === "user" ? "User" : "Assistant"}: ${t.content}`);
-  lines.push(`User: ${message}`);
-  return [
-    "You are continuing an ongoing conversation. Below is the transcript so far.",
-    "Read it for context and reply only as the assistant to the final User message.",
-    "",
-    lines.join("\n\n"),
-    "",
-    "Assistant:"
-  ].join("\n");
-}
-function runBrain(brain, prompt) {
+function renderPrompt(history, message, memory = []) {
+  const recent = history.slice(-MAX_REPLAY_TURNS);
+  const parts = [];
+  if (recent.length || memory.length) {
+    parts.push(
+      "You are continuing an ongoing conversation. Use the context below and reply only as the assistant to the final User message."
+    );
+  }
+  if (memory.length) {
+    parts.push(
+      "",
+      "Relevant notes from this user's earlier sessions:",
+      ...memory.map((m) => `- (${m.turn.role}) ${m.turn.content.slice(0, 500)}`)
+    );
+  }
+  if (recent.length) {
+    parts.push("", "Transcript so far:", ...recent.map((t) => `${t.role === "user" ? "User" : "Assistant"}: ${t.content}`));
+  }
+  if (parts.length === 0) return message;
+  parts.push("", `User: ${message}`, "", "Assistant:");
+  return parts.join("\n");
+}
+function runBrain(brain, prompt, onChunk) {
   return new Promise((resolve) => {
     let child;
     try {
@@ -160,7 +170,9 @@ function runBrain(brain, prompt) {
     let out = "";
     let err = "";
     child.stdout.on("data", (d) => {
-      out += d.toString();
+      const s = d.toString();
+      out += s;
+      if (onChunk) onChunk(s);
     });
     child.stderr.on("data", (d) => {
       err += d.toString();
@@ -310,6 +322,122 @@ Default brain? [${chosen.join("/")}] (${defPick}): `) ?? "").trim();
   else console.log(c.dim('No brain is ready yet. Install one, then run "holt init" again.\n'));
 }
 
+// src/commands/chat.ts
+import { randomUUID as randomUUID2 } from "crypto";
+
+// src/memory.ts
+import { appendFileSync, readFileSync as readFileSync4, existsSync as existsSync4, mkdirSync as mkdirSync2, rmSync, statSync } from "fs";
+import { join as join3 } from "path";
+import { randomUUID } from "crypto";
+var OLLAMA_URL = process.env.HOLT_OLLAMA_URL || "http://127.0.0.1:11434";
+var EMBED_MODEL = process.env.HOLT_EMBED_MODEL || "nomic-embed-text";
+function memDir() {
+  return join3(wsHoltDir(), "memory");
+}
+function memPath() {
+  return join3(memDir(), "turns.jsonl");
+}
+function newSessionId() {
+  return randomUUID().slice(0, 8);
+}
+var embedProbe = null;
+async function embeddingsAvailable() {
+  if (embedProbe !== null) return embedProbe;
+  try {
+    const res = await fetch(`${OLLAMA_URL}/api/tags`, { signal: AbortSignal.timeout(1200) });
+    if (!res.ok) return embedProbe = false;
+    const data = await res.json();
+    embedProbe = !!data.models?.some((m) => (m.name || "").startsWith(EMBED_MODEL));
+  } catch {
+    embedProbe = false;
+  }
+  return embedProbe;
+}
+async function embed(text) {
+  if (!await embeddingsAvailable()) return null;
+  try {
+    const res = await fetch(`${OLLAMA_URL}/api/embeddings`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ model: EMBED_MODEL, prompt: text.slice(0, 4e3) }),
+      signal: AbortSignal.timeout(1e4)
+    });
+    if (!res.ok) return null;
+    const data = await res.json();
+    if (!Array.isArray(data.embedding)) return null;
+    return data.embedding.map((x) => Math.round(x * 1e4) / 1e4);
+  } catch {
+    return null;
+  }
+}
+function loadTurns() {
+  if (!existsSync4(memPath())) return [];
+  const out = [];
+  for (const line of readFileSync4(memPath(), "utf8").split("\n")) {
+    if (!line.trim()) continue;
+    try {
+      out.push(JSON.parse(line));
+    } catch {
+    }
+  }
+  return out;
+}
+function appendTurn(t) {
+  mkdirSync2(memDir(), { recursive: true });
+  appendFileSync(memPath(), JSON.stringify(t) + "\n", "utf8");
+}
+function clearMemory() {
+  if (existsSync4(memPath())) rmSync(memPath());
+}
+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 bytes = existsSync4(memPath()) ? statSync(memPath()).size : 0;
+  return { turns: turns.length, sessions, withEmbeddings, bytes };
+}
+function cosine(a, b) {
+  let dot = 0;
+  let na = 0;
+  let nb = 0;
+  const n = Math.min(a.length, b.length);
+  for (let i = 0; i < n; i++) {
+    const x = a[i];
+    const y = b[i];
+    dot += x * y;
+    na += x * x;
+    nb += y * y;
+  }
+  return na && nb ? dot / (Math.sqrt(na) * Math.sqrt(nb)) : 0;
+}
+function tokens(s) {
+  return new Set(
+    s.toLowerCase().split(/[^a-z0-9]+/).filter((w) => w.length > 2)
+  );
+}
+function keywordScore(q, text) {
+  if (q.size === 0) return 0;
+  const t = tokens(text);
+  let hit = 0;
+  for (const w of q) if (t.has(w)) hit++;
+  return hit / q.size;
+}
+async function recall(query, currentSession, k = 4) {
+  const past = loadTurns().filter((t) => t.session !== currentSession);
+  if (past.length === 0) return [];
+  const qEmb = await embed(query);
+  const qTok = tokens(query);
+  const scored = [];
+  for (const turn of past) {
+    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 });
+  }
+  scored.sort((a, b) => b.score - a.score);
+  return scored.slice(0, k);
+}
+
 // src/commands/setting.ts
 function printStatus(cfg) {
   console.log("\n" + c.accent("Holt settings") + c.dim("  (this folder)"));
@@ -387,11 +515,12 @@ async function setting() {
 function help() {
   console.log(c.dim([
     "  commands:",
-    "    /brain [name]   switch brain (claude, codex, gemini). context is kept.",
-    "    /setting        configure brains and your launch command",
-    "    /clear          forget the conversation so far",
-    "    /help           this list",
-    "    /exit           leave"
+    "    /brain [name]     switch brain (claude, codex, gemini). context is kept.",
+    "    /memory [query]   memory stats, or preview what a query would recall",
+    "    /setting          configure brains and your launch command",
+    "    /clear            forget this session so far (saved memory stays)",
+    "    /help             this list",
+    "    /exit             leave"
   ].join("\n")));
 }
 async function chat() {
@@ -413,9 +542,15 @@ async function chat() {
     return;
   }
   let current = cfg.defaultBrain;
+  const session = newSessionId();
   const history = [];
+  const embedOk = await embeddingsAvailable();
+  const stats = memStats();
   console.log("\n" + c.accent("Holt") + c.dim(`  brain: ${cfg.brains[current].label}`));
-  console.log(c.dim("Type a message. Commands: /brain  /setting  /clear  /help  /exit\n"));
+  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"}).`
+  ));
+  console.log(c.dim("Type a message. Commands: /brain  /memory  /setting  /clear  /help  /exit\n"));
   while (true) {
     const raw = await ask(c.accent("\u203A "));
     if (raw === null) break;
@@ -424,6 +559,7 @@ async function chat() {
     if (line.startsWith("/")) {
       const parts = line.slice(1).split(/\s+/);
       const cmd = (parts[0] || "").toLowerCase();
+      const rest = parts.slice(1).join(" ");
       const arg = (parts[1] || "").toLowerCase();
       if (cmd === "exit" || cmd === "quit" || cmd === "q") break;
       if (cmd === "help" || cmd === "h") {
@@ -432,7 +568,19 @@ async function chat() {
       }
       if (cmd === "clear") {
         history.length = 0;
-        console.log(c.dim("  context cleared."));
+        console.log(c.dim("  session context cleared. Saved memory is untouched."));
+        continue;
+      }
+      if (cmd === "memory" || cmd === "mem") {
+        if (rest) {
+          const hits = await recall(rest, session, 5);
+          if (hits.length === 0) console.log(c.dim("  nothing relevant in memory for that."));
+          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('  usage: /memory <query> to preview recall, or "holt memory clear" to wipe.'));
+        }
         continue;
       }
       if (cmd === "setting" || cmd === "settings") {
@@ -463,12 +611,23 @@ async function chat() {
       console.log(c.red(`  ${brain.label} (${brain.command}) is not on your PATH. Use /brain to switch or /setting.`));
       continue;
     }
-    console.log(c.dim(`  ${brain.label} is thinking...`));
-    const res = await runBrain(brain, renderPrompt(history, line));
+    const remembered = await recall(line, session, 4);
+    const label = remembered.length ? `${brain.label} is thinking (recalled ${remembered.length} moment${remembered.length === 1 ? "" : "s"})...` : `${brain.label} is thinking...`;
+    console.log(c.dim(`  ${label}`) + "\n");
+    let streamed = false;
+    const res = await runBrain(brain, renderPrompt(history, line, remembered), (chunk) => {
+      streamed = true;
+      process.stdout.write(chunk);
+    });
     if (res.ok) {
+      if (!streamed) console.log(res.text);
+      if (!res.text.endsWith("\n")) console.log("");
+      console.log("");
       history.push({ role: "user", content: line });
       history.push({ role: "assistant", content: res.text });
-      console.log("\n" + res.text + "\n");
+      const now = Date.now();
+      appendTurn({ id: randomUUID2().slice(0, 8), ts: now, session, role: "user", content: line, emb: await embed(line) ?? void 0 });
+      appendTurn({ id: randomUUID2().slice(0, 8), ts: now, session, role: "assistant", content: res.text, emb: await embed(res.text) ?? void 0 });
     } else {
       console.log(c.red("\n  " + res.text + "\n"));
     }
@@ -493,8 +652,64 @@ async function login(which) {
   await runInteractive(s.login[0], s.login.slice(1));
 }
 
+// src/commands/memory.ts
+async function memoryCmd(sub, rest = []) {
+  const { ask, close } = createReader();
+  if (!await ensureTrusted(ask)) {
+    close();
+    return;
+  }
+  const action = (sub || "").toLowerCase();
+  if (action === "clear") {
+    const s2 = memStats();
+    if (s2.turns === 0) {
+      console.log(c.dim("\n  Memory is already empty.\n"));
+      close();
+      return;
+    }
+    const a = (await ask(`
+  Delete all ${s2.turns} remembered moments in this folder? [y/N] `) ?? "").trim().toLowerCase();
+    if (a === "y" || a === "yes") {
+      clearMemory();
+      console.log(c.green("  Memory cleared.\n"));
+    } else console.log(c.dim("  Kept.\n"));
+    close();
+    return;
+  }
+  if (action === "search") {
+    const q = rest.join(" ").trim();
+    if (!q) {
+      console.log(c.dim("\n  Usage: holt memory search <query>\n"));
+      close();
+      return;
+    }
+    const hits = await recall(q, "__none__", 8);
+    console.log("");
+    if (hits.length === 0) console.log(c.dim("  Nothing relevant found."));
+    else for (const h of hits) {
+      const when = new Date(h.turn.ts).toISOString().slice(0, 10);
+      console.log(`  ${c.accent(h.score.toFixed(2))}  ${c.dim(when)}  (${h.turn.role}) ${h.turn.content.slice(0, 100).replace(/\s+/g, " ")}`);
+    }
+    console.log("");
+    close();
+    return;
+  }
+  const s = memStats();
+  const embedOk = await embeddingsAvailable();
+  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(`  sessions    ${sessions}`);
+  console.log(`  embedded    ${s.withEmbeddings} of ${s.turns}`);
+  console.log(`  size        ${(s.bytes / 1024).toFixed(1)} KB  (./.holt/memory/turns.jsonl)`);
+  console.log(`  recall via  ${embedOk ? "embeddings (local Ollama)" : "keyword match (start Ollama with an embed model for semantic recall)"}`);
+  console.log(c.dim("\n  holt memory search <query>   find remembered moments"));
+  console.log(c.dim("  holt memory clear            wipe this folder's memory\n"));
+  close();
+}
+
 // src/cli.ts
-var VERSION = "0.2.0";
+var VERSION = "0.3.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
@@ -509,7 +724,8 @@ Usage: holt <command>
 
 Commands:
   init            Trust this folder, choose and install brains, sign in, set defaults
-  chat            Start a session. Switch brains mid-chat with /brain, context is kept
+  chat            Start a session. It remembers past sessions in this folder
+  memory          Inspect memory: holt memory [search <query> | clear]
   setting         Configure brains and your launch command (per folder)
   login <brain>   Sign in to a brain: claude, codex, or gemini
   version         Print the Holt version
@@ -548,6 +764,9 @@ async function main() {
     case "login":
       await login(process.argv[3]);
       break;
+    case "memory":
+      await memoryCmd(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.2.0",
+  "version": "0.3.0",
   "description": "An open-source personal agent OS: any LLM, private memory you can see and walk.",
   "type": "module",
   "license": "MIT",