AGENTS.md vs CLAUDE.md: What Each File Does and Where Agent Memory Belongs

Disclosure: Membase is our product. You don’t need it to use AGENTS.md or CLAUDE.md, and we cover both files first. Facts were checked against the Claude Code, OpenAI Codex and Cursor documentation and agents.md in November 2026.

Quick answer

AGENTS.md and CLAUDE.md are both Markdown files of instructions that a coding agent reads before it works: build commands, code style, project rules.

• AGENTS.md is an open format that many coding agents read, including Codex, Cursor, Gemini CLI, GitHub Copilot’s coding agent, Windsurf, Zed and Aider.
• CLAUDE.md is Claude Code’s own file, with extra features such as @imports, a personal CLAUDE.local.md and path-scoped rules.
• Claude Code now reads AGENTS.md too, from v2.1.277, when your project has no CLAUDE.md.

Which should you use? If your team uses more than one coding agent, keep your shared rules in AGENTS.md. Add a CLAUDE.md only for Claude-specific instructions, and start it with @AGENTS.md.

Neither file is memory. They hold rules you write. Decisions your agents learn while working need a memory layer, such as Membase.

In this guide: AGENTS.md vs CLAUDE.md at a glance · What is AGENTS.md · What is CLAUDE.md · How Claude Code reads AGENTS.md · Use one file for every agent · How Codex reads AGENTS.md · AGENTS.md vs Cursor rules · Example and template · Where agent memory belongs · FAQ

AGENTS.md vs CLAUDE.md at a glance

What is AGENTS.md?

AGENTS.md is “a README for agents”: one predictable place for the build steps, tests and conventions a coding agent needs, kept out of your human-facing README.

• It’s plain Markdown. There are no required fields; use any headings you like.
• It’s widely used. More than 60,000 open-source projects have one.
• It works in monorepos. Put another AGENTS.md in each package. Agents read the nearest file, so the closest one wins. Your own chat instructions override everything.
• It’s open. AGENTS.md came from work across OpenAI Codex, Amp, Google’s Jules, Cursor and Factory, and is now stewarded by the Agentic AI Foundation under the Linux Foundation.

Common sections: project overview, build and test commands, code style, testing instructions, security considerations, and commit or pull request rules.

What is CLAUDE.md?

CLAUDE.md is the instruction file Claude Code reads at the start of every session. It can live in several places:

It adds a few things AGENTS.md doesn’t standardize:

• @path imports, such as @README.md or @AGENTS.md, to pull in other files instead of copying them
• CLAUDE.local.md for personal notes you don’t commit
• .claude/rules/ for rules that apply only to certain paths

Run /init in Claude Code to generate a starter CLAUDE.md. More on how Claude Code remembers: How to Add Persistent Memory to Claude Code.

How Claude Code reads AGENTS.md

From v2.1.277, Claude Code reads AGENTS.md directly, with one rule:

By default, Claude Code reads AGENTS.md only when there’s no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in your working directory or any folder above it.

• If you have one of those, Claude Code reads it instead of AGENTS.md.
• Your ~/.claude/CLAUDE.md, your organization’s managed CLAUDE.md and .claude/rules/ files don’t count; they load alongside AGENTS.md.
• When Claude Code does read AGENTS.md, it also reads a subfolder’s AGENTS.md when it opens a file there, and expands @imports inside it.
• It doesn’t read AGENTS.local.md, AGENTS.override.md or anything under .agents/.

Want both? In Claude Code, type /config and set Project instructions:

Watch out: adding a CLAUDE.local.md for your own notes stops Claude Code reading AGENTS.md under the default setting. Switch to claude-md-and-agents-md to keep both.

Use one file for every coding agent

The simplest setup for a team that uses several agents:

1. Put shared rules in AGENTS.md at the repository root.
2. If you need Claude-specific instructions, add a CLAUDE.md next to it that imports AGENTS.md first:

@AGENTS.md

## Claude Code

Use plan mode for changes under src/billing/.

Claude Code reads the imported AGENTS.md first, then the rest. It never reads AGENTS.md twice, whatever your Project instructions setting.

If you don’t need anything Claude-specific, a symlink also works:

ln -s AGENTS.md CLAUDE.md

Two catches with the symlink: Claude Code edits the target file (AGENTS.md) rather than writing through the link, and symlinks can be unreliable for teammates on Windows. The @AGENTS.md import is the safer choice.

How Codex reads AGENTS.md

OpenAI Codex uses AGENTS.md as its instruction file:

• It reads your global ~/.codex/AGENTS.md first, then walks from the project root down to your current folder.
• In each folder it checks AGENTS.override.md, then AGENTS.md, and uses at most one file per folder.
• It stops adding files once they reach 32 KiB combined. Raise the limit with project_doc_max_bytes in ~/.codex/config.toml.
• Codex doesn’t read CLAUDE.md by default. To make it, add "CLAUDE.md" to project_doc_fallback_filenames in ~/.codex/config.toml; Codex then uses it in any folder without an AGENTS.md.

More on Codex: How to Add Persistent Memory to Codex CLI.

AGENTS.md vs Cursor rules

Cursor supports both:

A plain .md file in .cursor/rules is ignored; Cursor says to use AGENTS.md if you prefer plain Markdown. A common setup: AGENTS.md for shared rules, .cursor/rules for Cursor-only, path-scoped rules.

AGENTS.md example

# AGENTS.md

## Setup commands
- Install deps: `pnpm install`
- Start dev server: `pnpm dev`
- Run tests: `pnpm test`

## Code style
- TypeScript strict mode
- Single quotes, no semicolons
- Use functional patterns where possible
## Testing
- Add or update tests for the code you change
- Run `pnpm lint` and `pnpm test` before committing
## Pull requests
- Title format: [<package>] <Title>

AGENTS.md template

Copy this and fill in your project’s details:

# AGENTS.md

## Project overview
<What this project does, in two or three sentences>

## Setup and build
- Install: <command>
- Build: <command>
- Run locally: <command>
## Tests
- Run all tests: <command>
- Run one test: <command>
- Tests must pass before committing
## Code style
- <Language and formatter rules>
- <Naming conventions>
## Architecture
- <Where key logic lives>
- <Patterns to follow or avoid>
## Security
- <Secrets handling, files never to touch>
## Commits and pull requests
- <Message format, review rules>

Keep it short. Agents load these files into every session. Claude Code suggests staying under 200 lines per CLAUDE.md, and Codex stops at 32 KiB by default. Long files are followed less consistently.

Where agent memory belongs

AGENTS.md and CLAUDE.md hold rules you write. They’re not where an agent should keep what it learns:

Each agent’s built-in memory (Claude Code’s auto memory, Codex Memories) stays on one machine and in one tool. So a decision made in Claude Code doesn’t reach Codex or Cursor, or your teammates.

Membase keeps that memory in one place every agent can read. Connect it once:

npx add-mcp 'https://api.app.membase.com/mcp-http'

This adds Membase to Claude Code, Codex, Cursor and other MCP clients. Then add one line to your AGENTS.md, so every agent that reads it checks memory too:

## Memory
- Before starting a task, search Membase for past decisions about this code.

Rules in AGENTS.md, learned context in Membase, and every agent reads both.

Quick links

• Get a free Membase API key: connect memory to every coding agent
• How to Add Persistent Memory to Claude Code: CLAUDE.md, auto memory and Membase
• How to Add Persistent Memory to Codex CLI: AGENTS.md, Codex Memories and Membase
• Best MCP Memory Servers in 2026: memory servers for Claude Code, Cursor and Codex
• AGENTS.md: the open format and supported agents
• How Claude remembers your project: Claude Code’s official documentation
• Custom instructions with AGENTS.md: Codex’s official documentation
• Cursor rules: Cursor’s official documentation