Skip to content
Cameron Mills

All projects

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.

Code on GitHub

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.

Perpetual Memory: results against their thresholds
CheckExpected or thresholdActualResult
Quoted claims valid at installEvery claim valid724 of 724Pass
Top-three relevance on held-out briefsA bar fixed before the runAbout half relevant, well above the barPass
Launch hook time under heavy loadWithin its time limitOver the limitMissed
The install and retrieval checks against bars fixed before they ran, and the timing bound the final review measured.

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.