Giving AI agents a memory that survives a cleared session
Perpetual Memory
Part of Life Tracker
A source-backed knowledge base every agent draws on: each claim quotes its source line, file and commit. A handover routine lets a cleared session pick up where the last one stopped, from written state rather than memory.
How it works
How cited pages reach every agent run, and how a cleared session picks up again. Select a layer to open it.
Problem
My main Claude Code session once ran for three days and nearly filled its context window. Clearing it would have lost what I had asked, what it had committed and which threads were still open. Unattended agents had the same gap, so I wanted a knowledge bank every agent could draw on for the task in hand.
Approach
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 rather than summaries, because published research found that citations in AI-generated answers often fail to support the sentence they sit under.
Architecture
My notes vault has three layers (raw material, a wiki and outputs) with generated indexes. The knowledge bank is a folder of short pages inside it, one per topic, project or decision, and every claim on a page quotes the source line it came from. A page's privacy level is set automatically to the strictest level among the sources it cites. Search runs on a full-text index, with a simple word match as a fallback.
The handover has four parts: a generated summary of the whole picture, a ledger of each session (prompts, commits, runs, decisions and open threads), readable session logs and a handover note.
What I built
- The launch block. Before a queued agent starts, a hook gives it a short list of the most relevant pages. If the index is slow, the hook gives up rather than holding the run back.
- Daily upkeep. Every morning a scan rebuilds the index, re-checks every quotation and stops using any claim whose source line has gone. The bank flags itself as not live when it fails that check or the scan is out of date.
- The handover. When a session's context is nearly full, the status line says so. /checkpoint writes the ledger, the log and the summary, and /initiate brings the cleared session back up to speed. The ledger only credits a session with a commit it can prove it made, so work by agents running in parallel is not misattributed.
Results
The first version of the bank installed with every one of its quoted claims checked valid. On test briefs held back from development, about half of the top results were relevant, above the bar I set before the run.
| Check | Expected or threshold | Actual | Result |
|---|---|---|---|
| Quoted claims valid at install | Every claim valid | 724 of 724 | Pass |
| Top-three relevance on held-out briefs | A bar fixed before the run | About half relevant, well above the bar | Pass |
| Launch hook time under heavy load | Within its time limit | Over the limit | Missed |
What didn't work
Three review judges scored the bank low, and the hook was slow under heavy load. The main reason for the low scores was that most pages were still pointers, because the step that distils them had not yet run. That step now runs nightly, and the bank holds 97 pages. Search has no relevance threshold, so any shared word returns a result. The handover note itself is still written by hand.
Stack
- Python
- SQLite FTS5
- Claude Code hooks
- Markdown
- git
How these figures are sourced
The outcome figure is agent-reported: it is taken from a test log or report written by the agents that built and ran the system. The status was read from the code repository at commit c8e90f7 on 1 Oct 2026. Every figure and claim on this page is tied to a source file or a CV line in the site's content.