@inetafrica/open-claudia 2.6.36 → 2.6.37

package/CHANGELOG.md

@@ -1,5 +1,8 @@
 # Changelog
 
+## v2.6.37
+- **`/recall [on|off]` — watch recall work.** A per-chat debug toggle that, when on, posts a short `🧠 Recall this turn` line just before each reply listing the packs/entities that surfaced — and on the **discoverer** engine, the one-line why-bullet for each. On a gated turn (pre-gate skipped recall) it says so; on a quiet turn with no matches it stays silent. The engines now return a `why` map + `gated` flag, `promptWithDynamicContext` captures a recall summary into the per-turn `consumeLastInjected()` buffer, and `runner.js` renders it when `settings.showRecall` is set. Off by default; flip with `/recall` (buttons) or `/recall on`.
+
 ## v2.6.36
 - **Docs: document the dual-engine recall feature.** v2.6.34/v2.6.35 shipped the pluggable recall engine and `/engine` switch but the README and `.env.example` were never updated. This release fills the gap: README gains a "Pluggable recall" Features bullet, the `/engine` command row, a "Recall engines" narrative section, the `recall-stats` / `recall graph` CLI commands, and env-table rows for `RECALL_ENGINE` / `RECALL_GRAPH_DB` / `RECALL_METRICS` / `DREAM_TIER` (plus the corrected `DREAM_MODEL` default). `.env.example` gains `RECALL_ENGINE` and `DREAM_TIER`. Docs-only — no code changes.
 

package/README.md

@@ -189,6 +189,7 @@ When you select a project, the last conversation is automatically resumed. Tap "
 | `/learn [<hint>]` | Capture the last piece of work into the matching context pack |
 | `/skills [show\|remove <name>]` | List, show, or remove legacy learned skills |
 | `/engine [classic\|discoverer]` | Switch the per-chat memory recall engine (default `classic`) |
+| `/recall [on\|off]` | Toggle a per-turn "🧠 Recall this turn" debug line showing which packs/entities surfaced (and why, on discoverer) |
 | `/soul` | View/edit assistant identity and personality |
 | `/dreamsummary [on\|off]` | Toggle the post-dream memory summary in chat |
 
@@ -264,7 +265,7 @@ Open Claudia layers three memory systems on top of the backend's native sessions
 
 **Entity memory** (`~/.open-claudia/entities/<slug>.md`) works the same way for the people, places, projects, orgs, and systems you mention — who they are, current truth, and a dated observation log. Mentioning a name injects its note.
 
-**Recall engines** — how packs and entities get matched and surfaced is pluggable per chat via `/engine` (or the `RECALL_ENGINE` env default). **classic** (the default) is keyword FTS plus a relevance judge with headline injection — stable and unchanged. **discoverer** (opt-in) adds a typed-edge graph over the same corpus (`parent`/`governed-by`/`related` edges with weights in `recall-graph.db`) and runs: a pre-gate that skips recall on trivial turns → FTS seeding → spreading activation across the graph (1–2 hops — auto-pulls cross-cutting concerns the query never named) → a walker that reads each candidate and returns the genuinely-relevant set with one-line why-bullets (fail-open to keyword seeds, so it never recalls worse than classic). Edges form structurally from pack `parent` frontmatter and `[[links]]`, and strengthen via Hebbian co-use when the agent opens packs together (📖); weights decay over time. Inspect with `open-claudia recall-stats` and `open-claudia recall graph [--sync]`. Switch back any time with `/engine classic`.
+**Recall engines** — how packs and entities get matched and surfaced is pluggable per chat via `/engine` (or the `RECALL_ENGINE` env default). **classic** (the default) is keyword FTS plus a relevance judge with headline injection — stable and unchanged. **discoverer** (opt-in) adds a typed-edge graph over the same corpus (`parent`/`governed-by`/`related` edges with weights in `recall-graph.db`) and runs: a pre-gate that skips recall on trivial turns → FTS seeding → spreading activation across the graph (1–2 hops — auto-pulls cross-cutting concerns the query never named) → a walker that reads each candidate and returns the genuinely-relevant set with one-line why-bullets (fail-open to keyword seeds, so it never recalls worse than classic). Edges form structurally from pack `parent` frontmatter and `[[links]]`, and strengthen via Hebbian co-use when the agent opens packs together (📖); weights decay over time. Inspect with `open-claudia recall-stats` and `open-claudia recall graph [--sync]`, or flip on `/recall` to watch — per turn — which packs/entities surfaced and why, right in the chat. Switch back any time with `/engine classic`.
 
 **Dream consolidation** — while the per-turn reviewer takes quick notes, *dream* is the slow overnight pass (default 4am, on a high-tier model — opus by default, set `DREAM_TIER` or `DREAM_MODEL`): it merges packs that drifted into the same topic, builds parent/sub pack trees with umbrella summaries, tightens descriptions and tags so the router matches with less noise, dedupes entities, cross-links notes, and tends the recall graph (structural sync, weight decay, orphan prune). Anything merged away is backed up under `~/.open-claudia/backup/dream-<stamp>/` first, and every dream that changes something reports in chat. Configure with `DREAM_CRON` / `DREAM_MODEL`, disable with `DREAM=off`.
 

package/core/actions.js

@@ -282,6 +282,12 @@ async function handleAction(envelope) {
     await send(`Recall engine: ${state.settings.recallEngine || "classic (default)"}`);
     return;
   }
+  if (d.startsWith("rcl:")) {
+    state.settings.showRecall = d.slice(4) === "on";
+    saveState();
+    await send(`Recall debug: ${state.settings.showRecall ? "on" : "off"}`);
+    return;
+  }
   if (d.startsWith("cw:")) {
     const v = d.slice(3);
     if (v === "default") state.settings.compactWindow = null;

package/core/handlers.js

@@ -122,7 +122,7 @@ register({
     if (!authorized(env)) return;
     send([
       "Session: /session /sessions /projects /continue /status /stop /end",
-      "Settings: /model /effort /budget /plan /compact /compactwindow /worktree /mode /engine",
+      "Settings: /model /effort /budget /plan /compact /compactwindow /worktree /mode /engine /recall",
       "Identity: /whoami /link",
       "Team: /people /intros /auth (owner)",
       "Automation: /cron /vault /soul /dreamsummary",
@@ -719,6 +719,29 @@ register({
   },
 });
 
+register({
+  name: "recall", description: "Show what memory recall surfaced each turn (debug)", args: "[on|off]",
+  handler: async (env, { tail }) => {
+    if (!authorized(env)) return;
+    const { settings } = currentState();
+    if (tail) {
+      const v = tail.trim().toLowerCase();
+      if (v === "on" || v === "true") settings.showRecall = true;
+      else if (v === "off" || v === "false") settings.showRecall = false;
+      else return send(`Usage: /recall [on|off]. Currently ${settings.showRecall ? "on" : "off"}.`);
+      saveState();
+      return send(`Recall debug: ${settings.showRecall ? "on" : "off"}`);
+    }
+    send(
+      `Recall debug: ${settings.showRecall ? "on" : "off"}\n\n` +
+      "When on, I post a short \"🧠 Recall this turn\" line before each reply, showing which packs/entities surfaced (and, on the discoverer engine, why). Lets you watch recall work.",
+      { keyboard: { inline_keyboard: [
+        [{ text: "On", callback_data: "rcl:on" }, { text: "Off", callback_data: "rcl:off" }],
+      ] } },
+    );
+  },
+});
+
 register({
   name: "budget", description: "Set max spend for next task", args: "[$N]",
   handler: async (env, { tail }) => {

package/core/recall/discoverer.js

@@ -145,7 +145,7 @@ async function run(ctx) {
   // 1: pre-gate.
   if (!needsRecall(userText, seedCount)) {
     metrics.logTurn({ engine: "discoverer", query: userText, gated: true, latencyMs: Date.now() - started });
-    return { packBlock: "", entityBlock: "", packMatches: [], entityMatches: [] };
+    return { packBlock: "", entityBlock: "", packMatches: [], entityMatches: [], why: {}, gated: true };
   }
 
   // 3: spreading activation from seeds across the graph.
@@ -225,7 +225,10 @@ async function run(ctx) {
     latencyMs: Date.now() - started,
   });
 
-  return { packBlock, entityBlock, packMatches: finalPacks, entityMatches: finalEnts };
+  return {
+    packBlock, entityBlock, packMatches: finalPacks, entityMatches: finalEnts,
+    why: whyById ? Object.fromEntries(whyById) : {}, gated: false,
+  };
 }
 
 module.exports = { name: "discoverer", run, needsRecall, walk };

package/core/runner.js

@@ -881,7 +881,17 @@ async function runClaude(prompt, cwd, replyToMsgId, opts = {}) {
   // `open-claudia pack show <dir>` / `entity show <slug>` — so the banner
   // reflects what was read, not what was pushed. (consumeLastInjected is
   // drained here to keep the per-turn buffer from leaking into the next turn.)
-  try { require("./system-prompt").consumeLastInjected(); } catch (e) { /* best-effort */ }
+  try {
+    const injected = require("./system-prompt").consumeLastInjected();
+    if (settings.showRecall && injected && injected.recall) {
+      const r = injected.recall;
+      const esc = (s) => String(s).replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+      const fmt = (arr, icon) => arr.map((x) => (x.why ? `${icon} <b>${esc(x.name)}</b> — ${esc(x.why)}` : `${icon} <b>${esc(x.name)}</b>`));
+      const lines = [...fmt(r.packs || [], "📦"), ...fmt(r.entities || [], "👤")];
+      if (lines.length) send(`🧠 <b>Recall this turn</b> (${esc(r.engine)})\n${lines.join("\n")}`).catch(() => {});
+      else if (r.gated) send(`🧠 <b>Recall</b> (${esc(r.engine)}): skipped by pre-gate — trivial turn.`).catch(() => {});
+    }
+  } catch (e) { /* best-effort */ }
   const binaryPath = getActiveBinary();
   const proc = spawn(binaryPath, args, {
     cwd,

package/core/system-prompt.js

@@ -349,10 +349,10 @@ function tryUseRecallBudget(budget, text) {
 // What the last promptWithDynamicContext call freshly injected (not the
 // deduped repeats) — consumed by the runner to announce recalls in chat,
 // mirroring the write-side announcements.
-let lastInjected = { packs: [], entities: [] };
+let lastInjected = { packs: [], entities: [], recall: null };
 function consumeLastInjected() {
   const out = lastInjected;
-  lastInjected = { packs: [], entities: [] };
+  lastInjected = { packs: [], entities: [], recall: null };
   return out;
 }
 
@@ -613,7 +613,7 @@ function bumpFtsMissCounter(n) {
 }
 
 async function promptWithDynamicContext(prompt, opts = {}) {
-  lastInjected = { packs: [], entities: [] };
+  lastInjected = { packs: [], entities: [], recall: null };
   try {
     const { userText, contextText } = recallMatchParts(prompt);
     let historyText = "";
@@ -633,9 +633,17 @@ async function promptWithDynamicContext(prompt, opts = {}) {
       packsLib, entitiesLib, mergeMatches, filterMatches, logRecall,
       buildPackBlock, buildEntityBlock,
     };
-    const { packBlock, entityBlock } = await engine.run({
+    const result = await engine.run({
       userText, contextText, fullContext, packLimit, budget, helpers,
     });
+    const { packBlock, entityBlock } = result;
+    const why = result.why || {};
+    lastInjected.recall = {
+      engine: engine.name || recall.activeEngineName(settings),
+      gated: !!result.gated,
+      packs: (result.packMatches || []).map((m) => ({ name: m.name || m.dir, why: why[`pack:${m.dir}`] || "" })),
+      entities: (result.entityMatches || []).map((m) => ({ name: m.name || m.slug, why: why[`entity:${m.slug}`] || "" })),
+    };
     const budgetNote = budget.omitted > 0
       ? `\n\n## Memory budget\n${budget.omitted} matched memory item${budget.omitted === 1 ? " was" : "s were"} omitted to keep this turn under the recall budget (${budget.maxChars} chars). Use \`open-claudia pack show <dir>\`, \`entity show <slug>\`, or transcript search if deeper context is needed.`
       : "";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inetafrica/open-claudia",
-  "version": "2.6.36",
+  "version": "2.6.37",
   "description": "Your always-on AI coding assistant — Claude Code, Cursor Agent, and OpenAI Codex via Telegram or Kazee Chat",
   "main": "bot.js",
   "bin": {

package/test-recall-discoverer.js

@@ -59,6 +59,7 @@ const helpers = { packsLib, entitiesLib, mergeMatches, buildPackBlock, buildEnti
   });
   assert.strictEqual(gated.packBlock, "");
   assert.strictEqual(gated.packMatches.length, 0);
+  assert.strictEqual(gated.gated, true, "gated turn flags gated:true");
   assert.strictEqual(builtPacks, null, "gated turn never builds blocks");
 
   // seeded turn: FTS hits kazee-mobile → fail-open keeps it, block rendered
@@ -69,6 +70,8 @@ const helpers = { packsLib, entitiesLib, mergeMatches, buildPackBlock, buildEnti
   assert.strictEqual(out.packBlock, "PACKBLOCK");
   assert.strictEqual(out.packMatches.length, 1);
   assert.strictEqual(out.packMatches[0].dir, "kazee-mobile");
+  assert.strictEqual(out.gated, false, "seeded turn is not gated");
+  assert.strictEqual(typeof out.why, "object", "seeded turn returns a why map");
   assert.ok(builtPacks && builtPacks.some((m) => m.dir === "kazee-mobile"), "seed reached the builder");
 
   // resilient: a throwing matcher must not blow up the engine