One AGENTS.md Is Not Enough: My Three-Layer Agent Memory
A repo with many coding agents needs more than one instruction file: AGENTS.md for procedures, user memory for preferences, a fact store for on-demand facts.
TL;DR
Repeated agent mistakes in a repo pointed to missing documentation, not a bad agent. The fix is a three-layer setup: AGENTS.md for repo procedures, user memory for personal preferences, and a fact store for reference material. Claude Code reads the same rules through a CLAUDE.md that imports AGENTS.md, keeping every session consistent.
Third session of the week. A different coding agent, same repo, and it repeated the same mistake I had already corrected twice: ignoring the project's test wrapper and running the raw command instead. Fresh agent, zero memory, same wrong move.
Nothing was wrong with the agent. The repo was the problem. Every session started from zero, and the only thing standing between a fresh agent and my conventions was whatever it could infer from the code. Inference is not documentation.
My first fix was exactly what you would expect: one big rules file, everything in it. Build commands, commit style, my preferences, the works. The result humbled me. The more I stuffed in, the more the important rules got lost in the noise. Anthropic says this explicitly in its Claude Code best practices: bloated instruction files cause the actual instructions to be ignored [3]. Their test for every line is simple: if removing the line would not cause mistakes, cut it.
So I went looking for a healthier pattern and found agents.md. Not a framework, not an SDK, just a markdown file at the repo root containing instructions for coding agents. The official site calls it "a README for agents": a dedicated, predictable place for the context AI coding agents need [1]. Adoption is not niche either; the site counts over 60 thousand open-source projects using it [1]. One file, read by many agents, no duplication per tool.
Three layers, not one
The real unlock was realizing one file was never the right container. A monolithic rules file mixes different kinds of knowledge, and only one of them belongs in the repo.
First layer: AGENTS.md in the repo, holding repo procedures only. How to build, how to test, commit conventions, what never gets touched. Things that are true because of this codebase and would be wrong anywhere else. For monorepos the format supports nesting: agents automatically read the nearest file in the directory tree, and the closest one wins [1]. Each subproject can ship its own rules without bloating the root file.
Second layer: user memory. My preferences that follow me across every project. This is about me, not the repo, so it lives outside the repo. My model here is Claude Code. It carries two kinds of knowledge across sessions: instruction files written by the human, and auto memory, notes it writes itself from my corrections [2]. The second one is the time-saver. I correct an agent once, it takes the note, and I stop retyping the same feedback every session. The notes can be reviewed and deleted when they go stale.
Third layer: a fact store for on-demand knowledge. Conventions, decision records, reference material the agent needs occasionally. These are stored separately and looked up when relevant instead of being loaded every session. The reason for the split is volatility. Repo procedures rarely change. Developer preferences drift over months. Reference facts change weekly. Mix them in one file and the frequent updates make the stable parts noisy.
Bridging to Claude Code
One detail that makes the pattern practical: Claude Code does not read AGENTS.md, it reads CLAUDE.md. The official docs state it plainly: if your repository already uses AGENTS.md, create a CLAUDE.md that imports it so both tools read the same instructions without duplicating them [2]. One import line does the job; anything Claude-specific goes underneath.
The end result is bigger than tidy files. Agents from different vendors work in the same repo and read the same procedures. A correction I give one agent does not vanish for the others, because preferences and learnings live in dedicated layers instead of scattered chat history. Instruction files stay short because they no longer store everything. And each new session starts with fewer forgotten rules than the last.