September 25, 202610 min read

AGENTS.md vs CLAUDE.md: How Coding Agents Load Project Memory in 2026

Which instruction files Claude Code, Codex, Copilot, Cursor and Gemini CLI read, how nesting and precedence work, and what belongs in each file.

ByLokesh Kumar· Founder & Builder, Vyra
Share on XShare on LinkedIn

The short answer

AGENTS.md is the shared, tool-neutral instruction file. As of v2.1.277 on 18 September 2026, Claude Code reads it, but by default only when no CLAUDE.md or CLAUDE.local.md exists in your working directory or above it. Codex, Cursor and Copilot read AGENTS.md natively. Gemini CLI reads GEMINI.md unless you configure otherwise. Keep one AGENTS.md and import it where needed.

What changed in Claude Code this month?

A long-standing feature request on Anthropic's tracker, issue #6235 "Support AGENTS.md", has now shipped. The Claude Code changelog entry for v2.1.277 (18 September) reads: "in a project with no CLAUDE.md, Claude Code reads AGENTS.md instead; change it under 'Project instructions' in /config." The Hacker News thread on that entry is one of the month's larger discussions.

The memory docs spell out the default rule, which is stricter than many people assume:

The trap is CLAUDE.local.md. The docs note that adding one for your own uncommitted notes "stops Claude from reading AGENTS.md for you." If you want both, set Project instructions to claude-md-and-agents-md. The other values are claude-md-or-agents-md (default), claude-md, and managed-only.

There are also small behavioral differences. Per the same page, InstructionsLoaded hooks do not fire for an AGENTS.md read through the setting, and an AGENTS.md in a directory added with --add-dir does not load even when the environment variable that loads those directories' CLAUDE.md files is set.

What was the telemetry bug?

Five days after the release, Przemek published "Claude Code reads AGENTS.md only when telemetry is on". His finding: the AGENTS.md loader in v2.1.277 was gated behind a remote feature flag, tengu_agents_md_mod, defaulting to false. With DISABLE_TELEMETRY=1 or CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 set, the flag never arrived and local AGENTS.md files were skipped without any warning. He found the flag with a string search through the binary and confirmed the behavior with a canary word test, reporting it through v2.1.280.

His complaint was about the failure mode more than the flag: "The silence is the worst part." Users would, he wrote, "conclude that the model ignores their instructions." His workaround was a one-line CLAUDE.md containing @AGENTS.md, which uses the import mechanism and bypasses the flag.

The blog post itself does not report a fix. Anthropic's changelog does: v2.1.282 (24 September) "Changed AGENTS.md support to also work on Amazon Bedrock, Google Vertex AI, Microsoft Foundry, LLM gateways, and sessions with telemetry disabled." The memory docs phrase the boundary slightly differently, saying that "Before v2.1.281, some sessions, such as those on Amazon Bedrock or with telemetry disabled, read CLAUDE.md files only." Either way, if you run with telemetry off or through a cloud provider, update and then check /context to confirm what loaded.

The broader lesson for anyone building agent tooling: a local file read should not depend on a network round trip, and a missing instruction file should be visible to the user.

Which file does each coding agent read?

Every row below comes from the vendor's own docs, fetched this week.

AgentFile(s) readScope and precedenceSource
Claude CodeManaged CLAUDE.md, ~/.claude/CLAUDE.md, ./CLAUDE.md or ./.claude/CLAUDE.md, CLAUDE.local.md, .claude/rules/*.md; AGENTS.md when no CLAUDE.md exists (configurable)All files concatenated, root down to working directory; closer files read last. Subdirectory files load on demand when Claude reads files there. @imports up to four hopsAnthropic
OpenAI Codex~/.codex/AGENTS.override.md or AGENTS.md (global); per directory AGENTS.override.md, AGENTS.md, then project_doc_fallback_filenamesGit root to current directory, one file per directory, concatenated so later files win. Stops at project_doc_max_bytes (32 KiB default)OpenAI
GitHub Copilot.github/copilot-instructions.md; .github/instructions/*.instructions.md with applyTo globs; AGENTS.md anywhere; CLAUDE.md or GEMINI.md at rootNearest AGENTS.md wins. Personal over repository over organization. Agent instruction files not supported by all Copilot featuresGitHub
Cursor.cursor/rules/*.mdc (Project Rules), User Rules, Team Rules, AGENTS.md (root and nested)Team, then Project, then User; all merged, earlier source wins on conflictCursor
Gemini CLI~/.gemini/GEMINI.md, workspace and ancestor GEMINI.md, just-in-time subdirectory filesAll concatenated and sent with every prompt. context.fileName can add AGENTS.mdGoogle

Two things stand out. First, "precedence" mostly means ordering in the prompt, not a merge engine. Claude Code's docs say files "are concatenated into context rather than overriding each other," and Codex's docs describe later files winning because of where they sit in the prompt. The model resolves the conflict, and the Claude docs warn that with contradictory rules "Claude may pick one arbitrarily."

Second, Cursor is the outlier on direction. Its docs put Team Rules ahead of Project and User Rules, while Copilot ranks personal instructions highest. If you move between tools, the same personal preference can win in one and lose in another.

How do nesting and monorepos work?

The agents.md site states the convention in one line: "the closest AGENTS.md to the edited file wins; explicit user chat prompts override everything." It recommends one AGENTS.md per subpackage in a monorepo. The site says the format is used by over 60,000 open-source projects and is now stewarded by the Agentic AI Foundation under the Linux Foundation. Those are the project's own figures.

Implementations differ in when nested files are read:

The practical consequence: where you start the agent changes what it knows. Launching from the repo root versus a package directory gives a different instruction set in Codex and a different startup set in Claude Code.

What belongs in an instruction file?

The agents.md site lists the usual sections: project overview, build and test commands, code style, testing instructions, security considerations, commit and PR conventions, deployment steps. Anthropic's advice is narrower. Keep "facts Claude should hold in every session: build commands, conventions, project layout, 'always do X' rules," and target under 200 lines per file. Multi-step procedures go into skills or path-scoped rules.

Write instructions you could check. The Claude docs contrast "Use 2-space indentation" with "Format code properly," and "Run npm test before committing" with "Test your changes."

Things to leave out:

For cross-tool repos, the lowest-friction setup today is a single AGENTS.md with a CLAUDE.md that says @AGENTS.md followed by any Claude-only notes. Anthropic documents that the import never causes a double read. A symlink also works, but the docs note Git on Windows checks symlinks out as plain text unless core.symlinks is enabled.

Is an instruction file the same thing as agent memory?

No, and the distinction matters. An instruction file is static and human-written: it changes when someone commits to it. Learned memory is written by the agent as it works, from corrections and observations. See our explainers on persistent memory in AI assistants and memory versus RAG.

The vendors are converging on plain Markdown for both. Claude Code's auto memory writes to ~/.claude/projects/<project>/memory/, with a MEMORY.md index whose first 200 lines or 25KB load each session. Gemini CLI, per its memory docs, "persists durable facts, user preferences, and project details by editing Markdown memory files directly," routing shared facts into repository GEMINI.md files. That means the agent can write into the same file your team reviews as instructions, which is worth watching in diffs. Agent-written memory is also an attack surface, as covered in our post on memory poisoning.

Two recent essays push the file-format idea further. Cal Paterson's "Agent memory as a file format" proposes Memoryfields: a ZIP of Markdown pages with optional YAML frontmatter plus a SQLite vector index, arguing that "Memory should be a data format, not a multi-stage pipeline." Jordy Zomer's "I accidentally turned LLM memory into program analysis" goes the other way, storing an agent's findings as Datalog facts with provenance so that when an observation changes, in his words, "I want the affected conclusions to become invalid automatically." One favors prose, the other derivation, but both treat memory as inspectable data rather than hidden state. Curating that data over time is its own problem, discussed in memory consolidation for AI agents.

Common questions about AGENTS.md and CLAUDE.md

Does Claude Code read AGENTS.md now?

Yes, from v2.1.277. By default it reads AGENTS.md only when no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md exists in the working directory or above. You can switch to reading both via the Project instructions setting in /config.

Anthropic's docs recommend the @AGENTS.md import if anyone on the team uses Windows, since Git may check a symlink out as a one-line text file. The import also lets you add Claude-specific notes below it. Both approaches load the content once.

Which file wins when instructions conflict?

In most tools, nothing is formally merged. Files are concatenated, and the more specific or later file tends to win because of prompt position. The agents.md convention is that the closest file to the edited code wins and explicit chat prompts override everything.

Was the telemetry bug fixed?

The original blog post does not say so. Anthropic's changelog for v2.1.282 (24 September 2026) says AGENTS.md support was changed to also work in sessions with telemetry disabled and on Bedrock, Vertex AI, Foundry and LLM gateways.

Is AGENTS.md the same as agent memory?

No. AGENTS.md is a static file humans write and review. Agent memory is written by the agent during work, such as Claude Code's auto memory directory or Gemini CLI's memory files, and needs different review and trust rules.

Where Vyra by Vyraagi stands

Vyra by Vyraagi is a desktop agent, not a coding agent, and it does not read AGENTS.md or CLAUDE.md. Its memory is the learned kind: episodic memory plus a structured world model, consolidated nightly and held on-device. Vyra is in closed alpha, and OS support will be confirmed at beta. More on the design in what Vyra is and AI assistant with memory.

Sources

Vyra by Vyraagi keeps its learned memory on your machine; if that is the kind of agent you want, join the waitlist.

Vyra is in closed alpha now, with a Founders Beta ahead of public launch.

Join the WaitlistSee Plans

Related reading

Memory Poisoning: The AI Agent Attack That Waits Weeks to Go Off

Agents that remember can be tricked into remembering the wrong thing. How memory poisoning works, the four attack types researchers found, and what actually defends against it.

Why an AI Agent Needs to Forget on Purpose

A bigger context window does not fix agent memory. Consolidation — periodically compressing episodes into structure and letting importance decay — is what keeps recall usable past month three.

Memory vs RAG: Why Retrieval Alone Doesn't Make an Assistant Remember

RAG retrieves from documents you supplied. Memory is written by the assistant as it works. They solve different problems, and confusing them is why so many "AI with memory" builds disappoint.