An AGENTS.md file has a half-life. The instructions you wrote in week one are still there in week six — word for word — but the project has moved on, and now the file misleads your agent with total confidence. You never notice the moment it turns. You notice the third wrong decision.
The recent wave of AGENTS.md guides covers structure well: keep the entry file thin, layer the details, disclose progressively. That advice is correct — and insufficient, because structure solves loading, not freshness. The fix for rot is a maintenance layer: files split by how fast they change, write-back treated as part of the work, mechanical checks instead of good intentions, and a human gate on what becomes truth. The rest of this post is that layer, exactly as we run it in production.
Disclosure: Wallaby Token operates an OpenAI-compatible inference API. We run our own project — code, deploys, monitoring, this blog — on AI agents whose memory lives in these files, and we log every memory failure they produce.
Three ways an AGENTS.md rots
We keep a failure log for our own agents, maintained inside real production work — shipping code, deploys, monitoring, content — not sandbox demos. Every time memory misleads an agent, the incident is written up after the fact: what the agent believed, why it was wrong, what we changed, and the check that should catch the next occurrence. Twenty-one entries so far, each one reviewed and fed back into tuning the files and the prompts. Grouped, they form three patterns — and not one of them is a structure problem:
- Decisions outlive their reasons. A constraint was chosen for a cause that no longer exists, but the file still states the rule without the reason. The agent applies it faithfully — that is the failure: it did exactly what the file says.
- The file only grows. Everyone adds, nobody deletes. Six months in, the critical rules are still present — drowned under forty lines of historical trivia the agent now weighs equally.
- Reality forks from the file. A script gets renamed, a directory moves, a command changes a flag. The file still points at the ghost, and the agent follows it off the edge.
Notice what all three have in common: the file was well-structured the whole time. And none of the three is exotic — they are the default failure modes of any AGENTS.md that nobody maintains, which means the same patterns are almost certainly sitting in your own last month of sessions, unlogged.
Why structure doesn't fix it
Progressive disclosure — the pattern behind agents.md conventions and modern skill files — answers one question: what enters the context window, and when. Rot asks a different question: is the content still true? A perfectly layered lie is still a lie, and a stale fact loaded in the cheapest possible way is still stale. If your maintenance plan is "we wrote a good AGENTS.md," you have week-one documentation and week-six fiction.
The maintenance layer
Four pieces. None of them is exotic; the discipline is the point.
Split by change frequency, not by topic. Permanent facts (decisions, iron rules), current state (work in flight), and history (append-only log) decay at completely different rates, so they belong in different files with different review cadences. When "what is true this week" lives in its own small file, refreshing it is a two-minute job instead of an archaeological dig. Our public template splits these as MEMORY.md / NOW.md / INDEX.md for exactly this reason.
Write-back is part of the work. The rule that keeps the system alive: a session is not done when the code is done — it is done when what changed has been written back to the files. Skip it twice and you are back to trusting the context window, which is where the rot started.
Mechanical checks beat good intentions. Anything that depends on remembering to check will eventually not get checked. We run a zero-dependency script that flags drift mechanically: files that exist but are registered nowhere, "current state" entries that have stopped moving, contradictions between layers. The script is dumb and that is its virtue — it never has a busy week.
A human gate on what becomes truth. The agent proposes memory writes; a human approves what becomes fact. Anything the agent is unsure of goes on a to-confirm list — never into the files. This is the difference between a memory system and a very organized hallucination archive.
The honest limit: the model is the floor
Files raise the floor of what an agent can do reliably; they do not remove the floor. A weaker or less careful model will break any discipline you write down — it will read the index and invent a path anyway, nod at the write-back rule and skip it. We have watched this happen on our own system. So treat the maintenance layer as multiplicative, not magical: good files with a strong model compound; good files with a careless model just fail more politely. If your agent keeps ignoring the files no matter what you do, the problem may not be your files.
What we run, and what we publish
The file layer and the health-check script are open source in wallaby-agent-rules — the same files we use daily, MIT licensed, installable by pasting one prompt into whatever agent you already use. The backstory and design principles are in AI remembers, you find; the token-budget view of the entry file is in AGENTS.md as a token budget.
We did not publish a product, because there isn't one: no service, no sync, no lock-in. What we published is the part that survives being given away — plain files and the habits that keep them true.
Rolling out to a team
Memory files live in the repo, so a team inherits them with git clone — the new hire's agent starts with the same memory as yours, and git blame doubles as the audit trail for who changed which fact and why. Keep the human gate human: memory writes go through the same review as code, and the failure log works best as a shared file the whole team appends to. On the account side, one prepaid balance covers the whole team's agents, with one named key per developer and per-key caps — the mechanics are in One endpoint, one bill.
Your code, your business
Three commitments, verbatim from our privacy policy: No content logs. No training on your data. No usage reports built from your traffic. Usage lines record token counts, costs, and timing — never prompts, never completions. Your memory files never touch our systems at all — they live in your repository, which is the entire point.
Reliability you can verify
We operate a public status page so you can verify availability independently before troubleshooting your own setup. Our terms are written in plain language and publicly accessible. Wallaby Token is a registered Australian company with an ABN on file, and we run our own development workloads through the same gateway we sell — the agents behind this post ran on it.
Get started
The fastest path is the L0 prompt in PROMPT.md — paste two lines, watch your agent build the five files and hand you the first project map. Then do the one thing this post is actually about: pick a moment this week to write back what changed.