Advanced

Memory & CLAUDE.md

Claude Code has no memory of previous sessions by default — each claude invocation starts fresh. CLAUDE.md files and the auto-memory system are the two mechanisms for giving Claude Code persistent context about your project and working preferences.

What CLAUDE.md Is

CLAUDE.md is a Markdown file that Claude Code automatically reads at the start of every session. It is the primary mechanism for persistent project context. Claude Code reads CLAUDE.md files from:

The project root directory (./CLAUDE.md) — project-wide instructions
Subdirectories (e.g., ./src/CLAUDE.md) — component or module-specific instructions, read when Claude is working in that directory
The user's home directory (~/.claude/CLAUDE.md) — personal global preferences applied to every project

CLAUDE.md files are checked into version control alongside the code — making project-level instructions part of the repository that all team members benefit from.

Writing Effective CLAUDE.md

CLAUDE.md should give Claude Code the information it needs to work effectively without reading the entire codebase from scratch each session. The most valuable content:

Commands: How to build, test, lint, and deploy the project. Example: "Build: npm run build. Test: npm test. Lint: npm run lint."
Architecture overview: The key files, directories, and their purposes. Claude Code can explore, but knowing the structure upfront saves exploration time.
Conventions: Project-specific patterns — naming conventions, file organisation rules, design patterns in use, anything Claude should follow when writing new code.
Known constraints: Things Claude should not do — production-only config files to avoid, branches to never push to, APIs that have rate limits, dependencies that should not be added.
Current state notes: Active work in progress, known issues, decisions made recently that affect what should be changed.

Generate an initial CLAUDE.md with /init — Claude Code will write a draft based on its exploration of the codebase. Edit it to add context Claude cannot discover by reading code.

Auto-Memory: How Claude Code Writes Memory

When auto-memory is enabled, Claude Code can write observations and decisions from the current session to memory files, making them available in future sessions. Memory is written to ~/.claude/memory/ (global) or .claude/memory/ (project-level).

Claude writes memory when it learns something that would be valuable in a future session:

Project conventions discovered during a session ("this project uses tabs not spaces")
User preferences stated during a session ("always ask before running tests")
Decisions made that affect future work ("we decided to use library X for this — remember for future sessions")

You can also manually instruct Claude to save something: "Remember for future sessions that [fact]."

Memory at Session Start

At the start of each session, Claude Code reads:

CLAUDE.md files in the project hierarchy (most specific first)
Global CLAUDE.md from ~/.claude/CLAUDE.md
Memory files from ~/.claude/memory/ and .claude/memory/

This content is included in the system prompt context for the session. Large CLAUDE.md files and many memory entries consume context window space — keep content concise and focus on what is non-obvious from the code itself.

Managing Stale or Conflicting Memory

Memory can become stale — code structures change, conventions evolve, decisions get reversed. Signs of stale memory: Claude makes decisions based on old information, references files that no longer exist, or applies conventions that have changed.

Maintenance practices:

Review CLAUDE.md when project structure changes significantly — update outdated commands, remove references to deleted files
Use /memory to review current memory entries and remove ones that are no longer accurate
Add a "last reviewed" note to CLAUDE.md so you know when it was last verified against the actual project
For conflicting entries: Claude generally gives more weight to information that appears closer to the top of CLAUDE.md — put the most important and most current information first

Checklist: Do You Understand This?

CLAUDE.md is read automatically at session start — the primary mechanism for persistent project context
Effective CLAUDE.md content: commands, architecture overview, conventions, constraints, current state notes
Generate an initial CLAUDE.md with /init, then edit to add context Claude cannot discover from code
Auto-memory writes per-session observations to memory files — use /memory to review and clean up
Review CLAUDE.md when the project changes significantly — stale instructions cause incorrect Claude behaviour