Claude Code has two distinct memory systems that work together: CLAUDE.md files (instructions you write and maintain) and auto memory (notes Claude writes itself during sessions). Understanding both helps you build a workspace that gets more useful over time.
CLAUDE.md files -- your instructions to Claude
CLAUDE.md files are the primary memory mechanism. You write them; Claude reads them at every session start. They contain everything Claude needs to behave correctly in your workspace -- identity, conventions, file paths, rules, and references to supporting documents. This is deliberate, explicit memory: you decide what goes in, and it stays there until you change it.
There are three levels:
~/.claude/CLAUDE.md-- user-level; applies to all your workspaces on this machine[workspace]/.claude/CLAUDE.md-- workspace-level; applies to this repository only[workspace]/[project]/CLAUDE.md-- project-level; adds context specific to one piece of work
See the full CLAUDE.md Files guide for structure, imports, and size discipline.
Rules files -- granular instruction modules
Rather than putting all instructions in one long CLAUDE.md, split behavioural rules into separate files in .claude/rules/. Each file covers one concern -- communication standards, blocked commands, autonomy levels. All files in this directory are loaded automatically alongside CLAUDE.md.
Rules files are instructions, not learned knowledge. They are things you write deliberately to govern Claude's behaviour in specific situations. Examples: "always use UK English", "never send a client document without asking first", "always back up state before writing to it". CLAUDE.md memory is about context and identity; rules files are about operating procedures.
Auto memory -- notes Claude writes itself
Auto memory is a separate system where Claude records observations and facts during sessions -- things it has learned about your preferences, patterns it has noticed, context it should carry forward. Unlike CLAUDE.md (which you write), auto memory is dynamic: Claude updates it during conversations based on what you share.
What goes into auto memory
- Your stated preferences ("always use TypeScript strict mode")
- Corrections you have made to Claude's defaults
- Frequently referenced paths or project context
- Patterns in how you like work structured or presented
Practical examples of useful auto memory entries
These are the kinds of things Claude might store in auto memory after observing your working patterns:
- "User prefers bullet points over numbered lists for action items"
- "Client proposals should always include a cover page and a table of contents"
- "User's primary contact for invoice queries is accounts@clientname.com"
- "Reports go in Documentation/Reports/ -- not the project root"
- "Always check for duplicate project names before creating a new one"
You can also ask Claude to remember something directly: "Remember that my accountant's name is Sarah and her email is sarah@example.com." Claude stores this in auto memory and uses it in future sessions.
Viewing and editing auto memory
Auto memory is accessible via the /memory slash command. This opens a browseable interface showing what Claude has stored. You can review entries, edit them to correct mistakes, and delete anything that is no longer accurate.
/memoryAuto memory entries are stored in ~/.claude/memory/ as plain text files (markdown format -- readable in any text editor). You can also open them directly in a text editor if you prefer to manage them that way. There is nothing locked behind a proprietary format.
Privacy -- where is memory stored?
Both CLAUDE.md files and auto memory are stored locally on your computer, not on Anthropic's servers. CLAUDE.md files live in your workspace folders. Auto memory files live in ~/.claude/memory/ -- a folder in your home directory on your machine. Neither is synced to the cloud by default. If you use Claude Code on multiple machines, your memory does not automatically transfer between them unless you manually copy the relevant files or use a sync service.
Memory vs conversation context
Memory (both CLAUDE.md and auto memory) persists between sessions -- it is there every time you start Claude Code. Conversation context does not: when you start a new conversation, Claude does not remember what was said in the previous one. Memory is what bridges this gap. If something is worth Claude knowing in every future session, it should be in CLAUDE.md or auto memory. If it only matters for the current task, it can stay in the conversation.
The three memory layers compared
| Layer | Who writes it | Persists across sessions? | Best for |
|---|---|---|---|
| CLAUDE.md | You | Yes | Identity, conventions, file structure, stable instructions |
| Auto Memory | Claude (with your input) | Yes | Preferences, corrections, contacts, patterns observed during use |
| Conversation Context | Active session | No -- cleared when session ends | Current task details, in-progress work, temporary information |
Best practice: combine both systems
Use CLAUDE.md files for stable, intentional instructions -- the things you want to explicitly control. Use auto memory as a dynamic layer that captures preferences and corrections as they emerge in real use. Review auto memory periodically and promote useful entries to CLAUDE.md if they represent stable patterns worth codifying.
A practical workflow: when Claude gets something wrong, correct it in the session. Then decide where the correction belongs. If it is a one-off, leave it in the conversation. If you want Claude to remember it every future session, ask Claude to add it to memory, or add it to CLAUDE.md yourself. Over time, your workspace becomes a record of your working relationship with Claude -- and it improves with every session.
Building a workspace that improves over time
The most effective Claude Code setups are not fully designed upfront. They start with a minimal CLAUDE.md, then grow as real usage reveals what needs to be explicit. When Claude gets something wrong, correct it -- then decide whether the correction belongs in CLAUDE.md, a rules file, or auto memory. The workspace becomes a record of your working relationship with Claude.