Your agent starts every session with amnesia. A memory file, CLAUDE.md or AGENTS.md, is how it learns your project: commands, conventions and gotchas. The best ones are short, grown from real mistakes, pruned as models improve, and shared with the team.
Key takeaways
- AGENTS.md (or CLAUDE.md) is a README for agents, loaded at the start of every session.
- Put in what the agent can't infer: build and test commands, conventions, gotchas, where things live.
- Keep it short. For each line ask: would removing this cause mistakes? If not, cut it.
- Grow it from real mistakes, and prune it as models improve.
- Make it a map, not an encyclopedia: link to deeper docs and use nested files in subprojects.
Try it with your agent
Audit (or create) your memory file:
Read our AGENTS.md / CLAUDE.md (create one if missing). For each line, say whether removing it would make you err. Propose a version under 60 lines: commands (incl. single test), conventions you can't infer, gotchas. Link out to deeper docs.
Transcript
Intro
Your agent wakes up with amnesia at the start of every session. It doesn't remember your build command, your conventions, or the mistake it made yesterday. One small file fixes that.
What it is
The community standard calls AGENTS.md a README for agents: a predictable place for the instructions a coding agent needs. Claude Code reads CLAUDE.md the same way. It's loaded automatically at the start of every session. Big repos can add nested files in subfolders, and you can keep a personal one for your own preferences.
What goes in
What goes in it? Only what the agent can't figure out by itself. How to build and test, including how to run a single test. Conventions you can't infer from the code. Gotchas that have bitten you before. And pointers to where things live.
Keep it short
The most common mistake is making it too long. Anthropic's guide suggests a brutal test. For each line, ask: would removing this cause the agent to make mistakes? If not, cut it. Bloated files cause the agent to ignore your actual instructions.
There's a reason. Dex Horthy notes that frontier models can only follow roughly a hundred and fifty to two hundred instructions with good consistency. Beyond that, they're half attending to all of them. And your memory file shares that budget with the system prompt, the tools and your request.
Grow it from mistakes
So how do you write a good one? Don't write it all up front. Grow it from real mistakes. Mitchell Hashimoto says every line in Ghostty's agents file is based on a bad agent behavior, and together they almost completely resolved them. Boris Cherny's habit is the same: when the agent slips, tell it to add the lesson to the file.
Prune it
Then prune it, because models keep improving. A rule that was essential six months ago can over-constrain today's model. Thariq Shihipar from the Claude Code team expects memory files to shrink over time, and the team itself cut most of Claude Code's own system prompt for newer models.
A map, not an encyclopedia
For big projects, think of the file as a map. OpenAI's harness engineering team keeps a top-level agents file of about a hundred lines that works as a table of contents, pointing to deeper documents like architecture and design notes. The agent reads those only when it needs them.
Trails
Thorsten Ball calls nested files trails. Drop a small agents file into a subfolder, and the agent picks it up when it works there. The billing package can carry its own rules without cluttering everything else.
Team habits
Two team habits. Check the file into the repo, so everyone benefits from every lesson; Boris calls it a network effect. And don't copy a stranger's giant setup. Birgitta Böckeler warns you'll inherit contradictions you can't see, and then blame the agent for following them.
Quick check
Quick check. Your memory file has grown to nine hundred lines, and the agent seems to ignore half of it. What's the best fix? Tap your answer.
Try it
Let your agent audit its own memory file. This prompt asks it to justify every line and propose a short version that links out to deeper docs.
Recap
Recap. A memory file is a README for agents. Fill it with what the agent can't infer. Keep it short, grow it from real mistakes, and prune it as models improve. Make it a map, and share it with your team. Next: giving your agent new abilities with tools and MCP.