Claude Code Memory Explained: CLAUDE.md, Auto Memory, and /memory

Every Claude Code session starts with an empty context window. It doesn't remember yesterday's conversation, the bug you fixed together, or that you told it three times to use pnpm.

What it does have is memory files — plain Markdown on disk that load at the start of every session. There are two kinds, and knowing which is which saves a lot of repeating yourself.

The two memory systems

	CLAUDE.md	Auto memory
Who writes it	You	Claude
What's in it	Rules and instructions	Learnings: your preferences, corrections, project context
Where	Your project (and a few other places)	~/.claude/projects/<project>/memory/
Shared with the team?	Yes, if committed	No — it's on your machine only

Both are loaded as context, not enforced settings. Claude reads them and tries to follow them, but nothing stops it from slipping. For "this must never happen" rules, use a hook instead.

CLAUDE.md: the instructions you write

A CLAUDE.md file is where you write down what you'd otherwise explain at the start of every session: how to run the tests, which package manager to use, where things live, what not to touch.

It can live in several places, from broadest to most specific:

• ~/.claude/CLAUDE.md — your personal preferences, every project
• ./CLAUDE.md or ./.claude/CLAUDE.md — the project's shared instructions (commit this)
• ./CLAUDE.local.md — your private notes for this project (add it to .gitignore)

Files in parent directories load at launch too. Files in subdirectories load later, when Claude opens a file in that folder. They're all added together rather than one replacing another.

The fastest way to start one is /init, which looks at your codebase and writes a first draft. (What /init does)

What a good one looks like

Short and specific. Anthropic's own guidance is to keep each file under about 200 lines, because longer files cost more context and get followed less reliably.

# Commands
- Install: pnpm install
- Test: pnpm test (run before every commit)
- Dev server: pnpm dev on port 3000

# Conventions
- API handlers live in src/api/handlers/
- Use Zod for all request validation
- Never edit files in src/generated/

"Use 2-space indentation" works. "Write clean code" doesn't — there's nothing to check it against. (How to write a CLAUDE.md that actually helps)

Auto memory: the notes Claude writes

Auto memory is on by default. As you work, Claude decides some things are worth remembering and writes them down itself — you'll see "Saved 1 memory" or "Recalled 2 memories" in the interface.

It saves four kinds of notes:

• user — your role, experience, how you like to work
• feedback — corrections you gave and approaches you confirmed
• project — decisions and deadlines it can't work out from the code
• reference — where outside information lives (an issue tracker, a dashboard)

It deliberately skips anything it could rediscover by reading the code, and anything already in your CLAUDE.md.

The notes live in ~/.claude/projects/<project>/memory/: one Markdown file per memory, plus a MEMORY.md index. Only the index loads at startup (the first 200 lines or 25 KB); Claude opens the individual files when it needs them.

If you say "remember that the API tests need Redis running", that goes to auto memory. If you say "add this to CLAUDE.md", it goes to CLAUDE.md.

Viewing and editing: /memory

Type /memory in a session. It lists your CLAUDE.md files (including ones that don't exist yet, so you can create them), lets you toggle auto memory on or off, and opens the auto memory folder.

Everything is plain Markdown. If Claude saved something wrong, open the file and fix or delete it.

To see what actually loaded into the current session, run /context and look under Memory files.

"Claude isn't following my CLAUDE.md"

The usual causes, in order:

1. It didn't load. Check /context. A file in the wrong folder is invisible.
2. It's vague. "Be careful with the database" gives Claude nothing to act on.
3. Two files disagree. If your personal file says one thing and the project file another, Claude may pick either.
4. It's too long. Important rules get lost in a 600-line file.
5. It needs to be a hook. "Run the linter after every edit" is a job for automation, not a polite request.

After /compact, the project-root CLAUDE.md is re-read from disk, so it survives. Instructions you only typed into the chat don't — if it matters, put it in the file. (/compact vs /clear)

What memory doesn't do

Memory files carry instructions and facts. They don't carry the conversation itself, and auto memory is machine-local — it doesn't follow you to another laptop or a cloud session.

That second point catches people who move between machines: the notes Claude built up on your desktop aren't there when you open a session somewhere else. (Why AI agents forget)

The summary

• CLAUDE.md = rules you write. Commit the project one.
• Auto memory = notes Claude writes. Stored per project on your machine.
• /memory to view and edit both; /context to see what loaded.
• Keep instructions short and checkable. Use hooks for hard rules.

---

EasySpawn runs Claude Code on a persistent server, so your CLAUDE.md, auto memory and project files are in the same place every session — from your laptop, your phone or a browser. See how it works or join the waitlist.

Related: How to Write a CLAUDE.md That Actually Helps · Claude Code /compact vs /clear · What Is a Context Window? · How to Resume a Claude Code Session