canon Mutable Canonical Memory over an Immutable Journal
One canonical article per governed asset, at an address you can compute. An append-only journal underneath it keeps the first version the agent records. Recall arrives on its own, when a tool call touches the thing the knowledge is about.
Scroll to explore
The Project
Memory as a place, not a search
Most agent memory asks the model to remember to look. canon inverts that: knowledge lives at the address of the asset it governs, and the delivery the design bets on is unsolicited. When a session's tool call touches a governed asset, the governing article's one-line capsule arrives on its own. The agent never has to know the store exists to benefit from it, which is the property that matters once a project's memory outgrows what any session already knows.
The package is on npm as pi-canon under MIT, and the same store serves Pi, Codex, and Claude Code. The design holds three recall channels: touch, the capsule arriving when an asset is touched; recommendation, a retriever ranking the articles touch cannot reach against the session's active context; and search, the agent's own act and the only channel that reaches the journal.
The Evidence
Measured whole, taken apart, doubted, then closed
The project has run as four measurement campaigns, each with a paper and a public artifact trail. Part 1 built the design and measured the package whole: with canonical memory, agents avoided 19 of 20 planted traps across multi-session chains against 8 of 20 for a floor with none, at a third of the recall tokens. Part 2 took the package apart: six preregistered studies priced touch and recommendation directly and bounded search through the arm that carried it, a 128-session experiment priced the surface itself, and a replay on a real store caught a failure before shipping did.
Both campaigns measured whether memory can be reached, and both took for granted that what it holds is true. Part 3 tests that and it does not hold: writers leave superseded values standing in records whose contract is to state what is true now. A condition in which the tool speaks at the write boundary ended lower on that endpoint in 20 of 24 capture-lineage comparisons, tied in 2 and higher in 2. The size of that difference did not survive a counterbalanced repeat, and it is withdrawn rather than qualified.
Part 4 closes the line on the question none of the first three asked: once a result has entered the agent's live context, how long must it stay there, and who should decide? Six preregistered studies ran the registered ladder of context-withdrawal designs to its end. A transient guidance cue could leave one message after it arrived; a fixed window imposed on task evidence drove sessions into re-read loops and the capture was stopped by its registered cost ceiling; offered the choice, two sessions of twenty-four withdrew anything, and under a disclosed ephemeral default the model marked all 139 consulted results durable with task quality perfect in both arms. The shipped durable-by-default design stands validated for this use case by the exhaustion of its registered alternatives, and this is the first part with no planned next step.
The configuration that ships is the studies' verdicts, executed. Addressing and surfacing on touch are on by default. Recommendation works, measurably, in exactly the regime built for it, and still ships off by default because the package cannot know which kind of store it faces. The orientation line and the check-back were removed by their own measurements, after the surface experiment found that presenting the memory at all took first-pass correctness from 25 of 32 to 8 of 32.
Part 1
The Design, Measured Whole
The lineage, the address spine, the journal, and surfacing on touch, then a four-arm evaluation on multi-session chains with planted traps. The result that made the project worth continuing, and the honest limit that set the agenda: package-level by construction, unable to say which part earned the gap.
Part 2
Pricing Recall
Six preregistered studies price the recall channels: touch and recommendation directly, search bounded through the arm that carried it. A 128-session experiment prices the surface, a replay on a real store finds the failure the priced corpus never enters, and the interactive figures put the shipped cutoff in your hands.
Part 3
The Write Desk
Lineages of session records whose facts are revised, reversed, and retired, written through the shipped tool and read back by a fresh agent graded against a hidden oracle. A one-line growth signal at the write boundary, and a lower endpoint alongside it in three captures. Then a counterbalanced repeat took the magnitude back, and the page shows you the lineage carrying most of that capture's contrast.
Part 4
A Durable Fit
Who decides what leaves the context window: the system silently, the agent by opt-in, or a disclosed default with an opt-out. Six preregistered studies, a recorded re-read loop replayed read by read, the exact cost ceiling that caught it, and a closing capture in which the model kept every consulted result. The line's natural bookend.
Papers and Artifacts
Every number checked against the deposit
All four campaigns are published with their full artifact trails, each under a DOI that always resolves to the newest version of that paper.
Part 1, the design and the four-arm evaluation that measured it whole: doi.org/10.5281/zenodo.21890647. The deposit carries the per-cell artifact trail for every cited run and a verifier that recomputes its 92 quantitative claims from the artifacts.
Part 2, six preregistered studies pricing the recall channels: doi.org/10.5281/zenodo.21960350. Per-cell transcripts and traces for all 679 study cells and the 128 surface sessions, and a verifier that recomputes 135 headline numbers under an identity header.
Part 3, what gets written down and whether it stays true: doi.org/10.5281/zenodo.22057257. Every results document, the per-lineage endpoint CSV behind every direction count, the graded reports, the digest-pinned capture contracts, the fixture generators, both arm tools with the diff between them, and 98 checks that recompute the paper's numbers from those artifacts. One part is pinned rather than rebuildable: the retrieval corpus is the full text of two private stores, so its scores are fixed to a published digest and a frozen score file while the corpus itself stays unpublished. Eleven rounds of adversarial model review ran against it, and the errata for every claim corrected or withdrawn ship with the deposit rather than being folded in quietly.
Part 4, who decides what leaves the context window: doi.org/10.5281/zenodo.22087390. The six studies' frozen record ships beside the paper: designs and staged amendments, results and halt documents, graded reports and session manifests, fixtures with their hidden oracles, harnesses with their gates, and the verbatim external reviews across three rounds. A facts gate in the deposit recomputes every figure datum and pinned number in the paper from that archive alone, forty checks, the same gate that ran in the paper's build.
If a check fails, the paper and the deposit disagree, and the deposit is right. The package on npm is at 0.3.0, the first release carrying the growth line Part 3 measures; the release Part 2 describes is 0.2.3. A store like this one can be browsed with canon-atlas, a viewer built with canon in mind and kept agnostic about which package wrote the files.
The narrative versions are on Medium: Part 1 as My agents' wiki was written faster than it was read, Part 2 as Pricing recall in long-term memory for AI agents, Part 3 as I thought I had halved a memory bug. A second run took most of it back, Part 4 as I built my agent a way to shed context. It consistently opted out.