// memory: captures what fails in a session and offers it to the memory // registries. This file is the frame: the off switch, the fail-open hooks // 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. import type { EngineInterface, On, Register } from 'claude-code' type Api = EngineInterface type State = { enabled: boolean | null // null: not read yet this session warned: Set pending: string[] // milestones not yet shown in a note writes: Promise // the one chain every store write runs on } const SWITCH_FILE = '.claude/memory.json' const MAX_SWITCH_BYTES = 65536 const TOOL = 'memory_pending' const MAX_REGEX_INPUT = 65536 const PEM = '-----' const PEM_KIND = '(?:[A-Z]+ )?PRIVATE KEY' // Redaction patterns, applied in order. Repeats are bounded where the // input is free text, so no pattern can run away on a 64 KiB input. const REDACTIONS: [RegExp, string][] = [ [/\b([A-Za-z_]*(?:TOKEN|API_KEY|SECRET|PASSWORD|PASSWD)[A-Za-z_]*)=\S+/gi, '$1='], [/sk_live_[0-9A-Za-z]{10,}/g, ''], [/AKIA[0-9A-Z]{16}/g, ''], [/gh[pousr]_[A-Za-z0-9]{30,}/g, ''], [/xox[abprs]-[A-Za-z0-9-]{10,}/g, ''], [/SG\.[A-Za-z0-9_-]{16,}\.[A-Za-z0-9_-]{16,}/g, ''], [/sb_secret_[A-Za-z0-9_-]{10,}/g, ''], [new RegExp( `${PEM}BEGIN ${PEM_KIND}${PEM}[\\s\\S]*?` + `(?:${PEM}END ${PEM_KIND}${PEM}|$)`, 'g', ), ''], [/\bBearer\s+[A-Za-z0-9._~+/=-]{8,}/g, 'Bearer '], [/([a-z][a-z0-9+.-]{0,30}:\/\/)[^\s/@:]+:[^\s/@]+@/gi, '$1@'], ] const HEX_RUN = /\b[0-9a-f]{7,}\b/g const PATH = /(?:\.{0,2}\/)?[\w.-]{1,200}(?:\/[\w.-]{1,200}){1,30}/g /** The first `n` code units of `text` (input guard for regex work). */ export function cap(text: string, n: number): string { return text.slice(0, n) } /** The last `n` code units of `text` (the end of an output holds the error). */ export function tail(text: string, n: number): string { return n <= 0 ? '' : text.slice(-n) } /** Masks secret-shaped text; reads at most the first 64 KiB. */ export function redact(text: string): string { let out = cap(text, MAX_REGEX_INPUT) for (const [pattern, mask] of REDACTIONS) out = out.replace(pattern, mask) return out } /** A comparison key: volatile parts (hashes, paths, numbers) collapsed. */ export function normalize(line: string): string { return line .toLowerCase() .replace(HEX_RUN, '') .replace(PATH, '') .replace(/\d+/g, '#') .replace(/\s+/g, ' ') .trim() } // The store: one key per project root, at most MAX_SESSIONS sessions each. type Failure = { key: string // normalize(line): what makes two failures the same line: string excerpt: string command: string agent: boolean at: number count: number } type Milestone = { kind: 'commit' | 'finish' | 'green' label: string at: number } type Session = { id: string at: number // last activity failures: Failure[] milestones: Milestone[] red: string[] } type Project = { sessions: Session[] } const STORE_PREFIX = 'p:' const MAX_ROOT = 400 const MAX_SESSIONS = 3 const MAX_FAILURES = 50 const MAX_MILESTONES = 20 const MAX_RED = 10 const MAX_RED_LEN = 300 const MAX_LINE = 300 const MAX_COMMAND = 300 const EXCERPT_LEN = 600 const MAX_ENTRY = 2048 const STORE_CAP = 1048576 const LINE_WINDOW = 1000 // bounds the trailer regex on one long line const EXIT_CODE = /^Exit code \d+/ const RTK_TRAILER = /\s*\[(?:\+\d+ hidden|full output): rtk recall [0-9a-f]+\]$/ /** * The line that tells what failed, from an already redacted answer: the * last line after the first of an `Exit code N` text. `undefined` when the * text is another kind, has no such line, or the line holds no letter. */ export function failureLine(text: string): string | undefined { if (!EXIT_CODE.test(text)) return undefined const lines = text.split('\n') .map(l => l.slice(-LINE_WINDOW).replace(RTK_TRAILER, '').trim()) .filter(l => l !== '') if (lines.length < 2) return undefined const line = (lines[lines.length - 1] ?? '').slice(0, MAX_LINE) const letters = normalize(line).replace(/||#/g, '') return /\p{L}/u.test(letters) ? line : undefined } function isSession(v: unknown): v is Session { const s = v as Partial | null return typeof s === 'object' && s !== null && typeof s.id === 'string' && typeof s.at === 'number' && Array.isArray(s.failures) && Array.isArray(s.milestones) && Array.isArray(s.red) } /** A stored value read as a project; malformed parts are dropped. */ function asProject(value: unknown): Project { const sessions = (value as Partial | null)?.sessions if (!Array.isArray(sessions)) return { sessions: [] } return { sessions: sessions.filter(isSession) } } const storeKey = (root: string) => STORE_PREFIX + root.slice(0, MAX_ROOT) export async function loadProject($: Api, root: string): Promise { return asProject(await $.store.get(storeKey(root))) } /** * Finds the session or creates it, stamps its activity and keeps the * MAX_SESSIONS latest of the project; the one returned is never trimmed. */ export function sessionOf(p: Project, id: string, now: number): Session { const found = p.sessions.find(s => s.id === id) const s = found ?? { id, at: now, failures: [], milestones: [], red: [] } s.at = now const others = p.sessions.filter(o => o !== s).sort((a, b) => b.at - a.at) p.sessions = [s, ...others].slice(0, MAX_SESSIONS) return s } export function addFailure(s: Session, f: Failure): void { const same = s.failures.find(x => x.key === f.key) if (same === undefined) { s.failures = [...s.failures, f].slice(-MAX_FAILURES) return } same.count++ same.at = f.at } /** An entry over MAX_ENTRY loses its excerpt first, then its line. */ function fitEntry(f: Failure): Failure { const out = { ...f } for (const field of ['excerpt', 'line', 'command', 'key'] as const) { const over = JSON.stringify(out).length - MAX_ENTRY if (over <= 0) break out[field] = field === 'excerpt' ? '' : out[field].slice(0, Math.max(0, out[field].length - over)) } return out } /** * The failure entry of a tool answer, or `undefined` when the answer is * not a capturable failure. Everything stored comes from the redacted text. */ function buildFailure( text: string, command: string, agent: boolean, at: number, ): Failure | undefined { const red = redact(tail(text, MAX_REGEX_INPUT)) const line = failureLine(red) if (line === undefined) return undefined return fitEntry({ key: normalize(line), line, excerpt: tail(red, EXCERPT_LEN), command: redact(cap(command, MAX_REGEX_INPUT)).slice(0, MAX_COMMAND), agent, at, count: 1, }) } function bounded(s: Session): Session { return { ...s, milestones: s.milestones.slice(-MAX_MILESTONES), red: s.red.slice(-MAX_RED).map(r => r.slice(0, MAX_RED_LEN)), } } export async function saveProject( $: Api, root: string, p: Project, ): Promise { await $.store.set(storeKey(root), { sessions: p.sessions.map(bounded) }) } type Held = { key: string; size: number; project: Project; changed: boolean } async function readHeld($: Api): Promise { const keys = (await $.store.keys()).filter(k => k.startsWith(STORE_PREFIX)) const held: Held[] = [] for (const key of keys) { const raw = await $.store.get(key) const size = JSON.stringify(raw ?? null).length held.push({ key, size, project: asProject(raw), changed: false }) } return held } /** The oldest session that is not the current one, with its project. */ function oldestOther(held: Held[], cur: string, id: string) { let best: { h: Held; s: Session } | undefined for (const h of held) { for (const s of h.project.sessions) { if (h.key === cur && s.id === id) continue if (best === undefined || s.at < best.s.at) best = { h, s } } } return best } /** * Drops the oldest non-current sessions, across projects, until the * `p:*` keys fit STORE_CAP or none is droppable. Runs when a session * record is created, not on every write. */ async function sweepStore($: Api, curKey: string, id: string): Promise { const held = await readHeld($) let total = held.reduce((n, h) => n + h.size, 0) while (total > STORE_CAP) { const victim = oldestOther(held, curKey, id) if (victim === undefined) break const { h, s } = victim h.project.sessions = h.project.sessions.filter(x => x !== s) h.changed = true const size = JSON.stringify(h.project).length total += size - h.size h.size = size } for (const h of held.filter(x => x.changed)) { if (h.project.sessions.length === 0) await $.store.delete(h.key) else await $.store.set(h.key, h.project) } } /** Runs `job` after every earlier write; a failed link breaks nothing. */ function queueWrite(st: State, job: () => Promise): Promise { const run = st.writes.then(job) st.writes = run.catch(() => undefined) return run } type Where = { root: string; id: string } async function recordFailure($: Api, at: Where, f: Failure): Promise { const p = await loadProject($, at.root) const created = !p.sessions.some(s => s.id === at.id) addFailure(sessionOf(p, at.id, f.at), f) await saveProject($, at.root, p) if (created) await sweepStore($, storeKey(at.root), at.id) } function newState(): State { return { enabled: null, warned: new Set(), pending: [], writes: Promise.resolve(), } } /** Logs a hook's fail-open once per session; never throws itself. */ function warnOnce(st: State, $: Api, hook: string, kind: string): void { if (st.warned.has(hook)) return st.warned.add(hook) try { $.ui.log(`memory: ${hook} hook failed (${kind}); passed through`) } catch { // a failing log must not break the fail-open itself } } /** True unless the user's switch file says `enabled: false`. */ async function loadEnabled($: Api): Promise { try { const home = await $.env.get('HOME') if (!home) return true const 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)) if (typeof data !== 'object' || data === null) return true return (data as { enabled?: unknown }).enabled !== false } catch { return true } } /** The tool the model calls to list the pending captures (body: later). */ 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 }, }) } catch { $.ui.log('memory: tool not registered') } } /** * Reads the switch on the first event of a session and caches it; each * read of `enabled: true` registers the tool again (a name registered * twice is replaced). */ async function ensureEnabled($: Api, st: State): Promise { if (st.enabled !== null) return st.enabled st.enabled = await loadEnabled($) if (st.enabled) await registerTool($) return st.enabled } function registerSession(on: On, st: State): void { on('session.start', async ($, e, next) => { await ensureEnabled($, st) return next(e) }).catch(($, e, next) => { warnOnce(st, $, 'session.start', next.error.kind) return next(e) }) on('session.end', async ($, e, next) => { st.enabled = null st.pending = [] return next(e) }).catch(($, e, next) => { warnOnce(st, $, 'session.end', next.error.kind) return next(e) }) } /** Stores the failure a Bash answer carries; never throws, never re-runs. */ async function captureFailure( $: Api, st: State, at: Where, e: { command?: unknown; agentId?: unknown }, out: { isError?: boolean; text?: string }, ): Promise { try { if (out.isError !== true) return const agent = e.agentId !== undefined const f = buildFailure( String(out.text ?? ''), String(e.command ?? ''), agent, await $.clock.now(), ) if (f !== undefined) await queueWrite(st, () => recordFailure($, at, f)) } catch { warnOnce(st, $, 'Bash capture', 'store') } } function registerBash(on: On, st: State): void { on('tool.call', { tool: 'Bash' }, async ($, e, next) => { if (!(await ensureEnabled($, st))) return next(e) // read before next: a failure here must not run the tool twice const at = { root: await $.session.root(), id: await $.session.id() } if (at.root === '') return next(e) const out = await next(e) await captureFailure($, st, at, e, out) return out }).catch(($, e, next) => { warnOnce(st, $, 'Bash', next.error.kind) return next(e) }) } function registerPrompt(on: On, st: State): void { on('prompt.submit', async ($, e, next) => { await ensureEnabled($, st) return next(e) }).catch(($, e, next) => { warnOnce(st, $, 'prompt.submit', next.error.kind) return next(e) }) } export const register: Register = on => { const st = newState() registerSession(on, st) registerBash(on, st) registerPrompt(on, st) }