@holt-os/holt 0.18.1 → 0.19.2

package/README.md

@@ -179,6 +179,12 @@ Turns saved before semantic memory was enabled are upgraded in one pass with `ho
 
 Long conversations stay cheap: only recent turns are replayed verbatim, older context comes back through recall.
 
+### How recall works, and how well
+
+Each message is matched against your past sessions by meaning (local embeddings) and by exact words (BM25), so names, numbers and rare terms are not lost. Holt takes the best 32 matches, adds the message next to each one in short form, groups them by session, dates every session and orders them oldest first. Your own statements get a slight edge, because that is where facts about you live. The whole block stays inside a fixed budget of about 6,000 tokens. Tune it with `HOLT_RECALL_K`, `HOLT_RECALL_BUDGET`, `HOLT_RECALL_NEIGHBORS`, `HOLT_RECALL_NEIGHBOR_CAP` and `HOLT_RECALL_USER_BOOST`.
+
+On the public long-term memory benchmarks, Holt 0.19 scores 91.2% on LongMemEval (graded by GPT-4o), 88.2% on LoCoMo and 79.6% on BEAM at one million tokens. Every question, answer and grade, plus the code to rerun it, is in [holt-os/holt-benchmarks](https://github.com/holt-os/holt-benchmarks).
+
 ### Optional global memory (`holt memory global`)
 
 By default every folder's memory is **isolated**: recall never crosses folders. If you want a folder to draw on what you learned elsewhere, opt it into a shared store:
@@ -641,4 +647,6 @@ Holt is built to be extended without touching the core. See [`CONTRIBUTING.md`](
 
 ## License
 
-[MIT](./LICENSE) © Debashis Nayak
+[MIT](./LICENSE) © [Debashis Nayak](https://productsdecoded.com/about)
+
+Built by [Debashis Nayak](https://productsdecoded.com/about).

package/dist/cli.js

@@ -361,17 +361,21 @@ function isInstalled(command) {
 function renderPrompt(history, message, memory = []) {
   const recent = history.slice(-MAX_REPLAY_TURNS);
   const parts = [];
-  if (recent.length || memory.length) {
+  const memText = typeof memory === "string" ? memory.trim() : "";
+  const memRows = typeof memory === "string" ? [] : memory;
+  if (recent.length || memText || memRows.length) {
     parts.push(
       "You are the user's assistant, running through Holt, a tool that gives you durable memory of this user across sessions. Notes recalled from their past sessions may appear below; use them naturally and answer as their assistant.",
       "You are continuing an ongoing conversation. Use the context below and reply only as the assistant to the final User message."
     );
   }
-  if (memory.length) {
+  if (memText) {
+    parts.push("", memText);
+  } else if (memRows.length) {
     parts.push(
       "",
       "Relevant notes from this user's earlier sessions:",
-      ...memory.map((m) => `- (${m.turn.role}) ${m.turn.content.slice(0, 500)}`)
+      ...memRows.map((m) => `- (${m.turn.role}) ${m.turn.content.slice(0, 500)}`)
     );
   }
   if (recent.length) {
@@ -920,6 +924,142 @@ async function backfillEmbeddings(onProgress) {
   writeFileSync4(memPath(), turns.map((t) => JSON.stringify(t)).join("\n") + "\n", "utf8");
   return { embedded, total: missing.length };
 }
+var envNum = (name, dflt) => {
+  const v = Number(process.env[name]);
+  return Number.isFinite(v) && v > 0 ? v : dflt;
+};
+function bm25Scores(query, docs) {
+  const toks = docs.map((d) => (d || "").toLowerCase().split(/[^a-z0-9]+/).filter((w) => w.length > 2));
+  const N = toks.length || 1;
+  const avg = toks.reduce((a, t) => a + t.length, 0) / N || 1;
+  const df = /* @__PURE__ */ new Map();
+  for (const t of toks) for (const w of new Set(t)) if (query.has(w)) df.set(w, (df.get(w) || 0) + 1);
+  const k1 = 1.2;
+  const b = 0.75;
+  return toks.map((t) => {
+    if (!t.length) return 0;
+    const tf = /* @__PURE__ */ new Map();
+    for (const w of t) if (query.has(w)) tf.set(w, (tf.get(w) || 0) + 1);
+    let s = 0;
+    for (const [w, f] of tf) {
+      const n = df.get(w) || 0;
+      const idf = Math.log(1 + (N - n + 0.5) / (n + 0.5));
+      s += idf * f * (k1 + 1) / (f + k1 * (1 - b + b * t.length / avg));
+    }
+    return s;
+  });
+}
+async function recallContext(query, currentSession, opts = {}) {
+  const k = opts.k ?? envNum("HOLT_RECALL_K", 32);
+  const nb = opts.neighbors ?? envNum("HOLT_RECALL_NEIGHBORS", 1);
+  const budget = opts.budget ?? envNum("HOLT_RECALL_BUDGET", 24e3);
+  const rowCap = opts.rowCap ?? envNum("HOLT_RECALL_ROWCAP", 2e3);
+  const neighborCap = opts.neighborCap ?? envNum("HOLT_RECALL_NEIGHBOR_CAP", 250);
+  const userBoost = opts.userBoost ?? envNum("HOLT_RECALL_USER_BOOST", 1.15);
+  const all = loadTurns();
+  try {
+    const ws = workspace();
+    if (isGlobalEnabled(ws)) {
+      for (const g of loadGlobalFacts()) {
+        if (g.workspace === ws) continue;
+        all.push({ id: g.id, ts: g.ts, session: `global:${g.workspace}`, role: g.role, content: g.content, emb: g.emb });
+      }
+    }
+  } catch {
+  }
+  const at = (i) => all[i];
+  const pastIdx = [];
+  all.forEach((t, i) => {
+    if (t.session !== currentSession) pastIdx.push(i);
+  });
+  if (!pastIdx.length) return { blocks: [], hits: 0, chars: 0 };
+  const qEmb = await embed(query);
+  const qTok = tokens(query);
+  const bm = bm25Scores(qTok, pastIdx.map((i) => at(i).content));
+  const bmMax = Math.max(0, ...bm) || 1;
+  const scored = [];
+  pastIdx.forEach((i, j) => {
+    const t = at(i);
+    const cos = qEmb && Array.isArray(t.emb) ? cosine(qEmb, t.emb) : 0;
+    const kw = (bm[j] ?? 0) / bmMax;
+    let s = qEmb ? 0.75 * cos + 0.25 * kw : kw;
+    if (s <= (qEmb ? 0.3 : 0.1)) return;
+    if (t.role === "fact") s *= FACT_BOOST;
+    else if (t.role === "user") s *= userBoost;
+    scored.push({ i, s });
+  });
+  scored.sort((a, b) => b.s - a.s);
+  const top = scored.slice(0, k);
+  if (!top.length) return { blocks: [], hits: 0, chars: 0 };
+  const pick = /* @__PURE__ */ new Map();
+  for (const { i } of top) {
+    pick.set(i, true);
+    for (let d = 1; d <= nb; d++) {
+      for (const j of [i - d, i + d]) {
+        const t = all[j];
+        if (t && t.session === at(i).session && t.session !== currentSession && !pick.has(j)) pick.set(j, false);
+      }
+    }
+  }
+  const rank = new Map(top.map(({ i }, r) => [i, r]));
+  const order = [...pick.keys()].sort((a, b) => {
+    const ra = rank.get(a) ?? Infinity;
+    const rb = rank.get(b) ?? Infinity;
+    if (ra !== rb) return ra - rb;
+    return a - b;
+  });
+  const kept = /* @__PURE__ */ new Set();
+  let chars = 0;
+  const capOf = (i) => pick.get(i) ? rowCap : neighborCap;
+  for (const i of order) {
+    const len = Math.min(at(i).content.length, capOf(i));
+    if (chars + len > budget && kept.size) continue;
+    kept.add(i);
+    chars += len;
+  }
+  const bySession = /* @__PURE__ */ new Map();
+  for (const i of [...kept].sort((a, b) => a - b)) {
+    const s = at(i).session;
+    if (!bySession.has(s)) bySession.set(s, []);
+    bySession.get(s).push(i);
+  }
+  const blocks = [...bySession.entries()].map(([session, idx]) => ({
+    session,
+    ts: Math.min(...idx.map((i) => at(i).ts)),
+    rows: idx.map((i) => ({
+      role: at(i).role,
+      content: at(i).content.length > capOf(i) ? at(i).content.slice(0, capOf(i)) + " \u2026" : at(i).content,
+      ts: at(i).ts,
+      hit: !!pick.get(i)
+    }))
+  }));
+  blocks.sort((a, b) => a.ts - b.ts);
+  return { blocks, hits: top.length, chars };
+}
+var isoDay = (ts) => {
+  try {
+    return new Date(ts).toISOString().slice(0, 10);
+  } catch {
+    return "unknown date";
+  }
+};
+function formatMemoryContext(ctx, now = /* @__PURE__ */ new Date()) {
+  if (!ctx.blocks.length) return "";
+  const today = typeof now === "string" ? now : isoDay(now.getTime());
+  const out = [
+    `Today is ${today}. Notes from this user's earlier sessions follow, oldest first, each with its date.`,
+    "If notes disagree, the most recent one is current. Work out dates and durations from the session dates.",
+    "To count or total something, first list every matching item across all sessions, then answer. If the notes do not cover it, say so."
+  ];
+  for (const b of ctx.blocks) {
+    out.push("", `### Session on ${isoDay(b.ts)}`);
+    for (const r of b.rows) {
+      const who = r.role === "user" ? "User" : r.role === "assistant" ? "Assistant" : "Fact";
+      out.push(`${who}: ${r.content.trim()}`);
+    }
+  }
+  return out.join("\n");
+}
 
 // src/telegram.ts
 import { readFileSync as readFileSync5, writeFileSync as writeFileSync5, existsSync as existsSync5, mkdirSync as mkdirSync5 } from "fs";
@@ -1351,7 +1491,7 @@ async function runTask(task, opts = {}) {
       };
     }
     const runSession = "run-" + newSessionId();
-    const recalled = opts.recall !== false ? await recall(task, runSession, 4) : [];
+    const recalled = opts.recall !== false ? formatMemoryContext(await recallContext(task, runSession)) : "";
     const block = skillsPromptBlock();
     const base = renderPrompt([], task, recalled);
     const prompt = block ? block + "\n\n" + base : base;
@@ -2913,8 +3053,8 @@ function buildExtractionPrompt(history) {
     "- 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."',
+    '- "User decided to move the team wiki from Notion to Obsidian by the end of Q3."',
+    '- "Car loan payment is 420 euros per month with 18 payments remaining as of March 2026."',
     "",
     "Bad examples (do NOT output these):",
     '- "User asked a question about their finances."',
@@ -3802,20 +3942,19 @@ async function inject() {
       return;
     }
     const session = data.session_id || newSessionId();
-    const hits = await recall(prompt, session, 4);
-    if (!hits.length) {
+    const ctx = await recallContext(prompt, session, { budget: Number(process.env.HOLT_RECALL_BUDGET) || 8e3 });
+    if (!ctx.hits) {
       dlog("inject -> recalled 0 notes");
       return;
     }
-    const lines = hits.map((h) => `- ${h.turn.content.replace(/\s+/g, " ").trim().slice(0, 500)}`);
     process.stdout.write(
       [
-        "Background on this user, recalled from earlier sessions (use it directly, do not mention looking it up):",
-        ...lines,
+        "Background on this user, recalled from earlier sessions (use it directly, do not mention looking it up).",
+        formatMemoryContext(ctx),
         ""
       ].join("\n")
     );
-    dlog(`inject -> injected ${hits.length} note(s)`);
+    dlog(`inject -> injected ${ctx.hits} note(s), ${ctx.chars} chars`);
   } catch (e) {
     process.stderr.write("holt hook inject: " + (e instanceof Error ? e.message : String(e)) + "\n");
     dlog("inject -> error: " + (e instanceof Error ? e.message : String(e)));
@@ -4557,8 +4696,9 @@ async function chat() {
         }
       }
     }
-    const remembered = await recall(line, session, 4);
-    const label = remembered.length ? `Holt is thinking (recalled ${remembered.length} moment${remembered.length === 1 ? "" : "s"})...` : `Holt is thinking...`;
+    const recalledCtx = await recallContext(line, session);
+    const remembered = formatMemoryContext(recalledCtx);
+    const label = recalledCtx.hits ? `Holt is thinking (recalled ${recalledCtx.hits} moment${recalledCtx.hits === 1 ? "" : "s"})...` : `Holt is thinking...`;
     console.log(c.dim(`  ${label}`) + "\n");
     const skillsBlock = skillsPromptBlock();
     const base = renderPrompt(history, line, remembered);
@@ -7547,7 +7687,7 @@ function holtTools() {
 }
 
 // src/version.ts
-var VERSION = "0.18.1";
+var VERSION = "0.19.2";
 
 // src/commands/mcp.ts
 function printSetup() {

package/package.json

@@ -1,10 +1,13 @@
 {
   "name": "@holt-os/holt",
-  "version": "0.18.1",
+  "version": "0.19.2",
   "description": "An open-source personal agent OS: any LLM, private memory you can see and walk.",
   "type": "module",
   "license": "MIT",
-  "author": "Debashis Nayak",
+  "author": {
+    "name": "Debashis Nayak",
+    "url": "https://productsdecoded.com/about"
+  },
   "homepage": "https://productsdecoded.com/holt",
   "repository": {
     "type": "git",
@@ -44,7 +47,7 @@
     "build": "tsup src/cli.ts --format esm --clean",
     "start": "node dist/cli.js",
     "typecheck": "tsc --noEmit",
-    "test": "tsx scripts/specs.test.ts && tsx scripts/skillcompiler.test.ts && tsx scripts/scheduler.test.ts && tsx scripts/statusline.test.ts",
+    "test": "tsx scripts/memory.test.ts && tsx scripts/specs.test.ts && tsx scripts/skillcompiler.test.ts && tsx scripts/scheduler.test.ts && tsx scripts/statusline.test.ts",
     "release": "bash scripts/release.sh"
   },
   "devDependencies": {

package/skills/onboard/SKILL.md

@@ -83,7 +83,7 @@ holt memory add "<one durable fact>"
 One fact per call. Several facts can be piped in at once, one per line.
 
 Write facts that will still be true in a month and that a future session could
-not guess. "Runs product for a fintech in Bhubaneswar, nine years in" is a fact.
+not guess. "Runs design for a logistics startup in Lisbon, six years in" is a fact.
 "Wants to be more productive" is noise. Include names, numbers, and dates. Write
 the fact so it stands alone, because recall will surface it without this
 conversation around it.
@@ -120,6 +120,6 @@ things genuinely in flight this week?"
 Then, quietly, between questions:
 
 ```
-holt memory add "Senior product manager, nine years, currently between roles and job-hunting in the Netherlands"
-holt memory add "Runs Sasyam Agro with an uncle in Bargarh; demo plots are on the uncle's land"
+holt memory add "Product designer, six years, leading the checkout redesign at a logistics startup"
+holt memory add "Runs a weekend pottery studio with a cousin; classes are on Saturday mornings"
 ```