Files
claude_mac/docs/superpowers/plans/2026-11-04-memory-recall.md
T

26 KiB

Phase 4c Memory Recall Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Bring the right registry entries back to the model at three moments (a design or analysis prompt, a known error, the start of a context) without noise, inside the mods/memory mod and hooks/session-start.sh.

Architecture: One file grows: mods/memory/hooks/register.ts (single-file house style of model-router; the validator has no local-module story we rely on). A shared reader (memory.sh index through $.process.run for statuses, $.fs.read for the three registries) feeds the 4b error index, a BM25 + haiku intent recall at prompt.submit, and a known-error line on failing Bash results; a per-context ledger and a per-turn budget bound both channels; every injection is logged in the store. The digest is a bash block at the end of the session-start banner.

Tech Stack: TypeScript Claude Code mod (engine 2.1.316 types, claude plugin test kit), bash (session-start.sh, lib/reconcile.sh, lib/memory.sh), bun for the proof harness.

Spec: docs/superpowers/specs/2026-11-04-memory-recall-design.md (approved 2026-11-04). Contract: .claude/tasks/contracts/2026-11-04-memory-recall-1859.md (answers 0-11 [gated]). Spike: .claude/tasks/plans/2026-11-04-memory-recall-spike/REPORT.md.

Global Constraints

  • Every hook fails open: .catch → next(e) (or the 4b memory_pending failure answer), one log line per hook per session through warnOnce; a failing read, model call or process run attaches nothing and changes nothing.
  • The mod never writes a registry and never calls a write verb of lib/memory.sh; the only process it runs is bash <HOME>/.claude/lib/memory.sh -C <root> index.
  • Model id claude-haiku-5-5 (full id, LRN-203); every $.model.complete and $.process.run is raced by an own timer (LRN-218): haiku 3000 ms, memory.sh 2500 ms.
  • Regexes over prompt, tool or registry text are bounded (no nested unbounded quantifier, no \s* crossing a newline under /m) and timed on 64 KiB inputs under 50 ms each (LRN-219, LRN-259).
  • Test oracles are literal strings; nothing an oracle compares is computed by the code under test (LRN-237). Secret-shaped fixtures are built at runtime by concatenation (BLK-041).
  • register.ts: every line ≤ 80 columns; functions ≤ 25 logic lines and ≤ 5 locals where reasonable; no global mutable state (closure State only).
  • Injection text: <ID> <title ≤ 100> — <lesson>; lesson = first sentence of the kind's field, ≤ 280 chars with …; block ≤ 1500 chars; at most 3 entries per recall.
  • Keyword patterns copied verbatim from mods/model-router/hooks/register.ts default prompt rules at commit 9bbd1d5 (name the commit in a comment).
  • Tests: make test suite=lib/tests/mods.test.sh while iterating; the full make test once before each commit that touches shell. Never touch settings.json (dirty on purpose) or ~/.claude/memory.json.
  • Commits: one per task, message given in the task, only the task's files.

Review Focus

  1. A BDR whose Decision field is 2 000 chars → the lesson is cut at 280 with …, and three such hits stay ≤ 1500 chars (Task 3, test RB3).
  2. $.process.run rejects, hangs, or exits non-zero (no bash, a broken HOME) → recall and the error channel inject nothing, memory_pending still answers with index: status reader unavailable (Task 1, tests SR3-SR5).
  3. A pasted 64 KiB log as the prompt → the query is cut to 2000 chars before tokenizing and BM25 over the real-size corpus stays fast (Task 3, test RB5).
  4. Design words in every prompt of a long session → already injected IDs never come back in that context; with no candidate left, no haiku call is made (Task 4, tests IR7-IR8).
  5. The same known error 20 times in a context → one injection (Task 5, test TE4).

Task 0: Preflight (controller)

  • git branch --show-current → feature/memory-recall; make test suite=lib/tests/mods.test.sh green at fb6cbf1; grep -c "test(" mods/memory/hooks/register.test.ts noted; ls lib/tests/*.test.sh | head and the Makefile test target read to learn how a new shell suite is picked up. Drift → re-plan.

Task 1: Shared reader (statuses from memory.sh, entries with lessons)

Files: Modify mods/memory/hooks/register.ts (index block ~386-523, loadIndex, formatPending callers), mods/memory/hooks/register.test.ts.

Interfaces:

  • Produces:

    • export type Kind = 'BDR' | 'LRN' | 'BLK'
    • export type Entry = { id: string; kind: Kind; title: string; lesson: string; body: string }
    • export function entriesOf(text: string): Entry[] — heading regex /^## ((BDR|LRN|BLK)-\d+)\b[ \t]*[—-]?[ \t]*([^\n]{0,300})$/gm; title = the heading text after the ID with a trailing [tag] and (date) removed, cut at 100 with …; body from heading to next heading (heading included).
    • export function lessonOf(kind: Kind, body: string): string — label order BDR Decision; LRN Apply, Future application, Pattern; BLK Solution, Real cause; line shape ^[ \t]*-[ \t]*(\*\*)?<Label>(\*\*)?[ \t]*:[ \t]*(.{0,2000})$ (case-insensitive label, /m, bounded); first sentence = up to the first . / ; followed by a capital or end, else the whole field; cut at 280 with …; '' when no label.
    • export function parseIndex(stdout: string): Map<string, string> — rows | ID | Date | Title | Status | → ID → lowercased first word of Status ('' when empty).
    • export function isLive(status: Map<string, string>, id: string): boolean — false when the word is superseded or deprecated, true otherwise (an ID absent from the map is live).
    • async function statusMap($: Api, root: string): Promise<Map<string, string> | undefined> — $.env.get('HOME'), then $.process.run(['bash', ${home}/.claude/lib/memory.sh, '-C', root, 'index'], { timeoutMs: 2000 }) raced by a 2500 ms timer; undefined on timeout, rejection, missing HOME or exitCode !== 0.
    • type Registries = { entries: Entry[]; status: Map<string, string> | undefined; index: Map<string, string>; note: string }
    • async function loadRegistries($: Api, root: string): Promise<Registries> replaces loadIndex: reads decisions.md, learnings.md, blockers.md with the 4b tryRead; index = buildIndex(entries.filter(BLK|LRN), status); note = the 4b index: line (now naming three files) plus ; status reader unavailable when status is undefined.
    • export function buildIndex(entries: Entry[], status: Map<string, string> | undefined): Map<string, string> — status === undefined → empty map (nothing is known without statuses); else the 4b span/gram rule over live entries.
  • Removed: isSuperseded, STATUS, the shortcut: comment above it; the TODO.md line harvesting it is ticked in Task 7.

  • Consumed by: pendingAnswer, newFailureCount (switch to loadRegistries).

  • Step 1: tests (literal oracles)

    • SR1 parseIndex on a literal 4-line stdout (.claude/memory/decisions.md, header, separator, | BDR-031 | 2026-06-25 | t | superseded |, | LRN-001 | 2026-01-01 | t | |) → BDR-031→superseded, LRN-001→''.
    • SR2 a test-side on('process.run', …) answering that stdout with exit 0 → memory_pending lists a failure matching a BLK span as known BLK-…, and an entry marked superseded in the stdout is not indexed (its matching failure reads NEW).
    • SR3 process.run throws → the answer holds status reader unavailable and the failure reads NEW; SR4 exit code 2 → same; SR5 process.run never settles → the answer arrives (clock advanced 2500 ms) with status reader unavailable.
    • LS1-LS4 lessonOf: BDR - **Decision**: Use X. Then Y. → Use X.; LRN with Pattern and Apply → the Apply text; BLK - Solution: fix z → fix z; a 2 000-char field → 280 chars ending ….
    • EN1 entriesOf on ## BDR-007 — Title here [accepted] (2026-01-02) → title Title here; a ## Notes heading is not an entry.
    • Update IDX tests whose oracle assumed the lexical superseded reader or the 2-file index: line, each to a literal new expectation; list them in the report.
    • TIMEentries entriesOf + lessonOf on a 64 KiB registry of one entry with a 64 KiB field → < 50 ms.
  • Step 2: run make test suite=lib/tests/mods.test.sh → new tests FAIL.

  • Step 3: implement; remove isSuperseded/STATUS/shortcut:.

  • Step 4: suite green; awk 'length($0) > 80' mods/memory/hooks/register.ts | wc -l → 0.

  • Step 5: commit feat(memory): status reader through memory.sh, entries with lessons.

Task 2: Errno phrases out of the error index

Files: register.ts (grams, PLACEHOLDERS), register.test.ts.

Interfaces:

  • Produces: export const ERRNO_PHRASES: readonly string[] (the 18 phrases of spec Unit 3, lowercase); export function deErrno(normLine: string): string — each phrase (word-bounded, after normalize) → <errno>; grams calls deErrno first; PLACEHOLDERS gains <errno>.

  • Consumed by: buildIndex, matchOf (unchanged signatures).

  • Step 1: tests

    • ER1 entry span `cat: x: No such file or directory (os error 2)` and failure line ls: cannot access '/tmp/zz': No such file or directory → NEW (the LRN-056 collision, reproduced on a fixture).
    • ER2 entry span `fatal: unable to access remote host thing` and the same failure line text → known (content grams still match).
    • ER3 deErrno('cat: <path>: no such file or directory (os error #)') → 'cat: <path>: <errno> (os error #)'.
    • ER4 grams of '<errno> <path> # <hex>' → [].
    • TIMEerrno deErrno on 64 KiB of no such file or repeats → < 50 ms.
  • Step 2: FAIL. Step 3: implement. Step 4: green, width 0.

  • Step 5: commit fix(memory): errno phrases never make an error known.

Task 3: BM25 ranking, rerank prompt, answer parse, recall block (pure)

Files: register.ts (new block after the index block), register.test.ts.

Interfaces:

  • Produces:
    • export function tokensOf(text: string): string[] — lowercase, [\p{L}\p{N}]{2,40} runs (bounded), minus STOP_WORDS (a const of ≤ 60 FR+EN function words: the, and, for, with, that, this, from, les, des, une, pour, dans, avec, est, pas, que, qui, sur, …).
    • export function bm25Rank(entries: Entry[], query: string, k: number): Entry[] — query = cap(query, 2000); document = title + lesson + body; k1 1.2, b 0.75, idf ln(1 + (N - df + 0.5) / (df + 0.5)); entries with score > 0, highest first, ties by ID order, at most k.
    • export function rerankPrompt(query: string, cands: Entry[]): string — exactly: Prompt: <redact(cap(query, 2000))>\nCandidates:\n<ID> | <title> | <lesson> (one line per candidate)\nAnswer with at most 3 candidate IDs that would help with this prompt, comma separated, or none.
    • export function parseIds(text: string, cands: Entry[], max: number): string[] — /(?:BDR|LRN|BLK)-\d{1,5}/g matches, kept when a candidate ID, deduplicated, order kept, at most max.
    • export function recallLine(e: Entry): string — ${e.id} ${e.title} — ${e.lesson} (no — when the lesson is empty).
    • export function recallBlock(lines: string[], cap: number): string — memory recall: + \n + lines; a line that would make the block exceed cap is dropped; '' when no line fits.
  • Step 1: tests
    • RB1 three fixture entries; query quoting heredoc shell → the heredoc entry first (literal ID order oracle).
    • RB2 parseIds('BLK-041, BDR-999, LRN-258', cands, 3) with cands BLK-041, LRN-258 → ['BLK-041', 'LRN-258']; parseIds('none', …) → [].
    • RB3 three BDR entries with 2 000-char Decision fields → each line's lesson ends …, recallBlock(…, 1500).length <= 1500, literal first line.
    • RB4 rerankPrompt on two candidates → the literal expected string.
    • RB5 bm25Rank over 500 synthetic entries of 1 600 chars and a 64 KiB query → < 300 ms (and the query really cut: a token beyond char 2000 does not change the order).
    • RB6 a query with a token built at runtime as a secret shape ('sk_live_' + 'a'.repeat(24)) → rerankPrompt holds <redacted:stripe>.
  • Step 2: FAIL. Step 3: implement. Step 4: green, width 0.
  • Step 5: commit feat(memory): bm25 ranking and the rerank prompt.

Task 4: Intent recall at prompt.submit (trigger, haiku, ledger, budget, log, switch)

Files: register.ts (State, newState, loadEnabled, registerSession, registerPrompt, store Project type), register.test.ts.

Interfaces:

  • State gains: recall: boolean | null (the "recall" key, read with enabled), seen: Map<string, Set<string>> (context key → injected IDs), spent: Map<string, number> (context key → chars injected this turn / this context), fresh: Set<string> (session ids whose next qualifying prompt is a context start), lastPrompt: Map<string, number> (session id → time of the last composer prompt).
  • loadEnabled returns { enabled: boolean; recall: boolean }; "recall": false → recall off; a non-boolean recall logs one line (memory: ~/.claude/memory.json has no boolean "recall", recall stays on) and counts as absent. ensureEnabled keeps its boolean contract; add ensureRecall($, st): Promise<boolean>.
  • export const DESIGN_RULE, export const ANALYSIS_RULE — the two router patterns (commit 9bbd1d5), flags iu.
  • export function isTrigger(text: string, fresh: boolean, idleMs: number): boolean — !text.startsWith('/'), ≥ 12 code points, and (fresh or idleMs >= 1800000 or a rule matches).
  • export const IDLE_MS = 1800000, export const RECALL_CAP = 1500, export const HAIKU = 'claude-haiku-5-5', export const RERANK_MS = 3000.
  • function contextKey(session: string, agent: string | undefined): string → ${session}:${agent ?? 'main'}.
  • export function onContextStart(st: State, session: string): void — deletes every seen/spent key starting ${session}:, adds session to fresh. Called from session.start and from a new classic.SessionStart hook when source is startup, clear or compact (resume → nothing).
  • async function recallFor($: Api, st: State, at: Where, text: string): Promise<string> — loads registries; status === undefined → ''; candidates = bm25Rank(entries filtered by isLive and not in seen[key], text, 30); none → '' without a model call; $.model.complete({ model: HAIKU, prompt: rerankPrompt(text, cands), effort: 'low', maxTokens: 64, timeoutMs: RERANK_MS }) raced by RERANK_MS; not answered / timeout / throw → ''; ids → lines → recallBlock(lines, RECALL_CAP - spent); records ids in seen, chars in spent, and a log record.
  • Project store gains log?: { at: number; session: string; agent: string; channel: 'prompt' | 'tool'; ids: string[] }[], kept ≤ 200 (oldest dropped) through the 4b write chain (queueWrite + loadProject/saveProject); asProject keeps a valid log array and drops malformed records.
  • registerPrompt: on a composer, non-mid-turn prompt with a non-empty root: (1) the 4b note as today; (2) when ensureRecall and isTrigger(text, fresh.has(session), now - lastPrompt): clear fresh for the session, reset the main key's spent, append the recall block when non-empty; (3) lastPrompt.set(session, now) on every composer prompt. Both contexts go in one next({ ...e, context: [...(e.context ?? []), note?, block?] }). session.end also clears seen, spent, fresh, lastPrompt, recall.
  • Step 1: tests (a bottom on('model.complete', …) recording asks, on('process.run', …) answering a fixture index, mock.clock)
    • IR1 first composer prompt of a session on va concevoir la suite du mod (no keyword) → one ask; context holds the literal block memory recall:\nBLK-001 ….
    • IR2 a second ordinary prompt 1 min later without keyword → no ask, no block.
    • IR3 31 min later an ordinary prompt → an ask.
    • IR4 /feat add x → no ask; a mid-turn prompt (turnId set) → no ask; origin sdk → no ask; 11-char prompt → no ask.
    • IR5 the model answers BDR-999, BLK-001 (BDR-999 not a candidate) → only BLK-001 injected; answers none → no block; never settles → no block after RERANK_MS (clock advanced) and the prompt passes; isAnswered: false → no block.
    • IR6 classic.SessionStart compact (fired with $.classic.SessionStart({ source: 'compact' }) in the test) → the next ordinary prompt asks again and BLK-001 may come back; resume → no reset.
    • IR7 design keyword in three prompts in a row → BLK-001 injected once only (later asks never list it as a candidate).
    • IR8 every candidate already seen → no ask at all.
    • IR9 "recall": false in the switch file → no ask, the 4b note still attached after a milestone; "recall": "no" → recall on + one log line.
    • IR10 process.run fails → no ask, prompt unchanged.
    • IR11 after an injection, loadProject holds one log record {channel: 'prompt', ids: ['BLK-001']}; 205 injections → 200 records kept.
    • IR12 a milestone pending and a trigger on the same prompt → context [note, block] in that order.
    • TIMErules both rules on 64 KiB of letters → < 50 ms.
  • Step 2: FAIL. Step 3: implement. Step 4: green, width 0.
  • Step 5: commit feat(memory): intent recall at the prompt, once per context.

Task 5: Known-error line on failing Bash results

Files: register.ts (captureFailure returns the built failure, registerBash), register.test.ts.

Interfaces:

  • captureFailure returns Promise<Failure | undefined> (the failure it built, stored or not).
  • async function knownLine($: Api, st: State, at: Where, f: Failure, agent: string | undefined): Promise<string> — ensureRecall false → ''; registries; status === undefined → ''; id = matchOf(index, f.key); none, or already in seen[key] → ''; entry → memory: known ${recallLine(entry)}; when its length exceeds RECALL_CAP - spent[key] → ''; records seen, spent, and a tool log record.
  • registerBash: after capture, line !== '' → return { ...out, context: [...(out.context ?? []), line] }; else return out (unchanged object).
  • Step 1: tests
    • TE1 a failing command whose line matches a fixture BLK span → the answer keeps isError, text, result and gains context: ['memory: known BLK-002 …'] (literal).
    • TE2 an ENOENT line (the ER1 fixture) → no context key added (answer deep-equal to the tool's).
    • TE3 a sub-agent (agentId: 'a1') failure → injected; the same failure in the main loop → injected too (separate keys).
    • TE4 the same failure 20 times in one context → one injection.
    • TE5 "recall": false → no context, capture still stored.
    • TE6 a matched entry superseded in the status stdout → no injection.
    • TE7 budget: spent at 1450 for the main key and a 200-char line → no injection.
  • Step 2: FAIL. Step 3: implement. Step 4: green, width 0.
  • Step 5: commit feat(memory): known-error line on failing commands.

Task 6: Earlier-session milestones in memory_pending

Files: register.ts (formatPending, milestoneText), register.test.ts.

Interfaces: formatPending lists the current session's milestones under milestones: (header renamed from milestones (this session):), then the earlier sessions' (newest session first), each earlier line ending (earlier session). Check grep -rn "milestones (this session)" skills agents lib docs README.md USAGE.md and update every citer in the same commit (BDR-100).

  • Step 1: tests PM1 current + one earlier milestone → literal lines in that order; PM2 only an earlier milestone (the 4b live-proof case) → the answer is not nothing captured and holds - commit fix: probe (HH:MM) (earlier session) (HH:MM from the test clock through the same local-time helper the 4b tests use).
  • Step 2-4: FAIL, implement, green.
  • Step 5: commit feat(memory): memory_pending lists earlier-session milestones.

Task 7: Session digest in session-start.sh

Files: Modify hooks/session-start.sh (end of file, before the final echo ""); Create lib/tests/session-digest.test.sh (or the name the Makefile's discovery requires, Task 0).

Interfaces: a function _memory_digest <project-root> printing the block of spec Unit 5:

memory digest:
- open: BLK-017 Bing Webmaster API unusable for a multi-client agency (W2…
- open: +1 more, +3 upstream
- todo: deferred (BDR-123): remap inline-writing best-tier skills …
- journal: 2026-11-04 — 4b memory capture merged into develop …

Source handling: _ss_source=''; if [ ! -t 0 ]; then _ss_in=$(timeout 1 cat 2>/dev/null); _ss_source=$(printf '%s' "$_ss_in" | jq -r '.source // empty' 2>/dev/null); fi; digest when _ss_source is empty, startup, clear or compact. Root = git rev-parse --show-toplevel else pwd; .claude/memory/ absent → nothing. Open BLK through lib/reconcile.sh reconcile_blk_open (source the lib from $_repo_dir/lib), status word open listed (≤ 3, then +N more), upstream counted; TODO: first 3 - [ ] lines under ### Actionable up to the next # heading, the - [ ] prefix dropped; journal: last line starting - . Every line cut at 160 chars (…), block cut at 800. All digest commands 2>/dev/null; the function's failure never changes the exit code (|| true).

  • Step 1: tests (a mktemp -d fixture project per case, literal expected output): SD1 source startup with 1 open + 2 upstream BLK, a TODO with 4 unchecked items, a journal → the literal block (3 todo lines, +2 upstream); SD2 source resume → no memory digest:; SD3 </dev/null → digest printed (empty source), exit 0; SD4 no .claude/memory → no block; SD5 TODO without ### Actionable → no todo line; SD6 a 400-char journal line → cut at 160 with …; SD7 10 open BLK with long titles → block ≤ 800 chars; SD8 the existing callers (lib/tests/memory.test.sh T13c/d, push-guard.test.sh, graphify-gate.test.sh) still green.
  • Step 2-4: FAIL, implement, bash lib/tests/session-digest.test.sh green, shellcheck hooks/session-start.sh lib/tests/session-digest.test.sh clean, full make test green.
  • Step 5: commit feat(hooks): memory digest at session start.

Task 8: Measured proof harness (controller + one sonnet dispatch)

Files: Create .claude/tasks/plans/2026-11-04-memory-recall-spike/recall-bench.ts (bun, imports entriesOf, lessonOf, parseIndex, isLive, bm25Rank, rerankPrompt, parseIds, recallBlock, normalize, failureLine, redact, buildIndex, matchOf, deErrno from mods/memory/hooks/register.ts), RECALL.md (counts and shares only).

  • Step 1 (sonnet): the harness: mode prompts reads the last 14 days of ~/.claude/projects/-home-bchanot-Documents-claude/*.jsonl (main-loop files only), keeps composer user prompts (string content, not a slash command, not a tool result) that meet isTrigger with fresh true for each session's first prompt and real idle gaps from timestamps, samples 20 with --seed, runs the real reader on this repo (bash lib/memory.sh index via Bun.spawnSync), BM25 top-30, then haiku through claude -p --model claude-haiku-5-5 --output-format json with rerankPrompt as the prompt, times each call, prints per prompt the prompt's first 120 chars (redacted) and the injected IDs + titles, and totals: asks, injections, mean IDs, timeout share at 3 s. Mode errors replays the Bash failures of the same 14 days (main + */subagents/*.jsonl) through failureLine + the error index and prints per session the injections and each injected (line, ID, title) (redacted). Read-only; writes nothing but stdout.
  • Step 2 (controller): run both modes; label each injected entry relevant / not relevant to its prompt or error; show the labels to the user at the merge gate; write RECALL.md: counts, the relevant share for each channel, the timeout share, the per-session injection rate, no prompt or error text.
  • Step 3: gate input: relevant share < 64 % on either channel, or a timeout share > 25 %, → propose a change (tighter trigger, fewer candidates, RERANK_MS 5000) at the merge gate.
  • Step 4: commit chore(bench): phase 4c recall precision measured on 14 days of transcripts.

Task 9: Docs and TODO (sonnet)

Files: README.md, USAGE.md (French), CHANGELOG.md [Unreleased], ARCHITECTURE.md (mods line), .claude/tasks/TODO.md.

  • Content: recall triggers (first prompt of a context, after 30 min idle, design/analysis words; never slash commands), what is injected and its cap, the known-error line, the digest and its sources, "recall": false, the injection log (kept, not shown), residuals (3 s bound drops a share of recalls, the router's classifier label is not used, sub-agents get the error channel only, EVAL not recalled). TODO: 4c sub-bullet "built … merge pending", 4d line: "the injection log now exists (4c), 4d waits on its data", the 4b shortcut: harvest line ticked (the lexical superseded reader is gone, Task 1). make test suite=lib/tests/doctrine-citers.test.sh green.
  • commit docs: memory recall, known-error line and session digest.

Task 10: Live proof (controller + user)

  • Headless: a mktemp -d repo on a feature branch, .claude/memory/blockers.md fixture with a BLK whose backticked span is `fatal: unable to access probe remote xyz`, claude -p --model haiku runs git ls-remote https://127.0.0.1:9/probe.git style command failing with that text (or a script echoing it to stderr with exit 1), then reports the context lines it saw: expect memory: known BLK-001 ….
  • Interactive (user): in a fresh session in this repo, a design prompt → the transcript holds one memory recall: attachment on that prompt; /compact → the next session-start context holds memory digest:; record both in the contract § PROOF.
  • make test all green; shellcheck ./*.sh hooks/*.sh lib/*.sh clean.