File-Based Memory

A team adopts a coding agent, runs it for a few weeks, and hits the same wall every team hits: each new session opens with no idea what the last one learned. The agent re-discovers that the test suite needs a particular flag, re-derives the reason a certain directory is off-limits, re-litigates a naming convention that was already settled three sessions ago. Someone on the team, mildly annoyed, starts pasting a running list of "things Claude should already know" into a text file at the repo root and telling the agent to read it first. It works. Within a month, half the codebases at the company have one.

That is not a workaround. It is, with hindsight, the industry converging on an answer to a question the previous chapter left open. Chapter 7 established the memory ladder in the abstract — retrieval, then agentic search, then a store the agent both reads and writes — as a capability. This chapter is about the concrete, unglamorous shape that top rung actually took in practice by 2026, and it is worth naming plainly because it surprises people expecting something more exotic: not a database, not a vector store, not a bespoke memory service. Plain files, version-controlled, that both agents and humans can read.

What converged

The convergence is the finding worth sitting with. Independent teams building coding agents for different purposes — some optimizing for long, unattended runs, some for interactive pair-programming, some for round-the-clock autonomous loops — arrived at close to the same four-part stack without coordinating. Anthropic’s own guidance on harnesses for long-running agents describes an initializer step that creates a progress log the agent reads at the start of each session, plus a structured task file tracking which requirements pass and which don’t — deliberately choosing JSON over markdown for that file because, as the guidance notes, models are less likely to inappropriately rewrite a JSON file than a prose one. Practitioner write-ups of self-improving agent loops describe the identical shape under different names: a chronological progress log, a structured task/requirements file, and a standing conventions file the agent updates as it learns.

Lay the two descriptions side by side and four channels repeat: a chronological progress log — a running record of what was attempted, in what order, and what happened; persistent task or plan state — a structured record of what’s done, in-progress, and still open, so a fresh session doesn’t have to re-derive the plan from the conversation history; git commit history itself, which turns out to double as memory — a session’s diffs and commit messages are queryable after the fact, and an agent can run `git log` to reconstruct what changed and why without anyone having summarized it; and a standing instructions file — CLAUDE.md, AGENTS.md, or an equivalent — that gets read at the start of every session and, notably, gets written to by the agent as it learns things worth remembering.

The standing file, examined

Anthropic’s guidance on context engineering describes CLAUDE.md-style files as content that gets "naively dropped into context up front" — loaded unconditionally at session start, distinct from the just-in-time retrieval (glob, grep, targeted file reads) an agent uses to navigate everything else. That placement is deliberate: the standing file is small enough to afford unconditionally and important enough to not risk missing. The same guidance frames external files more broadly as a form of "agentic memory" — an agent that writes structured notes outside the context window specifically so they survive a compaction or a context reset and can be reloaded later, rather than depending on anything staying in the live conversation.

What makes this a genuine instance of agent memory, rather than a static prompt prefix, is the write path. A developer seeds CLAUDE.md or AGENTS.md with the conventions they already know; the agent then appends to it — a gotcha it hit and fixed, a pattern it noticed while working, a correction after being caught making the same mistake twice. Practitioner accounts of this loop describe sections for conventions, known pitfalls, and recent learnings, updated by the agent itself as sessions proceed, with the explicit caveat that the mechanism only works if the file’s content actually gets re-injected into every session’s context — a standing file nobody loads is not memory, it is an orphaned document.

This is also, by 2026, no longer a single-tool convention. AGENTS.md shipped alongside OpenAI Codex in August 2025 as a deliberate consolidation effort, with Google Jules, Cursor, Aider, and several other agents adopting the same filename in the same window — the multi-vendor motivation being exactly the problem this chapter opens with: without a shared convention, every tool invents its own memory file and every repository ends up carrying several redundant ones. By the end of 2025 the format had spread past twenty tools and more than sixty thousand open-source repositories, and in December 2025 OpenAI donated it, alongside Anthropic’s Model Context Protocol and Block’s goose agent framework, to a new Linux Foundation body built specifically to keep agent-facing standards vendor-neutral. The standardization is circumstantial evidence for the same conclusion the harness guidance and the practitioner write-ups reach independently: whatever else differs between these systems, the field converged on the same file-based answer to "how does an agent remember."

The Converged Memory Stack

No single channel does the whole job, and that is the design, not a gap. Git history is exhaustive but unopinionated — it records what happened, never why it mattered. The progress log supplies the narrative git omits, but degrades to noise if nobody prunes it. Task state answers "what’s left" without anyone re-reading a conversation, but only for work that was explicitly tracked. The standing file is the only channel built to generalize past a specific piece of work into a rule for the next one — which is exactly why it is also the one most prone to becoming unreliable if it grows without discipline.

Why files won, so far

The design argument for files over more sophisticated alternatives — a database, a managed memory service, a vector store as the primary mechanism rather than a retrieval aid — rests on four properties, and none of them are about model capability. Files are legible to humans without special tooling: a teammate opens CLAUDE.md in a normal editor and reads exactly what the agent has been told and has told itself, with no query console required. They are versioned for free by git, which gives memory a built-in audit trail — when a piece of standing guidance changed, `git blame` on the file answers it directly, a property a database row generally doesn’t have without deliberate schema work. They compose with review workflows that already exist: a change to standing memory shows up in a diff and gets reviewed the same way a code change does, rather than requiring a separate approval surface. And they degrade gracefully — a memory file that’s wrong is just wrong text, editable by anyone, not a corrupted index requiring specialized recovery.

None of that is an argument that files are the ceiling, only that they were the accessible floor, and the field reached for the floor first because it was cheap, inspectable, and already fit inside tooling every team had. That is consistent with the broader shape of this volume: context engineering keeps favoring the plainest mechanism that works over the more powerful one that requires new infrastructure, at least until the plain mechanism visibly breaks.

Where files break

And it does visibly break, in three specific ways worth naming rather than glossing over. First, file-based memory does not scale indefinitely: a CLAUDE.md that grows without bound — every gotcha ever discovered, every convention ever mentioned, never pruned — becomes its own instance of the context rot this volume named in Chapter 2, a standing file so large that loading it unconditionally costs more attention than it returns. The fix is editorial, not technical: someone has to prune the file the way they’d prune any other document that ages, which is a discipline most teams don’t yet have a name for or a habit of doing.

Second, files handle structured queries badly. A team six months into a project cannot easily ask a text file "which decisions touched the payment module" or "what did we try before, and why did it fail" the way a queryable store could answer directly — the answer is somewhere in the prose, if it was ever written down precisely enough to find, and finding it means an agent (or a human) reading and reasoning over unstructured text rather than running a query. This is precisely the gap the next chapter’s Decision Memory concept starts to close, by making individual decisions first-class and queryable rather than folded into a narrative log, and it is one of the gaps Chapter 10’s treatment of knowledge graphs as context addresses more fully by giving context explicit structure — entities and relations — rather than leaving everything as prose a model has to re-parse.

Third, and least technical: file-based memory only works if someone or something stays disciplined about writing to it. A standing file that nobody updates goes stale the same way tribal knowledge goes stale when the one engineer who knew it leaves. A progress log nobody prunes turns from memory into noise. This is fundamentally a process problem, not an architecture problem — the file format can be exactly right and the memory system can still fail because the write habit didn’t hold, which is the least satisfying kind of failure to diagnose because there’s no stack trace for a team that stopped updating a text file.

None of these limits argue for abandoning file-based memory — they argue for treating it as a first cut, not a final architecture. The four channels in the table above are cheap, auditable, and already compatible with how engineering teams review changes, which is why they converged on independently. The chapters that follow this one exist because those same channels run out of runway exactly where this chapter said they would: at scale, under structured query, and under the discipline problem of who keeps a text file honest.