Your agent forgets everything. Four ways teams fix it

Close the session and the agent forgets. Open a new one and it re-reads the same files, proposes the design you rejected on Tuesday, and asks the question you answered yesterday. Most people working with coding agents hit this early, and the fixes they reach for come down to four.

They are not equivalent, and the difference is measurable: what matters is not whether the agent can find the context, but how much of its context window it spends finding out. Here is what each one costs.

1. An instruction file — AGENTS.md, CLAUDE.md

The cheapest thing that works. One file at the repo root, read at the start of every session, carrying the rules: how to build, what to never touch, which conventions are real.

What it is good at. Stable knowledge. Coding standards, approval rules, the command that runs the tests. Things that were true last month and will be true next month.

Where it breaks. It is a single mutable file, so it has no history. When it says "we use X" and last week it said "we use Y", nothing records that the change was a decision rather than a typo — or why. It also grows: every session that appends a note makes the file that every future session must read longer. The file that was supposed to save context starts spending it.

Use it for how to work. Not for what happened.

2. A memory service

A vector store the agent writes to and searches — mem0 and its neighbours. The agent decides what is worth remembering, embeds it, and retrieves by similarity later.

What it is good at. Recall across projects and across time, without anyone maintaining anything. It is the only option here that works when you do not know in advance what you will need.

Where it breaks. It is a second system. The memory lives outside the repo, so it does not branch, does not merge, does not survive a colleague cloning the project, and cannot be reviewed in a pull request. Retrieval is approximate: you get what is similar to the question, which is not always what is true. And it is usually a network call and a vendor.

Use it for a single developer's long-running context across many repositories. Not for a team's shared record.

3. A decisions folder

ADRs — one Markdown file per decision, committed with the code. An old practice that turned out to suit agents well.

What it is good at. It is in the repo, it is reviewable, it has git history, and it answers why better than anything else on this list.

Where it breaks. Reversing a decision is two edits somebody has to remember to make: the new file, and the note on the old one. Skip the second and the folder confidently states two contradictory things, with no way to tell which is current. Worse, it is prose: the agent has to read and interpret every candidate file to know which apply. We measured that sifting cost on five real questions — grep returns 1.3 MB → 39 KB of candidate documents against the ones a link names.

Use it for reasoning that is worth a paragraph. Expect to police it.

4. An append-only journal

One event appended per change. Nothing is ever rewritten, so state is folded on read rather than stored — the same shape git itself uses.

What it is good at. The two properties the others are missing. Because nothing is edited in place, two branches touching the same task produce no conflict: across 8,396 merge commits in public repositories using file-based trackers, 15% hit conflicts in task files, and 89% of those were the content conflicts an append-only format removes. And because history is the storage rather than a side effect, "why" cannot silently go stale: superseding a decision is one event, not two edits.

The cost that matters. One task, read by an agent, is 982 bytes — and it stays that size whether the project has 10 tasks or 1,000, while the journal behind it grows from 5 KB → 528 KB. The agent reads an answer, not an archive.

Where it breaks. It is a format and a tool, which is more to adopt than a file you already have. It is bad at freeform knowledge — it records work, not everything you know. And a journal nobody writes to is worse than an AGENTS.md somebody keeps.

So which one

They are not exclusive, and the sensible arrangement uses two:

• AGENTS.md for how to work. Stable, small, rules only. Keep it short enough that every session can afford to read all of it.
• A journal for what happened. Tasks, their history, the decisions and the reasoning — the part that must not be quietly rewritten.

A memory service is the right answer when the context is one person's and spans many repositories. A decisions folder is the right answer when you will not adopt a tool, and you should expect to keep it honest by hand.

The thing to avoid is the arrangement most teams drift into: everything in one growing instruction file, because it started as three lines and nobody chose to make it the whole memory.

---