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
@@ -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
|
||||
|
||||
Reference in new issue
Block a user