I gave my repo a memory so my AI agents would stop forgetting. It almost made me miss a bug.

I built this site piece by piece with Claude Code and Codex. I would think of something, ask them to add it, and move on quickly. Then I noticed that every time they showed up, they had no idea what had come before.

They are not dumb. They have no memory. Every new session is a cold start, and I cannot reread the whole repo or crawl git every time I write an article. Over time, they re-guess the architecture and sometimes fight the previous version of themselves.

I was researching Google’s OKF (Open Knowledge Format), a structured Markdown format for giving AI agents curated context. I turned this repo’s brain into an OKF bundle. I did not assume it worked; I ran an experiment. It saved me once and almost tripped me once.

Nobody was maintaining my site’s memory

The docs existed, but the knowledge was not in a place an agent would read and maintain. The reasons behind the architecture, the traps I had already hit, and the decisions I had made were scattered across commit messages, my head, and past conversations. The next session saw none of them.

Every session had to recrawl the code to rebuild a mental model, which was slow and expensive. When a decision was not visible in the code (for example, a bug fixed with a platform setting rather than a code change), the agent had no way to know and was likely to fix it in the wrong direction.

I gave the repo an OKF bundle

OKF is straightforward: a directory of Markdown files, one concept per file, with YAML frontmatter declaring a type (concept / howto / reference / decision). The concepts connect through ordinary Markdown links. Agents start at an index and follow those links instead of searching blindly.

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 came from real work, not generated guesses.

The bundle is not magic. Agents will not read or update it on their own. I put the rule, "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). The memory stays useful only if someone reads and maintains it.

I did not just trust it. I ran an A/B test

I did not want to claim "it works" based on vibes. I started two cold-start agents and gave them the same tricky, repo-specific question. One had to read /knowledge first; the other could not read the knowledge base and could only crawl the code. I compared two things: did they get the answer right, and how much work did it take?

Round one: both got it right, but memory was twice as fast

I asked: "If I add a React component to an article page, will Google’s crawler see it? Which file do I change?" The answer is not obvious: article-page crawler HTML comes from a separate hand-written script, while the client uses createRoot to clear and repaint. Changing only the React component is not enough.

Both got it right. The question was a little unfair to the knowledge base because the script has a helpful comment that a code-only crawl can find too. Still, the agent that read the knowledge base got there in half the time and a third of the tokens. This round measured efficiency.

Round two: memory answered a question the code could not

For round two, I gave them a real symptom without the 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 found 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. It also made the right call: turn off that setting in the Cloudflare dashboard instead of patching around it in code.

A code-only agent had no way to know this because it is not in the code. That is what OKF memory adds: the "why" and the past decision, which the code itself cannot express.

But memory almost misled me

The code-only agent 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. A visitor on a later day computes a different number, which also triggers #418.

The agent that read the knowledge base stopped at the recorded cause, Cloudflare, and never looked further. It missed this bug. The memory made it stop questioning and stop searching. That is anchoring bias.

The real lesson: memory is for recall, not truth

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

My conclusion is simple: use memory for recall. It is fast, and it carries decisions the code cannot. But verify current reality anyway; memory should never be a reason to stop looking. Write anything new from that verification back into the memory.

That is what I did: I changed the trap node from "Cloudflare only" to "the two classes of #418," added a rule not to stop at the first cause, and fixed the real bug. The experiment made the memory better. That is probably what this practice should look like.

I am not sure this is the best way to manage agent memory. At least Claude and Codex no longer start from zero on this repo, and I learned not to treat memory as a reason to stop checking. The knowledge bundle is in the repo and versioned alongside the code.