From e31baf669cab9a28cb0ce36bf19e7c2f9ef181be Mon Sep 17 00:00:00 2001 From: bchanot Date: Wed, 4 Nov 2026 12:07:20 +0100 Subject: [PATCH] feat(memory): memory_pending tool with the registry error index --- mods/memory/hooks/register.test.ts | 257 ++++++++++++++++++++++++++++- mods/memory/hooks/register.ts | 226 ++++++++++++++++++++++++- 2 files changed, 477 insertions(+), 6 deletions(-) diff --git a/mods/memory/hooks/register.test.ts b/mods/memory/hooks/register.test.ts index e728267..3768c2f 100644 --- a/mods/memory/hooks/register.test.ts +++ b/mods/memory/hooks/register.test.ts @@ -3,6 +3,7 @@ import type { Engine, MockClock } from 'claude-code/testing' import type { On } from 'claude-code' import { cap, tail, redact, normalize, failureLine, sessionOf, addFailure, + entriesOf, isSuperseded, grams, buildIndex, matchOf, readRegistry, } from './register' const HOME = '/home/t' @@ -14,6 +15,7 @@ type World = { switchText: string | undefined // ~/.claude/memory.json (undefined: absent) rootFails: boolean // session.root rejects id: string // what session.id answers now + root: string // what session.root answers now answer: unknown // what the Bash bottom answers now byCommand: Map // answers that depend on the command clock: MockClock @@ -21,6 +23,7 @@ type World = { sets: string[] // every store key written logs: string[] // every $.ui.log line tools: string[] // every tool name registered + files: Map // other files (null: a directory) } type Opts = { @@ -28,6 +31,7 @@ type Opts = { rootFails?: boolean seed?: Record // the store at the start storeFails?: boolean // store.set rejects (a hand-made store) + files?: Record // registries under the root } /** @@ -51,10 +55,12 @@ function handStore(on: On, w: World, fails: boolean): void { async function boot($: Engine, on: On, o: Opts = {}): Promise { const clock = mock.clock(on, { now: 1000 }) const w: World = { - switchText: o.switchText, rootFails: o.rootFails ?? false, id: 's1', + switchText: o.switchText, rootFails: o.rootFails ?? false, + id: 's1', root: ROOT, answer: BASH_ANSWER, byCommand: new Map(), clock, kv: new Map(Object.entries(o.seed ?? {})), sets: [], logs: [], tools: [], + files: new Map(Object.entries(o.files ?? {})), } handStore(on, w, o.storeFails ?? false) on('tool.register', (_a, e) => { @@ -63,6 +69,13 @@ async function boot($: Engine, on: On, o: Opts = {}): Promise { }) on('env.get', () => ({ value: HOME })) on('fs.stat', (_a, e) => { + if (w.files.has(e.path)) { + const text = w.files.get(e.path) + return { value: { + kind: text === null ? 'dir' as const : 'file' as const, + size: text?.length ?? 0, mtimeMs: 0, isLink: false, + } } + } if (e.path !== SWITCH || w.switchText === undefined) { throw new Error('ENOENT') } @@ -72,6 +85,7 @@ async function boot($: Engine, on: On, o: Opts = {}): Promise { } } }) on('fs.read', (_a, e) => { + if (w.files.has(e.path)) return { value: w.files.get(e.path) ?? '' } if (e.path !== SWITCH || w.switchText === undefined) { throw new Error('ENOENT') } @@ -79,7 +93,7 @@ async function boot($: Engine, on: On, o: Opts = {}): Promise { }) on('session.root', () => { if (w.rootFails) throw new Error('no root') - return { value: ROOT } + return { value: w.root } }) on('session.id', () => ({ value: w.id })) on('session.start', (_a, e) => ({ cwd: e.cwd })) @@ -490,3 +504,242 @@ test('addFailure: same key counts, a new key appends', () => { addFailure(s, f('y')) expect(s.failures.map(x => [x.key, x.count])).toEqual([['x', 2], ['y', 1]]) }) + +// ---- the registry index and memory_pending ---------------------------- + +const REG = `${ROOT}/.claude/memory` +const BLK = `${REG}/blockers.md` +const LRN = `${REG}/learnings.md` +const BLOCKERS = '## BLK-001 \u2014 x\n- **Status**: open\n' + + 'seen: `fatal: unable to access remote`\n' +const LEARNINGS = '## LRN-002 \u2014 y\n- **Status**: superseded\n' + + 'old: `error: pathspec did not match anything`\n' +const REGS = { [BLK]: BLOCKERS, [LRN]: LEARNINGS } +const PENDING = 'mcp__memory__memory_pending' + +const pending = async ($: Engine): Promise => + String(((await $.tool.call({ tool: PENDING })) as { result: unknown }) + .result) + +test('IDX1: a captured line the registry holds reads known BLK-001', async ( + $, on, +) => { + const w = await boot($, on, { files: REGS }) + await failing($, w, EXIT1 + 'fatal: unable to access remote host', 'git pull') + expect(await pending($)).toBe([ + 'memory_pending (project app, 1 session(s))', + 'index: read blockers.md, learnings.md', + 'failures:', + '- known BLK-001 \u00d71 fatal: unable to access remote host' + + ' \u2014 command: git pull', + ' excerpt: Exit code 1\u23cefatal: unable to access remote host', + ].join('\n')) +}) + +test('IDX2: an unrelated line reads NEW', async ($, on) => { + const w = await boot($, on, { files: REGS }) + await failing($, w, EXIT1 + 'completely different problem happened') + expect(await pending($)).toContain('- NEW \u00d71 completely different') +}) + +test('IDX3: a line matching only a superseded LRN reads NEW', async ( + $, on, +) => { + const w = await boot($, on, { files: REGS }) + await failing($, w, EXIT1 + 'error: pathspec did not match anything') + expect(await pending($)).toContain('- NEW \u00d71 error: pathspec') +}) + +test('IDX4: no registry files, every failure NEW, both named', async ( + $, on, +) => { + const w = await boot($, on) + await failing($, w, EXIT1 + 'fatal: unable to access remote host') + const text = await pending($) + expect(text).toContain( + 'index: skipped blockers.md (missing), learnings.md (missing)') + expect(text).toContain('- NEW \u00d71') +}) + +test('IDX5: an empty store answers nothing captured', async ($, on) => { + await boot($, on) + expect(await pending($)).toBe('memory_pending: nothing captured') +}) + +test('IDX6: the tool is not registered when disabled, and says off', async ( + $, on, +) => { + const w = await boot($, on, { switchText: '{"enabled": false}' }) + expect(w.tools).toEqual([]) + expect(await pending($)) + .toBe('memory capture is off (~/.claude/memory.json)') +}) + +test('IDX7: the answer holds no unredacted runtime-built token', async ( + $, on, +) => { + const w = await boot($, on) + const token = 'gh' + 'p_' + 'Q'.repeat(36) + await failing($, w, EXIT1 + 'fatal: bad ' + token, 'git push ' + token) + const text = await pending($) + expect(text).toContain('') + expect(text).not.toContain('QQQQ') +}) + +test('IDX8: the error span is indexed, not the prose between', async () => { + const body = '## BLK-009 \u2014 z\n`git rm` and later words ' + + '`fatal: unable to access remote host`\n' + const index = buildIndex([body]) + expect(matchOf(index, normalize('fatal: unable to access remote host'))) + .toBe('BLK-009') + expect(matchOf(index, normalize('and later words fatal unable'))) + .toBeUndefined() +}) + +test('a key of fewer than 4 words has no gram, so it is NEW', () => { + expect(grams('a b c')).toEqual([]) + expect(grams('a b c d e')).toEqual(['a b c d', 'b c d e']) + const index = buildIndex(['## BLK-001 x\n`aaa bbb ccc ddd`\n']) + expect(matchOf(index, 'aaa bbb ccc')).toBeUndefined() +}) + +test('entriesOf slices between headings, heading line included', () => { + const text = '## BLK-001 a\nx\n## other\ny\n## LRN-2 [b]\nz\n' + expect(entriesOf(text)).toEqual([ + { id: 'BLK-001', body: '## BLK-001 a\nx\n## other\ny\n' }, + { id: 'LRN-2', body: '## LRN-2 [b]\nz\n' }, + ]) +}) + +test('isSuperseded: the last status wins, else the heading tag', () => { + expect(isSuperseded('## LRN-1 a\n- **Status**: open\n- **Statut**: ' + + 'superseded\n')).toBe(true) + expect(isSuperseded('## LRN-1 a\n- **Status**: superseded\n' + + '- **Status**: open\n')).toBe(false) + expect(isSuperseded('## LRN-1 [superseded] a\nbody\n')).toBe(true) + expect(isSuperseded('## LRN-1 [open] a\n')).toBe(false) +}) + +test('readRegistry: a directory and an over-size file read as empty', async ( + $, on, +) => { + const big = 'x'.repeat(4194305) + const w = await boot($, on, { files: { [BLK]: null, [LRN]: big } }) + expect(await readRegistry($ as never, BLK)).toBe('') + expect(await readRegistry($ as never, LRN)).toBe('') + await failing($, w, EXIT1 + 'fatal: bad thing') + expect(await pending($)).toContain( + 'index: skipped blockers.md (not a file), learnings.md (over 4 MiB)') +}) + +test('an empty root answers no project root', async ($, on) => { + const w = await boot($, on) + w.root = '' + expect(await pending($)).toBe('memory_pending: no project root') +}) + +test('milestones, sub-agent, earlier session and order', async ($, on) => { + const mk = (id: string, at: number, failures: unknown[], ms: unknown[]) => + ({ id, at, failures, milestones: ms, red: [] }) + const f = (line: string, agent = false) => ({ + key: line, line, excerpt: 'a\nb', command: 'c', agent, at: 1, count: 2, + }) + const seed = { [`p:${ROOT}`]: { sessions: [ + mk('s1', 900, [f('known one fatal: unable to access remote host'), + f('brand new line here ok', true)], + [{ kind: 'commit', label: 'fix: x', at: 3600000 * 14 + 120000 }]), + mk('s0', 100, [f('old trouble in town today')], []), + ] } } + const w = await boot($, on, { seed, files: REGS }) + expect(w.kv.size).toBe(1) + expect(await pending($)).toBe([ + 'memory_pending (project app, 2 session(s))', + 'index: read blockers.md, learnings.md', + 'milestones (this session):', + '- commit fix: x (14:02)', + 'failures:', + '- NEW \u00d72 (sub-agent) brand new line here ok \u2014 command: c', + ' excerpt: a\u23ceb', + '- known BLK-001 \u00d72 known one fatal: unable to access remote host' + + ' \u2014 command: c', + ' excerpt: a\u23ceb', + '- NEW \u00d72 (earlier session) old trouble in town today' + + ' \u2014 command: c', + ' excerpt: a\u23ceb', + ].join('\n')) +}) + +test('the excerpt shows its last 300 characters', async ($, on) => { + const w = await boot($, on) + await failing($, w, EXIT1 + 'x'.repeat(400) + '\nfatal: tail marker') + const text = await pending($) + const shown = text.split('excerpt: ')[1] ?? '' + expect(shown.length).toBe(300) + expect(shown.endsWith('fatal: tail marker')).toBe(true) +}) + +test('the failure list is capped at 20000 chars with a count', async ( + $, on, +) => { + const f = (i: number) => ({ + key: `k${i}`, line: `line ${i} ${'y'.repeat(300)}`, + excerpt: 'e'.repeat(300), command: 'c', agent: false, at: 1, count: 1, + }) + const failures = Array.from({ length: 50 }, (_, i) => f(i)) + const seed = { [`p:${ROOT}`]: { sessions: [ + { id: 's1', at: 1, milestones: [], red: [], failures }, + ] } } + await boot($, on, { seed }) + const text = await pending($) + expect(text).toMatch(/\n\u2026 \d+ more failure\(s\) omitted$/) + expect(text.length).toBeLessThan(20300) +}) + +test('ID1/ID2: after an id change the earlier session is marked', async ( + $, on, +) => { + const w = await boot($, on) + await failing($, w, EXIT1 + 'boom one here today') + w.id = 's2' + await w.clock.advance(10) + await failing($, w, EXIT1 + 'boom two here today') + const text = await pending($) + expect(text).toContain('session(s))') + expect(text).toContain('- NEW \u00d71 boom two here today') + expect(text).toContain('(earlier session) boom one here today') + expect(text.indexOf('boom two')).toBeLessThan(text.indexOf('boom one')) +}) + +const endSession = ($: Engine) => + $.session.end({ reason: 'clear', sessionId: 's1', resume: { id: 's1' } }) + +test('session.end re-reads the switch and registers the tool again', async ( + $, on, +) => { + const w = await boot($, on, { switchText: '{"enabled": false}' }) + expect(w.tools).toEqual([]) + w.switchText = undefined + await endSession($) + await bash($, 'ls') + expect(w.tools).toEqual(['memory_pending']) + w.switchText = '{"enabled": false}' + await endSession($) + expect(await pending($)) + .toBe('memory capture is off (~/.claude/memory.json)') +}) + +test('the tool failing answers a stable text, not a throw', async ( + $, on, +) => { + const w = await boot($, on, { rootFails: true }) + expect(await pending($)).toBe( + 'memory_pending failed (throw); nothing returned') + expect(w.logs.some(l => l.startsWith('memory: memory_pending hook'))) + .toBe(true) +}) + +test('the tool never writes the store', async ($, on) => { + const w = await boot($, on, { files: REGS }) + await pending($) + expect(w.sets).toEqual([]) +}) diff --git a/mods/memory/hooks/register.ts b/mods/memory/hooks/register.ts index 95ac6df..cda6d77 100644 --- a/mods/memory/hooks/register.ts +++ b/mods/memory/hooks/register.ts @@ -17,6 +17,7 @@ type State = { const SWITCH_FILE = '.claude/memory.json' const MAX_SWITCH_BYTES = 65536 const TOOL = 'memory_pending' +const SERVED_TOOL = 'mcp__memory__memory_pending' const MAX_REGEX_INPUT = 65536 const PEM = '-----' @@ -278,6 +279,194 @@ async function sweepStore($: Api, curKey: string, id: string): Promise { } } +// The registry error index: which captured failures a registry knows. +const REGISTRIES = ['blockers.md', 'learnings.md'] +const MAX_REGISTRY = 4194304 +const MIN_SPAN = 12 +const GRAM_WORDS = 4 +const HEADING = /^## ((?:BLK|LRN)-\d+)\b.*$/gm +const SPAN = /`([^`\n]+)`/g +const STATUS = /^\s*-\s*\*\*Stat(?:us|ut)[^*]*\*\*\s*:?\s*([A-Za-z-]+)/gim + +type Entry = { id: string; body: string } + +/** Why a registry is not read, or `undefined` when it is readable. */ +async function skipReason($: Api, path: string): Promise { + try { + const info = await $.fs.stat(path) + if (info.kind !== 'file') return 'not a file' + return info.size > MAX_REGISTRY ? 'over 4 MiB' : undefined + } catch { + return 'missing' + } +} + +/** A registry's text; `''` when missing, not a file or over 4 MiB. */ +export async function readRegistry($: Api, path: string): Promise { + if ((await skipReason($, path)) !== undefined) return '' + try { + return await $.fs.read(path) + } catch { + return '' + } +} + +/** The BLK/LRN entries; a body runs from its heading to the next one. */ +export function entriesOf(text: string): Entry[] { + const heads = [...text.matchAll(HEADING)] + return heads.map((m, i) => ({ + id: m[1] ?? '', + body: text.slice(m.index ?? 0, heads[i + 1]?.index ?? text.length), + })) +} + +// shortcut: a lexical reader, not memory.sh's shared parser (that lives in +// shell); upgrade = call the parser once the engine exposes a CLI run in +// hooks. +/** The last labelled status reads superseded; else the heading `[tag]`. */ +export function isSuperseded(body: string): boolean { + const last = [...body.matchAll(STATUS)].pop() + if (last !== undefined) return (last[1] ?? '').toLowerCase() === 'superseded' + return /\[superseded\]/i.test(body.split('\n', 1)[0] ?? '') +} + +/** Every window of 4 words; a key of fewer words has none (always NEW). */ +export function grams(normLine: string): string[] { + const words = normLine.split(/[^a-z0-9<>#]+/).filter(Boolean) + if (words.length < GRAM_WORDS) return [] + return words + .slice(0, words.length - GRAM_WORDS + 1) + .map((_, i) => words.slice(i, i + GRAM_WORDS).join(' ')) +} + +function spansOf(body: string): string[] { + return [...body.matchAll(SPAN)] + .map(m => m[1] ?? '') + .filter(span => span.length >= MIN_SPAN) +} + +function indexEntry(index: Map, entry: Entry): void { + if (isSuperseded(entry.body)) return + for (const span of spansOf(entry.body)) { + for (const gram of grams(normalize(span))) { + if (!index.has(gram)) index.set(gram, entry.id) + } + } +} + +/** gram -> first ID, over the backticked spans of live entries. */ +export function buildIndex(texts: string[]): Map { + const index = new Map() + for (const text of texts) { + for (const entry of entriesOf(text)) indexEntry(index, entry) + } + return index +} + +/** The registry ID of the first gram of `key` the index holds. */ +export function matchOf( + index: Map, + key: string, +): string | undefined { + for (const gram of grams(key)) { + const id = index.get(gram) + if (id !== undefined) return id + } + return undefined +} + +type Registries = { index: Map; note: string } + +async function loadIndex($: Api, root: string): Promise { + const texts: string[] = [] + const read: string[] = [] + const skipped: string[] = [] + for (const name of REGISTRIES) { + const path = `${root}/.claude/memory/${name}` + const why = await skipReason($, path) + if (why !== undefined) { + skipped.push(`${name} (${why})`) + continue + } + texts.push(await readRegistry($, path)) + read.push(name) + } + const parts = [ + read.length > 0 ? `read ${read.join(', ')}` : '', + skipped.length > 0 ? `skipped ${skipped.join(', ')}` : '', + ] + return { + index: buildIndex(texts), + note: `index: ${parts.filter(Boolean).join('; ')}`, + } +} + +// The answer of memory_pending: data for the model, never executed. +const ANSWER_CAP = 20000 +const EXCERPT_SHOWN = 300 +const OFF_TEXT = 'memory capture is off (~/.claude/memory.json)' +const NOTHING_TEXT = 'memory_pending: nothing captured' + +type Row = { f: Failure; id: string | undefined; earlier: boolean } + +/** Current-session NEW, current-session known, then earlier sessions. */ +function rowsOf(p: Project, curId: string, index: Map) { + const rows: Row[] = p.sessions.flatMap(s => s.failures.map(f => ({ + f, id: matchOf(index, f.key), earlier: s.id !== curId, + }))) + const rank = (r: Row) => (r.earlier ? 2 : r.id === undefined ? 0 : 1) + return rows.sort((a, b) => rank(a) - rank(b)) +} + +function failureText({ f, id, earlier }: Row): string { + const tag = id === undefined ? 'NEW' : `known ${id}` + const marks = (f.agent ? ' (sub-agent)' : '') + + (earlier ? ' (earlier session)' : '') + const head = `- ${tag} ×${f.count}${marks} ${f.line} — command: ${f.command}` + if (f.excerpt === '') return head + const shown = tail(f.excerpt, EXCERPT_SHOWN).replace(/\r?\n/g, '⏎') + return `${head}\n excerpt: ${shown}` +} + +function milestoneText(m: Milestone): string { + const hhmm = new Date(m.at).toISOString().slice(11, 16) + return `- ${m.kind} ${m.label} (${hhmm})` +} + +/** The failure list within ANSWER_CAP; the rest is counted, not shown. */ +function capFailures(items: string[]): string[] { + const kept: string[] = [] + let used = 0 + for (const item of items) { + if (used + item.length + 1 > ANSWER_CAP) break + kept.push(item) + used += item.length + 1 + } + const omitted = items.length - kept.length + return omitted > 0 ? [...kept, `… ${omitted} more failure(s) omitted`] : kept +} + +export function formatPending( + root: string, + p: Project, + curId: string, + rx: Registries, +): string { + const rows = rowsOf(p, curId, rx.index) + const ms = p.sessions.find(s => s.id === curId)?.milestones ?? [] + if (rows.length === 0 && ms.length === 0) return NOTHING_TEXT + const name = root.split('/').filter(Boolean).pop() ?? root + const out = [`memory_pending (project ${name}, ${p.sessions.length} ` + + 'session(s))', rx.note] + if (ms.length > 0) { + out.push('milestones (this session):', ...ms.map(milestoneText)) + } + if (rows.length > 0) { + out.push('failures:', ...capFailures(rows.map(failureText))) + } + return out.join('\n') +} + /** Runs `job` after every earlier write; a failed link breaks nothing. */ function queueWrite(st: State, job: () => Promise): Promise { const run = st.writes.then(job) @@ -331,15 +520,21 @@ async function loadEnabled($: Api): Promise { } } -/** The tool the model calls to list the pending captures (body: later). */ +/** The tool the model calls to list the failures and milestones captured. */ async function registerTool($: Api): Promise { try { await $.tool.register({ name: TOOL, description: - 'List the failures and milestones captured in this project and ' + - 'not yet written to the memory registries.', - inputSchema: { type: 'object', additionalProperties: false }, + 'Failures and milestones this mod captured in the current ' + + 'project\'s recent sessions, each failure NEW or known . Call it first in /capitalize and every CAPITALIZE step; it ' + + 'never writes anything.', + inputSchema: { + type: 'object', + properties: {}, + additionalProperties: false, + }, }) } catch { $.ui.log('memory: tool not registered') @@ -358,6 +553,28 @@ async function ensureEnabled($: Api, st: State): Promise { return st.enabled } +/** The tool's answer; reads the store and the registries, writes nothing. */ +async function pendingAnswer($: Api, st: State): Promise { + if (!(await ensureEnabled($, st))) return OFF_TEXT + const root = await $.session.root() + if (root === '') return 'memory_pending: no project root' + const id = await $.session.id() + await st.writes + const project = await loadProject($, root) + return formatPending(root, project, id, await loadIndex($, root)) +} + +function registerPending(on: On, st: State): void { + on('tool.call', { tool: SERVED_TOOL }, async $ => ({ + result: await pendingAnswer($, st), + })).catch(($, _e, next) => { + warnOnce(st, $, 'memory_pending', next.error.kind) + return { + result: `memory_pending failed (${next.error.kind}); nothing returned`, + } + }) +} + function registerSession(on: On, st: State): void { on('session.start', async ($, e, next) => { await ensureEnabled($, st) @@ -426,5 +643,6 @@ export const register: Register = on => { const st = newState() registerSession(on, st) registerBash(on, st) + registerPending(on, st) registerPrompt(on, st) }