CLAUDE.md Is a Second Source of Truth and It's Already Out of Date
The standard advice for giving a coding agent persistent context is to write it down in a markdown file — CLAUDE.md, AGENTS.md, rules.md, whichever name the toolchain prefers. Drop in a few paragraphs about the project, the preferred style, the key conventions, and the agent will carry them forward across sessions.
The problem, as the field is discovering, is that markdown files do not maintain themselves. Cal Paterson’s piece on agent memory as a file format, which hit the top of Hacker News on August 31, makes the structural argument directly: a static context file creates a second, unmaintained source of truth. The project evolves. The agent’s behavior evolves. The file does not. The gap between what the file says and what is actually true grows until the file becomes noise.
Theo Browne Deleted His
T3 Chat founder Theo Browne arrived at the same conclusion by a different route. After investing time in configuring agent memory files for his development workflow, he deleted all of them. His public characterization: AI coding tools’ memory systems are “garbage.”
Browne’s own agents.md for the T3 codebase is notable for what it does not contain. It is not a technical specification of the codebase. It is a values document — directional, personal, about how he wants the agent to behave rather than what the codebase currently looks like. His argument is that this is the only content a static file can reliably maintain: preferences and intent, not state.
The factual state of the project — what files exist, what the current architecture looks like, what changed last week — belongs in a system that can observe and update itself.
RocksDB as Agent Memory
The infrastructure alternative that has gained traction is using an embedded key-value store, with RocksDB as the common choice. The case for RocksDB in agent memory contexts is practical rather than theoretical. Ordered keys support prefix-scan queries without a query engine. Column families provide tiered retention: hot recent context in one family, cold long-term memory in another, with different compaction policies for each. LSM storage handles a write-heavy event log — every agent action, observation, and decision — efficiently without read-amplification on typical agent query patterns.
The pattern is: the agent writes every meaningful event to the store as it runs, not as a post-hoc summary. Retrieval uses prefix scans or similarity search over embeddings stored in a parallel column family. The “context file” is generated fresh each session from the live store, not maintained by hand.
Where OpenAI Landed
OpenAI’s workspace agents, shipped with Codex cloud access in August 2026, implement a version of this at the platform level. Agents get access to a persistent workspace that includes file storage, code execution, tool connections, and memory. The memory layer is not a markdown file the developer maintains — it is a managed store the agent writes to and reads from across sessions without human intervention.
The design acknowledges what the CLAUDE.md era revealed: memory is an infrastructure problem. Asking developers to maintain it manually introduces the same category of failure as asking them to manually update their own documentation. It happens for a while, then it stops, and nobody notices until the system breaks in a confusing way.
The Remaining Tension
Static files are not going away. They are cheap, transparent, and version-controlled alongside the code they describe. For small projects with stable conventions and a single developer, a well-maintained CLAUDE.md is harder to break than a running database process.
The split that is emerging is by workload size and update frequency. Static files work when context is stable and the human is willing to maintain it. Embedded stores become necessary when context changes faster than a human can curate it, when multiple agents share state, or when the agent needs to query its own history rather than just receive it.
The uncomfortable implication of Paterson’s framing is that most teams are using static files in situations that have already crossed the threshold where they stop working — and discovering the failure only after the agent has been operating on stale assumptions long enough to cause real problems.