MemoryBrain

MemoryBrain › Guides

CLAUDE.md, AGENTS.md and memory in Claude Code and Codex: what is each one?

CLAUDE.md and AGENTS.md hold project instructions. Auto memory keeps learnings between sessions. Codex looks for AGENTS.md; Claude Code can read either name, depending on its version, existing files and settings.

By Carlos Moya. Updated November 8, 2026.

Check what your agent is reading

  1. Identify the tool and version

    In Claude Code, run claude --version. Direct AGENTS.md support arrived in v2.1.277 on September 18, 2026. Keep these repository files separate from memory in a chat app.

  2. Check files and precedence

    Codex loads global instructions from ~/.codex first, then project instructions down to the working directory. At each level it selects AGENTS.override.md before AGENTS.md; guidance closer to the working directory overrides earlier guidance.

    By default, Claude Code uses AGENTS.md when it finds no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in the working directory or its ancestors. If it finds them, it uses the Claude files. In /config, “Project instructions” lets you change that selection and read both.

  3. Check loading as well as the answer

    In Claude Code, check /memory. Before v2.1.280, directly loaded AGENTS.md files did not appear there. In Codex, start a new session and ask it to list the instruction sources it loaded. Compare the paths with your files.

  4. Try a simple rule

    Add an observable convention, request a small change and inspect the result. Avoid secrets or deployment operations as a test. Reciting a rule does not demonstrate that the agent applies it.

Instructions and auto memory serve different purposes

AGENTS.md is an open format for guiding coding agents. Use it for real project commands and conventions reviewed by the team. It is not an automatic record of every session.

In Claude Code, auto memory contains notes Claude writes. Its index is MEMORY.md and you can review it through /memory. CLAUDE.md files accumulate from parent directories; closer files are read later and CLAUDE.local.md is appended after CLAUDE.md at each level. Avoid conflicting rules: these are context, not enforced permissions.

Codex also has its own local memory, separate from ChatGPT web memory. It is off by default. Once enabled, it can generate memory files from eligible prior chats and update them in the background, rather than necessarily when each chat ends. In Codex CLI, /memories controls whether the current chat can use memories or contribute to future ones. Generated files live under the Codex home directory, ~/.codex by default. Review them as generated state, rather than a replacement for AGENTS.md or instructions you routinely edit by hand.

A minimal file to adapt

This is an illustrative AGENTS.md. Replace the command with one that exists in your repository:

# Project instructions
## Validation
- Run npm test after changing logic.
- Say what you checked and what you did not.
## Style
- Follow the conventions of the file you edit.
- Explain why before adding dependencies.

If Claude does not load AGENTS.md directly, a CLAUDE.md beside it can contain @AGENTS.md. This is an explicit import; avoid maintaining two copies that drift apart.

Release v2.1.277 excluded Bedrock, Vertex and Foundry from the new support. That limitation belongs to that release. Current documentation describes later changes, including cases before v2.1.281. Check your version and actual loading before applying that exception to a current installation.

Where personal memory fits

Personal decisions and their sources can live outside the repository. MemoryBrain serves that memory to ChatGPT and Claude; it does not replace coding agent instructions or permissions. More: reviewing a memory file before trusting it.

Frequently asked questions

Can I use only AGENTS.md?

Codex recognizes it. Claude Code can read it too, but check the version, existing Claude files and the Project instructions setting.

Does CLAUDE.md enforce every rule?

No. It is context that guides the agent. Permissions and restrictions that must be enforced need tool controls.

Was this example tested in my repository?

No. It is an illustrative template. Adapt the test command and check loading in a new session.

Try it

See how a memory that keeps the source of everything works, no account needed.

Join the waitlistSee a demo, no account

Sources