Giving AI agents a memory that survives a cleared session

My main Claude Code session once ran for three days and reached 87% of a million-token context, and clearing it would have lost what I asked, what it committed and which threads were open. Unattended agents had the same gap, so the brief was a knowledge bank that every agent draws on for the task in hand.

Write state down mechanically from transcripts, run records and git, and have a fresh session read it back. For shared knowledge, hand agents pointers to cited pages, not distilled sentences, because a published study found citations in generative search often fail to support their sentence.

The notes vault has three layers (raw, wiki, output) with generated indexes. The knowledge bank is a folder of short pages inside it, one per topic, project or decision. Every claim quotes the whole source line it came from, with the file, line, commit and date. A page's privacy class is the most restrictive class among the sources it cites, set mechanically. Retrieval runs on a SQLite FTS5 index, with a plain token match as fallback.

The handover has four parts: a generated whole-picture summary, a session ledger (prompts, commits, runs, decisions, open threads), readable session logs and a handover note.

• The launch block. Before a queued agent starts, a hook adds at most 120 words naming up to three relevant pages. It fails open on a four-second alarm, so a slow index never blocks a run.
• Daily upkeep. Every morning a scan rebuilds the index, re-checks every quoted line and stops serving a claim whose line has gone. Stale sources queue at most one distil run a night. A status line says NOT LIVE when the bank fails validation or the scan is over 48 hours old.
• The handover. At 85% context the status line shows CHECKPOINT. /checkpoint writes the ledger, the log and the summary, and /initiate brings the cleared session back up to speed. The ledger claims a commit only when its hash appears in that session's own git output or its trailer names the session, so parallel agents' work is not misattributed.

The 90-page seed installed with 724 of 724 claims valid. On 12 held-out briefs, 19 of the top-three results were relevant out of 36 (0.528), against a bar of 0.30 fixed before the run.

Three review judges scored the bank 4, 4 and 7 out of 10, and the hook missed its four-second bound at p95 under heavy load. The main reason for the low scores: 72 of the 90 pages are pointers, and the distiller had not yet run. Retrieval has no relevance floor, so any shared word returns a result. The handover note itself is still written by hand.