Give Claude Code a memory that lasts between sessions

Every Claude Code session starts with an empty conversation. What carries over is whatever it loads from memory files. Get those right and you stop explaining your project every morning.

#CLAUDE.md: the memory you write

CLAUDE.md is a plain Markdown file of instructions and facts. Claude Code looks for it in several places and loads all of them, broadest first:

They're combined, not overridden. Files closer to where you're working are read last, so a project instruction naturally sits after your personal defaults.

CLAUDE.md files in subfolders work too. They load when Claude reads or edits files in that folder, so api/CLAUDE.md only costs context when you're working on the API.

#Start with /init

Run /init in a project and Claude Code writes a first CLAUDE.md from what it finds in the code. Treat it as a draft: delete anything Claude could work out by reading the code, and add what it couldn't.

Two more commands help you see what's going on:

• /memory opens your memory files and lets you turn auto memory on or off.
• /context shows which memory and rules files were loaded.

#What to write

The best CLAUDE.md is short and holds things the code doesn't say:

# Project notes

- Run tests with `npm test`; the e2e suite needs `docker compose up` first.
- Money is stored in pence as integers. Never use floats for amounts.
- `legacy/` is frozen. Don't refactor it; add adapters in `src/compat/`.
- We chose Postgres over Mongo for reporting joins. Don't propose switching.

Good entries are commands, conventions, traps and decisions with their reason. Poor entries summarise code that Claude can read for itself; they go stale and waste context every session.

#Split it up with imports and rules

When the file grows, break it apart:

• Imports. A line like @docs/architecture.md pulls another file into memory. Imports can nest up to four levels. To mention a path without importing it, put it in backticks.
• Rules. Files in .claude/rules/ are loaded like CLAUDE.md. Give one a paths field in its frontmatter, such as src/**/*.ts, and it only loads when Claude works on matching files.

---
paths: src/api/**/*.ts
---

- Every handler validates its input with the shared schema before touching the database.
- Return errors in the { error, message } shape used by src/api/errors.ts.

#Auto memory: notes Claude keeps itself

Auto memory is on by default in local sessions. Claude saves notes it thinks will help later in ~/.claude/projects/<project>/memory/, with an index file called MEMORY.md. The first 200 lines (up to 25 KB) of that index load at the start of every session, and the topic files it points to are read only when relevant.

You can read and edit these notes like any other file, and switch the feature off with /memory if you'd rather keep memory entirely by hand.

#What survives a compaction

Long sessions get compacted to free up context. The project-root CLAUDE.md is re-read from disk afterwards, so its instructions survive. Nested CLAUDE.md files and path-scoped rules load again the next time Claude touches matching files.

#Going further

The built-in files remember what you or Claude chose to write down. Tools like claude-mem go further: they record what happens in each session automatically, compress it, and bring relevant history back in later sessions. The Overclaud harness includes it, which is how Claude can recall a decision from last week without anyone writing it into a file.

#Questions

#How long should CLAUDE.md be?

As short as it can be while still saving you from repeating yourself. Everything in it is loaded every session, so each line should earn its place. Move detail into imported files or path-scoped rules.

#Should CLAUDE.md go in git?

The project CLAUDE.md, yes: it's shared knowledge for everyone working on the code. Keep personal preferences in ~/.claude/CLAUDE.md and private project notes in CLAUDE.local.md.

#What's the difference between CLAUDE.md and auto memory?

You write CLAUDE.md and it's loaded in full. Claude writes auto memory, and only its index loads up front.

#Sources

• Claude Code docs: Memory