From acbfd71327023fac6216d288838994fac4010638 Mon Sep 17 00:00:00 2001 From: bchanot Date: Thu, 5 Nov 2026 16:28:54 +0100 Subject: [PATCH] feat(memory): recall switch, injection log and per-context ledger --- mods/memory/hooks/register.test.ts | 222 ++++++++++++++++++++++++++++- mods/memory/hooks/register.ts | 205 ++++++++++++++++++++++++-- 2 files changed, 412 insertions(+), 15 deletions(-) diff --git a/mods/memory/hooks/register.test.ts b/mods/memory/hooks/register.test.ts index d20f737..4d60057 100644 --- a/mods/memory/hooks/register.test.ts +++ b/mods/memory/hooks/register.test.ts @@ -8,7 +8,10 @@ import { buildIndex, matchOf, deErrno, tokensOf, bm25Rank, rerankPrompt, parseIds, recallLine, recallBlock, failureKey, segments, suiteKeyOf, commitLabel, finishLabel, + newState, switchOf, claim, onContextStart, resetContext, endContext, + appendLog, loadLog, RECALL_CAP, } from './register' +import type { LogRecord } from './register' const HOME = '/home/t' const SWITCH = `${HOME}/.claude/memory.json` @@ -157,6 +160,7 @@ async function boot($: Engine, on: On, o: Opts = {}): Promise { on('tool.call', { tool: 'Bash' }, (_a, e) => (w.byCommand.get(e.command) ?? w.answer) as never) on('session.end', (_a, e) => ({ sessionId: e.sessionId })) + on('classic.SessionStart', () => ({})) await $.session.start({ cwd: '/tmp', surface: null, isInteractive: false }) return w } @@ -1772,7 +1776,7 @@ test('assembleEntries joins kind, memory.sh title, lesson and body', () => { expect(assembleEntries([body], new Map())[0]?.title).toBe('') }) -test('TIMEentries: entriesOf and lessonOf on 64 KiB fields, under 50 ms', () => { +test('TIMEentries: entriesOf, lessonOf on 64 KiB fields, under 50 ms', () => { const bodies = [ '## BLK-001 x\n- Solution: ' + 'a'.repeat(65536 - 26), '## BLK-001 x\n- Solution: ' + 'a. '.repeat(21000), @@ -1919,6 +1923,18 @@ test('RB7: failureKey is the normalized last line of the redacted tail', () => { expect(failureKey('Exit code 1\nrm: /tmp/x/y: Permission denied', 'rm x')) .toBe('rm: : permission denied') expect(failureKey('', 'ls')).toBeUndefined() + expect(failureKey('make: *** [all] Error 2', 'make')).toBeUndefined() +}) + +test('RB6b: a secret straddling char 2000 of the query is redacted', () => { + const secret = 'sk_live_' + 'a'.repeat(24) + const q = 'x'.repeat(1979) + ' ' + secret + ' tail' + const p = rerankPrompt(q, []) + expect(q.indexOf(secret)).toBeLessThan(2000) + expect(q.indexOf(secret) + secret.length).toBeGreaterThan(2000) + expect(p).toContain('') + expect(p).not.toContain('sk_live_') + expect(p).not.toContain('aaaa') }) test('TIMErank: tokensOf and parseIds on 64 KiB, under 50 ms', () => { @@ -1928,3 +1944,207 @@ test('TIMErank: tokensOf and parseIds on 64 KiB, under 50 ms', () => { parseIds('BDR-1 '.repeat(10000) + 'LRN-'.repeat(15000), [], 3) expect(now() - t0).toBeLessThan(50) }) + +// ---- recall: switch key, injection log, per-context ledger ------------- + +test('SW1: no enabled key with "recall": false logs nothing', async ( + $, on, +) => { + const w = await boot($, on, { switchText: '{"recall": false}' }) + await bash($, 'ls') + expect(w.logs).toEqual([]) + expect(w.tools).toEqual(['memory_pending']) +}) + +test('SW2: a non-boolean "recall" logs one line, recall stays on', async ( + $, on, +) => { + const w = await boot($, on, { switchText: '{"recall": "no"}' }) + await bash($, 'ls') + await bash($, 'ls') + expect(w.logs).toEqual([ + 'memory: ~/.claude/memory.json has no boolean "recall", ' + + 'recall stays on', + ]) + expect(w.tools).toEqual(['memory_pending']) +}) + +test('SW3: switchOf reads the two keys', () => { + const $ = { ui: { log: () => undefined } } as never + const of = (data: unknown) => switchOf($, newState(), data) + expect(of({})).toEqual({ enabled: true, recall: true }) + expect(of({ recall: false })).toEqual({ enabled: true, recall: false }) + expect(of({ recall: 'no' })).toEqual({ enabled: true, recall: true }) + expect(of({ enabled: false })).toEqual({ enabled: false, recall: false }) + expect(of({ enabled: false, recall: true })) + .toEqual({ enabled: false, recall: false }) + expect(of(null)).toEqual({ enabled: true, recall: true }) +}) + +test('SW4: enabled false turns everything off, silently', async ($, on) => { + const w = await boot($, on, { switchText: '{"enabled": false}' }) + await failing($, w, 'Exit code 1\nfatal: bad thing') + expect(w.logs).toEqual([]) + expect(w.tools).toEqual([]) + expect(w.sets).toEqual([]) +}) + +/** A state that holds injections for two sessions and an agent. */ +function ledger() { + const st = newState() + for (const key of ['s1:main', 's1:a1', 's2:main']) { + st.seen.set(key, new Set(['BLK-001'])) + st.spent.set(key, 100) + } + return st +} + +test('CS1: startup, clear and compact reset the session, mark it fresh', + () => { + for (const source of ['startup', 'clear', 'compact']) { + const st = ledger() + resetContext(st, source, 's1', undefined) + expect([...st.seen.keys()]).toEqual(['s2:main']) + expect([...st.spent.keys()]).toEqual(['s2:main']) + expect([...st.fresh]).toEqual(['s1']) + } + }) + +test('CS2: resume and fork change nothing', () => { + const st = ledger() + resetContext(st, 'resume', 's1', undefined) + resetContext(st, 'fork', 's1', undefined) + expect([...st.seen.keys()]).toEqual(['s1:main', 's1:a1', 's2:main']) + expect([...st.spent.values()]).toEqual([100, 100, 100]) + expect(st.fresh.size).toBe(0) +}) + +test('CS3: an agent start resets only that agent key', () => { + const st = ledger() + resetContext(st, 'startup', 's1', 'a1') + expect([...st.seen.keys()]).toEqual(['s1:main', 's2:main']) + expect([...st.spent.keys()]).toEqual(['s1:main', 's2:main']) + expect(st.fresh.size).toBe(0) +}) + +test('CS4: the classic SessionStart event passes through the hook', + async ($, on) => { + const w = await boot($, on) + const out = await $.classic.SessionStart({ + hook_event_name: 'SessionStart', transcript_path: '/t', cwd: ROOT, + session_id: 's1', source: 'compact', + } as never) + expect(out).toEqual({}) + expect(w.logs).toEqual([]) + }) + +test('CS5: endContext clears only the ending session', () => { + const st = ledger() + for (const id of ['s1', 's2']) { + st.fresh.add(id) + st.lastPrompt.set(id, 5) + } + endContext(st, 's1') + expect([...st.seen.keys()]).toEqual(['s2:main']) + expect([...st.spent.keys()]).toEqual(['s2:main']) + expect([...st.fresh]).toEqual(['s2']) + expect([...st.lastPrompt.keys()]).toEqual(['s2']) +}) + +test('onContextStart is the one reset: forgets then marks fresh', () => { + const st = ledger() + onContextStart(st, 's2') + expect([...st.seen.keys()]).toEqual(['s1:main', 's1:a1']) + expect([...st.fresh]).toEqual(['s2']) +}) + +test('CL1: claim returns the unseen IDs that fit and records them', () => { + const st = newState() + const got = claim(st, 'k', ['A-1', 'B-2', 'C-3'], [400, 400, 400]) + expect(got).toEqual(['A-1', 'B-2', 'C-3']) + expect(st.spent.get('k')).toBe(1200) + expect([...(st.seen.get('k') ?? [])]).toEqual(['A-1', 'B-2', 'C-3']) +}) + +test('CL2: claim excludes the seen and stops at the budget', () => { + const st = newState() + expect(claim(st, 'k', ['A-1'], [900])).toEqual(['A-1']) + // A-1 is seen; B-2 (700) would pass 1500, C-3 (600) fits exactly + expect(claim(st, 'k', ['A-1', 'B-2', 'C-3'], [900, 700, 600])) + .toEqual(['C-3']) + expect(st.spent.get('k')).toBe(RECALL_CAP) + expect(st.seen.get('k')?.has('B-2')).toBe(false) + expect(claim(st, 'k', ['B-2'], [1])).toEqual([]) +}) + +test('CL3: claim keys are independent', () => { + const st = newState() + claim(st, 's1:main', ['A-1'], [1500]) + expect(claim(st, 's1:a1', ['A-1'], [1500])).toEqual(['A-1']) +}) + +/** The plugin's $.store over the world's Map, for the pure log calls. */ +const storeApi = (w: World) => ({ store: { + get: async (k: string) => w.kv.get(k), + set: async (k: string, v: unknown) => { + w.sets.push(k) + w.kv.set(k, JSON.parse(JSON.stringify(v))) + }, +} }) as never + +const REC = (at: number, ids = ['BLK-001']): LogRecord => + ({ at, session: 's1', agent: 'main', channel: 'prompt', ids }) + +test('LG1: a log in l: survives a capture and a sweep', async ( + $, on, +) => { + const big = (id: string, at: number) => ({ + id, at, milestones: [], red: [], + failures: [{ key: 'k', line: 'l', excerpt: 'x'.repeat(600000), + command: 'c', agent: false, at, count: 1 }], + }) + const seed = { + 'l:/work/app': [REC(7)], + 'p:/other': { sessions: [big('o2', 20), big('o1', 10)] }, + } + const w = await boot($, on, { seed }) + await failing($, w, EXIT1 + 'fatal: bad thing') + expect(projectOf(w, '/other')?.sessions.map(s => s.id)).toEqual(['o2']) + expect(w.kv.get('l:/work/app')).toEqual([REC(7)]) + expect(projectOf(w)?.sessions).toHaveLength(1) +}) + +test('LG2: 205 appends keep the newest 200', async ($, on) => { + const w = await boot($, on) + const st = newState() + const api = storeApi(w) + for (let at = 0; at < 205; at++) await appendLog(api, st, ROOT, REC(at)) + const log = w.kv.get(`l:${ROOT}`) as LogRecord[] + expect(log).toHaveLength(200) + expect(log[0]?.at).toBe(5) + expect(log[199]?.at).toBe(204) + expect(w.sets.every(k => k === `l:${ROOT}`)).toBe(true) +}) + +test('LG3: over 64 KiB serialized, the oldest records are dropped', + async ($, on) => { + const w = await boot($, on) + const st = newState() + const ids = ['X'.repeat(10000)] + for (let at = 0; at < 10; at++) { + await appendLog(storeApi(w), st, ROOT, REC(at, ids)) + } + const log = w.kv.get(`l:${ROOT}`) as LogRecord[] + expect(log.map(r => r.at)).toEqual([4, 5, 6, 7, 8, 9]) + expect(JSON.stringify(log).length).toBeLessThanOrEqual(65536) + }) + +test('LG4: loadLog drops malformed records; project key untouched', + async ($, on) => { + const bad = { at: 'x', session: 's1', agent: 'main', ids: [] } + const w = await boot($, on, { seed: { + [`l:${ROOT}`]: [REC(1), bad, null, { ...REC(2), channel: 'x' }], + } }) + expect(await loadLog(storeApi(w), ROOT)).toEqual([REC(1)]) + expect(w.kv.has(`p:${ROOT}`)).toBe(false) + }) diff --git a/mods/memory/hooks/register.ts b/mods/memory/hooks/register.ts index c06cd7a..d009031 100644 --- a/mods/memory/hooks/register.ts +++ b/mods/memory/hooks/register.ts @@ -9,13 +9,24 @@ type Api = EngineInterface type State = { enabled: boolean | null // null: not read yet this session + recall: boolean | null // the "recall" key, read with `enabled` warned: Set pending: string[] // milestones not yet shown in a note writes: Promise // the one chain every store write runs on + seen: Map> // context key -> injected IDs + spent: Map // context key -> chars injected + fresh: Set // sessions whose next qualifying prompt starts a context + lastPrompt: Map // session id -> time of its last prompt } +export const IDLE_MS = 1800000 +export const RECALL_CAP = 1500 +export const HAIKU = 'claude-haiku-5-5' +export const RERANK_MS = 3000 + const SWITCH_FILE = '.claude/memory.json' const MAX_SWITCH_BYTES = 65536 +const CONTEXT_STARTS = new Set(['startup', 'clear', 'compact']) const TOOL = 'memory_pending' const SERVED_TOOL = 'mcp__memory__memory_pending' const SWITCH_UNREADABLE = @@ -23,6 +34,9 @@ const SWITCH_UNREADABLE = const SWITCH_INVALID = 'memory: ~/.claude/memory.json has no boolean "enabled", capture stays on' +const SWITCH_RECALL_INVALID = + 'memory: ~/.claude/memory.json has no boolean "recall", recall stays on' + const MAX_REGEX_INPUT = 65536 const PEM = '-----' const PEM_KIND = '(?:[A-Z]+ )?PRIVATE KEY' @@ -686,8 +700,10 @@ export function bm25Rank(entries: Entry[], query: string, k: number): Entry[] { /** The haiku prompt: the redacted user prompt and one line per candidate. */ export function rerankPrompt(query: string, cands: Entry[]): string { const lines = cands.map(c => `${c.id} | ${c.title} | ${c.lesson}`) + // redact first: a secret straddling the cut would escape its pattern + const asked = cap(redact(cap(query, MAX_REGEX_INPUT)), MAX_QUERY) return ( - `Prompt: ${redact(cap(query, MAX_QUERY))}\nCandidates:\n` + + `Prompt: ${asked}\nCandidates:\n` + `${lines.join('\n')}\nAnswer with at most ${MAX_PICKS} candidate IDs ` + 'that would help with this prompt, comma separated, or none.' ) @@ -721,6 +737,7 @@ export function recallBlock(lines: string[], max: number): string { /** The dedup key of a failure text, as `buildFailure` stores it. */ export function failureKey(text: string, command: string): string | undefined { void command // the key comes from the output only; kept for the harness + if (!EXIT_CODE.test(text)) return undefined const line = lastLine(redact(tail(text, MAX_REGEX_INPUT))) return line === undefined ? undefined : normalize(line) } @@ -881,6 +898,57 @@ function queueWrite(st: State, job: () => Promise): Promise { return run } +export type LogRecord = { + at: number + session: string + agent: string + channel: 'prompt' | 'tool' + ids: string[] +} + +const LOG_PREFIX = 'l:' +const MAX_LOG = 200 +const MAX_LOG_BYTES = 65536 + +function isLogRecord(v: unknown): v is LogRecord { + const r = v as Partial | null + return typeof r === 'object' && r !== null && + typeof r.at === 'number' && typeof r.session === 'string' && + typeof r.agent === 'string' && + (r.channel === 'prompt' || r.channel === 'tool') && + Array.isArray(r.ids) && r.ids.every(i => typeof i === 'string') +} + +const logKey = (root: string) => LOG_PREFIX + root.slice(0, MAX_ROOT) + +/** The injection log of a project; malformed records are dropped. */ +export async function loadLog($: Api, root: string): Promise { + const raw = await $.store.get(logKey(root)) + return Array.isArray(raw) ? raw.filter(isLogRecord) : [] +} + +/** The newest records that fit MAX_LOG and MAX_LOG_BYTES serialized. */ +function fitLog(log: LogRecord[]): LogRecord[] { + let kept = log.slice(-MAX_LOG) + while (kept.length > 0 && JSON.stringify(kept).length > MAX_LOG_BYTES) { + kept = kept.slice(1) + } + return kept +} + +/** Appends an injection record on the write chain; the oldest fall off. */ +export function appendLog( + $: Api, + st: State, + root: string, + record: LogRecord, +): Promise { + return queueWrite(st, async () => { + const log = await loadLog($, root) + await $.store.set(logKey(root), fitLog([...log, record])) + }) +} + type Where = { root: string; id: string } /** Load, change the current session, save; sweeps when it is created. */ @@ -970,12 +1038,17 @@ export function finishLabel(command: string): string | undefined { return undefined } -function newState(): State { +export function newState(): State { return { enabled: null, + recall: null, warned: new Set(), pending: [], writes: Promise.resolve(), + seen: new Map(), + spent: new Map(), + fresh: new Set(), + lastPrompt: new Map(), } } @@ -995,28 +1068,43 @@ function logOnce(st: State, $: Api, key: string, text: string): void { } } +type Switch = { enabled: boolean; recall: boolean } + /** - * True unless the user's switch file says `enabled: false`. A file that - * exists but cannot be read or parsed keeps capture on and logs one line. + * The switch file's two keys. An absent key is on; a present non-boolean + * logs one line and counts as absent. `enabled: false` cuts recall too. */ -async function loadEnabled($: Api, st: State): Promise { +export function switchOf($: Api, st: State, data: unknown): Switch { + const keys = (data ?? {}) as { enabled?: unknown; recall?: unknown } + if (keys.enabled !== undefined && typeof keys.enabled !== 'boolean') { + logOnce(st, $, 'switch', SWITCH_INVALID) + } + if (keys.recall !== undefined && typeof keys.recall !== 'boolean') { + logOnce(st, $, 'switch-recall', SWITCH_RECALL_INVALID) + } + const enabled = keys.enabled !== false + return { enabled, recall: enabled && keys.recall !== false } +} + +/** + * The user's switch file. A file that exists but cannot be read or parsed + * keeps everything on and logs one line. + */ +async function loadEnabled($: Api, st: State): Promise { + const on = { enabled: true, recall: true } let path = '' try { const home = await $.env.get('HOME') - if (!home) return true + if (!home) return on path = `${home}/${SWITCH_FILE}` const info = await $.fs.stat(path) - if (info.kind !== 'file' || info.size > MAX_SWITCH_BYTES) return true - const data: unknown = JSON.parse(await $.fs.read(path)) - const enabled = (data as { enabled?: unknown } | null)?.enabled - if (typeof enabled === 'boolean') return enabled - logOnce(st, $, 'switch', SWITCH_INVALID) - return true + if (info.kind !== 'file' || info.size > MAX_SWITCH_BYTES) return on + return switchOf($, st, JSON.parse(await $.fs.read(path))) } catch { if (path !== '' && !(await isGone($, path))) { logOnce(st, $, 'switch', SWITCH_UNREADABLE) } - return true + return on } } @@ -1048,11 +1136,62 @@ async function registerTool($: Api): Promise { */ async function ensureEnabled($: Api, st: State): Promise { if (st.enabled !== null) return st.enabled - st.enabled = await loadEnabled($, st) + const sw = await loadEnabled($, st) + st.enabled = sw.enabled + st.recall = sw.recall if (st.enabled) await registerTool($) return st.enabled } +/** True when the mod is on and the "recall" key does not turn it off. */ +async function ensureRecall($: Api, st: State): Promise { + return (await ensureEnabled($, st)) && st.recall === true +} + +const contextKey = (session: string, agent: string | undefined) => + `${session}:${agent ?? 'main'}` + +/** Forgets what a session's contexts injected. */ +function forgetContexts(st: State, session: string): void { + for (const map of [st.seen, st.spent]) { + for (const key of [...map.keys()]) { + if (key.startsWith(`${session}:`)) map.delete(key) + } + } +} + +/** A new context: nothing injected yet, the next prompt may recall. */ +export function onContextStart(st: State, session: string): void { + forgetContexts(st, session) + st.fresh.add(session) +} + +/** + * Takes the IDs not yet seen in the context whose line costs (`chars`, + * parallel to `ids`) still fit RECALL_CAP, and records them. Synchronous: + * called after the last await, so two racing callers never both claim. + */ +export function claim( + st: State, + key: string, + ids: string[], + chars: number[], +): string[] { + const seen = st.seen.get(key) ?? new Set() + let spent = st.spent.get(key) ?? 0 + const taken: string[] = [] + ids.forEach((id, i) => { + const cost = chars[i] ?? 0 + if (seen.has(id) || spent + cost > RECALL_CAP) return + seen.add(id) + spent += cost + taken.push(id) + }) + st.seen.set(key, seen) + st.spent.set(key, spent) + return taken +} + /** 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 @@ -1076,6 +1215,41 @@ function registerPending(on: On, st: State): void { }) } +/** The ending session's recall state; other sessions keep theirs. */ +export function endContext(st: State, session: string): void { + forgetContexts(st, session) + st.fresh.delete(session) + st.lastPrompt.delete(session) +} + +/** + * A context starts on startup, clear and compact (not resume or fork). + * An agent's start resets that agent's key only. + */ +export function resetContext( + st: State, + source: string, + session: string, + agent: string | undefined, +): void { + if (!CONTEXT_STARTS.has(source)) return + if (agent === undefined) return onContextStart(st, session) + const key = contextKey(session, agent) + st.seen.delete(key) + st.spent.delete(key) +} + +function registerContext(on: On, st: State): void { + on('classic.SessionStart', async ($, e, next) => { + const session = e.session_id ?? await $.session.id() + resetContext(st, e.source, session, e.agent_id) + return next(e) + }).catch(($, e, next) => { + warnOnce(st, $, 'SessionStart', next.error.kind) + return next(e) + }) +} + function registerSession(on: On, st: State): void { on('session.start', async ($, e, next) => { await ensureEnabled($, st) @@ -1086,8 +1260,10 @@ function registerSession(on: On, st: State): void { }) on('session.end', async ($, e, next) => { st.enabled = null + st.recall = null st.pending = [] st.warned.clear() + endContext(st, e.sessionId) return next(e) }).catch(($, e, next) => { warnOnce(st, $, 'session.end', next.error.kind) @@ -1258,6 +1434,7 @@ function registerPrompt(on: On, st: State): void { export const register: Register = on => { const st = newState() registerSession(on, st) + registerContext(on, st) registerBash(on, st) registerPending(on, st) registerPrompt(on, st)