@inetafrica/open-claudia 2.6.35 → 2.6.37

package/.env.example

@@ -27,6 +27,10 @@ USAGE_ALERT_BASELINE_TURNS=20
 USAGE_ALERT_MIN_BASELINE_TURNS=6
 USAGE_ALERT_COOLDOWN_MS=1800000
 MEMORY_RECALL_MAX_CHARS=9000
+# Default recall engine when a chat hasn't picked one with /engine: classic | discoverer
+RECALL_ENGINE=classic
+# Dream model tier: low (haiku) | medium (sonnet) | high (opus, default). DREAM_MODEL overrides.
+DREAM_TIER=high
 PROJECT_TRANSCRIPTS=true
 TRANSCRIPT_MAX_ENTRY_CHARS=12000
 TRANSCRIPTS_DIR=

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # 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.
+
 ## v2.6.35
 - **Fix `/status` silently dying + show the active recall engine.** The status handler referenced an undefined `activeCrons`, throwing a ReferenceError that `router.js` swallows by design — so `/status` did nothing. It now counts this channel's crons via `jobs.listForChannel(...)` and adds a `Recall engine:` line so you can confirm which engine (`classic`/`discoverer`) the chat is on. Note: `/engine` already worked when typed; it just may not appear in Telegram's slash-command autocomplete until the client refreshes the cached `setMyCommands` menu.
 

package/README.md

@@ -15,7 +15,8 @@ Send text, voice notes, screenshots, and files from your phone. Your chosen AI a
 ### Memory & long-term context
 - **Context packs** — living per-topic documents (one per project, system, or recurring task) holding Stance, Procedure, State, and Journal. Packs matching your message are auto-injected into the agent's context, and a background reviewer updates them after every substantial turn — the assistant keeps its train of thought across sessions and projects
 - **Entity memory** — short notes on the people, places, projects, orgs, and systems you mention, extracted automatically and injected when they come up again
-- **Dream consolidation** — a nightly pass on a stronger model that merges duplicate packs, builds umbrella/parent pack trees, tightens descriptions, dedupes entities, and reports what it tidied — with everything backed up first
+- **Pluggable recall** — switch per chat with `/engine`: the stable **classic** keyword engine (default) or the opt-in **discoverer**, which walks a typed-edge graph over the same packs/entities and surfaces hits with one-line why-bullets
+- **Dream consolidation** — a nightly pass on a stronger model that merges duplicate packs, builds umbrella/parent pack trees, tightens descriptions, dedupes entities, tends the recall graph, and reports what it tidied — with everything backed up first
 - **Personality** — a persona file gives the assistant a consistent voice on top of your soul file, and the dream pass evolves it gently as you work together
 - **Transcript search** — redacted project transcripts indexed in SQLite FTS5; `open-claudia transcript-search` gives the agent ~50ms ranked recall over months of history
 - **Smart compaction** — long conversations are summarized proactively before they get slow; full briefs are archived to disk so nothing is truly lost (`/compact`, `/compactwindow`)
@@ -177,7 +178,7 @@ When you select a project, the last conversation is automatically resumed. Tap "
 | `/ask` | Toggle ask mode — read-only Q&A, no edits (Cursor Agent only) |
 | `/worktree` | Toggle isolated git branch |
 | `/mode` | Switch between direct and agent bot modes |
-| `/status` | Show current session, backend, and settings |
+| `/status` | Show current session, backend, recall engine, and settings |
 | `/usage` | Token usage and cost for this session |
 | `/doctor` / `/requirements` | Check Node, CLI binaries/versions/auth, voice stack, and writable paths |
 
@@ -187,6 +188,8 @@ 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 |
 
@@ -262,7 +265,9 @@ 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.
 
-**Dream consolidation** — while the per-turn reviewer takes quick notes, *dream* is the slow overnight pass (default 4am, on a stronger 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, and cross-links notes. 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`.
+**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`.
 
 **Personality** — your `soul.md` holds identity and hard rules; `~/.open-claudia/persona.md` holds the voice on top — tone, quirks, emoji habits. It feeds into the system prompt and the dream pass may evolve it gently (bounded, backed up, announced). Edit it directly any time.
 
@@ -272,6 +277,8 @@ Open Claudia layers three memory systems on top of the backend's native sessions
 open-claudia pack list|show <dir>|match "<text>"|migrate|remove <dir>|reindex
 open-claudia entity list|show <slug>|match "<text>"|note <name> "<text>"|remove <slug>|reindex
 open-claudia dream [--dry-run]               # run the consolidation pass now
+open-claudia recall-stats                    # discoverer-engine metrics summary
+open-claudia recall graph [--sync]           # recall-graph node/edge stats; --sync rebuilds structural edges
 open-claudia transcript-search "<query>"     # alias: ts; --all for every project
 open-claudia transcript-window "<pattern>"   # alias: tw; hits with surrounding turns
 ```
@@ -427,6 +434,8 @@ All stored in `~/.open-claudia/`:
 | `USAGE_ALERT_RATE_MULTIPLIER` | No | Alert when the latest context-token rate exceeds the recent baseline by this multiple (default `1.75`, `off` disables) |
 | `USAGE_ALERT_BASELINE_TURNS` / `USAGE_ALERT_MIN_BASELINE_TURNS` / `USAGE_ALERT_COOLDOWN_MS` | No | Tune token-rate baseline size, minimum sample size, and alert cooldown |
 | `MEMORY_RECALL_MAX_CHARS` | No | Hard cap for auto-injected pack/entity memory per turn (default `9000`, `off` disables auto recall injection) |
+| `RECALL_ENGINE` | No | Default recall engine when a chat hasn't set one via `/engine` (`classic` or `discoverer`, default `classic`) |
+| `RECALL_GRAPH_DB` / `RECALL_METRICS` | No | Override the discoverer graph DB path; `off` on metrics disables per-turn recall logging |
 | `PROJECT_TRANSCRIPTS` | No | Enable redacted project transcripts (default `true`) |
 | `TRANSCRIPT_MAX_ENTRY_CHARS` | No | Max chars per transcript entry (default `12000`) |
 | `TRANSCRIPTS_DIR` / `PACKS_DIR` / `ENTITIES_DIR` | No | Override storage directories |
@@ -435,7 +444,8 @@ All stored in `~/.open-claudia/`:
 | `PACK_MATCH_THRESHOLD` / `ENTITY_MATCH_THRESHOLD` | No | Router match score thresholds (default `2`) |
 | `DREAM` | No | `off` disables the nightly memory consolidation pass (default on) |
 | `DREAM_CRON` | No | Schedule for the dream pass (default `0 4 * * *`) |
-| `DREAM_MODEL` | No | Model for the dream pass (default `sonnet`) |
+| `DREAM_MODEL` | No | Explicit model override for the dream pass (otherwise picked from `DREAM_TIER`) |
+| `DREAM_TIER` | No | Model tier for the dream pass: `low` (haiku) / `medium` (sonnet) / `high` (opus, default) |
 | `PERSONA_FILE` | No | Override the persona file location |
 | `WEB_UI` / `WEB_PORT` / `WEB_PASSWORD` | No | Web UI toggle, port, and password |
 | `WHISPER_CLI` / `WHISPER_MODEL` | No | whisper.cpp binary and model for voice notes |

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.35",
+  "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