From cea9f6a7b977afe7b12fddf117c7ce3653ab8106 Mon Sep 17 00:00:00 2001 From: bchanot Date: Thu, 5 Nov 2026 18:21:46 +0100 Subject: [PATCH] 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:`); 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:` 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:` 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 `@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-.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:`) are swept at 1 MiB; log keys (`l:`) 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-.json`, an engine layout, not fixed by this repo); delete it to wipe the captures. - Note: one context line, `memory: