Memory Management
The previous lesson covered project memory with CLAUDE.md. Claude Code actually has three distinct memory levels. Understanding all three lets you put the right context in the right place — and keep sessions focused.
Three levels of memory
Claude Code reads memory files from three scopes. All three are loaded before your first message. They stack — each level adds to the one above it.
| Level | Location | Scope |
|---|---|---|
| User memory | ~/.claude/CLAUDE.md | Every project on this machine |
| Project memory | CLAUDE.md (project root) | This project only — shared via git |
| Imported files | @path/to/file in your prompt | On demand, for a specific task |
User memory
A CLAUDE.md file in your home directory is loaded for every project on your machine. Use it for personal preferences that should apply everywhere — not project-specific rules.
How to create it
Project memory
The project-level CLAUDE.md at your repo root — covered in detail in the previous lesson. It holds everything specific to this codebase: stack, conventions, folder structure, and dev commands.
CLAUDE.md to git and every developer on the team benefits from it automatically.Imported memory files
Pull any file into context on demand using the @ prefix in your prompt. The file contents are inserted as additional context for that session — no permanent change to CLAUDE.md needed.
| Prompt | What it loads |
|---|---|
| @docs/api-spec.md — Implement the /users endpoint as described | API spec into context for this task |
| @prisma/schema.prisma — Add a Post model with title, body, and authorId | Current schema before Claude adds to it |
| @memory/stripe-setup.md — Set up checkout using the same pattern as before | Personal notes file with your preferred Stripe pattern |
memory/ folder in your home directory with Markdown files for recurring patterns. Reference them with @~/memory/stripe.md whenever you need them.How all three levels stack
When you open a project and send a message, Claude Code builds its context in this order. Each layer adds to the previous one — they do not override each other.
- User memory loaded —
~/.claude/CLAUDE.md: personal style, language, habits - Project memory loaded —
CLAUDE.md: stack, folder structure, conventions, commands - Imported files loaded (if any @): task-specific context you explicitly requested
- Your message — Claude responds with full awareness of all layers above
Choosing the right level
A quick reference for deciding which memory level to use for a given piece of context.
| Context type | Where to put it | Why |
|---|---|---|
| Preferred response style, language | ~/.claude/CLAUDE.md | Personal preference — applies everywhere |
| No-console-log rule for all my code | ~/.claude/CLAUDE.md | Universal habit, not project-specific |
| This project uses Next.js + Prisma | CLAUDE.md (root) | Project-specific, shared with teammates |
| Our components go in src/components/ | CLAUDE.md (root) | Convention specific to this codebase |
| API spec for the task I'm building now | @ import in prompt | One-off task context, not always needed |
| Personal Stripe integration notes | @ import from ~/memory/ | Cross-project but optional — load on demand |
A real example — all three levels
Here is what the full memory setup looks like for a developer working on a Next.js SaaS app, with personal preferences, project conventions, and a task-specific import.
~/.claude/CLAUDE.md — user memory
CLAUDE.md — project memory
Prompt with @ import — task-specific memory
Before your message, Claude sees: personal style from user memory, project stack and conventions from CLAUDE.md, and the full contents of docs/payments-spec.md from the import.
Before you continue
- Three memory levels: user (~/.claude/CLAUDE.md), project (CLAUDE.md), and @ imports.
- They stack — user first, then project, then any imported files.
- Put personal habits in user memory; put team conventions in project memory.
- Use @ imports for one-off task context you do not need every session.
- Next lesson: Understanding Sub-Agents.
What's Next
Memory management keeps Claude context-aware across long sessions. Next: Sub-Agents — how Claude delegates tasks to specialised agents.