Claude Code Memory

Problem: Every new session starts blank. You type the same context again. Framework, conventions, current focus, file layout. The agent has no memory of yesterday.

Quick Win: Spin up the memory file in 30 seconds:

cd your-project
claude
/init

Claude reads your repo and drops a starter CLAUDE.md next to it. That file becomes permanent project context, loaded at the top of every future session.

What CLAUDE.md Actually Is

The memory file is CLAUDE.md. It sits on disk, so it survives everything. Chat history dies when the session ends. This file does not. Claude reads it on startup and treats it as authoritative.

Here is the important part. Text inside CLAUDE.md gets a high priority slot in the context window. Claude follows it more tightly than chat messages and more tightly than files it pulls in mid-session. Treat it like config, not like docs.

That priority gap shapes how you structure everything else. The priority hierarchy spells it out in full.

Structure the File for Retention

Split the file into two halves. Stuff that never changes on top. Stuff that moves on the bottom.

# Project Context
 
- Framework: Next.js 14 with App Router
- Database: Supabase with Row Level Security
- Testing: Vitest for unit tests
 
## Key Directories
 
- `src/app/` - Route handlers and pages
- `src/lib/` - Shared utilities
- `src/components/` - React components
 
## Standards
 
- TypeScript strict mode required
- All API routes need error handling
- Run `npm test` before committing
 
## Current Focus
 
- Building user authentication flow
- Priority: Login and password reset

The Current Focus block is your scratchpad. Overwrite it every few days. Leave the rest alone.

Hierarchical Memory Up the Tree

CLAUDE.md files nest. Claude walks up the directory tree and loads each one it finds:

~/projects/CLAUDE.md          <- Universal defaults
~/projects/my-app/CLAUDE.md   <- Project-specific
~/projects/my-app/api/CLAUDE.md <- Component-specific

Monorepo? Different subfolders with different stacks? This is where it earns its keep. Keep the top-level files short. Every layer gets loaded on every launch.

@import: Composable Memory

One file can pull in others. The syntax is @path/to/import. Your memory setup stops being a single file and starts looking like a small graph.

See @README for project overview and @package.json for available npm commands.
 
# Additional Instructions
 
- git workflow @docs/git-instructions.md

Relative and absolute paths both work. Relative paths resolve against the file doing the importing, not your working directory. You can point at anything on your machine:

# Pull in shared team standards
 
- @docs/coding-standards.md
- @docs/api-conventions.md
 
# Reference external files with absolute paths
 
- @~/.claude/my-preferences.md

First-time approval. The first time a project imports a file outside itself, Claude Code pops an approval dialog listing the exact paths. Approve to load. Decline to skip. The choice is remembered per project. A decline is permanent until you unset it, and the dialog will not show up again.

Code block safety. Imports inside fenced code or inline code spans are ignored. Writing @path/to/file in an example is safe.

Recursive imports. Imported files can import their own files. Max depth is 5 hops. Use this to layer instruction sets without stuffing everything into one place.

Git worktree tip. CLAUDE.local.md only lives in one worktree at a time. If you bounce between worktrees, put personal instructions in your home directory and import them:

# Individual Preferences
 
- @~/.claude/my-project-instructions.md

CLAUDE.local.md: Private Memory

Some context belongs to you, not the team. Local sandbox URLs. Test fixtures. A branch naming habit. Put those in CLAUDE.local.md. Claude Code adds this file to .gitignore automatically, so it never leaks into the repo.

# CLAUDE.local.md
 
## My Local Setup
 
- Dev server: http://localhost:3001
- Test database: local-dev-db
- Preferred branch naming: feature/[initials]-[description]

It loads next to CLAUDE.md at the same high priority. Your personal notes stay personal. The shared file stays clean.

/memory: Inspect and Edit Live

Run /memory inside a session to see every memory file currently loaded and open any of them in your editor. It covers three jobs:

• Checking which CLAUDE.md files, rules, and imports are active
• Editing memory without leaving the session
• Debugging when an instruction seems to be getting ignored

Modular Rules: Path-Scoped Memory

Want tighter control? The .claude/rules/ directory lets you break instructions into many small files, each scoped to a path pattern:

.claude/rules/
├── api-guidelines.md     # paths: src/api/**/*
├── react-patterns.md     # paths: src/components/**/*
└── testing-rules.md      # paths: **/*.test.*

Critical: Rules files sit at the same high priority as CLAUDE.md. What changes is scope. Path targeting decides when that priority kicks in.

This fixes the "monolithic CLAUDE.md" problem. Cram everything into one file and every instruction fights for attention, including the ones that have nothing to do with what you are working on right now. With rules, your API guidance only competes when Claude is actually editing API code.

User-level rules. Personal rules that cover every project live at ~/.claude/rules/. They load before project rules, so project rules win a tie.

Brace expansion. Path patterns accept brace expansion for multiple extensions or folders: src/**/*.{ts,tsx} or {src,lib}/**/*.ts.

Symlinks. The .claude/rules/ folder follows symlinks, which lets you reuse rule sets across projects. Circular symlinks get caught and skipped.

The Rules Directory guide has the full path-pattern syntax, the priority order, and migration notes.

The Five Memory Locations

Claude Code has five distinct memory slots. Each one serves a job:

Managed policy paths change by OS:

• macOS: /Library/Application Support/ClaudeCode/CLAUDE.md
• Linux: /etc/claude-code/CLAUDE.md
• Windows: C:\Program Files\ClaudeCode\CLAUDE.md

Higher slots load first and set the floor. More specific files layer on top.

Subtree Discovery: Lazy Loading

Claude walks up the tree at launch. It also notices CLAUDE.md files sitting in folders below the one you started in.

The key difference. Those subtree files do not get loaded on launch. They load the moment Claude reads a file inside that subfolder. Startup stays cheap, and localized rules still show up when they matter.

So if packages/auth/CLAUDE.md holds auth-only instructions, they stay dormant until Claude opens a file under packages/auth/.

Git Your Memory File

Put CLAUDE.md under version control and it turns into a checkpointable memory:

# Before experimenting with instructions
git add CLAUDE.md && git commit -m "working context state"
 
# Try new instructions, then restore if needed
git checkout CLAUDE.md

Instant rollback when an edit backfires.

Auto Memory: Claude's Own Notes

You write CLAUDE.md. Claude writes its own notebook too. That file lives at ~/.claude/projects/<project>/memory/ and fills up with debugging observations, build patterns, and architecture notes. The first 200 lines of the main MEMORY.md file get loaded on startup next to your CLAUDE.md files. The full auto memory guide covers the storage layout and configuration.

Session Memory: Rolling Summary

Claude Code now keeps a rolling summary of the current session that updates on every message. The summary file lives at ~/.claude/projects/[project]/[session]/session_memory and tracks:

• Session title. Auto-generated description of your work
• Current status. Completed items, discussion points, open questions
• Key results. Important outcomes and learnings
• Work log. Chronological record of actions taken

This feed powers instant compaction. Fire /compact and Claude drops the summary into a fresh context right away. No two-minute stall.

Ask Claude "where is your session memory stored?" and it will print the exact path for the current session.

Fresh Context on Demand

Long sessions fill up with noise. Reset with /clear:

/clear

That wipes the conversation buffer and keeps CLAUDE.md in place. The noise goes. Your memory stays.

For a full reset, quit and relaunch:

exit
claude

Isolated Contexts per Task

Want totally separate memory for a branch? Fork a folder:

mkdir feature-auth && cd feature-auth
cp ../CLAUDE.md CLAUDE.md
echo "## Focus: Authentication only" >> CLAUDE.md
claude

Each folder carries its own CLAUDE.md. Contexts stay walled off. Great for feature branches and scratch work.

When Things Go Wrong

Context feels stale. Conversation history has piled up junk.

• Fix: Run /clear. Chat goes, CLAUDE.md stays.

Projects bleed into each other. Instructions from one repo are showing up in another.

• Fix: Every project needs its own CLAUDE.md sitting at the project root.

Instructions getting ignored. The file has grown too long or lost shape.

• Fix: Keep CLAUDE.md under 400 lines. Push domain-specific details into path-scoped rules, so they only get high priority when the path matches.

Next Steps

• Treat CLAUDE.md as an operating system for heavier orchestration patterns
• Read the auto memory guide for Claude's own project notes
• Study context management to keep tokens lean
• Check out planning modes for structured work
• Wire up git integration for memory checkpoints
• See how memory fits into context engineering for production agent systems

Remember: CLAUDE.md is not project documentation. It is your agent's operating system. Structure it well, and every session picks up exactly where the last one stopped.