AGENTS.md: The File That Gives Your Agent a Memory
AGENTS.md is the file your agent harness loads before the model wakes up. Here is what belongs in it, what to cut, and how to keep it from rotting.
AGENTS.md does not make the model smarter. It tells the model what it would otherwise have to re-discover every single time.
The model has no memory. This is not a limitation they plan to fix. It is how transformer inference works: you give it tokens, it produces tokens, and when the session ends everything it learned about your project disappears. The next session starts from zero.
That is not a bug you work around. It is a constraint you design for. The file that does the most work in that design is AGENTS.md.
The model wakes up with amnesia
Anthropic’s guidance for long-running agents uses the analogy of engineers working in shifts. Each engineer arrives at the worksite with no memory of what happened on the previous shift. They read the handoff notes, check the git log, and only then start work. Anthropic recommends: leave a progress file, read the recent commit history, run end-to-end verification before touching anything.
Your AI coding agent is that engineer, every single session. Without a handoff, it makes assumptions. Some of those assumptions are wrong. They accumulate into drift: the agent refactoring things it was told to leave alone, picking a library you already replaced, breaking conventions it was never shown.
AGENTS.md is the shift handoff. Not a full brief. A tight list of the things the next session actually needs to know before it touches your codebase.
What AGENTS.md is
AGENTS.md is an emerging open standard: a plain text file, usually Markdown, that the agent harness reads at session start and injects into the model’s context before it sees your first message. It is instructions-as-memory. Not docs for humans. Not a README. Not a spec. Standing orders that persist across sessions because the file does, even when the model’s state does not.
Several agents already treat it as a native primitive. pi, the open-source coding agent by earendil-works (Mario Zechner), reads AGENTS.md automatically from the current directory and every parent directory up the tree, plus a global ~/.pi/agent/AGENTS.md for cross-project standing orders. The cascade is deliberate: project-level rules override global defaults, and directory-level rules override project rules. You can have one file that shapes every project, and a narrower file that shapes this one.
LangChain frames the filesystem as the most foundational harness primitive and defines an agent as model plus harness. An AGENTS.md sitting in your repo root is the simplest possible expression of that primitive: a durable file that survives context resets and tells the model how to behave in this specific project. The harness engineering article goes deeper on the full architecture; this is the piece focused on the memory layer inside it.
What belongs in it
The lean version of AGENTS.md has three things.
What the project is. One paragraph. Not the pitch deck. What the system does, what it is built with, and what a typical task looks like. The model should be able to orient itself before it sees your first instruction.
Non-obvious conventions. The things a competent engineer would get wrong on their first day. The module that must never be touched without a migration. The linter rule that looks redundant but catches a real class of bug. The deploy sequence that has a non-obvious order dependency. If a senior engineer who knows your stack would still get it wrong, it belongs here. If they would guess it right, it does not.
Pointers to deeper context. Paths to the spec files, the architecture diagram, the ADRs, the environment variable reference. The agent can fetch those when it needs them. Do not paste them inline.
What belongs
- Required:One-paragraph project summaryWhat it does, the stack, and what a typical task looks like.
- Required:Non-obvious conventionsThe things a new engineer would get wrong on their first day.
- Required:Links or paths to deeper docsSpecs, ADRs, environment references. Do not paste them inline.
- Anti-pattern:The full tech stack listed exhaustivelyThe model already knows React. Tell it only what is unusual.
- Anti-pattern:General coding principlesIf it applies to every project everywhere, it belongs in the global file or nowhere.
- Anti-pattern:The entire system architecture explained in proseThat is a spec or an ADR. Link to it.
What does not belong
A bloated AGENTS.md is worse than none. Every line you add burns context window on every turn. If your file runs to 500 lines, the agent spends thousands of tokens on standing orders before it sees your first message. Token cost compounds fast at that rate: a long AGENTS.md is not free memory, it is memory you pay for on every single request.
Worse, a long file is a file nobody updates. Six months in, half of it is stale, and the agent is operating on a fiction. The project moved to a new ORM two months ago. The file still says Prisma.
The patterns that kill AGENTS.md files:
Boilerplate instructions the model already follows. “Write clean code.” “Handle errors gracefully.” “Use descriptive variable names.” These cost tokens and change nothing.
General principles that apply to every project. Those belong in a global config or a team-level file, not in this project’s file.
The entire spec for a feature you are currently building. That is a separate artifact for a reason. A spec belongs in a spec file, versioned alongside the feature, loaded when you are working on it, and archived when it ships. Do not paste it into standing orders.
A wall of context the agent can look up on its own. It has a filesystem. Use it.
The pruning test
Anthropic published this test directly in their agent guidance. The test is one question per line: if removing this line would not cause the agent to make a mistake, cut it.
Run that test on your AGENTS.md every month. Take each line. Ask whether the agent would do something wrong without it. If the answer is no, the line is noise. Cut it.
This is not editing for style. It is editing for function. The goal is the smallest file that prevents the actual mistakes your project generates, and nothing else in it.
A real AGENTS.md, short enough to be useful
This is close to the one I ran during the 70-day build: a 13-app crypto fintech, built solo with AI agents. Every session started by reading this file.
# Project context
Crypto fintech monorepo. 13 apps, 3 APIs (Rust), 3 PostgreSQL databases,
Kubernetes in production. Each app is a standalone Next.js workspace.
Work targets one app at a time unless a task explicitly spans multiple.
# Non-obvious conventions
- Never modify `packages/db` shared schema directly. All schema changes
go through a migration in the target app's `migrations/` directory.
- The `core-api` service owns auth. Do not implement auth logic in app-level
code.
- Linting: `pnpm lint` must pass before any commit. The rule set is strict;
do not disable rules inline without a comment explaining why.
- Environment variables: see `.env.example` in each app root. No secrets
in code or in this file.
# Where to find context
- Architecture: `docs/architecture.md`
- Feature specs: `docs/specs/<feature>.md`
- ADRs: `docs/adr/`
- API contracts: `packages/openapi/`That is it. Under 200 words. The agent navigates to those paths when it needs depth. The file itself stays lean.
AGENTS.md is not a spec
These two things get confused. They are not the same tool.
AGENTS.md is always-on memory. It loads every session, costs context every turn, and should contain only the standing orders that apply to every task you will ever run in this repo. It answers: how does this project work, always.
A spec is a per-feature artifact. It describes one change in detail: requirements, constraints, acceptance criteria, edge cases. It loads when you are working on that feature and gets archived when the feature ships. The spec-driven development article covers how to write one properly.
The right mental model: AGENTS.md is the employee handbook. The spec is the project brief. The handbook applies to everyone every day. The brief applies to one engagement. Do not put the brief in the handbook.
AGENTS.md
- 01Loads every session, every turn
- 02Contains standing orders for the whole repo
- 03Short, pruned, always current
- 04Lives at the repo root (and parents, and global)
- 05Covers conventions, not feature detail
Spec file
- 01Loaded for one feature, then archived
- 02Contains requirements for one change
- 03As long as the feature needs it to be
- 04Lives in docs/specs/ alongside the feature
- 05Covers intent, constraints, acceptance criteria
How to keep it from rotting
The file rots the moment you stop treating it as code.
Version it. AGENTS.md lives in the repo. Every change is a commit. If a convention changes, the file changes in the same PR. If you renamed the ORM, the file gets updated in the same change that does the rename.
Apply the pruning test on a cadence. Once a month is enough for active projects. The goal is to catch lines that stopped being true or stopped preventing real mistakes.
Keep the global file separate. Your global ~/.pi/agent/AGENTS.md (or the equivalent for your harness) holds things that apply to every project: your name, your preferred test runner, the code style you always use. The project file holds only what is specific to this repo. Mixing them causes drift in both directions: the project file fills with generic noise, and the global file fills with project-specific details.
Write the file for the next session, not the current one. When you finish a task and the conventions changed, update AGENTS.md before you close the session. The file should reflect the state of the project as of now, not as of six months ago when you first created it.
The honest version
The model is not going to remember your conventions. It is not going to remember you asked it to leave a module alone. It is not going to remember the migration pattern you explained last week.
That is not a flaw. That is the architecture. Design for it.
AGENTS.md gives the harness a file to read. The harness injects it. The model starts the session knowing the things it would otherwise have to re-discover or get wrong. That is not magic. It is writing things down in the one place the system actually reads.
Keep the file short. Keep it true. Run the pruning test. The agent you run against a 150-word AGENTS.md that someone maintains beats the agent you run against a 700-word AGENTS.md that nobody reads.
Common questions
Does every project need an AGENTS.md?
No. A short-lived experiment or a single-file script does not need one. AGENTS.md earns its cost when a project has conventions the model would otherwise get wrong, when multiple sessions are happening on the same codebase, or when more than one person is running agent sessions on the same repo.
If you could describe every convention in a one-sentence system prompt, just put it in the system prompt. AGENTS.md is for the projects where that description runs past a paragraph.
How is AGENTS.md different from a system prompt?
A system prompt is ephemeral: you set it for a session and it is gone. AGENTS.md is a file in the repo, versioned with the code, readable by the harness at any point. The system prompt is something you configure per session. AGENTS.md is something the harness reads automatically, so every session gets the same standing orders without you having to remember to paste them in.
How long should AGENTS.md actually be?
Short enough to read in sixty seconds. For most projects that is 100 to 250 words. The sample above covers a 13-app monorepo in under 200 words.
If your file exceeds 400 words, apply the pruning test before you add anything else. Every line past that point is a cost you pay on every turn. Most of them are not worth it.
Should AGENTS.md be committed to the repo or kept out of version control?
Commit it. AGENTS.md describes how to work in this codebase, and that description should change when the codebase changes. Git gives you history, blame, and review. Keeping it out of version control means the conventions drift silently. The one exception is if your AGENTS.md contains anything sensitive: secrets must never go into a committed file, and should not go into AGENTS.md at all.
pi reads AGENTS.md from parent directories. Should I put one at the repo root and one deeper?
Yes, when the repo has meaningful sub-contexts. A monorepo might have a root AGENTS.md with repo-wide conventions and a per-package AGENTS.md with package-specific rules. pi merges them by loading from the current directory upward, so the more specific file is read last and can override the broader one. Do not duplicate content across levels: if a rule applies everywhere, it goes in the root file only.
What is the difference between AGENTS.md and a CLAUDE.md or a Cursor rules file?
The concept is the same: a file the harness reads before the model sees your message. The filename varies by harness. Claude Code reads CLAUDE.md. Cursor has its own rules format. pi reads AGENTS.md. AGENTS.md is the name that has the strongest momentum toward a cross-harness open standard, which is why it is worth knowing regardless of which tool you run today.
If you switch harnesses, the content of the file transfers directly. The filename is just a convention.