AGENTS.md: The File That Gives Your Agent a Memory

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. For the context around the repo (decisions, people, the meeting where something was decided), the next layer is an LLM wiki the agent reads.

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 open standard: a plain Markdown file 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. OpenAI donated it in December 2025 to the Agentic AI Foundation at the Linux Foundation, the same home as MCP.

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.

Every major agent reads it now

Does your tool read AGENTS.md? Almost certainly yes. The real differences are in how nested files combine, and that is where people get surprised.

Who reads AGENTS.md

Checked against each tool's own docs on October 6, 2026.

Agent	Reads AGENTS.md	Nested files
Codex	Yes, plus a global ~/.codex/AGENTS.md	Concatenated from the repo root down; closer wins
Claude Code	Yes since v2.1.277, when there is no CLAUDE.md	A subfolder's file loads when Claude opens a file there
GitHub Copilot	Yes	The nearest file wins
Cursor	Yes, as an alternative to .cursor/rules	Applies to its folder; the more specific file wins
OpenCode	Yes, and it beats a CLAUDE.md in the same place	First match walking up wins
Windsurf	Yes	A subfolder's file applies only inside it
Antigravity	Yes, alongside GEMINI.md	Global and project rules add up; specific wins
Gemini CLI	Only if you add it to context.fileName	Every file found is concatenated
pi	Yes, plus a global ~/.pi/agent/AGENTS.md	Every parent folder; deeper overrides

AGENTS.md vs CLAUDE.md: keep one file

CLAUDE.md is Claude Code’s name for the same idea. It used to be the reason teams kept two files and tried to keep them in sync. That reason is gone. Since v2.1.277, Claude Code reads AGENTS.md as project instructions whenever there is no CLAUDE.md or CLAUDE.local.md in the folder or above it. Your personal ~/.claude/CLAUDE.md does not count. The repo for this site has an AGENTS.md and no CLAUDE.md, and Claude Code loads it every session.

The trap is the default when both exist. With a CLAUDE.md present, Claude Code reads only the CLAUDE.md and ignores the AGENTS.md next to it. That is how a team ends up with two files drifting apart and one agent following the stale one.

Three setups work. Only AGENTS.md, for a repo more than one agent touches. A CLAUDE.md that imports it, when Claude needs lines the other agents should not see, or when you are on a Claude Code older than v2.1.277:

@AGENTS.md

# Claude Code only

- Use subagents for repo-wide searches.

Or a symlink, ln -s AGENTS.md CLAUDE.md. It works, but Claude Code’s Edit and Write tools refuse to write through a symlink, and on Windows the docs send you to the import instead.

Two files with copied content is the one setup that is always wrong. If you do keep a CLAUDE.md, the CLAUDE.md best practices guide covers what earns a line in it and what each line costs.

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. Vercel measured why the pointers belong in the file itself: on Next.js, an 8KB index of doc paths in AGENTS.md passed every one of their evals, while the same docs packaged as a skill, which the agent loads only if it decides to, passed 53 percent of the time. The same as no docs at all.

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.

There is now data behind the test. Evaluating AGENTS.md, a 2026 study, ran coding agents on real GitHub issues with and without context files. Files an LLM generated lowered the success rate slightly and raised inference cost by 20 percent or more. Files the repo’s own developers wrote did only slightly better, about 4 points, and the authors still call that no general improvement. What helped was the non-standard stuff: the conventions a model would not guess. The repository overview, the part everyone writes first, did not. That is why the summary above stops at one paragraph.

So do not let /init, the command that drafts the file for you, write it and walk away. A generated file is a draft to prune, not a memory.

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 (Fastify), 3 PostgreSQL databases,
Kubernetes in production. Each frontend is a standalone Next.js app.
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

1. 01Loads every session, every turn
2. 02Contains standing orders for the whole repo
3. 03Short, pruned, always current
4. 04Lives at the repo root (and parents, and global)
5. 05Covers conventions, not feature detail

Spec file

1. 01Loaded for one feature, then archived
2. 02Contains requirements for one change
3. 03As long as the feature needs it to be
4. 04Lives in docs/specs/ alongside the feature
5. 05Covers intent, constraints, acceptance criteria

Don’t let it become legacy code

The file turns into legacy code the moment you stop treating it as code. Nobody trusts it, and everyone works around it.

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 Claude Code read AGENTS.md?+

Yes, since v2.1.277, as long as there is no CLAUDE.md in the folder or above it. If a CLAUDE.md exists, Claude Code reads only that by default. On an older version, or when you need a CLAUDE.md anyway, start it with an @AGENTS.md line so the shared file is imported.

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 loads every AGENTS.md from the current directory up to the root, and the more specific file overrides 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, CLAUDE.md and Cursor rules?+

The concept is the same: a file the harness reads before the model sees your message. CLAUDE.md is Claude Code's filename and .cursor/rules is Cursor's format. AGENTS.md is the open standard, and both of those tools now read it too.

Keep one AGENTS.md as the source of truth. Add a CLAUDE.md or a Cursor rule only for lines that one tool needs and the others should not see.