docs: memory capture after the final review

This commit is contained in:
bchanot committed 2026-11-04 14:05:06 +01:00
1 parent c81a7a2132
commit a4d29ea9f2
6 files changed
+11 -9

No files matched your search

+1
View File
@@ -114,6 +114,7 @@ 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); merge pending (gates, review, user go)
- 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.
- **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.
- 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.
@@ -93,4 +93,4 @@ the user decides (it amends gated answer 2, the capture rule):
Option A accepted by the user at the gate. Implemented as `ERRORISH` in
`failureLine` (`mods/memory/hooks/register.ts`): contract answer 2-amended
and criterion 15. `noise.py --tighten errorish` reproduces the shipped rule.
and criterion 15. `noise.py --tighten errorish` approximates the shipped rule: it has no letter test, which `failureLine` also applies.
+2 -2
View File
@@ -156,13 +156,13 @@ Limits: a main-loop switch re-reads cold the part of the context the target mode
`mods/memory/` is a second Claude Code mod. It watches Bash failures and milestones so that `/capitalize` starts from what really happened, not from recollection. Writing a registry stays a model draft, your approval and `lib/memory.sh`; the mod never writes one.
- Records: a Bash result whose text starts `Exit code N` and whose last line (the first line, the rtk trailer and letterless lines dropped) is an error line. That line must also be error-shaped: it holds 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, Bearer tokens and `user:pass@` URLs. Permission refusals, guard redirects and tool_use errors are never captured. A sub-agent failure is marked `(sub-agent)`.
- 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, `curl -u user:pass` and `--password`. 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; 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`.
- 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)`.
- Residuals: cross-process writes are unverified (two concurrent sessions: last writer wins). Non-Bash failures are not captured. The superseded reader is lexical (header tag or last labelled status line). 40-hex Gitea tokens are kept by design, they look like SHAs, and `Authorization: token ...` is not caught. 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. The superseded reader is lexical (header tag or last labelled status line). 40-hex Gitea tokens are kept by design, they look like SHAs, are not caught. 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`).
---
+1 -2
View File
@@ -212,8 +212,7 @@ Le mod `mods/memory/` note les échecs Bash et les jalons de la session pour que
- 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`.
- 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)`.
- 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. Le lecteur « remplacé » est lexical (étiquette d'en-tête ou dernière ligne de statut étiquetée). Les jetons Gitea de 40 hex sont gardés volontairement (ils ressemblent à des SHA) et `Authorization: token ...` n'est pas attrapé. 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. Le lecteur « remplacé » est lexical (étiquette d'en-tête ou dernière ligne de statut étiquetée). Les jetons Gitea de 40 hex sont gardés volontairement (ils ressemblent à des SHA) ne sont pas attrapés. 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
+2 -1
View File
@@ -104,7 +104,8 @@ AskUserQuestion:
uncommitted for a later run.
- `edit <n>` → re-dispatch `commit-changer` with `MODE: propose` and the
user's correction for step N folded into the prompt (plus the "Captured
this session" block, as in STEP 1), so all grouping /
this session" block: reuse the same captured block from STEP 1, do not
call the tool again), so all grouping /
message judgment stays on the dispatched propose mode (`model="opus"`,
BDR-077 — never redrawn inline on the session model); show the redrawn
plan and re-ask.
+4 -3
View File
@@ -229,9 +229,10 @@ Hotfixes are often trivial (typo, config, import) — skip by default. But if th
- Bug that cost real time to locate despite being "superficial" → propose `BLK-XXX` in `.claude/memory/blockers.md` (status: resolved).
Default behaviour: `CAPITALIZE: hotfix trivial, skip` (no prompt, no output).
Exception: when memory_pending (per /capitalize STEP 1 "Captured first")
returns a `NEW` failure of the current session not marked `(sub-agent)`,
propose that one blocker draft through the same gate.
Exception: call memory_pending first (per /capitalize STEP 1 "Captured
first"); tool unavailable → the default behaviour above. When it returns a
NEW failure of the current session not marked (sub-agent), propose one
blocker draft per such failure through the same gate.
Ask the user only when there is an actual candidate to propose.
Always append a 1-line journal entry (even trivial hotfix — journal is timeline, not signal) and any approved BLK/LRN per `lib/capitalize-commit.md` § WRITE.