I gave my repo a memory so my AI agents would stop forgetting — then it almost made me miss a bug

This site was built piece by piece by Claude Code and Codex. I would think of something, ask them to add it, and it was fast. Then one day it hit me: every time they show up, they have no idea what was built before.

It is not that they are dumb — they have no memory. Each new session is a cold start, and you cannot re-read the whole repo or crawl git every time you write one article. Over time they re-guess the architecture, and sometimes fight the previous version of themselves.

I had just been researching Google’s OKF (Open Knowledge Format) — a structured markdown format for giving AI agents curated context. So I turned this repo’s brain into an OKF bundle. I did not just trust that it helped; I ran an experiment. It saved me once, and almost tripped me once.

Nobody was maintaining my site’s memory

The problem was not "not enough docs." It was that the knowledge was not where an agent would read and maintain it. Why the architecture is shaped this way, which traps I already hit, which decisions were deliberate — all scattered across commit messages, my head, and some past conversation. The next session sees none of it.

So every session re-crawls the code to rebuild a mental model — slow and expensive. And when a decision is not visible in the code (for example, a bug that was fixed with a platform setting, not a code change), the agent has no way to know, and is likely to fix it in the wrong direction.

I gave the repo a brain: an OKF bundle

OKF is simple at its core: a directory of markdown files, one concept per file, with YAML frontmatter declaring a type (concept / howto / reference / decision), and concepts linked into a graph with ordinary markdown links. Agents start from an index and traverse the links instead of blindly searching.

I added a /knowledge directory and wrote one node for each thing I had actually built over these weeks: the SSR dual-renderer, the article data model, the series system, i18n, the data-snapshot pipeline, deployment, and the traps I hit. All of it real, not generated.

But here is the key point, the one I most want to stress: the bundle is not magic. On its own, agents will not read or update it. I wrote the discipline — "read the relevant node before you work, update it after" — into the entry files agents load by default (AGENTS.md for Codex, CLAUDE.md for Claude Code). Only if it is read and maintained does this memory stay alive.

I did not just trust it — I ran an A/B

I did not want to claim "it works" on vibes. So I spun up two cold-start agents and gave them the same tricky, repo-specific question: one was told to read /knowledge first, the other was forbidden from the knowledge base and could only read the code. Then I compared two things: did they get it right, and how much work did it take.

Round one: both correct, but memory was twice as fast

First I asked: "If I add a React component to an article page, will Google’s crawler see it? Which file do I change?" The correct answer is non-obvious — the crawler HTML for article pages is generated by a separate hand-written script, and the client uses createRoot to clear and repaint, so touching only the React component is not enough.

Both got it right. Honestly, this question was unfairly easy for the knowledge base, because that script happens to carry a very helpful comment that a pure code crawl also finds. But the agent that read the knowledge base got there in half the time and a third of the tokens. This round was about efficiency.

Round two: memory answered something the code could not

For the second round I gave a real symptom with no answer: "The live site keeps logging React #418 (hydration mismatch) in the console, and mobile LCP is ~8 seconds. How do I fix it — a code change or something else?"

The agent that read the knowledge base nailed the root cause in seconds: Cloudflare’s Email Obfuscation was rewriting the email on the page at the edge, so the server HTML no longer matched React. And it gave the correct decision — go to the Cloudflare dashboard and turn that setting off, do not patch it in code.

A pure code-crawling agent could never know this, because it is simply not in the code. This is OKF memory’s irreplaceable value: it remembers the "why" and the past decision — things the code itself cannot express.

But memory almost tripped me too

Here is the twist. The code-only agent instead surfaced a real bug that was not in the knowledge base: the homepage calls new Date() during render to compute "which day it is," so the build-day number gets baked into the prerendered HTML, and a visitor on a later day computes a different number — which also triggers #418.

And the agent that read the knowledge base? It stopped at the recorded cause (Cloudflare) and never looked further, missing this bug entirely. Memory made it stop doubting and stop searching. That is anchoring bias.

The real lesson: memory is recall, not truth

Both were actually right — just about different #418s. The site really has two hydration traps: one is an edge-layer HTML rewrite (invisible in code; only memory knows how it was solved), and one is a render-time date value (not in memory; only fresh analysis found it).

So my conclusion is not "with memory you stop checking." It is: use memory to recall — it is fast, and it gives you decisions the code cannot — but still verify current reality, and never let memory become an excuse to stop looking. And whatever you find while verifying, write it back into memory.

That is what I did this time: I generalized that trap node from "Cloudflare only" to "the two classes of #418," added an explicit rule to not stop at the first cause, and fixed the real bug. The experiment itself made the memory better — which is probably what this whole practice should look like.

I am not sure this is the best way to manage agent memory. But at least now, Claude and Codex do not cold-start completely on this repo, and I have learned not to treat memory as an excuse to stop checking. The knowledge bundle lives in the repo, in the open — you can read it directly.