CLAUDE.md
CLAUDE.md is not project memory
CLAUDE.md and AGENTS.md are instruction files. They tell an agent how to behave: commands, style, guardrails. Project memory is what the team has learned (architecture, decisions, conventions, handoffs), kept next to the code and updated when the code changes. You want both. A 2,000-line rules file is not both.
| Artifact | Who writes it | When it loads | How it goes stale | How a teammate sees it |
|---|---|---|---|---|
| CLAUDE.md / AGENTS.md | humans, sometimes an agent | usually every session | silently, as the repo moves | if it is committed |
| Chat / auto-memory | the tool | that person, that machine | it never reaches the teammate | usually it doesn’t |
| Project memory (mex) | team + agents, reviewed | retrieved when relevant | mex check / grounding against the tree | git pull |
mex does not ask you to delete CLAUDE.md. Setup installs a small anchor and routes the agent into project memory instead of stuffing the whole wiki into the rules file.