From fb6cbf1e34848e7d518934e0bfde14a541c947a1 Mon Sep 17 00:00:00 2001 From: bchanot Date: Wed, 4 Nov 2026 19:15:34 +0100 Subject: [PATCH 01/41] docs(spec): phase 4c memory recall design, contract and spike --- .../2026-11-04-memory-recall-1859.md | 48 ++++++ .../2026-11-04-memory-recall-spike/REPORT.md | 27 +++ .../specs/2026-11-04-memory-recall-design.md | 158 ++++++++++++++++++ 3 files changed, 233 insertions(+) create mode 100644 .claude/tasks/contracts/2026-11-04-memory-recall-1859.md create mode 100644 .claude/tasks/plans/2026-11-04-memory-recall-spike/REPORT.md create mode 100644 docs/superpowers/specs/2026-11-04-memory-recall-design.md diff --git a/.claude/tasks/contracts/2026-11-04-memory-recall-1859.md b/.claude/tasks/contracts/2026-11-04-memory-recall-1859.md new file mode 100644 index 0000000..fb07ffa --- /dev/null +++ b/.claude/tasks/contracts/2026-11-04-memory-recall-1859.md @@ -0,0 +1,48 @@ +# 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 , 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 `, 'index'], {timeoutMs})` in a hook | works: exit 0, 508 lines (4 registries, `| ID | Date | Title | Status |`), 128 ms | +| `classic.SessionStart` in a mod | fires with `source` startup; `--continue "/compact"` fires `resume` then `compact`; keys: session_id, transcript_path, cwd, source, model, agent_id, agent_type, effort, … | +| `classic.SessionStart` returning `additionalContext` | reaches the model (it quoted `PROBE4C-SESSIONSTART-CONTEXT source=startup`) | +| `tool.call` Bash error answer `{...out, context: [...]}` | reaches the model (it quoted `PROBE4C-TOOL-CONTEXT` as tool-result context); the error answer has no `context` key before the hook adds one | +| `$.model.complete({model: 'claude-haiku-5-5', prompt, maxTokens: 64, effort})` | see below | + +haiku rerank latency (prompt = a design question + 30 candidates; same session, sequential): + +| variant | prompt chars | input tokens | ms (n=3, + 2 earlier full/low runs: 2494, 7332) | output tokens | +|---|---|---|---|---| +| effort low, ~350 chars per candidate | 10 865 | 3 965 | 1725, 2743, 1790 | 225-258 | +| no effort, same prompt | 10 865 | 3 965 | 2063, 5713, 1938 | 224-302 | +| effort low, ~150 chars per candidate | 4 865 | 2 045 | 2921, 2060, 2755 | 326-394 | + +- Median ≈ 2 s; tail 5.7-7.3 s (2 of 11 calls over 5 s, 3 of 11 over 2.7 s). A 3 s bound drops roughly one call in five on this sample. +- `maxTokens: 64` does not cap output tokens (220-400 reported): the model thinks; the request type has no thinking switch. A shorter candidate list does not cut latency. +- Answers were valid candidate IDs every time. +- Cost per recall ≈ 4k input + 0.3k output haiku tokens. + +Consequences for the design: decision 4 (superseded reader) = memory.sh through `$.process.run` (single reader, 128 ms, no port); the compact/clear ledger reset hooks `classic.SessionStart`; the 3 s bound is the user's number, its timeout share is measured by the proof harness on the 20 real prompts and put to the gate. diff --git a/docs/superpowers/specs/2026-11-04-memory-recall-design.md b/docs/superpowers/specs/2026-11-04-memory-recall-design.md new file mode 100644 index 0000000..c3b2725 --- /dev/null +++ b/docs/superpowers/specs/2026-11-04-memory-recall-design.md @@ -0,0 +1,158 @@ +# Phase 4c memory recall — design (2026-11-04) + +BDR-125 phase 4c, host `mods/memory` (BDR-137). Contract +`.claude/tasks/contracts/2026-11-04-memory-recall-1859.md` (brainstorm answers +0-11 `[gated 2026-11-04]`). Engine facts: +`.claude/tasks/plans/2026-11-04-memory-recall-spike/REPORT.md` (CLI 2.1.318). +Branch `feature/memory-recall`. + +## Goal +The registries hold the lessons; nothing brings them back when they matter. +4c brings back the right entries at three moments, without noise: when a +design or analysis prompt starts work, when a known error comes back, and at +the start of every context. Writing is untouched (4b capture, memory.sh). +Success: precision of the injected entries at or above the 14/22 baseline +(64 %), the error channel's noise measured before shipping, a digest seen +after a real compaction. + +## Unit 1 — shared reader (register.ts) +- Status: `lib/memory.sh -C index` through `$.process.run(['bash', + /.claude/lib/memory.sh, '-C', root, 'index'], {timeoutMs: 2000})`, + raced by an own 2.5 s timer; rows `| ID | Date | Title | Status |`; an ID is + closed for recall when its status word is `superseded` or `deprecated` + (memory.sh is the single reader, BDR-129; spike: 128 ms). The script path is + `$HOME/.claude/lib/memory.sh` (the installed lib, the same one the skills + call). A failed or timed-out read → the status map is unavailable for that + call: recall injects nothing, the error channel injects nothing, and + `memory_pending` answers as today with an `index: status reader unavailable` + line and every failure `NEW`. +- Entries: the registry files `decisions.md`, `learnings.md`, `blockers.md` + read with `$.fs.read` (stat first, 4 MiB cap per file, as 4b `loadIndex`); + the 4b `entriesOf` heading regex extends to `BDR|LRN|BLK`; each entry keeps + `{id, kind, title, lesson, body}`. +- Lesson line: BDR the `Decision` field; LRN `Apply`, else `Future + application`, else `Pattern`; BLK `Solution`, else `Real cause` (label match + case-insensitive, bold or plain, `- **Label**:` / `- Label:`); its first + sentence, cut at 280 chars with `…`; an entry without one has the empty + lesson (title only). +- The 4b lexical `isSuperseded` and its `shortcut:` comment are removed: the + error index (BLK + LRN spans, as 4b) takes its live set from the same status + map. + +## Unit 2 — intent recall (`prompt.submit`) +- Trigger: origin `composer`, `turnId` absent, not a slash command (text not + starting `/`), ≥ 12 code points, and one of: the first such prompt of the + context (set at `session.start` and on `classic.SessionStart` source + `clear` or `compact`, consumed by the first qualifying prompt); the first + after ≥ 30 min without a composer prompt in this session; a match of the + design or analysis keyword patterns, copied from model-router's default + prompt rules (`mods/model-router/hooks/register.ts`, commit 9bbd1d5): + `plan|planifie|planning|brainstorm|architecture|con[cç]ois|design` and + `pourquoi|why|explique|explain|analyse|analyze|comprendre|understand|review|audit`, + same word boundaries. +- Rank: BM25 (k1 1.2, b 0.75) over title + lesson + body of the live + BDR/LRN/BLK entries, tokens = lowercase letter/digit runs of ≥ 2 chars minus + a short FR+EN stop-word list; the query is the prompt's first 2000 chars, + redacted (4b `redact`). Entries already injected in this context are + removed before ranking. Top 30 with a score > 0. +- Rerank: `$.model.complete({model: 'claude-haiku-5-5', effort: 'low', + maxTokens: 64, timeoutMs: 3000, prompt})`, raced by an own 3 s timer + (LRN-218). The prompt: the redacted query, the candidates one per line as + `ID | title | lesson`, and the instruction to answer at most 3 IDs, comma + separated, or `none`. The answer is parsed for `(BDR|LRN|BLK)-\d+`, kept + only when the ID is a candidate, at most 3, order kept. +- Inject: one context block `memory recall:` then one line per entry + ` — <lesson>`; the block ≤ 1500 chars (an entry that + would overflow is dropped). No candidate, a `none`, a timeout, a refusal or + any error → nothing attached, the prompt passes unchanged. +- The 4b milestone note on the same prompt is attached first; recall follows. + +## Unit 3 — tool-error recall (Bash `tool.call`) +- After the 4b capture (same failure rule, same redacted line): the failure's + key is matched against the error index (live BLK/LRN, Unit 1); a match whose + ID was not injected in this context attaches `memory: known <ID> <title ≤ + 100> — <lesson>` to the tool answer's `context` (the answer keeps its shape, + LRN-205; spike: the model sees it). +- Common phrases: before gramming, both the entry spans and the failure key + replace each errno phrase by the placeholder `<errno>`; a gram made only of + placeholders is skipped (LRN-258, `<errno>` joins `#`, `<path>`, `<hex>`). + Phrases: no such file or directory, permission denied, command not found, + is a directory, not a directory, file exists, directory not empty, + operation not permitted, no space left on device, connection refused, + connection timed out, broken pipe, resource temporarily unavailable, + invalid argument, too many open files, read-only file system, device or + resource busy, input/output error. +- Main loop and sub-agents (the context key carries the agent id). + +## Unit 4 — ledger, budget, log +- Once per context: `st.seen: Map<contextKey, Set<ID>>`, key = session id + + (`agentId` or `main`); cleared at `session.end`, and the session's keys on + `classic.SessionStart` source `clear` or `compact`. +- Budget: the main loop has 1500 chars per turn, shared by both channels, + reset by each composer prompt; a sub-agent (error channel only) has 1500 + chars for its whole context. +- Log: each injection appends `{at, session, agent, channel: 'prompt' | + 'tool', ids}` to the project's store value (`log`, last 200 kept, 4b write + chain and size caps); never displayed; 4d reads it. + +## Unit 5 — session digest (`hooks/session-start.sh`) +- Reads the hook JSON from stdin only when stdin is not a terminal, with + `timeout 1`; `source` taken with jq when present, else empty. Prints the + digest for `startup`, `clear`, `compact`, and for an empty source (a manual + run); never for `resume`. +- Only in a project whose git toplevel (else cwd) has `.claude/memory/`: + `memory digest:` then up to three kinds of lines: + open BLK from `reconcile_blk_open` with status word `open` (`BLK-n title`, + ≤ 160 chars each, at most 3, then `+N more`), the upstream ones counted + (`+N upstream`); the first 3 unchecked `- [ ]` items under + `### Actionable` in `.claude/tasks/TODO.md` (≤ 160 chars each); the last + `- ` line of `.claude/memory/journal.md` (≤ 160 chars). Block ≤ 800 chars. + Any missing file or section → that line is omitted; nothing to show → no + block. Fail silent: an error in the digest never changes the banner or the + exit code. +- No SubagentStart twin. + +## Unit 6 — `memory_pending` +Milestones of the earlier stored sessions follow the current session's, +marked `(earlier session)`, same 3-session window; the answer order stays +header, `index:`, milestones, failures. + +## Unit 7 — off switch +`~/.claude/memory.json`: `"enabled": false` cuts everything (4b); +`"recall": false` cuts Units 2 and 3 injections only (capture, the note, the +tool and the log of past injections stay). Read like `enabled` (lazily per +session, a non-boolean logs one line and counts as absent). + +## Docs +README / USAGE (fr) memory sections gain recall, the error channel, the +digest, `"recall": false`, the residuals; CHANGELOG `[Unreleased]`; TODO (4c +ticked at merge, 4d stays deferred with the log now in place). + +## Proof +- Kit tests: reader (status map, lesson per kind, failure → fail open), + trigger (first prompt, idle, keyword, slash and mid-turn excluded), BM25 + order on fixtures, rerank parse (foreign IDs dropped, `none`, timeout, never + settles), budget and once-per-context (reset on compact/clear and + session.end), error channel (known match attaches, ENOENT does not, sub-agent + key), earlier milestones, `recall: false`, log cap; regex costs timed on + 64 KiB (LRN-259). +- Shell suite: the digest on fixture projects (sources, missing files, caps, + `</dev/null`), existing session-start callers unchanged. +- Measured before shipping (LRN-261, EVAL-056): a bun harness under + `.claude/tasks/plans/2026-11-04-memory-recall-spike/` imports the mod's own + functions (no port) and calls haiku through `claude -p --model haiku`: + (a) 20 real composer prompts from 14 days of this repo's transcripts that + meet the trigger: injected IDs per prompt, timeout share at 3 s; the + controller labels each injected entry relevant or not, the user checks the + labels; bar: relevant share ≥ 64 % (14/22). (b) the 14-day Bash failure + replay: injections per session and the noise share on the injected ones, + ENOENT lines included. Counts and shares only in the committed notes. +- Live: headless `-p` for the error channel (a failing command matching a + fixture BLK attaches the line); interactive by the user for recall (a design + prompt in a fresh session), and the digest after a real `/compact`. + +## Out of scope +Read path triggers, Bash command triggers, critical deny-once, Tier 1, +cross-repo index, `memory_search` tool, reading the router's classifier +label, a SubagentStart twin, injection citation tracking (4d), EVAL in the +recall corpus. From fe6f953553874f9e7a48ed40aa9246fed372d8aa Mon Sep 17 00:00:00 2001 From: bchanot <chanot.bastien@gmail.com> Date: Wed, 4 Nov 2026 20:19:43 +0100 Subject: [PATCH 02/41] docs(plan): phase 4c memory recall plan r1, pass B gated --- .../2026-11-04-memory-recall-1859.md | 2 + .../plans/2026-11-04-memory-recall.md | 208 ++++++++++++++++++ 2 files changed, 210 insertions(+) create mode 100644 docs/superpowers/plans/2026-11-04-memory-recall.md diff --git a/.claude/tasks/contracts/2026-11-04-memory-recall-1859.md b/.claude/tasks/contracts/2026-11-04-memory-recall-1859.md index fb07ffa..437c5c6 100644 --- a/.claude/tasks/contracts/2026-11-04-memory-recall-1859.md +++ b/.claude/tasks/contracts/2026-11-04-memory-recall-1859.md @@ -30,6 +30,8 @@ Brainstorm answers `[gated 2026-11-04]` (user: "continue" to recommendations 0-1 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. diff --git a/docs/superpowers/plans/2026-11-04-memory-recall.md b/docs/superpowers/plans/2026-11-04-memory-recall.md new file mode 100644 index 0000000..5ac4c5e --- /dev/null +++ b/docs/superpowers/plans/2026-11-04-memory-recall.md @@ -0,0 +1,208 @@ +# 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. From d1f3dacdcdec81d3a1aae189951ffa85efaff57e Mon Sep 17 00:00:00 2001 From: bchanot <chanot.bastien@gmail.com> Date: Wed, 4 Nov 2026 22:16:38 +0100 Subject: [PATCH 03/41] chore(plan): phase 4c plan r1 challenge synthesis (r2 pending) --- .../CHALLENGE-r1.md | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) create mode 100644 .claude/tasks/plans/2026-11-04-memory-recall-spike/CHALLENGE-r1.md diff --git a/.claude/tasks/plans/2026-11-04-memory-recall-spike/CHALLENGE-r1.md b/.claude/tasks/plans/2026-11-04-memory-recall-spike/CHALLENGE-r1.md new file mode 100644 index 0000000..858a06f --- /dev/null +++ b/.claude/tasks/plans/2026-11-04-memory-recall-spike/CHALLENGE-r1.md @@ -0,0 +1,19 @@ +# 4c plan r1 challenge (2026-11-04) — synthesis for the r2 revision (paused for the extract-guard /feat) + +Verdicts: correctness CONCERNS(5), robustness CONCERNS(4), simplicity CONCERNS(1). No BLOCKER. Full reports in the session transcript; findings to apply in r2: +- Budget: reset the main key's `spent` on every composer non-mid-turn prompt, not only on trigger prompts; test recall → ordinary prompt → known error injected (corr 1, rob 1). +- Digest: read open BLK through `bash memory.sh -C <root> index blocker` (titles + status word, 17 ms) instead of sourcing reconcile.sh (`set -uo pipefail` leaks, `$_repo_dir` unset, no titles, 296-420 ms); run the digest in a subshell `( … ) 2>/dev/null || true`; lib path from `$(dirname "${BASH_SOURCE[0]}")/../lib`; read stdin at the top of the script behind `command -v timeout jq`; char-safe cuts (non-ASCII SD6) (corr 2, 8, 13; rob 2, 13; simp 1). +- Test world: `boot` gains a `process.run` bottom driven by a World field (default literal index stdout matching REGS: BLK-001 open, LRN-002 superseded) so IDX1, the order test, NT1b keep their meaning; IDX3 re-anchored; SR3-5 set throw / exit 2 / hang (corr 3). +- Regexes: no `$` after bounded captures (heading `[^\n]{0,300}`, label `.{0,2000}` as prefixes); tests at 2001 chars and a 320-char heading; entriesOf IDs == parseIndex IDs on this repo (corr 4, rob 5, rob 6). +- Harness: main-loop files with `entrypoint == "cli"` only; haiku from a `mktemp -d` cwd with the spike's isolation (`--setting-sources local`, tools off); latency from `duration_api_ms`, labelled upper bound; import `isTrigger`, `IDLE_MS`, rules, and an exported `buildFailure`/`failureKey`; reuse noise.py `pairs_of`/`find_files` as the walk reference; report n beside each share, < 10 injected = "insufficient sample" (corr 5, 12, 15; rob 4; simp 5). +- Latency stacking: load registries once per prompt.submit, shared by note and recall; skip `process.run` when no registry file was read; consecutive-failure pause for the rerank modelled on the router's (3 fails → cooldown) (rob 3). +- Switch: `{"recall": false}` alone must not log SWITCH_INVALID for an absent `enabled` (corr 6). +- `input/output error` → `<path> error` after normalize, or run deErrno before PATH; ER case (corr 7, rob 14). +- Ledger scope: clear by session id at session.end; `classic.SessionStart` with `agent_id` resets only that agent's key; use `$.session.id()`; one call site for context start (classic.SessionStart startup|clear|compact), not session.start (corr 9, simp 4); missing `lastPrompt` = not idle (rob 10). +- Log: `saveProject` persists `log`; sweep keeps it or a separate `l:<root>` key; test injection → capture → log kept (corr 11, rob 8). +- Concurrency: check-and-record of `seen`/`spent` synchronous after the last await; two-concurrent-failures test (rob 9). +- Loader: `loadRegistries($, root, names)`; 4b callers keep two files and their `index:` line; recall reads three; `parseIndex` returns `{status, title}` and titles come from memory.sh (simp 2, 3). +- Status unavailable: index all entries for the advisory NEW/known label in memory_pending; injections stay off (rob 7). +- Task 4 split into 4a (switch, log store, ledger) and 4b (trigger, rerank) (simp 7). +- Docs: plugin.json description and register.ts header comment; no version bump (simp 6, corr 14). +- Live safety: Task 0 tells the user that `"recall": false` in `~/.claude/memory.json` is the kill switch during the build (rob 11); Task 10 headless recipe copies LRN-260 (`GITFLOW_NO_PUSH=1`, `--allowedTools`) (rob 12); sub-agent delivery of the known line checked headless or listed as residual (corr 10). From 634279818185b6e65425dee44e02e2229889a117 Mon Sep 17 00:00:00 2001 From: bchanot <chanot.bastien@gmail.com> Date: Thu, 5 Nov 2026 15:11:41 +0100 Subject: [PATCH 04/41] docs(plan): phase 4c plan r2 (challenge r1 findings) --- .../plans/2026-11-04-memory-recall.md | 50 +++++++++++++++++++ 1 file changed, 50 insertions(+) diff --git a/docs/superpowers/plans/2026-11-04-memory-recall.md b/docs/superpowers/plans/2026-11-04-memory-recall.md index 5ac4c5e..641e99b 100644 --- a/docs/superpowers/plans/2026-11-04-memory-recall.md +++ b/docs/superpowers/plans/2026-11-04-memory-recall.md @@ -206,3 +206,53 @@ Source handling: `_ss_source=''`; `if [ ! -t 0 ]; then _ss_in=$(timeout 1 cat 2> - [ ] **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. + +## 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: +- `boot` in register.test.ts gains one `process.run` bottom driven by a World field (default: a literal `memory.sh index` stdout 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). +- `parseIndex` returns `Map<id, {status, title}>`; titles come from memory.sh (fence-aware, tag and date stripped), `entriesOf` only splits bodies (heading regex = 4b `HEADING` widened to `BDR|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 their `index:` line unchanged; recall passes the three files (simp 3). +- Status unavailable: `memory_pending` still labels NEW/known from all entries (advisory), with `status reader unavailable` on the `index:` line; injections stay off (rob 7). +- A real-registry check in the test (skipped when the repo files are absent): the `entriesOf` IDs equal the `parseIndex` IDs 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.run` is 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 `spent` resets 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.SessionStart` hook on `startup | clear | compact` (not `session.start`); `resume` changes nothing; a `classic.SessionStart` carrying `agent_id` resets only that agent's key; `session.end` clears by the ending session's id only; keys use `$.session.id()` (corr 9, simp 4). +- A missing `lastPrompt` means not idle (rob 10). +- Check-and-record of `seen`/`spent` run synchronously after the last await; test: two concurrent failing Bash calls → one injection (rob 9). +- The log: `saveProject` persists `log`; 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 `enabled` key with `"recall": false` logs nothing; only a present non-boolean logs (corr 6). + +Task 4b — trigger and rerank: +- Registries load once per `prompt.submit` and 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 |`, status `open` listed, `upstream` counted), NOT `reconcile_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 -c` checked 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 (no `sdk-*` sessions); the walk reuses `noise.py`'s `pairs_of`/`find_files` logic as reference (ported in TS, the source named). +- haiku runs from a `mktemp -d` cwd with `--setting-sources local`, no tools; latency from the JSON `duration_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). From c38e602fcdd97d99a8f5ccae615b4c1652be20ef Mon Sep 17 00:00:00 2001 From: bchanot <chanot.bastien@gmail.com> Date: Thu, 5 Nov 2026 15:26:42 +0100 Subject: [PATCH 05/41] docs(plan): phase 4c plan r3 (confirmation pass) --- .../superpowers/plans/2026-11-04-memory-recall.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/docs/superpowers/plans/2026-11-04-memory-recall.md b/docs/superpowers/plans/2026-11-04-memory-recall.md index 641e99b..cba54ba 100644 --- a/docs/superpowers/plans/2026-11-04-memory-recall.md +++ b/docs/superpowers/plans/2026-11-04-memory-recall.md @@ -256,3 +256,18 @@ Task 8 — harness (corr 5, 12, 15; rob 4; simp 5): 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 `log` seeded 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 `entriesOf` IDs == `parseIndex` IDs check runs in a shell suite (a new case in `lib/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 reads `known BLK-001` and the `index:` line ends `status 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.SessionStart` as the context-start site, titles from memory.sh, digest from `memory.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; `loadRegistries` and the harness both use it; the harness imports also `recallLine`. +- **Digest tests (conf 5, 6, 7, 8).** SD9 = a copy of the script beside a fake `lib/memory.sh` that exits 2, then one that prints malformed rows, and a `blockers.md` that 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-8` succeeds); no `cut -c`. Without `timeout` or `jq`: 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.run` World field, never add a second bottom; the test at register.test.ts ~885 (expects `known LRN-002` after editing the file to open) sets its own stdout with LRN-002 open. +- **Errno phrase (conf 11).** `deErrno` runs on the lowercased line BEFORE `normalize`'s PATH step for `input/output error` only (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`/`saveProject` untouched. +- **/clear event (conf 13).** Task 10's interactive check includes a `/clear` then an ordinary prompt: the transcript shows one `memory recall:` on it; the context-start key uses the event's `session_id` when present, else `$.session.id()`. If `clear` never 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.complete` gets `{model, prompt, maxTokens, effort}` only if the d.ts does not type `timeoutMs` (check the d.ts; the own 3 s race stays either way); the TODO `shortcut:` tick is in Task 9; `isTrigger`, `IDLE_MS`, `DESIGN_RULE`, `ANALYSIS_RULE` are produced by 4b. From 44e843685f39373de410bcc64328cdf47597f350 Mon Sep 17 00:00:00 2001 From: bchanot <chanot.bastien@gmail.com> Date: Thu, 5 Nov 2026 15:59:17 +0100 Subject: [PATCH 06/41] chore(contract): phase 4c STEP 3 gate [gated], criteria 9-12 --- .../2026-11-04-memory-recall-1859.md | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/.claude/tasks/contracts/2026-11-04-memory-recall-1859.md b/.claude/tasks/contracts/2026-11-04-memory-recall-1859.md index 437c5c6..4a9fbeb 100644 --- a/.claude/tasks/contracts/2026-11-04-memory-recall-1859.md +++ b/.claude/tasks/contracts/2026-11-04-memory-recall-1859.md @@ -42,6 +42,25 @@ Pass B `[gated 2026-11-04]` (plan r1; user: "oui, tels quels" / "oui"): visible 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). + +9. `[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 +10. `[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 +11. `[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 +12. `[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 From 38afa9325dd1b88a235092d45a34898ebc047b45 Mon Sep 17 00:00:00 2001 From: bchanot <chanot.bastien@gmail.com> Date: Thu, 5 Nov 2026 16:06:09 +0100 Subject: [PATCH 07/41] feat(memory): status reader through memory.sh, entries with lessons --- lib/tests/memory.test.sh | 15 ++ mods/memory/hooks/register.test.ts | 217 +++++++++++++++++++++++++++-- mods/memory/hooks/register.ts | 201 ++++++++++++++++++++++---- 3 files changed, 388 insertions(+), 45 deletions(-) diff --git a/lib/tests/memory.test.sh b/lib/tests/memory.test.sh index f4396c7..d79a64c 100755 --- a/lib/tests/memory.test.sh +++ b/lib/tests/memory.test.sh @@ -693,5 +693,20 @@ cp "$FIX/v1h/.claude/memory/blockers.md" v1h.bak printf -- '---\nformat: 2\n---\n' > "$FIX/v1h/.claude/memory/blockers.md" check T13d-banner-flips-off "$(banner "$FIX/v1h")" 0 cat v1h.bak > "$FIX/v1h/.claude/memory/blockers.md" +# T18 the mod's entriesOf reads the same IDs as memory.sh index on this repo's +# registries (parseIndex lists no EVAL row); FAILS when they are absent +parity=$(R="$ROOT" OUT="$(bash "$MEM" -C "$ROOT" index 2>/dev/null)" \ + bun -e ' +import { readFileSync } from "node:fs" +const { entriesOf, parseIndex } = + await import(`${process.env.R}/mods/memory/hooks/register.ts`) +const read = n => readFileSync(`${process.env.R}/.claude/memory/${n}.md`, "utf8") +const a = new Set(["decisions", "learnings", "blockers"] + .flatMap(n => entriesOf(read(n)).map(e => e.id))) +const b = new Set(parseIndex(process.env.OUT ?? "").keys()) +const diff = [...a].filter(x => !b.has(x)).concat([...b].filter(x => !a.has(x))) +console.log(a.size > 0 && diff.length === 0 ? "same" : `differ ${diff}`) +' 2>&1) +check T18-entriesOf-vs-index-ids "$parity" same echo "PASS=$pass FAIL=$fail" [ "$fail" -eq 0 ] diff --git a/mods/memory/hooks/register.test.ts b/mods/memory/hooks/register.test.ts index a2ceb6a..5c9ad9c 100644 --- a/mods/memory/hooks/register.test.ts +++ b/mods/memory/hooks/register.test.ts @@ -3,7 +3,8 @@ import type { Engine, MockClock } from 'claude-code/testing' import type { On } from 'claude-code' import { cap, tail, redact, normalize, failureLine, sessionOf, addFailure, - entriesOf, isSuperseded, grams, buildIndex, matchOf, + entriesOf, parseIndex, isLive, lessonOf, assembleEntries, grams, + buildIndex, matchOf, segments, suiteKeyOf, commitLabel, finishLabel, } from './register' @@ -12,6 +13,19 @@ const SWITCH = `${HOME}/.claude/memory.json` const ROOT = '/work/app' const BASH_ANSWER = { result: { stdout: 'ok', stderr: '' } } +/** What `memory.sh index` prints for the fixture registries below. */ +const INDEX_OUT = [ + '.claude/memory/blockers.md', '', + '| ID | Date | Title | Status |', '|---|---|---|---|', + '| BLK-001 | 2026-01-01 | x | open |', '', + '.claude/memory/learnings.md', '', + '| ID | Date | Title | Status |', '|---|---|---|---|', + '| LRN-002 | 2026-01-01 | y | superseded |', '', +].join('\n') + +/** How the process bottom answers: a stdout, or a way to fail. */ +type Proc = { stdout: string } | 'throw' | 'exit2' | 'hang' + type World = { switchText: string | undefined // ~/.claude/memory.json (undefined: absent) rootFails: boolean // session.root rejects @@ -28,6 +42,8 @@ type World = { unreadable: Set<string> // paths whose fs.read throws statFails: Set<string> // paths whose fs.stat throws though they exist existsFails: Set<string> // paths whose fs.exists throws + proc: Proc // what `memory.sh index` does now + runs: string[][] // every process.run argv gets: number // store.get calls getsFail: boolean // store.get throws } @@ -77,6 +93,7 @@ async function boot($: Engine, on: On, o: Opts = {}): Promise<World> { unreadable: new Set(o.unreadable ?? []), statFails: new Set(o.statFails ?? []), existsFails: new Set(o.existsFails ?? []), + proc: { stdout: INDEX_OUT }, runs: [], gets: 0, getsFail: false, } handStore(on, w, o.storeFails ?? false) @@ -115,6 +132,15 @@ async function boot($: Engine, on: On, o: Opts = {}): Promise<World> { } return { value: w.switchText } }) + on('process.run', async (_a, e) => { + w.runs.push([...e.argv]) + if (w.proc === 'throw') throw new Error('spawn failed') + if (w.proc === 'hang') await new Promise(() => undefined) + const done = w.proc === 'exit2' + ? { exitCode: 2, stdout: '' } : { exitCode: 0, stdout: w.proc.stdout } + return { value: { ...done, stderr: '', isStdoutTruncated: false, + isStderrTruncated: false } } + }) on('session.root', () => { if (w.rootFails) throw new Error('no root') return { value: w.root } @@ -580,6 +606,10 @@ const LEARNINGS = '## LRN-002 \u2014 y\n- **Status**: superseded\n' + const REGS = { [BLK]: BLOCKERS, [LRN]: LEARNINGS } const PENDING = 'mcp__memory__memory_pending' +/** The error index of one registry text, every entry live (no statuses). */ +const idxOf = (text: string) => + buildIndex(assembleEntries([text], new Map()), undefined) + const pending = async ($: Engine): Promise<string> => String(((await $.tool.call({ tool: PENDING })) as { result: unknown }) .result) @@ -652,7 +682,7 @@ test('IDX7: the answer holds no unredacted runtime-built token', async ( test('IDX8: the error span is indexed, not the prose between', async () => { const body = '## BLK-009 \u2014 z\n`git rm` and later words ' + '`fatal: unable to access remote host`\n' - const index = buildIndex([body]) + const index = idxOf(body) expect(matchOf(index, normalize('fatal: unable to access remote host'))) .toBe('BLK-009') expect(matchOf(index, normalize('and later words fatal unable'))) @@ -662,7 +692,7 @@ test('IDX8: the error span is indexed, not the prose between', async () => { test('a key of fewer than 4 words has no gram, so it is NEW', () => { expect(grams('a b c')).toEqual([]) expect(grams('a b c d e')).toEqual(['a b c d', 'b c d e']) - const index = buildIndex(['## BLK-001 x\n`aaa bbb ccc ddd`\n']) + const index = idxOf('## BLK-001 x\n`aaa bbb ccc ddd`\n') expect(matchOf(index, 'aaa bbb ccc')).toBeUndefined() }) @@ -674,13 +704,13 @@ test('entriesOf slices between headings, heading line included', () => { ]) }) -test('isSuperseded: the last status wins, else the heading tag', () => { - expect(isSuperseded('## LRN-1 a\n- **Status**: open\n- **Statut**: ' + - 'superseded\n')).toBe(true) - expect(isSuperseded('## LRN-1 a\n- **Status**: superseded\n' + - '- **Status**: open\n')).toBe(false) - expect(isSuperseded('## LRN-1 [superseded] a\nbody\n')).toBe(true) - expect(isSuperseded('## LRN-1 [open] a\n')).toBe(false) +test('isLive: superseded and deprecated are dead, an absent ID too', () => { + const m = parseIndex(INDEX_OUT) + expect(isLive(m, 'BLK-001')).toBe(true) + expect(isLive(m, 'LRN-002')).toBe(false) + expect(isLive(m, 'BLK-999')).toBe(false) + expect(isLive(parseIndex('| BDR-001 | d | t | deprecated |\n'), 'BDR-001')) + .toBe(false) }) test('a directory and an over-size file are skipped on the index line', async ( @@ -816,7 +846,7 @@ test('TIME1: an index over 80000 newlines builds in under 500 ms', () => { const body = '## BLK-001 x\n' + '\n'.repeat(80000) + '- **Status**: open\n' + '\r\n'.repeat(40000) + '`fatal: unable to access remote`\n' const t0 = now() - const index = buildIndex([body]) + const index = idxOf(body) expect(now() - t0).toBeLessThan(500) expect(index.size).toBe(2) }) @@ -867,8 +897,8 @@ test('a registry of exactly 4 MiB is read, one byte more skipped', async ( }) test('a span of 12 chars is indexed, one of 11 is not', () => { - const at12 = buildIndex(['## BLK-001 x\n`aa bb cc ddd`\n']) - const at11 = buildIndex(['## BLK-001 x\n`aa bb cc dd`\n']) + const at12 = idxOf('## BLK-001 x\n`aa bb cc ddd`\n') + const at11 = idxOf('## BLK-001 x\n`aa bb cc dd`\n') expect(at12.size).toBe(1) expect(at11.size).toBe(0) }) @@ -888,6 +918,7 @@ test('a throwing exists probe names the registry, keeps the other', async ( const files = { [BLK]: BLOCKERS, [LRN]: LEARNINGS.replace( 'superseded', 'open') } const w = await boot($, on, { files, statFails: [BLK], existsFails: [BLK] }) + w.proc = { stdout: INDEX_OUT.replace('superseded', 'open') } await failing($, w, EXIT1 + 'error: pathspec did not match anything') const text = await pending($) expect(text).toContain( @@ -1296,7 +1327,7 @@ test('I2: credentials on the command line are redacted', () => { test('IDX9: a placeholder-only gram is not indexed nor matched', () => { const span = '`connect 10.0.0.1:5432 refused 12 34`' - const index = buildIndex(['## LRN-074 x\n' + span + '\n']) + const index = idxOf('## LRN-074 x\n' + span + '\n') const key = normalize('Error at 2026-11-04 12:00:00.123 timeout') expect(matchOf(index, key)).toBeUndefined() expect(grams('# # # # x')).toEqual(['# # # x']) @@ -1450,7 +1481,7 @@ test('TIME1: each 6-bis rule stays fast on 64 KiB adversarial input', () => { test('the registry index caps a 1 MiB span before normalize', () => { const body = '## BLK-001 x\n`' + 'fatal word '.repeat(95326) + '`\n' const t0 = now() - const index = buildIndex([body]) + const index = idxOf(body) expect(now() - t0).toBeLessThan(50) expect(index.size).toBeGreaterThan(0) }) @@ -1566,3 +1597,159 @@ test('TIME1: curl prefix shapes stay fast on 64 KiB', () => { expect(now() - t0).toBeLessThan(30) } }) + +// ---- Task 1 (phase 4c): statuses from memory.sh, entries with lessons ---- + +const SR_LINE = 'fatal: unable to access remote host' + +test('SR1: parseIndex reads ID, lowercased status word and title', () => { + const out = [ + '.claude/memory/decisions.md', '', + '| ID | Date | Title | Status |', '|---|---|---|---|', + '| BDR-031 | 2026-06-25 | t | superseded |', + '| LRN-001 | 2026-01-01 | a | b | Open (2026) |', + '| LRN-003 | 2026-01-01 | t | |', + ].join('\n') + expect([...parseIndex(out)]).toEqual([ + ['BDR-031', { status: 'superseded', title: 't' }], + ['LRN-001', { status: 'open', title: 'a | b' }], + ['LRN-003', { status: '', title: 't' }], + ]) +}) + +test('SR2: a superseded entry is not indexed, a live one is known', async ( + $, on, +) => { + const w = await boot($, on, { files: REGS }) + w.proc = { stdout: INDEX_OUT.replace('| open |', '| superseded |') } + await failing($, w, EXIT1 + SR_LINE) + expect(await pending($)).toContain('- NEW ×1 ' + SR_LINE) + w.proc = { stdout: INDEX_OUT.replace('| superseded |', '| open |') } + await failing($, w, EXIT1 + 'error: pathspec did not match anything') + expect(await pending($)).toContain('- known LRN-002 ×1 error: path') +}) + +test('SR2b: the process is run once, with the memory.sh argv', async ( + $, on, +) => { + const w = await boot($, on, { files: REGS }) + await pending($) + expect(w.runs).toEqual([ + ['bash', '/home/t/.claude/lib/memory.sh', '-C', '/work/app', 'index'], + ]) +}) + +for (const [name, proc] of [ + ['SR3: process.run throws', 'throw'], + ['SR4: exit code 2', 'exit2'], + ['SR6: an empty stdout', { stdout: '' }], +] as const) { + test(`${name}: advisory known, status reader unavailable`, async ( + $, on, + ) => { + const w = await boot($, on, { files: REGS }) + w.proc = proc + await failing($, w, EXIT1 + SR_LINE) + const text = await pending($) + expect(text).toContain( + 'index: read blockers.md, learnings.md; status reader unavailable') + expect(text).toContain('- known BLK-001 ×1 ' + SR_LINE) + }) +} + +test('SR5: process.run never settles, the answer comes at 2500 ms', async ( + $, on, +) => { + const w = await boot($, on, { files: REGS }) + await failing($, w, EXIT1 + SR_LINE) + w.proc = 'hang' + const answer = pending($) + await new Promise(r => setTimeout(r, 20)) // let the call reach its wait + await w.clock.advance(2500) + const text = await answer + expect(text).toContain('read blockers.md, learnings.md; status reader unav') + expect(text).toContain('- known BLK-001 ×1 ' + SR_LINE) +}) + +test('SR7: no registry read, no process run, no unavailable note', async ( + $, on, +) => { + const w = await boot($, on) + await failing($, w, EXIT1 + SR_LINE) + const text = await pending($) + expect(w.runs).toEqual([]) + expect(text).not.toContain('status reader') +}) + +test('LS1: a BDR Decision reads its first sentence', () => { + expect(lessonOf('BDR', '## BDR-1 t\n- **Decision**: Use X. Then Y.\n')) + .toBe('Use X.') +}) + +test('LS2: an LRN takes Apply before Pattern', () => { + const body = '## LRN-1 t\n- **Pattern**: p one\n- **Apply**: do it now\n' + expect(lessonOf('LRN', body)).toBe('do it now') + expect(lessonOf('LRN', '## LRN-1 t\n- **Pattern**: p one\n')) + .toBe('p one') +}) + +test('LS3: a BLK plain label, Solution before Real cause', () => { + expect(lessonOf('BLK', '## BLK-1 t\n- Real cause: c\n- Solution: fix z\n')) + .toBe('fix z') + expect(lessonOf('BLK', '## BLK-1 t\n- **Real cause**: only c\n')) + .toBe('only c') + expect(lessonOf('BLK', '## BLK-1 t\n- **Friction**: f\n')).toBe('') +}) + +test('LS4: a 2000-char field is cut at 280 ending with an ellipsis', () => { + const text = lessonOf('BDR', '## BDR-1 t\n- **Decision**: ' + + 'a'.repeat(2000) + '\n') + expect(text).toHaveLength(280) + expect(text.endsWith('a…')).toBe(true) +}) + +test('LS5: a 2001-char Decision still yields a lesson cut at 280', () => { + const text = lessonOf('BDR', '## BDR-1 t\n- **Decision**: ' + + 'b'.repeat(2001) + '\nnext line\n') + expect(text).toHaveLength(280) + expect(text.endsWith('…')).toBe(true) +}) + +test('LS6: `; ` ends the sentence before a capital only', () => { + expect(lessonOf('BDR', '- Decision: a; Then b')).toBe('a;') + expect(lessonOf('BDR', '- Decision: a; then b. c')).toBe('a; then b. c') +}) + +test('EN1: a heading of 320 chars is still an entry; ## Notes is not', () => { + const text = '## BDR-007 — ' + 'T'.repeat(320) + '\nbody\n## Notes\nx\n' + const parts = entriesOf(text) + expect(parts.map(p => p.id)).toEqual(['BDR-007']) + expect(parts[0]?.body).toBe(text) // the 4b rule: up to the next entry +}) + +test('assembleEntries joins kind, memory.sh title, lesson and body', () => { + const body = '## LRN-009 — t [open] (2026-01-02)\n- **Apply**: do z. Ok\n' + const long = 'W'.repeat(150) + const index = parseIndex( + `| LRN-009 | 2026-01-02 | ${long} | open |\n`) + const [e] = assembleEntries([body], index) + expect(e).toEqual({ + id: 'LRN-009', kind: 'LRN', title: 'W'.repeat(99) + '…', + lesson: 'do z.', body, + }) + expect(assembleEntries([body], new Map())[0]?.title).toBe('') +}) + +test('TIMEentries: entriesOf and lessonOf on 64 KiB fields, under 50 ms', () => { + const bodies = [ + '## BLK-001 x\n- Solution: ' + 'a'.repeat(65536 - 26), + '## BLK-001 x\n- Solution: ' + 'a. '.repeat(21000), + '## BLK-001 x\n' + ' '.repeat(65536) + '- Solution: y', + '## BLK-001 x\n' + '- '.repeat(32768), + ] + for (const text of bodies) { + const t0 = now() + for (const part of entriesOf(text)) lessonOf('BLK', part.body) + expect(now() - t0).toBeLessThan(50) + } +}) diff --git a/mods/memory/hooks/register.ts b/mods/memory/hooks/register.ts index 958ac1e..d9a4aa9 100644 --- a/mods/memory/hooks/register.ts +++ b/mods/memory/hooks/register.ts @@ -383,17 +383,40 @@ async function sweepStore($: Api, curKey: string, id: string): Promise<void> { } // The registry error index: which captured failures a registry knows. -const REGISTRIES = ['blockers.md', 'learnings.md'] const MAX_REGISTRY = 4194304 const MIN_SPAN = 12 const GRAM_WORDS = 4 -const HEADING = /^## ((?:BLK|LRN)-\d+)\b.*$/gm +// the ID only: a bounded capture carries no `$`, so a long heading stays one +const HEADING = /^## ((?:BDR|LRN|BLK)-\d+)\b/gm const SPAN = /`([^`\n]+)`/g -// [ \t] not \s: a multiline regex must not cross newlines (quadratic). -const STATUS = - /^[ \t]*-[ \t]*\*\*Stat(?:us|ut)[^*\n]*\*\*[ \t]*:?[ \t]*([A-Za-z-]+)/gim +const STATUS_WAIT_MS = 2500 // our own race over the process's 2000 ms +const STATUS_TIMEOUT_MS = 2000 +const MAX_INDEX_ROW = 1000 +const DEAD = new Set(['superseded', 'deprecated']) +const INDEX_ROW = new RegExp( + '^\\|[ \\t]{0,5}((?:BDR|LRN|BLK)-\\d+)[ \\t]{0,5}\\|[^|]{0,40}\\|' + + '(.{0,900})\\|([^|]{0,100})\\|[ \\t]{0,5}$', +) +const MAX_TITLE = 100 +const MAX_LESSON = 280 +const MAX_FIELD = 2000 +const LESSON_LABELS: Record<Kind, string[]> = { + BDR: ['Decision'], + LRN: ['Apply', 'Future application', 'Pattern'], + BLK: ['Solution', 'Real cause'], +} -type Entry = { id: string; body: string } +export type Kind = 'BDR' | 'LRN' | 'BLK' +export type Entry = { + id: string + kind: Kind + title: string + lesson: string + body: string +} +type Part = { id: string; body: string } +type Listed = { status: string; title: string } +export type StatusMap = Map<string, Listed> type Read = { text: string } | { why: string } @@ -423,8 +446,8 @@ async function tryRead($: Api, path: string): Promise<Read> { } } -/** The BLK/LRN entries; a body runs from its heading to the next one. */ -export function entriesOf(text: string): Entry[] { +/** The entries' ID and body; a body runs from its heading to the next. */ +export function entriesOf(text: string): Part[] { const heads = [...text.matchAll(HEADING)] return heads.map((m, i) => ({ id: m[1] ?? '', @@ -432,14 +455,63 @@ export function entriesOf(text: string): Entry[] { })) } -// shortcut: a lexical reader, not memory.sh's shared parser (that lives in -// shell); upgrade = call the parser once the engine exposes a CLI run in -// hooks. -/** The last labelled status reads superseded; else the heading `[tag]`. */ -export function isSuperseded(body: string): boolean { - const last = [...body.matchAll(STATUS)].pop() - if (last !== undefined) return (last[1] ?? '').toLowerCase() === 'superseded' - return /\[superseded\]/i.test(body.split('\n', 1)[0] ?? '') +/** + * ID -> status word and title, from the rows `memory.sh index` prints + * (`| ID | Date | Title | Status |`); the status is its lowercased first + * word, `''` when empty. + */ +export function parseIndex(stdout: string): StatusMap { + const rows: StatusMap = new Map() + for (const line of stdout.split('\n')) { + const m = INDEX_ROW.exec(line.slice(0, MAX_INDEX_ROW)) + if (m === null) continue + const word = (m[3] ?? '').trim().match(/^[A-Za-z-]+/)?.[0] ?? '' + const title = (m[2] ?? '').trim() + rows.set(m[1] ?? '', { status: word.toLowerCase(), title }) + } + return rows +} + +/** False when the ID is superseded or deprecated, or the map lacks it. */ +export function isLive(status: StatusMap, id: string): boolean { + const row = status.get(id) + return row !== undefined && !DEAD.has(row.status) +} + +/** `text` cut to `n` characters, the last one `…` when it was cut. */ +function clip(text: string, n: number): string { + return text.length > n ? `${text.slice(0, n - 1)}…` : text +} + +/** The first sentence: up to `. ` or `; ` before a capital, or the end. */ +function firstSentence(field: string): string { + return /^(.*?[.;])(?:[ \t]+(?=[A-Z])|$)/.exec(field)?.[1] ?? field +} + +/** + * The one-line lesson of an entry: the first sentence of its first labelled + * field, in the order of its kind; `''` when none is there. + */ +export function lessonOf(kind: Kind, body: string): string { + for (const label of LESSON_LABELS[kind]) { + const line = new RegExp( + `^[ \\t]*-[ \\t]*(?:\\*\\*)?${label}(?:\\*\\*)?[ \\t]*:[ \\t]*` + + `(.{0,${MAX_FIELD}})`, + 'im', + ).exec(body) + const field = (line?.[1] ?? '').trim() + if (line !== null) return clip(firstSentence(field), MAX_LESSON) + } + return '' +} + +/** The entries of registry texts, titled by `memory.sh index`'s rows. */ +export function assembleEntries(texts: string[], index: StatusMap): Entry[] { + return texts.flatMap(entriesOf).map(({ id, body }) => { + const kind = id.slice(0, 3) as Kind + const title = clip(index.get(id)?.title ?? '', MAX_TITLE) + return { id, kind, title, lesson: lessonOf(kind, body), body } + }) } const PLACEHOLDERS = new Set(['#', '<path>', '<hex>']) @@ -465,7 +537,6 @@ function spansOf(body: string): string[] { } function indexEntry(index: Map<string, string>, entry: Entry): void { - if (isSuperseded(entry.body)) return for (const span of spansOf(entry.body)) { for (const gram of grams(normalize(span))) { if (!index.has(gram)) index.set(gram, entry.id) @@ -473,11 +544,19 @@ function indexEntry(index: Map<string, string>, entry: Entry): void { } } -/** gram -> first ID, over the backticked spans of live entries. */ -export function buildIndex(texts: string[]): Map<string, string> { +/** + * gram -> first ID, over the backticked spans of live entries. Without + * statuses (`undefined`) every entry is indexed: advisory, never injected. + */ +export function buildIndex( + entries: Entry[], + status: StatusMap | undefined, +): Map<string, string> { const index = new Map<string, string>() - for (const text of texts) { - for (const entry of entriesOf(text)) indexEntry(index, entry) + for (const entry of entries) { + if (status === undefined || isLive(status, entry.id)) { + indexEntry(index, entry) + } } return index } @@ -494,15 +573,54 @@ export function matchOf( return undefined } -type Registries = { index: Map<string, string>; note: string } +/** The stdout of `argv` on exit 0; `undefined` on any other end or 2.5 s. */ +async function runWithin($: Api, argv: string[]): Promise<string | undefined> { + const stop = new AbortController() + const timer = $.clock.sleep(STATUS_WAIT_MS, { signal: stop.signal }) + .then(() => undefined, () => undefined) + const run = $.process.run(argv, { timeoutMs: STATUS_TIMEOUT_MS }) + .then(r => (r.exitCode === 0 ? r.stdout : undefined), () => undefined) + try { + return await Promise.race([run, timer]) + } finally { + stop.abort() + } +} -async function loadIndex($: Api, root: string): Promise<Registries> { +/** The statuses `memory.sh index` prints; `undefined` when unavailable. */ +async function statusMap($: Api, root: string): Promise<StatusMap | undefined> { + try { + const home = await $.env.get('HOME') + if (!home) return undefined + const out = await runWithin( + $, ['bash', `${home}/.claude/lib/memory.sh`, '-C', root, 'index']) + const rows = out === undefined ? undefined : parseIndex(out) + return rows?.size ? rows : undefined + } catch { + return undefined + } +} + +type Registries = { + entries: Entry[] + status: StatusMap | undefined + index: Map<string, string> + note: string +} + +type Loaded = { texts: string[]; note: string } + +/** The texts of the named registries and the first part of the note. */ +async function readRegistries( + $: Api, + root: string, + names: string[], +): Promise<Loaded> { const texts: string[] = [] const read: string[] = [] const skipped: string[] = [] - for (const name of REGISTRIES) { - const path = `${root}/.claude/memory/${name}` - const r = await tryRead($, path) + for (const name of names) { + const r = await tryRead($, `${root}/.claude/memory/${name}`) if ('why' in r) { skipped.push(`${name} (${r.why})`) continue @@ -514,9 +632,31 @@ async function loadIndex($: Api, root: string): Promise<Registries> { read.length > 0 ? `read ${read.join(', ')}` : '', skipped.length > 0 ? `skipped ${skipped.join(', ')}` : '', ] + return { texts, note: `index: ${parts.filter(Boolean).join('; ')}` } +} + +const FAILURE_FILES = ['blockers.md', 'learnings.md'] +const FAILURE_KINDS = new Set<Kind>(['BLK', 'LRN']) + +/** + * The entries of the named registries with their statuses, and the error + * index over the BLK and LRN ones. No registry read: no process run. + */ +async function loadRegistries( + $: Api, + root: string, + names: string[], +): Promise<Registries> { + const { texts, note } = await readRegistries($, root, names) + const status = texts.length > 0 ? await statusMap($, root) : undefined + const entries = assembleEntries(texts, status ?? new Map()) + const failing = entries.filter(e => FAILURE_KINDS.has(e.kind)) + const lost = texts.length > 0 && status === undefined return { - index: buildIndex(texts), - note: `index: ${parts.filter(Boolean).join('; ')}`, + entries, + status, + index: buildIndex(failing, status), + note: lost ? `${note}; status reader unavailable` : note, } } @@ -797,7 +937,8 @@ async function pendingAnswer($: Api, st: State): Promise<string> { const id = await $.session.id() await st.writes const project = await loadProject($, root) - return formatPending(root, project, id, await loadIndex($, root)) + const rx = await loadRegistries($, root, FAILURE_FILES) + return formatPending(root, project, id, rx) } function registerPending(on: On, st: State): void { @@ -960,7 +1101,7 @@ function registerBash(on: On, st: State): void { async function newFailureCount($: Api, st: State, at: Where): Promise<number> { await st.writes const p = await loadProject($, at.root) - const { index } = await loadIndex($, at.root) + const { index } = await loadRegistries($, at.root, FAILURE_FILES) const cur = p.sessions.find(s => s.id === at.id) return (cur?.failures ?? []).filter(isFailure) .filter(f => matchOf(index, f.key) === undefined).length From 6adb05ce1ef758542eb2574c2edf2b7a73329753 Mon Sep 17 00:00:00 2001 From: bchanot <chanot.bastien@gmail.com> Date: Thu, 5 Nov 2026 16:12:22 +0100 Subject: [PATCH 08/41] fix(memory): errno phrases never make an error known --- mods/memory/hooks/register.test.ts | 93 +++++++++++++++++++++++++++--- mods/memory/hooks/register.ts | 27 ++++++++- 2 files changed, 110 insertions(+), 10 deletions(-) diff --git a/mods/memory/hooks/register.test.ts b/mods/memory/hooks/register.test.ts index 5c9ad9c..d886ae4 100644 --- a/mods/memory/hooks/register.test.ts +++ b/mods/memory/hooks/register.test.ts @@ -4,7 +4,7 @@ import type { On } from 'claude-code' import { cap, tail, redact, normalize, failureLine, sessionOf, addFailure, entriesOf, parseIndex, isLive, lessonOf, assembleEntries, grams, - buildIndex, matchOf, + buildIndex, matchOf, deErrno, segments, suiteKeyOf, commitLabel, finishLabel, } from './register' @@ -27,6 +27,7 @@ const INDEX_OUT = [ type Proc = { stdout: string } | 'throw' | 'exit2' | 'hang' type World = { + home: string | undefined // what env.get answers for HOME switchText: string | undefined // ~/.claude/memory.json (undefined: absent) rootFails: boolean // session.root rejects id: string // what session.id answers now @@ -93,7 +94,7 @@ async function boot($: Engine, on: On, o: Opts = {}): Promise<World> { unreadable: new Set(o.unreadable ?? []), statFails: new Set(o.statFails ?? []), existsFails: new Set(o.existsFails ?? []), - proc: { stdout: INDEX_OUT }, runs: [], + proc: { stdout: INDEX_OUT }, runs: [], home: HOME, gets: 0, getsFail: false, } handStore(on, w, o.storeFails ?? false) @@ -101,7 +102,7 @@ async function boot($: Engine, on: On, o: Opts = {}): Promise<World> { w.tools.push(e.name) return { value: undefined } as never }) - on('env.get', () => ({ value: HOME })) + on('env.get', () => ({ value: w.home })) on('fs.exists', (_a, e) => { if (w.existsFails.has(e.path)) throw new Error('EIO') return { value: w.files.has(e.path) || @@ -1651,8 +1652,8 @@ for (const [name, proc] of [ w.proc = proc await failing($, w, EXIT1 + SR_LINE) const text = await pending($) - expect(text).toContain( - 'index: read blockers.md, learnings.md; status reader unavailable') + expect(text.split('\n').find(l => l.startsWith('index:'))) + .toBe('index: read blockers.md, learnings.md; status reader unavailable') expect(text).toContain('- known BLK-001 ×1 ' + SR_LINE) }) } @@ -1664,10 +1665,10 @@ test('SR5: process.run never settles, the answer comes at 2500 ms', async ( await failing($, w, EXIT1 + SR_LINE) w.proc = 'hang' const answer = pending($) - await new Promise(r => setTimeout(r, 20)) // let the call reach its wait await w.clock.advance(2500) const text = await answer - expect(text).toContain('read blockers.md, learnings.md; status reader unav') + expect(text.split('\n').find(l => l.startsWith('index:'))) + .toBe('index: read blockers.md, learnings.md; status reader unavailable') expect(text).toContain('- known BLK-001 ×1 ' + SR_LINE) }) @@ -1681,6 +1682,35 @@ test('SR7: no registry read, no process run, no unavailable note', async ( expect(text).not.toContain('status reader') }) +test('SR8: HOME unset, status unavailable, fails open', async ($, on) => { + const w = await boot($, on, { files: REGS }) + await failing($, w, EXIT1 + SR_LINE) + w.home = undefined + const text = await pending($) + expect(w.runs).toEqual([]) + expect(text.split('\n').find(l => l.startsWith('index:'))) + .toBe('index: read blockers.md, learnings.md; status reader unavailable') + expect(text).toContain('- known BLK-001 ×1 ' + SR_LINE) +}) + +test('SR9: the status word is its leading letters only', () => { + const row = '| BDR-031 | 2026-06-25 | t | superseded-by BDR-040 |' + expect(parseIndex(row).get('BDR-031')?.status).toBe('superseded') +}) + +test('TIMEindex: parseIndex on 64 KiB stays under 50 ms', () => { + const rows = [ + '| LRN-001 | 2026-01-01 | ' + 'a | '.repeat(16000) + ' | open |', + '| BLK-001 | ' + '|'.repeat(65000), + ('| LRN-002 | 2026-01-01 | t | open |\n').repeat(2000), + ] + for (const text of rows) { + const t0 = now() + parseIndex(text.slice(0, 65536)) + expect(now() - t0).toBeLessThan(50) + } +}) + test('LS1: a BDR Decision reads its first sentence', () => { expect(lessonOf('BDR', '## BDR-1 t\n- **Decision**: Use X. Then Y.\n')) .toBe('Use X.') @@ -1753,3 +1783,52 @@ test('TIMEentries: entriesOf and lessonOf on 64 KiB fields, under 50 ms', () => expect(now() - t0).toBeLessThan(50) } }) + +// ---- Task 2 (phase 4c): errno phrases out of the error index ---- + +const ER_ENTRY = '## LRN-009 e\n- **Status**: open\n' + +test('ER1: an ENOENT line never makes another ENOENT known', async ( + $, on, +) => { + const text = ER_ENTRY + + 'seen: `cat: x: No such file or directory (os error 2)`\n' + const w = await boot($, on, { files: { [LRN]: text } }) + w.proc = { stdout: '| LRN-009 | 2026-01-01 | e | open |' } + await failing($, w, + EXIT1 + "ls: cannot access '/tmp/zz': No such file or directory") + expect(await pending($)).toContain('- NEW ×1 ls: cannot access') +}) + +test('ER2: content grams still match around an errno-free line', async ( + $, on, +) => { + const text = ER_ENTRY + 'seen: `fatal: unable to access remote host thing`\n' + const w = await boot($, on, { files: { [LRN]: text } }) + w.proc = { stdout: '| LRN-009 | 2026-01-01 | e | open |' } + await failing($, w, EXIT1 + 'fatal: unable to access remote host thing') + expect(await pending($)).toContain('- known LRN-009 ×1 fatal:') +}) + +test('ER3: deErrno replaces a phrase on a normalized line', () => { + expect(deErrno('cat: <path>: no such file or directory (os error #)')) + .toBe('cat: <path>: <errno> (os error #)') + expect(deErrno('xpermission denied here')).toBe('xpermission denied here') +}) + +test('ER4: a gram of placeholders only is skipped', () => { + expect(grams('<errno> <path> # <hex>')).toEqual([]) +}) + +test('ER5: input/output error becomes <errno> despite the path rule', () => { + expect(normalize('cp: Input/output error (os error 5)')) + .toBe('cp: <errno> (os error #)') + expect(normalize('read /dev/sda1: input/output error')) + .toBe('read <path>: <errno>') +}) + +test('TIMEerrno: deErrno on 64 KiB of a phrase prefix, under 50 ms', () => { + const t0 = now() + deErrno('no such file or '.repeat(4096)) + expect(now() - t0).toBeLessThan(50) +}) diff --git a/mods/memory/hooks/register.ts b/mods/memory/hooks/register.ts index d9a4aa9..dd8cf42 100644 --- a/mods/memory/hooks/register.ts +++ b/mods/memory/hooks/register.ts @@ -112,6 +112,7 @@ const CURL_SEGMENT = new RegExp( const COOKIE_FLAG = new RegExp(`(?<=^|\\s)-b[ \\t]{1,5}${VALUE}`, 'g') const HEX_RUN = /\b[0-9a-f]{7,}\b/g +const IO_ERROR = /input\/output error/g const PATH = /(?:\.{0,2}\/)?[\w.-]{1,200}(?:\/[\w.-]{1,200}){1,30}/g /** The first `n` code units of `text` (input guard for regex work). */ @@ -156,6 +157,7 @@ export function redact(text: string): string { export function normalize(line: string): string { return line .toLowerCase() + .replace(IO_ERROR, '<errno>') // before PATH reads its slash .replace(HEX_RUN, '<hex>') .replace(PATH, '<path>') .replace(/\d+/g, '#') @@ -465,7 +467,7 @@ export function parseIndex(stdout: string): StatusMap { for (const line of stdout.split('\n')) { const m = INDEX_ROW.exec(line.slice(0, MAX_INDEX_ROW)) if (m === null) continue - const word = (m[3] ?? '').trim().match(/^[A-Za-z-]+/)?.[0] ?? '' + const word = (m[3] ?? '').trim().match(/^[A-Za-z]+/)?.[0] ?? '' const title = (m[2] ?? '').trim() rows.set(m[1] ?? '', { status: word.toLowerCase(), title }) } @@ -514,14 +516,33 @@ export function assembleEntries(texts: string[], index: StatusMap): Entry[] { }) } -const PLACEHOLDERS = new Set(['#', '<path>', '<hex>']) +export const ERRNO_PHRASES: readonly string[] = [ + 'no such file or directory', 'permission denied', 'command not found', + 'is a directory', 'not a directory', 'file exists', + 'directory not empty', 'operation not permitted', + 'no space left on device', 'connection refused', 'connection timed out', + 'broken pipe', 'resource temporarily unavailable', 'invalid argument', + 'too many open files', 'read-only file system', + 'device or resource busy', 'input/output error', +] + +// Word-bounded literals; `input/output error` is already `<errno>` here. +const ERRNO = new RegExp( + `(?<![a-z0-9])(?:${ERRNO_PHRASES.join('|')})(?![a-z0-9])`, 'g') + +/** Each errno phrase of a normalized line, as `<errno>`. */ +export function deErrno(normLine: string): string { + return normLine.replace(ERRNO, '<errno>') +} + +const PLACEHOLDERS = new Set(['#', '<path>', '<hex>', '<errno>']) /** * Every window of 4 words, except one made only of placeholders (it * carries no content); a key of fewer words has none (always NEW). */ export function grams(normLine: string): string[] { - const words = normLine.split(/[^a-z0-9<>#]+/).filter(Boolean) + const words = deErrno(normLine).split(/[^a-z0-9<>#]+/).filter(Boolean) if (words.length < GRAM_WORDS) return [] return words .slice(0, words.length - GRAM_WORDS + 1) From a75efabbf161ce918cc993d83ad0717b905763b6 Mon Sep 17 00:00:00 2001 From: bchanot <chanot.bastien@gmail.com> Date: Thu, 5 Nov 2026 16:18:39 +0100 Subject: [PATCH 09/41] feat(memory): bm25 ranking and the rerank prompt --- mods/memory/hooks/register.test.ts | 98 ++++++++++++++++++++++++++- mods/memory/hooks/register.ts | 103 +++++++++++++++++++++++++++++ 2 files changed, 200 insertions(+), 1 deletion(-) diff --git a/mods/memory/hooks/register.test.ts b/mods/memory/hooks/register.test.ts index d886ae4..d20f737 100644 --- a/mods/memory/hooks/register.test.ts +++ b/mods/memory/hooks/register.test.ts @@ -1,10 +1,12 @@ import { test, expect, mock } from 'claude-code/testing' import type { Engine, MockClock } from 'claude-code/testing' import type { On } from 'claude-code' +import type { Entry, Kind } from './register' import { cap, tail, redact, normalize, failureLine, sessionOf, addFailure, entriesOf, parseIndex, isLive, lessonOf, assembleEntries, grams, - buildIndex, matchOf, deErrno, + buildIndex, matchOf, deErrno, tokensOf, bm25Rank, rerankPrompt, + parseIds, recallLine, recallBlock, failureKey, segments, suiteKeyOf, commitLabel, finishLabel, } from './register' @@ -1832,3 +1834,97 @@ test('TIMEerrno: deErrno on 64 KiB of a phrase prefix, under 50 ms', () => { deErrno('no such file or '.repeat(4096)) expect(now() - t0).toBeLessThan(50) }) + +const mk = (id: string, title: string, lesson: string, body = ''): Entry => + ({ id, kind: id.slice(0, 3) as Kind, title, lesson, body }) + +const RB_ENTRIES = [ + mk('LRN-001', 'css grid gaps', 'Use gap.', 'layout of cards'), + mk('BLK-002', 'heredoc quoting breaks', 'Quote the delimiter.', + 'shell heredoc quoting eats the dollar sign in shell scripts'), + mk('BDR-003', 'store keys', 'Prefix them.', 'kv store naming'), +] + +test('RB1: bm25Rank puts the heredoc entry first, drops score 0', () => { + const ids = bm25Rank(RB_ENTRIES, 'quoting heredoc shell', 5).map(e => e.id) + expect(ids).toEqual(['BLK-002']) + expect(bm25Rank(RB_ENTRIES, 'the and for', 5)).toEqual([]) + expect(tokensOf('The Heredoc, a b ÉTÉ 42')).toEqual(['heredoc', 'été', '42']) +}) + +test('RB1b: ties go by numeric ID order, k bounds the result', () => { + const twin = [mk('LRN-10', 'zed', ''), mk('LRN-9', 'zed', '')] + expect(bm25Rank(twin, 'zed', 5).map(e => e.id)).toEqual(['LRN-9', 'LRN-10']) + expect(bm25Rank(twin, 'zed', 1).map(e => e.id)).toEqual(['LRN-9']) +}) + +test('RB2: parseIds keeps candidate IDs once, in order, up to max', () => { + const cands = [mk('BLK-041', 't', ''), mk('LRN-258', 't', '')] + expect(parseIds('BLK-041, BDR-999, LRN-258', cands, 3)) + .toEqual(['BLK-041', 'LRN-258']) + expect(parseIds('LRN-258 BLK-041 LRN-258', cands, 1)).toEqual(['LRN-258']) + expect(parseIds('none', cands, 3)).toEqual([]) +}) + +test('RB3: long Decisions give ellipsis lessons and a block under cap', () => { + const field = 'Use alpha ' + 'x'.repeat(1990) + const es = ['BDR-001', 'BDR-002', 'BDR-003'].map(id => + assembleEntries([`## ${id} — t\n- **Decision**: ${field}\n`], + new Map([[id, { status: 'accepted', title: 'T' + id }]]))[0]!) + for (const e of es) expect(recallLine(e).endsWith('…')).toBe(true) + const block = recallBlock(es.map(recallLine), 1500) + expect(block.length).toBeLessThanOrEqual(1500) + expect(block.split('\n')[0]).toBe('memory recall:') + expect(block.split('\n')[1]).toBe( + 'BDR-001 TBDR-001 — Use alpha ' + 'x'.repeat(280 - 11) + '…') +}) + +test('RB3b: recallLine and recallBlock edges', () => { + expect(recallLine(mk('LRN-1', 'T', 'a;'))).toBe('LRN-1 T — a;') + expect(recallLine(mk('LRN-1', 'T', 'Use X.'))).toBe('LRN-1 T — Use X.') + expect(recallLine(mk('LRN-1', 'T', ''))).toBe('LRN-1 T') + expect(recallBlock(['a'.repeat(50)], 20)).toBe('') + expect(recallBlock(['a'.repeat(50), 'bb'], 20)).toBe('memory recall:\nbb') + expect(recallBlock([], 100)).toBe('') +}) + +test('RB4: rerankPrompt is the literal prompt', () => { + const cands = [mk('LRN-1', 'T one', 'Do a.'), mk('BLK-2', 'T two', '')] + expect(rerankPrompt('fix the heredoc', cands)).toBe( + 'Prompt: fix the heredoc\nCandidates:\nLRN-1 | T one | Do a.\n' + + 'BLK-2 | T two | \nAnswer with at most 3 candidate IDs that would ' + + 'help with this prompt, comma separated, or none.') +}) + +test('RB5: 500 entries and a 64 KiB query rank under 300 ms', () => { + const es = Array.from({ length: 500 }, (_, i) => + mk(`LRN-${i + 1}`, `t${i}`, 'l', `w${i} word `.repeat(160))) + const head = 'w7 '.padEnd(2000, 'z ') + const t0 = now() + const a = bm25Rank(es, head + 'w9 '.repeat(20000), 5).map(e => e.id) + expect(now() - t0).toBeLessThan(300) + const b = bm25Rank(es, head + 'w300 '.repeat(20000), 5).map(e => e.id) + expect(a).toEqual(b) + expect(a[0]).toBe('LRN-8') +}) + +test('RB6: a secret-shaped token is redacted in the rerank prompt', () => { + const secret = 'sk_live_' + 'a'.repeat(24) + const p = rerankPrompt(`use ${secret} now`, []) + expect(p).toContain('<redacted:stripe>') + expect(p).not.toContain(secret) +}) + +test('RB7: failureKey is the normalized last line of the redacted tail', () => { + expect(failureKey('Exit code 1\nrm: /tmp/x/y: Permission denied', 'rm x')) + .toBe('rm: <path>: permission denied') + expect(failureKey('', 'ls')).toBeUndefined() +}) + +test('TIMErank: tokensOf and parseIds on 64 KiB, under 50 ms', () => { + const t0 = now() + tokensOf('ab '.repeat(21000)) + tokensOf('x'.repeat(65536)) + parseIds('BDR-1 '.repeat(10000) + 'LRN-'.repeat(15000), [], 3) + expect(now() - t0).toBeLessThan(50) +}) diff --git a/mods/memory/hooks/register.ts b/mods/memory/hooks/register.ts index dd8cf42..c06cd7a 100644 --- a/mods/memory/hooks/register.ts +++ b/mods/memory/hooks/register.ts @@ -622,6 +622,109 @@ async function statusMap($: Api, root: string): Promise<StatusMap | undefined> { } } +const STOP_WORDS = new Set( + ('the and for with that this from are was were not but you your have has ' + + 'had will can all any its into than then them they their there what ' + + 'when which who how why les des une pour dans avec est pas que qui sur ' + + 'par aux ces ses son mais ont sont plus comme').split(' '), +) +const TOKEN = /[\p{L}\p{N}]{2,40}/gu +const MAX_QUERY = 2000 +const MAX_DOC = 65536 +const BM25_K1 = 1.2 +const BM25_B = 0.75 +const MAX_PICKS = 3 + +/** Lowercase word runs (2-40 letters or digits) minus function words. */ +export function tokensOf(text: string): string[] { + const words = cap(text, MAX_DOC).toLowerCase().match(TOKEN) ?? [] + return words.filter(w => !STOP_WORDS.has(w)) +} + +type Doc = { entry: Entry; tf: Map<string, number>; len: number } + +function docOf(entry: Entry): Doc { + const tokens = tokensOf(`${entry.title} ${entry.lesson} ${entry.body}`) + const tf = new Map<string, number>() + for (const t of tokens) tf.set(t, (tf.get(t) ?? 0) + 1) + return { entry, tf, len: tokens.length } +} + +function scoreOf( + doc: Doc, terms: string[], df: Map<string, number>, n: number, avg: number, +): number { + let score = 0 + for (const term of terms) { + const f = doc.tf.get(term) ?? 0 + if (f === 0) continue + const d = df.get(term) ?? 0 + const idf = Math.log(1 + (n - d + 0.5) / (d + 0.5)) + const norm = 1 - BM25_B + (BM25_B * doc.len) / avg + score += (idf * f * (BM25_K1 + 1)) / (f + BM25_K1 * norm) + } + return score +} + +/** The `k` best entries for a query (BM25), highest first, score > 0. */ +export function bm25Rank(entries: Entry[], query: string, k: number): Entry[] { + const terms = [...new Set(tokensOf(cap(query, MAX_QUERY)))] + const docs = entries.map(docOf) + const df = new Map<string, number>() + for (const d of docs) for (const t of d.tf.keys()) { + df.set(t, (df.get(t) ?? 0) + 1) + } + const avg = docs.reduce((sum, d) => sum + d.len, 0) / (docs.length || 1) + return docs + .map(d => ({ e: d.entry, s: scoreOf(d, terms, df, docs.length, avg || 1) })) + .filter(x => x.s > 0) + .sort((a, b) => b.s - a.s || + a.e.id.localeCompare(b.e.id, 'en', { numeric: true })) + .slice(0, k) + .map(x => x.e) +} + +/** The haiku prompt: the redacted user prompt and one line per candidate. */ +export function rerankPrompt(query: string, cands: Entry[]): string { + const lines = cands.map(c => `${c.id} | ${c.title} | ${c.lesson}`) + return ( + `Prompt: ${redact(cap(query, MAX_QUERY))}\nCandidates:\n` + + `${lines.join('\n')}\nAnswer with at most ${MAX_PICKS} candidate IDs ` + + 'that would help with this prompt, comma separated, or none.' + ) +} + +const ID_IN_ANSWER = /(?:BDR|LRN|BLK)-\d{1,5}/g + +/** The candidate IDs named in a model answer, deduplicated, in order. */ +export function parseIds(text: string, cands: Entry[], max: number): string[] { + const known = new Set(cands.map(c => c.id)) + const found = cap(text, MAX_REGEX_INPUT).match(ID_IN_ANSWER) ?? [] + return [...new Set(found)].filter(id => known.has(id)).slice(0, max) +} + +/** One recall line; the lesson keeps its own terminator. */ +export function recallLine(e: Entry): string { + const head = `${e.id} ${e.title}` + return e.lesson === '' ? head : `${head} — ${e.lesson}` +} + +/** The injected block; a line that would pass `max` characters is dropped. */ +export function recallBlock(lines: string[], max: number): string { + const header = 'memory recall:' + let block = header + for (const line of lines) { + if (block.length + 1 + line.length <= max) block += `\n${line}` + } + return block === header ? '' : block +} + +/** The dedup key of a failure text, as `buildFailure` stores it. */ +export function failureKey(text: string, command: string): string | undefined { + void command // the key comes from the output only; kept for the harness + const line = lastLine(redact(tail(text, MAX_REGEX_INPUT))) + return line === undefined ? undefined : normalize(line) +} + type Registries = { entries: Entry[] status: StatusMap | undefined From acbfd71327023fac6216d288838994fac4010638 Mon Sep 17 00:00:00 2001 From: bchanot <chanot.bastien@gmail.com> Date: Thu, 5 Nov 2026 16:28:54 +0100 Subject: [PATCH 10/41] feat(memory): recall switch, injection log and per-context ledger --- mods/memory/hooks/register.test.ts | 222 ++++++++++++++++++++++++++++- mods/memory/hooks/register.ts | 205 ++++++++++++++++++++++++-- 2 files changed, 412 insertions(+), 15 deletions(-) diff --git a/mods/memory/hooks/register.test.ts b/mods/memory/hooks/register.test.ts index d20f737..4d60057 100644 --- a/mods/memory/hooks/register.test.ts +++ b/mods/memory/hooks/register.test.ts @@ -8,7 +8,10 @@ import { buildIndex, matchOf, deErrno, tokensOf, bm25Rank, rerankPrompt, parseIds, recallLine, recallBlock, failureKey, segments, suiteKeyOf, commitLabel, finishLabel, + newState, switchOf, claim, onContextStart, resetContext, endContext, + appendLog, loadLog, RECALL_CAP, } from './register' +import type { LogRecord } from './register' const HOME = '/home/t' const SWITCH = `${HOME}/.claude/memory.json` @@ -157,6 +160,7 @@ async function boot($: Engine, on: On, o: Opts = {}): Promise<World> { on('tool.call', { tool: 'Bash' }, (_a, e) => (w.byCommand.get(e.command) ?? w.answer) as never) on('session.end', (_a, e) => ({ sessionId: e.sessionId })) + on('classic.SessionStart', () => ({})) await $.session.start({ cwd: '/tmp', surface: null, isInteractive: false }) return w } @@ -1772,7 +1776,7 @@ test('assembleEntries joins kind, memory.sh title, lesson and body', () => { expect(assembleEntries([body], new Map())[0]?.title).toBe('') }) -test('TIMEentries: entriesOf and lessonOf on 64 KiB fields, under 50 ms', () => { +test('TIMEentries: entriesOf, lessonOf on 64 KiB fields, under 50 ms', () => { const bodies = [ '## BLK-001 x\n- Solution: ' + 'a'.repeat(65536 - 26), '## BLK-001 x\n- Solution: ' + 'a. '.repeat(21000), @@ -1919,6 +1923,18 @@ test('RB7: failureKey is the normalized last line of the redacted tail', () => { expect(failureKey('Exit code 1\nrm: /tmp/x/y: Permission denied', 'rm x')) .toBe('rm: <path>: permission denied') expect(failureKey('', 'ls')).toBeUndefined() + expect(failureKey('make: *** [all] Error 2', 'make')).toBeUndefined() +}) + +test('RB6b: a secret straddling char 2000 of the query is redacted', () => { + const secret = 'sk_live_' + 'a'.repeat(24) + const q = 'x'.repeat(1979) + ' ' + secret + ' tail' + const p = rerankPrompt(q, []) + expect(q.indexOf(secret)).toBeLessThan(2000) + expect(q.indexOf(secret) + secret.length).toBeGreaterThan(2000) + expect(p).toContain('<redacted:stripe>') + expect(p).not.toContain('sk_live_') + expect(p).not.toContain('aaaa') }) test('TIMErank: tokensOf and parseIds on 64 KiB, under 50 ms', () => { @@ -1928,3 +1944,207 @@ test('TIMErank: tokensOf and parseIds on 64 KiB, under 50 ms', () => { parseIds('BDR-1 '.repeat(10000) + 'LRN-'.repeat(15000), [], 3) expect(now() - t0).toBeLessThan(50) }) + +// ---- recall: switch key, injection log, per-context ledger ------------- + +test('SW1: no enabled key with "recall": false logs nothing', async ( + $, on, +) => { + const w = await boot($, on, { switchText: '{"recall": false}' }) + await bash($, 'ls') + expect(w.logs).toEqual([]) + expect(w.tools).toEqual(['memory_pending']) +}) + +test('SW2: a non-boolean "recall" logs one line, recall stays on', async ( + $, on, +) => { + const w = await boot($, on, { switchText: '{"recall": "no"}' }) + await bash($, 'ls') + await bash($, 'ls') + expect(w.logs).toEqual([ + 'memory: ~/.claude/memory.json has no boolean "recall", ' + + 'recall stays on', + ]) + expect(w.tools).toEqual(['memory_pending']) +}) + +test('SW3: switchOf reads the two keys', () => { + const $ = { ui: { log: () => undefined } } as never + const of = (data: unknown) => switchOf($, newState(), data) + expect(of({})).toEqual({ enabled: true, recall: true }) + expect(of({ recall: false })).toEqual({ enabled: true, recall: false }) + expect(of({ recall: 'no' })).toEqual({ enabled: true, recall: true }) + expect(of({ enabled: false })).toEqual({ enabled: false, recall: false }) + expect(of({ enabled: false, recall: true })) + .toEqual({ enabled: false, recall: false }) + expect(of(null)).toEqual({ enabled: true, recall: true }) +}) + +test('SW4: enabled false turns everything off, silently', async ($, on) => { + const w = await boot($, on, { switchText: '{"enabled": false}' }) + await failing($, w, 'Exit code 1\nfatal: bad thing') + expect(w.logs).toEqual([]) + expect(w.tools).toEqual([]) + expect(w.sets).toEqual([]) +}) + +/** A state that holds injections for two sessions and an agent. */ +function ledger() { + const st = newState() + for (const key of ['s1:main', 's1:a1', 's2:main']) { + st.seen.set(key, new Set(['BLK-001'])) + st.spent.set(key, 100) + } + return st +} + +test('CS1: startup, clear and compact reset the session, mark it fresh', + () => { + for (const source of ['startup', 'clear', 'compact']) { + const st = ledger() + resetContext(st, source, 's1', undefined) + expect([...st.seen.keys()]).toEqual(['s2:main']) + expect([...st.spent.keys()]).toEqual(['s2:main']) + expect([...st.fresh]).toEqual(['s1']) + } + }) + +test('CS2: resume and fork change nothing', () => { + const st = ledger() + resetContext(st, 'resume', 's1', undefined) + resetContext(st, 'fork', 's1', undefined) + expect([...st.seen.keys()]).toEqual(['s1:main', 's1:a1', 's2:main']) + expect([...st.spent.values()]).toEqual([100, 100, 100]) + expect(st.fresh.size).toBe(0) +}) + +test('CS3: an agent start resets only that agent key', () => { + const st = ledger() + resetContext(st, 'startup', 's1', 'a1') + expect([...st.seen.keys()]).toEqual(['s1:main', 's2:main']) + expect([...st.spent.keys()]).toEqual(['s1:main', 's2:main']) + expect(st.fresh.size).toBe(0) +}) + +test('CS4: the classic SessionStart event passes through the hook', + async ($, on) => { + const w = await boot($, on) + const out = await $.classic.SessionStart({ + hook_event_name: 'SessionStart', transcript_path: '/t', cwd: ROOT, + session_id: 's1', source: 'compact', + } as never) + expect(out).toEqual({}) + expect(w.logs).toEqual([]) + }) + +test('CS5: endContext clears only the ending session', () => { + const st = ledger() + for (const id of ['s1', 's2']) { + st.fresh.add(id) + st.lastPrompt.set(id, 5) + } + endContext(st, 's1') + expect([...st.seen.keys()]).toEqual(['s2:main']) + expect([...st.spent.keys()]).toEqual(['s2:main']) + expect([...st.fresh]).toEqual(['s2']) + expect([...st.lastPrompt.keys()]).toEqual(['s2']) +}) + +test('onContextStart is the one reset: forgets then marks fresh', () => { + const st = ledger() + onContextStart(st, 's2') + expect([...st.seen.keys()]).toEqual(['s1:main', 's1:a1']) + expect([...st.fresh]).toEqual(['s2']) +}) + +test('CL1: claim returns the unseen IDs that fit and records them', () => { + const st = newState() + const got = claim(st, 'k', ['A-1', 'B-2', 'C-3'], [400, 400, 400]) + expect(got).toEqual(['A-1', 'B-2', 'C-3']) + expect(st.spent.get('k')).toBe(1200) + expect([...(st.seen.get('k') ?? [])]).toEqual(['A-1', 'B-2', 'C-3']) +}) + +test('CL2: claim excludes the seen and stops at the budget', () => { + const st = newState() + expect(claim(st, 'k', ['A-1'], [900])).toEqual(['A-1']) + // A-1 is seen; B-2 (700) would pass 1500, C-3 (600) fits exactly + expect(claim(st, 'k', ['A-1', 'B-2', 'C-3'], [900, 700, 600])) + .toEqual(['C-3']) + expect(st.spent.get('k')).toBe(RECALL_CAP) + expect(st.seen.get('k')?.has('B-2')).toBe(false) + expect(claim(st, 'k', ['B-2'], [1])).toEqual([]) +}) + +test('CL3: claim keys are independent', () => { + const st = newState() + claim(st, 's1:main', ['A-1'], [1500]) + expect(claim(st, 's1:a1', ['A-1'], [1500])).toEqual(['A-1']) +}) + +/** The plugin's $.store over the world's Map, for the pure log calls. */ +const storeApi = (w: World) => ({ store: { + get: async (k: string) => w.kv.get(k), + set: async (k: string, v: unknown) => { + w.sets.push(k) + w.kv.set(k, JSON.parse(JSON.stringify(v))) + }, +} }) as never + +const REC = (at: number, ids = ['BLK-001']): LogRecord => + ({ at, session: 's1', agent: 'main', channel: 'prompt', ids }) + +test('LG1: a log in l:<root> survives a capture and a sweep', async ( + $, on, +) => { + const big = (id: string, at: number) => ({ + id, at, milestones: [], red: [], + failures: [{ key: 'k', line: 'l', excerpt: 'x'.repeat(600000), + command: 'c', agent: false, at, count: 1 }], + }) + const seed = { + 'l:/work/app': [REC(7)], + 'p:/other': { sessions: [big('o2', 20), big('o1', 10)] }, + } + const w = await boot($, on, { seed }) + await failing($, w, EXIT1 + 'fatal: bad thing') + expect(projectOf(w, '/other')?.sessions.map(s => s.id)).toEqual(['o2']) + expect(w.kv.get('l:/work/app')).toEqual([REC(7)]) + expect(projectOf(w)?.sessions).toHaveLength(1) +}) + +test('LG2: 205 appends keep the newest 200', async ($, on) => { + const w = await boot($, on) + const st = newState() + const api = storeApi(w) + for (let at = 0; at < 205; at++) await appendLog(api, st, ROOT, REC(at)) + const log = w.kv.get(`l:${ROOT}`) as LogRecord[] + expect(log).toHaveLength(200) + expect(log[0]?.at).toBe(5) + expect(log[199]?.at).toBe(204) + expect(w.sets.every(k => k === `l:${ROOT}`)).toBe(true) +}) + +test('LG3: over 64 KiB serialized, the oldest records are dropped', + async ($, on) => { + const w = await boot($, on) + const st = newState() + const ids = ['X'.repeat(10000)] + for (let at = 0; at < 10; at++) { + await appendLog(storeApi(w), st, ROOT, REC(at, ids)) + } + const log = w.kv.get(`l:${ROOT}`) as LogRecord[] + expect(log.map(r => r.at)).toEqual([4, 5, 6, 7, 8, 9]) + expect(JSON.stringify(log).length).toBeLessThanOrEqual(65536) + }) + +test('LG4: loadLog drops malformed records; project key untouched', + async ($, on) => { + const bad = { at: 'x', session: 's1', agent: 'main', ids: [] } + const w = await boot($, on, { seed: { + [`l:${ROOT}`]: [REC(1), bad, null, { ...REC(2), channel: 'x' }], + } }) + expect(await loadLog(storeApi(w), ROOT)).toEqual([REC(1)]) + expect(w.kv.has(`p:${ROOT}`)).toBe(false) + }) diff --git a/mods/memory/hooks/register.ts b/mods/memory/hooks/register.ts index c06cd7a..d009031 100644 --- a/mods/memory/hooks/register.ts +++ b/mods/memory/hooks/register.ts @@ -9,13 +9,24 @@ type Api = EngineInterface type State = { enabled: boolean | null // null: not read yet this session + recall: boolean | null // the "recall" key, read with `enabled` warned: Set<string> pending: string[] // milestones not yet shown in a note writes: Promise<void> // the one chain every store write runs on + seen: Map<string, Set<string>> // context key -> injected IDs + spent: Map<string, number> // context key -> chars injected + fresh: Set<string> // sessions whose next qualifying prompt starts a context + lastPrompt: Map<string, number> // session id -> time of its last prompt } +export const IDLE_MS = 1800000 +export const RECALL_CAP = 1500 +export const HAIKU = 'claude-haiku-5-5' +export const RERANK_MS = 3000 + const SWITCH_FILE = '.claude/memory.json' const MAX_SWITCH_BYTES = 65536 +const CONTEXT_STARTS = new Set(['startup', 'clear', 'compact']) const TOOL = 'memory_pending' const SERVED_TOOL = 'mcp__memory__memory_pending' const SWITCH_UNREADABLE = @@ -23,6 +34,9 @@ const SWITCH_UNREADABLE = const SWITCH_INVALID = 'memory: ~/.claude/memory.json has no boolean "enabled", capture stays on' +const SWITCH_RECALL_INVALID = + 'memory: ~/.claude/memory.json has no boolean "recall", recall stays on' + const MAX_REGEX_INPUT = 65536 const PEM = '-----' const PEM_KIND = '(?:[A-Z]+ )?PRIVATE KEY' @@ -686,8 +700,10 @@ export function bm25Rank(entries: Entry[], query: string, k: number): Entry[] { /** The haiku prompt: the redacted user prompt and one line per candidate. */ export function rerankPrompt(query: string, cands: Entry[]): string { const lines = cands.map(c => `${c.id} | ${c.title} | ${c.lesson}`) + // redact first: a secret straddling the cut would escape its pattern + const asked = cap(redact(cap(query, MAX_REGEX_INPUT)), MAX_QUERY) return ( - `Prompt: ${redact(cap(query, MAX_QUERY))}\nCandidates:\n` + + `Prompt: ${asked}\nCandidates:\n` + `${lines.join('\n')}\nAnswer with at most ${MAX_PICKS} candidate IDs ` + 'that would help with this prompt, comma separated, or none.' ) @@ -721,6 +737,7 @@ export function recallBlock(lines: string[], max: number): string { /** The dedup key of a failure text, as `buildFailure` stores it. */ export function failureKey(text: string, command: string): string | undefined { void command // the key comes from the output only; kept for the harness + if (!EXIT_CODE.test(text)) return undefined const line = lastLine(redact(tail(text, MAX_REGEX_INPUT))) return line === undefined ? undefined : normalize(line) } @@ -881,6 +898,57 @@ function queueWrite(st: State, job: () => Promise<void>): Promise<void> { return run } +export type LogRecord = { + at: number + session: string + agent: string + channel: 'prompt' | 'tool' + ids: string[] +} + +const LOG_PREFIX = 'l:' +const MAX_LOG = 200 +const MAX_LOG_BYTES = 65536 + +function isLogRecord(v: unknown): v is LogRecord { + const r = v as Partial<LogRecord> | null + return typeof r === 'object' && r !== null && + typeof r.at === 'number' && typeof r.session === 'string' && + typeof r.agent === 'string' && + (r.channel === 'prompt' || r.channel === 'tool') && + Array.isArray(r.ids) && r.ids.every(i => typeof i === 'string') +} + +const logKey = (root: string) => LOG_PREFIX + root.slice(0, MAX_ROOT) + +/** The injection log of a project; malformed records are dropped. */ +export async function loadLog($: Api, root: string): Promise<LogRecord[]> { + const raw = await $.store.get(logKey(root)) + return Array.isArray(raw) ? raw.filter(isLogRecord) : [] +} + +/** The newest records that fit MAX_LOG and MAX_LOG_BYTES serialized. */ +function fitLog(log: LogRecord[]): LogRecord[] { + let kept = log.slice(-MAX_LOG) + while (kept.length > 0 && JSON.stringify(kept).length > MAX_LOG_BYTES) { + kept = kept.slice(1) + } + return kept +} + +/** Appends an injection record on the write chain; the oldest fall off. */ +export function appendLog( + $: Api, + st: State, + root: string, + record: LogRecord, +): Promise<void> { + return queueWrite(st, async () => { + const log = await loadLog($, root) + await $.store.set(logKey(root), fitLog([...log, record])) + }) +} + type Where = { root: string; id: string } /** Load, change the current session, save; sweeps when it is created. */ @@ -970,12 +1038,17 @@ export function finishLabel(command: string): string | undefined { return undefined } -function newState(): State { +export function newState(): State { return { enabled: null, + recall: null, warned: new Set(), pending: [], writes: Promise.resolve(), + seen: new Map(), + spent: new Map(), + fresh: new Set(), + lastPrompt: new Map(), } } @@ -995,28 +1068,43 @@ function logOnce(st: State, $: Api, key: string, text: string): void { } } +type Switch = { enabled: boolean; recall: boolean } + /** - * True unless the user's switch file says `enabled: false`. A file that - * exists but cannot be read or parsed keeps capture on and logs one line. + * The switch file's two keys. An absent key is on; a present non-boolean + * logs one line and counts as absent. `enabled: false` cuts recall too. */ -async function loadEnabled($: Api, st: State): Promise<boolean> { +export function switchOf($: Api, st: State, data: unknown): Switch { + const keys = (data ?? {}) as { enabled?: unknown; recall?: unknown } + if (keys.enabled !== undefined && typeof keys.enabled !== 'boolean') { + logOnce(st, $, 'switch', SWITCH_INVALID) + } + if (keys.recall !== undefined && typeof keys.recall !== 'boolean') { + logOnce(st, $, 'switch-recall', SWITCH_RECALL_INVALID) + } + const enabled = keys.enabled !== false + return { enabled, recall: enabled && keys.recall !== false } +} + +/** + * The user's switch file. A file that exists but cannot be read or parsed + * keeps everything on and logs one line. + */ +async function loadEnabled($: Api, st: State): Promise<Switch> { + const on = { enabled: true, recall: true } let path = '' try { const home = await $.env.get('HOME') - if (!home) return true + if (!home) return on path = `${home}/${SWITCH_FILE}` const info = await $.fs.stat(path) - if (info.kind !== 'file' || info.size > MAX_SWITCH_BYTES) return true - const data: unknown = JSON.parse(await $.fs.read(path)) - const enabled = (data as { enabled?: unknown } | null)?.enabled - if (typeof enabled === 'boolean') return enabled - logOnce(st, $, 'switch', SWITCH_INVALID) - return true + if (info.kind !== 'file' || info.size > MAX_SWITCH_BYTES) return on + return switchOf($, st, JSON.parse(await $.fs.read(path))) } catch { if (path !== '' && !(await isGone($, path))) { logOnce(st, $, 'switch', SWITCH_UNREADABLE) } - return true + return on } } @@ -1048,11 +1136,62 @@ async function registerTool($: Api): Promise<void> { */ async function ensureEnabled($: Api, st: State): Promise<boolean> { if (st.enabled !== null) return st.enabled - st.enabled = await loadEnabled($, st) + const sw = await loadEnabled($, st) + st.enabled = sw.enabled + st.recall = sw.recall if (st.enabled) await registerTool($) return st.enabled } +/** True when the mod is on and the "recall" key does not turn it off. */ +async function ensureRecall($: Api, st: State): Promise<boolean> { + return (await ensureEnabled($, st)) && st.recall === true +} + +const contextKey = (session: string, agent: string | undefined) => + `${session}:${agent ?? 'main'}` + +/** Forgets what a session's contexts injected. */ +function forgetContexts(st: State, session: string): void { + for (const map of [st.seen, st.spent]) { + for (const key of [...map.keys()]) { + if (key.startsWith(`${session}:`)) map.delete(key) + } + } +} + +/** A new context: nothing injected yet, the next prompt may recall. */ +export function onContextStart(st: State, session: string): void { + forgetContexts(st, session) + st.fresh.add(session) +} + +/** + * Takes the IDs not yet seen in the context whose line costs (`chars`, + * parallel to `ids`) still fit RECALL_CAP, and records them. Synchronous: + * called after the last await, so two racing callers never both claim. + */ +export function claim( + st: State, + key: string, + ids: string[], + chars: number[], +): string[] { + const seen = st.seen.get(key) ?? new Set<string>() + let spent = st.spent.get(key) ?? 0 + const taken: string[] = [] + ids.forEach((id, i) => { + const cost = chars[i] ?? 0 + if (seen.has(id) || spent + cost > RECALL_CAP) return + seen.add(id) + spent += cost + taken.push(id) + }) + st.seen.set(key, seen) + st.spent.set(key, spent) + return taken +} + /** The tool's answer; reads the store and the registries, writes nothing. */ async function pendingAnswer($: Api, st: State): Promise<string> { if (!(await ensureEnabled($, st))) return OFF_TEXT @@ -1076,6 +1215,41 @@ function registerPending(on: On, st: State): void { }) } +/** The ending session's recall state; other sessions keep theirs. */ +export function endContext(st: State, session: string): void { + forgetContexts(st, session) + st.fresh.delete(session) + st.lastPrompt.delete(session) +} + +/** + * A context starts on startup, clear and compact (not resume or fork). + * An agent's start resets that agent's key only. + */ +export function resetContext( + st: State, + source: string, + session: string, + agent: string | undefined, +): void { + if (!CONTEXT_STARTS.has(source)) return + if (agent === undefined) return onContextStart(st, session) + const key = contextKey(session, agent) + st.seen.delete(key) + st.spent.delete(key) +} + +function registerContext(on: On, st: State): void { + on('classic.SessionStart', async ($, e, next) => { + const session = e.session_id ?? await $.session.id() + resetContext(st, e.source, session, e.agent_id) + return next(e) + }).catch(($, e, next) => { + warnOnce(st, $, 'SessionStart', next.error.kind) + return next(e) + }) +} + function registerSession(on: On, st: State): void { on('session.start', async ($, e, next) => { await ensureEnabled($, st) @@ -1086,8 +1260,10 @@ function registerSession(on: On, st: State): void { }) on('session.end', async ($, e, next) => { st.enabled = null + st.recall = null st.pending = [] st.warned.clear() + endContext(st, e.sessionId) return next(e) }).catch(($, e, next) => { warnOnce(st, $, 'session.end', next.error.kind) @@ -1258,6 +1434,7 @@ function registerPrompt(on: On, st: State): void { export const register: Register = on => { const st = newState() registerSession(on, st) + registerContext(on, st) registerBash(on, st) registerPending(on, st) registerPrompt(on, st) From 3bb2eafb0cc15ce2b905e58f38eee92ab3fbd568 Mon Sep 17 00:00:00 2001 From: bchanot <chanot.bastien@gmail.com> Date: Thu, 5 Nov 2026 16:41:34 +0100 Subject: [PATCH 11/41] feat(memory): intent recall at the prompt, once per context --- mods/memory/hooks/register.test.ts | 422 ++++++++++++++++++++++++++++- mods/memory/hooks/register.ts | 204 +++++++++++++- 2 files changed, 609 insertions(+), 17 deletions(-) diff --git a/mods/memory/hooks/register.test.ts b/mods/memory/hooks/register.test.ts index 4d60057..5743f97 100644 --- a/mods/memory/hooks/register.test.ts +++ b/mods/memory/hooks/register.test.ts @@ -1,6 +1,6 @@ import { test, expect, mock } from 'claude-code/testing' import type { Engine, MockClock } from 'claude-code/testing' -import type { On } from 'claude-code' +import type { On, EngineInterface as Api } from 'claude-code' import type { Entry, Kind } from './register' import { cap, tail, redact, normalize, failureLine, sessionOf, addFailure, @@ -9,7 +9,8 @@ import { parseIds, recallLine, recallBlock, failureKey, segments, suiteKeyOf, commitLabel, finishLabel, newState, switchOf, claim, onContextStart, resetContext, endContext, - appendLog, loadLog, RECALL_CAP, + appendLog, loadLog, RECALL_CAP, isTrigger, promptContext, + DESIGN_RULE, ANALYSIS_RULE, HAIKU, RERANK_MS, IDLE_MS, } from './register' import type { LogRecord } from './register' @@ -31,6 +32,15 @@ const INDEX_OUT = [ /** How the process bottom answers: a stdout, or a way to fail. */ type Proc = { stdout: string } | 'throw' | 'exit2' | 'hang' +/** How the model bottom answers: a text, a non-answer, or a failure. */ +type Model = { text: string } | 'unanswered' | 'throw' | 'hang' + +/** What the model bottom was asked. */ +type Ask = { + model: string; prompt: string; effort: unknown + maxTokens: unknown; timeoutMs: unknown +} + type World = { home: string | undefined // what env.get answers for HOME switchText: string | undefined // ~/.claude/memory.json (undefined: absent) @@ -52,6 +62,8 @@ type World = { runs: string[][] // every process.run argv gets: number // store.get calls getsFail: boolean // store.get throws + model: Model // what `model.complete` does now + asks: Ask[] // every model.complete call } type Opts = { @@ -100,7 +112,7 @@ async function boot($: Engine, on: On, o: Opts = {}): Promise<World> { statFails: new Set(o.statFails ?? []), existsFails: new Set(o.existsFails ?? []), proc: { stdout: INDEX_OUT }, runs: [], home: HOME, - gets: 0, getsFail: false, + gets: 0, getsFail: false, model: { text: 'none' }, asks: [], } handStore(on, w, o.storeFails ?? false) on('tool.register', (_a, e) => { @@ -147,6 +159,19 @@ async function boot($: Engine, on: On, o: Opts = {}): Promise<World> { return { value: { ...done, stderr: '', isStdoutTruncated: false, isStderrTruncated: false } } }) + on('model.complete', async (_a, e) => { + const x = e as unknown as Ask + w.asks.push({ model: x.model, prompt: x.prompt, effort: x.effort, + maxTokens: x.maxTokens, timeoutMs: x.timeoutMs }) + if (w.model === 'throw') throw new Error('api down') + if (w.model === 'hang') await new Promise(() => undefined) + const usage = { input_tokens: 0, output_tokens: 0 } + const done = w.model === 'unanswered' + ? { isAnswered: false, reason: 'api-error', status: 500, + error: 'server_error', usage } + : { isAnswered: true, text: w.model.text, usage } + return { value: done } as never + }) on('session.root', () => { if (w.rootFails) throw new Error('no root') return { value: w.root } @@ -2148,3 +2173,394 @@ test('LG4: loadLog drops malformed records; project key untouched', expect(await loadLog(storeApi(w), ROOT)).toEqual([REC(1)]) expect(w.kv.has(`p:${ROOT}`)).toBe(false) }) + +// ---- intent recall at the prompt --------------------------------------- + +const DECISIONS = `${REG}/decisions.md` +const entryText = (id: string, title: string, label: string, lesson: string) => + `## ${id} \u2014 ${title}\n- **Status**: open\n- **${label}**: ${lesson}\n` +const rowsOut = (rows: [string, string][]) => [ + '.claude/memory/x.md', '', '| ID | Date | Title | Status |', + '|---|---|---|---|', + ...rows.map(([id, title]) => `| ${id} | 2026-01-01 | ${title} | open |`), '', +].join('\n') + +const BLK1_LINE = 'BLK-001 mod design \u2014 Keep the suite small and ' + + 'concevoir the mod first.' +const BLK1 = entryText('BLK-001', 'mod design', 'Solution', + 'Keep the suite small and concevoir the mod first.') +const LRN2 = entryText('LRN-002', 'design notes', 'Pattern', + 'Write design notes before coding.') +const REC_FILES = { [BLK]: BLK1, [LRN]: LRN2 } +const REC_INDEX = rowsOut([['BLK-001', 'mod design'], + ['LRN-002', 'design notes']]) + +const GO = 'on va concevoir la suite du mod' +const DESIGN = 'design the mod suite please' +const NOTES = 'write notes about the mod now' + +/** Boots the notes world with recall fixtures; the model picks BLK-001. */ +async function bootRecall($: Engine, on: On, o: Opts = {}) { + const r = await bootNotes($, on, { files: REC_FILES, ...o }) + r.w.proc = { stdout: REC_INDEX } + r.w.model = { text: 'BLK-001' } + return r +} + +const start = ($: Engine, source = 'startup') => $.classic.SessionStart({ + hook_event_name: 'SessionStart', transcript_path: '/t', cwd: ROOT, + session_id: 's1', source, +} as never) + +const say = ($: Engine, text: string, turnId?: string) => $.prompt.submit({ + text, wait: turnId !== undefined, origin: { kind: 'composer' }, + ...(turnId === undefined ? {} : { turnId }), +}) + +const BLOCK1 = `memory recall:\n${BLK1_LINE}` + +test('IR1: the first prompt of a context asks and injects the block', + async ($, on) => { + const { w, seen } = await bootRecall($, on) + await start($) + await say($, GO) + expect(w.asks).toHaveLength(1) + expect(w.asks[0]).toMatchObject({ model: 'claude-haiku-5-5', + effort: 'low', maxTokens: 64, timeoutMs: 3000 }) + expect(w.asks[0]?.prompt).toContain('BLK-001 | mod design | ') + expect(seen).toEqual([[BLOCK1]]) + }) + +test('IR2 IR3: an ordinary prompt 1 min later is silent, 31 min asks', + async ($, on) => { + const { w, seen } = await bootRecall($, on) + await start($) + await say($, GO) + await w.clock.advance(60000) + await say($, NOTES) + expect(w.asks).toHaveLength(1) + expect(seen[1]).toBeUndefined() + await w.clock.advance(1860000) + await say($, NOTES) + expect(w.asks).toHaveLength(2) + }) + +test('IR4: slash, mid-turn, sdk and short prompts never ask', async ( + $, on, +) => { + const { w, seen } = await bootRecall($, on) + await start($) + await say($, '/feat add design notes') + await say($, DESIGN, 'u1') + await $.prompt.submit({ text: DESIGN, wait: false, origin: { kind: 'sdk' } }) + await say($, 'design note') + expect(w.asks).toEqual([]) + expect(seen.every(c => c === undefined)).toBe(true) + await say($, DESIGN) + expect(w.asks).toHaveLength(1) +}) + +test('IR5: an ID that is not a candidate is never injected', async ( + $, on, +) => { + const { w, seen } = await bootRecall($, on) + w.model = { text: 'BDR-999, BLK-001' } + await start($) + await say($, GO) + expect(seen).toEqual([[BLOCK1]]) +}) + +test('IR5b: none, an unanswered call and a throw add nothing', async ( + $, on, +) => { + const { w, seen } = await bootRecall($, on) + await start($) + for (const m of [{ text: 'none' }, 'unanswered', 'throw'] as Model[]) { + w.model = m + await say($, DESIGN) + } + expect(w.asks).toHaveLength(3) + expect(seen.every(c => c === undefined)).toBe(true) +}) + +test('IR5c: a call that never settles passes after RERANK_MS', async ( + $, on, +) => { + const { w, seen } = await bootRecall($, on) + w.model = 'hang' + await start($) + const p = say($, DESIGN) + await w.clock.advance(RERANK_MS) + await p + expect(w.asks).toHaveLength(1) + expect(seen).toEqual([undefined]) +}) + +test('IR6: compact starts a new context, resume does not', async ($, on) => { + const { w, seen } = await bootRecall($, on) + await start($) + await say($, GO) + await start($, 'compact') + await say($, GO) + expect(w.asks).toHaveLength(2) + expect(seen).toEqual([[BLOCK1], [BLOCK1]]) + await start($, 'resume') + await say($, NOTES) + expect(w.asks).toHaveLength(2) +}) + +test('IR7: BLK-001 is injected once, later asks never list it', async ( + $, on, +) => { + const { w, seen } = await bootRecall($, on) + await start($) + for (let i = 0; i < 3; i++) await say($, DESIGN) + expect(w.asks).toHaveLength(3) + expect(w.asks[1]?.prompt).not.toContain('BLK-001') + expect(w.asks[2]?.prompt).not.toContain('BLK-001') + expect(seen).toEqual([[BLOCK1], undefined, undefined]) +}) + +test('IR8: every candidate already seen means no ask at all', async ( + $, on, +) => { + const { w } = await bootRecall($, on, { files: { [BLK]: BLK1 } }) + await start($) + await say($, DESIGN) + await say($, DESIGN) + expect(w.asks).toHaveLength(1) +}) + +test('IR9: "recall": false asks nothing, the note still attaches', async ( + $, on, +) => { + const { w, seen } = await bootRecall($, on, + { switchText: '{"enabled": true, "recall": false}' }) + await start($) + await run($, w, 'git commit -m "fix: y"') + await say($, DESIGN) + expect(w.asks).toEqual([]) + expect(seen[0]).toHaveLength(1) + expect(seen[0]?.[0]).toContain('memory: commit fix: y') +}) + +test('IR9b: a non-boolean "recall" logs one line, recall stays on', async ( + $, on, +) => { + const { w, seen } = await bootRecall($, on, + { switchText: '{"recall": "no"}' }) + await start($) + await say($, GO) + expect(seen).toEqual([[BLOCK1]]) + expect(w.logs).toEqual([ + 'memory: ~/.claude/memory.json has no boolean "recall", recall stays on', + ]) +}) + +for (const proc of ['throw', 'exit2'] as const) { + test(`IR10: status reader ${proc}: no ask, prompt unchanged`, async ( + $, on, + ) => { + const { w, seen } = await bootRecall($, on) + w.proc = proc + await start($) + await say($, GO) + expect(w.asks).toEqual([]) + expect(seen).toEqual([undefined]) + }) +} + +test('IR11: an injection leaves one log record; 205 keep 200', async ( + $, on, +) => { + const { w } = await bootRecall($, on) + await start($) + await say($, GO) + expect(await loadLog(storeApi(w), ROOT)).toEqual([ + { at: 1000, session: 's1', agent: 'main', channel: 'prompt', + ids: ['BLK-001'] }, + ]) + for (let i = 0; i < 204; i++) { + await start($, 'clear') + await say($, GO) + } + expect(await loadLog(storeApi(w), ROOT)).toHaveLength(200) +}) + +test('IR12: a pending milestone and a trigger give [note, block]', async ( + $, on, +) => { + const { w, seen } = await bootRecall($, on) + await start($) + await run($, w, 'git commit -m "fix: y"') + await say($, GO) + expect(seen).toHaveLength(1) + expect(seen[0]?.[0]).toContain('memory: commit fix: y') + expect(seen[0]?.[1]).toBe(BLOCK1) +}) + +test('registries load once per prompt for the note and the recall', async ( + $, on, +) => { + const { w } = await bootRecall($, on) + await start($) + await run($, w, 'git commit -m "fix: y"') + const before = w.runs.length + await say($, GO) + expect(w.runs.length - before).toBe(1) +}) + +test('RP1: 3 failed reranks in a row pause it 15 min, a success resets', + async ($, on) => { + const { w } = await bootRecall($, on) + w.model = 'unanswered' + await start($) + for (let i = 0; i < 4; i++) await say($, DESIGN) + expect(w.asks).toHaveLength(3) + await w.clock.advance(900000) + await say($, DESIGN) + expect(w.asks).toHaveLength(4) + }) + +test('RP2: a success between failures keeps the pause away', async ( + $, on, +) => { + const { w } = await bootRecall($, on) + await start($) + for (const m of ['unanswered', 'unanswered', { text: 'none' }, + 'unanswered', 'unanswered', 'unanswered'] as Model[]) { + w.model = m + await say($, DESIGN) + } + expect(w.asks).toHaveLength(6) + await say($, DESIGN) + expect(w.asks).toHaveLength(6) +}) + +test('RP3: timeouts and throws count like failures', async ($, on) => { + const { w } = await bootRecall($, on) + await start($) + w.model = 'throw' + await say($, DESIGN) + await say($, DESIGN) + w.model = 'hang' + const p = say($, DESIGN) + await w.clock.advance(RERANK_MS) + await p + await say($, DESIGN) + expect(w.asks).toHaveLength(3) +}) + +test('TIMErules: both rules on 64 KiB of letters, under 50 ms', () => { + const text = 'a'.repeat(65536) + const t0 = now() + expect(DESIGN_RULE.test(text)).toBe(false) + expect(ANALYSIS_RULE.test(text)).toBe(false) + expect(isTrigger(text, false, 0)).toBe(false) + expect(now() - t0).toBeLessThan(50) +}) + +test('isTrigger: rules, fresh, idle, slash and length', () => { + expect(isTrigger('please review this module', false, 0)).toBe(true) + expect(isTrigger('on va concevoir la suite', false, 0)).toBe(false) + expect(isTrigger('on va concevoir la suite', true, 0)).toBe(true) + expect(isTrigger('on va concevoir la suite', false, IDLE_MS)).toBe(true) + expect(isTrigger('/feat design the thing', true, IDLE_MS)).toBe(false) + expect(isTrigger('design note', true, 0)).toBe(false) + expect(isTrigger('un-design-ed thing here', false, 0)).toBe(false) + expect(HAIKU).toBe('claude-haiku-5-5') +}) + +/** + * The few calls promptContext makes, over the world: the test's own `$` has + * no session.root, and a hook's `$` is refused outside its module. + */ +const fakeApi = (w: World): Api => ({ + session: { root: async () => w.root, id: async () => w.id }, + clock: { now: async () => w.clock.now(), + sleep: () => new Promise<void>(() => undefined) }, + env: { get: async () => w.home }, + fs: { + stat: async (p: string) => { + const text = w.files.get(p) + if (text === undefined) throw new Error('ENOENT') + return { kind: 'file', size: text?.length ?? 0 } + }, + read: async (p: string) => w.files.get(p) ?? '', + exists: async (p: string) => w.files.has(p), + }, + process: { run: async () => ({ exitCode: 0, + stdout: (w.proc as { stdout: string }).stdout }) }, + model: { complete: async (a: Ask) => { + w.asks.push(a) + return { isAnswered: true, text: (w.model as { text: string }).text } + } }, + store: storeApi(w).store, + ui: { log: () => undefined }, +}) as unknown as Api + +/** A state past the switch read, so promptContext skips the tool setup. */ +const switchedOn = () => Object.assign(newState(), { + enabled: true, recall: true }) + +/** A recall entry whose line is 381 characters: 90 title, 280 lesson. */ +const longEntry = (n: number) => { + const field = 'alpha '.repeat(50).slice(0, 279) + '.' + return entryText(`BLK-00${n}`, 't'.repeat(89) + n, 'Solution', field) +} + +test('SP1: an ordinary prompt resets the main key spent budget', async ( + $, on, +) => { + const ids = ['BLK-001', 'BLK-002', 'BLK-003'] + const w = await boot($, on, { files: { + [BLK]: [1, 2, 3].map(longEntry).join('\n') } }) + const api = () => fakeApi(w) + w.proc = { stdout: rowsOut(ids.map(id => + [id, 't'.repeat(89) + id.slice(-1)])) } + w.model = { text: ids.join(', ') } + const st = switchedOn() + const e = (text: string) => ({ text, origin: { kind: 'composer' } }) + onContextStart(st, 's1') + const [block] = await promptContext(api(), st, e('design alpha now')) + expect(block?.length).toBe(1160) // 14 header + 3 x (381 line + 1) + expect(st.spent.get('s1:main')).toBe(1160) + expect(await promptContext(api(), st, e('nothing special at all'))) + .toEqual([]) + expect(st.spent.has('s1:main')).toBe(false) + // a 400-char line fits after the reset; 1160 + 400 > 1500 would not + expect(claim(st, 's1:main', ['KNOWN-1'], [400])).toEqual(['KNOWN-1']) +}) + +test('SP2: a prompt without a known last prompt is not idle', async ( + $, on, +) => { + const w = await boot($, on, { files: REC_FILES }) + w.proc = { stdout: REC_INDEX } + const api = () => fakeApi(w) + const st = switchedOn() + const e = { text: NOTES, origin: { kind: 'composer' } } + expect(await promptContext(api(), st, e)).toEqual([]) + expect(w.asks).toEqual([]) + expect(st.lastPrompt.get('s1')).toBe(1000) +}) + +test('CL4: a missing cost refuses the id, it is not free', () => { + const st = newState() + expect(claim(st, 'k', ['A-1', 'B-2'], [10])).toEqual(['A-1']) + expect(st.seen.get('k')?.has('B-2')).toBe(false) +}) + +test('LG5: two appends fired together keep both records', async ( + $, on, +) => { + const w = await boot($, on) + const st = newState() + const api = storeApi(w) + await Promise.all([ + appendLog(api, st, ROOT, REC(1)), + appendLog(api, st, ROOT, REC(2)), + ]) + expect((w.kv.get(`l:${ROOT}`) as LogRecord[]).map(r => r.at)) + .toEqual([1, 2]) +}) diff --git a/mods/memory/hooks/register.ts b/mods/memory/hooks/register.ts index d009031..5d3e7cf 100644 --- a/mods/memory/hooks/register.ts +++ b/mods/memory/hooks/register.ts @@ -17,6 +17,7 @@ type State = { spent: Map<string, number> // context key -> chars injected fresh: Set<string> // sessions whose next qualifying prompt starts a context lastPrompt: Map<string, number> // session id -> time of its last prompt + rerank: { fails: number; until: number } // failures in a row, pause end } export const IDLE_MS = 1800000 @@ -724,9 +725,11 @@ export function recallLine(e: Entry): string { return e.lesson === '' ? head : `${head} — ${e.lesson}` } +const RECALL_HEADER = 'memory recall:' + /** The injected block; a line that would pass `max` characters is dropped. */ export function recallBlock(lines: string[], max: number): string { - const header = 'memory recall:' + const header = RECALL_HEADER let block = header for (const line of lines) { if (block.length + 1 + line.length <= max) block += `\n${line}` @@ -906,6 +909,8 @@ export type LogRecord = { ids: string[] } +// shortcut: one `l:<root>` key per project, so no cap across roots; upgrade +// path: one global log key, or a sweep of the `l:` keys by age. const LOG_PREFIX = 'l:' const MAX_LOG = 200 const MAX_LOG_BYTES = 65536 @@ -1049,6 +1054,7 @@ export function newState(): State { spent: new Map(), fresh: new Set(), lastPrompt: new Map(), + rerank: { fails: 0, until: 0 }, } } @@ -1181,8 +1187,9 @@ export function claim( let spent = st.spent.get(key) ?? 0 const taken: string[] = [] ids.forEach((id, i) => { - const cost = chars[i] ?? 0 - if (seen.has(id) || spent + cost > RECALL_CAP) return + const cost = chars[i] + // a missing cost refuses the id: unknown is not free + if (cost === undefined || seen.has(id) || spent + cost > RECALL_CAP) return seen.add(id) spent += cost taken.push(id) @@ -1398,33 +1405,202 @@ function registerBash(on: On, st: State): void { } /** Failures of the current session no registry entry knows. */ -async function newFailureCount($: Api, st: State, at: Where): Promise<number> { +async function newFailureCount( + $: Api, + st: State, + at: Where, + index: Map<string, string>, +): Promise<number> { await st.writes const p = await loadProject($, at.root) - const { index } = await loadRegistries($, at.root, FAILURE_FILES) const cur = p.sessions.find(s => s.id === at.id) return (cur?.failures ?? []).filter(isFailure) .filter(f => matchOf(index, f.key) === undefined).length } /** The note for the oldest unnoted milestone; clears what it covers. */ -async function noteFor($: Api, st: State, at: Where): Promise<string> { +async function noteFor( + $: Api, + st: State, + at: Where, + rx: Registries, +): Promise<string> { const first = st.pending[0] ?? '' st.pending = [] - const n = await newFailureCount($, st, at) + const n = await newFailureCount($, st, at, rx.index) return `memory: ${first} \u2014 ${n} new failure mode(s) this session;` + ' /capitalize when ready.' } +// The default prompt rules of the model router (mods/model-router, commit +// 9bbd1d5): a prompt that designs or analyses asks for recall. +const WORD_BEFORE = '(?<![\\p{L}\\p{N}-])' +const WORD_AFTER = '(?![\\p{L}\\p{N}-])' +const wordRule = (words: string) => + new RegExp(`${WORD_BEFORE}(${words})${WORD_AFTER}`, 'iu') + +export const DESIGN_RULE = wordRule( + 'plan|planifie|planning|brainstorm|architecture|con[c\\u00e7]ois|design', +) +export const ANALYSIS_RULE = wordRule( + 'pourquoi|why|explique|explain|analyse|analyze|comprendre|understand|' + + 'review|audit', +) + +const MIN_PROMPT = 12 // code points +const MAX_CANDS = 30 +const RERANK_FAILS = 3 // failed reranks in a row that pause it +const RERANK_PAUSE_MS = 900000 + +/** True when a prompt may ask for recall: fresh context, idle, or a rule. */ +export function isTrigger( + text: string, + fresh: boolean, + idleMs: number, +): boolean { + if (text.startsWith('/') || Array.from(text).length < MIN_PROMPT) { + return false + } + const asked = cap(text, MAX_REGEX_INPUT) + return fresh || idleMs >= IDLE_MS || + DESIGN_RULE.test(asked) || ANALYSIS_RULE.test(asked) +} + +/** Counts a rerank: the third failure in a row pauses it for 15 min. */ +function countRerank(st: State, ok: boolean, now: number): void { + if (ok) { + st.rerank.fails = 0 + return + } + st.rerank.fails += 1 + if (st.rerank.fails < RERANK_FAILS) return + st.rerank = { fails: 0, until: now + RERANK_PAUSE_MS } +} + +/** The haiku answer, or undefined: failed, unanswered, late or paused. */ +async function askRerank( + $: Api, + st: State, + text: string, + cands: Entry[], +): Promise<string | undefined> { + const now = await $.clock.now() + if (now < st.rerank.until) return undefined + const ask = { + model: HAIKU, + prompt: rerankPrompt(text, cands), + effort: 'low' as const, + maxTokens: 64, + timeoutMs: RERANK_MS, + } + const call = $.model.complete(ask).catch((): undefined => undefined) + const late = $.clock.sleep(RERANK_MS).then((): undefined => undefined) + const out = await Promise.race([call, late]) + const answer = out?.isAnswered === true ? out.text : undefined + countRerank(st, answer !== undefined, now) + return answer +} + +/** Live entries of the context not injected yet, best BM25 first. */ +function candidatesFor( + st: State, + key: string, + rx: Registries, + text: string, +): Entry[] { + const { status } = rx + if (status === undefined) return [] + const seen = st.seen.get(key) + const open = rx.entries.filter(e => isLive(status, e.id) && !seen?.has(e.id)) + return bm25Rank(open, text, MAX_CANDS) +} + +/** + * The recall block for a prompt: BM25 candidates, haiku picks, the ledger + * claim, the log. '' when nothing is to be injected. + */ +async function recallFor( + $: Api, + st: State, + at: Where, + text: string, + rx: Registries, +): Promise<string> { + const key = contextKey(at.id, undefined) + const cands = candidatesFor(st, key, rx, text) + if (cands.length === 0) return '' + const answer = await askRerank($, st, text, cands) + const byId = new Map(cands.map(c => [c.id, c])) + const picked = parseIds(answer ?? '', cands, MAX_PICKS) + .flatMap(id => byId.get(id) ?? []) + const when = await $.clock.now() + // the header is charged to the first line of the block + const costs = picked.map((e, i) => + recallLine(e).length + 1 + (i === 0 ? RECALL_HEADER.length : 0)) + const taken = claim(st, key, picked.map(e => e.id), costs) + const block = recallBlock( + picked.filter(e => taken.includes(e.id)).map(recallLine), RECALL_CAP) + if (block === '') return '' + const record = { at: when, session: at.id, agent: 'main', ids: taken } + await appendLog($, st, at.root, { ...record, channel: 'prompt' }) + .catch(() => undefined) + return block +} + +const ALL_FILES = ['decisions.md', ...FAILURE_FILES] + +/** The contexts a prompt adds: the 4b note, then the recall block. */ +async function additions( + $: Api, + st: State, + at: Where, + text: string, + wantRecall: boolean, +): Promise<string[]> { + const rx = await loadRegistries($, at.root, ALL_FILES) + const note = st.pending.length > 0 ? await noteFor($, st, at, rx) : '' + const block = wantRecall + ? await recallFor($, st, at, text, rx).catch(() => '') + : '' + return [note, block].filter(part => part !== '') +} + +type PromptIn = { + text: string + turnId?: string | undefined + origin: { kind: string } +} + +/** + * The contexts to append to a composer prompt; [] for any other prompt. A + * new prompt starts a new turn: the main key's `spent` budget resets. + */ +export async function promptContext( + $: Api, + st: State, + e: PromptIn, +): Promise<string[]> { + if (!(await ensureEnabled($, st))) return [] + if (e.origin.kind !== 'composer' || e.turnId !== undefined) return [] + const at = { root: await $.session.root(), id: await $.session.id() } + if (at.root === '') return [] + const now = await $.clock.now() + const last = st.lastPrompt.get(at.id) + const idle = last === undefined ? 0 : now - last // unknown: not idle + st.lastPrompt.set(at.id, now) + st.spent.delete(contextKey(at.id, undefined)) + const wantRecall = (await ensureRecall($, st)) && + isTrigger(e.text, st.fresh.has(at.id), idle) + if (wantRecall) st.fresh.delete(at.id) + if (!wantRecall && st.pending.length === 0) return [] + return additions($, st, at, e.text, wantRecall) +} + function registerPrompt(on: On, st: State): void { on('prompt.submit', async ($, e, next) => { - if (!(await ensureEnabled($, st))) return next(e) - const mine = e.origin.kind === 'composer' && e.turnId === undefined - if (!mine || st.pending.length === 0) return next(e) - const at = { root: await $.session.root(), id: await $.session.id() } - if (at.root === '') return next(e) - const note = await noteFor($, st, at) - return next({ ...e, context: [...(e.context ?? []), note] }) + const added = await promptContext($, st, e) + if (added.length === 0) return next(e) + return next({ ...e, context: [...(e.context ?? []), ...added] }) }).catch(($, e, next) => { warnOnce(st, $, 'prompt.submit', next.error.kind) return next(e) From 66696e9a3e9d97d47a50c941fb774a69bdd1eeb2 Mon Sep 17 00:00:00 2001 From: bchanot <chanot.bastien@gmail.com> Date: Thu, 5 Nov 2026 16:52:21 +0100 Subject: [PATCH 12/41] feat(memory): known-error line on failing commands --- mods/memory/hooks/register.test.ts | 197 +++++++++++++++++++++++++++++ mods/memory/hooks/register.ts | 76 +++++++++-- 2 files changed, 264 insertions(+), 9 deletions(-) diff --git a/mods/memory/hooks/register.test.ts b/mods/memory/hooks/register.test.ts index 5743f97..6806c0a 100644 --- a/mods/memory/hooks/register.test.ts +++ b/mods/memory/hooks/register.test.ts @@ -1716,6 +1716,7 @@ test('SR7: no registry read, no process run, no unavailable note', async ( test('SR8: HOME unset, status unavailable, fails open', async ($, on) => { const w = await boot($, on, { files: REGS }) await failing($, w, EXIT1 + SR_LINE) + w.runs = [] // the capture's known-line step ran the reader once w.home = undefined const text = await pending($) expect(w.runs).toEqual([]) @@ -2564,3 +2565,199 @@ test('LG5: two appends fired together keep both records', async ( expect((w.kv.get(`l:${ROOT}`) as LogRecord[]).map(r => r.at)) .toEqual([1, 2]) }) + +// ---- known-error line on failing commands ------------------------------ + +const KN_SPAN = 'fatal: unable to access remote host' +const KN_ENTRY = entryText('BLK-002', 'remote access', 'Solution', + 'Check the VPN first.') + `seen: \`${KN_SPAN}\`\n` +const KN_LINE = 'memory: known BLK-002 remote access — ' + + 'Check the VPN first.' + +/** A world whose BLK-002 is open and matches KN_SPAN. */ +async function bootKnown($: Engine, on: On, o: Opts = {}) { + const w = await boot($, on, { files: { [BLK]: KN_ENTRY }, ...o }) + w.proc = { stdout: rowsOut([['BLK-002', 'remote access']]) } + return w +} + +const asAgent = ($: Engine, command = 'make') => + $.tool.call({ tool: 'Bash', command, agentId: 'a1' } as never) + +test('TE1: a known failure gains the context line, keeps its shape', + async ($, on) => { + const w = await bootKnown($, on) + const out = await failing($, w, EXIT1 + KN_SPAN) + expect(out).toEqual({ ...(w.answer as object), context: [KN_LINE] }) + }) + +test('TE2: an ENOENT line adds no context key', async ($, on) => { + const text = ER_ENTRY + + 'seen: `cat: x: No such file or directory (os error 2)`\n' + const w = await boot($, on, { files: { [LRN]: text } }) + w.proc = { stdout: '| LRN-009 | 2026-01-01 | e | open |' } + const out = await failing($, w, + EXIT1 + "ls: cannot access '/tmp/zz': No such file or directory") + expect(out).toEqual(w.answer) + expect('context' in (out as object)).toBe(false) +}) + +test('TE3: a sub-agent and the main loop each get the line', async ( + $, on, +) => { + const w = await bootKnown($, on) + failWith(w, EXIT1 + KN_SPAN) + const sub = await asAgent($) + expect((sub as { context?: string[] }).context).toEqual([KN_LINE]) + const main = await bash($, 'make') + expect((main as { context?: string[] }).context).toEqual([KN_LINE]) + const again = await asAgent($) + expect('context' in (again as object)).toBe(false) +}) + +test('TE4: the same failure 20 times in one context injects once', + async ($, on) => { + const w = await bootKnown($, on) + failWith(w, EXIT1 + KN_SPAN) + let injected = 0 + for (let i = 0; i < 20; i++) { + const out = await bash($, 'make') as { context?: string[] } + if (out.context !== undefined) injected++ + } + expect(injected).toBe(1) + }) + +test('TE4b: two concurrent failing calls inject one line', async ( + $, on, +) => { + const w = await bootKnown($, on) + failWith(w, EXIT1 + KN_SPAN) + const outs = await Promise.all([bash($, 'make'), bash($, 'make')]) as + { context?: string[] }[] + expect(outs.filter(o => o.context !== undefined)).toHaveLength(1) + expect(await loadLog(storeApi(w), ROOT)).toHaveLength(1) +}) + +test('TE5: "recall": false adds no line, the capture is stored', + async ($, on) => { + const w = await bootKnown($, on, { + switchText: '{"enabled": true, "recall": false}' }) + const out = await failing($, w, EXIT1 + KN_SPAN) + expect(out).toEqual(w.answer) + expect(failuresOf(w)).toHaveLength(1) + }) + +test('TE6: a superseded entry injects nothing', async ($, on) => { + const w = await bootKnown($, on) + w.proc = { stdout: [ + '| BLK-002 | 2026-01-01 | remote access | superseded |'].join('\n') } + const out = await failing($, w, EXIT1 + KN_SPAN) + expect(out).toEqual(w.answer) +}) + +test('TE6b: an unavailable status reader injects nothing', async ( + $, on, +) => { + const w = await bootKnown($, on) + w.proc = 'exit2' + const out = await failing($, w, EXIT1 + KN_SPAN) + expect(out).toEqual(w.answer) +}) + +test('TE7: at 1448 chars spent, a 200-char line is refused', async ( + $, on, +) => { + // four lines of 362 chars (57 title + 280 lesson) = 1448 spent + const names = ['alpha', 'bravo', 'charlie', 'delta', 'echo'] + const spanOf = (n: string) => `fatal: ${n} cluster is down` + const body = (i: number, title: number, lesson: number) => entryText( + `BLK-01${i}`, 't'.repeat(title - 1) + i, 'Solution', + 'l'.repeat(lesson - 1) + '.') + `seen: \`${spanOf(names[i] ?? '')}\`\n` + const texts = [0, 1, 2, 3].map(i => body(i, 57, 280)) + texts.push(body(4, 50, 125)) // 14 + 8 + 50 + 3 + 125 = 200 + const rows = texts.map((_t, i): [string, string] => + [`BLK-01${i}`, 't'.repeat(i === 4 ? 49 : 56) + i]) + const w = await boot($, on, { files: { [BLK]: texts.join('\n') } }) + w.proc = { stdout: rowsOut(rows) } + for (let i = 0; i < 4; i++) { + const out = await failing($, w, EXIT1 + spanOf(names[i] ?? '')) as + { context?: string[] } + expect(out.context?.[0]?.length).toBe(362) + } + const last = await failing($, w, EXIT1 + spanOf('echo')) + expect(last).toEqual(w.answer) +}) + +test('TE8: a failing known-line step returns the answer unchanged', + async ($, on) => { + const w = await bootKnown($, on) + w.proc = 'throw' + const out = await failing($, w, EXIT1 + KN_SPAN) + expect(out).toEqual(w.answer) + expect(failuresOf(w)).toHaveLength(1) + }) + +test('TE9: a recall of ~1160 chars, an ordinary prompt, then a ~395 known ' + + 'line is injected', async ($, on) => { + const span = 'fatal: alpha cluster is down' + const known = entryText('BLK-004', 't'.repeat(89) + '4', 'Solution', + 'alpha '.repeat(50).slice(0, 279) + '.') + `seen: \`${span}\`\n` + const { w, seen } = await bootNotes($, on, { files: { [BLK]: + [...[1, 2, 3].map(longEntry), known].join('\n') } }) + w.proc = { stdout: rowsOut([1, 2, 3, 4].map((n): [string, string] => + [`BLK-00${n}`, 't'.repeat(89) + n])) } + w.model = { text: 'BLK-001, BLK-002, BLK-003' } + await start($) + await say($, 'design alpha now') + expect(seen[0]?.[0]?.length).toBe(1160) // 14 + 3 x (381 + 1) + await say($, 'nothing special at all') + const out = await failing($, w, EXIT1 + span) as { context?: string[] } + // 1160 + 395 > 1500: only the per-prompt reset lets it through + expect(out.context?.[0]?.length).toBe(395) +}) + +test('RB8: a first pick the budget refuses leaves spent equal to the block', + async ($, on) => { + const w = await boot($, on, { files: { [BLK]: [ + longEntry(1), + entryText('BLK-002', 'beta', 'Solution', 'alpha b.'), + ].join('\n') } }) + w.proc = { stdout: rowsOut([ + ['BLK-001', 't'.repeat(89) + '1'], ['BLK-002', 'beta']]) } + w.model = { text: 'BLK-001, BLK-002' } + const st = switchedOn() + // another caller spends 1150 while the rerank is in flight + const api = Object.assign(fakeApi(w), { model: { complete: async () => { + claim(st, 's1:main', ['X'], [1150]) + return { isAnswered: true, text: 'BLK-001, BLK-002' } + } } }) as unknown as Api + onContextStart(st, 's1') + const [block] = await promptContext(api, + st, { text: 'design alpha now', origin: { kind: 'composer' } }) + expect(block).toBe('memory recall:\nBLK-002 beta — alpha b.') + expect(st.spent.get('s1:main')).toBe(1150 + (block?.length ?? 0)) + expect(st.seen.get('s1:main')?.has('BLK-001')).toBe(false) + }) + +test('PC1: a throwing note still lets the recall attach', async ($, on) => { + const { w, seen } = await bootRecall($, on) + await start($) + await run($, w, 'git commit -m "fix: y"') + w.getsFail = true + await say($, GO) + expect(seen[0]).toEqual([BLOCK1]) +}) + +test('PC2: a throwing recall still lets the note attach', async ($, on) => { + const w = await boot($, on, { files: REC_FILES }) + w.proc = { stdout: REC_INDEX } + const st = switchedOn() + st.pending = ['commit fix: y'] + const api = Object.assign(fakeApi(w), { model: { complete: async () => ({ + get isAnswered(): boolean { throw new Error('boom') }, + }) } }) as unknown as Api + const added = await promptContext(api, st, { text: GO, + origin: { kind: 'composer' } }) + expect(added).toHaveLength(1) + expect(added[0]).toContain('memory: commit fix: y') +}) diff --git a/mods/memory/hooks/register.ts b/mods/memory/hooks/register.ts index 5d3e7cf..ab65b5b 100644 --- a/mods/memory/hooks/register.ts +++ b/mods/memory/hooks/register.ts @@ -1285,17 +1285,19 @@ async function captureFailure( at: Where, e: { command?: unknown; agentId?: unknown }, out: { isError?: boolean; text?: string }, -): Promise<void> { +): Promise<Failure | undefined> { try { - if (out.isError !== true) return + if (out.isError !== true) return undefined const agent = e.agentId !== undefined const f = buildFailure( String(out.text ?? ''), String(e.command ?? ''), agent, await $.clock.now(), ) if (f !== undefined) await queueWrite(st, () => recordFailure($, at, f)) + return f } catch { warnOnce(st, $, 'Bash capture', 'store') + return undefined } } @@ -1388,6 +1390,52 @@ async function captureMilestones( } } +/** + * The known-error line of a failure: `memory: known <entry>` when a live + * BLK or LRN matches and the context has not seen it nor spent its budget. + * '' otherwise. Claims after the last await. + */ +async function knownLine( + $: Api, + st: State, + at: Where, + f: Failure, + agent: string | undefined, +): Promise<string> { + if (!(await ensureRecall($, st))) return '' + const rx = await loadRegistries($, at.root, FAILURE_FILES) + if (rx.status === undefined) return '' + const id = matchOf(rx.index, f.key) + const entry = rx.entries.find(e => e.id === id) + if (entry === undefined) return '' + const line = `memory: known ${recallLine(entry)}` + const key = contextKey(at.id, agent) + if (claim(st, key, [entry.id], [line.length]).length === 0) return '' + const record = { at: await $.clock.now(), session: at.id, ids: [entry.id] } + await appendLog($, st, at.root, { + ...record, agent: agent ?? 'main', channel: 'tool', + }).catch(() => undefined) + return line +} + +/** The known line of a failing answer; '' on any failure (fail open). */ +async function knownContext( + $: Api, + st: State, + at: Where, + e: BashEvent, + f: Failure | undefined, +): Promise<string> { + if (f === undefined) return '' + try { + const agent = typeof e.agentId === 'string' ? e.agentId : undefined + return await knownLine($, st, at, f, agent) + } catch { + warnOnce(st, $, 'Bash known', 'recall') + return '' + } +} + function registerBash(on: On, st: State): void { on('tool.call', { tool: 'Bash' }, async ($, e, next) => { if (!(await ensureEnabled($, st))) return next(e) @@ -1395,9 +1443,11 @@ function registerBash(on: On, st: State): void { const at = { root: await $.session.root(), id: await $.session.id() } if (at.root === '') return next(e) const out = await next(e) - await captureFailure($, st, at, e, out) + const f = await captureFailure($, st, at, e, out) await captureMilestones($, st, at, e, out as BashOut) - return out + const line = await knownContext($, st, at, e, f) + if (line === '') return out + return { ...out, context: [...(out.context ?? []), line] } }).catch(($, e, next) => { warnOnce(st, $, 'Bash', next.error.kind) return next(e) @@ -1534,10 +1584,12 @@ async function recallFor( const picked = parseIds(answer ?? '', cands, MAX_PICKS) .flatMap(id => byId.get(id) ?? []) const when = await $.clock.now() - // the header is charged to the first line of the block - const costs = picked.map((e, i) => - recallLine(e).length + 1 + (i === 0 ? RECALL_HEADER.length : 0)) - const taken = claim(st, key, picked.map(e => e.id), costs) + const taken: string[] = [] + for (const e of picked) { + // the header is charged to the first line actually taken + const header = taken.length === 0 ? RECALL_HEADER.length : 0 + taken.push(...claim(st, key, [e.id], [recallLine(e).length + 1 + header])) + } const block = recallBlock( picked.filter(e => taken.includes(e.id)).map(recallLine), RECALL_CAP) if (block === '') return '' @@ -1558,7 +1610,13 @@ async function additions( wantRecall: boolean, ): Promise<string[]> { const rx = await loadRegistries($, at.root, ALL_FILES) - const note = st.pending.length > 0 ? await noteFor($, st, at, rx) : '' + // separate failures: a throw in one never drops the other + const note = st.pending.length > 0 + ? await noteFor($, st, at, rx).catch(() => { + warnOnce(st, $, 'prompt.submit', 'note') + return '' + }) + : '' const block = wantRecall ? await recallFor($, st, at, text, rx).catch(() => '') : '' From 78eff1cf345e51b170de9be49ed8e1d0b487e180 Mon Sep 17 00:00:00 2001 From: bchanot <chanot.bastien@gmail.com> Date: Thu, 5 Nov 2026 16:59:25 +0100 Subject: [PATCH 13/41] feat(memory): memory_pending lists earlier-session milestones --- mods/memory/hooks/register.test.ts | 49 +++++++++++++++++++++++++++-- mods/memory/hooks/register.ts | 50 +++++++++++++++++++++++------- 2 files changed, 86 insertions(+), 13 deletions(-) diff --git a/mods/memory/hooks/register.test.ts b/mods/memory/hooks/register.test.ts index 6806c0a..09057d0 100644 --- a/mods/memory/hooks/register.test.ts +++ b/mods/memory/hooks/register.test.ts @@ -785,7 +785,7 @@ test('milestones, sub-agent, earlier session and order', async ($, on) => { expect(await pending($)).toBe([ 'memory_pending (project app, 2 session(s))', 'index: read blockers.md, learnings.md', - 'milestones (this session):', + 'milestones:', '- commit fix: x (' + localHhmm(3600000 * 14 + 120000) + ')', 'failures:', '- NEW \u00d72 (sub-agent) brand new line here ok \u2014 command: c', @@ -799,6 +799,39 @@ test('milestones, sub-agent, earlier session and order', async ($, on) => { ].join('\n')) }) +test('PM1: current milestone first, then the earlier one', async ( + $, on, +) => { + const mk = (id: string, at: number, ms: unknown[]) => + ({ id, at, failures: [], milestones: ms, red: [] }) + const seed = { [`p:${ROOT}`]: { sessions: [ + mk('s0', 100, [{ kind: 'commit', label: 'fix: old', at: 7200000 }]), + mk('s1', 900, [{ kind: 'commit', label: 'fix: new', at: 3600000 }]), + ] } } + await boot($, on, { seed }) + expect(await pending($)).toBe([ + 'memory_pending (project app, 2 session(s))', + 'index: skipped blockers.md (missing), learnings.md (missing)', + 'milestones:', + '- commit fix: new (' + localHhmm(3600000) + ')', + '- commit fix: old (' + localHhmm(7200000) + ') (earlier session)', + ].join('\n')) +}) + +test('PM2: only an earlier milestone is not nothing captured', async ( + $, on, +) => { + const seed = { [`p:${ROOT}`]: { sessions: [ + { id: 's0', at: 100, failures: [], red: [], + milestones: [{ kind: 'commit', label: 'fix: probe', at: 3600000 }] }, + ] } } + await boot($, on, { seed }) + const text = await pending($) + expect(text).not.toBe('memory_pending: nothing captured') + expect(text).toContain( + '- commit fix: probe (' + localHhmm(3600000) + ') (earlier session)') +}) + test('the excerpt shows its last 300 characters', async ($, on) => { const w = await boot($, on) await failing($, w, EXIT1 + 'x'.repeat(400) + '\nfatal: tail marker') @@ -1143,7 +1176,7 @@ test('a stored commit milestone shows in the memory_pending answer', async ( expect(await pending($)).toBe([ 'memory_pending (project app, 1 session(s))', 'index: skipped blockers.md (missing), learnings.md (missing)', - 'milestones (this session):', + 'milestones:', '- commit fix(x): y (' + localHhmm(1000) + ')', ].join('\n')) }) @@ -2627,6 +2660,17 @@ test('TE4: the same failure 20 times in one context injects once', expect(injected).toBe(1) }) +test('TE7: the status reader runs only for a candidate', async ( + $, on, +) => { + const w = await bootKnown($, on) + const known = w.runs.length + await failing($, w, EXIT1 + 'fatal: nothing alike zebra quartz') + expect(w.runs.length).toBe(known) + await failing($, w, EXIT1 + KN_SPAN) + expect(w.runs.length - known).toBe(1) +}) + test('TE4b: two concurrent failing calls inject one line', async ( $, on, ) => { @@ -2760,4 +2804,5 @@ test('PC2: a throwing recall still lets the note attach', async ($, on) => { origin: { kind: 'composer' } }) expect(added).toHaveLength(1) expect(added[0]).toContain('memory: commit fix: y') + expect(w.logs.filter(l => l.includes('prompt.submit'))).toEqual([]) }) diff --git a/mods/memory/hooks/register.ts b/mods/memory/hooks/register.ts index ab65b5b..ce008e1 100644 --- a/mods/memory/hooks/register.ts +++ b/mods/memory/hooks/register.ts @@ -852,11 +852,22 @@ function failureText({ f, id, earlier }: Row): string { return `${head}\n excerpt: ${shown}` } -function milestoneText(m: Milestone): string { +function milestoneText(m: Milestone, earlier = false): string { const d = new Date(m.at) const two = (n: number) => String(n).padStart(2, '0') const hhmm = `${two(d.getHours())}:${two(d.getMinutes())}` - return `- ${m.kind} ${m.label} (${hhmm})` + const mark = earlier ? ' (earlier session)' : '' + return `- ${m.kind} ${m.label} (${hhmm})${mark}` +} + +/** Current session first, then the earlier ones, newest session first. */ +function milestoneLines(p: Project, curId: string): string[] { + const lines = (s: Session) => s.milestones.filter(isMilestone) + .map(m => milestoneText(m, s.id !== curId)) + const cur = p.sessions.filter(s => s.id === curId) + const old = p.sessions.filter(s => s.id !== curId) + .sort((a, b) => b.at - a.at) + return [...cur, ...old].flatMap(lines) } /** The failure list within ANSWER_CAP; the rest is counted, not shown. */ @@ -879,14 +890,13 @@ export function formatPending( rx: Registries, ): string { const rows = rowsOf(p, curId, rx.index) - const cur = p.sessions.find(s => s.id === curId) - const ms = (cur?.milestones ?? []).filter(isMilestone) + const ms = milestoneLines(p, curId) if (rows.length === 0 && ms.length === 0) return NOTHING_TEXT const name = root.split('/').filter(Boolean).pop() ?? root const out = [`memory_pending (project ${name}, ${p.sessions.length} ` + 'session(s))', rx.note] if (ms.length > 0) { - out.push('milestones (this session):', ...ms.map(milestoneText)) + out.push('milestones:', ...ms) } if (rows.length > 0) { out.push('failures:', ...capFailures(rows.map(failureText))) @@ -1390,10 +1400,30 @@ async function captureMilestones( } } +/** + * The live BLK or LRN entry `key` matches. The match runs on every entry + * first: the status reader is spawned only for a candidate ID. + */ +async function liveCandidate( + $: Api, + root: string, + key: string, +): Promise<Entry | undefined> { + const { texts } = await readRegistries($, root, FAILURE_FILES) + const all = assembleEntries(texts, new Map()) + const failing = all.filter(e => FAILURE_KINDS.has(e.kind)) + const id = matchOf(buildIndex(failing, undefined), key) + if (id === undefined) return undefined + const status = await statusMap($, root) + if (status === undefined || !isLive(status, id)) return undefined + return assembleEntries(texts, status).find(e => e.id === id) +} + /** * The known-error line of a failure: `memory: known <entry>` when a live * BLK or LRN matches and the context has not seen it nor spent its budget. - * '' otherwise. Claims after the last await. + * '' otherwise. Claims synchronously once the reads are done; only the + * log write follows. */ async function knownLine( $: Api, @@ -1403,15 +1433,13 @@ async function knownLine( agent: string | undefined, ): Promise<string> { if (!(await ensureRecall($, st))) return '' - const rx = await loadRegistries($, at.root, FAILURE_FILES) - if (rx.status === undefined) return '' - const id = matchOf(rx.index, f.key) - const entry = rx.entries.find(e => e.id === id) + const entry = await liveCandidate($, at.root, f.key) if (entry === undefined) return '' const line = `memory: known ${recallLine(entry)}` const key = contextKey(at.id, agent) + const now = await $.clock.now() if (claim(st, key, [entry.id], [line.length]).length === 0) return '' - const record = { at: await $.clock.now(), session: at.id, ids: [entry.id] } + const record = { at: now, session: at.id, ids: [entry.id] } await appendLog($, st, at.root, { ...record, agent: agent ?? 'main', channel: 'tool', }).catch(() => undefined) From 8778c9d92031cbb1f0f0571b915c29305bc1ced6 Mon Sep 17 00:00:00 2001 From: bchanot <chanot.bastien@gmail.com> Date: Thu, 5 Nov 2026 17:02:16 +0100 Subject: [PATCH 14/41] fix(memory): known line rematches on live entries after the status read --- mods/memory/hooks/register.test.ts | 13 +++++++++++++ mods/memory/hooks/register.ts | 13 ++++++++----- 2 files changed, 21 insertions(+), 5 deletions(-) diff --git a/mods/memory/hooks/register.test.ts b/mods/memory/hooks/register.test.ts index 09057d0..0ed33ce 100644 --- a/mods/memory/hooks/register.test.ts +++ b/mods/memory/hooks/register.test.ts @@ -2671,6 +2671,19 @@ test('TE7: the status reader runs only for a candidate', async ( expect(w.runs.length - known).toBe(1) }) +test('TE7b: a live successor sharing the span of a dead entry wins', async ( + $, on, +) => { + const older = entryText('BLK-001', 'old remote access', 'Solution', + 'Old fix.') + `seen: \`${KN_SPAN}\`\n` + const w = await bootKnown($, on, { files: { [BLK]: older + KN_ENTRY } }) + w.proc = { stdout: [ + '| BLK-001 | 2026-01-01 | old remote access | superseded |', + '| BLK-002 | 2026-02-01 | remote access | open |'].join('\n') } + const out = await failing($, w, EXIT1 + KN_SPAN) + expect(out).toEqual({ ...(w.answer as object), context: [KN_LINE] }) +}) + test('TE4b: two concurrent failing calls inject one line', async ( $, on, ) => { diff --git a/mods/memory/hooks/register.ts b/mods/memory/hooks/register.ts index ce008e1..d157a98 100644 --- a/mods/memory/hooks/register.ts +++ b/mods/memory/hooks/register.ts @@ -1185,7 +1185,7 @@ export function onContextStart(st: State, session: string): void { /** * Takes the IDs not yet seen in the context whose line costs (`chars`, * parallel to `ids`) still fit RECALL_CAP, and records them. Synchronous: - * called after the last await, so two racing callers never both claim. + * called after the reads, so two racing callers never both claim. */ export function claim( st: State, @@ -1401,8 +1401,8 @@ async function captureMilestones( } /** - * The live BLK or LRN entry `key` matches. The match runs on every entry - * first: the status reader is spawned only for a candidate ID. + * The live BLK or LRN entry `key` matches. A match on every entry gates + * the status reader; the live entry is then rematched on the statuses. */ async function liveCandidate( $: Api, @@ -1415,8 +1415,11 @@ async function liveCandidate( const id = matchOf(buildIndex(failing, undefined), key) if (id === undefined) return undefined const status = await statusMap($, root) - if (status === undefined || !isLive(status, id)) return undefined - return assembleEntries(texts, status).find(e => e.id === id) + if (status === undefined) return undefined + const entries = assembleEntries(texts, status) + const kept = entries.filter(e => FAILURE_KINDS.has(e.kind)) + const liveId = matchOf(buildIndex(kept, status), key) + return entries.find(e => e.id === liveId) } /** From 4928c0e5e788301d6919c7dd7b14d849dc3ff854 Mon Sep 17 00:00:00 2001 From: bchanot <chanot.bastien@gmail.com> Date: Thu, 5 Nov 2026 17:03:23 +0100 Subject: [PATCH 15/41] feat(hooks): memory digest at session start --- hooks/session-start.sh | 91 ++++++++++++++++++++ lib/tests/session-digest.test.sh | 141 +++++++++++++++++++++++++++++++ 2 files changed, 232 insertions(+) create mode 100644 lib/tests/session-digest.test.sh diff --git a/hooks/session-start.sh b/hooks/session-start.sh index 79a0b3e..127bd02 100644 --- a/hooks/session-start.sh +++ b/hooks/session-start.sh @@ -5,6 +5,24 @@ # git fetch for the version/update check near the end. # ============================================================ +# ── Session source (memory digest gate) ── +# stdin carries the hook JSON. Read it first, before any child can eat it. +# Digest on startup | clear | compact, and on an empty source from a manual +# terminal run; never on resume. Without timeout or jq the source is +# unknowable: digest only when stdin is a terminal, never from a hook. +_ss_digest=0 +if command -v timeout >/dev/null 2>&1 && command -v jq >/dev/null 2>&1; then + _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 + case "$_ss_source" in ""|startup|clear|compact) _ss_digest=1 ;; esac + unset _ss_in _ss_source +elif [ -t 0 ]; then + _ss_digest=1 +fi + # ── Quick health check (filesystem only, no subprocesses) ── BROKEN=() for f in CLAUDE.md settings.json agents skills rules; do @@ -324,5 +342,78 @@ graphify (graphify-out/graph.json present): EOF fi unset _gx_root +# ── memory digest ── +# Cut a line at 160 chars with an ellipsis; a cut that split a multibyte +# char (non-UTF-8 locale) loses trailing chars until iconv accepts it. +_digest_cut() { + local v=$1 + [ "${#v}" -le 160 ] && { printf '%s' "$v"; return; } + v="${v:0:159}" + if command -v iconv >/dev/null 2>&1; then + while [ -n "$v" ] && ! printf '%s' "$v" | iconv -f UTF-8 -t UTF-8 >/dev/null 2>&1; do + v="${v%?}" + done + fi + printf '%s…' "$v" +} + +# Open BLK (≤ 3 listed, the rest counted) and upstream count, as digest lines. +_digest_blockers() { # <root> <memory.sh> + local row line rest status title open=0 upstream=0 more="" + while IFS= read -r row; do + [[ "$row" == "| BLK-"* ]] || continue + line="${row#| }"; line="${line% |}" + rest="${line#* | }"; rest="${rest#* | }" + [[ "$rest" == *" | "* ]] || continue + status="${rest##* | }"; title="${rest% | *}" + case "$status" in + open) open=$((open + 1)) + [ "$open" -le 3 ] && echo "- open: ${line%% | *} $title" ;; + upstream) upstream=$((upstream + 1)) ;; + esac + done < <(bash "$2" -C "$1" index blocker 2>/dev/null) + [ "$open" -gt 3 ] && more="+$((open - 3)) more" + [ "$upstream" -gt 0 ] && more="${more:+$more, }+${upstream} upstream" + [ -n "$more" ] && echo "- open: $more" +} + +_digest_todo() { # <root> → first 3 unchecked Actionable items + awk '/^### Actionable/ { on = 1; next } /^#/ { on = 0 } + on && sub(/^- \[ \] /, "") && n++ < 3 { print "- todo: " $0 }' \ + "$1/.claude/tasks/TODO.md" +} + +_digest_journal() { # <root> → last journal bullet + local last + last=$(grep '^- ' "$1/.claude/memory/journal.md" | tail -1) + [ -n "$last" ] && echo "- journal: ${last#- }" +} + +# The block: header + lines, whole lines dropped from the end until ≤ 800. +# Built in a variable and printed once, so a failure mid-way prints nothing. +_memory_digest() { # <project-root> + local root=$1 lib line block="" lines=() + lib="$(dirname "${BASH_SOURCE[0]}")/../lib/memory.sh" + [ -d "$root/.claude/memory" ] || return 0 + [ -f "$lib" ] && while IFS= read -r line; do lines+=("$line"); done \ + < <(_digest_blockers "$root" "$lib") + while IFS= read -r line; do lines+=("$line"); done < <(_digest_todo "$root") + while IFS= read -r line; do lines+=("$line"); done < <(_digest_journal "$root") + [ "${#lines[@]}" -gt 0 ] || return 0 + block="memory digest:" + for line in "${lines[@]}"; do + line=$(_digest_cut "$line") + [ $((${#block} + ${#line} + 1)) -le 800 ] || break + block+=$'\n'"$line" + done + printf '%s\n' "$block" +} +if [ "$_ss_digest" = 1 ]; then + _ss_root=$(git rev-parse --show-toplevel 2>/dev/null) || _ss_root=$PWD + ( _memory_digest "$_ss_root" ) 2>/dev/null || true + unset _ss_root +fi +unset _ss_digest + echo "" unset TOKEN_WARN PROFILE_PLAIN diff --git a/lib/tests/session-digest.test.sh b/lib/tests/session-digest.test.sh new file mode 100644 index 0000000..3a653c1 --- /dev/null +++ b/lib/tests/session-digest.test.sh @@ -0,0 +1,141 @@ +#!/usr/bin/env bash +# lib/tests/session-digest.test.sh — memory digest at the end of the +# session-start banner (phase 4c, Task 7). Fixture projects under mktemp -d. +set -u +ROOT="$(cd "$(dirname "$0")/../.." && pwd)" +SS="$ROOT/hooks/session-start.sh" +WORK="$(mktemp -d)"; trap 'rm -rf "$WORK"' EXIT +export SESSION_START_OFFLINE=1 +pass=0; fail=0 +check() { if [ "$2" = "$3" ]; then pass=$((pass+1)); else fail=$((fail+1)); + printf 'FAIL %s: got[%s] want[%s]\n' "$1" "$2" "$3"; fi; } + +# mkproj <name> -> path with an empty memory dir +mkproj() { + mkdir -p "$WORK/$1/.claude/memory" "$WORK/$1/.claude/tasks" + echo "$WORK/$1" +} +# blk <proj> <n> <status> <title>: append a BLK entry +blk() { + printf '\n## BLK-%03d — %s [%s]\n\n- **Date**: 2026-11-0%d\n' \ + "$2" "$4" "$3" "$(( $2 % 9 + 1 ))" >> "$1/.claude/memory/blockers.md" +} +# run <proj> <stdin-file|-> [script]: the banner +run() { + local in=${2:--} + if [ "$in" = - ]; then + (cd "$1" && bash "${3:-$SS}" </dev/null 2>/dev/null) + else + (cd "$1" && bash "${3:-$SS}" <"$in" 2>/dev/null) + fi +} +digest() { sed -n '/^memory digest:/,$p' | sed '$d'; } +printf '{"source":"startup"}' > "$WORK/startup.json" +printf '{"source":"resume"}' > "$WORK/resume.json" +printf '{"source":"clear"}' > "$WORK/clear.json" +printf '{"source":"compact"}' > "$WORK/compact.json" + +# SD1: 1 open + 2 upstream, 4 todo items, a journal +p=$(mkproj sd1) +blk "$p" 1 open "Bing API unusable" +blk "$p" 2 upstream "Up one"; blk "$p" 3 upstream "Up two" +printf '### Actionable\n- [ ] one\n- [x] done\n- [ ] two\n- [ ] three\n- [ ] four\n\n### Later\n- [ ] nope\n' \ + > "$p/.claude/tasks/TODO.md" +printf '## 2026-11-04\n- first line\n- 2026-11-04: last line\n' > "$p/.claude/memory/journal.md" +want='memory digest: +- open: BLK-001 Bing API unusable +- open: +2 upstream +- todo: one +- todo: two +- todo: three +- journal: 2026-11-04: last line' +check SD1-startup "$(run "$p" "$WORK/startup.json" | digest)" "$want" +check SD1b-clear "$(run "$p" "$WORK/clear.json" | digest)" "$want" +check SD1c-compact "$(run "$p" "$WORK/compact.json" | digest)" "$want" +check SD1d-banner-first "$(run "$p" "$WORK/startup.json" | head -2 | tail -1 | cut -c1-3)" "┌─ " + +# SD2: resume -> none +check SD2-resume "$(run "$p" "$WORK/resume.json" | grep -c 'memory digest:')" 0 + +# SD3: empty stdin -> digest, exit 0 +run "$p" - >/dev/null; rc=$? +check SD3-empty-source "$(run "$p" - | grep -c 'memory digest:')/$rc" 1/0 + +# SD4: no .claude/memory -> no block +mkdir -p "$WORK/sd4" +check SD4-no-memory "$(run "$WORK/sd4" - | grep -c 'memory digest:')" 0 + +# SD5: TODO without ### Actionable -> no todo line (others stay) +p=$(mkproj sd5) +blk "$p" 1 open "Only blocker" +printf '### Backlog\n- [ ] hidden\n' > "$p/.claude/tasks/TODO.md" +check SD5-no-actionable "$(run "$p" - | digest)" 'memory digest: +- open: BLK-001 Only blocker' + +# SD6: a 400-char journal line with an em dash, cut at 160, valid UTF-8 +p=$(mkproj sd6) +long=$(printf 'a — %.0s' $(seq 1 130)) +printf '## d\n- %s\n' "$long" > "$p/.claude/memory/journal.md" +for loc in C.UTF-8 C; do + out=$(cd "$p" && LC_ALL=$loc bash "$SS" </dev/null 2>/dev/null | digest | tail -1) + ok=$(printf '%s' "$out" | iconv -f UTF-8 -t UTF-8 >/dev/null 2>&1 && echo valid || echo invalid) + check "SD6-valid-utf8-$loc" "$ok" valid + check "SD6-ellipsis-$loc" "${out: -1}" "…" +done +out=$(cd "$p" && LC_ALL=C.UTF-8 bash "$SS" </dev/null 2>/dev/null | digest | tail -1) +check SD6-len-160 "${#out}" 160 + +# SD7: 10 open BLK with long titles, long todos and journal -> whole lines, <= 800 +p=$(mkproj sd7) +lt=$(printf 'title%.0s ' $(seq 1 40)) +for i in 1 2 3 4 5 6 7 8 9 10; do blk "$p" "$i" open "$lt"; done +printf '### Actionable\n- [ ] %s\n- [ ] %s\n- [ ] %s\n' "$lt" "$lt" "$lt" > "$p/.claude/tasks/TODO.md" +printf '## d\n- %s\n' "$lt$lt" > "$p/.claude/memory/journal.md" +out=$(run "$p" - | digest) +check SD7-le-800 "$([ "${#out}" -le 800 ] && echo yes || echo no)" yes +check SD7-header "$(printf '%s' "$out" | head -1)" 'memory digest:' +check SD7-whole-lines "$(printf '%s\n' "$out" | tail -n +2 | grep -vc '^- \(open: BLK-\|open: +\|todo: \|journal: \)')" 0 +check SD7-dropped-from-end "$(printf '%s' "$out" | grep -c 'journal:')" 0 +check SD7-lines-le-160 "$(printf '%s\n' "$out" | awk 'length($0) > 160' | wc -l | tr -d ' ')" 0 + +# SD9: copy of the script beside a failing / malformed lib; blockers dir +mkdir -p "$WORK/sd9/hooks" "$WORK/sd9/lib" +cp "$SS" "$WORK/sd9/hooks/session-start.sh" +for f in "$ROOT"/lib/*; do + [ "$(basename "$f")" = memory.sh ] || ln -s "$f" "$WORK/sd9/lib/" +done +S9="$WORK/sd9/hooks/session-start.sh" +p=$(mkproj sd9) +blk "$p" 1 open "Never shown" +printf '#!/usr/bin/env bash\nexit 2\n' > "$WORK/sd9/lib/memory.sh" +out=$(run "$p" - "$S9"); rc=$? +check SD9a-exit2-rc "$rc" 0 +check SD9a-banner "$(printf '%s' "$out" | grep -c 'make doctor')" 1 +check SD9a-no-digest "$(printf '%s' "$out" | grep -c 'memory digest:')" 0 +printf '#!/usr/bin/env bash\nprintf "| BLK-1 |\\n| BLK-2 | x\\n| BLK-3 | d | t | weird |\\ngarbage\\n"\n' \ + > "$WORK/sd9/lib/memory.sh" +out=$(run "$p" - "$S9"); rc=$? +check SD9b-malformed-rc "$rc" 0 +check SD9b-banner "$(printf '%s' "$out" | grep -c 'make doctor')" 1 +check SD9b-no-digest "$(printf '%s' "$out" | grep -c 'memory digest:')" 0 +p=$(mkproj sd9d); mkdir "$p/.claude/memory/blockers.md" +out=$(run "$p" -); rc=$? +check SD9c-dir-rc "$rc" 0 +check SD9c-banner "$(printf '%s' "$out" | grep -c 'make doctor')" 1 +check SD9c-no-digest "$(printf '%s' "$out" | grep -c 'memory digest:')" 0 + +# SD10: PATH without jq, piped resume -> no digest, banner intact +bin="$WORK/nojq"; mkdir -p "$bin" +for c in bash git cat sed awk grep tail head cut dirname readlink wc tr \ + sort uniq timeout iconv env date basename mktemp find ls cp rm mkdir \ + cmp stat id uname tee printf; do + src=$(command -v "$c" 2>/dev/null) && ln -sf "$src" "$bin/$c" +done +p=$(mkproj sd10); blk "$p" 1 open "Hidden" +out=$(cd "$p" && PATH="$bin" bash "$SS" <"$WORK/resume.json" 2>/dev/null) +check SD10-no-jq-no-digest "$(printf '%s' "$out" | grep -c 'memory digest:')" 0 +check SD10-no-jq-banner "$(printf '%s' "$out" | grep -c 'make doctor')" 1 +check SD10-jq-really-absent "$(PATH="$bin" command -v jq | wc -l | tr -d ' ')" 0 + +printf 'session-digest: %d passed, %d failed\n' "$pass" "$fail" +[ "$fail" -eq 0 ] From 3937948a2a4c84f451ddb8ed88f228ba341ebd9a Mon Sep 17 00:00:00 2001 From: bchanot <chanot.bastien@gmail.com> Date: Thu, 5 Nov 2026 17:08:52 +0100 Subject: [PATCH 16/41] chore(contract): phase 4c digest cap order [gated] --- .claude/tasks/contracts/2026-11-04-memory-recall-1859.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.claude/tasks/contracts/2026-11-04-memory-recall-1859.md b/.claude/tasks/contracts/2026-11-04-memory-recall-1859.md index 4a9fbeb..d4ff2a2 100644 --- a/.claude/tasks/contracts/2026-11-04-memory-recall-1859.md +++ b/.claude/tasks/contracts/2026-11-04-memory-recall-1859.md @@ -44,6 +44,8 @@ Pass B `[gated 2026-11-04]` (plan r1; user: "oui, tels quels" / "oui"): visible 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. + 9. `[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 From 177502139ddc3f6bfd300eab8b387ece29e98607 Mon Sep 17 00:00:00 2001 From: bchanot <chanot.bastien@gmail.com> Date: Thu, 5 Nov 2026 17:11:45 +0100 Subject: [PATCH 17/41] fix(hooks): digest keeps the journal line under the cap --- hooks/session-start.sh | 51 ++++++++++++++++++++++---------- lib/tests/session-digest.test.sh | 40 +++++++++++++++++++------ 2 files changed, 67 insertions(+), 24 deletions(-) diff --git a/hooks/session-start.sh b/hooks/session-start.sh index 127bd02..e622e65 100644 --- a/hooks/session-start.sh +++ b/hooks/session-start.sh @@ -389,25 +389,46 @@ _digest_journal() { # <root> → last journal bullet [ -n "$last" ] && echo "- journal: ${last#- }" } -# The block: header + lines, whole lines dropped from the end until ≤ 800. +# The block: header + open BLK lines + count line + todo lines + journal. +# Over 800 chars: todo lines go (last to first); header, open BLK lines +# (3 x 160 max), count line and journal stay, which always fits in 800. # Built in a variable and printed once, so a failure mid-way prints nothing. -_memory_digest() { # <project-root> - local root=$1 lib line block="" lines=() - lib="$(dirname "${BASH_SOURCE[0]}")/../lib/memory.sh" - [ -d "$root/.claude/memory" ] || return 0 - [ -f "$lib" ] && while IFS= read -r line; do lines+=("$line"); done \ - < <(_digest_blockers "$root" "$lib") - while IFS= read -r line; do lines+=("$line"); done < <(_digest_todo "$root") - while IFS= read -r line; do lines+=("$line"); done < <(_digest_journal "$root") - [ "${#lines[@]}" -gt 0 ] || return 0 - block="memory digest:" - for line in "${lines[@]}"; do - line=$(_digest_cut "$line") - [ $((${#block} + ${#line} + 1)) -le 800 ] || break - block+=$'\n'"$line" +_digest_assemble() { # reads the arrays blk, cnt, todo, jr of the caller + local block i + while :; do + block="memory digest:" + for i in "${blk[@]}" "${cnt[@]}" "${todo[@]}" "${jr[@]}"; do + block+=$'\n'"$i" + done + [ "${#block}" -le 800 ] && break + if [ "${#todo[@]}" -gt 0 ]; then unset 'todo[-1]' + else break; fi done printf '%s\n' "$block" } + +_digest_collect() { # <array name> <line source output on stdin> + local -n _dc=$1; local line + while IFS= read -r line; do _dc+=("$(_digest_cut "$line")"); done +} + +_memory_digest() { # <project-root> + local root=$1 lib line blk=() cnt=() todo=() jr=() + lib="$(dirname "${BASH_SOURCE[0]}")/../lib/memory.sh" + [ -d "$root/.claude/memory" ] || return 0 + if [ -f "$lib" ]; then + while IFS= read -r line; do + case "$line" in + "- open: +"*) cnt+=("$line") ;; + *) blk+=("$(_digest_cut "$line")") ;; + esac + done < <(_digest_blockers "$root" "$lib") + fi + _digest_collect todo < <(_digest_todo "$root") + _digest_collect jr < <(_digest_journal "$root") + [ $((${#blk[@]} + ${#cnt[@]} + ${#todo[@]} + ${#jr[@]})) -gt 0 ] || return 0 + _digest_assemble +} if [ "$_ss_digest" = 1 ]; then _ss_root=$(git rev-parse --show-toplevel 2>/dev/null) || _ss_root=$PWD ( _memory_digest "$_ss_root" ) 2>/dev/null || true diff --git a/lib/tests/session-digest.test.sh b/lib/tests/session-digest.test.sh index 3a653c1..1b2ccba 100644 --- a/lib/tests/session-digest.test.sh +++ b/lib/tests/session-digest.test.sh @@ -85,18 +85,40 @@ done out=$(cd "$p" && LC_ALL=C.UTF-8 bash "$SS" </dev/null 2>/dev/null | digest | tail -1) check SD6-len-160 "${#out}" 160 -# SD7: 10 open BLK with long titles, long todos and journal -> whole lines, <= 800 +# SD7: 3 open BLK + 3 long todos + a journal line over the 800 cap: todo +# lines drop from the last, the journal and every BLK line stay +rep() { printf "%$2s" '' | tr ' ' "$1"; } p=$(mkproj sd7) -lt=$(printf 'title%.0s ' $(seq 1 40)) -for i in 1 2 3 4 5 6 7 8 9 10; do blk "$p" "$i" open "$lt"; done -printf '### Actionable\n- [ ] %s\n- [ ] %s\n- [ ] %s\n' "$lt" "$lt" "$lt" > "$p/.claude/tasks/TODO.md" -printf '## d\n- %s\n' "$lt$lt" > "$p/.claude/memory/journal.md" +for i in 1 2 3; do blk "$p" "$i" open "$(rep b 100)"; done +printf '### Actionable\n- [ ] A%s\n- [ ] B%s\n- [ ] C%s\n' \ + "$(rep x 200)" "$(rep x 200)" "$(rep x 200)" > "$p/.claude/tasks/TODO.md" +printf '## d\n- %s\n' "$(rep j 100)" > "$p/.claude/memory/journal.md" +want="memory digest: +- open: BLK-001 $(rep b 100) +- open: BLK-002 $(rep b 100) +- open: BLK-003 $(rep b 100) +- todo: A$(rep x 150)… +- todo: B$(rep x 150)… +- journal: $(rep j 100)" out=$(run "$p" - | digest) +check SD7-drops-last-todo "$out" "$want" check SD7-le-800 "$([ "${#out}" -le 800 ] && echo yes || echo no)" yes -check SD7-header "$(printf '%s' "$out" | head -1)" 'memory digest:' -check SD7-whole-lines "$(printf '%s\n' "$out" | tail -n +2 | grep -vc '^- \(open: BLK-\|open: +\|todo: \|journal: \)')" 0 -check SD7-dropped-from-end "$(printf '%s' "$out" | grep -c 'journal:')" 0 -check SD7-lines-le-160 "$(printf '%s\n' "$out" | awk 'length($0) > 160' | wc -l | tr -d ' ')" 0 + +# SD7b: the worst case (10 open BLK, long titles, 3 long todos, 160-char +# journal): all todos drop, 3 BLK + count + journal stay, whole lines, <= 800 +p=$(mkproj sd7b) +for i in 1 2 3 4 5 6 7 8 9 10; do blk "$p" "$i" open "$(rep b 300)"; done +blk "$p" 11 upstream "Up" +printf '### Actionable\n- [ ] %s\n- [ ] %s\n' "$(rep x 300)" "$(rep x 300)" \ + > "$p/.claude/tasks/TODO.md" +printf '## d\n- %s\n' "$(rep j 300)" > "$p/.claude/memory/journal.md" +out=$(run "$p" - | digest) +check SD7b-le-800 "$([ "${#out}" -le 800 ] && echo yes || echo no)" yes +check SD7b-no-todo "$(printf '%s\n' "$out" | grep -c '^- todo:')" 0 +check SD7b-3-blk "$(printf '%s\n' "$out" | grep -c '^- open: BLK-')" 3 +check SD7b-count-line "$(printf '%s\n' "$out" | grep -x -- '- open: +7 more, +1 upstream')" '- open: +7 more, +1 upstream' +check SD7b-journal "$(printf '%s\n' "$out" | tail -1)" "- journal: $(rep j 148)…" +check SD7b-lines-le-160 "$(printf '%s\n' "$out" | awk 'length($0) > 160' | wc -l | tr -d ' ')" 0 # SD9: copy of the script beside a failing / malformed lib; blockers dir mkdir -p "$WORK/sd9/hooks" "$WORK/sd9/lib" From d0d119fe30d3682eb4e8eebec1fd53196c8bfedf Mon Sep 17 00:00:00 2001 From: bchanot <chanot.bastien@gmail.com> Date: Thu, 5 Nov 2026 17:17:31 +0100 Subject: [PATCH 18/41] fix(hooks): digest bash 3.2 safe and time-bounded --- hooks/session-start.sh | 46 +++++++++++++++++--------------- lib/tests/session-digest.test.sh | 18 +++++++++++++ 2 files changed, 42 insertions(+), 22 deletions(-) diff --git a/hooks/session-start.sh b/hooks/session-start.sh index e622e65..9ef26a9 100644 --- a/hooks/session-start.sh +++ b/hooks/session-start.sh @@ -10,6 +10,8 @@ # Digest on startup | clear | compact, and on an empty source from a manual # terminal run; never on resume. Without timeout or jq the source is # unknowable: digest only when stdin is a terminal, never from a hook. +# A non-JSON stdin makes jq print nothing: it reads as an empty source and +# the digest prints. _ss_digest=0 if command -v timeout >/dev/null 2>&1 && command -v jq >/dev/null 2>&1; then _ss_source="" @@ -350,7 +352,8 @@ _digest_cut() { [ "${#v}" -le 160 ] && { printf '%s' "$v"; return; } v="${v:0:159}" if command -v iconv >/dev/null 2>&1; then - while [ -n "$v" ] && ! printf '%s' "$v" | iconv -f UTF-8 -t UTF-8 >/dev/null 2>&1; do + while [ -n "$v" ] \ + && ! printf '%s' "$v" | iconv -f UTF-8 -t UTF-8 >/dev/null 2>&1; do v="${v%?}" done fi @@ -359,7 +362,9 @@ _digest_cut() { # Open BLK (≤ 3 listed, the rest counted) and upstream count, as digest lines. _digest_blockers() { # <root> <memory.sh> - local row line rest status title open=0 upstream=0 more="" + local row line rest status title open=0 upstream=0 more="" tmo=() + # a hung memory.sh must not stall every session start + command -v timeout >/dev/null 2>&1 && tmo=(timeout 2) while IFS= read -r row; do [[ "$row" == "| BLK-"* ]] || continue line="${row#| }"; line="${line% |}" @@ -371,7 +376,7 @@ _digest_blockers() { # <root> <memory.sh> [ "$open" -le 3 ] && echo "- open: ${line%% | *} $title" ;; upstream) upstream=$((upstream + 1)) ;; esac - done < <(bash "$2" -C "$1" index blocker 2>/dev/null) + done < <("${tmo[@]}" bash "$2" -C "$1" index blocker 2>/dev/null) [ "$open" -gt 3 ] && more="+$((open - 3)) more" [ "$upstream" -gt 0 ] && more="${more:+$more, }+${upstream} upstream" [ -n "$more" ] && echo "- open: $more" @@ -390,26 +395,21 @@ _digest_journal() { # <root> → last journal bullet } # The block: header + open BLK lines + count line + todo lines + journal. -# Over 800 chars: todo lines go (last to first); header, open BLK lines -# (3 x 160 max), count line and journal stay, which always fits in 800. +# Todo lines are added in order while the block stays <= 800 chars, so the +# last ones drop first; header, open BLK lines (3 x 160 max), count line and +# journal always stay and always fit. The only loop is bounded by the todo +# count (3). Stays bash 3.2 safe (checked by SD11). # Built in a variable and printed once, so a failure mid-way prints nothing. _digest_assemble() { # reads the arrays blk, cnt, todo, jr of the caller - local block i - while :; do - block="memory digest:" - for i in "${blk[@]}" "${cnt[@]}" "${todo[@]}" "${jr[@]}"; do - block+=$'\n'"$i" - done - [ "${#block}" -le 800 ] && break - if [ "${#todo[@]}" -gt 0 ]; then unset 'todo[-1]' - else break; fi + local head="memory digest:" tail="" body="" line size + for line in "${blk[@]}" "${cnt[@]}"; do head+=$'\n'"$line"; done + for line in "${jr[@]}"; do tail=$'\n'"$line"; done + size=$((${#head} + ${#tail})) + for line in "${todo[@]}"; do + [ $((size + ${#line} + 1)) -le 800 ] || break + body+=$'\n'"$line"; size=$((size + ${#line} + 1)) done - printf '%s\n' "$block" -} - -_digest_collect() { # <array name> <line source output on stdin> - local -n _dc=$1; local line - while IFS= read -r line; do _dc+=("$(_digest_cut "$line")"); done + printf '%s%s%s\n' "$head" "$body" "$tail" } _memory_digest() { # <project-root> @@ -424,8 +424,10 @@ _memory_digest() { # <project-root> esac done < <(_digest_blockers "$root" "$lib") fi - _digest_collect todo < <(_digest_todo "$root") - _digest_collect jr < <(_digest_journal "$root") + while IFS= read -r line; do todo+=("$(_digest_cut "$line")"); done \ + < <(_digest_todo "$root") + while IFS= read -r line; do jr+=("$(_digest_cut "$line")"); done \ + < <(_digest_journal "$root") [ $((${#blk[@]} + ${#cnt[@]} + ${#todo[@]} + ${#jr[@]})) -gt 0 ] || return 0 _digest_assemble } diff --git a/lib/tests/session-digest.test.sh b/lib/tests/session-digest.test.sh index 1b2ccba..d7aab40 100644 --- a/lib/tests/session-digest.test.sh +++ b/lib/tests/session-digest.test.sh @@ -159,5 +159,23 @@ check SD10-no-jq-no-digest "$(printf '%s' "$out" | grep -c 'memory digest:')" 0 check SD10-no-jq-banner "$(printf '%s' "$out" | grep -c 'make doctor')" 1 check SD10-jq-really-absent "$(PATH="$bin" command -v jq | wc -l | tr -d ' ')" 0 +# SD11: the digest section stays bash 3.2 safe (macOS) +sec=$(sed -n '/^# ── memory digest ──/,/^unset _ss_digest/p' "$SS") +check SD11-section-found "$([ -n "$sec" ] && echo yes || echo no)" yes +check SD11-bash32-safe "$(printf '%s\n' "$sec" \ + | grep -c -e 'local -n' -e '\[-1\]' -e 'mapfile' -e 'declare -A' -e 'readarray')" 0 + +# SD12: a memory.sh that hangs costs under 3 s, no digest, exit 0 +printf '#!/usr/bin/env bash\ncase "$*" in *index*) sleep 5 ;; esac\n' \ + > "$WORK/sd9/lib/memory.sh" +p=$(mkproj sd12); blk "$p" 1 open "Slow" +t0=$(date +%s) +out=$(run "$p" - "$S9"); rc=$? +t1=$(date +%s) +check SD12-hang-bounded "$([ $((t1 - t0)) -lt 3 ] && echo yes || echo no)" yes +check SD12-rc "$rc" 0 +check SD12-banner "$(printf '%s' "$out" | grep -c 'make doctor')" 1 +check SD12-no-digest "$(printf '%s' "$out" | grep -c 'memory digest:')" 0 + printf 'session-digest: %d passed, %d failed\n' "$pass" "$fail" [ "$fail" -eq 0 ] From f9787044ff7d7433302df0e3762a2cf9728f5ce4 Mon Sep 17 00:00:00 2001 From: bchanot <chanot.bastien@gmail.com> Date: Thu, 5 Nov 2026 17:19:38 +0100 Subject: [PATCH 19/41] test(hooks): SD12 timing bound with sub-second precision --- lib/tests/session-digest.test.sh | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) diff --git a/lib/tests/session-digest.test.sh b/lib/tests/session-digest.test.sh index d7aab40..89a7fea 100644 --- a/lib/tests/session-digest.test.sh +++ b/lib/tests/session-digest.test.sh @@ -165,14 +165,19 @@ check SD11-section-found "$([ -n "$sec" ] && echo yes || echo no)" yes check SD11-bash32-safe "$(printf '%s\n' "$sec" \ | grep -c -e 'local -n' -e '\[-1\]' -e 'mapfile' -e 'declare -A' -e 'readarray')" 0 -# SD12: a memory.sh that hangs costs under 3 s, no digest, exit 0 +# now_ms: milliseconds (GNU date %N), whole seconds x 1000 where unsupported +now_ms() { + local n; n=$(date +%s%N) + case "$n" in *N*|"") echo $(( $(date +%s) * 1000 )) ;; *) echo $((n / 1000000)) ;; esac +} +# SD12: a memory.sh that hangs costs under 3.5 s, no digest, exit 0 printf '#!/usr/bin/env bash\ncase "$*" in *index*) sleep 5 ;; esac\n' \ > "$WORK/sd9/lib/memory.sh" p=$(mkproj sd12); blk "$p" 1 open "Slow" -t0=$(date +%s) +t0=$(now_ms) out=$(run "$p" - "$S9"); rc=$? -t1=$(date +%s) -check SD12-hang-bounded "$([ $((t1 - t0)) -lt 3 ] && echo yes || echo no)" yes +t1=$(now_ms) +check SD12-hang-bounded "$([ $((t1 - t0)) -lt 3500 ] && echo yes || echo no)" yes check SD12-rc "$rc" 0 check SD12-banner "$(printf '%s' "$out" | grep -c 'make doctor')" 1 check SD12-no-digest "$(printf '%s' "$out" | grep -c 'memory digest:')" 0 From adb3db97cb2c4a9a7d3681128ec0522c769085c7 Mon Sep 17 00:00:00 2001 From: bchanot <chanot.bastien@gmail.com> Date: Thu, 5 Nov 2026 17:38:30 +0100 Subject: [PATCH 20/41] chore(bench): phase 4c recall measured on 14 days of transcripts, content floor gated --- .../2026-11-04-memory-recall-1859.md | 2 + .../2026-11-04-memory-recall-spike/RECALL.md | 27 ++ .../recall-bench.ts | 268 ++++++++++++++++++ 3 files changed, 297 insertions(+) create mode 100644 .claude/tasks/plans/2026-11-04-memory-recall-spike/RECALL.md create mode 100644 .claude/tasks/plans/2026-11-04-memory-recall-spike/recall-bench.ts diff --git a/.claude/tasks/contracts/2026-11-04-memory-recall-1859.md b/.claude/tasks/contracts/2026-11-04-memory-recall-1859.md index d4ff2a2..26e85f1 100644 --- a/.claude/tasks/contracts/2026-11-04-memory-recall-1859.md +++ b/.claude/tasks/contracts/2026-11-04-memory-recall-1859.md @@ -46,6 +46,8 @@ STEP 3 gate `[gated 2026-11-05]` (user: "oui"): plan r3 (`docs/superpowers/plans 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. + 9. `[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 diff --git a/.claude/tasks/plans/2026-11-04-memory-recall-spike/RECALL.md b/.claude/tasks/plans/2026-11-04-memory-recall-spike/RECALL.md new file mode 100644 index 0000000..fa8e6dc --- /dev/null +++ b/.claude/tasks/plans/2026-11-04-memory-recall-spike/RECALL.md @@ -0,0 +1,27 @@ +# Phase 4c recall measured on 14 days of transcripts (2026-11-05) + +Harness: `recall-bench.ts` (bun) imports the mod's own functions (`isTrigger`, `bm25Rank`, `rerankPrompt`, `parseIds`, `assembleEntries`, `failureKey`, `buildIndex`, `matchOf`…); statuses from `lib/memory.sh index`; haiku `claude-haiku-5-5` through `claude -p` from a `mktemp -d` cwd with `--setting-sources local`, no tools. Counts and shares only; no prompt or error text here (LRN-124). + +## Prompt channel + +Population: main-loop transcripts with `entrypoint == "cli"`, user entries with `origin.kind == "human"` (typed prompts), not meta, not compaction summaries: 65 prompts, 11 older entries skipped (no `origin` field), 24 meet the trigger, 20 sampled (seed 42). A first run sampled `<task-notification>` and summary entries (origin `task-notification` / `isCompactSummary`, never seen by the mod's `composer` gate): discarded as a measurement. + +| measure | value | +|---|---| +| asks | n = 20 | +| injections (prompts with ≥ 1 entry) | 15 / 20 | +| entries injected | n = 38 (2.5 per injection) | +| relevant entries (controller labels) | 19 / 38 = 50 % | +| relevant on prompts with ≥ 5 content words (estimate) | 16 / 28 = 57 % | +| bar (BDR-125 amendment 2, haiku rerank baseline) | 14 / 22 = 64 % | +| haiku `duration_api_ms` > 3000 (upper bound) | 4 / 20 = 20 % (first run: 7 / 20) | + +The noise sits on content-free prompts triggered by idle time (short approvals): 0 relevant of 10 injected. Prompts with a topic recall the right entries. Caveat: the harness reads today's registries, so entries written after a prompt can be recalled for it (temporal leakage): the true shares are somewhat lower. + +## Error channel + +36 Bash failures keyed over 14 days (main + sub-agents), 3 known-line injections (2 sessions): one exact lesson, two plausible. n = 3: insufficient sample. + +## Decision (2026-11-05) + +User: "Plancher de contenu" — no intent recall on a prompt with fewer than 5 content words (stop words excluded); recall ships on and switchable (`"recall": false`); the injection log (4c) feeds the 4d measurement on real use. The 3 s rerank bound stays (timeout share 20 % < 25 %). diff --git a/.claude/tasks/plans/2026-11-04-memory-recall-spike/recall-bench.ts b/.claude/tasks/plans/2026-11-04-memory-recall-spike/recall-bench.ts new file mode 100644 index 0000000..7916607 --- /dev/null +++ b/.claude/tasks/plans/2026-11-04-memory-recall-spike/recall-bench.ts @@ -0,0 +1,268 @@ +// Measurement harness of the phase 4c memory recall (read-only, stdout). +// Transcript walk follows noise.py (2026-11-03-memory-capture-spike): +// its find_files / pairs_of logic, ported to TS. +// Run: bun recall-bench.ts prompts [--seed N] [--n 20] +// bun recall-bench.ts errors +import * as fs from 'node:fs' +import * as os from 'node:os' +import * as path from 'node:path' +import { + IDLE_MS, RECALL_CAP, HAIKU, RERANK_MS, assembleEntries, bm25Rank, + buildIndex, entriesOf, failureKey, isLive, isTrigger, matchOf, parseIds, + parseIndex, recallBlock, recallLine, redact, rerankPrompt, + type Entry, type StatusMap, +} from '../../../../mods/memory/hooks/register.ts' + +const REPO = path.resolve(import.meta.dir, '../../../..') +const ROOT = path.join( + os.homedir(), '.claude/projects/-home-bchanot-Documents-claude') +const DAYS = 14 +const MAX_CANDS = 30 +const MAX_PICKS = 3 +const MIN_SAMPLE = 10 +const MEMORY_DIR = path.join(REPO, '.claude/memory') + +type Rec = Record<string, any> +type Found = { sid: string; agent: boolean; file: string } +type Composer = { sid: string; text: string; fresh: boolean; idle: number } + +function findFiles(): Found[] { + const cutoff = Date.now() - DAYS * 86400000 + const recent = (p: string) => + (fs.statSync(p, { throwIfNoEntry: false })?.mtimeMs ?? 0) >= cutoff + const found: Found[] = [] + for (const name of fs.readdirSync(ROOT).sort()) { + const full = path.join(ROOT, name) + if (name.endsWith('.jsonl') && recent(full)) { + found.push({ sid: name.slice(0, -6), agent: false, file: full }) + } + if (name.endsWith('.jsonl')) continue + const sub = path.join(full, 'subagents') + if (!fs.statSync(sub, { throwIfNoEntry: false })?.isDirectory()) continue + for (const f of fs.readdirSync(sub).sort()) { + const p = path.join(sub, f) + if (f.endsWith('.jsonl') && recent(p)) { + found.push({ sid: name, agent: true, file: p }) + } + } + } + return found +} + +function records(file: string): Rec[] { + const out: Rec[] = [] + for (const raw of fs.readFileSync(file, 'utf8').split('\n')) { + try { out.push(JSON.parse(raw)) } catch { /* skip bad line */ } + } + return out +} + +function blocksOf(r: Rec): Rec[] { + const c = r.message?.content + return Array.isArray(c) ? c.filter(b => b && typeof b === 'object') : [] +} + +function resultText(content: unknown): string { + if (typeof content === 'string') return content + if (!Array.isArray(content)) return '' + return content.filter(b => b?.type === 'text').map(b => b.text).join('') +} + +/** Bash failures: tool_use paired with its tool_result (is_error). */ +function failuresOf(file: string): { text: string; command: string }[] { + const calls = new Map<string, string>() + const out: { text: string; command: string }[] = [] + for (const r of records(file)) { + for (const b of blocksOf(r)) { + if (b.type === 'tool_use' && b.name === 'Bash') { + calls.set(b.id, String(b.input?.command ?? '')) + } else if (b.type === 'tool_result' && calls.has(b.tool_use_id) && + b.is_error === true) { + out.push({ text: resultText(b.content), + command: calls.get(b.tool_use_id) ?? '' }) + } + } + } + return out +} + +const WRAPPERS = ['<command-', '<local-command', '<system-reminder'] + +const skipped = { noOrigin: 0 } + +/** A typed prompt: origin.kind human, string content, not a command. */ +function composerText(r: Rec): string | undefined { + if (r.type !== 'user' || r.isSidechain === true) return undefined + if (r.isMeta === true || r.isCompactSummary === true) return undefined + if (r.entrypoint !== 'cli') return undefined + const c = r.message?.content + if (typeof c !== 'string') return undefined + if (r.origin?.kind === undefined) { + skipped.noOrigin += 1 + return undefined + } + const t = c.trim() + if (r.origin.kind !== 'human' || t.startsWith('/')) return undefined + return WRAPPERS.some(w => t.startsWith(w)) ? undefined : t +} + +/** Trigger-meeting typed prompts; fresh = first after a summary or start. */ +function triggerPrompts(files: Found[]): { all: number; hits: Composer[] } { + const hits: Composer[] = [] + let all = 0 + for (const f of files.filter(x => !x.agent)) { + let last: number | undefined + let fresh = true + for (const r of records(f.file)) { + if (r.isCompactSummary === true) { fresh = true; continue } + const text = composerText(r) + if (text === undefined) continue + all += 1 + const at = Date.parse(r.timestamp) + const idle = last === undefined || Number.isNaN(at) ? 0 : at - last + if (!Number.isNaN(at)) last = at + if (isTrigger(text, fresh, idle)) { + hits.push({ sid: f.sid, text, fresh, idle }) + } + fresh = false + } + } + return { all, hits } +} + +function rng(seed: number): () => number { + let a = seed >>> 0 + return () => { + a = (a + 0x6d2b79f5) >>> 0 + let t = Math.imul(a ^ (a >>> 15), 1 | a) + t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t + return ((t ^ (t >>> 14)) >>> 0) / 4294967296 + } +} + +function sample<T>(items: T[], n: number, seed: number): T[] { + const pool = [...items] + const next = rng(seed) + for (let i = pool.length - 1; i > 0; i--) { + const j = Math.floor(next() * (i + 1)); + [pool[i], pool[j]] = [pool[j]!, pool[i]!] + } + return pool.slice(0, n) +} + +function statuses(): StatusMap { + const r = Bun.spawnSync(['bash', 'lib/memory.sh', '-C', '.', 'index'], + { cwd: REPO }) + if (r.exitCode !== 0) throw new Error('memory.sh index failed') + return parseIndex(r.stdout.toString()) +} + +function registryTexts(names: string[]): string[] { + return names.map(n => fs.readFileSync(path.join(MEMORY_DIR, n), 'utf8')) +} + +function haiku(prompt: string): { text: string; ms: number } | undefined { + const dir = fs.mkdtempSync(os.tmpdir() + '/recall-') + try { + const r = Bun.spawnSync(['claude', '-p', '--model', HAIKU, + '--output-format', 'json', '--setting-sources', 'local', + '--tools', ''], { cwd: dir, stdin: new TextEncoder().encode(prompt) }) + const j = JSON.parse(r.stdout.toString()) + return { text: String(j.result ?? ''), ms: Number(j.duration_api_ms) } + } catch { + return undefined + } finally { + fs.rmSync(dir, { recursive: true, force: true }) + } +} + +function argOf(name: string, fallback: number): number { + const i = process.argv.indexOf(name) + const v = i < 0 ? NaN : Number(process.argv[i + 1]) + return Number.isFinite(v) ? v : fallback +} + +function share(k: number, n: number): string { + return n < MIN_SAMPLE ? `${k}/${n} (insufficient sample, < ${MIN_SAMPLE})` + : `${k}/${n}` +} + +function oneLine(text: string, n: number): string { + return redact(text).replace(/\s+/g, ' ').slice(0, n) +} + +function runPrompts(): void { + const status = statuses() + const entries = assembleEntries( + registryTexts(['decisions.md', 'learnings.md', 'blockers.md']), status) + const live = entries.filter(e => isLive(status, e.id)) + const { all, hits } = triggerPrompts(findFiles()) + const picked = sample(hits, argOf('--n', 20), argOf('--seed', 1)) + console.log(`human prompts (cli): ${all}, skipped no origin: ${skipped.noOrigin}, meeting isTrigger: ` + + `${hits.length}, sampled: ${picked.length}, live entries: ${live.length}`) + let asks = 0, answered = 0, inj = 0, ids = 0, late = 0 + picked.forEach((p, i) => { + asks += 1 + const cands = bm25Rank(live, p.text, MAX_CANDS) + const a = haiku(rerankPrompt(p.text, cands)) + const got = parseIds(a?.text ?? '', cands, MAX_PICKS) + const byId = new Map(cands.map(c => [c.id, c])) + const block = recallBlock( + got.flatMap(id => byId.get(id) ?? []).map(recallLine), RECALL_CAP) + const slow = a !== undefined && a.ms > RERANK_MS + if (a !== undefined) answered += 1 + if (slow) late += 1 + if (block !== '') { inj += 1; ids += got.length } + console.log(`#${i} [${p.fresh ? 'fresh' : 'idle/rule'}] ` + + `"${oneLine(p.text, 120)}"`) + for (const id of got) console.log(` ${id} ${byId.get(id)?.title}`) + console.log(` duration_api_ms=${a?.ms ?? 'n/a'} (upper bound) ` + + `timeout(>${RERANK_MS})=${a === undefined ? 'failed' : slow ? 'yes' : 'no'}`) + }) + console.log(`TOTAL asks=${asks} answered=${answered} injections=${inj} ` + + `mean IDs per injection=${inj ? (ids / inj).toFixed(2) : 'n/a'} ` + + `timeout share=${share(late, answered)} injection share=` + + share(inj, asks)) +} + +function errorIndex(status: StatusMap): Map<string, string> { + const texts = registryTexts(['blockers.md', 'learnings.md']) + return buildIndex(assembleEntries(texts, status), status) +} + +function runErrors(): void { + const status = statuses() + const index = errorIndex(status) + const titles = new Map( + registryTexts(['blockers.md', 'learnings.md']).flatMap(entriesOf) + .map(p => [p.id, status.get(p.id)?.title ?? ''] as const)) + const seen = new Map<string, Set<string>>() + const perSession = new Map<string, number>() + let failures = 0 + for (const f of findFiles()) { + const ledger = `${f.sid}|${f.agent}` + for (const x of failuresOf(f.file)) { + const key = failureKey(x.text, x.command) + if (key === undefined) continue + failures += 1 + const id = matchOf(index, key) + const done = seen.get(ledger) ?? new Set<string>() + if (id === undefined || done.has(id)) continue + seen.set(ledger, done.add(id)) + perSession.set(f.sid, (perSession.get(f.sid) ?? 0) + 1) + console.log(`${f.sid.slice(0, 8)}${f.agent ? ' sub' : ''}: ` + + `"${oneLine(key, 120)}" -> ${id} ${titles.get(id) ?? ''}`) + } + } + const total = [...perSession.values()].reduce((a, b) => a + b, 0) + console.log('per session: ' + [...perSession] + .map(([s, n]) => `${s.slice(0, 8)}=${n}`).join(' ')) + console.log(`TOTAL failures keyed=${failures} known-line injections=` + + `${share(total, failures)} sessions with injection=` + + `${perSession.size}`) +} + +const mode = process.argv[2] +if (mode === 'prompts') runPrompts() +else if (mode === 'errors') runErrors() +else console.error('usage: recall-bench.ts prompts|errors') From debdead5e0d89c6444495c0bb500a5a9ef8d731f Mon Sep 17 00:00:00 2001 From: bchanot <chanot.bastien@gmail.com> Date: Thu, 5 Nov 2026 17:43:25 +0100 Subject: [PATCH 21/41] feat(memory): recall needs five content words (measurement gate) --- mods/memory/hooks/register.test.ts | 25 +++++++++++++++++++------ mods/memory/hooks/register.ts | 3 +++ 2 files changed, 22 insertions(+), 6 deletions(-) diff --git a/mods/memory/hooks/register.test.ts b/mods/memory/hooks/register.test.ts index 0ed33ce..f0e4771 100644 --- a/mods/memory/hooks/register.test.ts +++ b/mods/memory/hooks/register.test.ts @@ -9,7 +9,7 @@ import { parseIds, recallLine, recallBlock, failureKey, segments, suiteKeyOf, commitLabel, finishLabel, newState, switchOf, claim, onContextStart, resetContext, endContext, - appendLog, loadLog, RECALL_CAP, isTrigger, promptContext, + appendLog, loadLog, RECALL_CAP, isTrigger, MIN_CONTENT_WORDS, promptContext, DESIGN_RULE, ANALYSIS_RULE, HAIKU, RERANK_MS, IDLE_MS, } from './register' import type { LogRecord } from './register' @@ -2230,7 +2230,7 @@ const REC_INDEX = rowsOut([['BLK-001', 'mod design'], ['LRN-002', 'design notes']]) const GO = 'on va concevoir la suite du mod' -const DESIGN = 'design the mod suite please' +const DESIGN = 'design the mod suite and tests please' const NOTES = 'write notes about the mod now' /** Boots the notes world with recall fixtures; the model picks BLK-001. */ @@ -2495,7 +2495,8 @@ test('TIMErules: both rules on 64 KiB of letters, under 50 ms', () => { }) test('isTrigger: rules, fresh, idle, slash and length', () => { - expect(isTrigger('please review this module', false, 0)).toBe(true) + const long = 'please review this module and the new tests' + expect(isTrigger(long, false, 0)).toBe(true) expect(isTrigger('on va concevoir la suite', false, 0)).toBe(false) expect(isTrigger('on va concevoir la suite', true, 0)).toBe(true) expect(isTrigger('on va concevoir la suite', false, IDLE_MS)).toBe(true) @@ -2505,6 +2506,16 @@ test('isTrigger: rules, fresh, idle, slash and length', () => { expect(HAIKU).toBe('claude-haiku-5-5') }) +test('isTrigger: fewer than five content words never triggers', () => { + expect(MIN_CONTENT_WORDS).toBe(5) + expect(isTrigger('oui ça me convient', true, 0)).toBe(false) + expect(isTrigger('non pas de changement go', false, IDLE_MS)).toBe(false) + expect(isTrigger('i approve all for all', false, IDLE_MS)).toBe(false) + expect(isTrigger('design the mod suite please', false, 0)).toBe(false) + expect(isTrigger('la spec me convient, écris le plan maintenant stp', + true, 0)).toBe(true) +}) + /** * The few calls promptContext makes, over the world: the test's own `$` has * no session.root, and a hook's `$` is refused outside its module. @@ -2556,7 +2567,8 @@ test('SP1: an ordinary prompt resets the main key spent budget', async ( const st = switchedOn() const e = (text: string) => ({ text, origin: { kind: 'composer' } }) onContextStart(st, 's1') - const [block] = await promptContext(api(), st, e('design alpha now')) + const [block] = await promptContext(api(), st, + e('design alpha now, whole team')) expect(block?.length).toBe(1160) // 14 header + 3 x (381 line + 1) expect(st.spent.get('s1:main')).toBe(1160) expect(await promptContext(api(), st, e('nothing special at all'))) @@ -2765,7 +2777,7 @@ test('TE9: a recall of ~1160 chars, an ordinary prompt, then a ~395 known ' + [`BLK-00${n}`, 't'.repeat(89) + n])) } w.model = { text: 'BLK-001, BLK-002, BLK-003' } await start($) - await say($, 'design alpha now') + await say($, 'design alpha now, whole team') expect(seen[0]?.[0]?.length).toBe(1160) // 14 + 3 x (381 + 1) await say($, 'nothing special at all') const out = await failing($, w, EXIT1 + span) as { context?: string[] } @@ -2790,7 +2802,8 @@ test('RB8: a first pick the budget refuses leaves spent equal to the block', } } }) as unknown as Api onContextStart(st, 's1') const [block] = await promptContext(api, - st, { text: 'design alpha now', origin: { kind: 'composer' } }) + st, { text: 'design alpha now, whole team', + origin: { kind: 'composer' } }) expect(block).toBe('memory recall:\nBLK-002 beta — alpha b.') expect(st.spent.get('s1:main')).toBe(1150 + (block?.length ?? 0)) expect(st.seen.get('s1:main')?.has('BLK-001')).toBe(false) diff --git a/mods/memory/hooks/register.ts b/mods/memory/hooks/register.ts index d157a98..05d0425 100644 --- a/mods/memory/hooks/register.ts +++ b/mods/memory/hooks/register.ts @@ -1529,6 +1529,8 @@ export const ANALYSIS_RULE = wordRule( ) const MIN_PROMPT = 12 // code points +// Measurement gate: fewer content words than this never asks for recall. +export const MIN_CONTENT_WORDS = 5 const MAX_CANDS = 30 const RERANK_FAILS = 3 // failed reranks in a row that pause it const RERANK_PAUSE_MS = 900000 @@ -1542,6 +1544,7 @@ export function isTrigger( if (text.startsWith('/') || Array.from(text).length < MIN_PROMPT) { return false } + if (tokensOf(text).length < MIN_CONTENT_WORDS) return false const asked = cap(text, MAX_REGEX_INPUT) return fresh || idleMs >= IDLE_MS || DESIGN_RULE.test(asked) || ANALYSIS_RULE.test(asked) From c43b18cdcd7e0f4ee936dd70db513e36d08ce965 Mon Sep 17 00:00:00 2001 From: bchanot <chanot.bastien@gmail.com> Date: Thu, 5 Nov 2026 17:46:15 +0100 Subject: [PATCH 22/41] chore(bench): phase 4c re-measure after the content floor, 5 s rerank bound gated --- .claude/tasks/contracts/2026-11-04-memory-recall-1859.md | 2 ++ .claude/tasks/plans/2026-11-04-memory-recall-spike/RECALL.md | 4 ++++ 2 files changed, 6 insertions(+) diff --git a/.claude/tasks/contracts/2026-11-04-memory-recall-1859.md b/.claude/tasks/contracts/2026-11-04-memory-recall-1859.md index 26e85f1..1f48be8 100644 --- a/.claude/tasks/contracts/2026-11-04-memory-recall-1859.md +++ b/.claude/tasks/contracts/2026-11-04-memory-recall-1859.md @@ -48,6 +48,8 @@ Digest cap order `[gated 2026-11-05]` (user: "Retirer d'abord les TODO"): over 8 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). + 9. `[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 diff --git a/.claude/tasks/plans/2026-11-04-memory-recall-spike/RECALL.md b/.claude/tasks/plans/2026-11-04-memory-recall-spike/RECALL.md index fa8e6dc..325f675 100644 --- a/.claude/tasks/plans/2026-11-04-memory-recall-spike/RECALL.md +++ b/.claude/tasks/plans/2026-11-04-memory-recall-spike/RECALL.md @@ -25,3 +25,7 @@ The noise sits on content-free prompts triggered by idle time (short approvals): ## Decision (2026-11-05) User: "Plancher de contenu" — no intent recall on a prompt with fewer than 5 content words (stop words excluded); recall ships on and switchable (`"recall": false`); the injection log (4c) feeds the 4d measurement on real use. The 3 s rerank bound stays (timeout share 20 % < 25 %). + +## After the content floor (debdead) and the bound decision + +Same harness, same seed: 15 prompts meet the trigger (was 24), all sampled; 14 injections; n = 41 entries; relevant 25 / 41 = 61 % counting entries written after the prompt (temporal leakage, 6 entries), 19 / 35 = 54 % excluding them. Still under the 64 % bar; the misses are vague follow-ups, the hits are topical prompts. haiku `duration_api_ms` > 3000 over the three runs: 16 / 55 = 29 % (> 25 % bar); > 4500: 1 / 55; > 5000: 1 / 55. User decision: `RERANK_MS` = 5000. From 3261a919c29aefdabb2b9a2ffe1536643d154037 Mon Sep 17 00:00:00 2001 From: bchanot <chanot.bastien@gmail.com> Date: Thu, 5 Nov 2026 17:47:33 +0100 Subject: [PATCH 23/41] feat(memory): rerank bound 5 s (measurement gate) --- mods/memory/hooks/register.test.ts | 2 +- mods/memory/hooks/register.ts | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/mods/memory/hooks/register.test.ts b/mods/memory/hooks/register.test.ts index f0e4771..9c369b6 100644 --- a/mods/memory/hooks/register.test.ts +++ b/mods/memory/hooks/register.test.ts @@ -2260,7 +2260,7 @@ test('IR1: the first prompt of a context asks and injects the block', await say($, GO) expect(w.asks).toHaveLength(1) expect(w.asks[0]).toMatchObject({ model: 'claude-haiku-5-5', - effort: 'low', maxTokens: 64, timeoutMs: 3000 }) + effort: 'low', maxTokens: 64, timeoutMs: 5000 }) expect(w.asks[0]?.prompt).toContain('BLK-001 | mod design | ') expect(seen).toEqual([[BLOCK1]]) }) diff --git a/mods/memory/hooks/register.ts b/mods/memory/hooks/register.ts index 05d0425..d1b1919 100644 --- a/mods/memory/hooks/register.ts +++ b/mods/memory/hooks/register.ts @@ -23,7 +23,7 @@ type State = { export const IDLE_MS = 1800000 export const RECALL_CAP = 1500 export const HAIKU = 'claude-haiku-5-5' -export const RERANK_MS = 3000 +export const RERANK_MS = 5000 const SWITCH_FILE = '.claude/memory.json' const MAX_SWITCH_BYTES = 65536 From 2a0d73da120fc62ecf7d69db6aa88ab79b732ea4 Mon Sep 17 00:00:00 2001 From: bchanot <chanot.bastien@gmail.com> Date: Thu, 5 Nov 2026 17:51:19 +0100 Subject: [PATCH 24/41] docs: memory recall, known-error line and session digest --- .claude/tasks/TODO.md | 8 +- ARCHITECTURE.md | 4 +- CHANGELOG.md | 1 + README.md | 9 +- USAGE.md | 9 +- .../specs/2026-11-04-memory-recall-design.md | 97 +++++++++++-------- mods/memory/.claude-plugin/plugin.json | 2 +- mods/memory/hooks/register.ts | 2 + 8 files changed, 84 insertions(+), 48 deletions(-) diff --git a/.claude/tasks/TODO.md b/.claude/tasks/TODO.md index 5a9e5d6..b99fe67 100644 --- a/.claude/tasks/TODO.md +++ b/.claude/tasks/TODO.md @@ -114,10 +114,12 @@ Shared rules for every phase: - Measured recall (5 real FR prompts, 22 relevant entries): BM25 full text 9/22, haiku rerank of lexical top-30 14/22 (~8.5k chars). Error 4-gram match on real errors: BLK-030/031/034 exact, no false positive; 5 of 7 real errors of 2026-10-23 had NO entry: capture is the weak link. - **4b capture (mod).** Failure ledger: tool results with isError, deny or non-zero exit carrying a distinctive error line → normalized + verbatim + command, REDACTED at capture (rtk-rewrite redaction + gitleaks patterns), bounded ring per session in `$.store` (4 MiB cap), matched against the registry error index; unmatched = new failure modes. Milestones: feat/fix commit, `gitflow finish`, a suite red then green. `memory_pending` tool returns unmatched failures + milestones; /capitalize, /close and every CAPITALIZE step call it first; one context note at the next prompt after a milestone, never per turn, never at Stop. "Proactive capitalization" paragraph KEPT. Writing always = model draft + user approval + lib/memory.sh. - Built 2026-11-04 on feature/memory-capture (f1d4f9d..HEAD): mod `mods/memory`, kit 100+ cases, consumers wired, noise measured (NOISE.md); merged 2026-11-04 into develop (dfadf8a): GATE 0 MET, verifier criteria 1-15 met (9 proven live), security PASS ×4, BDR-137 - - shortcut: `mods/memory/hooks/register.ts` `isSuperseded` is a lexical reader, not memory.sh's status parser; upgrade = share that parser when 4c needs it (final review M11) - - **4c read side (next).** 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` (native matchers; the mod's `session.compact` only skips); 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 scope=global index, `memory_search` tool. + - [x] shortcut (done in 4c, Task 1: the lexical reader is gone, statuses come from `memory.sh index`): `mods/memory/hooks/register.ts` `isSuperseded` is a lexical reader, not memory.sh's status parser; upgrade = share that parser when 4c needs it (final review M11) + - **4c read side (built 2026-11-05 on feature/memory-recall, merge pending).** 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` (native matchers; the mod's `session.compact` only skips); 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 scope=global index, `memory_search` tool. - 4c follow-up from the 4b live proof (2026-11-04): `memory_pending` lists milestones of the current session only, so a `/capitalize` run right after `/clear` misses the previous session's `fix:`/finish milestones (they stay in the store). Option: list earlier-session milestones marked `(earlier session)`. Doctrine (capitalize before /clear) covers the normal path. - - **4d feedback and promotion.** DEFERRED until a plain injection log (ID, trigger kind, turn, cited or not) shows misses or noise; then /prune-memory reads it and promotion to a mechanism follows BDR-100. + - **4d feedback and promotion.** The injection log now exists (4c, store key `l:<root>`); 4d waits on its data. DEFERRED until a plain injection log (ID, trigger kind, turn, cited or not) shows misses or noise; then /prune-memory reads it and promotion to a mechanism follows BDR-100. + - [ ] shortcut: the injection log lives under `l:<root>` store keys with no cross-root cap (each key holds 200 records and 64 KiB); upgrade = a global cap or sweep of stale roots when the store nears its 1 MiB cap (`mods/memory/hooks/register.ts`). + - [ ] residual: the pre-existing `memory.sh check` call in `hooks/session-start.sh` is not time-bounded (the digest's `memory.sh index blocker` call is); upgrade = wrap it in `timeout 2`. - Proof: recall precision on ≥20 real prompts and ≥10 real errors, target ≥ the 14/22 baseline; digest after a real compaction; redaction test on the ledger; `/context` delta; captured-failure demo: an error from session N recalled in session N+1. ### Actionable diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index ed7b9d4..e06c19f 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -20,7 +20,7 @@ claude-config/ ├── update-all.sh # One-command update for all components ├── Makefile # Unified entry point: make install / doctor / update / test (make help) ├── plugins.lock.json # Version pinning for non-marketplace dependencies and vendored skills -├── hooks/ # Claude Code hooks: session start, statusline, RTK rewrite, ctx7 + design-toolchain reminders, attention notify, unpushed-work guard, manual-mode push guard, system-dir extraction guard, instruction-load log, code-limits line-width signal +├── hooks/ # Claude Code hooks: session start, statusline, RTK rewrite, ctx7 + design-toolchain reminders, attention notify, unpushed-work guard, manual-mode push guard, system-dir extraction guard, instruction-load log, memory digest at session start, code-limits line-width signal ├── githooks/ # Generated git hooks (pre-commit, post-commit, post-merge, reference-transaction), git's global core.hooksPath ├── .githooks/ # This repo's own copy of the same hooks ├── .claude/rules/ # This repo's project path rules (paths: frontmatter), loaded on Read of a matching file @@ -38,6 +38,6 @@ claude-config/ - `skills/` = entry points you invoke via `/skill-name` - `agents/` = execution units called by skills (never invoked directly by user) -- `mods/` = Claude Code mods (function-hooks plugins); each loads through the tracked symlink `skills/<name>` as `<name>@skills-dir`, live at the next session; `mods/model-router/routing.json` (tracked) holds the phase table (tier, effort and the `about` line the first-use dialog shows), every skill and agent row and the first-use decisions; the mod also redirects a main-loop code write made outside a skill run to a skill (README, "Write guard"); `mods/memory/` is the capture mod (Bash failures and milestones in the plugin store, read by `memory_pending`) +- `mods/` = Claude Code mods (function-hooks plugins); each loads through the tracked symlink `skills/<name>` as `<name>@skills-dir`, live at the next session; `mods/model-router/routing.json` (tracked) holds the phase table (tier, effort and the `about` line the first-use dialog shows), every skill and agent row and the first-use decisions; the mod also redirects a main-loop code write made outside a skill run to a skill (README, "Write guard"); `mods/memory/` is the capture mod (Bash failures and milestones in the plugin store, read by `memory_pending`) that also recalls registry entries and known errors - `templates/` = symlinked to `~/.claude/templates/` — copy into projects via `/onboard` or manually - **Graphify** builds a knowledge graph of any codebase (`/graphify query`), producing a navigable wiki in `graphify-out/wiki/`. This map helps Claude understand project structure, find relevant code faster, and reason across files. Essential for large-scope tasks (multi-file features, complex bugs, architectural changes). Small tasks should skip it and read files directly. Proposed only from 200 tracked code files: the session-start banner informs, the user decides; nothing builds a graph without that go. Where `graphify-out/graph.json` exists, the session-start hook prints the graphify usage rules. diff --git a/CHANGELOG.md b/CHANGELOG.md index 0ea7201..5320979 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -10,6 +10,7 @@ Format follows [Keep a Changelog](https://keepachangelog.com/) and this project - **Secure-by-default guardrails**: `rules/secure-by-default.md` (always on) makes six domains baseline on every project (the Supabase and cloud-function detail lives in the path rules `rules/supabase.md` and `rules/cloud-functions.md`), plus systematic API and access hygiene (auth on every route, CORS, secrets, passwords hashed with argon2id or bcrypt, never compared in clear, logged or hardcoded): hosting (rate limit, CDN and firewall, hard spend cap), Supabase (RLS on every table, owner-scoped policies, no service role key client-side), SMS and email (recorded consent, unsubscribe, STOP), cloud functions (no self-trigger, instance cap, budget stop), injection (bound values in raw escapes, `format()` for dynamic SQL, allowlisted filters, no shell into a DB tool), exposure (no data in the console, no production source map, no debug flag, no secret in hydrated state, data attributes, hidden fields or shipped comments). `/guardrails` audits them: a stdlib Python scanner (`skills/guardrails/scripts/scan.py`, FAIL / WARN / MANUAL, exit 1 on FAIL) then judgment, report in `.claude/audits/GUARDRAILS.md`. The security-auditor gate runs the scanner's `api` and `supabase` domains and blocks on FAIL. Items only a provider dashboard can set stay MANUAL, never claimed done. An optional read-only live probe (`skills/guardrails/scripts/probe.py`, `--live`) confirms a finding from outside on a target the user owns and names: anon-read, cross-user, no-auth route, CORS reflection and a capped rate-limit burst, verdicts OPEN / CLOSED / SKIPPED / ERROR. An `exposure` block in the plan adds three read-only probes, meant for a production build or a staging URL: a served or inline source map for the page's scripts, a stack trace in a 404 or a user-named error route, sensitive keys in a JSON response (identifier-shaped names printed, never values); a target the probe could not observe is SKIPPED or ERROR, never CLOSED, and every plan path must start with `/`. It sends GET, HEAD and OPTIONS only (one opt-in POST burst, capped at 25), requires `--authorized`, takes secrets from the environment never the command line, never follows a redirect to another host, and stops at a request budget. After the report, `/guardrails` proposes fixes (plan phase, so Fable when the router can switch), applies only the ones the user accepts through the `bugfixer` executor and the `lib/verify-secure-loop.md` gates, then re-scans: each accepted fix is a contract criterion whose oracle is the scanner (`--assert-absent RULE:path`, marker `GUARDRAILS-CLEAR`), and a full pass against the pre-fix baseline (`--baseline`, marker `GUARDRAILS-NO-NEW`) catches regressions; a live probe replays on the user's go; two rounds at most, residuals reported open; `--report-only` keeps the audit alone. Suites: `lib/tests/guardrails-scan.test.sh` (clean fixture plus one mutant per rule, check modes, `gates.sh` integration) and `lib/tests/guardrails-probe.test.sh` (probe logic against a localhost fixture server). - **/a11y skill**: accessibility leaves `/guardrails` and becomes its own skill. Same A11Y-* rules (img alt, field label, click without keyboard, focus outline removed, positive tabindex) on the shared scan engine (`skills/guardrails/scripts/scanner.py`, a `Catalogue` per CLI; `skills/a11y/scripts/scan.py`, markers `A11Y-CLEAR` / `A11Y-NO-NEW`), a Tab-only walk of the main flow on `--live` through `/browse` (marked not done otherwise), report `.claude/audits/A11Y.md`, fixes proposed with the alt and label wording as the user's choice, applied through the bugfix circuit (`bugfixer`, verify-secure gates, `bugfix/a11y-<date>`), re-pass against a baseline. The keyboard, alt and label doctrine moves from `rules/secure-by-default.md` to the lazy `rules/a11y.md` (loads on UI files only; `rules/web-building.md` points at it). `/guardrails` scans `injection` (INJ-*) and `exposure` (EXP-*) instead, with per-language SQL patterns, shared `code_files` / `hits` / `dedupe_lines` / `client_reachable` helpers and a walker that lists files over 1 MB by path; `--domain a11y` is a usage error there. `/web-validate` keeps full WCAG conformance. Suite `lib/tests/a11y-scan.test.sh`; routing row `reflect`; a top-level skill in no pack, so on under every profile. - **memory mod**: `mods/memory/`, a Claude Code mod, captures Bash failures (`Exit code N` whose last line is error-shaped (a word like error, fatal, cannot, denied, a shellcheck code), redacted at capture (env secrets, vendor key prefixes, `--token` flags, API-key headers and cookies, JSON/YAML password/token/secret pairs, a 40-hex URL user; residual `user:p@ss@host` partial), sub-agent ones marked) and milestones (a `feat`/`fix` commit, a `gitflow.sh finish`, a `make test` red then green) in the plugin `$.store` (3 sessions per project, 50 failures each, 1 MiB). One context note at the first prompt after a milestone; the `mcp__memory__memory_pending` tool lists milestones and failures as `NEW` or `known <ID>` against the BLK/LRN entries, and `/capitalize`, `/close` and the CAPITALIZE steps call it first. It never writes a registry. Off with `{"enabled": false}` in `~/.claude/memory.json`. Residuals: concurrent sessions last writer wins, non-Bash failures not captured, noise 83 % measured before the filter, cut by two thirds (`NOISE.md`). +- **memory recall**: the memory mod hands registry entries back. A composer prompt of 5 content words or more that opens a context, follows 30 minutes idle or holds a design or analysis word gets up to 3 live BDR, LRN or BLK entries (BM25 top 30, one haiku rerank bounded to 5 s), and a Bash failure matching a live BLK or LRN entry gets a `memory: known <ID>` line; 1500 characters per turn, each entry once per context, sub-agents on the error channel only. `hooks/session-start.sh` prints a `memory digest:` (open BLK from `memory.sh index blocker`, 3 Actionable TODO items, last journal line, 800 characters, TODO dropped first) on startup, clear and compact. `"recall": false` in `~/.claude/memory.json` cuts the injections; each one is logged under the `l:<root>` store key for phase 4d. Measured precision 54 to 61 % against the 64 % bar, so recall ships switchable. - **model-router mod**: `mods/model-router/`, a Claude Code mod (function-hooks plugin), routes every repo skill and agent from phase rows (`plan`, `reflect`, `orchestrate`, `escalate`, `judge`, `audit`, `implement`, `write`, `verify`, `explore`, `apply`, `mechanical`; built-ins Explore on sonnet/medium, Plan on opus/xhigh). A typed skill routes the main loop to its row, and a best-tier row holds across turns in a run slot until `/route clear`, `/route off`, a user `/model` or a typed skill on a non-best row. Agents get their row's model at spawn (within the tier, upward only) and its effort on every step; explicit Agent params win. Orchestrators declare their phases through the `mcp__model-router__route` tool. `ultrathink` in a prompt sets the turn's minimum effort and `/route effort=max` holds until `/route clear`; the built-in `/effort` is not a lever inside a run. `/route show` names the run slot (`main: run <phase>`), and a `null` row in the override drops a default row. The model gets a `route` tool and the user a `/route` command (`show|clear|off|on|reload|pending|ask on|off|forget <name|all|projects>|<phase>|model=<alias|id> effort=<level>|switch on|off|verbose on|off`). Optional per-machine config `~/.claude/model-router.json`, where `"enabled": false` turns it off on that machine. The spinner suffix and the status line show the route in force. It loads in every session through the tracked symlink `skills/model-router` (`model-router@skills-dir`). `make doctor` gains a Mods section; suite `make test suite=lib/tests/mods.test.sh`. Known limits: a main-loop switch (a `/model` hand pick excepted) runs only while the cold read it costs (the context minus what the target model's prompt cache holds) fits `upgradeMaxTokens` (200000) or `downgradeMaxTokens` (120000), and a downgrade also needs `mainModelSwitch` (on by default, off on any non-boolean value); the hooks send full model ids, so the `models` table has to follow new versions. - **model-router first-use confirmation**: `mods/model-router/routing.json` (tracked) is the single source of the phase table and of every skill and agent row, and keeps the decisions: `confirmed`, `changed` (`from`/`to`), `projects` exceptions keyed by the origin remote reduced to `host/path` (credentials and local paths never stored), and `ask`. The first use of a rowed typed skill, a rowed agent spawn or a main-loop phase declared through the `route` tool opens a dialog with context: the skill's description (first sentence of its `SKILL.md` frontmatter) or the agent's, the phase with its `about` line (a new field on each of the 12 phases) and the model id and effort the next step really runs on. A row offers Later, Keep or Change; a main-loop phase Later or Keep. Change asks the model (fable, opus, sonnet, haiku with their tier), then the effort among those the phases of that model use (skipped when there is only one), then Everywhere or This project only; the pair maps to an existing phase (rows stay phase names, the same phase counts as Keep, a pair no phase offers is added by hand as a new phase). A skill-row change toasts the model and effort it now runs on, with the `/route switch on` hint when the main loop holds back a downgrade; a free-text answer counts as Later. One dialog at a time, never in headless (`-p`) runs or inside a sub-agent. Only a dialog answer, `/route ask on|off` or `/route forget` (which takes decisions back; a changed row returns to its shipped phase, the frontmatter floors stay yours to realign) writes the file (serialized, 64 KiB cap, never created when absent); each write asks you to commit it from the config repo. `/route pending` lists unconfirmed rows and phases. Layers: routing.json < `~/.claude/model-router.json` (its `ask` wins); a project's `.claude/model-router.json` is never read. Tests: `mods/model-router/hooks/register.test.ts`. - **model-router `/model` scope**: a `/model <name>` typed in the composer, or a pick in the `/model` picker, with a model the table knows asks where it applies. The picker's switch is held first (PreModelSwitch deny; the engine prints that a hook blocked it); a pick while another dialog is open is refused with `answer the open dialog first`. This project writes the full id as `model` into the project's `.claude/settings.local.json` (created if absent, refused through a link) and sets a sticky model route. This conversation sets the sticky route only. Everywhere runs the native `/model` (user `settings.json`). Both non-native answers drop the run slot and keep a sticky effort. With the picker's Default, an unknown name, a headless run or another origin, the native command runs with no question. A model chosen in that dialog always switches: it bypasses the cold-read caps and the `mainUpgrade` / `mainModelSwitch` flags, and while it is marked down or outside a known window it waits and the automatic chain decides. A native switch or `/clear` drops it; `/route model=` keeps the caps. Known limits: the `/config` Model row still writes user `settings.json`; a dialog never answered has no timeout. Tests: `mods/model-router/hooks/register.test.ts`. diff --git a/README.md b/README.md index be00e4d..53233b0 100644 --- a/README.md +++ b/README.md @@ -161,9 +161,14 @@ Limits: a main-loop switch re-reads cold the part of the context the target mode - Milestones: a successful `feat` or `fix` commit (plain `-m` or heredoc form), a `gitflow.sh finish` (not `finish chore`), a `make test ...` command red then green. Milestones are recorded on the main loop only: sub-agent commits and finishes are ignored. - Store: the plugin's `$.store`, keyed by project root: the 3 most recent sessions per project, 50 failures per session, 2 KiB per entry, 1 MiB for the whole store. It survives `/clear`. The store is the plugin's JSON file under the Claude configuration directory (observed here as `~/.claude/plugins/store/memory_skills-dir-<hash>.json`, an engine layout, not fixed by this repo); delete it to wipe the captures. - Note: one context line, `memory: <kind> <label> — <n> new failure mode(s) this session; /capitalize when ready.`, at the first composer prompt after a milestone. Never per turn, never at Stop, never in a sub-agent. -- Tool: `mcp__memory__memory_pending` (deferred: a skill loads it once with `ToolSearch("select:mcp__memory__memory_pending")`). `/capitalize`, `/close` and the CAPITALIZE steps of `/feat`, `/bugfix`, `/hotfix`, `/ship-feature` and `/commit-change` call it first. It lists this session's milestones, then the failures as `NEW` or `known <ID>` (word 4-grams matched against the backticked spans of BLK and LRN entries, superseded ones excluded), earlier sessions marked. Every text it returns is data. It never writes a registry and never calls `lib/memory.sh`. +- Tool: `mcp__memory__memory_pending` (deferred: a skill loads it once with `ToolSearch("select:mcp__memory__memory_pending")`). `/capitalize`, `/close` and the CAPITALIZE steps of `/feat`, `/bugfix`, `/hotfix`, `/ship-feature` and `/commit-change` call it first. It lists this session's milestones, then the failures as `NEW` or `known <ID>` (word 4-grams matched against the backticked spans of BLK and LRN entries, superseded ones excluded through `lib/memory.sh index`; when that reader is unavailable every entry is matched and the `index:` line ends `status reader unavailable`), earlier sessions marked. Every text it returns is data. It never writes a registry and never calls `lib/memory.sh`. +- Recall: the mod hands registry entries back at the moment they matter. A prompt typed in the composer (never a slash command, at least 5 content words, stop words excluded) triggers it when it is the first of a context (start, `/clear`, `/compact`), comes after 30 minutes idle, or holds a design or analysis word (plan, architecture, design, why, explain, analyse, review, audit and their French forms). BM25 ranks the live BDR, LRN and BLK entries, one haiku call keeps at most 3, bounded to 5 seconds. The context block `memory recall:` carries one line per entry (ID, title, lesson), at most 1500 characters per turn, each entry once per context. Any failure or timeout injects nothing. +- Known error: a Bash failure whose key matches a live BLK or LRN entry attaches `memory: known <ID> <title> — <lesson>` to the tool answer, once per ID per context, from the same 1500-character budget. Sub-agents get this channel only. +- Digest: `hooks/session-start.sh` prints `memory digest:` on `startup`, `clear` and `compact` (never `resume`) in a project that has `.claude/memory/`: up to 3 open BLK from `memory.sh index blocker` (the rest counted, upstream ones counted), up to 3 unchecked Actionable TODO items, the last journal line, 800 characters at most. When the cap bites, TODO lines drop first, then nothing else. Without `timeout` and `jq` it prints only from a terminal. +- Recall switch: `{"enabled": true, "recall": false}` in `~/.claude/memory.json` cuts the injections (recall and known-error line) and keeps capture. Each injection is logged under the `l:<root>` store key (last 200 records, 64 KiB), never shown; phase 4d reads it. +- Recall residuals: measured on 14 days of this repo's transcripts, precision is 54 to 61 % against a 64 % bar, so recall ships on and switchable, and the log decides. The router's classifier label is not used. EVAL entries are not recalled. Each failing command that matches an entry spawns one `memory.sh index`. The haiku bound drops the recalls that answer slower than 5 seconds. - Off switch: `{"enabled": false}` in `~/.claude/memory.json`, read at the first event of a session, so it applies at the next session or after `/reload-plugins`. Off, the tool answers `memory capture is off (~/.claude/memory.json)`. A switch file that cannot be read, or whose `enabled` is not a boolean, keeps capture on and logs one line. -- Residuals: cross-process writes are unverified (two concurrent sessions: last writer wins). Non-Bash failures are not captured. `-b` counts as curl's cookie flag only when `curl` opens its command segment, after optional env assignments, `sudo`, `rtk` or `$(`: `time curl -b …` keeps its cookies. The superseded reader is lexical (header tag or last labelled status line). 40-hex Gitea tokens are kept by design: they look like commit SHAs. A session root that moves with `/cd` or a worktree move hides earlier captures of the same repo from /capitalize. A bare `gitflow.sh finish` on a chore branch counts as a milestone. Measured at 83 % noise before the error-shaped filter over 14 days of this repo's transcripts; the filter keeps every useful sample and cuts captures by two thirds (`.claude/tasks/plans/2026-11-03-memory-capture-spike/NOISE.md`). +- Residuals: cross-process writes are unverified (two concurrent sessions: last writer wins). Non-Bash failures are not captured. `-b` counts as curl's cookie flag only when `curl` opens its command segment, after optional env assignments, `sudo`, `rtk` or `$(`: `time curl -b …` keeps its cookies. 40-hex Gitea tokens are kept by design: they look like commit SHAs. A session root that moves with `/cd` or a worktree move hides earlier captures of the same repo from /capitalize. A bare `gitflow.sh finish` on a chore branch counts as a milestone. Measured at 83 % noise before the error-shaped filter over 14 days of this repo's transcripts; the filter keeps every useful sample and cuts captures by two thirds (`.claude/tasks/plans/2026-11-03-memory-capture-spike/NOISE.md`). --- diff --git a/USAGE.md b/USAGE.md index 94b42b3..f9d2a10 100644 --- a/USAGE.md +++ b/USAGE.md @@ -210,9 +210,14 @@ Le mod `mods/memory/` note les échecs Bash et les jalons de la session pour que - Jalons : un commit `feat` ou `fix` réussi (`-m` simple ou heredoc), un `gitflow.sh finish` (pas `finish chore`), une commande `make test ...` rouge puis verte. Les jalons ne sont notés que sur la boucle principale : commits et finish de sous-agents ignorés. - Stockage : le `$.store` du plugin, par racine de projet : 3 sessions les plus récentes par projet, 50 échecs par session, 2 Kio par entrée, 1 Mio pour tout le store. Il survit à `/clear`. Le store est le fichier JSON du plugin sous le dossier de configuration de Claude (observé ici en `~/.claude/plugins/store/memory_skills-dir-<hash>.json`, disposition du moteur, non fixée par ce dépôt) ; le supprimer efface les captures. - La note : une ligne de contexte, `memory: <kind> <label> — <n> new failure mode(s) this session; /capitalize when ready.`, au premier prompt tapé après un jalon. Jamais à chaque tour, jamais au Stop, jamais dans un sous-agent. -- L'outil : `mcp__memory__memory_pending` (différé : un skill le charge une fois avec `ToolSearch("select:mcp__memory__memory_pending")`). `/capitalize`, `/close` et les étapes CAPITALIZE de `/feat`, `/bugfix`, `/hotfix`, `/ship-feature` et `/commit-change` l'appellent en premier. Il liste les jalons de la session, puis les échecs `NEW` ou `known <ID>` (4-grammes de mots comparés aux passages entre accents graves des entrées BLK et LRN, les remplacées exclues), les sessions précédentes signalées. Chaque texte est une donnée. Il n'écrit aucun registre et n'appelle pas `lib/memory.sh`. +- L'outil : `mcp__memory__memory_pending` (différé : un skill le charge une fois avec `ToolSearch("select:mcp__memory__memory_pending")`). `/capitalize`, `/close` et les étapes CAPITALIZE de `/feat`, `/bugfix`, `/hotfix`, `/ship-feature` et `/commit-change` l'appellent en premier. Il liste les jalons de la session, puis les échecs `NEW` ou `known <ID>` (4-grammes de mots comparés aux passages entre accents graves des entrées BLK et LRN, les remplacées exclues via `lib/memory.sh index` ; si ce lecteur est indisponible, toutes les entrées sont comparées et la ligne `index:` finit par `status reader unavailable`), les sessions précédentes signalées. Chaque texte est une donnée. Il n'écrit aucun registre et n'appelle pas `lib/memory.sh`. +- Rappel : le mod ramène les entrées des registres au bon moment. Un prompt tapé dans le composer (jamais une commande slash, au moins 5 mots de contenu, mots vides exclus) le déclenche s'il est le premier d'un contexte (démarrage, `/clear`, `/compact`), s'il suit 30 minutes d'inactivité, ou s'il contient un mot de conception ou d'analyse (plan, architecture, design, pourquoi, explique, analyse, review, audit et leurs équivalents anglais). BM25 classe les entrées BDR, LRN et BLK vivantes, un appel haiku en garde 3 au plus, borné à 5 secondes. Le bloc de contexte `memory recall:` porte une ligne par entrée (ID, titre, leçon), 1500 caractères par tour au plus, chaque entrée une fois par contexte. Un échec ou un dépassement n'injecte rien. +- Erreur connue : un échec Bash dont la clé correspond à une entrée BLK ou LRN vivante ajoute `memory: known <ID> <titre> — <leçon>` à la réponse de l'outil, une fois par ID et par contexte, sur le même budget de 1500 caractères. Les sous-agents n'ont que ce canal. +- Digest : `hooks/session-start.sh` affiche `memory digest:` sur `startup`, `clear` et `compact` (jamais `resume`) dans un projet qui a `.claude/memory/` : jusqu'à 3 BLK ouverts issus de `memory.sh index blocker` (le reste compté, les « upstream » comptés), jusqu'à 3 items Actionable non cochés du TODO, la dernière ligne du journal, 800 caractères au plus. Quand le plafond mord, les lignes TODO tombent d'abord, rien d'autre. Sans `timeout` ni `jq`, il ne s'affiche que depuis un terminal. +- Interrupteur du rappel : `{"enabled": true, "recall": false}` dans `~/.claude/memory.json` coupe les injections (rappel et ligne d'erreur connue) et garde la capture. Chaque injection est journalisée sous la clé de store `l:<racine>` (200 enregistrements, 64 Kio), jamais affichée ; la phase 4d la lit. +- Limites du rappel : mesurée sur 14 jours de transcripts de ce dépôt, la précision est de 54 à 61 % pour une barre à 64 %, donc le rappel est livré actif et coupable, et le journal tranchera. L'étiquette du classifieur du routeur n'est pas utilisée. Les entrées EVAL ne sont pas rappelées. Chaque commande en échec qui correspond à une entrée lance un `memory.sh index`. La borne haiku écarte les rappels qui répondent après 5 secondes. - Interrupteur : `{"enabled": false}` dans `~/.claude/memory.json`, lu au premier événement d'une session : effet à la session suivante ou après `/reload-plugins`. Coupé, l'outil répond `memory capture is off (~/.claude/memory.json)`. Un fichier illisible, ou dont `enabled` n'est pas un booléen, laisse la capture active et journalise une ligne. -- Limites connues : les écritures entre processus ne sont pas vérifiées (deux sessions simultanées : la dernière écrit). Les échecs hors Bash ne sont pas captés. `-b` ne vaut drapeau de cookies de curl que si `curl` ouvre son segment de commande, après d'éventuelles affectations de variables, `sudo`, `rtk` ou `$(` : `time curl -b …` garde ses cookies. Le lecteur « remplacé » est lexical (étiquette d'en-tête ou dernière ligne de statut étiquetée). Un jeton de 40 hexadécimaux nu est gardé à dessein : il ressemble à un SHA de commit (expurgé seulement comme utilisateur d'URL). Une racine de session qui bouge avec `/cd` ou un changement de worktree cache à /capitalize les captures précédentes du même dépôt. Un `gitflow.sh finish` nu sur une branche chore compte comme un jalon. Bruit mesuré à 83 % avant le filtre de forme d'erreur sur 14 jours de transcripts de ce dépôt ; le filtre garde tous les échantillons utiles et réduit les captures des deux tiers (`.claude/tasks/plans/2026-11-03-memory-capture-spike/NOISE.md`). +- Limites connues : les écritures entre processus ne sont pas vérifiées (deux sessions simultanées : la dernière écrit). Les échecs hors Bash ne sont pas captés. `-b` ne vaut drapeau de cookies de curl que si `curl` ouvre son segment de commande, après d'éventuelles affectations de variables, `sudo`, `rtk` ou `$(` : `time curl -b …` garde ses cookies. Un jeton de 40 hexadécimaux nu est gardé à dessein : il ressemble à un SHA de commit (expurgé seulement comme utilisateur d'URL). Une racine de session qui bouge avec `/cd` ou un changement de worktree cache à /capitalize les captures précédentes du même dépôt. Un `gitflow.sh finish` nu sur une branche chore compte comme un jalon. Bruit mesuré à 83 % avant le filtre de forme d'erreur sur 14 jours de transcripts de ce dépôt ; le filtre garde tous les échantillons utiles et réduit les captures des deux tiers (`.claude/tasks/plans/2026-11-03-memory-capture-spike/NOISE.md`). ## Les plugins — décision rapide diff --git a/docs/superpowers/specs/2026-11-04-memory-recall-design.md b/docs/superpowers/specs/2026-11-04-memory-recall-design.md index c3b2725..30e8c87 100644 --- a/docs/superpowers/specs/2026-11-04-memory-recall-design.md +++ b/docs/superpowers/specs/2026-11-04-memory-recall-design.md @@ -16,34 +16,41 @@ Success: precision of the injected entries at or above the 14/22 baseline after a real compaction. ## Unit 1 — shared reader (register.ts) -- Status: `lib/memory.sh -C <root> index` through `$.process.run(['bash', +- Status and titles: `lib/memory.sh -C <root> index` through `$.process.run(['bash', <HOME>/.claude/lib/memory.sh, '-C', root, 'index'], {timeoutMs: 2000})`, - raced by an own 2.5 s timer; rows `| ID | Date | Title | Status |`; an ID is - closed for recall when its status word is `superseded` or `deprecated` - (memory.sh is the single reader, BDR-129; spike: 128 ms). The script path is - `$HOME/.claude/lib/memory.sh` (the installed lib, the same one the skills - call). A failed or timed-out read → the status map is unavailable for that - call: recall injects nothing, the error channel injects nothing, and - `memory_pending` answers as today with an `index: status reader unavailable` - line and every failure `NEW`. -- Entries: the registry files `decisions.md`, `learnings.md`, `blockers.md` - read with `$.fs.read` (stat first, 4 MiB cap per file, as 4b `loadIndex`); - the 4b `entriesOf` heading regex extends to `BDR|LRN|BLK`; each entry keeps - `{id, kind, title, lesson, body}`. + raced by an own 2.5 s timer; rows `| ID | Date | Title | Status |`. memory.sh + is the single reader (BDR-129): `parseIndex` returns `Map<id, {status, + title}>`, the title already fence-aware with tag and date stripped, and an ID + is closed for recall when its status word is `superseded` or `deprecated`. + An ID absent from a map that exists is not live (fail closed). The script + path is `$HOME/.claude/lib/memory.sh`. The run is skipped when no registry + file was read. +- Status unavailable (failed, timed out or malformed read): `memory_pending` + still labels each failure `NEW` or `known <ID>` from ALL entries (advisory, + superseded ones included) and its `index:` line ends `status reader + unavailable`; recall and the error channel inject nothing. +- Entries: `decisions.md`, `learnings.md`, `blockers.md` read with `$.fs.read` + (stat first, 4 MiB cap per file). `entriesOf` only splits bodies (heading + regex = the 4b one widened to `BDR|LRN|BLK`, no title capture); the pure + `assembleEntries(texts, index)` joins kind, the memory.sh title cut at 100 + with `…`, the lesson and the body into `{id, kind, title, lesson, body}`. + 4b callers load `blockers.md` and `learnings.md` only. - Lesson line: BDR the `Decision` field; LRN `Apply`, else `Future application`, else `Pattern`; BLK `Solution`, else `Real cause` (label match - case-insensitive, bold or plain, `- **Label**:` / `- Label:`); its first - sentence, cut at 280 chars with `…`; an entry without one has the empty - lesson (title only). -- The 4b lexical `isSuperseded` and its `shortcut:` comment are removed: the - error index (BLK + LRN spans, as 4b) takes its live set from the same status - map. + case-insensitive, bold or plain); its first sentence, cut at 280 chars with + `…`; none → empty lesson (title only). Label and heading regexes carry + bounded prefixes (`.{0,2000}`, `[^\n]{0,300}`), no `$`. +- The 4b lexical `isSuperseded` and its `shortcut:` comment are gone: the error + index takes its live set from the same status map. ## Unit 2 — intent recall (`prompt.submit`) - Trigger: origin `composer`, `turnId` absent, not a slash command (text not - starting `/`), ≥ 12 code points, and one of: the first such prompt of the - context (set at `session.start` and on `classic.SessionStart` source - `clear` or `compact`, consumed by the first qualifying prompt); the first + starting `/`), ≥ 12 code points, and at least 5 content words (tokens minus + the stop-word list; measurement gate 2026-11-05, `MIN_CONTENT_WORDS`), and + one of: the first such prompt of the context (set at `session.start` and + consumed by the first qualifying prompt; a new context starts through the + classic `SessionStart` hook on source `startup`, `clear` or `compact`, keyed + by the event's `session_id` when present, else `$.session.id()`); the first after ≥ 30 min without a composer prompt in this session; a match of the design or analysis keyword patterns, copied from model-router's default prompt rules (`mods/model-router/hooks/register.ts`, commit 9bbd1d5): @@ -56,7 +63,8 @@ after a real compaction. redacted (4b `redact`). Entries already injected in this context are removed before ranking. Top 30 with a score > 0. - Rerank: `$.model.complete({model: 'claude-haiku-5-5', effort: 'low', - maxTokens: 64, timeoutMs: 3000, prompt})`, raced by an own 3 s timer + maxTokens: 64, timeoutMs: 5000, prompt})`, raced by an own 5 s timer + (`RERANK_MS`; measurement gate 2026-11-05: 29 % of calls ran over 3 s) (LRN-218). The prompt: the redacted query, the candidates one per line as `ID | title | lesson`, and the instruction to answer at most 3 IDs, comma separated, or `none`. The answer is parsed for `(BDR|LRN|BLK)-\d+`, kept @@ -92,24 +100,30 @@ after a real compaction. reset by each composer prompt; a sub-agent (error channel only) has 1500 chars for its whole context. - Log: each injection appends `{at, session, agent, channel: 'prompt' | - 'tool', ids}` to the project's store value (`log`, last 200 kept, 4b write - chain and size caps); never displayed; 4d reads it. + 'tool', ids}` to its own store key `l:<root>` (≤ 200 records, ≤ 64 KiB, + oldest dropped), outside the session sweep and the project value; never + displayed; 4d reads it. No cross-root cap (TODO `shortcut:`). ## Unit 5 — session digest (`hooks/session-start.sh`) - Reads the hook JSON from stdin only when stdin is not a terminal, with - `timeout 1`; `source` taken with jq when present, else empty. Prints the - digest for `startup`, `clear`, `compact`, and for an empty source (a manual - run); never for `resume`. + `timeout 1`; `source` taken with jq. Prints the digest for `startup`, + `clear`, `compact`, and for an empty source (a manual run); never for + `resume`. Without `timeout` or `jq` the source is unknowable: the digest + prints only when stdin is a terminal, never from a hook. - Only in a project whose git toplevel (else cwd) has `.claude/memory/`: - `memory digest:` then up to three kinds of lines: - open BLK from `reconcile_blk_open` with status word `open` (`BLK-n title`, - ≤ 160 chars each, at most 3, then `+N more`), the upstream ones counted - (`+N upstream`); the first 3 unchecked `- [ ]` items under - `### Actionable` in `.claude/tasks/TODO.md` (≤ 160 chars each); the last - `- ` line of `.claude/memory/journal.md` (≤ 160 chars). Block ≤ 800 chars. - Any missing file or section → that line is omitted; nothing to show → no - block. Fail silent: an error in the digest never changes the banner or the - exit code. + `memory digest:` then up to four kinds of lines: + open BLK from `memory.sh -C <root> index blocker` (run under `timeout 2`, + rows with status word `open`: `- open: BLK-n title`, ≤ 160 chars each, at + most 3, then `+N more`), the upstream ones counted (`+N upstream`); the first + 3 unchecked `- [ ]` items under `### Actionable` in `.claude/tasks/TODO.md` + (≤ 160 chars each); the last `- ` line of `.claude/memory/journal.md` + (≤ 160 chars). Cuts use bash `${v:0:159}…` and stay valid UTF-8. +- Block ≤ 800 chars. Header, BLK lines, the count line and the journal line + always stay; TODO lines are added in order while they fit, so under the cap + they drop first, whole lines, never a mid-line cut. Any missing file or + section → that line is omitted; nothing to show → no block. Fail silent: a + `memory.sh` that fails, hangs, prints malformed rows or a `blockers.md` that + is a directory never changes the banner or the exit code. - No SubagentStart twin. ## Unit 6 — `memory_pending` @@ -142,7 +156,7 @@ ticked at merge, 4d stays deferred with the log now in place). `.claude/tasks/plans/2026-11-04-memory-recall-spike/` imports the mod's own functions (no port) and calls haiku through `claude -p --model haiku`: (a) 20 real composer prompts from 14 days of this repo's transcripts that - meet the trigger: injected IDs per prompt, timeout share at 3 s; the + meet the trigger: injected IDs per prompt, timeout share at the bound; the controller labels each injected entry relevant or not, the user checks the labels; bar: relevant share ≥ 64 % (14/22). (b) the 14-day Bash failure replay: injections per session and the noise share on the injected ones, @@ -151,6 +165,13 @@ ticked at merge, 4d stays deferred with the log now in place). fixture BLK attaches the line); interactive by the user for recall (a design prompt in a fresh session), and the digest after a real `/compact`. +## Measurement gates (2026-11-05) +`.claude/tasks/plans/2026-11-04-memory-recall-spike/RECALL.md`: on 14 days of +transcripts the rerank precision is 54 to 61 % against the 64 % bar. Decided: +recall ships on and switchable (`"recall": false`), with a content floor (5 +content words, Unit 2) and `RERANK_MS` 5000 (Unit 2); the injection log feeds +4d. Error channel: n = 3, insufficient sample. + ## Out of scope Read path triggers, Bash command triggers, critical deny-once, Tier 1, cross-repo index, `memory_search` tool, reading the router's classifier diff --git a/mods/memory/.claude-plugin/plugin.json b/mods/memory/.claude-plugin/plugin.json index fd42d91..44914ef 100644 --- a/mods/memory/.claude-plugin/plugin.json +++ b/mods/memory/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "memory", "version": "0.1.0", - "description": "Captures what fails in a session (failed Bash runs, commits, finished branches) and hands it to the memory registries, fail-open, with a per-machine off switch.", + "description": "Captures what fails in a session (failed Bash runs, commits, finished branches) and hands it to the memory registries, recalls matching registry entries on design prompts and known errors, fail-open, with a per-machine off switch.", "author": { "name": "bchanot" } diff --git a/mods/memory/hooks/register.ts b/mods/memory/hooks/register.ts index d1b1919..1ac74c8 100644 --- a/mods/memory/hooks/register.ts +++ b/mods/memory/hooks/register.ts @@ -3,6 +3,8 @@ // and the per-session state. Every hook reads the session id and root at // the point of use, never from a cache. A hook that fails passes the event // through unchanged: the mod may never break a tool call or a prompt. +// It also recalls: registry entries on a qualifying prompt and a known-error +// line on a Bash failure, both switchable with "recall": false. import type { EngineInterface, On, Register } from 'claude-code' type Api = EngineInterface From c4cc1bb8516f7eb7096dad471cde862c2eef3a80 Mon Sep 17 00:00:00 2001 From: bchanot <chanot.bastien@gmail.com> Date: Thu, 5 Nov 2026 17:52:34 +0100 Subject: [PATCH 25/41] chore(contract): phase 4c headless known-line proof PASS --- .claude/tasks/contracts/2026-11-04-memory-recall-1859.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/.claude/tasks/contracts/2026-11-04-memory-recall-1859.md b/.claude/tasks/contracts/2026-11-04-memory-recall-1859.md index 1f48be8..985c165 100644 --- a/.claude/tasks/contracts/2026-11-04-memory-recall-1859.md +++ b/.claude/tasks/contracts/2026-11-04-memory-recall-1859.md @@ -73,3 +73,7 @@ Rerank bound gate `[gated 2026-11-05]` (three harness runs: 16/55 haiku calls ov - 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`. From 717e2262e585977a8565aabda9718db27de9c4f4 Mon Sep 17 00:00:00 2001 From: bchanot <chanot.bastien@gmail.com> Date: Thu, 5 Nov 2026 18:15:07 +0100 Subject: [PATCH 26/41] chore(contract): phase 4c final review gate [gated] --- .claude/tasks/contracts/2026-11-04-memory-recall-1859.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.claude/tasks/contracts/2026-11-04-memory-recall-1859.md b/.claude/tasks/contracts/2026-11-04-memory-recall-1859.md index 985c165..adf1a0c 100644 --- a/.claude/tasks/contracts/2026-11-04-memory-recall-1859.md +++ b/.claude/tasks/contracts/2026-11-04-memory-recall-1859.md @@ -50,6 +50,8 @@ Measurement gate `[gated 2026-11-05]` (RECALL.md: prompt channel 19/38 = 50 % re 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`). + 9. `[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 From 2397c36f061ce69a00a568fbfccf6a8f2fbf91b7 Mon Sep 17 00:00:00 2001 From: bchanot <chanot.bastien@gmail.com> Date: Thu, 5 Nov 2026 18:19:22 +0100 Subject: [PATCH 27/41] =?UTF-8?q?fix(memory):=20final=20review=20=E2=80=94?= =?UTF-8?q?=202-letter=20stop=20words,=20log=20keys=20in=20the=20sweep,=20?= =?UTF-8?q?trigger=20and=20outcome=20in=20the=20log?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- mods/memory/hooks/register.test.ts | 148 ++++++++++++++++++++++- mods/memory/hooks/register.ts | 185 ++++++++++++++++++++++------- 2 files changed, 282 insertions(+), 51 deletions(-) diff --git a/mods/memory/hooks/register.test.ts b/mods/memory/hooks/register.test.ts index 9c369b6..bf9d79f 100644 --- a/mods/memory/hooks/register.test.ts +++ b/mods/memory/hooks/register.test.ts @@ -2149,6 +2149,8 @@ const storeApi = (w: World) => ({ store: { w.sets.push(k) w.kv.set(k, JSON.parse(JSON.stringify(v))) }, + keys: async () => [...w.kv.keys()], + delete: async (k: string) => void w.kv.delete(k), } }) as never const REC = (at: number, ids = ['BLK-001']): LogRecord => @@ -2198,6 +2200,56 @@ test('LG3: over 64 KiB serialized, the oldest records are dropped', expect(JSON.stringify(log).length).toBeLessThanOrEqual(65536) }) +test('LG5: a record without trigger and outcome stays valid', async ( + $, on, +) => { + const bad = { ...REC(3), trigger: 'x' } + const odd = { ...REC(4), outcome: 'x' } + const ok = { ...REC(5), trigger: 'idle', outcome: 'none' } + const seed = { [`l:${ROOT}`]: [REC(1), bad, odd, ok] } + const w = await boot($, on, { seed }) + expect(await loadLog(storeApi(w), ROOT)).toEqual([REC(1), ok]) +}) + +/** A raw log of `n` records of about `kb` KiB, the newest at `at`. */ +const bigLog = (at: number, kb: number) => + [REC(at, ['X'.repeat(kb * 1024)])] + +test('LG6: over the engine cap, the oldest l: key goes first', async ( + $, on, +) => { + const seed: Record<string, unknown> = {} + for (let i = 1; i <= 68; i++) seed[`l:/r${i}`] = bigLog(i * 10, 60) + const w = await boot($, on, { seed }) + await failing($, w, EXIT1 + 'fatal: bad thing') + expect(w.kv.has('l:/r1')).toBe(false) + expect(w.kv.has('l:/r68')).toBe(true) + expect(failuresOf(w)).toHaveLength(1) + const bytes = [...w.kv.values()].reduce( + (n: number, v) => n + JSON.stringify(v).length, 0) + expect(bytes).toBeLessThanOrEqual(4194304) +}) + +test('LG7: the current root log is never evicted while others exist', + async ($, on) => { + const seed: Record<string, unknown> = { [`l:${ROOT}`]: bigLog(1, 60) } + for (let i = 1; i <= 68; i++) seed[`l:/r${i}`] = bigLog(i * 10, 60) + const w = await boot($, on, { seed }) + await failing($, w, EXIT1 + 'fatal: bad thing') + expect(w.kv.has(`l:${ROOT}`)).toBe(true) + expect(w.kv.has('l:/r1')).toBe(false) + }) + +test('LG8: a new log key sweeps too, before its own write', async ( + $, on, +) => { + const w = await boot($, on) + for (let i = 1; i <= 68; i++) w.kv.set(`l:/r${i}`, bigLog(i * 10, 60)) + await appendLog(storeApi(w), newState(), ROOT, REC(900)) + expect(w.kv.has('l:/r1')).toBe(false) + expect(w.kv.get(`l:${ROOT}`)).toEqual([REC(900)]) +}) + test('LG4: loadLog drops malformed records; project key untouched', async ($, on) => { const bad = { at: 'x', session: 's1', agent: 'main', ids: [] } @@ -2229,7 +2281,7 @@ const REC_FILES = { [BLK]: BLK1, [LRN]: LRN2 } const REC_INDEX = rowsOut([['BLK-001', 'mod design'], ['LRN-002', 'design notes']]) -const GO = 'on va concevoir la suite du mod' +const GO = 'on va concevoir la suite du mod memory recall' const DESIGN = 'design the mod suite and tests please' const NOTES = 'write notes about the mod now' @@ -2253,6 +2305,81 @@ const say = ($: Engine, text: string, turnId?: string) => $.prompt.submit({ const BLOCK1 = `memory recall:\n${BLK1_LINE}` +/** The `trigger` and `outcome` of every logged ask, oldest first. */ +async function askLog(w: World) { + return (await loadLog(storeApi(w), ROOT)) + .map(r => [r.trigger, r.outcome, r.ids]) +} + +test('LO1: a fresh ask that injects logs fresh and injected', async ( + $, on, +) => { + const { w } = await bootRecall($, on) + await start($) + await say($, GO) + expect(await askLog(w)).toEqual([['fresh', 'injected', ['BLK-001']]]) +}) + +test('LO2: idle and keyword triggers are told apart', async ($, on) => { + const { w } = await bootRecall($, on) + await start($) + await say($, GO) + await w.clock.advance(1860000) + await say($, NOTES) + await say($, DESIGN) + expect((await askLog(w)).map(r => r[0])) + .toEqual(['fresh', 'idle', 'keyword']) +}) + +test('LO3: an answer of none logs an empty ask', async ($, on) => { + const { w, seen } = await bootRecall($, on) + w.model = { text: 'none' } + await start($) + await say($, GO) + expect(seen).toEqual([undefined]) + expect(await askLog(w)).toEqual([['fresh', 'none', []]]) +}) + +test('LO4: no candidate left logs none without asking', async ($, on) => { + const { w } = await bootRecall($, on) + w.proc = { stdout: rowsOut([['BLK-001', 'x'], ['LRN-002', 'y']]) + .replace(/open/g, 'superseded') } + await start($) + await say($, GO) + expect(w.asks).toEqual([]) + expect(await askLog(w)).toEqual([['fresh', 'none', []]]) +}) + +test('LO5: an unanswered call and a throw log timeout', async ($, on) => { + const { w } = await bootRecall($, on) + await start($) + for (const m of ['unanswered', 'throw'] as Model[]) { + w.model = m + await say($, DESIGN) + } + expect(await askLog(w)).toEqual([ + ['fresh', 'timeout', []], ['keyword', 'timeout', []], + ]) +}) + +test('LO6: an ask during the pause logs paused', async ($, on) => { + const { w } = await bootRecall($, on) + w.model = 'unanswered' + await start($) + for (let i = 0; i < 4; i++) await say($, DESIGN) + expect((await askLog(w)).map(r => r[1])) + .toEqual(['timeout', 'timeout', 'timeout', 'paused']) + expect(w.asks).toHaveLength(3) +}) + +test('LO7: a pick the ledger refuses logs refused', async ($, on) => { + const { w } = await bootRecall($, on) + await start($) + await Promise.all([say($, GO), say($, DESIGN)]) + expect((await askLog(w)).map(r => r[1]).sort()) + .toEqual(['injected', 'refused']) +}) + test('IR1: the first prompt of a context asks and injects the block', async ($, on) => { const { w, seen } = await bootRecall($, on) @@ -2412,7 +2539,7 @@ test('IR11: an injection leaves one log record; 205 keep 200', async ( await say($, GO) expect(await loadLog(storeApi(w), ROOT)).toEqual([ { at: 1000, session: 's1', agent: 'main', channel: 'prompt', - ids: ['BLK-001'] }, + ids: ['BLK-001'], trigger: 'fresh', outcome: 'injected' }, ]) for (let i = 0; i < 204; i++) { await start($, 'clear') @@ -2495,11 +2622,12 @@ test('TIMErules: both rules on 64 KiB of letters, under 50 ms', () => { }) test('isTrigger: rules, fresh, idle, slash and length', () => { + const SUITE = 'on va concevoir la suite du mod memory' const long = 'please review this module and the new tests' expect(isTrigger(long, false, 0)).toBe(true) - expect(isTrigger('on va concevoir la suite', false, 0)).toBe(false) - expect(isTrigger('on va concevoir la suite', true, 0)).toBe(true) - expect(isTrigger('on va concevoir la suite', false, IDLE_MS)).toBe(true) + expect(isTrigger(SUITE, false, 0)).toBe(false) + expect(isTrigger(SUITE, true, 0)).toBe(true) + expect(isTrigger(SUITE, false, IDLE_MS)).toBe(true) expect(isTrigger('/feat design the thing', true, IDLE_MS)).toBe(false) expect(isTrigger('design note', true, 0)).toBe(false) expect(isTrigger('un-design-ed thing here', false, 0)).toBe(false) @@ -2508,6 +2636,14 @@ test('isTrigger: rules, fresh, idle, slash and length', () => { test('isTrigger: fewer than five content words never triggers', () => { expect(MIN_CONTENT_WORDS).toBe(5) + // 2-letter function words (finding I1) are no content + for (const vague of ['ok tu peux continuer la suite stp', + 'ok je valide, on passe à la suite', 'is it ok to do it now']) { + expect(isTrigger(vague, true, 0)).toBe(false) + expect(isTrigger(vague, false, IDLE_MS)).toBe(false) + } + const topical = 'why does the recall rerank pick stale memory entries' + expect(isTrigger(topical, false, 0)).toBe(true) expect(isTrigger('oui ça me convient', true, 0)).toBe(false) expect(isTrigger('non pas de changement go', false, IDLE_MS)).toBe(false) expect(isTrigger('i approve all for all', false, IDLE_MS)).toBe(false) @@ -2733,7 +2869,7 @@ test('TE6b: an unavailable status reader injects nothing', async ( expect(out).toEqual(w.answer) }) -test('TE7: at 1448 chars spent, a 200-char line is refused', async ( +test('TE7c: at 1448 chars spent, a 200-char line is refused', async ( $, on, ) => { // four lines of 362 chars (57 title + 280 lesson) = 1448 spent diff --git a/mods/memory/hooks/register.ts b/mods/memory/hooks/register.ts index 1ac74c8..5bcc2be 100644 --- a/mods/memory/hooks/register.ts +++ b/mods/memory/hooks/register.ts @@ -401,6 +401,40 @@ async function sweepStore($: Api, curKey: string, id: string): Promise<void> { } } +// The engine rejects every `$.store.set` once the store passes 4 MiB in all. +// The `p:` keys are swept at STORE_CAP; the `l:` keys are swept here, oldest +// first, so the two together stay under the engine cap and capture lives. +const ENGINE_CAP = 4194304 +const ENGINE_MARGIN = 131072 // room for the next session and log write + +type Weighed = { key: string; size: number; at: number } + +/** A store key's bytes and, for a log, the `at` of its newest record. */ +async function weigh($: Api, key: string): Promise<Weighed> { + const raw = await $.store.get(key) + const size = JSON.stringify(raw ?? null).length + const times = Array.isArray(raw) ? raw.filter(isLogRecord).map(r => r.at) : [] + return { key, size, at: Math.max(0, ...times) } +} + +/** + * Deletes the oldest `l:` keys, by their newest record, while the `p:` + * and `l:` keys together pass the engine cap. Never the `keep` key. + */ +async function sweepLogs($: Api, keep: string): Promise<void> { + const ours = (await $.store.keys()) + .filter(k => k.startsWith(STORE_PREFIX) || k.startsWith(LOG_PREFIX)) + const all = await Promise.all(ours.map(k => weigh($, k))) + let total = all.reduce((n, w) => n + w.size, 0) + const logs = all.filter(w => w.key.startsWith(LOG_PREFIX) && w.key !== keep) + .sort((a, b) => a.at - b.at) + for (const w of logs) { + if (total <= ENGINE_CAP - ENGINE_MARGIN) break + await $.store.delete(w.key) + total -= w.size + } +} + // The registry error index: which captured failures a registry knows. const MAX_REGISTRY = 4194304 const MIN_SPAN = 12 @@ -639,11 +673,16 @@ async function statusMap($: Api, root: string): Promise<StatusMap | undefined> { } } +// Function words, 3+ letters first, then the 2-letter FR and EN ones: TOKEN +// takes 2+ letters, so without them "ok tu peux continuer la suite stp" +// counts 7 content words and passes the floor. At most 120 words. const STOP_WORDS = new Set( ('the and for with that this from are was were not but you your have has ' + 'had will can all any its into than then them they their there what ' + 'when which who how why les des une pour dans avec est pas que qui sur ' + - 'par aux ces ses son mais ont sont plus comme').split(' '), + 'par aux ces ses son mais ont sont plus comme ' + + 'ok tu je il on la le de du et en un au ce se sa ne ni ou si ' + + 'is it to do of in at an be by or as if so we me my no go up').split(' '), ) const TOKEN = /[\p{L}\p{N}]{2,40}/gu const MAX_QUERY = 2000 @@ -913,16 +952,26 @@ function queueWrite(st: State, job: () => Promise<void>): Promise<void> { return run } +export type Trigger = 'fresh' | 'idle' | 'keyword' | 'tool' +export type Outcome = 'injected' | 'none' | 'timeout' | 'refused' | 'paused' + +const TRIGGERS: string[] = ['fresh', 'idle', 'keyword', 'tool'] +const OUTCOMES: string[] = ['injected', 'none', 'timeout', 'refused', 'paused'] + +// `trigger` and `outcome` are absent on records written before 4c's review. export type LogRecord = { at: number session: string agent: string channel: 'prompt' | 'tool' ids: string[] + trigger?: Trigger + outcome?: Outcome } -// shortcut: one `l:<root>` key per project, so no cap across roots; upgrade -// path: one global log key, or a sweep of the `l:` keys by age. +// shortcut: one `l:<root>` key per project (about 28 KiB at 200 records), +// swept by `sweepLogs` against the engine's 4 MiB store cap, oldest key +// first; upgrade path: one global log key, or a smaller per-root cap. const LOG_PREFIX = 'l:' const MAX_LOG = 200 const MAX_LOG_BYTES = 65536 @@ -933,7 +982,9 @@ function isLogRecord(v: unknown): v is LogRecord { typeof r.at === 'number' && typeof r.session === 'string' && typeof r.agent === 'string' && (r.channel === 'prompt' || r.channel === 'tool') && - Array.isArray(r.ids) && r.ids.every(i => typeof i === 'string') + Array.isArray(r.ids) && r.ids.every(i => typeof i === 'string') && + (r.trigger === undefined || TRIGGERS.includes(r.trigger)) && + (r.outcome === undefined || OUTCOMES.includes(r.outcome)) } const logKey = (root: string) => LOG_PREFIX + root.slice(0, MAX_ROOT) @@ -962,6 +1013,7 @@ export function appendLog( ): Promise<void> { return queueWrite(st, async () => { const log = await loadLog($, root) + if (log.length === 0) await sweepLogs($, logKey(root)) await $.store.set(logKey(root), fitLog([...log, record])) }) } @@ -979,7 +1031,10 @@ async function mutateSession( const created = !p.sessions.some(s => s.id === at.id) change(sessionOf(p, at.id, now)) await saveProject($, at.root, p) - if (created) await sweepStore($, storeKey(at.root), at.id) + if (created) { + await sweepStore($, storeKey(at.root), at.id) + await sweepLogs($, logKey(at.root)) + } } const recordFailure = ($: Api, at: Where, f: Failure) => @@ -1447,6 +1502,7 @@ async function knownLine( const record = { at: now, session: at.id, ids: [entry.id] } await appendLog($, st, at.root, { ...record, agent: agent ?? 'main', channel: 'tool', + trigger: 'tool', outcome: 'injected', }).catch(() => undefined) return line } @@ -1537,21 +1593,28 @@ const MAX_CANDS = 30 const RERANK_FAILS = 3 // failed reranks in a row that pause it const RERANK_PAUSE_MS = 900000 -/** True when a prompt may ask for recall: fresh context, idle, or a rule. */ -export function isTrigger( +/** What made a prompt ask for recall: a fresh context, idle, or a rule. */ +export function triggerKind( text: string, fresh: boolean, idleMs: number, -): boolean { +): Exclude<Trigger, 'tool'> | undefined { if (text.startsWith('/') || Array.from(text).length < MIN_PROMPT) { - return false + return undefined } - if (tokensOf(text).length < MIN_CONTENT_WORDS) return false + if (tokensOf(text).length < MIN_CONTENT_WORDS) return undefined + if (fresh) return 'fresh' + if (idleMs >= IDLE_MS) return 'idle' const asked = cap(text, MAX_REGEX_INPUT) - return fresh || idleMs >= IDLE_MS || - DESIGN_RULE.test(asked) || ANALYSIS_RULE.test(asked) + return DESIGN_RULE.test(asked) || ANALYSIS_RULE.test(asked) + ? 'keyword' + : undefined } +/** True when a prompt may ask for recall. */ +export const isTrigger = (text: string, fresh: boolean, idleMs: number) => + triggerKind(text, fresh, idleMs) !== undefined + /** Counts a rerank: the third failure in a row pauses it for 15 min. */ function countRerank(st: State, ok: boolean, now: number): void { if (ok) { @@ -1563,15 +1626,14 @@ function countRerank(st: State, ok: boolean, now: number): void { st.rerank = { fails: 0, until: now + RERANK_PAUSE_MS } } -/** The haiku answer, or undefined: failed, unanswered, late or paused. */ +/** The haiku answer, or undefined: failed, unanswered or late. */ async function askRerank( $: Api, st: State, text: string, cands: Entry[], + now: number, ): Promise<string | undefined> { - const now = await $.clock.now() - if (now < st.rerank.until) return undefined const ask = { model: HAIKU, prompt: rerankPrompt(text, cands), @@ -1601,38 +1663,70 @@ function candidatesFor( return bm25Rank(open, text, MAX_CANDS) } +type Ask = { at: Where; text: string; trigger: Exclude<Trigger, 'tool'> } +type Picked = { block: string; ids: string[]; outcome: Outcome } + +const nothing = (outcome: Outcome): Picked => ({ block: '', ids: [], outcome }) + +/** The candidates a model answer names, in the answer's order. */ +function picksOf(answer: string, cands: Entry[]): Entry[] { + const byId = new Map(cands.map(c => [c.id, c])) + return parseIds(answer, cands, MAX_PICKS).flatMap(id => byId.get(id) ?? []) +} + +/** Claims the picks one by one; the header is charged to the first taken. */ +function claimPicks(st: State, key: string, picked: Entry[]): string[] { + const taken: string[] = [] + for (const e of picked) { + const header = taken.length === 0 ? RECALL_HEADER.length : 0 + taken.push(...claim(st, key, [e.id], [recallLine(e).length + 1 + header])) + } + return taken +} + +/** Asks haiku among the candidates and claims its picks. */ +async function pickRecall( + $: Api, + st: State, + key: string, + text: string, + cands: Entry[], +): Promise<Picked> { + const now = await $.clock.now() + if (now < st.rerank.until) return nothing('paused') + const answer = await askRerank($, st, text, cands, now) + if (answer === undefined) return nothing('timeout') + const picked = picksOf(answer, cands) + if (picked.length === 0) return nothing('none') + const taken = claimPicks(st, key, picked) + const block = recallBlock( + picked.filter(e => taken.includes(e.id)).map(recallLine), RECALL_CAP) + if (block === '') return nothing('refused') + return { block, ids: taken, outcome: 'injected' } +} + /** * The recall block for a prompt: BM25 candidates, haiku picks, the ledger - * claim, the log. '' when nothing is to be injected. + * claim. Every ask is logged with its outcome; '' when nothing is injected. */ async function recallFor( $: Api, st: State, - at: Where, - text: string, + ask: Ask, rx: Registries, ): Promise<string> { - const key = contextKey(at.id, undefined) - const cands = candidatesFor(st, key, rx, text) - if (cands.length === 0) return '' - const answer = await askRerank($, st, text, cands) - const byId = new Map(cands.map(c => [c.id, c])) - const picked = parseIds(answer ?? '', cands, MAX_PICKS) - .flatMap(id => byId.get(id) ?? []) - const when = await $.clock.now() - const taken: string[] = [] - for (const e of picked) { - // the header is charged to the first line actually taken - const header = taken.length === 0 ? RECALL_HEADER.length : 0 - taken.push(...claim(st, key, [e.id], [recallLine(e).length + 1 + header])) + const key = contextKey(ask.at.id, undefined) + const cands = candidatesFor(st, key, rx, ask.text) + const got = cands.length === 0 + ? nothing('none') + : await pickRecall($, st, key, ask.text, cands) + const record = { + at: await $.clock.now(), session: ask.at.id, agent: 'main', + ids: got.ids, trigger: ask.trigger, outcome: got.outcome, } - const block = recallBlock( - picked.filter(e => taken.includes(e.id)).map(recallLine), RECALL_CAP) - if (block === '') return '' - const record = { at: when, session: at.id, agent: 'main', ids: taken } - await appendLog($, st, at.root, { ...record, channel: 'prompt' }) + await appendLog($, st, ask.at.root, { ...record, channel: 'prompt' }) .catch(() => undefined) - return block + return got.block } const ALL_FILES = ['decisions.md', ...FAILURE_FILES] @@ -1643,7 +1737,7 @@ async function additions( st: State, at: Where, text: string, - wantRecall: boolean, + trigger: Ask['trigger'] | undefined, ): Promise<string[]> { const rx = await loadRegistries($, at.root, ALL_FILES) // separate failures: a throw in one never drops the other @@ -1653,8 +1747,8 @@ async function additions( return '' }) : '' - const block = wantRecall - ? await recallFor($, st, at, text, rx).catch(() => '') + const block = trigger !== undefined + ? await recallFor($, st, { at, text, trigger }, rx).catch(() => '') : '' return [note, block].filter(part => part !== '') } @@ -1683,11 +1777,12 @@ export async function promptContext( const idle = last === undefined ? 0 : now - last // unknown: not idle st.lastPrompt.set(at.id, now) st.spent.delete(contextKey(at.id, undefined)) - const wantRecall = (await ensureRecall($, st)) && - isTrigger(e.text, st.fresh.has(at.id), idle) - if (wantRecall) st.fresh.delete(at.id) - if (!wantRecall && st.pending.length === 0) return [] - return additions($, st, at, e.text, wantRecall) + const trigger = (await ensureRecall($, st)) + ? triggerKind(e.text, st.fresh.has(at.id), idle) + : undefined + if (trigger !== undefined) st.fresh.delete(at.id) + if (trigger === undefined && st.pending.length === 0) return [] + return additions($, st, at, e.text, trigger) } function registerPrompt(on: On, st: State): void { From cea9f6a7b977afe7b12fddf117c7ce3653ab8106 Mon Sep 17 00:00:00 2001 From: bchanot <chanot.bastien@gmail.com> Date: Thu, 5 Nov 2026 18:21:46 +0100 Subject: [PATCH 28/41] docs: memory recall facts after the final review --- .claude/tasks/TODO.md | 2 +- README.md | 6 +++--- USAGE.md | 6 +++--- 3 files changed, 7 insertions(+), 7 deletions(-) diff --git a/.claude/tasks/TODO.md b/.claude/tasks/TODO.md index b99fe67..307bf77 100644 --- a/.claude/tasks/TODO.md +++ b/.claude/tasks/TODO.md @@ -118,7 +118,7 @@ Shared rules for every phase: - **4c read side (built 2026-11-05 on feature/memory-recall, merge pending).** 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` (native matchers; the mod's `session.compact` only skips); 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 scope=global index, `memory_search` tool. - 4c follow-up from the 4b live proof (2026-11-04): `memory_pending` lists milestones of the current session only, so a `/capitalize` run right after `/clear` misses the previous session's `fix:`/finish milestones (they stay in the store). Option: list earlier-session milestones marked `(earlier session)`. Doctrine (capitalize before /clear) covers the normal path. - **4d feedback and promotion.** The injection log now exists (4c, store key `l:<root>`); 4d waits on its data. DEFERRED until a plain injection log (ID, trigger kind, turn, cited or not) shows misses or noise; then /prune-memory reads it and promotion to a mechanism follows BDR-100. - - [ ] shortcut: the injection log lives under `l:<root>` store keys with no cross-root cap (each key holds 200 records and 64 KiB); upgrade = a global cap or sweep of stale roots when the store nears its 1 MiB cap (`mods/memory/hooks/register.ts`). + - [ ] shortcut: the injection log lives under `l:<root>` store keys (about 28 KiB each, 200 records and 64 KiB at most); `sweepLogs` counts them with the `p:` keys and evicts the oldest log key (by its newest record, never the current root's) once the total nears the engine's 4 MiB store cap; upgrade = one global log key or a smaller per-root cap (`mods/memory/hooks/register.ts`). - [ ] residual: the pre-existing `memory.sh check` call in `hooks/session-start.sh` is not time-bounded (the digest's `memory.sh index blocker` call is); upgrade = wrap it in `timeout 2`. - Proof: recall precision on ≥20 real prompts and ≥10 real errors, target ≥ the 14/22 baseline; digest after a real compaction; redaction test on the ledger; `/context` delta; captured-failure demo: an error from session N recalled in session N+1. diff --git a/README.md b/README.md index 53233b0..753c3f8 100644 --- a/README.md +++ b/README.md @@ -159,13 +159,13 @@ Limits: a main-loop switch re-reads cold the part of the context the target mode - Records: a Bash result whose text starts `Exit code N` and whose last line (the first line and the rtk trailer dropped) is an error line. That line must hold a letter and an error-shaped word, else the failure is dropped (no earlier line is tried): a word such as error, fatal, cannot, No such, denied, failed, unexpected, traceback, or a shellcheck code (SC1234); otherwise nothing is stored. The entry is stored redacted: `KEY=value` secrets, Stripe, AWS, GitHub, Slack, SendGrid and Supabase keys, private key blocks, JWTs, Bearer and `Authorization: Basic|token` values, `user:pass@` URLs, `-u`/`--user user:pass` and `--password`; also the Anthropic, OpenAI, GitLab, Google and npm key prefixes and `github_pat_`, `--token`/`--api-key`/`--secret` flags, API-key headers (`X-Api-Key`, `api-key`, `apikey`, any name ending in `api-key` or `api_key`), `PRIVATE-TOKEN`, `Cookie` and `Set-Cookie` headers (to the end of the line), `--cookie` values and `curl -b` cookies, JSON and `key: value` password/token/secret/api-key pairs whose key may carry a prefix or suffix (`access_token`, `db_password`), and a 40-hex token as URL user. Residual: `user:p@ss@host` becomes `<redacted>@ss@host`, so the password's tail after its own `@` stays. Permission refusals, guard redirects and tool_use errors are never captured. A sub-agent failure is marked `(sub-agent)`. - Milestones: a successful `feat` or `fix` commit (plain `-m` or heredoc form), a `gitflow.sh finish` (not `finish chore`), a `make test ...` command red then green. Milestones are recorded on the main loop only: sub-agent commits and finishes are ignored. -- Store: the plugin's `$.store`, keyed by project root: the 3 most recent sessions per project, 50 failures per session, 2 KiB per entry, 1 MiB for the whole store. It survives `/clear`. The store is the plugin's JSON file under the Claude configuration directory (observed here as `~/.claude/plugins/store/memory_skills-dir-<hash>.json`, an engine layout, not fixed by this repo); delete it to wipe the captures. +- Store: the plugin's `$.store`, keyed by project root: the 3 most recent sessions per project, 50 failures per session, 2 KiB per entry. Session keys (`p:<root>`) are swept at 1 MiB; log keys (`l:<root>`) hold about 28 KiB per project; both sit under the engine's 4 MiB cap for the whole store, and when the total nears it the oldest log key is evicted first (never the current project's). It survives `/clear`. The store is the plugin's JSON file under the Claude configuration directory (observed here as `~/.claude/plugins/store/memory_skills-dir-<hash>.json`, an engine layout, not fixed by this repo); delete it to wipe the captures. - Note: one context line, `memory: <kind> <label> — <n> new failure mode(s) this session; /capitalize when ready.`, at the first composer prompt after a milestone. Never per turn, never at Stop, never in a sub-agent. -- Tool: `mcp__memory__memory_pending` (deferred: a skill loads it once with `ToolSearch("select:mcp__memory__memory_pending")`). `/capitalize`, `/close` and the CAPITALIZE steps of `/feat`, `/bugfix`, `/hotfix`, `/ship-feature` and `/commit-change` call it first. It lists this session's milestones, then the failures as `NEW` or `known <ID>` (word 4-grams matched against the backticked spans of BLK and LRN entries, superseded ones excluded through `lib/memory.sh index`; when that reader is unavailable every entry is matched and the `index:` line ends `status reader unavailable`), earlier sessions marked. Every text it returns is data. It never writes a registry and never calls `lib/memory.sh`. +- Tool: `mcp__memory__memory_pending` (deferred: a skill loads it once with `ToolSearch("select:mcp__memory__memory_pending")`). `/capitalize`, `/close` and the CAPITALIZE steps of `/feat`, `/bugfix`, `/hotfix`, `/ship-feature` and `/commit-change` call it first. It lists the milestones of this session and of the earlier ones kept in the store, then the failures as `NEW` or `known <ID>` (word 4-grams matched against the backticked spans of BLK and LRN entries, superseded ones excluded through `lib/memory.sh index`; when that reader is unavailable every entry is matched and the `index:` line ends `status reader unavailable`), earlier sessions marked. Every text it returns is data. It never writes a registry; every call reads the statuses through `lib/memory.sh index`. - Recall: the mod hands registry entries back at the moment they matter. A prompt typed in the composer (never a slash command, at least 5 content words, stop words excluded) triggers it when it is the first of a context (start, `/clear`, `/compact`), comes after 30 minutes idle, or holds a design or analysis word (plan, architecture, design, why, explain, analyse, review, audit and their French forms). BM25 ranks the live BDR, LRN and BLK entries, one haiku call keeps at most 3, bounded to 5 seconds. The context block `memory recall:` carries one line per entry (ID, title, lesson), at most 1500 characters per turn, each entry once per context. Any failure or timeout injects nothing. - Known error: a Bash failure whose key matches a live BLK or LRN entry attaches `memory: known <ID> <title> — <lesson>` to the tool answer, once per ID per context, from the same 1500-character budget. Sub-agents get this channel only. - Digest: `hooks/session-start.sh` prints `memory digest:` on `startup`, `clear` and `compact` (never `resume`) in a project that has `.claude/memory/`: up to 3 open BLK from `memory.sh index blocker` (the rest counted, upstream ones counted), up to 3 unchecked Actionable TODO items, the last journal line, 800 characters at most. When the cap bites, TODO lines drop first, then nothing else. Without `timeout` and `jq` it prints only from a terminal. -- Recall switch: `{"enabled": true, "recall": false}` in `~/.claude/memory.json` cuts the injections (recall and known-error line) and keeps capture. Each injection is logged under the `l:<root>` store key (last 200 records, 64 KiB), never shown; phase 4d reads it. +- Recall switch: `{"enabled": true, "recall": false}` in `~/.claude/memory.json` cuts the injections (recall and known-error line) and keeps capture. Every ask is logged under the `l:<root>` store key (last 200 records, 64 KiB), never shown: when, session, agent, channel, the IDs injected, the `trigger` (`fresh`, `idle`, `keyword`, `tool`) and the `outcome` (`injected`, `none`, `timeout`, `refused`, `paused`; an ask that injects nothing is logged with no IDs); phase 4d reads it. - Recall residuals: measured on 14 days of this repo's transcripts, precision is 54 to 61 % against a 64 % bar, so recall ships on and switchable, and the log decides. The router's classifier label is not used. EVAL entries are not recalled. Each failing command that matches an entry spawns one `memory.sh index`. The haiku bound drops the recalls that answer slower than 5 seconds. - Off switch: `{"enabled": false}` in `~/.claude/memory.json`, read at the first event of a session, so it applies at the next session or after `/reload-plugins`. Off, the tool answers `memory capture is off (~/.claude/memory.json)`. A switch file that cannot be read, or whose `enabled` is not a boolean, keeps capture on and logs one line. - Residuals: cross-process writes are unverified (two concurrent sessions: last writer wins). Non-Bash failures are not captured. `-b` counts as curl's cookie flag only when `curl` opens its command segment, after optional env assignments, `sudo`, `rtk` or `$(`: `time curl -b …` keeps its cookies. 40-hex Gitea tokens are kept by design: they look like commit SHAs. A session root that moves with `/cd` or a worktree move hides earlier captures of the same repo from /capitalize. A bare `gitflow.sh finish` on a chore branch counts as a milestone. Measured at 83 % noise before the error-shaped filter over 14 days of this repo's transcripts; the filter keeps every useful sample and cuts captures by two thirds (`.claude/tasks/plans/2026-11-03-memory-capture-spike/NOISE.md`). diff --git a/USAGE.md b/USAGE.md index f9d2a10..b8bb88e 100644 --- a/USAGE.md +++ b/USAGE.md @@ -208,13 +208,13 @@ Le mod `mods/memory/` note les échecs Bash et les jalons de la session pour que - Ce qu'il enregistre : un résultat Bash dont le texte commence par `Exit code N` et dont la dernière ligne (première ligne et trailer rtk écartés) est une ligne d'erreur. La dernière ligne doit contenir une lettre et un mot d'erreur (error, fatal, cannot, No such, denied, failed, unexpected, traceback, ou un code shellcheck SC1234), sinon l'échec est abandonné. Elle est stockée expurgée : `NOM=valeur` (TOKEN, API_KEY, SECRET, PASSWORD, PASSWD, chiffres admis), clés Stripe/AWS/GitHub/Slack/SendGrid/Supabase, bloc de clé privée, JWT, `Bearer`, `user:pass@` dans une URL, `-u`/`--user user:pass`, `--password`, `Authorization: Basic|Bearer|token`, préfixes Anthropic/OpenAI/GitLab/Google/npm et `github_pat_`, drapeaux `--token`/`--api-key`/`--secret`, en-têtes de clé d'API (`X-Api-Key`, `api-key`, `apikey`, tout nom finissant par `api-key` ou `api_key`), en-têtes `PRIVATE-TOKEN`, `Cookie` et `Set-Cookie` (jusqu'à la fin de la ligne), valeurs de `--cookie` et cookies passés à `curl -b`, paires JSON ou `clé: valeur` password/token/secret/api-key dont la clé peut porter un préfixe ou un suffixe (`access_token`, `db_password`), jeton de 40 hexadécimaux comme utilisateur d'URL. Résiduel : `user:p@ss@host` devient `<redacted>@ss@host`, donc la fin du mot de passe après son propre `@` reste. Refus de permission, redirections de garde et erreurs de tool_use ne sont jamais captés. Un échec de sous-agent est marqué `(sub-agent)`. - Jalons : un commit `feat` ou `fix` réussi (`-m` simple ou heredoc), un `gitflow.sh finish` (pas `finish chore`), une commande `make test ...` rouge puis verte. Les jalons ne sont notés que sur la boucle principale : commits et finish de sous-agents ignorés. -- Stockage : le `$.store` du plugin, par racine de projet : 3 sessions les plus récentes par projet, 50 échecs par session, 2 Kio par entrée, 1 Mio pour tout le store. Il survit à `/clear`. Le store est le fichier JSON du plugin sous le dossier de configuration de Claude (observé ici en `~/.claude/plugins/store/memory_skills-dir-<hash>.json`, disposition du moteur, non fixée par ce dépôt) ; le supprimer efface les captures. +- Stockage : le `$.store` du plugin, par racine de projet : 3 sessions les plus récentes par projet, 50 échecs par session, 2 Kio par entrée. Les clés de session (`p:<racine>`) sont purgées à 1 Mio ; les clés de journal (`l:<racine>`) pèsent environ 28 Kio par projet ; les deux restent sous le plafond de 4 Mio du moteur pour tout le store, et quand le total s'en approche la plus ancienne clé de journal part d'abord (jamais celle du projet courant). Il survit à `/clear`. Le store est le fichier JSON du plugin sous le dossier de configuration de Claude (observé ici en `~/.claude/plugins/store/memory_skills-dir-<hash>.json`, disposition du moteur, non fixée par ce dépôt) ; le supprimer efface les captures. - La note : une ligne de contexte, `memory: <kind> <label> — <n> new failure mode(s) this session; /capitalize when ready.`, au premier prompt tapé après un jalon. Jamais à chaque tour, jamais au Stop, jamais dans un sous-agent. -- L'outil : `mcp__memory__memory_pending` (différé : un skill le charge une fois avec `ToolSearch("select:mcp__memory__memory_pending")`). `/capitalize`, `/close` et les étapes CAPITALIZE de `/feat`, `/bugfix`, `/hotfix`, `/ship-feature` et `/commit-change` l'appellent en premier. Il liste les jalons de la session, puis les échecs `NEW` ou `known <ID>` (4-grammes de mots comparés aux passages entre accents graves des entrées BLK et LRN, les remplacées exclues via `lib/memory.sh index` ; si ce lecteur est indisponible, toutes les entrées sont comparées et la ligne `index:` finit par `status reader unavailable`), les sessions précédentes signalées. Chaque texte est une donnée. Il n'écrit aucun registre et n'appelle pas `lib/memory.sh`. +- L'outil : `mcp__memory__memory_pending` (différé : un skill le charge une fois avec `ToolSearch("select:mcp__memory__memory_pending")`). `/capitalize`, `/close` et les étapes CAPITALIZE de `/feat`, `/bugfix`, `/hotfix`, `/ship-feature` et `/commit-change` l'appellent en premier. Il liste les jalons de la session et ceux des sessions précédentes gardés dans le store, puis les échecs `NEW` ou `known <ID>` (4-grammes de mots comparés aux passages entre accents graves des entrées BLK et LRN, les remplacées exclues via `lib/memory.sh index` ; si ce lecteur est indisponible, toutes les entrées sont comparées et la ligne `index:` finit par `status reader unavailable`), les sessions précédentes signalées. Chaque texte est une donnée. Il n'écrit aucun registre ; chaque appel lit les statuts via `lib/memory.sh index`. - Rappel : le mod ramène les entrées des registres au bon moment. Un prompt tapé dans le composer (jamais une commande slash, au moins 5 mots de contenu, mots vides exclus) le déclenche s'il est le premier d'un contexte (démarrage, `/clear`, `/compact`), s'il suit 30 minutes d'inactivité, ou s'il contient un mot de conception ou d'analyse (plan, architecture, design, pourquoi, explique, analyse, review, audit et leurs équivalents anglais). BM25 classe les entrées BDR, LRN et BLK vivantes, un appel haiku en garde 3 au plus, borné à 5 secondes. Le bloc de contexte `memory recall:` porte une ligne par entrée (ID, titre, leçon), 1500 caractères par tour au plus, chaque entrée une fois par contexte. Un échec ou un dépassement n'injecte rien. - Erreur connue : un échec Bash dont la clé correspond à une entrée BLK ou LRN vivante ajoute `memory: known <ID> <titre> — <leçon>` à la réponse de l'outil, une fois par ID et par contexte, sur le même budget de 1500 caractères. Les sous-agents n'ont que ce canal. - Digest : `hooks/session-start.sh` affiche `memory digest:` sur `startup`, `clear` et `compact` (jamais `resume`) dans un projet qui a `.claude/memory/` : jusqu'à 3 BLK ouverts issus de `memory.sh index blocker` (le reste compté, les « upstream » comptés), jusqu'à 3 items Actionable non cochés du TODO, la dernière ligne du journal, 800 caractères au plus. Quand le plafond mord, les lignes TODO tombent d'abord, rien d'autre. Sans `timeout` ni `jq`, il ne s'affiche que depuis un terminal. -- Interrupteur du rappel : `{"enabled": true, "recall": false}` dans `~/.claude/memory.json` coupe les injections (rappel et ligne d'erreur connue) et garde la capture. Chaque injection est journalisée sous la clé de store `l:<racine>` (200 enregistrements, 64 Kio), jamais affichée ; la phase 4d la lit. +- Interrupteur du rappel : `{"enabled": true, "recall": false}` dans `~/.claude/memory.json` coupe les injections (rappel et ligne d'erreur connue) et garde la capture. Chaque demande est journalisée sous la clé de store `l:<racine>` (200 enregistrements, 64 Kio), jamais affichée : date, session, agent, canal, IDs injectés, `trigger` (`fresh`, `idle`, `keyword`, `tool`) et `outcome` (`injected`, `none`, `timeout`, `refused`, `paused` ; une demande qui n'injecte rien est journalisée sans ID) ; la phase 4d la lit. - Limites du rappel : mesurée sur 14 jours de transcripts de ce dépôt, la précision est de 54 à 61 % pour une barre à 64 %, donc le rappel est livré actif et coupable, et le journal tranchera. L'étiquette du classifieur du routeur n'est pas utilisée. Les entrées EVAL ne sont pas rappelées. Chaque commande en échec qui correspond à une entrée lance un `memory.sh index`. La borne haiku écarte les rappels qui répondent après 5 secondes. - Interrupteur : `{"enabled": false}` dans `~/.claude/memory.json`, lu au premier événement d'une session : effet à la session suivante ou après `/reload-plugins`. Coupé, l'outil répond `memory capture is off (~/.claude/memory.json)`. Un fichier illisible, ou dont `enabled` n'est pas un booléen, laisse la capture active et journalise une ligne. - Limites connues : les écritures entre processus ne sont pas vérifiées (deux sessions simultanées : la dernière écrit). Les échecs hors Bash ne sont pas captés. `-b` ne vaut drapeau de cookies de curl que si `curl` ouvre son segment de commande, après d'éventuelles affectations de variables, `sudo`, `rtk` ou `$(` : `time curl -b …` garde ses cookies. Un jeton de 40 hexadécimaux nu est gardé à dessein : il ressemble à un SHA de commit (expurgé seulement comme utilisateur d'URL). Une racine de session qui bouge avec `/cd` ou un changement de worktree cache à /capitalize les captures précédentes du même dépôt. Un `gitflow.sh finish` nu sur une branche chore compte comme un jalon. Bruit mesuré à 83 % avant le filtre de forme d'erreur sur 14 jours de transcripts de ce dépôt ; le filtre garde tous les échantillons utiles et réduit les captures des deux tiers (`.claude/tasks/plans/2026-11-03-memory-capture-spike/NOISE.md`). From a22052e31aaf9ca32241409c6b62b474e7e0c677 Mon Sep 17 00:00:00 2001 From: bchanot <chanot.bastien@gmail.com> Date: Thu, 5 Nov 2026 18:23:15 +0100 Subject: [PATCH 29/41] chore(bench): phase 4c re-measure after the final-review fixes --- .claude/tasks/plans/2026-11-04-memory-recall-spike/RECALL.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/.claude/tasks/plans/2026-11-04-memory-recall-spike/RECALL.md b/.claude/tasks/plans/2026-11-04-memory-recall-spike/RECALL.md index 325f675..6fb34c4 100644 --- a/.claude/tasks/plans/2026-11-04-memory-recall-spike/RECALL.md +++ b/.claude/tasks/plans/2026-11-04-memory-recall-spike/RECALL.md @@ -29,3 +29,7 @@ User: "Plancher de contenu" — no intent recall on a prompt with fewer than 5 c ## After the content floor (debdead) and the bound decision Same harness, same seed: 15 prompts meet the trigger (was 24), all sampled; 14 injections; n = 41 entries; relevant 25 / 41 = 61 % counting entries written after the prompt (temporal leakage, 6 entries), 19 / 35 = 54 % excluding them. Still under the 64 % bar; the misses are vague follow-ups, the hits are topical prompts. haiku `duration_api_ms` > 3000 over the three runs: 16 / 55 = 29 % (> 25 % bar); > 4500: 1 / 55; > 5000: 1 / 55. User decision: `RERANK_MS` = 5000. + +## After the final-review fixes (2397c36: 2-letter stop words, log trigger/outcome, log keys in the sweep) + +Same harness, same seed: still 15 prompts meet the trigger (the 2-letter stop words did not change this sample), 14 injections, n = 40 entries; relevant 30 / 40 = 75 % counting entries written after the prompt (8 such entries), 22 / 32 = 69 % excluding them; haiku > 3000 ms 1 / 15, > 5000 ms 1 / 15. Reading: the rerank is not deterministic (different picks run to run) and the labels are one labeller's on a small sample; across the four measured runs the relevant share ranged about 54-75 %. The injection log (now with `trigger` and `outcome`) is the real-use measure for 4d. From a2e22b4918b9603c518e8a7f003ae201ca12564d Mon Sep 17 00:00:00 2001 From: bchanot <chanot.bastien@gmail.com> Date: Thu, 5 Nov 2026 18:42:49 +0100 Subject: [PATCH 30/41] chore(contract): phase 4c interactive proof PASS --- .claude/tasks/contracts/2026-11-04-memory-recall-1859.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.claude/tasks/contracts/2026-11-04-memory-recall-1859.md b/.claude/tasks/contracts/2026-11-04-memory-recall-1859.md index adf1a0c..f0cf730 100644 --- a/.claude/tasks/contracts/2026-11-04-memory-recall-1859.md +++ b/.claude/tasks/contracts/2026-11-04-memory-recall-1859.md @@ -78,4 +78,4 @@ Final review gate `[gated 2026-11-05]` (final opus review "Approved with fixes"; ## 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`. +- Interactive (user, 2026-11-05 18:35-18:42, fresh session in this repo on feature/memory-recall): session 236ca087: `memory digest:` in the SessionStart context (line 9); the composer prompt "conçois un plan pour la phase 4d …" carries one `memory recall:` attachment (line 20, BDR-125). `/clear` → session 14360e08: `memory digest:` at its SessionStart (line 7); the prompt "explique pourquoi le digest …" carries one `memory recall:` (line 22, LRN-099: an off-topic pick, counted as a miss). `/compact` → compaction summary (line 114) then `memory digest:` on the following SessionStart (line 127). PASS: recall in a fresh context, recall again after /clear (classic.SessionStart clear observed through its effect), digest on startup, clear and compact. From c8afc03e8aa35fc12a96254e0948d05beeae884f Mon Sep 17 00:00:00 2001 From: bchanot <chanot.bastien@gmail.com> Date: Thu, 5 Nov 2026 18:49:26 +0100 Subject: [PATCH 31/41] chore(contract): phase 4c GATE 0 MET (GATES_TIMEOUT 540) --- .claude/tasks/contracts/2026-11-04-memory-recall-1859.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/.claude/tasks/contracts/2026-11-04-memory-recall-1859.md b/.claude/tasks/contracts/2026-11-04-memory-recall-1859.md index f0cf730..6bed0c9 100644 --- a/.claude/tasks/contracts/2026-11-04-memory-recall-1859.md +++ b/.claude/tasks/contracts/2026-11-04-memory-recall-1859.md @@ -55,19 +55,19 @@ Final review gate `[gated 2026-11-05]` (final opus review "Approved with fixes"; 9. `[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 + EVIDENCE: MET exit=0 marker-found :: MOD4C-OK 10. `[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 + EVIDENCE: MET exit=0 marker-found :: DIGEST-OK 11. `[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 + EVIDENCE: MET exit=0 marker-found :: RECALL-OK 12. `[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 + EVIDENCE: MET exit=0 marker-found :: BRANCH4C-OK ## 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) From a8847d75254f34c2068e8892cabad473db097374 Mon Sep 17 00:00:00 2001 From: bchanot <chanot.bastien@gmail.com> Date: Thu, 5 Nov 2026 19:07:55 +0100 Subject: [PATCH 32/41] chore(contract): phase 4c gates 1-2 decisions [gated], criterion 8 amended --- .claude/tasks/contracts/2026-11-04-memory-recall-1859.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.claude/tasks/contracts/2026-11-04-memory-recall-1859.md b/.claude/tasks/contracts/2026-11-04-memory-recall-1859.md index 6bed0c9..eb41772 100644 --- a/.claude/tasks/contracts/2026-11-04-memory-recall-1859.md +++ b/.claude/tasks/contracts/2026-11-04-memory-recall-1859.md @@ -52,6 +52,8 @@ Rerank bound gate `[gated 2026-11-05]` (three harness runs: 16/55 haiku calls ov 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`). +Gates 1-2 decisions `[gated 2026-11-05]` (verifier ECARTS(2) on criteria 7 and 8; security PASS with 2 MEDIUM; user: recommended options): (a) criterion 7 — `{"enabled": false}` in `~/.claude/memory.json` also silences the session-start digest (absent or unreadable file = on; `"recall": false` does not touch the digest); (b) criterion 8 AMENDED — the precision proof is: the whole qualifying population of 14 days (15 prompts after the content floor), several harness runs with the run-to-run range reported (54-75 %, RECALL.md), the error channel reported as an insufficient sample (n = 3), the digest after a real compaction, the noise measured before shipping, and the user's decision "recall ships on and switchable; 4d measures on the injection log" (the ≥ 20 prompts / ≥ 64 % / ≥ 10 errors bar of the seed is not reachable on 14 days of data and is replaced by this, not dropped silently); (c) a repository marked foreign (`git config gitflow.protect false`) gets no recall, no known line and no digest; (d) the store fix: the sweep runs BEFORE the save that could pass the engine cap, and a rejected `set` triggers one sweep-and-retry; a mock store enforcing the cap tests it; (e) the harness passes `--no-session-persistence` to `claude -p`. + 9. `[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 From fb2a4ff5ba7eac348c99789721e2f50a7d39e536 Mon Sep 17 00:00:00 2001 From: bchanot <chanot.bastien@gmail.com> Date: Thu, 5 Nov 2026 19:14:26 +0100 Subject: [PATCH 33/41] fix(memory): sweep before save, retry on a rejected set, foreign repos get no recall --- mods/memory/hooks/register.test.ts | 126 +++++++++++++++++++++++++++++ mods/memory/hooks/register.ts | 63 ++++++++++++--- 2 files changed, 179 insertions(+), 10 deletions(-) diff --git a/mods/memory/hooks/register.test.ts b/mods/memory/hooks/register.test.ts index bf9d79f..5c03b2e 100644 --- a/mods/memory/hooks/register.test.ts +++ b/mods/memory/hooks/register.test.ts @@ -64,6 +64,11 @@ type World = { getsFail: boolean // store.get throws model: Model // what `model.complete` does now asks: Ask[] // every model.complete call + storeCap: number // store.set rejects when the store would pass this size + rejected: number // store.set calls rejected (full store or rejectSets) + rejectSets: number // the next store.set calls to reject whatever the size + gitProtect: string | undefined // `git config gitflow.protect` (absent: exit 1) + gitRuns: string[][] // every git process.run argv } type Opts = { @@ -75,6 +80,16 @@ type Opts = { unreadable?: string[] // paths whose fs.read throws statFails?: string[] // paths whose fs.stat throws though they exist existsFails?: string[] // paths whose fs.exists throws + storeCap?: number // total serialized bytes the store accepts + rejectSets?: number // reject this many store.set calls, then accept + gitProtect?: string // what `git config --get gitflow.protect` prints +} + +/** The bytes the store holds, counting `key` as empty (it is rewritten). */ +function storedSize(w: World, key: string): number { + let n = 0 + for (const [k, v] of w.kv) if (k !== key) n += JSON.stringify(v).length + return n } /** @@ -92,6 +107,13 @@ function handStore(on: On, w: World, fails: boolean): void { on('store.delete', (_a, e) => ({ value: void w.kv.delete(e.key) })) on('store.set', (_a, e) => { if (fails) throw new Error('disk full') + const over = storedSize(w, e.key) + JSON.stringify(e.value).length > + w.storeCap + if (over || w.rejectSets > 0) { + w.rejectSets = Math.max(0, w.rejectSets - 1) + w.rejected++ + throw new Error('store full') + } w.sets.push(e.key) w.kv.set(e.key, JSON.parse(JSON.stringify(e.value))) return { value: undefined } @@ -113,6 +135,9 @@ async function boot($: Engine, on: On, o: Opts = {}): Promise<World> { existsFails: new Set(o.existsFails ?? []), proc: { stdout: INDEX_OUT }, runs: [], home: HOME, gets: 0, getsFail: false, model: { text: 'none' }, asks: [], + storeCap: o.storeCap ?? Infinity, rejected: 0, + rejectSets: o.rejectSets ?? 0, + gitProtect: o.gitProtect, gitRuns: [], } handStore(on, w, o.storeFails ?? false) on('tool.register', (_a, e) => { @@ -151,6 +176,13 @@ async function boot($: Engine, on: On, o: Opts = {}): Promise<World> { return { value: w.switchText } }) on('process.run', async (_a, e) => { + if (e.argv[0] === 'git') { + w.gitRuns.push([...e.argv]) + const out = w.gitProtect + return { value: { exitCode: out === undefined ? 1 : 0, + stdout: out === undefined ? '' : `${out}\n`, stderr: '', + isStdoutTruncated: false, isStderrTruncated: false } } + } w.runs.push([...e.argv]) if (w.proc === 'throw') throw new Error('spawn failed') if (w.proc === 'hang') await new Promise(() => undefined) @@ -2968,3 +3000,97 @@ test('PC2: a throwing recall still lets the note attach', async ($, on) => { expect(added[0]).toContain('memory: commit fix: y') expect(w.logs.filter(l => l.includes('prompt.submit'))).toEqual([]) }) + +// ---- store sweep before the save, one retry on a rejected set ---------- + +const ENGINE_BYTES = 4194304 +const fill = (n: number) => 'x'.repeat(n - 2) // n serialized bytes + +test('SW1: a full store and a new session: swept first, the save lands', + async ($, on) => { + const w = await boot($, on, { + storeCap: ENGINE_BYTES, + seed: { 'l:/a': fill(1400000), 'l:/b': fill(1400000), + 'l:/c': fill(1394240) }, + }) + await failing($, w, EXIT1 + 'fatal: bad thing') + expect(failuresOf(w)).toHaveLength(1) + expect(w.kv.has('l:/a')).toBe(false) + expect(w.rejected).toBe(0) + }) + +test('SW2: a rejected set sweeps and retries once, the retry lands', + async ($, on) => { + const w = await boot($, on, { rejectSets: 1 }) + await failing($, w, EXIT1 + 'fatal: bad thing') + expect(w.rejected).toBe(1) + expect(failuresOf(w)).toHaveLength(1) + }) + +test('SW3: a set rejected twice is not retried a third time', async ( + $, on, +) => { + const w = await boot($, on, { rejectSets: 5 }) + const out = await failing($, w, EXIT1 + 'fatal: bad thing') + expect(out).toEqual(w.answer) + expect(w.rejected).toBe(2) +}) + +test('SW4: a rejected log set retries once and lands', async ($, on) => { + const { w } = await bootRecall($, on, { rejectSets: 1 }) + await start($) + await say($, GO) + expect(w.rejected).toBe(1) + expect(await askLog(w)).toEqual([['fresh', 'injected', ['BLK-001']]]) +}) + +// ---- a foreign repository gets no recall and no known line ------------- + +test('FR1: gitflow.protect false: no known line, capture still works', + async ($, on) => { + const w = await bootKnown($, on, { gitProtect: 'false' }) + const out = await failing($, w, EXIT1 + KN_SPAN) + expect(out).toEqual(w.answer) + expect(failuresOf(w)).toHaveLength(1) + expect(w.gitRuns[0]).toEqual( + ['git', '-C', ROOT, 'config', '--get', 'gitflow.protect']) + }) + +test('FR2: gitflow.protect false: no recall, memory_pending answers', + async ($, on) => { + const { w, seen } = await bootRecall($, on, { gitProtect: 'false' }) + await start($) + await run($, w, 'git commit -m "fix: y"') + await say($, GO) + expect(seen[0]?.some(c => c.startsWith('memory recall:')) ?? false) + .toBe(false) + expect(w.asks).toHaveLength(0) + expect(await pending($)).toContain('fix: y') + }) + +const protectCases: [string, Opts][] = [ + ['true', { gitProtect: 'true' }], ['absent', {}], +] +for (const [name, opts] of protectCases) { + test(`FR3: gitflow.protect ${name}: known line unchanged`, async ($, on) => { + const w = await bootKnown($, on, opts) + const out = await failing($, w, EXIT1 + KN_SPAN) + expect(out).toEqual({ ...(w.answer as object), context: [KN_LINE] }) + }) + + test(`FR3: gitflow.protect ${name}: recall unchanged`, async ($, on) => { + const { seen } = await bootRecall($, on, opts) + await start($) + await say($, GO) + expect(seen[0]?.[0]).toBe(BLOCK1) + }) +} + +test('FR4: the protect read happens once per root and session', async ( + $, on, +) => { + const w = await bootKnown($, on, { gitProtect: 'true' }) + await failing($, w, EXIT1 + KN_SPAN) + await failing($, w, EXIT1 + 'fatal: other zebra quartz', 'make b') + expect(w.gitRuns).toHaveLength(1) +}) diff --git a/mods/memory/hooks/register.ts b/mods/memory/hooks/register.ts index 5bcc2be..9dd95a9 100644 --- a/mods/memory/hooks/register.ts +++ b/mods/memory/hooks/register.ts @@ -20,6 +20,7 @@ type State = { fresh: Set<string> // sessions whose next qualifying prompt starts a context lastPrompt: Map<string, number> // session id -> time of its last prompt rerank: { fails: number; until: number } // failures in a row, pause end + foreign: Map<string, boolean> // project root -> gitflow.protect is false } export const IDLE_MS = 1800000 @@ -673,6 +674,20 @@ async function statusMap($: Api, root: string): Promise<StatusMap | undefined> { } } +/** + * True when the project's git config marks it foreign (`gitflow.protect` + * is `false`). Read once per root and session; any failure: not foreign. + */ +async function isForeign($: Api, st: State, root: string): Promise<boolean> { + const known = st.foreign.get(root) + if (known !== undefined) return known + const out = await runWithin( + $, ['git', '-C', root, 'config', '--get', 'gitflow.protect']) + const foreign = out?.trim() === 'false' + st.foreign.set(root, foreign) + return foreign +} + // Function words, 3+ letters first, then the 2-letter FR and EN ones: TOKEN // takes 2+ letters, so without them "ok tu peux continuer la suite stp" // counts 7 content words and passes the floor. At most 120 words. @@ -1004,6 +1019,19 @@ function fitLog(log: LogRecord[]): LogRecord[] { return kept } +/** Runs `write`; if it rejects, sweeps once and runs it a second time. */ +async function retryOnce( + sweep: () => Promise<void>, + write: () => Promise<void>, +): Promise<void> { + try { + await write() + } catch { + await sweep() + await write() + } +} + /** Appends an injection record on the write chain; the oldest fall off. */ export function appendLog( $: Api, @@ -1014,27 +1042,38 @@ export function appendLog( return queueWrite(st, async () => { const log = await loadLog($, root) if (log.length === 0) await sweepLogs($, logKey(root)) - await $.store.set(logKey(root), fitLog([...log, record])) + await retryOnce( + () => sweepLogs($, logKey(root)), + () => $.store.set(logKey(root), fitLog([...log, record])), + ) }) } type Where = { root: string; id: string } -/** Load, change the current session, save; sweeps when it is created. */ +const sweepAll = async ($: Api, at: Where) => { + await sweepStore($, storeKey(at.root), at.id) + await sweepLogs($, logKey(at.root)) +} + +/** + * Load, change the current session, save. A new session sweeps the store + * first, so the save fits; a rejected save sweeps and retries once. + */ async function mutateSession( $: Api, at: Where, now: number, change: (s: Session) => void, ): Promise<void> { - const p = await loadProject($, at.root) - const created = !p.sessions.some(s => s.id === at.id) - change(sessionOf(p, at.id, now)) - await saveProject($, at.root, p) - if (created) { - await sweepStore($, storeKey(at.root), at.id) - await sweepLogs($, logKey(at.root)) + const save = async () => { + const p = await loadProject($, at.root) + change(sessionOf(p, at.id, now)) + await saveProject($, at.root, p) } + const known = await loadProject($, at.root) + if (!known.sessions.some(s => s.id === at.id)) await sweepAll($, at) + await retryOnce(() => sweepAll($, at), save) } const recordFailure = ($: Api, at: Where, f: Failure) => @@ -1122,6 +1161,7 @@ export function newState(): State { fresh: new Set(), lastPrompt: new Map(), rerank: { fails: 0, until: 0 }, + foreign: new Map(), } } @@ -1493,6 +1533,7 @@ async function knownLine( agent: string | undefined, ): Promise<string> { if (!(await ensureRecall($, st))) return '' + if (await isForeign($, st, at.root)) return '' const entry = await liveCandidate($, at.root, f.key) if (entry === undefined) return '' const line = `memory: known ${recallLine(entry)}` @@ -1777,7 +1818,9 @@ export async function promptContext( const idle = last === undefined ? 0 : now - last // unknown: not idle st.lastPrompt.set(at.id, now) st.spent.delete(contextKey(at.id, undefined)) - const trigger = (await ensureRecall($, st)) + const recalling = (await ensureRecall($, st)) && + !(await isForeign($, st, at.root)) + const trigger = recalling ? triggerKind(e.text, st.fresh.has(at.id), idle) : undefined if (trigger !== undefined) st.fresh.delete(at.id) From fd646a611a78200ffb96d7afd649499fdc864cdf Mon Sep 17 00:00:00 2001 From: bchanot <chanot.bastien@gmail.com> Date: Fri, 6 Nov 2026 11:38:48 +0100 Subject: [PATCH 34/41] chore(memory): BLK-043 fork bomb resolved in 49aa2ff, BLK-044 open, contract and plans --- .claude/memory/blockers.md | 13 ++ .claude/memory/journal.md | 3 + .claude/tasks/TODO.md | 5 +- .../2026-11-06-detect-plan-fork-bomb-0105.md | 53 +++++++ .../2026-11-05-memory-feedback-4d-1834.md | 138 ++++++++++++++++++ .../2026-11-06-detect-plan-fork-bomb-0030.md | 110 ++++++++++++++ 6 files changed, 321 insertions(+), 1 deletion(-) create mode 100644 .claude/tasks/contracts/2026-11-06-detect-plan-fork-bomb-0105.md create mode 100644 .claude/tasks/plans/2026-11-05-memory-feedback-4d-1834.md create mode 100644 .claude/tasks/plans/2026-11-06-detect-plan-fork-bomb-0030.md diff --git a/.claude/memory/blockers.md b/.claude/memory/blockers.md index 54c5cc7..76b831b 100644 --- a/.claude/memory/blockers.md +++ b/.claude/memory/blockers.md @@ -370,3 +370,16 @@ rules: - **Real cause**: no rule or guard named package/archive extraction into system dirs; the ssh deny rule did not cover vaas-cli ssh; extraction improvised instead of telling the user there was no package manager. - **Solution**: `hooks/extract-guard.sh` (deny before run, quoted remote scripts re-scanned) + soft_deny line + doctrine bullet (list first, extract into a literal mktemp -d path, PATH/PYTHONPATH, no package manager → tell the user). See the extract-guard BDR. - **Status**: resolved 2026-11-05. + +## BLK-043 — detect_plan CLI fallback forks claude from SessionStart hook: recursive fork bomb, OOM, reboot [open] (2026-11-06) +- **Friction**: `make test suite=lib/tests/session-digest.test.sh` (uncommitted SD13 cases) ate 14 GiB in 45 s, 2026-11-05 23:49; earlyoom killed valheim, node, mariadb, docker, audio; kernel OOM; machine rebooted 23:55; all sessions + RC lost. OOM dump: 126 `claude`, 396 `bash`, 124 `sh`. +- **Real cause**: `lib/detect-plugins.sh` `detect_plan` falls back to `claude config get planType` when `$HOME/.claude.json` lacks plan markers. claude 2.1.318 has no `config` subcommand → words read as prompt → full session → its SessionStart hook (`hooks/session-start.sh:158`) calls `detect_plan` again, same HOME → unbounded recursion. SD13 `mkhome` linked `~/.claude/*` but not `~/.claude.json`. Prod survives only via internal flags `tengu_cobalt_compass` + `tengu_harbor` in `~/.claude.json`; flag rename upstream → every session start recurses. +- **Solution**: pending /bugfix (plan `.claude/tasks/plans/2026-11-06-detect-plan-fork-bomb-0030.md`): CLI fallback dropped (default pro), hook recursion guard env marker, suite-wide `claude` stub in PATH + regression cases. +- **Status**: open 2026-11-06, fix in progress. +- **Status (2026-11-06)**: resolved 49aa2ff (hotfix/detect-plan-fork-bomb): CLI fallback dropped, env guard SESSION_START_RUNNING, lib/tests/detect-plan.test.sh red on main lib, green after; merge pending user + +## BLK-044 — claude processes run with oom_score_adj -1000 of unknown origin: OOM killers spare a runaway claude [open] (2026-11-06) +- **Friction**: during the detect_plan fork bomb (2026-11-05 23:49), every `claude`, `bash`, `grep` child carried `oom_score_adj=-1000`; earlyoom and kernel OOM could not kill the runaway, killed every other service instead (valheim, mariadb, docker, networkd, logind) until reboot. Live session 2026-11-06 still shows `-1000`. +- **Real cause**: unknown. Not set by the repo (`lib/cc.sh`, hooks: no OOMScoreAdjust). Suspects: inherited from launcher (dtach under `systemd-run --user --scope`, sshd, or the RC/remote-control process). +- **Solution**: none yet. Next: trace `/proc/<pid>/oom_score_adj` up the parent chain of a live claude; then set `OOMScoreAdjust` (e.g. 500) on the `cc` scope so a claude runaway dies first. +- **Status**: open 2026-11-06. diff --git a/.claude/memory/journal.md b/.claude/memory/journal.md index b73d838..98c89d7 100644 --- a/.claude/memory/journal.md +++ b/.claude/memory/journal.md @@ -696,3 +696,6 @@ rules: ## 2026-11-05 - 2026-11-05: extract-guard built on feature/extract-guard (hook, soft_deny, doctrine; verifier CONFORME, security PASS); live in settings working copy; 4c paused at plan r2; merge pending user. + +## 2026-11-06 +- 2026-11-06: machine OOM reboot 2026-11-05 23:55 root-caused: detect_plan `claude config get planType` fork bomb via SessionStart (BLK-043), SD13 fake HOME trigger. /bugfix: 3 lenses → r2 (hotfix off main, worktree), GATE 0 MET, verifier ECARTS(1 SC2016) → CONFORME, security PASS ×2; 49aa2ff. BLK-044 open (oom_score_adj -1000). Merge + Part B pending. diff --git a/.claude/tasks/TODO.md b/.claude/tasks/TODO.md index 307bf77..906be29 100644 --- a/.claude/tasks/TODO.md +++ b/.claude/tasks/TODO.md @@ -117,9 +117,12 @@ Shared rules for every phase: - [x] shortcut (done in 4c, Task 1: the lexical reader is gone, statuses come from `memory.sh index`): `mods/memory/hooks/register.ts` `isSuperseded` is a lexical reader, not memory.sh's status parser; upgrade = share that parser when 4c needs it (final review M11) - **4c read side (built 2026-11-05 on feature/memory-recall, merge pending).** 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` (native matchers; the mod's `session.compact` only skips); 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 scope=global index, `memory_search` tool. - 4c follow-up from the 4b live proof (2026-11-04): `memory_pending` lists milestones of the current session only, so a `/capitalize` run right after `/clear` misses the previous session's `fix:`/finish milestones (they stay in the store). Option: list earlier-session milestones marked `(earlier session)`. Doctrine (capitalize before /clear) covers the normal path. - - **4d feedback and promotion.** The injection log now exists (4c, store key `l:<root>`); 4d waits on its data. DEFERRED until a plain injection log (ID, trigger kind, turn, cited or not) shows misses or noise; then /prune-memory reads it and promotion to a mechanism follows BDR-100. + - **4d feedback and promotion.** Plan r1 (draft, not challenged): `.claude/tasks/plans/2026-11-05-memory-feedback-4d-1834.md`. Log read 2026-11-05: 1 real record, no decision possible; it cannot show usefulness or misses alone and transcripts live 7 days. Order: 4d.1 log fields `cands` + `ms` → 4d.2 weekly reader (log × transcripts, labels.tsv) → 4d.3 gate (≥20 prompt + ≥10 tool injections, or 5 weeks) with thresholds fixed now → 4d.4 /prune-memory + BDR-100 promotion, conditional. Starts after the 4c merge; 4 open choices in the plan. - [ ] shortcut: the injection log lives under `l:<root>` store keys (about 28 KiB each, 200 records and 64 KiB at most); `sweepLogs` counts them with the `p:` keys and evicts the oldest log key (by its newest record, never the current root's) once the total nears the engine's 4 MiB store cap; upgrade = one global log key or a smaller per-root cap (`mods/memory/hooks/register.ts`). - [ ] residual: the pre-existing `memory.sh check` call in `hooks/session-start.sh` is not time-bounded (the digest's `memory.sh index blocker` call is); upgrade = wrap it in `timeout 2`. + - [ ] BLK-043 hotfix `49aa2ff` on hotfix/detect-plan-fork-bomb (worktree ../claude-hotfix-wt): merge on user signal (`gitflow finish` → main + develop), then `git worktree remove`; then Part B on this branch: suite-wide `claude` PATH stub + final empty-log check in `lib/tests/session-digest.test.sh` BEFORE SD13/SD14 run again (plan `.claude/tasks/plans/2026-11-06-detect-plan-fork-bomb-0030.md` r2). + - [ ] shortcut (BLK-043 gate 2 LOWs): `lib/tests/detect-plan.test.sh` unchecked `mktemp -d` (empty WORK → real `claude probe`), `bash -c "source '$LIB'"` interpolation, no `GIT_CEILING_DIRECTORIES` on hook runs; and the memory, graphify-gate, push-guard suites run the hook with no `claude` stub. Upgrade = `|| exit 1` + `command -v claude` assert, positional args, ceiling dir, shared stub helper. + - [ ] BLK-044: trace origin of `oom_score_adj=-1000` on claude processes; set `OOMScoreAdjust` on the `cc` scope so a runaway claude dies first. - Proof: recall precision on ≥20 real prompts and ≥10 real errors, target ≥ the 14/22 baseline; digest after a real compaction; redaction test on the ledger; `/context` delta; captured-failure demo: an error from session N recalled in session N+1. ### Actionable diff --git a/.claude/tasks/contracts/2026-11-06-detect-plan-fork-bomb-0105.md b/.claude/tasks/contracts/2026-11-06-detect-plan-fork-bomb-0105.md new file mode 100644 index 0000000..b79412b --- /dev/null +++ b/.claude/tasks/contracts/2026-11-06-detect-plan-fork-bomb-0105.md @@ -0,0 +1,53 @@ +# CONTRACT — detect-plan-fork-bomb +- date: 2026-11-06 | flow: bugfix | branch: hotfix/detect-plan-fork-bomb (worktree /home/bchanot/Documents/claude-hotfix-wt, off main 4093cca) +- status: active + +## REQUEST (verbatim — IMMUTABLE) +oui lance le bugfix maintenat pour regler cette escalade et met dnas blockers + +(context, the bug as received: `make test suite=lib/tests/session-digest.test.sh` filled the RAM, OOM, machine reboot 2026-11-05 23:55; root cause `lib/detect-plugins.sh` `detect_plan` falls back to `claude config get planType`, which starts a full session whose SessionStart hook calls `detect_plan` again: recursive fork bomb. Plan: `.claude/tasks/plans/2026-11-06-detect-plan-fork-bomb-0030.md` r2.) + +## CLARIFICATIONS +Q: landing branch? / A: hotfix/* off main, in a separate git worktree; finish merges main + develop; the session-digest stub (Part B) goes to feature/memory-recall after. [gated 2026-11-06] +Q: safety order / A: NEVER run `hooks/session-start.sh`, `make test` (any form) or any suite that runs the hook, in either tree, before fix 1 is on disk in the worktree. The red proof runs `detect_plan` directly (no hook) with the `claude` stub on PATH. Every suite run goes through `systemd-run --user --scope -q -p TasksMax=256`. Never run the real `claude` CLI. [gated 2026-11-06] +Q: BLK entry / A: BLK-043 (fork bomb, open → resolved at commit) and BLK-044 (oom_score_adj -1000, open) written 2026-11-06. [gated 2026-11-06] + +## ACCEPTANCE CRITERIA +1. `detect_plan` in the worktree calls no `claude` CLI; the vulnerable call exists on main (positive control). + CHECK: cd /home/bchanot/Documents/claude-hotfix-wt && git show main:lib/detect-plugins.sh | grep -q 'claude config get planType' && ! grep -nE '(^|[^A-Za-z_./-])claude[[:space:]]+[a-z-]' lib/detect-plugins.sh && echo C1_NO_CLI + EXPECT: C1_NO_CLI + EVIDENCE: MET exit=0 marker-found :: C1_NO_CLI +2. Regression suite `lib/tests/detect-plan.test.sh` exists and passes on the fixed tree, contained. + CHECK: cd /home/bchanot/Documents/claude-hotfix-wt && test -f lib/tests/detect-plan.test.sh && systemd-run --user --scope -q -p TasksMax=256 bash lib/tests/detect-plan.test.sh && echo C2_GREEN + EXPECT: C2_GREEN + EVIDENCE: MET exit=0 marker-found :: detect-plan: 9 passed, 0 failed C2_GREEN +3. Symptom reproduced: the same suite FAILS when pointed at main's `lib/detect-plugins.sh` (the suite takes the lib path from `DETECT_PLUGINS_LIB`, default the repo copy), and the stub, not a real `claude`, caught the call. + CHECK: cd /home/bchanot/Documents/claude-hotfix-wt && git show main:lib/detect-plugins.sh > /home/bchanot/.cache/claude-tmp/claude-1000/-home-bchanot-Documents-claude/fb6518b7-0114-4bfb-9d49-04965b322457/scratchpad/main-detect-plugins.sh && if DETECT_PLUGINS_LIB=/home/bchanot/.cache/claude-tmp/claude-1000/-home-bchanot-Documents-claude/fb6518b7-0114-4bfb-9d49-04965b322457/scratchpad/main-detect-plugins.sh systemd-run --user --scope -q -p TasksMax=256 bash lib/tests/detect-plan.test.sh >/home/bchanot/.cache/claude-tmp/claude-1000/-home-bchanot-Documents-claude/fb6518b7-0114-4bfb-9d49-04965b322457/scratchpad/c3.out 2>&1; then false; else grep -q 'FAIL T1-no-json-calls' /home/bchanot/.cache/claude-tmp/claude-1000/-home-bchanot-Documents-claude/fb6518b7-0114-4bfb-9d49-04965b322457/scratchpad/c3.out && echo C3_RED_BEFORE; fi + (amended 2026-11-06 by the orchestrator before GATE 0: same check, literal scratchpad paths instead of `rm -rf "$t"`; fail line pinned to the regression case) + EXPECT: C3_RED_BEFORE + EVIDENCE: MET exit=0 marker-found :: C3_RED_BEFORE +4. The suite proves its stub is reached (positive control: a `claude` call through PATH logs exactly 1 line before the absence checks), calls `detect_plan` directly with a HOME holding no `.claude.json` and asserts output `pro` with 0 new logged calls. + (judged by the verifier from the suite source) +5. Recursion guard: `hooks/session-start.sh` exits 0 with no output when `SESSION_START_RUNNING` is set, and otherwise exports `SESSION_START_RUNNING=1` before any child process. The suite asserts both: an early-exit case, and a child of the hook (a PATH stub `git`) that records `1`. The hook comment states the guard is defense-in-depth with no live caller and relies on Claude Code passing env to hooks. + CHECK: cd /home/bchanot/Documents/claude-hotfix-wt && grep -q 'SESSION_START_RUNNING' hooks/session-start.sh && grep -q 'SESSION_START_RUNNING' lib/tests/detect-plan.test.sh && echo C5_GUARD_PRESENT + EXPECT: C5_GUARD_PRESENT + EVIDENCE: MET exit=0 marker-found :: C5_GUARD_PRESENT +6. Dead code removed: `detect_plan` docstring says it returns max or pro (no free); the `free)` arm of the plan `case` in `hooks/session-start.sh` is gone. + CHECK: cd /home/bchanot/Documents/claude-hotfix-wt && ! grep -nE '^[[:space:]]*free\)' hooks/session-start.sh && ! grep -niE 'max, pro, or free' lib/detect-plugins.sh && echo C6_NO_DEAD + EXPECT: C6_NO_DEAD + EVIDENCE: MET exit=0 marker-found :: C6_NO_DEAD +7. shellcheck clean on the three files. + CHECK: cd /home/bchanot/Documents/claude-hotfix-wt && shellcheck lib/detect-plugins.sh hooks/session-start.sh lib/tests/detect-plan.test.sh && echo C7_LINT + EXPECT: C7_LINT + EVIDENCE: MET exit=0 marker-found :: C7_LINT +8. Full suite green once, contained (LRN-209: one full run before finish). + CHECK: cd /home/bchanot/Documents/claude-hotfix-wt && systemd-run --user --scope -q -p TasksMax=512 make test >/home/bchanot/.cache/claude-tmp/claude-1000/-home-bchanot-Documents-claude/fb6518b7-0114-4bfb-9d49-04965b322457/scratchpad/hotfix-maketest.log 2>&1; rc=$?; tail -5 /home/bchanot/.cache/claude-tmp/claude-1000/-home-bchanot-Documents-claude/fb6518b7-0114-4bfb-9d49-04965b322457/scratchpad/hotfix-maketest.log; [ "$rc" -eq 0 ] && echo C8_SUITE_GREEN + EXPECT: C8_SUITE_GREEN + EVIDENCE: MET exit=0 marker-found :: GREEN ✓ G3 strict-YAML: all agents/*.md frontmatter parse GREEN ✓ G4 hermetic: run-reconcile.sh reads fixtures only, not the live registry G… + +## FILE SCOPE +In /home/bchanot/Documents/claude-hotfix-wt only: +- lib/detect-plugins.sh (detect_plan) +- hooks/session-start.sh (guard at top; `free)` arm) +- lib/tests/detect-plan.test.sh (new) +Nothing in /home/bchanot/Documents/claude (the feature/memory-recall tree and its uncommitted work). diff --git a/.claude/tasks/plans/2026-11-05-memory-feedback-4d-1834.md b/.claude/tasks/plans/2026-11-05-memory-feedback-4d-1834.md new file mode 100644 index 0000000..5727c19 --- /dev/null +++ b/.claude/tasks/plans/2026-11-05-memory-feedback-4d-1834.md @@ -0,0 +1,138 @@ +# Phase 4d memory feedback and promotion: plan (2026-11-05) + +BDR-125 phase 4d, host `mods/memory` (BDR-137). Input: the 4c injection log, +store key `l:<root>` (`LogRecord` in `mods/memory/hooks/register.ts`). +Status: draft r1, not challenged, not gated. Starts after the 4c merge. + +## What the log holds (read 2026-11-05, 18:30) + +- Real use: 1 record. This repo, trigger `fresh`, outcome `injected`, IDs + BDR-125, BDR-137, LRN-261: the prompt that asked for this plan. +- Plus 1 headless proof record (tool channel, fixture BLK-001, temp repo). +- Expected rate in this repo (RECALL.md, 14 days, after the content floor): + about 15 triggered asks per 14 days, 3 tool-channel injections. + +No decision can come from this. The TODO gate ("deferred until the log shows +misses or noise") is not met, and the log alone can never meet it, for the +three reasons below. + +## Gaps between the log and the 4d questions + +1. Usefulness is not recorded. The 4d design (queue challenge 2026-10-25) + asked for "cited or not"; a record holds `at, session, agent, channel, + ids, trigger, outcome`. Relevance needs the prompt and the reply, and + both live in the transcript, not in the store. +2. Misses leave no trace. The log lists what came, never what should have + come. Example: this plan's prompt did not bring BDR-100, the promotion + rule the TODO 4d line cites, and nothing records that. +3. Transcripts live 7 days (`cleanupPeriodDays: 7`, job7 step D, secret + hygiene). A single log-to-transcript join at the gate, about 3 weeks + out, would find most turns gone. Older transcripts survive today; the + setting does not promise it. + +Minor: a prompt-channel `none` mixes "BM25 found no candidate" and "haiku +declined" (both paths in `recallFor`); rerank latency is not logged, only +the `timeout` outcome. + +## 4d.1 Two log fields (mod, /feat after the 4c merge) + +- Prompt records gain `cands` (BM25 candidates after the seen filter, 0-30) + and `ms` (rerank wall time, absent when no rerank ran). Both optional in + `isLogRecord`: records written before stay valid. +- Size: about 40 bytes more per record, 200 records stay under 40 KiB + (cap 64 KiB). +- Nothing else enters the store: no prompt text, no reply text (LRN-124), + no runtime cited flag (it would need a Stop hook reading the transcript + every turn, for a signal the offline join gets at no runtime cost). +- Proof: kit tests for both fields, an old-shape record still loads, the + `none` split visible on a fixture with zero candidates. + +## 4d.2 Weekly reader (harness, no runtime change) + +- `feedback.ts` (bun) beside this plan. It reuses `recall-bench.ts`'s + transcript loader (`findFiles`, `records`, `composerText`, exported, not + copied) and the mod's own functions (no port, LRN-261). +- Reads every `l:` key of the store file, all roots. The file path is + engine-internal (`~/.claude/plugins/store/memory_skills-dir-*.json`): + a renamed file fails loudly, acceptable for a measurement tool. +- Joins each record to its transcript by `session` and `at`: + - prompt channel: the composer prompt it answered and the assistant turn + that followed; + - tool channel: the failing command and the next 3 Bash results of the + same session (retry succeeded or not). +- Per injected entry: `cited` (the ID appears in the turn's assistant + text, a lower bound) and a relevance label (controller labels, the user + spot-checks: the 4c method). +- Misses: on up to 5 triggered asks per run, the controller searches the + registries for relevant entries the recall did not bring, and names the + cause (no lexical overlap, BM25 rank over 30, haiku declined). The + FR-prompt vs EN-entry gap is the expected first cause. +- Persists `labels.tsv` (at, root name, channel, trigger, outcome, cands, + ID, cited, label): IDs and enums only, committed. Labelled records are + skipped on the next run; prompt and reply text stay in the scratchpad. +- Writes `FEEDBACK.md`: counts and shares only. +- Cadence: once a week, inside the 7-day window, about 10 minutes of label + checks for the user. + +## 4d.3 Gate and decisions fixed before the data + +Gate: at least 20 labelled injected prompt asks and 10 tool injections (the +BDR-125 proof line), or 5 weeks after the 4c merge, whichever comes first. +At the date cap with a smaller n: report "insufficient sample" with the n, +extend once or close. + +| Signal | Threshold | Action | +|---|---|---| +| prompt precision (relevant / injected entries) | at least 64 % | keep | +| same, below 64 % | worst trigger kind below 50 % | tighten or drop that trigger (idle first: the 4c noise sat there) | +| precision of the 3rd pick | below 40 % | cap at 2 entries | +| timeout + paused share (asks with `cands` > 0) | above 25 % | revisit `RERANK_MS` or skip the rerank on short lists | +| `ms` p90 | below 2500 | lower `RERANK_MS`: every triggered prompt waits that long | +| tool precision | below 50 % | require 2 matched grams, or exclude the entry | +| misses in the sample | 1 ask in 3 or more | diagnose by cause; no fix built ahead | +| entry injected 3 times or more, 0 relevant | any | noisy: /prune-memory rewrites it | +| entry relevant 3 times or more, in 2 sessions or more | any | promotion candidate (BDR-100) | + +Each action is its own /feat or /hotfix with the measurement attached. 4d +builds no tuning before the gate. + +## 4d.4 Promotion and /prune-memory (conditional) + +Built only if the gate shows at least one noisy entry or one promotion +candidate; otherwise closed with the measurement, like phase 3. + +- Promotion stays a proposal: the reader lists each candidate with its + counts, the user picks, the mechanism (guard, test, skill step) becomes + its own TODO run, and the entry links the mechanism's commit. Never + automatic. +- /prune-memory STEP 1 gains "D. Recall feedback": reads `labels.tsv` + through one lib script that holds the thresholds (doctrine "After code + changes" step 4); noisy entries join section C, promotion candidates go + to STEP 2 as TODO lines. +- Open at that point: where other repos keep their labels (the mod logs + every root, the reader lives in this repo). + +## Open choices (user) + +1. Cadence vs retention: weekly reader runs (recommended); or raise + `cleanupPeriodDays` for the window (reverses job7 step D, transcripts + carry secrets); or one run at the gate on a single week. +2. 4d.1 fields `cands` and `ms`: add them (recommended) or measure with the + current record. +3. Gate numbers and the 5-week cap. +4. Promotion threshold: relevant 3 times in 2 sessions. + +## Prerequisite: 4c merge + +- Recall half of the interactive proof seen in this session: a fresh design + prompt brought 3 entries, all relevant to the ask by the controller's + reading (labeller and beneficiary are the same model: unchecked). +- Still owed: the digest after a real `/compact`, the 4c gates, the user's + "merge it". + +## Out of scope + +Runtime cited flag, prompt text in the store, the 4c deferrals (Read and +Bash command triggers, critical deny-once, Tier 1, cross-repo index, +`memory_search`), the `l:<root>` cross-root shortcut and the unbounded +`memory.sh check` residual (own TODO lines). diff --git a/.claude/tasks/plans/2026-11-06-detect-plan-fork-bomb-0030.md b/.claude/tasks/plans/2026-11-06-detect-plan-fork-bomb-0030.md new file mode 100644 index 0000000..f2643ce --- /dev/null +++ b/.claude/tasks/plans/2026-11-06-detect-plan-fork-bomb-0030.md @@ -0,0 +1,110 @@ +# Bugfix plan: detect_plan fork bomb (2026-11-06) + +## Diagnosis + +BUG: running `lib/tests/session-digest.test.sh` (uncommitted SD13 cases) +filled 14 GiB of RAM in 45 s; 2026-11-05 23:49 → OOM → reboot 23:55. +Kernel OOM dump: 126 `claude`, 396 `bash`, 124 `sh`, all +`oom_score_adj=-1000`. + +ROOT CAUSE: `lib/detect-plugins.sh:85` `detect_plan` falls back to +`claude config get planType` when `$HOME/.claude.json` lacks the plan +markers or is absent. claude 2.1.318 has no `config` subcommand +(`claude config --help` prints the main usage), so the words are read +as a prompt and a full session starts. Its SessionStart hook +(`hooks/session-start.sh:158` → `detect_plan`) runs with the same HOME, +finds the same missing markers, starts another `claude`: unbounded +recursion. SD13's `mkhome` builds a HOME that links `~/.claude/*` but +not `~/.claude.json`, so the fallback fires. + +EVIDENCE: journal boot -1 (earlyoom + kernel OOM table), transcript +90b2c305 (`make test suite=lib/tests/session-digest.test.sh` at +23:49:07, result at 23:51:28), `claude config --help` output. + +BLAST RADIUS: production too. Real sessions survive only because +`~/.claude.json` holds `tengu_cobalt_compass` + `tengu_harbor` (internal +feature flags). If upstream renames them, every session start recurses. +`detect_plan` is called only from `hooks/session-start.sh:158`. No other +hook or lib calls the `claude` CLI (`lib/cc.sh` is the user launcher). +The hook header already promises "Filesystem only, except one git fetch". + +RELATED MEMORY: no BLK/BDR/LRN bears (grep detect_plan, fork, recurs, +oom, planType). + +## Fix plan + +1. `lib/detect-plugins.sh` `detect_plan`: delete the `claude config get + planType` fallback and its `case`; markers absent → `echo "pro"` + (the existing default). Comment states why the CLI is never called + (a hook-launched `claude` re-enters this hook). +2. `hooks/session-start.sh`: recursion guard at the top, before stdin + is read: `[ -n "${CLAUDE_SS_RUNNING:-}" ] && exit 0; export + CLAUDE_SS_RUNNING=1`. The variable lives only in the hook's process + tree: a sibling session never sees it; any `claude` a future change + spawns from the hook gets a silent no-op hook instead of a cascade. +3. `lib/tests/session-digest.test.sh` (keeps the uncommitted SD13/SD14 + cases intact): + - suite-wide stub: `$WORK/stub/claude` writes one line to + `$WORK/claude-calls` and exits 0; `PATH="$WORK/stub:$PATH"` exported + before any case. A regression then records a call instead of + forking a real session. SD13h's `PATH="$bin"` already holds no + claude. + - SD15a: `HOME` without `.claude.json` (mkhome as is), hook runs → + `claude-calls` absent/empty. + - SD15b: `CLAUDE_SS_RUNNING=1` set → hook prints nothing, rc 0. + - SD15c: `detect_plan` sourced alone with an empty HOME prints `pro`. + Replaces the `ulimit -u` idea: the per-user process cap counts every + process of the user (hundreds of live ones), so a value is either + too tight (spurious red) or too loose (no protection); the stub is + deterministic. + +ORDER: fix 1 lands before the suite runs again (DO NOT run the suite +on the current tree). + +RISK: low. Plan detection for users without the markers now always +reports Pro (banner budget label only). Guard: a user who runs the hook +by hand from inside a hook-spawned shell sees nothing (no such use). + +Out of scope: origin of `oom_score_adj=-1000` on claude processes +(recorded as an open BLK), plan detection accuracy. + +## Revision r2 (after 3-lens challenge, 2026-11-06) + +Challenge: simplicity SOLID (4 MINOR), correctness CONCERNS (1 MAJOR), +robustness CONCERNS (3 MAJOR). Named changes: + +- R1 (correctness 1, robustness 3: landing). The fallback is on main and + develop. The fix splits in two: + - Part A, on its own branch off main or develop (user choice), in a + separate `git worktree` (so `~/.claude/hooks` and `~/.claude/lib`, + symlinked to the main working tree, never flip to another branch and + the uncommitted 4c work stays untouched): fix 1, fix 2, and a + standalone regression suite `lib/tests/detect-plan.test.sh` that + needs nothing from feature/memory-recall. + - Part B, on feature/memory-recall after Part A merges: suite-wide + stub in session-digest.test.sh + final empty-log assertion. +- R2 (robustness 1+2, correctness 2+4: proof). The stub is written with + the log path expanded at creation, `chmod +x`, and a positive control + first calls `claude` through PATH and asserts 1 logged line (stub + reached). The regression case calls `detect_plan` directly (no hook, + no recursion path) with an empty HOME and asserts output `pro` AND + 0 new log lines. Red proof: that case runs once against the pre-fix + lib (safe: stub catches the single call) and must fail, then pass + after fix 1. Copied into the contract as [gated]: never run the hook, + `make test` or the session-digest suite before fix 1 is on disk. +- R3 (correctness 3, robustness 5: guard). Guard kept as + defense-in-depth (the -1000 adj made the runaway unkillable), renamed + `SESSION_START_RUNNING` (simplicity 4, repo convention). The hook + comment says it has no live caller and that it relies on claude + passing env to its hooks. Test: hook run with the variable set prints + nothing, rc 0; and a PATH stub `git` writes `$SESSION_START_RUNNING` + seen by the hook's child, asserting `1` (proves the export). +- R4 (simplicity 2, correctness 5: dead code). detect_plan docstring + "max or pro"; the `free)` arm at session-start.sh:162 dropped. +- R5 (simplicity 3): SD15a/SD15c dropped from Part B; one final + cumulative empty-log check covers every hook run of the suite. +- R6 (robustness 6: containment). The first run of each suite after the + fix goes through `systemd-run --user --scope -p TasksMax=256` (cgroup + pids cap counting only that scope). +- Deferred to TODO (robustness 4, MINOR): stub in memory, graphify-gate + and push-guard suites, which run the hook with the real HOME. From 4a7ce370180f66016e2ae515433c9c2f95512bec Mon Sep 17 00:00:00 2001 From: bchanot <chanot.bastien@gmail.com> Date: Fri, 6 Nov 2026 13:15:28 +0100 Subject: [PATCH 35/41] fix(memory): enabled:false in memory.json and foreign repos cut the session digest The digest now honours the mod's switch (boolean false only) and skips repositories with gitflow.protect false, like the recall channels. SD13/SD14 cover both. --- hooks/session-start.sh | 15 ++++++++--- lib/tests/session-digest.test.sh | 45 ++++++++++++++++++++++++++++++++ 2 files changed, 57 insertions(+), 3 deletions(-) diff --git a/hooks/session-start.sh b/hooks/session-start.sh index c447b8e..c811057 100644 --- a/hooks/session-start.sh +++ b/hooks/session-start.sh @@ -25,7 +25,13 @@ if command -v timeout >/dev/null 2>&1 && command -v jq >/dev/null 2>&1; then _ss_source=$(printf '%s' "$_ss_in" | jq -r '.source // empty' 2>/dev/null) fi case "$_ss_source" in ""|startup|clear|compact) _ss_digest=1 ;; esac - unset _ss_in _ss_source + # The mod's switch: `"enabled": false` (a boolean) cuts the digest. An + # absent, unreadable or unparsable file, or any other value, keeps it. + # "recall" is the mod's own key and is ignored here. + _ss_off=$(jq -r 'if .enabled == false then "off" else "on" end' \ + "$HOME/.claude/memory.json" 2>/dev/null) + [ "$_ss_off" = off ] && _ss_digest=0 + unset _ss_in _ss_source _ss_off elif [ -t 0 ]; then _ss_digest=1 fi @@ -437,8 +443,11 @@ _memory_digest() { # <project-root> } if [ "$_ss_digest" = 1 ]; then _ss_root=$(git rev-parse --show-toplevel 2>/dev/null) || _ss_root=$PWD - ( _memory_digest "$_ss_root" ) 2>/dev/null || true - unset _ss_root + # A foreign repository (`gitflow.protect` false) gets no digest. + _ss_protect=$(git -C "$_ss_root" config --get gitflow.protect 2>/dev/null) + [ "$_ss_protect" = false ] || + ( _memory_digest "$_ss_root" ) 2>/dev/null || true + unset _ss_root _ss_protect fi unset _ss_digest diff --git a/lib/tests/session-digest.test.sh b/lib/tests/session-digest.test.sh index 89a7fea..1149670 100644 --- a/lib/tests/session-digest.test.sh +++ b/lib/tests/session-digest.test.sh @@ -182,5 +182,50 @@ check SD12-rc "$rc" 0 check SD12-banner "$(printf '%s' "$out" | grep -c 'make doctor')" 1 check SD12-no-digest "$(printf '%s' "$out" | grep -c 'memory digest:')" 0 +# mkhome <name> [json]: a HOME that links the real ~/.claude entries and +# holds the given memory.json (none when omitted); prints its path. +mkhome() { + local h="$WORK/home-$1" f + mkdir -p "$h/.claude" + for f in "$HOME"/.claude/*; do + [ "$(basename "$f")" = memory.json ] || ln -sf "$f" "$h/.claude/" + done + [ $# -lt 2 ] || printf '%s' "$2" > "$h/.claude/memory.json" + echo "$h" +} +digests() { grep -c 'memory digest:'; } +p=$(mkproj sd13); blk "$p" 1 open "Switched" + +# SD13: the memory switch. Only a boolean enabled:false cuts the digest. +check SD13a-enabled-false "$(cd "$p" && HOME=$(mkhome a '{"enabled": false}') \ + bash "$SS" <"$WORK/startup.json" 2>/dev/null | digests)" 0 +check SD13b-recall-false "$(cd "$p" && HOME=$(mkhome b '{"recall": false}') \ + bash "$SS" <"$WORK/startup.json" 2>/dev/null | digests)" 1 +check SD13c-malformed "$(cd "$p" && HOME=$(mkhome c '{"enabled": fal') \ + bash "$SS" <"$WORK/startup.json" 2>/dev/null | digests)" 1 +check SD13d-string-false "$(cd "$p" && HOME=$(mkhome d '{"enabled": "false"}') \ + bash "$SS" <"$WORK/startup.json" 2>/dev/null | digests)" 1 +check SD13e-absent "$(cd "$p" && HOME=$(mkhome e) \ + bash "$SS" <"$WORK/startup.json" 2>/dev/null | digests)" 1 +check SD13f-enabled-true "$(cd "$p" && HOME=$(mkhome f '{"enabled": true}') \ + bash "$SS" <"$WORK/startup.json" 2>/dev/null | digests)" 1 +check SD13g-not-an-object "$(cd "$p" && HOME=$(mkhome g '[1]') \ + bash "$SS" <"$WORK/startup.json" 2>/dev/null | digests)" 1 +# no jq: the switch is unreadable and the existing rule applies, no digest +# from a hook (stdin is not a terminal) +check SD13h-no-jq "$(cd "$p" && HOME=$(mkhome h '{"enabled": false}') \ + PATH="$bin" bash "$SS" <"$WORK/startup.json" 2>/dev/null | digests)" 0 + +# SD14: a foreign repository (gitflow.protect false) gets no digest +p=$(mkproj sd14); blk "$p" 1 open "Foreign" +git -C "$p" init -q +check SD14a-unset "$(run "$p" "$WORK/startup.json" | digests)" 1 +git -C "$p" config gitflow.protect true +check SD14b-true "$(run "$p" "$WORK/startup.json" | digests)" 1 +git -C "$p" config gitflow.protect false +check SD14c-false "$(run "$p" "$WORK/startup.json" | digests)" 0 +check SD14d-banner "$(run "$p" "$WORK/startup.json" | grep -c '^$')" \ + "$(run "$p" "$WORK/startup.json" | grep -c '^$')" + printf 'session-digest: %d passed, %d failed\n' "$pass" "$fail" [ "$fail" -eq 0 ] From 5a080b826724c992a27d5596e1978bae0c67d4d9 Mon Sep 17 00:00:00 2001 From: bchanot <chanot.bastien@gmail.com> Date: Fri, 6 Nov 2026 13:15:28 +0100 Subject: [PATCH 36/41] chore(settings): dark theme, switchModelsOnFlag moved by /config --- settings.json | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/settings.json b/settings.json index f907347..82709fe 100644 --- a/settings.json +++ b/settings.json @@ -556,6 +556,8 @@ "feedbackDrafts": "off", "effortLevel": "high", "autoMemoryEnabled": false, + "theme": "dark", + "switchModelsOnFlag": true, "remoteControlAtStartup": true, "inputNeededNotifEnabled": true, "skipAutoPermissionPrompt": true, @@ -612,6 +614,5 @@ "**Sensitive remote targets**: any namespace, host, database or container whose name carries `prod` or `production` as a whole word or name segment.", "**Sensitive data locations & audiences**: per-project `.env` files (gitignored) hold database, deploy and API credentials; some web projects store customer-submitted form data under a retention policy. Both are personal or client data — never send either to an external service." ] - }, - "switchModelsOnFlag": true + } } From d0ba68af0b931cab9e58479b650e17996a806439 Mon Sep 17 00:00:00 2001 From: bchanot <chanot.bastien@gmail.com> Date: Fri, 6 Nov 2026 14:05:56 +0100 Subject: [PATCH 37/41] =?UTF-8?q?chore(memory):=20LRN-263,=20LRN-264=20?= =?UTF-8?q?=E2=80=94=20capitalize?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .claude/memory/journal.md | 1 + .claude/memory/learnings.md | 10 ++++++++++ .claude/tasks/TODO.md | 3 ++- 3 files changed, 13 insertions(+), 1 deletion(-) diff --git a/.claude/memory/journal.md b/.claude/memory/journal.md index 98c89d7..b01d7b8 100644 --- a/.claude/memory/journal.md +++ b/.claude/memory/journal.md @@ -699,3 +699,4 @@ rules: ## 2026-11-06 - 2026-11-06: machine OOM reboot 2026-11-05 23:55 root-caused: detect_plan `claude config get planType` fork bomb via SessionStart (BLK-043), SD13 fake HOME trigger. /bugfix: 3 lenses → r2 (hotfix off main, worktree), GATE 0 MET, verifier ECARTS(1 SC2016) → CONFORME, security PASS ×2; 49aa2ff. BLK-044 open (oom_score_adj -1000). Merge + Part B pending. +- capitalize pre-compact: 2 learnings (hook never calls claude CLI; worktree ignored symlinks + diff3); TODO BLK-043 merge checked, Part B kept. 4c digest switch committed 4a7ce37. diff --git a/.claude/memory/learnings.md b/.claude/memory/learnings.md index 8b9a52e..9e22d3f 100644 --- a/.claude/memory/learnings.md +++ b/.claude/memory/learnings.md @@ -1956,3 +1956,13 @@ Rule: when editing a doctrine file under structure locks, grep the test's lock s - **Pattern**: a guard over shell command TEXT is never complete; plan challenges kept finding forms (r1: quote chars used as segment delimiters cut a quoted destination off its option; r2: multi-line quoted scripts split into orphan lines, wrappers hiding carriers, ssh value options, heredoc owner = last command on the line, here-strings read as heredocs, command substitutions cutting argv). Ship narrow: re-tokenize EVERY quoted word holding a blank (no carrier list), run the detector from every watched tool word, refuse unresolvable destinations, and put intent in an `autoMode.soft_deny` line for what text cannot show. - **Context**: extract-guard, feature/extract-guard 2026-11-05. awk traps found by the security gate: `index(substr(txt, i))` per quote/heredoc line = quadratic (1 MB → hook timeout → command RUNS, LRN-196); `RS="\001"` + `all = all $0` drops 0x01 bytes (comment desync); busybox awk slow on per-char appends (cap 64 KiB); the prefilter must run on a de-quoted copy or split tool names skip it. The accepted FP bit its author twice: a memory heredoc quoting a complete extraction command was refused, then the `<pkg> <dir>` placeholder too (angle brackets read as redirections) until placeholders were kept as words. - **Apply**: any PreToolUse text guard: prefilter on a de-quoted copy, size cap before parsing, linear tokenizer (forward scans), timed flood tests under gawk + mawk + busybox awk, fail closed only past the prefilter, MISSES in the header + soft_deny as net; text bodies about the guarded command go through Write + --body-file, never a heredoc in the Bash call. + +## LRN-263 — Hooks never invoke the claude CLI; hook-running tests stub it and cap tasks (2026-11-06) +- **Pattern**: hook (or lib a hook calls) never runs `claude` CLI. Removed subcommand (`claude config`) read as prompt → full session → its SessionStart hook re-runs → fork bomb (BLK-043). +- **Context**: `detect_plan` fallback `claude config get planType`, claude 2.1.318; 126 procs, 14 GiB, reboot. +- **Future use**: tests running hooks: PATH stub `claude` (log path expanded at creation, +x, positive control first), run under `systemd-run --user --scope -q -p TasksMax=N`. Grep hooks/lib for `claude <word>` in review. + +## LRN-264 — Fresh git worktree lacks gitignored symlinks; repo conflicts use diff3 markers (2026-11-06) +- **Pattern**: fresh `git worktree` lacks gitignored symlinks of main tree (`skills/darwin-skill`) → suites reading them go red (run-reconcile T6c): environment, not diff. Recreate link before blaming change. +- **Context**: hotfix worktree 2026-11-06; back-merge conflict used diff3 style. +- **Future use**: worktree setup → mirror ignored symlinks (`git status --ignored`). Conflict resolution here: strip `|||||||` base marker too, not only `<<<<<<<`/`=======`/`>>>>>>>`. diff --git a/.claude/tasks/TODO.md b/.claude/tasks/TODO.md index 906be29..211b521 100644 --- a/.claude/tasks/TODO.md +++ b/.claude/tasks/TODO.md @@ -120,7 +120,8 @@ Shared rules for every phase: - **4d feedback and promotion.** Plan r1 (draft, not challenged): `.claude/tasks/plans/2026-11-05-memory-feedback-4d-1834.md`. Log read 2026-11-05: 1 real record, no decision possible; it cannot show usefulness or misses alone and transcripts live 7 days. Order: 4d.1 log fields `cands` + `ms` → 4d.2 weekly reader (log × transcripts, labels.tsv) → 4d.3 gate (≥20 prompt + ≥10 tool injections, or 5 weeks) with thresholds fixed now → 4d.4 /prune-memory + BDR-100 promotion, conditional. Starts after the 4c merge; 4 open choices in the plan. - [ ] shortcut: the injection log lives under `l:<root>` store keys (about 28 KiB each, 200 records and 64 KiB at most); `sweepLogs` counts them with the `p:` keys and evicts the oldest log key (by its newest record, never the current root's) once the total nears the engine's 4 MiB store cap; upgrade = one global log key or a smaller per-root cap (`mods/memory/hooks/register.ts`). - [ ] residual: the pre-existing `memory.sh check` call in `hooks/session-start.sh` is not time-bounded (the digest's `memory.sh index blocker` call is); upgrade = wrap it in `timeout 2`. - - [ ] BLK-043 hotfix `49aa2ff` on hotfix/detect-plan-fork-bomb (worktree ../claude-hotfix-wt): merge on user signal (`gitflow finish` → main + develop), then `git worktree remove`; then Part B on this branch: suite-wide `claude` PATH stub + final empty-log check in `lib/tests/session-digest.test.sh` BEFORE SD13/SD14 run again (plan `.claude/tasks/plans/2026-11-06-detect-plan-fork-bomb-0030.md` r2). + - [x] BLK-043 hotfix merged 2026-11-06 (`bd5e661` main, `7e47bea` develop, back-merged into feature/memory-recall `3564e3e`, worktree removed). + - [ ] BLK-043 Part B: suite-wide `claude` PATH stub + final empty-log check in `lib/tests/session-digest.test.sh` (plan `.claude/tasks/plans/2026-11-06-detect-plan-fork-bomb-0030.md` r2). - [ ] shortcut (BLK-043 gate 2 LOWs): `lib/tests/detect-plan.test.sh` unchecked `mktemp -d` (empty WORK → real `claude probe`), `bash -c "source '$LIB'"` interpolation, no `GIT_CEILING_DIRECTORIES` on hook runs; and the memory, graphify-gate, push-guard suites run the hook with no `claude` stub. Upgrade = `|| exit 1` + `command -v claude` assert, positional args, ceiling dir, shared stub helper. - [ ] BLK-044: trace origin of `oom_score_adj=-1000` on claude processes; set `OOMScoreAdjust` on the `cc` scope so a runaway claude dies first. - Proof: recall precision on ≥20 real prompts and ≥10 real errors, target ≥ the 14/22 baseline; digest after a real compaction; redaction test on the ledger; `/context` delta; captured-failure demo: an error from session N recalled in session N+1. From 0da14d8bd8116d1c1b142871059669877df4abb7 Mon Sep 17 00:00:00 2001 From: bchanot <chanot.bastien@gmail.com> Date: Fri, 6 Nov 2026 14:38:49 +0100 Subject: [PATCH 38/41] chore(model-router): capitalize route confirmed (apply) --- mods/model-router/routing.json | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/mods/model-router/routing.json b/mods/model-router/routing.json index 7ac65a2..fba560d 100644 --- a/mods/model-router/routing.json +++ b/mods/model-router/routing.json @@ -201,7 +201,8 @@ "ship-feature": "plan", "deploy": "verify", "feat": "reflect", - "bugfix": "reflect" + "bugfix": "reflect", + "capitalize": "apply" } }, "changed": {}, From 2f45452ce19947d14021ab27d5dd47075413cce5 Mon Sep 17 00:00:00 2001 From: bchanot <chanot.bastien@gmail.com> Date: Fri, 6 Nov 2026 14:42:38 +0100 Subject: [PATCH 39/41] test(hooks): session-digest suite stubs the claude CLI (BLK-043 Part B) --- lib/tests/session-digest.test.sh | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/lib/tests/session-digest.test.sh b/lib/tests/session-digest.test.sh index 1149670..5176aa0 100644 --- a/lib/tests/session-digest.test.sh +++ b/lib/tests/session-digest.test.sh @@ -10,6 +10,19 @@ pass=0; fail=0 check() { if [ "$2" = "$3" ]; then pass=$((pass+1)); else fail=$((fail+1)); printf 'FAIL %s: got[%s] want[%s]\n' "$1" "$2" "$3"; fi; } +# Stub claude (BLK-043): a hook run that calls the CLI logs a line here +# instead of starting a session that re-runs this hook. +CLAUDE_LOG="$WORK/claude.log"; : >"$CLAUDE_LOG" +mkdir -p "$WORK/stub" +printf '#!/bin/sh\necho "$*" >>"%s"\n' "$CLAUDE_LOG" >"$WORK/stub/claude" +chmod +x "$WORK/stub/claude" +export PATH="$WORK/stub:$PATH" +calls() { wc -l <"$CLAUDE_LOG" | tr -d ' '; } +# SD0: positive control, the stub is reached through PATH +claude probe +check SD0-stub-reached "$(calls)" 1 +: >"$CLAUDE_LOG" + # mkproj <name> -> path with an empty memory dir mkproj() { mkdir -p "$WORK/$1/.claude/memory" "$WORK/$1/.claude/tasks" @@ -227,5 +240,8 @@ check SD14c-false "$(run "$p" "$WORK/startup.json" | digests)" 0 check SD14d-banner "$(run "$p" "$WORK/startup.json" | grep -c '^$')" \ "$(run "$p" "$WORK/startup.json" | grep -c '^$')" +# SD15: no hook run of this suite called the claude CLI (BLK-043) +check SD15-no-claude-calls "$(calls)" 0 + printf 'session-digest: %d passed, %d failed\n' "$pass" "$fail" [ "$fail" -eq 0 ] From 34e726ae4454744715db4815e165b931bd3aff24 Mon Sep 17 00:00:00 2001 From: bchanot <chanot.bastien@gmail.com> Date: Fri, 6 Nov 2026 14:43:02 +0100 Subject: [PATCH 40/41] =?UTF-8?q?chore(memory):=20journal=20=E2=80=94=20ho?= =?UTF-8?q?tfix=20BLK-043=20Part=20B=20session-digest=20stub?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .claude/memory/journal.md | 1 + .claude/tasks/TODO.md | 4 ++-- ...6-11-06-session-digest-claude-stub-1439.md | 22 +++++++++++++++++++ 3 files changed, 25 insertions(+), 2 deletions(-) create mode 100644 .claude/tasks/contracts/2026-11-06-session-digest-claude-stub-1439.md diff --git a/.claude/memory/journal.md b/.claude/memory/journal.md index b01d7b8..7e2149c 100644 --- a/.claude/memory/journal.md +++ b/.claude/memory/journal.md @@ -700,3 +700,4 @@ rules: ## 2026-11-06 - 2026-11-06: machine OOM reboot 2026-11-05 23:55 root-caused: detect_plan `claude config get planType` fork bomb via SessionStart (BLK-043), SD13 fake HOME trigger. /bugfix: 3 lenses → r2 (hotfix off main, worktree), GATE 0 MET, verifier ECARTS(1 SC2016) → CONFORME, security PASS ×2; 49aa2ff. BLK-044 open (oom_score_adj -1000). Merge + Part B pending. - capitalize pre-compact: 2 learnings (hook never calls claude CLI; worktree ignored symlinks + diff3); TODO BLK-043 merge checked, Part B kept. 4c digest switch committed 4a7ce37. +- 2026-11-06: BLK-043 Part B /hotfix 2f45452: session-digest suite stubs claude CLI (SD0 control, SD15 zero calls), 53/53 under TasksMax=256, security PASS (MEDIUM stub-first-on-PATH queued in TODO shortcut). 4c merge pending user. diff --git a/.claude/tasks/TODO.md b/.claude/tasks/TODO.md index 211b521..a2f03d2 100644 --- a/.claude/tasks/TODO.md +++ b/.claude/tasks/TODO.md @@ -121,8 +121,8 @@ Shared rules for every phase: - [ ] shortcut: the injection log lives under `l:<root>` store keys (about 28 KiB each, 200 records and 64 KiB at most); `sweepLogs` counts them with the `p:` keys and evicts the oldest log key (by its newest record, never the current root's) once the total nears the engine's 4 MiB store cap; upgrade = one global log key or a smaller per-root cap (`mods/memory/hooks/register.ts`). - [ ] residual: the pre-existing `memory.sh check` call in `hooks/session-start.sh` is not time-bounded (the digest's `memory.sh index blocker` call is); upgrade = wrap it in `timeout 2`. - [x] BLK-043 hotfix merged 2026-11-06 (`bd5e661` main, `7e47bea` develop, back-merged into feature/memory-recall `3564e3e`, worktree removed). - - [ ] BLK-043 Part B: suite-wide `claude` PATH stub + final empty-log check in `lib/tests/session-digest.test.sh` (plan `.claude/tasks/plans/2026-11-06-detect-plan-fork-bomb-0030.md` r2). - - [ ] shortcut (BLK-043 gate 2 LOWs): `lib/tests/detect-plan.test.sh` unchecked `mktemp -d` (empty WORK → real `claude probe`), `bash -c "source '$LIB'"` interpolation, no `GIT_CEILING_DIRECTORIES` on hook runs; and the memory, graphify-gate, push-guard suites run the hook with no `claude` stub. Upgrade = `|| exit 1` + `command -v claude` assert, positional args, ceiling dir, shared stub helper. + - [x] BLK-043 Part B: suite-wide `claude` PATH stub + final empty-log check in `lib/tests/session-digest.test.sh` (SD0/SD15, done 2026-11-06 via /hotfix; security PASS, MEDIUM folded into the shortcut below). + - [ ] shortcut (BLK-043 gate 2 LOWs): `lib/tests/detect-plan.test.sh` unchecked `mktemp -d` (empty WORK → real `claude probe`), `bash -c "source '$LIB'"` interpolation, no `GIT_CEILING_DIRECTORIES` on hook runs; and the memory, graphify-gate, push-guard suites run the hook with no `claude` stub. Upgrade = `|| exit 1` + `command -v claude` assert, positional args, ceiling dir, shared stub helper. Same gap in `lib/tests/session-digest.test.sh` SD0 (gate MEDIUM 2026-11-06): `claude probe` runs before any check that the stub is first on PATH (stub write failure or noexec TMPDIR → real CLI), a red SD0 does not stop the suite; LOW: log path interpolated into the generated stub unquoted. - [ ] BLK-044: trace origin of `oom_score_adj=-1000` on claude processes; set `OOMScoreAdjust` on the `cc` scope so a runaway claude dies first. - Proof: recall precision on ≥20 real prompts and ≥10 real errors, target ≥ the 14/22 baseline; digest after a real compaction; redaction test on the ledger; `/context` delta; captured-failure demo: an error from session N recalled in session N+1. diff --git a/.claude/tasks/contracts/2026-11-06-session-digest-claude-stub-1439.md b/.claude/tasks/contracts/2026-11-06-session-digest-claude-stub-1439.md new file mode 100644 index 0000000..6c3f8fb --- /dev/null +++ b/.claude/tasks/contracts/2026-11-06-session-digest-claude-stub-1439.md @@ -0,0 +1,22 @@ +# CONTRACT — session-digest-claude-stub +- date: 2026-11-06 | flow: hotfix | branch: feature/memory-recall +- status: active + +## REQUEST (verbatim — IMMUTABLE) +BLK-043 Part B on feature/memory-recall: in lib/tests/session-digest.test.sh add a suite-wide PATH stub for `claude` (log path expanded at creation, chmod +x, positive control first: call `claude` via PATH, assert 1 logged line), then a final cumulative check that the stub log has no line from any hook run of the suite. Plan: .claude/tasks/plans/2026-11-06-detect-plan-fork-bomb-0030.md r2 (R2, R5, R6: first run under `systemd-run --user --scope -q -p TasksMax=256`). Single test file. + +## CLARIFICATIONS +Q: safety / A: every run of the suite goes through `systemd-run --user --scope -q -p TasksMax=256`; never run the real `claude` CLI. [gated 2026-11-06] + +## ACCEPTANCE CRITERIA +1. Stub present, reached, and hook runs log no call; suite green, contained. + CHECK: cd /home/bchanot/Documents/claude && systemd-run --user --scope -q -p TasksMax=256 bash lib/tests/session-digest.test.sh >/home/bchanot/.cache/claude-tmp/claude-1000/-home-bchanot-Documents-claude/049658c4-3f30-4849-8ba6-906177262d8a/scratchpad/sd.out 2>&1 && grep -q 'failed$' /home/bchanot/.cache/claude-tmp/claude-1000/-home-bchanot-Documents-claude/049658c4-3f30-4849-8ba6-906177262d8a/scratchpad/sd.out && echo C1_GREEN + EXPECT: C1_GREEN +2. The stub is written with the log path expanded at creation, `chmod +x`, exported on PATH before the first case; a positive control (SD0) asserts 1 logged line; the log is then emptied; a final check (SD15) after all cases asserts 0 lines. + (judged from the suite source) +3. shellcheck clean. + CHECK: cd /home/bchanot/Documents/claude && shellcheck lib/tests/session-digest.test.sh && echo C3_LINT + EXPECT: C3_LINT + +## FILE SCOPE +- lib/tests/session-digest.test.sh From e941973df150a301389eb44dc68e26570efe2718 Mon Sep 17 00:00:00 2001 From: bchanot <chanot.bastien@gmail.com> Date: Fri, 6 Nov 2026 15:23:28 +0100 Subject: [PATCH 41/41] chore: purge transient planning artifacts (BDR-065) --- .../plans/2026-11-04-memory-recall.md | 273 ------------------ .../specs/2026-11-04-memory-recall-design.md | 179 ------------ 2 files changed, 452 deletions(-) delete mode 100644 docs/superpowers/plans/2026-11-04-memory-recall.md delete mode 100644 docs/superpowers/specs/2026-11-04-memory-recall-design.md diff --git a/docs/superpowers/plans/2026-11-04-memory-recall.md b/docs/superpowers/plans/2026-11-04-memory-recall.md deleted file mode 100644 index cba54ba..0000000 --- a/docs/superpowers/plans/2026-11-04-memory-recall.md +++ /dev/null @@ -1,273 +0,0 @@ -# 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. - -## 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: -- `boot` in register.test.ts gains one `process.run` bottom driven by a World field (default: a literal `memory.sh index` stdout 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). -- `parseIndex` returns `Map<id, {status, title}>`; titles come from memory.sh (fence-aware, tag and date stripped), `entriesOf` only splits bodies (heading regex = 4b `HEADING` widened to `BDR|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 their `index:` line unchanged; recall passes the three files (simp 3). -- Status unavailable: `memory_pending` still labels NEW/known from all entries (advisory), with `status reader unavailable` on the `index:` line; injections stay off (rob 7). -- A real-registry check in the test (skipped when the repo files are absent): the `entriesOf` IDs equal the `parseIndex` IDs 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.run` is 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 `spent` resets 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.SessionStart` hook on `startup | clear | compact` (not `session.start`); `resume` changes nothing; a `classic.SessionStart` carrying `agent_id` resets only that agent's key; `session.end` clears by the ending session's id only; keys use `$.session.id()` (corr 9, simp 4). -- A missing `lastPrompt` means not idle (rob 10). -- Check-and-record of `seen`/`spent` run synchronously after the last await; test: two concurrent failing Bash calls → one injection (rob 9). -- The log: `saveProject` persists `log`; 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 `enabled` key with `"recall": false` logs nothing; only a present non-boolean logs (corr 6). - -Task 4b — trigger and rerank: -- Registries load once per `prompt.submit` and 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 |`, status `open` listed, `upstream` counted), NOT `reconcile_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 -c` checked 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 (no `sdk-*` sessions); the walk reuses `noise.py`'s `pairs_of`/`find_files` logic as reference (ported in TS, the source named). -- haiku runs from a `mktemp -d` cwd with `--setting-sources local`, no tools; latency from the JSON `duration_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 `log` seeded 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 `entriesOf` IDs == `parseIndex` IDs check runs in a shell suite (a new case in `lib/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 reads `known BLK-001` and the `index:` line ends `status 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.SessionStart` as the context-start site, titles from memory.sh, digest from `memory.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; `loadRegistries` and the harness both use it; the harness imports also `recallLine`. -- **Digest tests (conf 5, 6, 7, 8).** SD9 = a copy of the script beside a fake `lib/memory.sh` that exits 2, then one that prints malformed rows, and a `blockers.md` that 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-8` succeeds); no `cut -c`. Without `timeout` or `jq`: 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.run` World field, never add a second bottom; the test at register.test.ts ~885 (expects `known LRN-002` after editing the file to open) sets its own stdout with LRN-002 open. -- **Errno phrase (conf 11).** `deErrno` runs on the lowercased line BEFORE `normalize`'s PATH step for `input/output error` only (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`/`saveProject` untouched. -- **/clear event (conf 13).** Task 10's interactive check includes a `/clear` then an ordinary prompt: the transcript shows one `memory recall:` on it; the context-start key uses the event's `session_id` when present, else `$.session.id()`. If `clear` never 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.complete` gets `{model, prompt, maxTokens, effort}` only if the d.ts does not type `timeoutMs` (check the d.ts; the own 3 s race stays either way); the TODO `shortcut:` tick is in Task 9; `isTrigger`, `IDLE_MS`, `DESIGN_RULE`, `ANALYSIS_RULE` are produced by 4b. diff --git a/docs/superpowers/specs/2026-11-04-memory-recall-design.md b/docs/superpowers/specs/2026-11-04-memory-recall-design.md deleted file mode 100644 index 30e8c87..0000000 --- a/docs/superpowers/specs/2026-11-04-memory-recall-design.md +++ /dev/null @@ -1,179 +0,0 @@ -# Phase 4c memory recall — design (2026-11-04) - -BDR-125 phase 4c, host `mods/memory` (BDR-137). Contract -`.claude/tasks/contracts/2026-11-04-memory-recall-1859.md` (brainstorm answers -0-11 `[gated 2026-11-04]`). Engine facts: -`.claude/tasks/plans/2026-11-04-memory-recall-spike/REPORT.md` (CLI 2.1.318). -Branch `feature/memory-recall`. - -## Goal -The registries hold the lessons; nothing brings them back when they matter. -4c brings back the right entries at three moments, without noise: when a -design or analysis prompt starts work, when a known error comes back, and at -the start of every context. Writing is untouched (4b capture, memory.sh). -Success: precision of the injected entries at or above the 14/22 baseline -(64 %), the error channel's noise measured before shipping, a digest seen -after a real compaction. - -## Unit 1 — shared reader (register.ts) -- Status and titles: `lib/memory.sh -C <root> index` through `$.process.run(['bash', - <HOME>/.claude/lib/memory.sh, '-C', root, 'index'], {timeoutMs: 2000})`, - raced by an own 2.5 s timer; rows `| ID | Date | Title | Status |`. memory.sh - is the single reader (BDR-129): `parseIndex` returns `Map<id, {status, - title}>`, the title already fence-aware with tag and date stripped, and an ID - is closed for recall when its status word is `superseded` or `deprecated`. - An ID absent from a map that exists is not live (fail closed). The script - path is `$HOME/.claude/lib/memory.sh`. The run is skipped when no registry - file was read. -- Status unavailable (failed, timed out or malformed read): `memory_pending` - still labels each failure `NEW` or `known <ID>` from ALL entries (advisory, - superseded ones included) and its `index:` line ends `status reader - unavailable`; recall and the error channel inject nothing. -- Entries: `decisions.md`, `learnings.md`, `blockers.md` read with `$.fs.read` - (stat first, 4 MiB cap per file). `entriesOf` only splits bodies (heading - regex = the 4b one widened to `BDR|LRN|BLK`, no title capture); the pure - `assembleEntries(texts, index)` joins kind, the memory.sh title cut at 100 - with `…`, the lesson and the body into `{id, kind, title, lesson, body}`. - 4b callers load `blockers.md` and `learnings.md` only. -- Lesson line: BDR the `Decision` field; LRN `Apply`, else `Future - application`, else `Pattern`; BLK `Solution`, else `Real cause` (label match - case-insensitive, bold or plain); its first sentence, cut at 280 chars with - `…`; none → empty lesson (title only). Label and heading regexes carry - bounded prefixes (`.{0,2000}`, `[^\n]{0,300}`), no `$`. -- The 4b lexical `isSuperseded` and its `shortcut:` comment are gone: the error - index takes its live set from the same status map. - -## Unit 2 — intent recall (`prompt.submit`) -- Trigger: origin `composer`, `turnId` absent, not a slash command (text not - starting `/`), ≥ 12 code points, and at least 5 content words (tokens minus - the stop-word list; measurement gate 2026-11-05, `MIN_CONTENT_WORDS`), and - one of: the first such prompt of the context (set at `session.start` and - consumed by the first qualifying prompt; a new context starts through the - classic `SessionStart` hook on source `startup`, `clear` or `compact`, keyed - by the event's `session_id` when present, else `$.session.id()`); the first - after ≥ 30 min without a composer prompt in this session; a match of the - design or analysis keyword patterns, copied from model-router's default - prompt rules (`mods/model-router/hooks/register.ts`, commit 9bbd1d5): - `plan|planifie|planning|brainstorm|architecture|con[cç]ois|design` and - `pourquoi|why|explique|explain|analyse|analyze|comprendre|understand|review|audit`, - same word boundaries. -- Rank: BM25 (k1 1.2, b 0.75) over title + lesson + body of the live - BDR/LRN/BLK entries, tokens = lowercase letter/digit runs of ≥ 2 chars minus - a short FR+EN stop-word list; the query is the prompt's first 2000 chars, - redacted (4b `redact`). Entries already injected in this context are - removed before ranking. Top 30 with a score > 0. -- Rerank: `$.model.complete({model: 'claude-haiku-5-5', effort: 'low', - maxTokens: 64, timeoutMs: 5000, prompt})`, raced by an own 5 s timer - (`RERANK_MS`; measurement gate 2026-11-05: 29 % of calls ran over 3 s) - (LRN-218). The prompt: the redacted query, the candidates one per line as - `ID | title | lesson`, and the instruction to answer at most 3 IDs, comma - separated, or `none`. The answer is parsed for `(BDR|LRN|BLK)-\d+`, kept - only when the ID is a candidate, at most 3, order kept. -- Inject: one context block `memory recall:` then one line per entry - `<ID> <title ≤ 100> — <lesson>`; the block ≤ 1500 chars (an entry that - would overflow is dropped). No candidate, a `none`, a timeout, a refusal or - any error → nothing attached, the prompt passes unchanged. -- The 4b milestone note on the same prompt is attached first; recall follows. - -## Unit 3 — tool-error recall (Bash `tool.call`) -- After the 4b capture (same failure rule, same redacted line): the failure's - key is matched against the error index (live BLK/LRN, Unit 1); a match whose - ID was not injected in this context attaches `memory: known <ID> <title ≤ - 100> — <lesson>` to the tool answer's `context` (the answer keeps its shape, - LRN-205; spike: the model sees it). -- Common phrases: before gramming, both the entry spans and the failure key - replace each errno phrase by the placeholder `<errno>`; a gram made only of - placeholders is skipped (LRN-258, `<errno>` joins `#`, `<path>`, `<hex>`). - Phrases: no such file or directory, permission denied, command not found, - is a directory, not a directory, file exists, directory not empty, - operation not permitted, no space left on device, connection refused, - connection timed out, broken pipe, resource temporarily unavailable, - invalid argument, too many open files, read-only file system, device or - resource busy, input/output error. -- Main loop and sub-agents (the context key carries the agent id). - -## Unit 4 — ledger, budget, log -- Once per context: `st.seen: Map<contextKey, Set<ID>>`, key = session id + - (`agentId` or `main`); cleared at `session.end`, and the session's keys on - `classic.SessionStart` source `clear` or `compact`. -- Budget: the main loop has 1500 chars per turn, shared by both channels, - reset by each composer prompt; a sub-agent (error channel only) has 1500 - chars for its whole context. -- Log: each injection appends `{at, session, agent, channel: 'prompt' | - 'tool', ids}` to its own store key `l:<root>` (≤ 200 records, ≤ 64 KiB, - oldest dropped), outside the session sweep and the project value; never - displayed; 4d reads it. No cross-root cap (TODO `shortcut:`). - -## Unit 5 — session digest (`hooks/session-start.sh`) -- Reads the hook JSON from stdin only when stdin is not a terminal, with - `timeout 1`; `source` taken with jq. Prints the digest for `startup`, - `clear`, `compact`, and for an empty source (a manual run); never for - `resume`. Without `timeout` or `jq` the source is unknowable: the digest - prints only when stdin is a terminal, never from a hook. -- Only in a project whose git toplevel (else cwd) has `.claude/memory/`: - `memory digest:` then up to four kinds of lines: - open BLK from `memory.sh -C <root> index blocker` (run under `timeout 2`, - rows with status word `open`: `- open: BLK-n title`, ≤ 160 chars each, at - most 3, then `+N more`), the upstream ones counted (`+N upstream`); the first - 3 unchecked `- [ ]` items under `### Actionable` in `.claude/tasks/TODO.md` - (≤ 160 chars each); the last `- ` line of `.claude/memory/journal.md` - (≤ 160 chars). Cuts use bash `${v:0:159}…` and stay valid UTF-8. -- Block ≤ 800 chars. Header, BLK lines, the count line and the journal line - always stay; TODO lines are added in order while they fit, so under the cap - they drop first, whole lines, never a mid-line cut. Any missing file or - section → that line is omitted; nothing to show → no block. Fail silent: a - `memory.sh` that fails, hangs, prints malformed rows or a `blockers.md` that - is a directory never changes the banner or the exit code. -- No SubagentStart twin. - -## Unit 6 — `memory_pending` -Milestones of the earlier stored sessions follow the current session's, -marked `(earlier session)`, same 3-session window; the answer order stays -header, `index:`, milestones, failures. - -## Unit 7 — off switch -`~/.claude/memory.json`: `"enabled": false` cuts everything (4b); -`"recall": false` cuts Units 2 and 3 injections only (capture, the note, the -tool and the log of past injections stay). Read like `enabled` (lazily per -session, a non-boolean logs one line and counts as absent). - -## Docs -README / USAGE (fr) memory sections gain recall, the error channel, the -digest, `"recall": false`, the residuals; CHANGELOG `[Unreleased]`; TODO (4c -ticked at merge, 4d stays deferred with the log now in place). - -## Proof -- Kit tests: reader (status map, lesson per kind, failure → fail open), - trigger (first prompt, idle, keyword, slash and mid-turn excluded), BM25 - order on fixtures, rerank parse (foreign IDs dropped, `none`, timeout, never - settles), budget and once-per-context (reset on compact/clear and - session.end), error channel (known match attaches, ENOENT does not, sub-agent - key), earlier milestones, `recall: false`, log cap; regex costs timed on - 64 KiB (LRN-259). -- Shell suite: the digest on fixture projects (sources, missing files, caps, - `</dev/null`), existing session-start callers unchanged. -- Measured before shipping (LRN-261, EVAL-056): a bun harness under - `.claude/tasks/plans/2026-11-04-memory-recall-spike/` imports the mod's own - functions (no port) and calls haiku through `claude -p --model haiku`: - (a) 20 real composer prompts from 14 days of this repo's transcripts that - meet the trigger: injected IDs per prompt, timeout share at the bound; the - controller labels each injected entry relevant or not, the user checks the - labels; bar: relevant share ≥ 64 % (14/22). (b) the 14-day Bash failure - replay: injections per session and the noise share on the injected ones, - ENOENT lines included. Counts and shares only in the committed notes. -- Live: headless `-p` for the error channel (a failing command matching a - fixture BLK attaches the line); interactive by the user for recall (a design - prompt in a fresh session), and the digest after a real `/compact`. - -## Measurement gates (2026-11-05) -`.claude/tasks/plans/2026-11-04-memory-recall-spike/RECALL.md`: on 14 days of -transcripts the rerank precision is 54 to 61 % against the 64 % bar. Decided: -recall ships on and switchable (`"recall": false`), with a content floor (5 -content words, Unit 2) and `RERANK_MS` 5000 (Unit 2); the injection log feeds -4d. Error channel: n = 3, insufficient sample. - -## Out of scope -Read path triggers, Bash command triggers, critical deny-once, Tier 1, -cross-repo index, `memory_search` tool, reading the router's classifier -label, a SubagentStart twin, injection citation tracking (4d), EVAL in the -recall corpus.