@100xprompt/brain 0.0.0-stage → 0.1.1

package/src/memory/cli.ts

@@ -0,0 +1,117 @@
+// `brain memory ingest <session-id> | search <query> [--project p] [--limit n] | status | forget [--project p] [--source id]`.
+// Plain output, counts first. `resolve` turns a session id into a Session (the coordinator wires the real readers).
+import { realpathSync } from "node:fs"
+import type { Session } from "../session/types.ts"
+import { gitInfo } from "../fsutil.ts"
+import { distill } from "./distill.ts"
+import { projectKey } from "./project.ts"
+import { redact } from "./redact.ts"
+import { openMemory, storeBytes } from "./store.ts"
+import type { ProjectKey } from "./types.ts"
+
+function flag(args: string[], name: string): string | undefined {
+  const i = args.indexOf(`--${name}`)
+  return i >= 0 ? args[i + 1] : undefined
+}
+
+function positional(args: string[]): string[] {
+  const out: string[] = []
+  for (let i = 0; i < args.length; i++) {
+    if (args[i]!.startsWith("--")) i++
+    else out.push(args[i]!)
+  }
+  return out
+}
+
+/** The project to act on: `--project` as an id or a label of a stored project, else the current folder's. */
+async function pickProject(args: string[], mem: ReturnType<typeof openMemory>): Promise<ProjectKey | { error: string }> {
+  const wanted = flag(args, "project")
+  if (!wanted) {
+    const cwd = (() => {
+      try {
+        return realpathSync(process.cwd())
+      } catch {
+        return process.cwd()
+      }
+    })()
+    return projectKey({ cwd, ...gitInfo(cwd) })
+  }
+  const known = await mem.projects()
+  const hit = known.find((p) => p.id === wanted.toLowerCase() || p.id === wanted) ?? known.filter((p) => p.label === wanted)[0]
+  if (hit) return { id: hit.id, label: hit.label }
+  const labelMatches = known.filter((p) => p.label === wanted)
+  if (labelMatches.length > 1) return { error: `"${wanted}" matches several projects; use the id` }
+  return { error: `no stored project "${wanted}" (known: ${known.map((p) => p.label).join(", ") || "none"})` }
+}
+
+export async function memoryCommand(args: string[], home: string, resolve: (id: string) => Promise<Session>, out: (line: string) => void = console.log): Promise<number> {
+  const [sub, ...rest] = args
+  const mem = openMemory(home)
+  try {
+    if (sub === "status" || !sub) {
+      const s = await mem.status()
+      if (!s.available) {
+        out("memory: not available")
+        out(`why: ${s.why}`)
+        return 0
+      }
+      const c = await mem.counts()
+      out(`memory: available, ${c.total} items in ${(await mem.projects()).length} projects`)
+      out(`store: ${s.store} (${(storeBytes(home) / 1024).toFixed(0)} KB)`)
+      out(`kinds: ${Object.entries(c.byKind).map(([k, n]) => `${k} ${n}`).join(", ") || "none"}`)
+      for (const p of await mem.projects()) out(`  ${p.label}  ${p.items} items  (${p.id})`)
+      return 0
+    }
+
+    if (sub === "ingest") {
+      const id = positional(rest)[0]
+      if (!id) return out("usage: brain memory ingest <session-id>"), 2
+      let session: Session
+      try {
+        session = await resolve(id)
+      } catch (e) {
+        return out(`cannot read session ${id}: ${(e as Error).message}`), 1
+      }
+      const s = await mem.status()
+      if (!s.available) return out(`memory is not available: ${s.why}`), 1
+      const items = distill(session)
+      const project = projectKey(session.header.project)
+      const { stored } = await mem.ingest(project, items)
+      const byKind: Record<string, number> = {}
+      for (const i of items) byKind[i.kind] = (byKind[i.kind] ?? 0) + 1
+      out(`stored ${stored} items from ${session.header.id}`)
+      out(`kinds: ${Object.entries(byKind).map(([k, n]) => `${k} ${n}`).join(", ") || "none"}`)
+      out(`project: ${project.label} (${project.id})`)
+      return 0
+    }
+
+    if (sub === "search") {
+      const query = positional(rest).join(" ").trim()
+      if (!query) return out("usage: brain memory search <query> [--project p] [--limit n]"), 2
+      const s = await mem.status()
+      if (!s.available) return out(`memory is not available: ${s.why}`), 1
+      const project = await pickProject(rest, mem)
+      if ("error" in project) return out(project.error), 1
+      const limit = Number(flag(rest, "limit")) || 8
+      const hits = await mem.recall(project, query, { limit })
+      out(`${hits.length} items for "${redact(query)}" in ${project.label}`)
+      for (const h of hits) out(`[${h.kind ?? "item"}] ${h.score.toFixed(3)}  ${h.text}${h.source ? `  (from ${h.source})` : ""}`)
+      return 0
+    }
+
+    if (sub === "forget") {
+      const s = await mem.status()
+      if (!s.available) return out(`memory is not available: ${s.why}`), 1
+      const project = await pickProject(rest, mem)
+      if ("error" in project) return out(project.error), 1
+      const n = await mem.forget(project, { source: flag(rest, "source") })
+      out(`forgot ${n} items in ${project.label}${flag(rest, "source") ? ` from ${flag(rest, "source")}` : ""}`)
+      return 0
+    }
+
+    out("usage: brain memory ingest <session-id> | search <query> [--project p] [--limit n] | status | forget [--project p] [--source id]")
+    return 2
+  } finally {
+    mem.close()
+  }
+}

package/src/memory/distill.ts

@@ -0,0 +1,381 @@
+// Zero-model distillation of a portable session into small memory items: what was decided, what must not be done, which
+// approaches failed, which files changed and why, which commands are reusable, how it ended. Precision over recall: a wrong
+// memory costs tokens in every future session, a missed one costs a re-discovery. Everything passes through `redact`.
+import { createHash } from "node:crypto"
+import { isAbsolute, relative } from "node:path"
+import type { Session, Turn } from "../session/types.ts"
+import { isInjected, withoutInjected } from "../session/util.ts"
+import { projectKey } from "./project.ts"
+import { redact } from "./redact.ts"
+import type { MemoryItem, MemoryKind } from "./types.ts"
+
+export interface DistillOptions {
+  /** Cap on items per session; the best are kept. Default 40. */
+  maxItems?: number
+}
+
+type Scored = MemoryItem & { score: number }
+
+const sha = (s: string, n = 12): string => createHash("sha1").update(s).digest("hex").slice(0, n)
+const oneLine = (s: string): string => s.replace(/\s+/g, " ").trim()
+
+/** Whitespace-collapsed text clipped to `n` characters at a word edge, with an ellipsis. */
+export function clipText(s: string, n: number): string {
+  const t = oneLine(s)
+  if (t.length <= n) return t
+  const cut = t.slice(0, n - 1)
+  const sp = cut.lastIndexOf(" ")
+  return `${(sp > n * 0.6 ? cut.slice(0, sp) : cut).trimEnd()}…`
+}
+
+// ---- user instructions --------------------------------------------------------------------------------------------
+
+const STRONG = /\b(always|never|from now on|going forward|in the future|we use|we always|we never|we decided|we('re| are) (using|going with)|the rule is|the convention is|prefer|i prefer|i like|i don'?t like|i hate|whenever|every time|should always|should never|must never|must not|mustn'?t|don'?t ever|under no circumstances|no matter what|default to)\b/i
+const MEDIUM = /\b(must|don'?t|do not|dont|make sure|ensure|instead of|instead|only use|only|avoid|stop (?:using|doing|adding|writing)|no need to|keep (?:it|them|the|using)|rather than|not (?:use|using)|use [\w./-]+ not [\w./-]+)\b/i
+const ONE_OFF = /\b(right now|this time|for now|just this|for this (?:task|one|case|session)|today|tonight|at the moment|in this (?:file|case)|the above|the following|above error|this error|that error|this bug)\b/i
+const QUESTION_START = /^(?:what|why|how|when|where|who|which|can|could|would|should|is|are|do|does|did|will|have|has|any idea|is there|are there)\b/i
+const FILLER_START = /^(?:and|also|but|so|ok|okay|yes|yeah|yep|no|now|well|then|please|pls|plz|btw|oh|hey|hi|hmm|alright|right|cool|nice|great)[\s,:.!-]+/i
+const DEICTIC_START = /^(?:it|this|that|these|those|they|them|he|she|its|there|here|the same|same|such)\b/i
+
+function splitInstructionCandidates(text: string): string[] {
+  const noCode = text.replace(/```[\s\S]*?(?:```|$)/g, " ").replace(/`([^`\n]{1,80})`/g, "$1")
+  const out: string[] = []
+  for (const line of noCode.split(/\n+/)) {
+    const l = line.replace(/^\s*(?:[-*•]|\d+[.)])\s+/, "").trim()
+    if (!l) continue
+    if (l.length > 600) continue // a pasted paragraph, log line or stack trace, not an instruction
+    if (/^\s*(?:at |\{|\[|<|\/\/|#|\$ |>>|[A-Za-z]+Error:)/.test(l) && !/\s/.test(l.slice(0, 3))) continue
+    for (const s of l.split(/(?<=[.!?])\s+(?=[A-Z0-9"'`])/)) {
+      const t = s.trim()
+      if (t) out.push(t)
+    }
+  }
+  return out
+}
+
+function classify(sentence: string): { kind: MemoryKind; strong: boolean } | undefined {
+  if (sentence.endsWith("?")) return undefined
+  let s = sentence
+  for (let i = 0; i < 2; i++) s = s.replace(FILLER_START, "")
+  if (s.length < 20 || s.split(/\s+/).length < 4) return undefined
+  if (QUESTION_START.test(s) && !/^(?:do not|don'?t|do it)\b/i.test(s)) return undefined
+  if (DEICTIC_START.test(s)) return undefined
+  if (/^(?:thanks|thank you|sure|great|perfect|good|looks good|lgtm)\b/i.test(s)) return undefined
+  const strong = STRONG.test(s)
+  const medium = MEDIUM.test(s)
+  if (!strong && !medium) return undefined
+  if (!strong && ONE_OFF.test(s)) return undefined
+  // medium markers inside an imperative about "this/it/the failing test" are one-offs: require a durable-sounding object
+  if (!strong && /\b(?:make sure|ensure)\b/i.test(s) && !/\b(?:always|every|all|each|any)\b/i.test(s) && /\b(?:this|it|that|the (?:tests?|build|app|page|server|thing))\b/i.test(s)) return undefined
+  const kind: MemoryKind = /\b(never|must not|mustn'?t|don'?t|do not|dont|avoid|stop|no need to|only|no matter what|under no circumstances)\b/i.test(s)
+    ? "constraint"
+    : /\b(prefer|rather than|i like|i don'?t like|i hate|instead|default to)\b/i.test(s)
+      ? "preference"
+      : "decision"
+  return { kind, strong }
+}
+
+function instructions(session: Session, at: (t: Turn) => string | undefined): Scored[] {
+  const out: Scored[] = []
+  const seen = new Set<string>()
+  const source = session.header.id
+  for (const t of session.turns) {
+    if (t.kind !== "user") continue
+    if (isInjected(t.text)) continue
+    const text = withoutInjected(t.text)
+    if (/^This session is being continued from a previous conversation/i.test(text)) continue
+    if (text.length > 4000) continue // a pasted blob, not a message
+    for (const sentence of splitInstructionCandidates(text)) {
+      const c = classify(sentence)
+      if (!c) continue
+      const clean = redact(clipText(sentence.replace(FILLER_START, ""), 300))
+      const key = clean.toLowerCase()
+      if (seen.has(key)) continue
+      seen.add(key)
+      out.push({ id: `${c.kind}-${sha(source + key)}`, kind: c.kind, name: clipText(clean, 70), text: clean, source, occurredAt: at(t), score: c.strong ? 88 : 72 })
+    }
+  }
+  return out
+}
+
+// ---- tool turns ---------------------------------------------------------------------------------------------------
+
+type Call = Extract<Turn, { kind: "tool_call" }>
+type Result = Extract<Turn, { kind: "tool_result" }>
+
+function inputObject(input: unknown): Record<string, any> {
+  if (input && typeof input === "object") return input as Record<string, any>
+  if (typeof input === "string") {
+    try {
+      const v = JSON.parse(input)
+      if (v && typeof v === "object") return v
+    } catch {}
+    return { command: input }
+  }
+  return {}
+}
+
+function commandOf(call: Call): string | undefined {
+  const o = inputObject(call.input)
+  const c = o.command ?? o.cmd ?? o.script
+  if (typeof c === "string") return c
+  if (Array.isArray(c)) return c.map(String).join(" ")
+  return undefined
+}
+
+function pathOf(call: Call): string | undefined {
+  const o = inputObject(call.input)
+  for (const k of ["file_path", "path", "filePath", "file", "filename", "target_file", "notebook_path"]) if (typeof o[k] === "string" && o[k]) return o[k] as string
+  return undefined
+}
+
+const ERROR_LINE = /\b(error|fail(?:ed|ure)?|not found|denied|cannot|can't|no such|exception|panic|fatal|unable|invalid|unexpected|refused|timed? ?out|ENOENT|EACCES|ERR_)\b/i
+const REJECTION = /(user (?:doesn'?t|does not|didn'?t) want|was rejected|rejected|interrupted by user|request was aborted|tool use was|permission to use|has not been read yet|hook (?:blocked|denied)|aborted)/i
+
+function firstErrorLine(output: string): string {
+  const lines = output.split("\n").map((l) => l.trim()).filter(Boolean)
+  const hit = lines.find((l) => ERROR_LINE.test(l) && l.length < 400) ?? lines[0] ?? ""
+  return clipText(hit, 160)
+}
+
+/** `cd x && FOO=1 cmd args` -> the part that says what the command is. */
+function core(command: string): string {
+  const first = command.split("\n").find((l) => l.trim() && !l.trim().startsWith("#")) ?? ""
+  return first.replace(/^\s*(?:cd\s+[^&;]+(?:&&|;)\s*)+/, "").replace(/^\s*(?:[A-Z_][A-Z0-9_]*=\S*\s+)+/, "").trim()
+}
+
+const failureKey = (c: string): string => core(c).split(/\s+/).slice(0, 2).join(" ")
+
+function failures(session: Session, at: (t: Turn) => string | undefined): Scored[] {
+  const calls = new Map<string, { call: Call; index: number }>()
+  session.turns.forEach((t, i) => t.kind === "tool_call" && calls.set(t.id, { call: t, index: i }))
+  const attempts: Array<{ command: string; ok: boolean; index: number }> = []
+  const failed: Array<{ command: string; error: string; index: number; at?: string; kind: string }> = []
+  session.turns.forEach((t, i) => {
+    if (t.kind !== "tool_result") return
+    const entry = calls.get(t.callId)
+    if (!entry) return
+    const { call } = entry
+    if (!["shell", "edit", "write", "mcp", "other", "web"].includes(call.toolKind)) return
+    const command = commandOf(call) ?? `${call.name}${pathOf(call) ? ` ${pathOf(call)}` : ""}`
+    attempts.push({ command, ok: t.ok, index: i })
+    if (t.ok || REJECTION.test(t.output.slice(0, 400)) || !t.output.trim()) return
+    failed.push({ command, error: firstErrorLine(t.output), index: i, at: t.at, kind: call.toolKind })
+  })
+  const source = session.header.id
+  const out: Scored[] = []
+  const seen = new Set<string>()
+  for (const f of failed) {
+    const key = failureKey(f.command)
+    const fixed = attempts.find((a) => a.ok && a.index > f.index && failureKey(a.command) === key)
+    const clean = redact(clipText(core(f.command) || f.command, 140))
+    if (!clean || seen.has(`${clean}|${f.error}`)) continue
+    seen.add(`${clean}|${f.error}`)
+    const fix = fixed && core(fixed.command) !== core(f.command) ? `; worked after changing it to \`${redact(clipText(core(fixed.command), 100))}\`` : fixed ? "; worked on retry" : ""
+    const text = `Tried \`${clean}\`: failed with "${redact(f.error)}"${fix}`
+    out.push({ id: `failed-${sha(source + f.command + f.error)}`, kind: "failed", name: clipText(`failed: ${clean}`, 70), text, source, occurredAt: f.at, score: fixed ? 60 : 30 })
+  }
+  return out.sort((a, b) => b.score - a.score).slice(0, 6)
+}
+
+const CMD_KEYWORD = /\b(test|tests|build|lint|typecheck|tsc|check|dev|start|serve|deploy|format|fmt|compile|bench|migrate)\b/i
+const CMD_TOOL = /^(?:bun|bunx|npm|npx|pnpm|yarn|cargo|go|pytest|python3?|make|tsc|eslint|prettier|ruff|gradle|\.\/gradlew|mvn|dotnet|deno|vitest|jest|gcloud|docker|terraform|swift|xcodebuild|next|vite|node|uv|poetry|rake|bundle|mix|flutter|gh)\b/
+
+function commandLabel(c: string): string {
+  if (/\b(test|tests|pytest|vitest|jest)\b/i.test(c)) return "to run the tests"
+  if (/\b(typecheck|tsc)\b/i.test(c)) return "to typecheck"
+  if (/\b(lint|eslint|ruff|check)\b/i.test(c)) return "to lint"
+  if (/\b(deploy)\b/i.test(c)) return "to deploy"
+  if (/\b(build|compile)\b/i.test(c)) return "to build"
+  if (/\b(format|fmt|prettier)\b/i.test(c)) return "to format"
+  if (/\b(dev|start|serve|run)\b/i.test(c)) return "to run the app"
+  if (/\bbench\b/i.test(c)) return "to benchmark"
+  return `to run ${c.split(/\s+/).slice(0, 2).join(" ")}`
+}
+
+function commands(session: Session, at: (t: Turn) => string | undefined): Scored[] {
+  const calls = new Map<string, Call>()
+  const stats = new Map<string, { n: number; at?: string; command: string }>()
+  for (const t of session.turns) {
+    if (t.kind === "tool_call") calls.set(t.id, t)
+    if (t.kind !== "tool_result" || !t.ok) continue
+    const call = calls.get(t.callId)
+    if (!call || call.toolKind !== "shell") continue
+    const raw = commandOf(call)
+    if (!raw || /<<|\|\s*(?:sh|bash)\b/.test(raw)) continue
+    const c = core(raw)
+    if (c.length < 4 || c.length > 200 || !CMD_TOOL.test(c) || !CMD_KEYWORD.test(c.split(/\s+/).slice(0, 4).join(" "))) continue
+    if (/^(?:gh|docker|gcloud)\b/.test(c) && !/\b(deploy|build|test)\b/.test(c)) continue
+    const shown = redact(clipText(raw.split("\n")[0]!.replace(/^\s*#.*$/, ""), 160))
+    if (shown !== clipText(raw.split("\n")[0]!, 160)) continue // contained a secret: never keep it
+    const cur = stats.get(c) ?? { n: 0, command: shown }
+    cur.n++
+    cur.at = at(t)
+    stats.set(c, cur)
+  }
+  const source = session.header.id
+  return [...stats.values()]
+    .sort((a, b) => b.n - a.n)
+    .slice(0, 8)
+    .map((s) => {
+      const label = commandLabel(s.command)
+      return {
+        id: `command-${sha(source + s.command)}`,
+        kind: "command" as const,
+        name: label,
+        text: `${label[0]!.toUpperCase()}${label.slice(1)}: \`${s.command}\``,
+        source,
+        occurredAt: s.at,
+        procedures: [{ trigger: label, action: `\`${s.command}\`` }],
+        score: 55 + Math.min(s.n, 5),
+      }
+    })
+}
+
+const SKIP_PATH = /(?:^|\/)(?:node_modules|\.git|dist|build|\.next|coverage|\.brain)\/|(?:package-lock\.json|bun\.lockb?|yarn\.lock|pnpm-lock\.yaml|\.DS_Store)$/
+
+function files(session: Session, at: (t: Turn) => string | undefined): Scored[] {
+  const cwd = session.header.project.cwd
+  const rel = (p: string): string => {
+    if (cwd && isAbsolute(p)) {
+      const r = relative(cwd, p)
+      if (r && !r.startsWith("..")) return r
+    }
+    return p
+  }
+  const project = projectKey(session.header.project)
+  const byPath = new Map<string, { keys: Set<string>; created: boolean; why?: string; plus: number; minus: number; first?: string; at?: string; written: number }>()
+  const touch = (path: string, key: string, t: Turn, extra: { created?: boolean; patch?: string; written?: number }, index: number) => {
+    if (SKIP_PATH.test(path)) return
+    const p = rel(path)
+    const cur = byPath.get(p) ?? { keys: new Set<string>(), created: false, plus: 0, minus: 0, written: 0 }
+    if (cur.keys.has(key)) return
+    cur.keys.add(key)
+    if (extra.created) cur.created = true
+    if (extra.patch) {
+      for (const l of extra.patch.split("\n")) {
+        if (l.startsWith("+") && !l.startsWith("+++")) {
+          cur.plus++
+          if (!cur.first && l.slice(1).trim().length > 6) cur.first = l.slice(1).trim()
+        } else if (l.startsWith("-") && !l.startsWith("---")) cur.minus++
+      }
+    }
+    if (extra.written) cur.written += extra.written
+    const why = nearbyWords(session.turns, index)
+    if (why) cur.why = why
+    cur.at = at(t)
+    byPath.set(p, cur)
+  }
+  session.turns.forEach((t, i) => {
+    if (t.kind === "file_edit") touch(t.path, t.callId ?? `edit${i}`, t, { patch: t.patch }, i)
+    else if (t.kind === "tool_call" && (t.toolKind === "edit" || t.toolKind === "write")) {
+      const p = pathOf(t)
+      if (!p) return
+      const o = inputObject(t.input)
+      const body = typeof o.content === "string" ? o.content : typeof o.file_text === "string" ? o.file_text : typeof o.new_string === "string" ? o.new_string : typeof o.patch === "string" ? o.patch : undefined
+      touch(p, t.id, t, { created: t.toolKind === "write", written: body?.length, patch: typeof o.patch === "string" ? o.patch : undefined }, i)
+    }
+  })
+  const source = session.header.id
+  const out: Scored[] = []
+  for (const [path, f] of byPath) {
+    const stat = f.plus || f.minus ? `+${f.plus}/-${f.minus} lines` : f.written ? `${f.written} characters written` : ""
+    const what = f.why ? clipText(f.why, 160) : f.first ? `first changed line: ${clipText(f.first, 100)}` : stat
+    const n = f.keys.size
+    const text = redact(`${path}: ${f.created && n === 1 ? "created" : n > 1 ? `edited ${n} times` : "edited"}${what ? `; ${what}` : ""}${f.why && stat ? ` (${stat})` : ""}`)
+    out.push({
+      id: `file-${sha(source + path)}`,
+      kind: "file",
+      name: path,
+      text,
+      source,
+      occurredAt: f.at,
+      entities: [{ name: path, type: "file" }, { name: project.label, type: "project" }],
+      relations: [{ from: path, to: project.label, type: "edited_in" }],
+      score: 40 + Math.min(n, 8) * 2 + (f.why ? 6 : 0),
+    })
+  }
+  return out.sort((a, b) => b.score - a.score).slice(0, 12)
+}
+
+/** The assistant's own words just before an edit, when they are short enough to be a reason ("Fixed the TTL unit"). */
+function nearbyWords(turns: Turn[], index: number): string | undefined {
+  for (let j = index - 1; j >= Math.max(0, index - 4); j--) {
+    const t = turns[j]!
+    if (t.kind === "assistant" && t.text.trim()) {
+      const first = oneLine(t.text).split(/(?<=[.!?:])\s/)[0] ?? ""
+      if (first.length >= 15 && first.length <= 180 && !/^(?:let me|i'll|i will|now|first|next|ok|sure)\b/i.test(first)) return first.replace(/[:.]$/, "")
+      if (first.length >= 15 && first.length <= 180) return first.replace(/^(?:let me|i'll|i will)\s+/i, "").replace(/[:.]$/, "")
+      return undefined
+    }
+    if (t.kind === "user" || t.kind === "compaction") return undefined
+  }
+  return undefined
+}
+
+// ---- summaries and state ------------------------------------------------------------------------------------------
+
+const DONE = /\b(summary|done|fixed|implemented|changed|added|completed|shipped|now (?:works|passes|returns|uses)|all \d+ (?:tests )?pass|pass(?:es|ing)?|verified|resolved|created|updated|refactored|removed|wired)\b/i
+
+function realUserTurns(session: Session): Array<Extract<Turn, { kind: "user" }>> {
+  return session.turns.filter((t): t is Extract<Turn, { kind: "user" }> => t.kind === "user" && !isInjected(t.text) && !/^This session is being continued/i.test(withoutInjected(t.text)) && withoutInjected(t.text).length < 6000)
+}
+
+function summaries(session: Session, at: (t: Turn) => string | undefined): Scored[] {
+  const source = session.header.id
+  const out: Scored[] = []
+  const compactions = session.turns.filter((t): t is Extract<Turn, { kind: "compaction" }> => t.kind === "compaction" && t.summary.trim().length >= 40)
+  for (const c of compactions.slice(-2)) {
+    const text = redact(clipText(c.summary, 1500))
+    out.push({ id: `summary-${sha(source + text)}`, kind: "summary", name: "summary of earlier work", text, source, occurredAt: at(c), score: 90 })
+  }
+  let last: Extract<Turn, { kind: "assistant" }> | undefined
+  let userAfter = false
+  for (let i = session.turns.length - 1; i >= 0; i--) {
+    const t = session.turns[i]!
+    if (t.kind === "user" && !isInjected(t.text)) userAfter = true
+    if (t.kind === "assistant" && t.text.trim().length >= 60) {
+      last = t
+      break
+    }
+  }
+  if (last && !userAfter && last.text.length >= 200 && DONE.test(last.text) && !last.text.trim().endsWith("?")) {
+    const text = redact(clipText(last.text, 1200))
+    out.push({ id: `summary-${sha(source + "last")}`, kind: "summary", name: "how the session ended", text, source, occurredAt: at(last), score: 70 })
+  }
+  return out
+}
+
+function state(session: Session, at: (t: Turn) => string | undefined, hasEndSummary: boolean): Scored[] {
+  const users = realUserTurns(session)
+  const goal = users[0]
+  if (!goal) return []
+  const lastUser = users[users.length - 1]!
+  const lastAssistant = [...session.turns].reverse().find((t): t is Extract<Turn, { kind: "assistant" }> => t.kind === "assistant" && t.text.trim().length >= 20)
+  const parts = [`Goal: ${clipText(withoutInjected(goal.text), 300)}`]
+  if (lastUser !== goal) parts.push(`Last request: ${clipText(withoutInjected(lastUser.text), 300)}`)
+  if (lastAssistant) parts.push(`Where it stands: ${clipText(lastAssistant.text, hasEndSummary ? 160 : 400)}`)
+  const text = redact(parts.join("\n"))
+  const source = session.header.id
+  return [{ id: `state-${sha(source)}`, kind: "state", name: clipText(`state: ${session.header.title ?? withoutInjected(goal.text)}`, 70), text, source, occurredAt: at(session.turns[session.turns.length - 1]!), score: 100 }]
+}
+
+// ---- entry point --------------------------------------------------------------------------------------------------
+
+export function distill(session: Session, opts: DistillOptions = {}): MemoryItem[] {
+  const max = opts.maxItems ?? 40
+  const fallback = session.header.updatedAt ?? session.header.startedAt
+  const at = (t: Turn): string | undefined => ("at" in t && t.at) || fallback
+  const sums = summaries(session, at)
+  const hasEnd = sums.some((s) => s.name === "how the session ended")
+  const all: Scored[] = [...state(session, at, hasEnd), ...sums, ...instructions(session, at), ...failures(session, at), ...files(session, at), ...commands(session, at)]
+  const kept = all
+    .filter((i) => i.text.replace(/\s+/g, " ").trim().length >= 20)
+    .filter((i) => !(i.kind === "file" && /^[\w./-]+:\s*$/.test(i.text)))
+    .sort((a, b) => b.score - a.score)
+    .slice(0, max)
+  const seen = new Set<string>()
+  return kept
+    .filter((i) => (seen.has(i.id) ? false : (seen.add(i.id), true)))
+    .map(({ score: _s, ...item }) => item)
+}