pi-canon: Mutable Canonical Memory over an Immutable Journal, with Recall by Surfacing. Design, and a four-arm multi-session evaluation

Abstract

Agent knowledge bases rot in two directed ways: agents scatter near-duplicate notes because nothing marks which article is the article for a topic, and they treat the store as a diary, burying current truth under event logs. pi-canon is a project-memory extension for the Pi coding agent built on a structural answer: two tiers with opposite mutability disciplines. In the canon, every governed asset resolves to at most one canonical article, addressed by the asset's own path or by the nearest governed ancestor, so one article may govern a subtree and an article matching no asset is free knowledge; articles are mutable and hold the current best understanding. The journal beneath is append-only, one file per event, with the agent instructed to preserve source wording, names, and exact numbers. The spine, the addressing convention, is not a component: it needs no configuration, and renames are a file move. Recall is by surfacing, push rather than retrieval: when a tool call is detected touching a governed asset, the article's one-line capsule is staged for the session, at most once per article per session, under a hard budget and subject to best-effort detection. The evaluation population comes before its numbers. On five author-built, development-exposed chains under a pre-specified frozen protocol, with four eligible trap designs each repeated five times, a four-arm study on canon-bench measured trap avoidance (probes where violating a planted constraint compiles fine and fails a hidden grader), plant-only recall, and token economics. canon passed 19 of 20 trap cells against 8 of 20 for the bare floor (18 for a self-maintained AGENTS.md arm, 16 for canon plus a static doctrine file); plant-only recall clustered at 40 to 42 of 45 in every arm with no robust separation under the frozen judge, the arm ordering changing when one pre-flagged judge-sensitive item is removed; and canon answered recall at 0.34x bare's median recall token count, while the doctrine-file arm was lowest on every metered worker-session cost. The caveats are structural and belong beside the numbers: the chains are development-exposed under direct adaptive reuse, the freeze carries no third-party timestamp, all results used two related workers from one provider family with the second-model check covering only canon and bare at two repetitions, and the same author designed the package, the chains, the traps, and the graders. The evaluation supports a package-level result on these chains; it does not estimate a general effect and does not attribute the result to components. This record carries the paper and the complete artifact trail: session transcripts, store snapshots, grader outputs, judge requests and verdicts, cold-control runs with their costs, the results CSVs, the freeze files, the figure sources with their render pipeline, and a provenance index mapping every claim in the paper to the artifact field behind it. verify_provenance.py in the archive re-derives 92 numeric claims from those artifacts using the standard library alone. The paper and data are released under CC BY 4.0. The pi-canon software itself is MIT licensed at github.com/shaneconner/pi-canon, as is the canon-bench evaluation harness at github.com/shaneconner/canon-bench.