Files
claude/mods/memory/hooks/register.ts
T

1807 lines
60 KiB
TypeScript
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
// 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.
// It also recalls: registry entries on a qualifying prompt and a known-error
// line on a Bash failure, both switchable with "recall": false.
import type { EngineInterface, On, Register } from 'claude-code'
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<string>
pending: string[] // milestones not yet shown in a note
writes: Promise<void> // the one chain every store write runs on
seen: Map<string, Set<string>> // context key -> injected IDs
spent: Map<string, number> // context key -> chars injected
fresh: Set<string> // sessions whose next qualifying prompt starts a context
lastPrompt: Map<string, number> // session id -> time of its last prompt
rerank: { fails: number; until: number } // failures in a row, pause end
}
export const IDLE_MS = 1800000
export const RECALL_CAP = 1500
export const HAIKU = 'claude-haiku-5-5'
export const RERANK_MS = 5000
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 =
'memory: ~/.claude/memory.json unreadable, capture stays on'
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'
// a value: a quoted string up to its closing quote, else up to a space
const VALUE = '("[^"\\n]{0,400}"|\'[^\'\\n]{0,400}\'|\\S+)'
const SECRET_KEY = '(?:password|token|secret|api[_-]?key)'
// the JSON key may hold `-`; the bare pair key may not (a `-` run would
// make every word start rescan 60 characters)
const keyWord = (cls: string) => `${cls}{0,60}${SECRET_KEY}${cls}{0,60}`
const JSON_KEY = keyWord('[A-Za-z0-9_-]')
const PAIR_KEY = keyWord('[A-Za-z0-9_]')
// Redaction patterns, applied in order: the JWT shape first (so a secret
// named variable still ends as `NAME=<redacted>` through pattern 1, and any
// other name keeps `NAME=<redacted:jwt>`), then the name rule, the vendor
// shapes, PEM, Bearer, URL credentials, and last the command-line shapes
// (-u user:pass, --password, Authorization), then the 6-bis shapes: vendor
// prefixes, --token flags, API-key headers, JSON and `key: value` pairs, a
// hex URL user. Repeats are bounded where the input is free text, so no
// pattern can run away on a 64 KiB input.
const REDACTIONS: [RegExp, string][] = [
[new RegExp(
'(?<![A-Za-z0-9_-])eyJ[A-Za-z0-9_-]{8,}\\.eyJ[A-Za-z0-9_-]{8,}' +
'\\.[A-Za-z0-9_-]{8,}',
'g',
), '<redacted:jwt>'],
// before pattern 1: a cookie jar `k=v; token=x` is one value
[new RegExp(`(?<=^|\\s)--cookie(?:=|[ \\t]{1,5})${VALUE}`, 'g'),
'--cookie <redacted>'],
[new RegExp(
'\\b([A-Za-z0-9_]{0,60}(?:TOKEN|API_KEY|SECRET|PASSWORD|PASSWD)' +
'[A-Za-z0-9_]{0,60})=' + VALUE,
'gi',
), '$1=<redacted>'],
[/sk_live_[0-9A-Za-z]{10,}/g, '<redacted:stripe>'],
[/AKIA[0-9A-Z]{16}/g, '<redacted:aws>'],
[/gh[pousr]_[A-Za-z0-9]{30,}/g, '<redacted:github>'],
[/xox[abprs]-[A-Za-z0-9-]{10,}/g, '<redacted:slack>'],
[/SG\.[A-Za-z0-9_-]{16,}\.[A-Za-z0-9_-]{16,}/g, '<redacted:sendgrid>'],
[/sb_secret_[A-Za-z0-9_-]{10,}/g, '<redacted:supabase>'],
[new RegExp(
`${PEM}BEGIN ${PEM_KIND}${PEM}[\\s\\S]*?` +
`(?:${PEM}END ${PEM_KIND}${PEM}|$)`,
'g',
), '<redacted:private-key>'],
[/\bBearer\s+[A-Za-z0-9._~+/=-]{8,}/g, 'Bearer <redacted>'],
[/(?<![a-z0-9+.-])([a-z][a-z0-9+.-]{0,200}:\/\/)[^\s/@:]+:[^\s/@]+@/gi,
'$1<redacted>@'],
[/(?<=^|\s)(-u|--user)[ \t]{1,5}\S{1,200}:\S*/g, '$1 <redacted>'],
[/--password(?:=|[ \t]{1,5})\S*/g, '--password <redacted>'],
[/Authorization:[ \t]{0,5}(Basic|Bearer|token)[ \t]{1,5}\S*/gi,
'Authorization: $1 <redacted>'],
[/sk-ant-[A-Za-z0-9_-]{10,}/g, '<redacted:anthropic>'],
[/sk-proj-[A-Za-z0-9_-]{10,}/g, '<redacted:openai>'],
[/github_pat_[A-Za-z0-9_]{10,}/g, '<redacted:github>'],
[/glpat-[A-Za-z0-9_-]{10,}/g, '<redacted:gitlab>'],
[/AIza[A-Za-z0-9_-]{20,}/g, '<redacted:google>'],
[/npm_[A-Za-z0-9]{10,}/g, '<redacted:npm>'],
[/--(token|api-key|secret)(?:=|[ \t]{1,5})\S*/g, '--$1 <redacted>'],
[new RegExp(
'(?<![A-Za-z0-9-])([A-Za-z0-9-]{0,30}api[_-]?key|PRIVATE-TOKEN|' +
'(?:Set-)?Cookie):[ \\t]{0,5}[^\\n]*',
'gi',
), '$1: <redacted>'],
[new RegExp(
`"(${JSON_KEY})"[ \\t]{0,5}:[ \\t]{0,5}"[^"\\n]{0,400}"`,
'gi',
), '"$1": "<redacted>"'],
// a value already `<redacted…>` (pattern 1) is not marked twice
[new RegExp(
`\\b(${PAIR_KEY})` +
`[ \\t]{0,5}[:=][ \\t]{0,5}(?!<redacted)${VALUE}`,
'gi',
), '$1: <redacted>'],
[/(?<![a-z0-9+.-])([a-z][a-z0-9+.-]{0,200}:\/\/)[0-9a-f]{40}@/gi,
'$1<redacted>@'],
]
const QUOTED = /'[^'\n]*'|"[^"\n]*"/g
const SEPARATOR = /[;&|\n]+/g
// before `curl`: ( $( NAME=value NAME=$( sudo rtk
const CURL_SEGMENT = new RegExp(
'^[ \\t(]{0,5}(?:\\$\\()?(?:[A-Za-z_]\\w{0,60}=' +
'(?:\\S{0,200}[ \\t]{1,5}|\\$\\()|(?:sudo|rtk)[ \\t]{1,5}){0,10}' +
'curl\\b',
)
const COOKIE_FLAG = new RegExp(`(?<=^|\\s)-b[ \\t]{1,5}${VALUE}`, 'g')
const HEX_RUN = /\b[0-9a-f]{7,}\b/g
const IO_ERROR = /input\/output error/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)
}
/**
* `curl -b <jar>` redacted per command segment: `-b` means a cookie jar
* only after `curl`. Segments are cut on separators outside quotes (the
* blanked copy has the same length, so its cuts apply to the text).
*/
function redactCurlCookie(text: string): string {
if (!text.includes('-b')) return text
const blank = text.replace(QUOTED, q => ' '.repeat(q.length))
const parts: string[] = []
let from = 0
for (const m of [...blank.matchAll(SEPARATOR), null]) {
const end = m?.index ?? text.length
const seg = text.slice(from, end)
const hit = seg.includes('-b') && CURL_SEGMENT.test(seg)
parts.push(hit ? seg.replace(COOKIE_FLAG, '-b <redacted>') : seg)
parts.push(m?.[0] ?? '')
from = end + (m?.[0].length ?? 0)
}
return parts.join('')
}
/** Masks secret-shaped text; reads at most the first 64 KiB. */
export function redact(text: string): string {
let out = redactCurlCookie(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(IO_ERROR, '<errno>') // before PATH reads its slash
.replace(HEX_RUN, '<hex>')
.replace(PATH, '<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_SPAN = 300 // a registry span is capped before normalize
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+/
export const ERRORISH = new RegExp(
'error|fatal|cannot|can\'t|no such|not found|denied|failed|failure|' +
'unexpected|invalid|exception|traceback|panic|usage:|SC\\d{4}|' +
'> \\d+|assert',
'i',
)
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 redacted line holds no
* letter or is not error-shaped (`ERRORISH`); no earlier line is tried.
*/
export function failureLine(text: string): string | undefined {
return EXIT_CODE.test(text) ? lastLine(text) : undefined
}
/** The error-shaped last line of a redacted text with a letter in it. */
function lastLine(text: string): string | 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)
return hasLetter(line) && ERRORISH.test(line) ? line : undefined
}
/** A letter outside the `<path>`, `<hex>` and `#` placeholders. */
function hasLetter(line: string): boolean {
return /\p{L}/u.test(normalize(line).replace(/<path>|<hex>/g, ''))
}
function isSession(v: unknown): v is Session {
const s = v as Partial<Session> | 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<Project> | 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<Project> {
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 {
if (!EXIT_CODE.test(text)) return undefined
const red = redact(tail(text, MAX_REGEX_INPUT))
const line = lastLine(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<void> {
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<Held[]> {
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<void> {
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)
}
}
// The engine rejects every `$.store.set` once the store passes 4 MiB in all.
// The `p:` keys are swept at STORE_CAP; the `l:` keys are swept here, oldest
// first, so the two together stay under the engine cap and capture lives.
const ENGINE_CAP = 4194304
const ENGINE_MARGIN = 131072 // room for the next session and log write
type Weighed = { key: string; size: number; at: number }
/** A store key's bytes and, for a log, the `at` of its newest record. */
async function weigh($: Api, key: string): Promise<Weighed> {
const raw = await $.store.get(key)
const size = JSON.stringify(raw ?? null).length
const times = Array.isArray(raw) ? raw.filter(isLogRecord).map(r => r.at) : []
return { key, size, at: Math.max(0, ...times) }
}
/**
* Deletes the oldest `l:` keys, by their newest record, while the `p:`
* and `l:` keys together pass the engine cap. Never the `keep` key.
*/
async function sweepLogs($: Api, keep: string): Promise<void> {
const ours = (await $.store.keys())
.filter(k => k.startsWith(STORE_PREFIX) || k.startsWith(LOG_PREFIX))
const all = await Promise.all(ours.map(k => weigh($, k)))
let total = all.reduce((n, w) => n + w.size, 0)
const logs = all.filter(w => w.key.startsWith(LOG_PREFIX) && w.key !== keep)
.sort((a, b) => a.at - b.at)
for (const w of logs) {
if (total <= ENGINE_CAP - ENGINE_MARGIN) break
await $.store.delete(w.key)
total -= w.size
}
}
// The registry error index: which captured failures a registry knows.
const MAX_REGISTRY = 4194304
const MIN_SPAN = 12
const GRAM_WORDS = 4
// the ID only: a bounded capture carries no `$`, so a long heading stays one
const HEADING = /^## ((?:BDR|LRN|BLK)-\d+)\b/gm
const SPAN = /`([^`\n]+)`/g
const STATUS_WAIT_MS = 2500 // our own race over the process's 2000 ms
const STATUS_TIMEOUT_MS = 2000
const MAX_INDEX_ROW = 1000
const DEAD = new Set(['superseded', 'deprecated'])
const INDEX_ROW = new RegExp(
'^\\|[ \\t]{0,5}((?:BDR|LRN|BLK)-\\d+)[ \\t]{0,5}\\|[^|]{0,40}\\|' +
'(.{0,900})\\|([^|]{0,100})\\|[ \\t]{0,5}$',
)
const MAX_TITLE = 100
const MAX_LESSON = 280
const MAX_FIELD = 2000
const LESSON_LABELS: Record<Kind, string[]> = {
BDR: ['Decision'],
LRN: ['Apply', 'Future application', 'Pattern'],
BLK: ['Solution', 'Real cause'],
}
export type Kind = 'BDR' | 'LRN' | 'BLK'
export type Entry = {
id: string
kind: Kind
title: string
lesson: string
body: string
}
type Part = { id: string; body: string }
type Listed = { status: string; title: string }
export type StatusMap = Map<string, Listed>
type Read = { text: string } | { why: string }
/** True only when exists says no; a throwing probe cannot tell. */
async function isGone($: Api, path: string): Promise<boolean> {
try {
return !(await $.fs.exists(path))
} catch {
return false
}
}
/** One stat, one read: the text, or why the registry is skipped. */
// a rejected stat means missing only when exists says so
async function tryRead($: Api, path: string): Promise<Read> {
try {
const info = await $.fs.stat(path)
if (info.kind !== 'file') return { why: 'not a file' }
if (info.size > MAX_REGISTRY) return { why: 'over 4 MiB' }
} catch {
return { why: (await isGone($, path)) ? 'missing' : 'unreadable' }
}
try {
return { text: await $.fs.read(path) }
} catch {
return { why: 'unreadable' }
}
}
/** The entries' ID and body; a body runs from its heading to the next. */
export function entriesOf(text: string): Part[] {
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),
}))
}
/**
* ID -> status word and title, from the rows `memory.sh index` prints
* (`| ID | Date | Title | Status |`); the status is its lowercased first
* word, `''` when empty.
*/
export function parseIndex(stdout: string): StatusMap {
const rows: StatusMap = new Map()
for (const line of stdout.split('\n')) {
const m = INDEX_ROW.exec(line.slice(0, MAX_INDEX_ROW))
if (m === null) continue
const word = (m[3] ?? '').trim().match(/^[A-Za-z]+/)?.[0] ?? ''
const title = (m[2] ?? '').trim()
rows.set(m[1] ?? '', { status: word.toLowerCase(), title })
}
return rows
}
/** False when the ID is superseded or deprecated, or the map lacks it. */
export function isLive(status: StatusMap, id: string): boolean {
const row = status.get(id)
return row !== undefined && !DEAD.has(row.status)
}
/** `text` cut to `n` characters, the last one `…` when it was cut. */
function clip(text: string, n: number): string {
return text.length > n ? `${text.slice(0, n - 1)}…` : text
}
/** The first sentence: up to `. ` or `; ` before a capital, or the end. */
function firstSentence(field: string): string {
return /^(.*?[.;])(?:[ \t]+(?=[A-Z])|$)/.exec(field)?.[1] ?? field
}
/**
* The one-line lesson of an entry: the first sentence of its first labelled
* field, in the order of its kind; `''` when none is there.
*/
export function lessonOf(kind: Kind, body: string): string {
for (const label of LESSON_LABELS[kind]) {
const line = new RegExp(
`^[ \\t]*-[ \\t]*(?:\\*\\*)?${label}(?:\\*\\*)?[ \\t]*:[ \\t]*` +
`(.{0,${MAX_FIELD}})`,
'im',
).exec(body)
const field = (line?.[1] ?? '').trim()
if (line !== null) return clip(firstSentence(field), MAX_LESSON)
}
return ''
}
/** The entries of registry texts, titled by `memory.sh index`'s rows. */
export function assembleEntries(texts: string[], index: StatusMap): Entry[] {
return texts.flatMap(entriesOf).map(({ id, body }) => {
const kind = id.slice(0, 3) as Kind
const title = clip(index.get(id)?.title ?? '', MAX_TITLE)
return { id, kind, title, lesson: lessonOf(kind, body), body }
})
}
export const ERRNO_PHRASES: readonly string[] = [
'no such file or directory', 'permission denied', 'command not found',
'is a directory', 'not a directory', 'file exists',
'directory not empty', 'operation not permitted',
'no space left on device', 'connection refused', 'connection timed out',
'broken pipe', 'resource temporarily unavailable', 'invalid argument',
'too many open files', 'read-only file system',
'device or resource busy', 'input/output error',
]
// Word-bounded literals; `input/output error` is already `<errno>` here.
const ERRNO = new RegExp(
`(?<![a-z0-9])(?:${ERRNO_PHRASES.join('|')})(?![a-z0-9])`, 'g')
/** Each errno phrase of a normalized line, as `<errno>`. */
export function deErrno(normLine: string): string {
return normLine.replace(ERRNO, '<errno>')
}
const PLACEHOLDERS = new Set(['#', '<path>', '<hex>', '<errno>'])
/**
* Every window of 4 words, except one made only of placeholders (it
* carries no content); a key of fewer words has none (always NEW).
*/
export function grams(normLine: string): string[] {
const words = deErrno(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))
.filter(win => !win.every(w => PLACEHOLDERS.has(w)))
.map(win => win.join(' '))
}
function spansOf(body: string): string[] {
return [...body.matchAll(SPAN)]
.map(m => (m[1] ?? '').slice(0, MAX_SPAN))
.filter(span => span.length >= MIN_SPAN)
}
function indexEntry(index: Map<string, string>, entry: Entry): void {
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. Without
* statuses (`undefined`) every entry is indexed: advisory, never injected.
*/
export function buildIndex(
entries: Entry[],
status: StatusMap | undefined,
): Map<string, string> {
const index = new Map<string, string>()
for (const entry of entries) {
if (status === undefined || isLive(status, entry.id)) {
indexEntry(index, entry)
}
}
return index
}
/** The registry ID of the first gram of `key` the index holds. */
export function matchOf(
index: Map<string, string>,
key: string,
): string | undefined {
for (const gram of grams(key)) {
const id = index.get(gram)
if (id !== undefined) return id
}
return undefined
}
/** The stdout of `argv` on exit 0; `undefined` on any other end or 2.5 s. */
async function runWithin($: Api, argv: string[]): Promise<string | undefined> {
const stop = new AbortController()
const timer = $.clock.sleep(STATUS_WAIT_MS, { signal: stop.signal })
.then(() => undefined, () => undefined)
const run = $.process.run(argv, { timeoutMs: STATUS_TIMEOUT_MS })
.then(r => (r.exitCode === 0 ? r.stdout : undefined), () => undefined)
try {
return await Promise.race([run, timer])
} finally {
stop.abort()
}
}
/** The statuses `memory.sh index` prints; `undefined` when unavailable. */
async function statusMap($: Api, root: string): Promise<StatusMap | undefined> {
try {
const home = await $.env.get('HOME')
if (!home) return undefined
const out = await runWithin(
$, ['bash', `${home}/.claude/lib/memory.sh`, '-C', root, 'index'])
const rows = out === undefined ? undefined : parseIndex(out)
return rows?.size ? rows : undefined
} catch {
return undefined
}
}
// Function words, 3+ letters first, then the 2-letter FR and EN ones: TOKEN
// takes 2+ letters, so without them "ok tu peux continuer la suite stp"
// counts 7 content words and passes the floor. At most 120 words.
const STOP_WORDS = new Set(
('the and for with that this from are was were not but you your have has ' +
'had will can all any its into than then them they their there what ' +
'when which who how why les des une pour dans avec est pas que qui sur ' +
'par aux ces ses son mais ont sont plus comme ' +
'ok tu je il on la le de du et en un au ce se sa ne ni ou si ' +
'is it to do of in at an be by or as if so we me my no go up').split(' '),
)
const TOKEN = /[\p{L}\p{N}]{2,40}/gu
const MAX_QUERY = 2000
const MAX_DOC = 65536
const BM25_K1 = 1.2
const BM25_B = 0.75
const MAX_PICKS = 3
/** Lowercase word runs (2-40 letters or digits) minus function words. */
export function tokensOf(text: string): string[] {
const words = cap(text, MAX_DOC).toLowerCase().match(TOKEN) ?? []
return words.filter(w => !STOP_WORDS.has(w))
}
type Doc = { entry: Entry; tf: Map<string, number>; len: number }
function docOf(entry: Entry): Doc {
const tokens = tokensOf(`${entry.title} ${entry.lesson} ${entry.body}`)
const tf = new Map<string, number>()
for (const t of tokens) tf.set(t, (tf.get(t) ?? 0) + 1)
return { entry, tf, len: tokens.length }
}
function scoreOf(
doc: Doc, terms: string[], df: Map<string, number>, n: number, avg: number,
): number {
let score = 0
for (const term of terms) {
const f = doc.tf.get(term) ?? 0
if (f === 0) continue
const d = df.get(term) ?? 0
const idf = Math.log(1 + (n - d + 0.5) / (d + 0.5))
const norm = 1 - BM25_B + (BM25_B * doc.len) / avg
score += (idf * f * (BM25_K1 + 1)) / (f + BM25_K1 * norm)
}
return score
}
/** The `k` best entries for a query (BM25), highest first, score > 0. */
export function bm25Rank(entries: Entry[], query: string, k: number): Entry[] {
const terms = [...new Set(tokensOf(cap(query, MAX_QUERY)))]
const docs = entries.map(docOf)
const df = new Map<string, number>()
for (const d of docs) for (const t of d.tf.keys()) {
df.set(t, (df.get(t) ?? 0) + 1)
}
const avg = docs.reduce((sum, d) => sum + d.len, 0) / (docs.length || 1)
return docs
.map(d => ({ e: d.entry, s: scoreOf(d, terms, df, docs.length, avg || 1) }))
.filter(x => x.s > 0)
.sort((a, b) => b.s - a.s ||
a.e.id.localeCompare(b.e.id, 'en', { numeric: true }))
.slice(0, k)
.map(x => x.e)
}
/** 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: ${asked}\nCandidates:\n` +
`${lines.join('\n')}\nAnswer with at most ${MAX_PICKS} candidate IDs ` +
'that would help with this prompt, comma separated, or none.'
)
}
const ID_IN_ANSWER = /(?:BDR|LRN|BLK)-\d{1,5}/g
/** The candidate IDs named in a model answer, deduplicated, in order. */
export function parseIds(text: string, cands: Entry[], max: number): string[] {
const known = new Set(cands.map(c => c.id))
const found = cap(text, MAX_REGEX_INPUT).match(ID_IN_ANSWER) ?? []
return [...new Set(found)].filter(id => known.has(id)).slice(0, max)
}
/** One recall line; the lesson keeps its own terminator. */
export function recallLine(e: Entry): string {
const head = `${e.id} ${e.title}`
return e.lesson === '' ? head : `${head} — ${e.lesson}`
}
const RECALL_HEADER = 'memory recall:'
/** The injected block; a line that would pass `max` characters is dropped. */
export function recallBlock(lines: string[], max: number): string {
const header = RECALL_HEADER
let block = header
for (const line of lines) {
if (block.length + 1 + line.length <= max) block += `\n${line}`
}
return block === header ? '' : block
}
/** 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)
}
type Registries = {
entries: Entry[]
status: StatusMap | undefined
index: Map<string, string>
note: string
}
type Loaded = { texts: string[]; note: string }
/** The texts of the named registries and the first part of the note. */
async function readRegistries(
$: Api,
root: string,
names: string[],
): Promise<Loaded> {
const texts: string[] = []
const read: string[] = []
const skipped: string[] = []
for (const name of names) {
const r = await tryRead($, `${root}/.claude/memory/${name}`)
if ('why' in r) {
skipped.push(`${name} (${r.why})`)
continue
}
texts.push(r.text)
read.push(name)
}
const parts = [
read.length > 0 ? `read ${read.join(', ')}` : '',
skipped.length > 0 ? `skipped ${skipped.join(', ')}` : '',
]
return { texts, note: `index: ${parts.filter(Boolean).join('; ')}` }
}
const FAILURE_FILES = ['blockers.md', 'learnings.md']
const FAILURE_KINDS = new Set<Kind>(['BLK', 'LRN'])
/**
* The entries of the named registries with their statuses, and the error
* index over the BLK and LRN ones. No registry read: no process run.
*/
async function loadRegistries(
$: Api,
root: string,
names: string[],
): Promise<Registries> {
const { texts, note } = await readRegistries($, root, names)
const status = texts.length > 0 ? await statusMap($, root) : undefined
const entries = assembleEntries(texts, status ?? new Map())
const failing = entries.filter(e => FAILURE_KINDS.has(e.kind))
const lost = texts.length > 0 && status === undefined
return {
entries,
status,
index: buildIndex(failing, status),
note: lost ? `${note}; status reader unavailable` : note,
}
}
// 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'
const NEWLINES = /\r\n?|\n/g
const isText = (...v: unknown[]) => v.every(x => typeof x === 'string')
/** The store is data: a malformed element is skipped, never thrown on. */
function isFailure(v: unknown): v is Failure {
const f = v as Partial<Failure> | null
return typeof f === 'object' && f !== null &&
isText(f.key, f.line, f.excerpt, f.command) &&
Number.isFinite(f.count)
}
function isMilestone(v: unknown): v is Milestone {
const m = v as Partial<Milestone> | null
return typeof m === 'object' && m !== null && isText(m.kind, m.label) &&
Number.isFinite(m.at) && Math.abs(m.at as number) < 8.64e15
}
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<string, string>) {
const rows: Row[] = p.sessions.flatMap(s =>
s.failures.filter(isFailure).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 cmd = f.command.replace(NEWLINES, '⏎')
const line = f.line.replace(NEWLINES, '⏎')
const head = `- ${tag} ×${f.count}${marks} ${line} — command: ${cmd}`
if (f.excerpt === '') return head
const shown = tail(f.excerpt, EXCERPT_SHOWN).replace(NEWLINES, '⏎')
return `${head}\n excerpt: ${shown}`
}
function milestoneText(m: Milestone, earlier = false): string {
const d = new Date(m.at)
const two = (n: number) => String(n).padStart(2, '0')
const hhmm = `${two(d.getHours())}:${two(d.getMinutes())}`
const mark = earlier ? ' (earlier session)' : ''
return `- ${m.kind} ${m.label} (${hhmm})${mark}`
}
/** Current session first, then the earlier ones, newest session first. */
function milestoneLines(p: Project, curId: string): string[] {
const lines = (s: Session) => s.milestones.filter(isMilestone)
.map(m => milestoneText(m, s.id !== curId))
const cur = p.sessions.filter(s => s.id === curId)
const old = p.sessions.filter(s => s.id !== curId)
.sort((a, b) => b.at - a.at)
return [...cur, ...old].flatMap(lines)
}
/** 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 = milestoneLines(p, curId)
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:', ...ms)
}
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<void>): Promise<void> {
const run = st.writes.then(job)
st.writes = run.catch(() => undefined)
return run
}
export type Trigger = 'fresh' | 'idle' | 'keyword' | 'tool'
export type Outcome = 'injected' | 'none' | 'timeout' | 'refused' | 'paused'
const TRIGGERS: string[] = ['fresh', 'idle', 'keyword', 'tool']
const OUTCOMES: string[] = ['injected', 'none', 'timeout', 'refused', 'paused']
// `trigger` and `outcome` are absent on records written before 4c's review.
export type LogRecord = {
at: number
session: string
agent: string
channel: 'prompt' | 'tool'
ids: string[]
trigger?: Trigger
outcome?: Outcome
}
// shortcut: one `l:<root>` key per project (about 28 KiB at 200 records),
// swept by `sweepLogs` against the engine's 4 MiB store cap, oldest key
// first; upgrade path: one global log key, or a smaller per-root cap.
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<LogRecord> | 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') &&
(r.trigger === undefined || TRIGGERS.includes(r.trigger)) &&
(r.outcome === undefined || OUTCOMES.includes(r.outcome))
}
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<LogRecord[]> {
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<void> {
return queueWrite(st, async () => {
const log = await loadLog($, root)
if (log.length === 0) await sweepLogs($, logKey(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. */
async function mutateSession(
$: Api,
at: Where,
now: number,
change: (s: Session) => void,
): Promise<void> {
const p = await loadProject($, at.root)
const created = !p.sessions.some(s => s.id === at.id)
change(sessionOf(p, at.id, now))
await saveProject($, at.root, p)
if (created) {
await sweepStore($, storeKey(at.root), at.id)
await sweepLogs($, logKey(at.root))
}
}
const recordFailure = ($: Api, at: Where, f: Failure) =>
mutateSession($, at, f.at, s => addFailure(s, f))
// Milestones: a commit, a gitflow finish, a suite gone from red to green.
// Regexes read at most 64 KiB of one command and use bounded repeats.
const MAX_LABEL = 80
const MAX_PENDING = 20
const ENV_PREFIX = '(?:[A-Za-z_]\\w{0,60}=\\S{0,200}[ \\t]{1,5}){0,10}'
const SUITE_SEGMENT = new RegExp(
`^${ENV_PREFIX}make\\b[^;&|]{0,1000}\\btest\\b`,
)
const COMMIT_SEGMENT = new RegExp(
`^[(\\s]{0,5}(?:rtk[ \\t]{1,5})?${ENV_PREFIX}` +
'git(?:[ \\t]{1,5}-C[ \\t]{1,5}\\S{1,200})?[ \\t]{1,5}commit\\b',
)
const CONVENTIONAL = '(feat|fix)(\\([^)\\n]{0,80}\\))?!?:[ \\t]{0,5}'
const COMMIT_MESSAGE = new RegExp(
`-[a-z]{0,5}m[ \\t]{1,5}(["']?)${CONVENTIONAL}([^"'\\n]{0,300})`,
)
// -m "$(cat <<'EOF' newline subject: the subject is the first body line
const COMMIT_HEREDOC = new RegExp(
'-[a-z]{0,5}m[ \\t]{1,5}"\\$\\(cat[ \\t]{1,5}<<-?["\']?' +
'[A-Za-z_]{1,20}["\']?[ \\t]{0,5}\\n[ \\t]{0,20}' +
`${CONVENTIONAL}([^\\n]{0,300})`,
)
const FINISH = new RegExp(
`^${ENV_PREFIX}(?:bash|sh)[ \\t]{1,5}\\S{0,200}gitflow\\.sh"?` +
'[ \\t]{1,5}finish\\b(?:[ \\t]{1,5}([a-z]{1,20})[ \\t]{1,5}' +
'([\\w.=/-]{1,60}))?',
)
const FINISH_CHORE = /\bfinish[ \t]{1,5}chore\b/
/** The `;` `&&` `||` newline separated parts of a command. */
export function segments(command: string): string[] {
return cap(command, MAX_REGEX_INPUT).split(/&&|\|\||;|\n/)
.map(s => s.trim())
}
const label = (text: string) => redact(text).slice(0, MAX_LABEL)
/** The redacted, whitespace-normalized command when it runs a suite. */
export function suiteKeyOf(command: string): string | undefined {
if (!segments(command).some(s => SUITE_SEGMENT.test(s))) return undefined
return redact(cap(command, MAX_REGEX_INPUT)).replace(/\s+/g, ' ').trim()
.slice(0, MAX_RED_LEN)
}
function conventional(type?: string, scope?: string, subject?: string) {
return label(`${type}${scope ?? ''}: ${(subject ?? '').trim()}`)
}
/** `<type><scope>: <subject>` of a feat/fix commit, else `undefined`. */
export function commitLabel(command: string): string | undefined {
const text = cap(command, MAX_REGEX_INPUT)
const seg = segments(command).find(s => COMMIT_SEGMENT.test(s))
if (seg === undefined) return undefined
const rest = text.slice(Math.max(0, text.indexOf(seg)))
const h = COMMIT_HEREDOC.exec(rest)
if (h !== null) return conventional(h[1], h[2], h[3])
const m = COMMIT_MESSAGE.exec(seg)
return m === null ? undefined : conventional(m[2], m[3], m[4])
}
/** `<type> <name>` after a gitflow finish, `finish` alone, or undefined. */
export function finishLabel(command: string): string | undefined {
for (const seg of segments(command)) {
const m = FINISH.exec(seg)
if (m === null || FINISH_CHORE.test(seg)) continue
return m[1] === undefined ? 'finish' : label(`${m[1]} ${m[2]}`)
}
return undefined
}
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(),
rerank: { fails: 0, until: 0 },
}
}
/** Logs a hook's fail-open once per session; never throws itself. */
function warnOnce(st: State, $: Api, hook: string, kind: string): void {
logOnce(st, $, hook, `memory: ${hook} hook failed (${kind}); passed through`)
}
/** Logs `text` once per session under `key`; never throws itself. */
function logOnce(st: State, $: Api, key: string, text: string): void {
if (st.warned.has(key)) return
st.warned.add(key)
try {
$.ui.log(text)
} catch {
// a failing log must not break the fail-open itself
}
}
type Switch = { enabled: boolean; recall: boolean }
/**
* 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.
*/
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<Switch> {
const on = { enabled: true, recall: true }
let path = ''
try {
const home = await $.env.get('HOME')
if (!home) return on
path = `${home}/${SWITCH_FILE}`
const info = await $.fs.stat(path)
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 on
}
}
/** The tool the model calls to list the failures and milestones captured. */
async function registerTool($: Api): Promise<void> {
try {
await $.tool.register({
name: TOOL,
description:
'Failures and milestones this mod captured in the current ' +
'project\'s recent sessions, each failure NEW or known <registry ' +
'ID>. 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')
}
}
/**
* 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<boolean> {
if (st.enabled !== null) return st.enabled
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<boolean> {
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 reads, 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<string>()
let spent = st.spent.get(key) ?? 0
const taken: string[] = []
ids.forEach((id, i) => {
const cost = chars[i]
// a missing cost refuses the id: unknown is not free
if (cost === undefined || 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<string> {
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)
const rx = await loadRegistries($, root, FAILURE_FILES)
return formatPending(root, project, id, rx)
}
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`,
}
})
}
/** 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)
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.recall = null
st.pending = []
st.warned.clear()
endContext(st, e.sessionId)
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<Failure | undefined> {
try {
if (out.isError !== true) return undefined
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))
return f
} catch {
warnOnce(st, $, 'Bash capture', 'store')
return undefined
}
}
type BashEvent = {
command?: unknown
agentId?: unknown
run_in_background?: unknown
}
type BashOut = {
isError?: boolean
deny?: unknown
text?: string
result?: {
backgroundTaskId?: unknown
timedOutAfterMs?: unknown
interrupted?: unknown
}
}
/** A finished foreground command that was neither denied nor failed. */
function isSuccess(e: BashEvent, out: BashOut): boolean {
const r = out.result
return out.isError !== true && out.deny === undefined &&
r?.backgroundTaskId === undefined && r?.timedOutAfterMs === undefined &&
r?.interrupted !== true && e.run_in_background !== true
}
/** The suite a failed command ran, remembered as red until it passes. */
function recordRed($: Api, st: State, at: Where, key: string, now: number) {
return queueWrite(st, () => mutateSession($, at, now, s => {
if (!s.red.includes(key)) s.red = [...s.red, key]
}))
}
/** `commit fix: x`; a bare `finish` is not said twice. */
const noteLabel = (m: Milestone) =>
m.label === m.kind ? m.kind : `${m.kind} ${m.label}`
/** Commit and finish milestones of a success; green when the suite was red. */
function recordSuccess(
$: Api,
st: State,
at: Where,
command: string,
now: number,
): Promise<void> {
const found = [
['commit', commitLabel(command)],
['finish', finishLabel(command)],
].filter((m): m is [Milestone['kind'], string] => m[1] !== undefined)
const key = suiteKeyOf(command)
if (found.length === 0 && key === undefined) return Promise.resolve()
return queueWrite(st, async () => {
const cur = (await loadProject($, at.root)).sessions
.find(s => s.id === at.id)
const green = key !== undefined && cur?.red.includes(key) === true
if (found.length === 0 && !green) return
const added = found.map(([kind, text]) => ({ kind, label: text, at: now }))
if (green) added.push({ kind: 'green', label: label(key), at: now })
await mutateSession($, at, now, s => {
s.milestones = [...s.milestones, ...added]
if (green) s.red = s.red.filter(r => r !== key)
})
st.pending = [...st.pending, ...added.map(noteLabel)].slice(-MAX_PENDING)
})
}
/** Milestones of a main-loop Bash answer; never throws. */
async function captureMilestones(
$: Api,
st: State,
at: Where,
e: BashEvent,
out: BashOut,
): Promise<void> {
try {
if (e.agentId !== undefined) return
const command = String(e.command ?? '')
const now = await $.clock.now()
const key = suiteKeyOf(command)
if (out.isError === true) {
if (key !== undefined && EXIT_CODE.test(String(out.text ?? ''))) {
await recordRed($, st, at, key, now)
}
} else if (isSuccess(e, out)) {
await recordSuccess($, st, at, command, now)
}
} catch {
warnOnce(st, $, 'Bash milestones', 'store')
}
}
/**
* The live BLK or LRN entry `key` matches. A match on every entry gates
* the status reader; the live entry is then rematched on the statuses.
*/
async function liveCandidate(
$: Api,
root: string,
key: string,
): Promise<Entry | undefined> {
const { texts } = await readRegistries($, root, FAILURE_FILES)
const all = assembleEntries(texts, new Map())
const failing = all.filter(e => FAILURE_KINDS.has(e.kind))
const id = matchOf(buildIndex(failing, undefined), key)
if (id === undefined) return undefined
const status = await statusMap($, root)
if (status === undefined) return undefined
const entries = assembleEntries(texts, status)
const kept = entries.filter(e => FAILURE_KINDS.has(e.kind))
const liveId = matchOf(buildIndex(kept, status), key)
return entries.find(e => e.id === liveId)
}
/**
* The known-error line of a failure: `memory: known <entry>` when a live
* BLK or LRN matches and the context has not seen it nor spent its budget.
* '' otherwise. Claims synchronously once the reads are done; only the
* log write follows.
*/
async function knownLine(
$: Api,
st: State,
at: Where,
f: Failure,
agent: string | undefined,
): Promise<string> {
if (!(await ensureRecall($, st))) return ''
const entry = await liveCandidate($, at.root, f.key)
if (entry === undefined) return ''
const line = `memory: known ${recallLine(entry)}`
const key = contextKey(at.id, agent)
const now = await $.clock.now()
if (claim(st, key, [entry.id], [line.length]).length === 0) return ''
const record = { at: now, session: at.id, ids: [entry.id] }
await appendLog($, st, at.root, {
...record, agent: agent ?? 'main', channel: 'tool',
trigger: 'tool', outcome: 'injected',
}).catch(() => undefined)
return line
}
/** The known line of a failing answer; '' on any failure (fail open). */
async function knownContext(
$: Api,
st: State,
at: Where,
e: BashEvent,
f: Failure | undefined,
): Promise<string> {
if (f === undefined) return ''
try {
const agent = typeof e.agentId === 'string' ? e.agentId : undefined
return await knownLine($, st, at, f, agent)
} catch {
warnOnce(st, $, 'Bash known', 'recall')
return ''
}
}
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)
const f = await captureFailure($, st, at, e, out)
await captureMilestones($, st, at, e, out as BashOut)
const line = await knownContext($, st, at, e, f)
if (line === '') return out
return { ...out, context: [...(out.context ?? []), line] }
}).catch(($, e, next) => {
warnOnce(st, $, 'Bash', next.error.kind)
return next(e)
})
}
/** Failures of the current session no registry entry knows. */
async function newFailureCount(
$: Api,
st: State,
at: Where,
index: Map<string, string>,
): Promise<number> {
await st.writes
const p = await loadProject($, at.root)
const cur = p.sessions.find(s => s.id === at.id)
return (cur?.failures ?? []).filter(isFailure)
.filter(f => matchOf(index, f.key) === undefined).length
}
/** The note for the oldest unnoted milestone; clears what it covers. */
async function noteFor(
$: Api,
st: State,
at: Where,
rx: Registries,
): Promise<string> {
const first = st.pending[0] ?? ''
st.pending = []
const n = await newFailureCount($, st, at, rx.index)
return `memory: ${first} \u2014 ${n} new failure mode(s) this session;` +
' /capitalize when ready.'
}
// The default prompt rules of the model router (mods/model-router, commit
// 9bbd1d5): a prompt that designs or analyses asks for recall.
const WORD_BEFORE = '(?<![\\p{L}\\p{N}-])'
const WORD_AFTER = '(?![\\p{L}\\p{N}-])'
const wordRule = (words: string) =>
new RegExp(`${WORD_BEFORE}(${words})${WORD_AFTER}`, 'iu')
export const DESIGN_RULE = wordRule(
'plan|planifie|planning|brainstorm|architecture|con[c\\u00e7]ois|design',
)
export const ANALYSIS_RULE = wordRule(
'pourquoi|why|explique|explain|analyse|analyze|comprendre|understand|' +
'review|audit',
)
const MIN_PROMPT = 12 // code points
// Measurement gate: fewer content words than this never asks for recall.
export const MIN_CONTENT_WORDS = 5
const MAX_CANDS = 30
const RERANK_FAILS = 3 // failed reranks in a row that pause it
const RERANK_PAUSE_MS = 900000
/** What made a prompt ask for recall: a fresh context, idle, or a rule. */
export function triggerKind(
text: string,
fresh: boolean,
idleMs: number,
): Exclude<Trigger, 'tool'> | undefined {
if (text.startsWith('/') || Array.from(text).length < MIN_PROMPT) {
return undefined
}
if (tokensOf(text).length < MIN_CONTENT_WORDS) return undefined
if (fresh) return 'fresh'
if (idleMs >= IDLE_MS) return 'idle'
const asked = cap(text, MAX_REGEX_INPUT)
return DESIGN_RULE.test(asked) || ANALYSIS_RULE.test(asked)
? 'keyword'
: undefined
}
/** True when a prompt may ask for recall. */
export const isTrigger = (text: string, fresh: boolean, idleMs: number) =>
triggerKind(text, fresh, idleMs) !== undefined
/** Counts a rerank: the third failure in a row pauses it for 15 min. */
function countRerank(st: State, ok: boolean, now: number): void {
if (ok) {
st.rerank.fails = 0
return
}
st.rerank.fails += 1
if (st.rerank.fails < RERANK_FAILS) return
st.rerank = { fails: 0, until: now + RERANK_PAUSE_MS }
}
/** The haiku answer, or undefined: failed, unanswered or late. */
async function askRerank(
$: Api,
st: State,
text: string,
cands: Entry[],
now: number,
): Promise<string | undefined> {
const ask = {
model: HAIKU,
prompt: rerankPrompt(text, cands),
effort: 'low' as const,
maxTokens: 64,
timeoutMs: RERANK_MS,
}
const call = $.model.complete(ask).catch((): undefined => undefined)
const late = $.clock.sleep(RERANK_MS).then((): undefined => undefined)
const out = await Promise.race([call, late])
const answer = out?.isAnswered === true ? out.text : undefined
countRerank(st, answer !== undefined, now)
return answer
}
/** Live entries of the context not injected yet, best BM25 first. */
function candidatesFor(
st: State,
key: string,
rx: Registries,
text: string,
): Entry[] {
const { status } = rx
if (status === undefined) return []
const seen = st.seen.get(key)
const open = rx.entries.filter(e => isLive(status, e.id) && !seen?.has(e.id))
return bm25Rank(open, text, MAX_CANDS)
}
type Ask = { at: Where; text: string; trigger: Exclude<Trigger, 'tool'> }
type Picked = { block: string; ids: string[]; outcome: Outcome }
const nothing = (outcome: Outcome): Picked => ({ block: '', ids: [], outcome })
/** The candidates a model answer names, in the answer's order. */
function picksOf(answer: string, cands: Entry[]): Entry[] {
const byId = new Map(cands.map(c => [c.id, c]))
return parseIds(answer, cands, MAX_PICKS).flatMap(id => byId.get(id) ?? [])
}
/** Claims the picks one by one; the header is charged to the first taken. */
function claimPicks(st: State, key: string, picked: Entry[]): string[] {
const taken: string[] = []
for (const e of picked) {
const header = taken.length === 0 ? RECALL_HEADER.length : 0
taken.push(...claim(st, key, [e.id], [recallLine(e).length + 1 + header]))
}
return taken
}
/** Asks haiku among the candidates and claims its picks. */
async function pickRecall(
$: Api,
st: State,
key: string,
text: string,
cands: Entry[],
): Promise<Picked> {
const now = await $.clock.now()
if (now < st.rerank.until) return nothing('paused')
const answer = await askRerank($, st, text, cands, now)
if (answer === undefined) return nothing('timeout')
const picked = picksOf(answer, cands)
if (picked.length === 0) return nothing('none')
const taken = claimPicks(st, key, picked)
const block = recallBlock(
picked.filter(e => taken.includes(e.id)).map(recallLine), RECALL_CAP)
if (block === '') return nothing('refused')
return { block, ids: taken, outcome: 'injected' }
}
/**
* The recall block for a prompt: BM25 candidates, haiku picks, the ledger
* claim. Every ask is logged with its outcome; '' when nothing is injected.
*/
async function recallFor(
$: Api,
st: State,
ask: Ask,
rx: Registries,
): Promise<string> {
const key = contextKey(ask.at.id, undefined)
const cands = candidatesFor(st, key, rx, ask.text)
const got = cands.length === 0
? nothing('none')
: await pickRecall($, st, key, ask.text, cands)
const record = {
at: await $.clock.now(), session: ask.at.id, agent: 'main',
ids: got.ids, trigger: ask.trigger, outcome: got.outcome,
}
await appendLog($, st, ask.at.root, { ...record, channel: 'prompt' })
.catch(() => undefined)
return got.block
}
const ALL_FILES = ['decisions.md', ...FAILURE_FILES]
/** The contexts a prompt adds: the 4b note, then the recall block. */
async function additions(
$: Api,
st: State,
at: Where,
text: string,
trigger: Ask['trigger'] | undefined,
): Promise<string[]> {
const rx = await loadRegistries($, at.root, ALL_FILES)
// separate failures: a throw in one never drops the other
const note = st.pending.length > 0
? await noteFor($, st, at, rx).catch(() => {
warnOnce(st, $, 'prompt.submit', 'note')
return ''
})
: ''
const block = trigger !== undefined
? await recallFor($, st, { at, text, trigger }, rx).catch(() => '')
: ''
return [note, block].filter(part => part !== '')
}
type PromptIn = {
text: string
turnId?: string | undefined
origin: { kind: string }
}
/**
* The contexts to append to a composer prompt; [] for any other prompt. A
* new prompt starts a new turn: the main key's `spent` budget resets.
*/
export async function promptContext(
$: Api,
st: State,
e: PromptIn,
): Promise<string[]> {
if (!(await ensureEnabled($, st))) return []
if (e.origin.kind !== 'composer' || e.turnId !== undefined) return []
const at = { root: await $.session.root(), id: await $.session.id() }
if (at.root === '') return []
const now = await $.clock.now()
const last = st.lastPrompt.get(at.id)
const idle = last === undefined ? 0 : now - last // unknown: not idle
st.lastPrompt.set(at.id, now)
st.spent.delete(contextKey(at.id, undefined))
const trigger = (await ensureRecall($, st))
? triggerKind(e.text, st.fresh.has(at.id), idle)
: undefined
if (trigger !== undefined) st.fresh.delete(at.id)
if (trigger === undefined && st.pending.length === 0) return []
return additions($, st, at, e.text, trigger)
}
function registerPrompt(on: On, st: State): void {
on('prompt.submit', async ($, e, next) => {
const added = await promptContext($, st, e)
if (added.length === 0) return next(e)
return next({ ...e, context: [...(e.context ?? []), ...added] })
}).catch(($, e, next) => {
warnOnce(st, $, 'prompt.submit', next.error.kind)
return next(e)
})
}
export const register: Register = on => {
const st = newState()
registerSession(on, st)
registerContext(on, st)
registerBash(on, st)
registerPending(on, st)
registerPrompt(on, st)
}