Claude Code Memory — How CLAUDE.md, /memory & Projects Work

Overview

The 4 Memory Layers in Claude Code

Claude Code doesn’t have a single memory system — it has four, each serving a different purpose. Understanding which to use (and when) is the difference between re-explaining your project every session and having Claude pick up exactly where you left off.

CLAUDE.md

Project-Level Instructions

A markdown file in your project root, checked into git. Claude reads it at the start of every session. Shared with your entire team.

Best for: coding standards, architecture decisions, project rules, build commands.

~/.claude/CLAUDE.md

User-Level Instructions

A markdown file in your home directory. Personal preferences that apply to ALL projects on your machine. Not tied to any repo.

Best for: coding style, preferred tools, response format, personal workflows.

/memory

Persistent Memory Files

Saves facts to ~/.claude/memory/ as markdown files with frontmatter. Claude reads the MEMORY.md index each session and loads individual files on demand.

Best for: learned context, user preferences, project decisions, recurring patterns.

Project Instructions

.claude/settings.json

Set in .claude/settings.json under the project key. Applied to everyone working in the repo. Checked into git.

Best for: repo-specific rules, CI/CD patterns, testing requirements, allowed tools.

Architecture

How the Memory Hierarchy Works

Claude Code loads context in a specific order every time you start a session. Understanding this order tells you where to put each piece of configuration — and what happens when two layers disagree.

1

User CLAUDE.md ~/.claude/CLAUDE.md

Loaded first. Applies to every project on your machine. Your personal defaults.
2

Project CLAUDE.md ./CLAUDE.md

Loaded per-project. Rules specific to this codebase. Overrides user-level where they conflict.
3

Project settings .claude/settings.json

Tool permissions, allowed directories, project-specific configuration. Defines what Claude can do, not just what it should do.
4

Memory files ~/.claude/memory/

MEMORY.md index always loaded. Individual memory files loaded on demand when relevant. Persistent facts Claude has saved across sessions.
5

Conversation context

The current session’s messages, tool results, and active files. Highest priority but ephemeral — gone when the session ends.

Key insight

Later layers override earlier ones. A project CLAUDE.md rule beats a user CLAUDE.md rule. Conversation context beats everything. This means you can set broad defaults in your user CLAUDE.md and override them per-project.

Watch for

Memory files are loaded on demand, not all at once. If you have 50 memory files but only 3 are relevant to the current conversation, Claude will only load those 3. This keeps context lean but means you need good titles and index entries.

Deep Dive

CLAUDE.md — Your Project’s Brain

The CLAUDE.md file is the single most impactful thing you can do to improve Claude Code’s performance on your project. It’s a plain markdown file in your project root that Claude reads at the start of every session. Think of it as the onboarding doc you’d give a new senior engineer joining your team.

What to Include

A good CLAUDE.md covers four areas: how to build and test, how to write code, where things live, and what not to do.

CLAUDE.md — Example project instructions

# My Project ## Build & Test - Run tests: `npm test` - Build: `npm run build` - Lint: `npm run lint` - Single test: `npm test -- --grep "test name"` ## Code Style - Use TypeScript strict mode - Prefer named exports over default exports - Write tests for all new functions - Use async/await, never raw Promises - Error messages must include context (what failed + why) ## Architecture - API routes in /src/api/ - React components in /src/components/ - Database models in /src/models/ - Shared utilities in /src/lib/ - All database access goes through the repository pattern ## Do NOT - Do not use any ORM besides Prisma - Do not add new dependencies without discussing first - Do not modify the auth middleware directly

Tips for Effective CLAUDE.md Files

Keep it under 500 lines. Claude reads this every session — bloat wastes context tokens on instructions instead of your actual work.
Use markdown headers for clear organization. Claude parses the structure to find relevant sections.
Be specific and actionable. “Use good variable names” is useless. “Use descriptive camelCase: getUserById not getUser” is useful.
Include actual commands, not descriptions of commands. npm test -- --coverage beats “run the tests with coverage enabled.”
Update it as your project evolves. A stale CLAUDE.md is worse than none — it teaches Claude wrong patterns.
Check it into git. Your CLAUDE.md should be reviewed in PRs like any other code. The whole team benefits.

User-Level CLAUDE.md

Your ~/.claude/CLAUDE.md applies to every project. Use it for preferences that follow you, not any specific codebase.

~/.claude/CLAUDE.md — Personal preferences

# My Preferences - Be concise. No trailing summaries or recaps. - When fixing a bug, explain the root cause in one sentence. - Default to Python 3.12+ unless the project specifies otherwise. - I prefer functional patterns over class-based OOP. - Always suggest the simplest solution first. - When writing commits, use conventional commit format.

Pro tip

You can also place a CLAUDE.md in subdirectories. Claude Code reads CLAUDE.md files from the root down to the current working directory. A packages/api/CLAUDE.md would apply only when you’re working in that subdirectory, letting you set package-specific rules in a monorepo.

Deep Dive

/memory — Persistent Facts Across Sessions

The /memory command lets you save and recall persistent facts that survive across sessions. Unlike CLAUDE.md (which you edit manually), memory files are created through conversation.

How It Works

Type /memory in Claude Code to save or recall persistent facts.
Creates markdown files in ~/.claude/memory/ with structured frontmatter.
MEMORY.md is the index file — always loaded at session start.
Individual memory files are loaded on demand when relevant to the conversation.
You can also create memory by telling Claude: “Remember that our API uses v3 endpoints” or “Remember my deploy process involves SSHing to prod first.”

Memory File Structure

~/.claude/memory/MEMORY.md — Index file

# Memory Index - [User Profile](user_profile.md) — Senior backend engineer, Python/Go - [Deploy Process](deploy_process.md) — SSH tunnel, staging first, then prod - [API Conventions](api_conventions.md) — v3 REST, snake_case, pagination - [Project Decisions](project_decisions.md) — Chose Postgres over Mongo, reasons why

~/.claude/memory/deploy_process.md — Individual memory file

--- title: Deploy Process tags: [deploy, infrastructure] --- # Deploy Process - Always deploy to staging first: `./deploy.sh staging` - Run smoke tests: `./test-smoke.sh staging` - If green, deploy to prod: `./deploy.sh prod` - Requires VPN connection to internal network - Deploy window: weekdays 10am-3pm ET only

When to Use /memory vs CLAUDE.md

These two systems serve different purposes. Here’s when to use each:

Feature	CLAUDE.md	/memory
Shared with team	Yes (checked into git)	No (local to your machine)
Automatic loading	Full file, every session	Index only; files on demand
Best for	Project rules, build commands, architecture	Personal preferences, learned facts, decisions
How to edit	Direct file edit in your editor	/memory command or direct file edit
Portability	Moves with the repo (git clone)	Stays on your machine
Scope	One project (or user-wide at ~/.claude/)	Cross-project, tied to your account
Context cost	Full file consumed every session	Only relevant files loaded

Rule of thumb

If the whole team needs it, put it in CLAUDE.md. If only you need it, use /memory. If it’s a one-off fact Claude learned mid-conversation (“the staging database is on port 5433”), /memory is perfect.

Configuration

Project Settings — .claude/settings.json

While CLAUDE.md tells Claude what to do, .claude/settings.json controls what Claude can do. It configures tool permissions, allowed directories, hooks, and project-level settings.

.claude/settings.json — Project configuration

{ "permissions": { "allow": [ "Bash(npm test*)", "Bash(npm run build)", "Bash(npx eslint*)", "Read", "Write", "Edit" ], "deny": [ "Bash(rm -rf*)", "Bash(git push --force*)" ] }, "hooks": { "Stop": [ { "command": "echo 'Session ended' >> ~/claude-log.txt" } ] } }

Key things you can configure in project settings:

Tool permissions: Whitelist or deny specific bash commands, tool access, and file operations.
Hooks: Run shell commands automatically on lifecycle events (session start/stop, before/after tool calls).
Project instructions: Additional text instructions loaded alongside CLAUDE.md.
MCP servers: Configure Model Context Protocol servers for custom tool integrations.

Settings layering

Like CLAUDE.md, settings have a user level (~/.claude/settings.json) and a project level (.claude/settings.json). There’s also a local-only variant at .claude/settings.local.json for settings you don’t want checked into git (personal API keys, local paths, etc.).

Avoid These

Common Memory Mistakes

Most developers make the same three mistakes when setting up Claude Code’s memory. Each one wastes context, causes inconsistent behavior, or loses knowledge between sessions.

Mistake #1

Stuffing everything into CLAUDE.md

If your CLAUDE.md is 2,000 lines, Claude spends tokens reading rules instead of doing work. Keep it focused on what matters for every session. Move rarely-needed details to /memory files that load on demand.

Mistake #2

Forgetting user-level CLAUDE.md

Personal preferences (response style, preferred language, common tools) belong in ~/.claude/CLAUDE.md, not repeated in every project. Write it once, apply everywhere. Your projects’ CLAUDE.md files stay focused on project-specific rules.

Mistake #3

Not saving learned context

When Claude learns something mid-conversation — a deploy quirk, an API gotcha, a team convention — tell it to /memory save it. Otherwise that knowledge dies when the session ends. Build the habit: learn it, save it.

More Pitfalls to Watch For

Conflicting rules across layers. If your user CLAUDE.md says “use tabs” and your project CLAUDE.md says “use spaces,” the project rule wins — but Claude may still mention the conflict. Keep layers consistent or be explicit about overrides.
Stale CLAUDE.md files. Your project evolves but your CLAUDE.md doesn’t. Claude follows outdated instructions, generates wrong patterns, and you spend time correcting it. Review your CLAUDE.md quarterly, at minimum.
Vague instructions. “Write clean code” means nothing. “Functions under 30 lines, no nested callbacks deeper than 2 levels, all errors must include a stack trace” means everything. Claude follows precise instructions far better than vague ones.
Duplicating info between CLAUDE.md and /memory. Pick one source of truth. Project rules go in CLAUDE.md. Personal/cross-project facts go in /memory. Duplication leads to drift.

The Shortcut

Building good memory files is hard.
Brainfile does it for you.

You need domain expertise, structured thinking, and the right format. What works for a backend engineer is wrong for a data scientist. What works for React is wrong for Rust.

Brainfile generates production-ready CLAUDE.md files, memory configurations, and project instructions — tailored to your profession. What takes days of trial-and-error, Brainfile does in minutes.

Get Your Brainfile →

150+ role-specific templates · CLAUDE.md + .cursorrules + memory files · Updated monthly

Claude Code Memory —
The Complete Guide Nobody Wrote

The 4 Memory Layers in Claude Code

Project-Level Instructions

User-Level Instructions

Persistent Memory Files

.claude/settings.json

How the Memory Hierarchy Works

User CLAUDE.md `~/.claude/CLAUDE.md`

Project CLAUDE.md `./CLAUDE.md`

Project settings `.claude/settings.json`

Memory files `~/.claude/memory/`

Conversation context

CLAUDE.md — Your Project’s Brain

What to Include

Tips for Effective CLAUDE.md Files

User-Level CLAUDE.md

/memory — Persistent Facts Across Sessions

How It Works

Memory File Structure

When to Use /memory vs CLAUDE.md

Project Settings — .claude/settings.json

Common Memory Mistakes

Stuffing everything into CLAUDE.md

Forgetting user-level CLAUDE.md

Not saving learned context

More Pitfalls to Watch For

Building good memory files is hard.
Brainfile does it for you.

Claude forgets everything between sessions.
Unless you tell it what to remember.

Free: Claude Memory Tips & Templates

Claude Code Memory —The Complete Guide Nobody Wrote

The 4 Memory Layers in Claude Code

Project-Level Instructions

User-Level Instructions

Persistent Memory Files

.claude/settings.json

How the Memory Hierarchy Works

User CLAUDE.md ~/.claude/CLAUDE.md

Project CLAUDE.md ./CLAUDE.md

Project settings .claude/settings.json

Memory files ~/.claude/memory/

Conversation context

CLAUDE.md — Your Project’s Brain

What to Include

Tips for Effective CLAUDE.md Files

User-Level CLAUDE.md

/memory — Persistent Facts Across Sessions

How It Works

Memory File Structure

When to Use /memory vs CLAUDE.md

Project Settings — .claude/settings.json

Common Memory Mistakes

Stuffing everything into CLAUDE.md

Forgetting user-level CLAUDE.md

Not saving learned context

More Pitfalls to Watch For

Building good memory files is hard.Brainfile does it for you.

Claude forgets everything between sessions.Unless you tell it what to remember.

Free: Claude Memory Tips & Templates

Claude Code Memory —
The Complete Guide Nobody Wrote

User CLAUDE.md `~/.claude/CLAUDE.md`

Project CLAUDE.md `./CLAUDE.md`

Project settings `.claude/settings.json`

Memory files `~/.claude/memory/`

Building good memory files is hard.
Brainfile does it for you.

Claude forgets everything between sessions.
Unless you tell it what to remember.