forked from bchanot/claude
docs: memory recall facts after the final review
This commit is contained in:
1 parent
2397c36f06
commit
cea9f6a7b9
3 files changed
+7
-7
No files matched your search
@@ -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.
|
||||
|
||||
|
||||
@@ -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`).
|
||||
|
||||
@@ -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`).
|
||||
|
||||
Reference in new issue
Block a user