AGENTS.md is not a decision log

AGENTS.md tells an agent how to work in your repo. When that file goes stale, agents follow it anyway. Here is how to audit it, and why decisions need a log of their own.

·9 min read

This week the MindMux team read a set of public developer threads, issues, and comments about how people actually maintain AGENTS.md and agent memory. This is not a formal survey, and we are not attaching numbers we cannot verify. What follows is what kept recurring in those discussions, described without names, together with two recent papers and a practical way to split AGENTS.md from a decision log.

The wording was remarkably consistent. People talk about AGENTS.md sync, a stale AGENTS.md, re-explaining decisions in every new chat, and the need for one source of truth. They are not asking for a longer rules file. They are asking for somewhere that decisions can live without rotting.

Agents follow the file you forgot to update

AGENTS.md works because agents actually read it. That is also why a stale line is expensive.

On 6 November 2026, Tural Mehtiyev, Biruk Tadesse, Lawrence Arkoh, and Wesley Assunção (North Carolina State University) posted the preprint When Instruction Files Go Stale: Documentation Debt and Hidden Cost in Coding Agents. They studied three real-world stale instructions — a test command, a code location, and a procedure for adding a component — from active open-source repositories that had a root-level AGENTS.md or, in some of the cases they measured, a CLAUDE.md. Agents fixed 22 maintenance tasks under three versions of each instruction (left stale, corrected, or removed), with the code and the task held fixed. The authors analyzed 732 trajectories from two models, Claude Haiku 5.5 and Claude Sonnet 5.5, at the level of individual tool calls.

Agents followed stale guidance when it was relevant to the task, sometimes even when the correct information was already elsewhere in the repo. On the stale test command, Claude Sonnet 5.5 needed about two extra tool calls per run, a third more than with the corrected command. The agents still usually shipped a passing fix. They recovered by searching the codebase. In none of the 732 runs did they edit the instruction file. Correcting the stale line eliminated operations on obsolete paths; removing it prevented most of them. Task success hid the cost: the stale line stayed in the repo, ready to be loaded in the next session.

The study is a focused experiment, and the authors say so. It uses two models from one vendor, in one harness, on three cases of stale context and 22 tasks. The 732 runs repeat those cases rather than sampling a large set of independent debt items. Extra effort was clearly measured only for Sonnet on the stale test command; in the other cases, the authors could not detect a difference in tool calls or tokens.

That still matches what we kept seeing in public discussions this week. One developer audited a long standing instruction file and found claims that were already wrong: an outdated runtime, a payment provider the project had left, and references to migrations that no longer existed. The agent still followed the file, not the code. Another team's AGENTS.md had been generated by find-and-replace from an older, tool-specific file, so two tools were reading different project descriptions — even the model names were wrong. A third watched copies of the same guidance drift apart within a day, because a change landed in only one place. People copy the same AGENTS.md across repositories, then wonder how project-level overrides are supposed to work. Teams that finally measure which lines still help often cut the file dramatically, and start asking a better question: does a longer file just go stale faster?

An AGENTS.md that is loaded in every session will be obeyed in every session — including the lines that are no longer true. And the agent will not fix the file for you.

AGENTS.md is not a decision log

AGENTS.md has a job: tell the agent how to work in this repository. Which commands to run. Which directories not to touch. How to open a PR.

That is not the same job as remembering why you chose cookie sessions over JWT, that a payment provider was already replaced, or that last month's ruling reversed a rule still sitting in the file.

When those judgments have nowhere else to go, they leak into the wrong places. In the discussions we read, long-lived decisions sometimes lived only inside a model's memory, so the next session raised questions the team had already settled. Some people were about to write architecture decision records by hand, because nothing in the repo held the call. Teams admitted that without a written decision log, they re-decided the same things every week. And agent-written memory sometimes collided with a human-reviewed AGENTS.md, so two sources of what the project believes started to fight.

A second paper makes the underlying problem precise. On 10 November 2026, Yukyeong Lee, Yumin Choi, Jinheon Baek, and Sung Ju Hwang (KAIST and DeepAuto.ai) posted Don't Just Trust Your Memory: Evidence-Linked Memory Reduces Memory-Induced Degradation in LLM Agents, introducing WikiTrace. They looked at tasks an agent consistently solves without memory but fails once memory is added. 52% of those failures traced to a memory item the agent followed, most often a wrong one. Lessons had been distilled from past runs and handed over without the trajectory they came from, so the agent had no way to check them. Linking each lesson back to its source run raised average score from 87.0 (the same insights, with no source) to 90.2 across eight suites from five agentic benchmarks, and cut that kind of regression from 6.5% to 4.5%.

These results come from simulated text worlds and tool-use environments, not from repository instruction files, and some cause labels come from an LLM judge. They are still useful as a warning: a rule without its why is a rumor. A decision log has to keep the current answer and the evidence that produced it, including the reversals.

One source of truth, across tools and repos

The sync problem gets worse as soon as more than one tool is in the loop.

In the discussions we read, developers who use Claude Code alongside Codex — sometimes Pi as well — asked how a single AGENTS.md can carry the same premises across tools, so they do not have to re-explain the project when they switch. Agencies maintaining many client repositories were trying to decide how AGENTS.md and the rest of the docs should divide, and how they stay in sync. Some teams already use a coordination repo so that cloning one place lets an agent work across projects; the first reply, often, is that the file will go stale. Others do not want memory locked inside a single vendor's product at all. They want every agent to read the same record.

The industry is moving toward shared context for the same reason. On 10 November 2026, Cursor's Projects is now multiplayer post (Aryaman Khandelwal) put it plainly: a decision made in one chat is accessible to every agent in the Project. That is the right instinct. Agent context has been per-person; teams decide things together. The knowledge still has to belong to the project — in a form any tool can read, review in a PR, and still find after you change agents next month.

This is about cross-session, cross-tool memory for decisions that have already been made.

How to audit AGENTS.md — and where a decision should live

You do not need a new tool to start. The useful split is between how the agent should work in this repo and what the project has already decided.

Audit AGENTS.md. Open the file, including copies in other repositories or subfolders. For every command, run it or at least confirm the path still exists. For every directory or filename, check that it is still there. For runtimes, versions, vendors, and payment providers, check that the repo still uses them. If copies exist in more than one place, diff them: a change that landed in only one file is already drift. Anything that answers "why did we choose this?" or "what did we reject?" is a decision, not a standing rule — move it out.

Keep AGENTS.md short. It should hold commands to build, test, lint, and run; directories or files not to touch; how to open a PR; and other current, easily verified facts about the repo. It should not be the place that remembers the rationale.

Put decisions in a log. Each entry needs a current answer, a date, a short rationale, and a status — including what it supersedes, if a later call reversed an earlier one. Here is an illustrative example, not a record from a real project:

# Auth strategy

Status: active
Supersedes: JWT for the desktop app (2026-09-02)

Current answer: Cookie-backed sessions in the existing SQLite store.
The app is local-first and has no hosted backend.

- 2026-10-19 — Chose sessions over JWT. There is no server component
  that would justify JWT.
- 2026-09-02 — Evaluated Auth.js and Lucia; deferred. JWT looked like
  the default and did not fit a local-first app.

After the audit, correct or delete the stale lines. In the study above, correcting a stale instruction eliminated operations on obsolete paths, and removing it prevented most of them. Do not wait for the agent to repair the file. In those 732 runs, none did.

What MindMux does

MindMux makes a product in this space, so here is what that product actually does today.

MindMux captures background, decisions, and constraints from conversations with agents — the chats you already have — into a Markdown project brain that agents read over MCP before they start a task. The open, local counterpart, brain.md, is a brain/ folder in your repo plus a small CLI (@mindmux/brain-md). Every page keeps a compiled_truth — the current answer — and an append-only timeline of how you got there. It is git-native and agent-agnostic: Claude Code, Codex, Cursor, and anything else that can read a file.

AGENTS.md can stay short. The brain holds the decisions. When a conclusion changes, the old truth stays on the record. The next session, on the next tool, starts from the same understanding — not from a copied AGENTS.md that drifted yesterday.

This is cross-session, cross-tool decision memory.

If that is the problem you have:

If the first thing you notice is that you did not have to re-explain a decision, or that two tools finally read the same one, it is working.

Sources

Share to