Claude CodeLesson 12 of 25

Memory Management

The previous lesson covered project memory with CLAUDE.md. But 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.

1
User memory ~/.claude/CLAUDE.md
Every project, every machine
2
Project memory CLAUDE.md (project root)
This project only
3
Imported files @path/to/file in your prompt
On demand, for a specific task

Level 1 — 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.

🏠
Level 1

User-level memory

~/.claude/CLAUDE.md

Scope: Every Claude Code session on this machine

Loaded globally, before any project CLAUDE.md. Ideal for your preferred coding style, language, response format, and habits you want in every project.

Example entry
## My Preferences
- Response language: English
- Always explain what you're about to do before writing code
- Prefer functional patterns over class-based ones
- Use const/let, never var
- When naming variables, prefer full words over abbreviations
Create it once, forget about it. Your personal preferences are loaded in every project you open — you never have to add them to individual project CLAUDE.md files again.

How to create it

Terminal
# Create the ~/.claude directory if it doesn't exist
$mkdir -p ~/.claude
# Create or open the global CLAUDE.md
$code ~/.claude/CLAUDE.md
Opened ~/.claude/CLAUDE.md in VS Code

Level 2 — 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, dev commands.

📁
Level 2

Project memory

CLAUDE.md (project root)

Scope: This project only — shared with the whole team via git

Loaded after user memory. Overrides or supplements global preferences. Commit this file so every team member and CI pipeline gets the same context automatically.

Example entry
## Stack
Next.js 15, TypeScript, Tailwind CSS, Prisma

## Conventions
- Use 'use client' only when needed
- All DB queries go in src/lib/db/

## Commands
- Dev: npm run dev
- Test: npm run test
Project memory is team memory. Commit CLAUDE.md to git and every developer on the team benefits from it automatically.

Level 3 — Imported Memory Files

You can pull any file into context on demand using the @ prefix directly in your prompt. The file contents are inserted as additional context for that session — no permanent change to CLAUDE.md needed.

Using @ to import a file into context

> @docs/api-spec.md Implement the /users endpoint exactly as described in that spec
↳ Loads the API spec into context for this task
> @prisma/schema.prisma Add a Post model with title, body, and authorId fields
↳ Gives Claude the current schema before it adds to it
> @memory/stripe-setup.md Set up a checkout session using the same pattern as before
↳ Loads a personal notes file with your preferred Stripe pattern
Tip — keep a personal memory folder. Create a memory/ folder in your home directory with Markdown files for recurring patterns you use across projects. 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.

1
User memory loaded~/.claude/CLAUDE.md

Your personal preferences — style, language, habits

↓
2
Project memory loadedCLAUDE.md

Stack, folder structure, conventions, commands for this repo

↓
3
Imported files loaded (if any @)@docs/api-spec.md

Task-specific context you explicitly requested

↓
4
Your message

Claude responds with full awareness of all layers above

If user memory and project memory have conflicting instructions, the project memory wins for that project — it is more specific. Imported files are the most specific and take highest precedence.

Choosing the Right Level

A quick reference for deciding which memory level to use for a given piece of context.

Context typeWhere to put itWhy
Preferred response style, language~/.claude/CLAUDE.mdPersonal preference — applies everywhere
No-console-log rule for all my code~/.claude/CLAUDE.mdUniversal habit, not project-specific
This project uses Next.js + PrismaCLAUDE.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 promptOne-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/CLAUDE.md
Markdown
## My Preferences
- Always explain briefly before writing code
- Prefer const/let over var
- Use full variable names, not abbreviations
- Default language: English

CLAUDE.md — project memory

📄CLAUDE.md
Markdown
## Stack
Next.js 15 App Router, TypeScript, Tailwind, Prisma
## Folder Structure
- Components: src/components/
- API routes: src/app/api/
## Commands
- Dev: npm run dev Test: npm run test

Prompt with @ import — task-specific memory

Claude Code prompt
> @docs/payments-spec.md Implement the POST /api/checkout endpoint described in that spec. Use the existing Stripe client in src/lib/stripe.ts.

What Claude sees before your message

From user memory:Explain before writing. Use const/let. Full variable names.
From project memory:Next.js 15, src/app/api/ for routes, npm run test to run tests.
From import:Full contents of docs/payments-spec.md — POST /api/checkout endpoint spec.

Memory Levels — Quick Reference

1User memory
~/.claude/CLAUDE.md
  • ✦ Loaded for every project
  • ✦ Personal style & habits
  • ✦ Never committed to git
2Project memory
CLAUDE.md
  • ✦ This project only
  • ✦ Stack, conventions, commands
  • ✦ Commit to git — team shared
3Imported files
@ in prompt
  • ✦ On demand only
  • ✦ Specs, schemas, notes
  • ✦ Most specific — highest precedence

What's Next

Memory management keeps Claude context-aware across long sessions. Next: Sub-Agents — how Claude delegates tasks to specialised agents.