36 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 4bmemory_pendingfailure answer), one log line per hook per session throughwarnOnce; 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 isbash <HOME>/.claude/lib/memory.sh -C <root> index. - Model id
claude-haiku-5-5(full id, LRN-203); every$.model.completeand$.process.runis 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 (closureStateonly).- 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.tsdefault prompt rules at commit9bbd1d5(name the commit in a comment). - Tests:
make test suite=lib/tests/mods.test.shwhile iterating; the fullmake testonce before each commit that touches shell. Never touchsettings.json(dirty on purpose) or~/.claude/memory.json. - Commits: one per task, message given in the task, only the task's files.
Review Focus
- A BDR whose
Decisionfield is 2 000 chars → the lesson is cut at 280 with…, and three such hits stay ≤ 1500 chars (Task 3, test RB3). $.process.runrejects, hangs, or exits non-zero (no bash, a brokenHOME) → recall and the error channel inject nothing,memory_pendingstill answers withindex: status reader unavailable(Task 1, tests SR3-SR5).- 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).
- 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).
- 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.shgreen at fb6cbf1;grep -c "test(" mods/memory/hooks/register.test.tsnoted;ls lib/tests/*.test.sh | headand the Makefiletesttarget 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 BDRDecision; LRNApply,Future application,Pattern; BLKSolution,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 issupersededordeprecated, 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;undefinedon timeout, rejection, missing HOME orexitCode !== 0.type Registries = { entries: Entry[]; status: Map<string, string> | undefined; index: Map<string, string>; note: string }async function loadRegistries($: Api, root: string): Promise<Registries>replacesloadIndex: readsdecisions.md,learnings.md,blockers.mdwith the 4btryRead;index=buildIndex(entries.filter(BLK|LRN), status);note= the 4bindex:line (now naming three files) plus; status reader unavailablewhenstatusis 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, theshortcut:comment above it; the TODO.md line harvesting it is ticked in Task 7. -
Consumed by:
pendingAnswer,newFailureCount(switch toloadRegistries). -
Step 1: tests (literal oracles)
SR1parseIndexon 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→''.SR2a test-sideon('process.run', …)answering that stdout with exit 0 →memory_pendinglists a failure matching a BLK span asknown BLK-…, and an entry marked superseded in the stdout is not indexed (its matching failure readsNEW).SR3process.runthrows → the answer holdsstatus reader unavailableand the failure readsNEW;SR4exit code 2 → same;SR5process.runnever settles → the answer arrives (clock advanced 2500 ms) withstatus reader unavailable.LS1-LS4lessonOf: BDR- **Decision**: Use X. Then Y.→Use X.; LRN withPatternandApply→ theApplytext; BLK- Solution: fix z→fix z; a 2 000-char field → 280 chars ending….EN1entriesOfon## BDR-007 — Title here [accepted] (2026-01-02)→ titleTitle here; a## Notesheading 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. TIMEentriesentriesOf+lessonOfon 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, afternormalize) →<errno>;gramscallsdeErrnofirst;PLACEHOLDERSgains<errno>. -
Consumed by:
buildIndex,matchOf(unchanged signatures). -
Step 1: tests
ER1entry span`cat: x: No such file or directory (os error 2)`and failure linels: cannot access '/tmp/zz': No such file or directory→ NEW (the LRN-056 collision, reproduced on a fixture).ER2entry span`fatal: unable to access remote host thing`and the same failure line text →known(content grams still match).ER3deErrno('cat: <path>: no such file or directory (os error #)')→'cat: <path>: <errno> (os error #)'.ER4gramsof'<errno> <path> # <hex>'→[].TIMEerrnodeErrnoon 64 KiB ofno such file orrepeats → < 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), minusSTOP_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, idfln(1 + (N - df + 0.5) / (df + 0.5)); entries with score > 0, highest first, ties by ID order, at mostk.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}/gmatches, kept when a candidate ID, deduplicated, order kept, at mostmax.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 exceedcapis dropped;''when no line fits.
- Step 1: tests
RB1three fixture entries; queryquoting heredoc shell→ the heredoc entry first (literal ID order oracle).RB2parseIds('BLK-041, BDR-999, LRN-258', cands, 3)with cands BLK-041, LRN-258 →['BLK-041', 'LRN-258'];parseIds('none', …)→[].RB3three BDR entries with 2 000-char Decision fields → each line's lesson ends…,recallBlock(…, 1500).length <= 1500, literal first line.RB4rerankPrompton two candidates → the literal expected string.RB5bm25Rankover 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).RB6a query with a token built at runtime as a secret shape ('sk_live_' + 'a'.repeat(24)) →rerankPromptholds<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:
Stategains:recall: boolean | null(the"recall"key, read withenabled),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).loadEnabledreturns{ enabled: boolean; recall: boolean };"recall": false→ recall off; a non-booleanrecalllogs one line (memory: ~/.claude/memory.json has no boolean "recall", recall stays on) and counts as absent.ensureEnabledkeeps its boolean contract; addensureRecall($, st): Promise<boolean>.export const DESIGN_RULE,export const ANALYSIS_RULE— the two router patterns (commit9bbd1d5), flagsiu.export function isTrigger(text: string, fresh: boolean, idleMs: number): boolean—!text.startsWith('/'), ≥ 12 code points, and (freshoridleMs >= 1800000or 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 everyseen/spentkey starting${session}:, addssessiontofresh. Called fromsession.startand from a newclassic.SessionStarthook whensourceisstartup,clearorcompact(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 byRERANK_MS; not answered / timeout / throw →''; ids → lines →recallBlock(lines, RECALL_CAP - spent); records ids inseen, chars inspent, 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);asProjectkeeps a validlogarray and drops malformed records. registerPrompt: on a composer, non-mid-turn prompt with a non-empty root: (1) the 4b note as today; (2) whenensureRecallandisTrigger(text, fresh.has(session), now - lastPrompt): clearfreshfor the session, reset the main key'sspent, append the recall block when non-empty; (3)lastPrompt.set(session, now)on every composer prompt. Both contexts go in onenext({ ...e, context: [...(e.context ?? []), note?, block?] }).session.endalso clearsseen,spent,fresh,lastPrompt,recall.- Step 1: tests (a bottom
on('model.complete', …)recording asks,on('process.run', …)answering a fixture index,mock.clock)IR1first composer prompt of a sessionon va concevoir la suite du mod(no keyword) → one ask; context holds the literal blockmemory recall:\nBLK-001 ….IR2a second ordinary prompt 1 min later without keyword → no ask, no block.IR331 min later an ordinary prompt → an ask.IR4/feat add x→ no ask; a mid-turn prompt (turnIdset) → no ask; originsdk→ no ask; 11-char prompt → no ask.IR5the model answersBDR-999, BLK-001(BDR-999 not a candidate) → only BLK-001 injected; answersnone→ no block; never settles → no block afterRERANK_MS(clock advanced) and the prompt passes;isAnswered: false→ no block.IR6classic.SessionStartcompact(fired with$.classic.SessionStart({ source: 'compact' })in the test) → the next ordinary prompt asks again and BLK-001 may come back;resume→ no reset.IR7design keyword in three prompts in a row → BLK-001 injected once only (later asks never list it as a candidate).IR8every candidate already seen → no ask at all.IR9"recall": falsein the switch file → no ask, the 4b note still attached after a milestone;"recall": "no"→ recall on + one log line.IR10process.run fails → no ask, prompt unchanged.IR11after an injection,loadProjectholds onelogrecord{channel: 'prompt', ids: ['BLK-001']}; 205 injections → 200 records kept.IR12a milestone pending and a trigger on the same prompt → context[note, block]in that order.TIMErulesboth 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:
captureFailurereturnsPromise<Failure | undefined>(the failure it built, stored or not).async function knownLine($: Api, st: State, at: Where, f: Failure, agent: string | undefined): Promise<string>—ensureRecallfalse →''; registries;status === undefined→'';id = matchOf(index, f.key); none, or already inseen[key]→''; entry →memory: known ${recallLine(entry)}; when its length exceedsRECALL_CAP - spent[key]→''; recordsseen,spent, and atoollog record.registerBash: after capture,line !== ''→return { ...out, context: [...(out.context ?? []), line] }; elsereturn out(unchanged object).- Step 1: tests
TE1a failing command whose line matches a fixture BLK span → the answer keepsisError,text,resultand gainscontext: ['memory: known BLK-002 …'](literal).TE2an ENOENT line (the ER1 fixture) → nocontextkey added (answer deep-equal to the tool's).TE3a sub-agent (agentId: 'a1') failure → injected; the same failure in the main loop → injected too (separate keys).TE4the same failure 20 times in one context → one injection.TE5"recall": false→ no context, capture still stored.TE6a matched entry superseded in the status stdout → no injection.TE7budget:spentat 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
PM1current + one earlier milestone → literal lines in that order;PM2only an earlier milestone (the 4b live-proof case) → the answer is notnothing capturedand 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 -dfixture project per case, literal expected output):SD1source startup with 1 open + 2 upstream BLK, a TODO with 4 unchecked items, a journal → the literal block (3 todo lines,+2 upstream);SD2sourceresume→ nomemory digest:;SD3</dev/null→ digest printed (empty source), exit 0;SD4no.claude/memory→ no block;SD5TODO without### Actionable→ no todo line;SD6a 400-char journal line → cut at 160 with…;SD710 open BLK with long titles → block ≤ 800 chars;SD8the existing callers (lib/tests/memory.test.shT13c/d,push-guard.test.sh,graphify-gate.test.sh) still green. - Step 2-4: FAIL, implement,
bash lib/tests/session-digest.test.shgreen,shellcheck hooks/session-start.sh lib/tests/session-digest.test.shclean, fullmake testgreen. - 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
promptsreads 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 meetisTriggerwithfreshtrue 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 indexviaBun.spawnSync), BM25 top-30, then haiku throughclaude -p --model claude-haiku-5-5 --output-format jsonwithrerankPromptas 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. Modeerrorsreplays the Bash failures of the same 14 days (main +*/subagents/*.jsonl) throughfailureLine+ 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_MS5000) 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 4bshortcut:harvest line ticked (the lexical superseded reader is gone, Task 1).make test suite=lib/tests/doctrine-citers.test.shgreen. - commit
docs: memory recall, known-error line and session digest.
Task 10: Live proof (controller + user)
- Headless: a
mktemp -drepo on a feature branch,.claude/memory/blockers.mdfixture with a BLK whose backticked span is`fatal: unable to access probe remote xyz`,claude -p --model haikurunsgit ls-remote https://127.0.0.1:9/probe.gitstyle command failing with that text (or a script echoing it to stderr with exit 1), then reports the context lines it saw: expectmemory: 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 holdsmemory digest:; record both in the contract § PROOF. make testall green;shellcheck ./*.sh hooks/*.sh lib/*.shclean.
R2 CHANGES (challenge r1: correctness CONCERNS(5), robustness CONCERNS(4), simplicity CONCERNS(1); no BLOCKER; these override the task text above)
Task split: Task 4 becomes 4a (switch key, log store, ledger and its resets: IR6, IR9, IR11 + the tests below) and 4b (trigger, BM25 candidates, rerank: IR1-IR5, IR7, IR8, IR10, IR12, TIMErules). Task 5 depends on 4a only.
Task 0 (rob 11): tell the user before Task 1 that the working-tree mod is live in their sessions and the executors' from the first save, and that adding "recall": false to ~/.claude/memory.json themselves is the kill switch during the build.
Task 1 — reader:
bootin register.test.ts gains oneprocess.runbottom driven by a World field (default: a literalmemory.sh indexstdout matching the fixture registries, BLK-001 open, LRN-002 superseded), so IDX1, the order test and NT1b keep their meaning; IDX3 is re-anchored on that stdout; SR3-SR5 set the field to throw / exit 2 / hang (corr 3).parseIndexreturnsMap<id, {status, title}>; titles come from memory.sh (fence-aware, tag and date stripped),entriesOfonly splits bodies (heading regex = 4bHEADINGwidened toBDR|LRN|BLK, no title capture); EN1's title oracle moves to SR1 (simp 2).- Bounded captures carry no
$: the label regex takes.{0,2000}as a prefix of the line, the heading[^\n]{0,300}likewise; tests at a 2 001-char Decision (lesson still cut at 280) and a 320-char heading (still an entry) (corr 4, rob 5). loadRegistries($, root, names): the 4b callers (pendingAnswer,newFailureCount) pass['blockers.md', 'learnings.md']and keep theirindex:line unchanged; recall passes the three files (simp 3).- Status unavailable:
memory_pendingstill labels NEW/known from all entries (advisory), withstatus reader unavailableon theindex:line; injections stay off (rob 7). - A real-registry check in the test (skipped when the repo files are absent): the
entriesOfIDs equal theparseIndexIDs on this repo (rob 6). isLive: an ID absent from the map while the map exists is NOT live (fail closed on AC3) (rob 6).process.runis skipped when no registry file was read (rob 3).
Task 2 — errno phrases: input/output error is listed as <path> error (normalize already turned input/output into <path>); ER case for it (corr 7, rob 14).
Task 3 — harness-facing exports: export isTrigger, IDLE_MS, DESIGN_RULE, ANALYSIS_RULE and a failureKey(text, command) wrapper of the buildFailure chain (tail → redact → lastLine → normalize) for the harness (simp 5, corr 12).
Task 4a — ledger:
- The main key's
spentresets on EVERY composer non-mid-turn prompt (outside the trigger branch); test: recall on prompt 1, ordinary prompt 2, then a known error is injected (corr 1, rob 1). - One context-start call site: the
classic.SessionStarthook onstartup | clear | compact(notsession.start);resumechanges nothing; aclassic.SessionStartcarryingagent_idresets only that agent's key;session.endclears by the ending session's id only; keys use$.session.id()(corr 9, simp 4). - A missing
lastPromptmeans not idle (rob 10). - Check-and-record of
seen/spentrun synchronously after the last await; test: two concurrent failing Bash calls → one injection (rob 9). - The log:
saveProjectpersistslog; the sweep keeps a project key that still holds a log (it drops sessions first); test: an injection, then a failure capture, then a sweep → the log still holds the record (corr 11, rob 8). - Switch: an absent
enabledkey with"recall": falselogs nothing; only a present non-boolean logs (corr 6).
Task 4b — trigger and rerank:
- Registries load once per
prompt.submitand are shared by the 4b note and recall (rob 3). - A consecutive-failure pause for the rerank, modelled on the router's: 3 failed or timed-out reranks in a row → no rerank for 15 min (in the closure), reset on a success; test (rob 3).
Task 5 — sub-agent delivery of the known line is verified headless in Task 10 or listed as a residual (corr 10).
Task 7 — digest (corr 2, 8, 13; rob 2, 13; simp 1):
- Open BLK come from
bash "$_mem_lib" -C "$root" index blocker(rows| ID | date | title | status |, statusopenlisted,upstreamcounted), NOTreconcile_blk_open; reconcile.sh is not sourced. - The digest runs in a subshell:
( _memory_digest "$root" ) 2>/dev/null || true; the lib path is$(dirname "${BASH_SOURCE[0]}")/../lib/memory.sh(like the neighbours), never$_repo_dir(unset by then). - stdin is read at the TOP of session-start.sh, behind
command -v timeout jq(without them: no source, the digest prints only on an empty-stdin manual run, never guessed as startup). - Cuts are char-safe (awk under a UTF-8 locale, or
cut -cchecked with a non-ASCII SD6 line containing—). - SD9: a digest that hits an unset variable still exits 0 and leaves the banner intact.
Task 8 — harness (corr 5, 12, 15; rob 4; simp 5):
- Prompts from main-loop files whose
entrypoint == "cli"only (nosdk-*sessions); the walk reusesnoise.py'spairs_of/find_fileslogic as reference (ported in TS, the source named). - haiku runs from a
mktemp -dcwd with--setting-sources local, no tools; latency from the JSONduration_api_ms, labelled an upper bound. - Every share is reported with its n; fewer than 10 injections on a channel → "insufficient sample" at the gate, not a pass or a fail.
Task 9 — docs: also the plugin.json description and the register.ts header comment (no version bump) (simp 6, corr 14).
Task 10 — headless recipe copies LRN-260 (GITFLOW_NO_PUSH=1, --allowedTools naming the one probe command) (rob 12); a memory fixture body is written with Write + --body-file, never a heredoc quoting an extraction command (extract-guard, LRN-262).
R3 CHANGES (confirmation pass: correctness CONCERNS(4), no BLOCKER; these override R2 and the task text)
- Split order (conf 1). 4a keeps only what it can show at its own commit: the switch-key logging (corr 6 test) and log retention (a
logseeded in the store, then a failure capture and a sweep: the log survives). IR6, IR9, IR11, the spent-reset test and the log-after-injection test move to 4b; the two-concurrent-failures test moves to Task 5. Task 5 depends on 4a and 4b. - Real-registry parity (conf 2). The
entriesOfIDs ==parseIndexIDs check runs in a shell suite (a new case inlib/tests/memory.test.sh, bun one-liner importing the two functions, EVAL rows filtered), and FAILS when the registries are absent; it is not a kit test. - Status unavailable (conf 3).
buildIndex(entries, undefined)indexes ALL entries (advisory); SR3-SR5 oracles: the SR2 failure readsknown BLK-001and theindex:line endsstatus reader unavailable; recall and the error channel inject nothing. A spec-amendment step (end of Task 9) rewrites spec Units 1, 2 and 5 for the four R2 deviations (status unavailable labels,classic.SessionStartas the context-start site, titles from memory.sh, digest frommemory.sh index blocker). - Entry assembly (conf 4). Export a pure
assembleEntries(texts: string[], index: Map<string, {status, title}>): Entry[]that joins kind, the memory.sh title cut at 100 with…,lessonOf, and the body;loadRegistriesand the harness both use it; the harness imports alsorecallLine. - Digest tests (conf 5, 6, 7, 8). SD9 = a copy of the script beside a fake
lib/memory.shthat exits 2, then one that prints malformed rows, and ablockers.mdthat is a directory: exit 0, banner intact, no digest. The block cap drops whole lines from the end until ≤ 800 chars (never a mid-line cut); SD7 uses long TODO items and a long journal line. Cuts use bash${v:0:159}…under the inherited locale, with an SD6 line containing—checked to stay valid UTF-8 (iconv -f UTF-8 -t UTF-8succeeds); nocut -c. Withouttimeoutorjq: the digest prints only when stdin is a terminal ([ -t 0 ], a manual run), never from a hook; SD10 runs with a PATH lacking jq and a piped{"source":"resume"}→ no digest. - Kill switch wording (conf 9). Task 0 tells the user: before 4a lands,
{"enabled": false}is the kill switch; from 4a on,{"enabled": true, "recall": false}cuts injections only. - Test world (conf 10). Tests drive the
process.runWorld field, never add a second bottom; the test at register.test.ts ~885 (expectsknown LRN-002after editing the file to open) sets its own stdout with LRN-002 open. - Errno phrase (conf 11).
deErrnoruns on the lowercased line BEFOREnormalize's PATH step forinput/output erroronly (a dedicated literal replacement), the other phrases after normalize as planned; ER case. - Log size (conf 12). The log lives in its own store key
l:<root>(≤ 200 records, ≤ 64 KiB, oldest dropped), outside the session sweep;loadProject/saveProjectuntouched. - /clear event (conf 13). Task 10's interactive check includes a
/clearthen an ordinary prompt: the transcript shows onememory recall:on it; the context-start key uses the event'ssession_idwhen present, else$.session.id(). Ifclearnever fires, it is reported as a residual at the merge gate. - Discriminating fixtures (conf 14). The spent-reset test uses a 3-entry recall of ~1 150 chars and a known line of ~400 chars (old code: dropped; new: injected); TE7 reaches its spent level through crafted injections, the lengths stated in the test.
- API and references (conf 15).
$.model.completegets{model, prompt, maxTokens, effort}only if the d.ts does not typetimeoutMs(check the d.ts; the own 3 s race stays either way); the TODOshortcut:tick is in Task 9;isTrigger,IDLE_MS,DESIGN_RULE,ANALYSIS_RULEare produced by 4b.