shaneconner/canon

pi-canon is a canonical project-memory system built for the Pi coding agent and mirrored for three other harnesses. Each governed asset is paired with exactly one authoritative article whose path is derived from the asset's own path, so src/core/config.ts is governed by articles/src/core/config.md, and beneath the articles sits an append-only journal, one file per event. When a tool call touches a governed asset, that article's single dense line arrives in the session unprompted, which means the agent does not have to know in advance that there was something to look up; path detection is best effort, but resolving a detected path to its article is not. Free knowledge is treated as a normal case, so untethered articles are allowed alongside tethered ones.

The repository ships as an installable package for four platforms in parallel. On Pi it installs via pi install npm:pi-canon or by cloning into ~/.pi/agent/extensions/, and it requires Node 22.18 or later together with Pi 0.83 or later on the 0.x line. On Codex and Claude Code the same repo is consumed as a marketplace: codex plugin marketplace add shaneconner/canon followed by codex plugin add canon@canon, or claude plugin marketplace add shaneconner/canon --scope user followed by claude plugin install canon@canon --scope user, and an absolute checkout path works for local development. On DeepSeek Harness the install is dsh plugin --profile <name> add dsh-canon, which pulls a separately published npm package called dsh-canon built from the same mirrored core but without the retriever and without the settings screen.

Typical users are developers who want a long-running coding agent to retain durable, governed knowledge of a project without manual retrieval. The Codex and Claude Code builds launch the same dependency-free MCP server and expose the same canon actions as the Pi build; Codex surfaces capsules after each tool result, Claude Code deduplicates one capsule packet across each parallel tool batch right before the next model request, and both emit a single write-after reminder before the agent stops. No configuration is required, the store is created on first write at <project>/.canon, the package imports only node:fs and node:path, makes no network calls, runs no git, and loads under plain Node with no build step; hooks are inert in projects without .canon/articles. License is MIT, all measurements were taken under Codex with GPT 5.6 on an OpenAI subscription, and other models or API-metered access are explicitly untested.