Files
claude_mac/.claude/tasks/contracts/2026-11-04-memory-recall-1859.md
T

14 KiB

CONTRACT — memory-recall (phase 4c)

  • date: 2026-11-04 | flow: ship-feature | branch: feature/memory-recall (off develop 06d2576, created at STEP 4)
  • status: active

REQUEST (verbatim — IMMUTABLE)

Phase 4c of the context mod queue (BDR-125), TODO.md "Phase 4b-4d, memory v2 capture, read, feedback" — the 4c read side: two channels only: intent recall at prompt.submit for classifier labels design/analysis or the first coding prompt after idle (BM25 top-30 over title + lesson + body → haiku keeps ≤3, bounded 3 s, fail open) and tool-error 4-gram match (PostToolUse; a classic hook is acceptable if the mod ledger is not needed). Session digest (open BLK via the status parser, actionable TODO, last journal line) in hooks/session-start.sh on source: startup|compact|clear; a SubagentStart twin if sub-agents need it. Injection = ID + title + lesson line; superseded never injected; budget ~1.5k chars per turn; once per context. Deferred: Read path triggers, Bash command triggers, "critical → deny once", Tier 1, cross-repo index, memory_search tool. Plus the 4b follow-ups queued for 4c: earlier-session milestones in memory_pending, common-phrase 4-gram collisions (every ENOENT reads known LRN-056), the lexical superseded reader shortcut:. Host: mods/memory (BDR-137). 4d stays deferred until an injection log exists.

(user brief 2026-11-02, step 3: "Phases 4b à 4d"; launched after the 4b merge, user "merge it" 2026-11-04. Session constraints of that brief hold: default model opus; verifier, security-auditor and plan-challengers pinned on opus; never commit a /model or UI write of settings.json (LRN-253); plan text through Write/Edit (BLK-039); destructive steps on the live tree in the main loop after the user's go, mv over rm (BLK-040).)

CLARIFICATIONS

Pass A (gaps found by the STEP 0d read-before, put to the user at the STEP 1 brainstorm; answers land [gated]):

  • The classifier label is private to model-router (st.turnMain, never stored or published) and the classifier never runs on prompts its keyword rules already map (plan|design|architecture… → plan, why|explain|review|audit… → reflect), nor on slash commands: a trigger "classifier labels design/analysis" read literally misses exactly the design/analysis prompts that say so.
  • No uniform "lesson line" exists in the registries (BDR **Decision** median 643 chars, max 1989; LRN Apply / Future application / Pattern; BLK Solution / Real cause; EVAL Action): three BDR hits overflow the 1.5k budget unless the line is cut.
  • Superseded readers diverge (memory.sh parser vs the 4b lexical reader: BDR-031 live for the lexical one, EVAL-041 falsely superseded for the shell one).
  • Engine types 2.1.316 expose $.state and $.process.run (4b recorded "no $.state" from the 2.1.277 types); runtime availability unverified for both; mod session.start has no source, classic.SessionStart does.
  • The 4-gram collision: no such file or / such file or directory belong to LRN-056 only, so every ENOENT reads known LRN-056 (document frequency does not fix it).
  • Proof needs ≥ 20 real prompts and ≥ 10 real errors labelled for relevance; precision bar = the 14/22 haiku-rerank baseline (BDR-125 amendment 2, TODO.md:114).

Brainstorm answers [gated 2026-11-04] (user: "continue" to recommendations 0-11, read as yes): 0. Spike first (done: .claude/tasks/plans/2026-11-04-memory-recall-spike/REPORT.md): $.process.run memory.sh index 128 ms; classic.SessionStart fires in a mod with source startup/resume/compact and its additionalContext reaches the model; tool.call error-answer context reaches the model; haiku rerank median ≈ 2 s, tail 5.7-7.3 s, ≈ 4k input tokens.

  1. Intent-recall trigger without the router classifier: composer prompt, not mid-turn, not a slash command, ≥ 12 chars, AND (first prompt of a context [startup, /clear, compaction] OR first prompt after ≥ 30 min idle OR a design/analysis keyword match, the router's two default rule lists copied with their source commit).
  2. Corpus = live BDR + LRN + BLK (EVAL excluded). Lesson line: BDR Decision; LRN Apply > Future application > Pattern; BLK Solution > Real cause; first sentence cut at 280 chars. Injection line = ID, title (≤ 100), lesson; ≤ 3 entries; hard cap 1500 chars.
  3. Rerank: BM25 top-30 over title + lesson + body; haiku claude-haiku-5-5, effort low, 64 max tokens, gets the prompt + 30 candidates as ID + title + lesson, answers IDs validated against the candidates; own 3 s race (LRN-218); failure or timeout → nothing injected (no BM25-only fallback).
  4. Superseded reader = lib/memory.sh (single reader, BDR-129) through $.process.run(['bash', memory.sh, '-C', root, 'index']) (spike: works, 128 ms); superseded and deprecated excluded; the 4b lexical shortcut: reader is replaced by it for the error index too (BDR-031 becomes superseded as memory.sh says).
  5. Tool-error channel in the existing Bash hook (the ledger lives in the mod): a captured failure matching a live BLK/LRN entry attaches memory: known <ID>, title, lesson to the tool result context; an errno stop-phrase list (no such file or directory, permission denied, command not found, …) drops grams wholly inside a stop phrase at index and match time; main loop and sub-agents; noise measured with the 14-day replay before shipping.
  6. Once per context: injected IDs kept in the closure per session and agent; reset at session.end and on classic.SessionStart compact/clear; the 1500-char per-turn budget covers both channels.
  7. Digest in hooks/session-start.sh: reads the hook JSON on stdin without blocking under </dev/null; sources startup, clear, compact (not resume); open BLK (upstream counted apart), first 3 unchecked items of TODO ### Actionable, last journal line; ≤ 160 chars per line, ≤ 800 per block; silent without registries or without the section. No SubagentStart twin.
  8. memory_pending lists earlier-session milestones after the current session's, marked (earlier session).
  9. Off switch: "enabled": false cuts everything; a new key "recall": false cuts the injections only (capture and tool stay).
  10. Injection log in scope: last 200 injections per project {at, session, channel, ids} in the store, not displayed (4d reads it).
  11. Proof: a bun harness importing the mod's own functions (no port), haiku through claude -p; 20 real prompts from 14 days of transcripts and the error replay; the controller labels relevance, the user checks the labels; bar ≥ 14/22; oracle written after the measurement; live: headless error half, interactive recall + digest after a real /compact by the user.

Pass B [gated 2026-11-04] (plan r1; user: "oui, tels quels" / "oui"): visible texts kept in English as written in the plan: memory recall: block, memory: known <ID> … line, memory digest: with - open: / - todo: / - journal: lines; the new suite is lib/tests/session-digest.test.sh; the memory_pending header milestones (this session): becomes milestones: with earlier-session lines marked (earlier session) (citers updated, BDR-100).

ACCEPTANCE CRITERIA (seed, enriched at STEP 3 [gated])

  1. Intent recall: on the qualifying prompts (trigger decided at the brainstorm), the mod ranks live registry entries by BM25 over title + lesson + body, asks a small model to keep ≤ 3, bounded in time, and attaches them as context (ID + title + lesson line); any failure or timeout attaches nothing and passes the prompt through unchanged.
  2. Tool-error match: a captured tool failure whose error line shares a 4-gram with a live BLK/LRN entry attaches that entry (ID + title + lesson line) as context; the common-phrase collision (ENOENT → LRN-056) no longer fires.
  3. Superseded entries are never injected; the superseded reader is decided at the brainstorm and its verdicts agree with lib/memory.sh on this repo's registries (an independent oracle, LRN-237).
  4. Budget: at most ~1.5k chars of injected recall per turn; an entry is injected at most once per context (reset on /clear and compaction).
  5. Session digest: hooks/session-start.sh prints open BLK (status parser), actionable TODO and the last journal line on source startup|compact|clear, bounded in size; runs unchanged with </dev/null and in projects without registries or TODO.
  6. memory_pending lists earlier-session milestones (marked (earlier session)) after the current session's.
  7. Every hook fails open; the ~/.claude/memory.json off switch covers the read side; claude plugin validate --strict, claude plugin test (mods suite) and make test are green.
  8. Proof: recall precision measured on ≥ 20 real prompts and tool-error matching on ≥ 10 real errors, at or above the 14/22 baseline; a digest observed after a real compaction; the injection noise measured before shipping (LRN-261); the measured oracle written only after the measurement (EVAL-056).

STEP 3 gate [gated 2026-11-05] (user: "oui"): plan r3 (docs/superpowers/plans/2026-11-04-memory-recall.md, c38e602; § R2 and § R3 override the task text, R3 wins) approved; the 3 s haiku bound stays, its timeout share measured on the 20 real prompts and put to the merge gate (> 25 % → propose 5 s).

Digest cap order [gated 2026-11-05] (user: "Retirer d'abord les TODO"): over 800 chars the digest drops TODO lines first (last to first), then open-BLK lines; the header, the +N count line and the journal line stay.

Measurement gate [gated 2026-11-05] (RECALL.md: prompt channel 19/38 = 50 % relevant < 64 % bar, noise on content-free idle prompts; timeout share 4/20 = 20 %; user: "Plancher de contenu"): no intent recall on a prompt with fewer than 5 content words (tokensOf minus stop words); recall ships on and switchable; the 3 s bound stays; 4d reads the injection log.

Rerank bound gate [gated 2026-11-05] (three harness runs: 16/55 haiku calls over 3 s = 29 % > the 25 % bar; 1/55 over 4.5 s and over 5 s; user: "5 s"): RERANK_MS = 5000 (own race and timeoutMs). After the content floor: 25/41 = 61 % relevant counting entries written after the prompt, 19/35 = 54 % excluding them (RECALL.md).

Final review gate [gated 2026-11-05] (final opus review "Approved with fixes"; user: all three now): (I1) 2-letter FR+EN function words join the stop-word list so the 5-content-word floor drops vague approvals, then a same-seed re-measure; (I2) the store sweep counts l: keys and evicts the oldest log key when the store would pass its cap (no total capture outage); (I3) log records carry trigger (fresh | idle | keyword | tool) and asks that injected nothing are logged with their outcome (none | timeout | refused | paused).

  1. [gated 2026-11-05] Mod tests: mods/memory/hooks/register.test.ts holds the plan's named tests and the mods suite is green; no line of register.ts over 80 columns. CHECK: cd /home/bchanot/Documents/claude && T=mods/memory/hooks/register.test.ts && for n in SR1 SR3 SR5 LS1 LS4 ER1 ER3 RB1 RB3 RB5 IR1 IR5 IR6 IR7 IR8 IR9 IR11 TE1 TE2 TE4 PM1 PM2; do /usr/bin/grep -q "$n" "$T" || exit 1; done && [ "$(awk 'length($0) > 80' mods/memory/hooks/register.ts | wc -l)" = 0 ] && a=$(make test suite=lib/tests/mods.test.sh 2>&1) && printf '%s\n' "$a" | /usr/bin/grep -q 'all suites green' && echo MOD4C-OK EXPECT: MOD4C-OK EVIDENCE: pending
  2. [gated 2026-11-05] Digest: lib/tests/session-digest.test.sh exists and is green, and the existing session-start callers stay green. CHECK: cd /home/bchanot/Documents/claude && [ -f lib/tests/session-digest.test.sh ] && a=$(make test suite=lib/tests/session-digest.test.sh 2>&1) && printf '%s\n' "$a" | /usr/bin/grep -q 'all suites green' && b=$(make test suite=lib/tests/memory.test.sh 2>&1) && printf '%s\n' "$b" | /usr/bin/grep -q 'all suites green' && echo DIGEST-OK EXPECT: DIGEST-OK EVIDENCE: pending
  3. [gated 2026-11-05] Measured before shipping: .claude/tasks/plans/2026-11-04-memory-recall-spike/RECALL.md holds, for the prompt channel and the error channel, the injected count n, the relevant share and the timeout share, and no prompt or error text. CHECK: cd /home/bchanot/Documents/claude/.claude/tasks/plans/2026-11-04-memory-recall-spike && [ -s RECALL.md ] && /usr/bin/grep -qi 'timeout' RECALL.md && /usr/bin/grep -qi 'relevant' RECALL.md && /usr/bin/grep -qE '\bn ?= ?[0-9]+' RECALL.md && echo RECALL-OK EXPECT: RECALL-OK EVIDENCE: pending
  4. [gated 2026-11-05] Whole branch: make test all suites green, shellcheck clean on the health stack, settings.json untouched by the branch's own commits (the develop merge excepted). CHECK: cd /home/bchanot/Documents/claude && t=$(make test 2>&1) && printf '%s\n' "$t" | /usr/bin/grep -q 'all suites green' && shellcheck ./.sh hooks/.sh lib/*.sh && [ -z "$(git diff develop...HEAD --stat -- settings.json)" ] && echo BRANCH4C-OK EXPECT: BRANCH4C-OK EVIDENCE: pending

FILE SCOPE (seed, final at STEP 3 [gated])

  • mods/memory/hooks/register.ts, mods/memory/hooks/register.test.ts (host, BDR-137); mods/memory/.claude-plugin/plugin.json (version)
  • hooks/session-start.sh and the suites that run it (lib/tests/memory.test.sh, push-guard.test.sh, graphify-gate.test.sh) if its output changes
  • lib/memory.sh only if a read helper is needed (no write path change)
  • README.md, USAGE.md, CHANGELOG.md, ARCHITECTURE.md, .claude/tasks/TODO.md
  • .claude/tasks/plans/ (spike and measurement notes), docs/superpowers/{specs,plans} (transient), this contract

PROOF (Task 10)

  • Headless (2026-11-05, claude -p --model haiku, live user settings, mod memory@skills-dir from this branch, scratch repo on feature/probe with a fixture BLK-001 whose friction line holds the backticked error, GITFLOW_NO_PUSH=1, --allowedTools 'Bash(sh probe.sh)'): the failing sh probe.sh printed the fixture error; the model quoted the tool-result context line memory: known BLK-001 probe remote unreachable from the sandbox — Use the local mirror path instead of the remote URL. PASS. Script $CLAUDE_JOB_DIR/tmp/proof10/run.sh, log out.jsonl beside it.
  • Interactive (user): pending — a recall on a design prompt in a fresh session, a recall again after /clear, the memory digest: after /compact.