docs: memory recall, known-error line and session digest
This commit is contained in:
1 parent
3261a919c2
commit
2a0d73da12
8 files changed
+84
-48
No files matched your search
@@ -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
|
||||
|
||||
+2
-2
@@ -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.
|
||||
@@ -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`.
|
||||
|
||||
@@ -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`).
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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"
|
||||
}
|
||||
|
||||
@@ -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
|
||||
|
||||
Reference in new issue
Block a user