The most trustworthy "memory" in my stack is markdown in a repo, because markdown in a repo is boring. It has diffs. It has history. It has review. It has a path for a human to say: yes, that's true now.

That sounds primitive until you compare it to the alternative — an agent silently updating its own beliefs in a database nobody reads. Hindsight, Hippo, Honcho, AgentMemory: useful tools, none of them is canon. Canon is the layer underneath the clever retrieval. It's where claims land after somebody has looked at them.

A pipeline where agent observations become proposals, pass through a pull request review gate, and land in a markdown canon repository.

The boring file is doing the important job

Walk through my stack and the things I trust the most are the things that look the least impressive. AGENTS.md at the root of a repo. The docs/ folder. The GBrain markdown wiki. A CLAUDE.md that nobody has touched in two months because it's still right. None of these are the part of the system that gets a launch blog.

But they're the layer every harness reads from. Claude Code reads CLAUDE.md. Codex reads AGENTS.md. Hermes can mount a wiki as context. OpenCode reads the same files. Pi reads AGENTS.md too. When the harness changes, the canon doesn't — that's the whole point. Repo docs survive harness swaps because they're not coupled to the harness.

Git is doing the load-bearing authority work here. git log answers when a claim was added. git blame answers who added it. diff lets a reviewer say no before the claim lands. Pull requests turn updates into a conversation. None of that exists for a vector DB or an opaque memory store. You can't git blame an embedding hit.

Authority is not retrieval confidence

A semantic memory hit and a reviewed doc look the same in a prompt — both arrive as text the model can read. The difference is what stands behind them. The reviewed doc has a human (or at minimum a documented agent process) that said "yes, this is true in this repo now." The vector hit has a similarity score.

The failure mode I've watched happen, more than once: a coding agent learns a repo convention from one task. It writes the learning into some opaque memory store ("uses pnpm, not npm"). Three months later the repo migrates to bun. Nobody updates the memory. The next agent retrieves "uses pnpm," treats it as a rule, and helpfully un-migrates a file or two. Nobody catches it until CI fails.

The hit wasn't wrong when it was written. It became wrong when the world moved. Without provenance and a review surface, you can't tell.

Memory can suggest. Canon decides.

The agent can read canon before it can write canon

The read path should be easy. Agents should pull canon into context when the task needs it — AGENTS.md is loaded at the start of a Pi session, the relevant docs get cat'd in when the agent is investigating something, the wiki is queryable. Friction here is bad. If the agent has to fight to read the rules, it won't.

The write path is the opposite. It should be slow, evidenced, and visible. A pipeline that has earned its keep for me:

  1. Agent observes a repeated convention (or a contradiction with the docs).
  2. Agent drafts a canon update with the specific evidence — diffs, test runs, prior commits.
  3. Proposal lands as a PR, not as a silent write.
  4. A reviewer (often me, sometimes another agent with a clearer mandate) checks the evidence.
  5. Merge.
  6. Future agents read the reviewed rule.

This is pro-agent. The point isn't to keep agents out of canon — it's to give them a safe proposal path so their generated truth doesn't become unreviewed infrastructure by accident. The same way a junior engineer doesn't push directly to main, the agent shouldn't push directly to canon.

The boundary is intentional. If you let the reflective layer write straight to the wiki, you've built a system where the agent's beliefs about the world become the world. That's not memory architecture. That's a confidence laundering machine.

Edges and exceptions

A few places this argument doesn't reach:

  • Vector stores are a great retrieval layer; they're a bad authority layer. Treat hits as candidates, not commandments. The argument is against canon-by-embedding, not against embeddings.
  • Trivial preferences ("Donovan likes terse output") don't need a PR review. The gate is for durable canon — things other agents will rely on, things that survive sessions.
  • Canon is alive, not frozen. It changes constantly. The point is that it changes through review.
  • Markdown specifically isn't the requirement. It's the lowest common denominator for "thing a human and an agent can both read." Plain SQL with a review queue would also work. The requirement is inspectability and a review gate, not the file extension.

Outcomes

  • Canon is the reviewed source of truth. Fancy retrieval belongs below it, not above it.
  • Semantic and reflective systems should propose updates to canon. Silent canon drift is the failure mode I keep watching for.
  • In this stack, markdown + git is the audit format because every agent and human in the loop can inspect it. The day I can't cat it, I stop trusting it.
  • The next post in this series is the other side of this argument — why retrieval is genuinely useful when it knows its place.