CLAUDE.md and auto memory solve different tasks, and they should not be confused. CLAUDE.md is instructions that Claude Code adds to the session context: the team's reviewable source of truth, living in the repository under version control. Auto memory is notes Claude keeps itself between sessions: an auxiliary accumulation of experience. The first you write and review consciously, the second accumulates along the way; mixing their roles means either cluttering the source of truth or expecting the reliability of a contract from notes.
Memory is arranged hierarchically. Claude Code looks for managed memory, the user file ~/.claude/CLAUDE.md, the project CLAUDE.md or .claude/CLAUDE.md, nested files as work goes and the personal CLAUDE.local.md. More specific instructions apply closer to their path. If the organization already uses AGENTS.md, Claude Code does not consider it an automatic full equivalent - it is imported explicitly with the @AGENTS.md directive; likewise via @path other files are included, recursively to the documented depth of 4, but never secrets.
A good CLAUDE.md is a project contract, not a retelling of the structure. It has the purpose, verification commands, boundaries ("do not run production migrations", "do not touch generated code") and a definition of done. The main file is kept to about 200 lines - not a hard parser limit but a practical recommendation: long instructions take up context and lose salience. General facts stay at the root, and path-specific requirements are moved to rules.
Path-scoped rules are the key to cheap and precise memory. A rule in .claude/rules/*.md with a paths frontmatter turns on only when Claude works with matching files; a rule without paths loads always. It helps to see such a rule once: below is a rule for src/api with two requirements. This is cheaper and more precise than a huge root memory: the relevant instruction is loaded next to its code rather than hanging in the context on every task.
The /init and /memory commands help keep memory conscious. /init creates an initial CLAUDE.md - a draft, not automatically correct policy, and it is checked against the actual scripts and CI. /memory shows the loaded memory sources and opens their management. Regular review matters: memory easily gets overgrown with duplicates, wishes and stale facts that do not help but take up context and mislead the agent.
Auto memory is a separate mechanism with its own rules. It is on by default, and the autoMemoryEnabled setting turns it off - for the user entirely or in a single project; it is stored separately from committed instructions. Only the beginning of the memory is loaded into context - the first 200 lines or 25 KB, whichever comes first; the rest Claude reads as needed. Durable observations are written there, not temporary task state. Everything important to the whole team is moved into reviewed CLAUDE.md and rules - auto memory is not a replacement for the shared source of truth.
The engineering conclusion about memory is simple: it should reduce repeated exploration, not turn into a second backlog. A note is useful while it saves the agent from re-finding what is already understood; it is harmful when it accumulates wishes, stale guesses and what belongs in the tracker. Regularly delete the stale, do not store passwords, personal data and unconfirmed assumptions - memory with junk misleads no worse than a wrong instruction.
The typical memory failures are predictable. A bloated CLAUDE.md that takes up context and loses salience instead of a short contract. Path-specific requirements dumped in the root instead of rules. Expecting a mid-session CLAUDE.md edit to take effect at once - while it applies only after clear, compact or a restart. And auto memory as a dump instead of durable observations. Keep the contract short, rules by path, and memory reviewed.
---
paths:
- "src/api/**/*.ts"
---
# API rules
- Validate all external input at the boundary.
- Add a contract test for every response schema change.
# A rule without paths loads always; with paths - only on matching files{ "autoMemoryEnabled": false } // turn auto memory off (it is on by default)
// Auto memory is separate from committed instructions; into context - first 200 lines / 25 KB.
// Importing files into CLAUDE.md: @AGENTS.md, @path/to/file (recursive to depth 4)