handbooksMemory management
How CLAUDE.md, auto memory, and .claude/rules work together, and the commands that let you review and edit everything Claude remembers at once.
- Claude Code has three memory-like mechanisms:
CLAUDE.md(you write it), auto memory (Claude writes it, from corrections you make mid-conversation), and.claude/rules/(scoped to one part of your project). - All three load automatically and all three are advice Claude reads, not rules it is forced to obey.
- Type
#followed by text, mid-conversation, to append a memory without leaving Claude Code. - Do not expect any of this to hold with certainty. A rule that must never be broken belongs in a hook instead.
The three mechanisms
CLAUDE.md is the one you write yourself: durable facts and conventions, checked into git or kept in your home directory. See CLAUDE.md for the file format and the smallest working example.
Auto memory is a set of notes Claude writes on its own, based on corrections you make during a conversation. You do not create these files by hand, and there is no fixed path to edit directly, you review and manage them through the commands below instead. Auto memory loads at the start of every session, the same as CLAUDE.md, and Claude treats both the same way: context to consider, not rules it is forced to obey.
.claude/rules/*.md is a separate, scoped layer. Use it for instructions that should only apply to files in a specific subtree, a backend/ directory's own conventions, say, rather than the whole project. Unlike CLAUDE.md, a rule file only loads when Claude is actually working in the part of the tree it covers.
Precedence, when more than one applies
The same hierarchy that governs CLAUDE.md governs memory generally. Files higher up load first: an enterprise-managed file, if your organization has one, before your project's, before your personal one. Claude Code walks the directory tree as it works, so a CLAUDE.md or rules file in a subdirectory you have not touched yet simply has not loaded.
None of these files override each other the way a stronger settings.json overrides a weaker one. They all load and sit together as context, more specific instructions alongside more general ones, rather than one replacing the rest.
Quick ways to manage it
- Type
#followed by text, mid-conversation, to append a memory without leaving Claude Code. - Run
/memoryto open every memory file for review,CLAUDE.md,.claude/rules/, and what auto memory has written, in one place. - Run
/initto have Claude generate a startingCLAUDE.mdby analyzing your codebase.
Run /memory in any project. You should see your personal and project CLAUDE.md files listed alongside anything auto memory has written so far.
When memory is not enough
A rule that must never be broken, not "usually followed," but never, belongs in a hook instead, which runs as a command rather than being read as advice. A multi-step procedure you only need occasionally belongs in a skill, so it does not cost context on every unrelated message.