Claude Code Memory: The Complete Guide

How Claude Code Memory Works

Claude Code has a layered memory system that works across three timescales:

Together, these three layers let Claude Code feel like a team member who remembers your project — your coding conventions, your build system, your architectural decisions — without you having to re-explain everything each session.

CLAUDE.md: Project Instructions

The CLAUDE.md file is the most important memory mechanism in Claude Code. It's a Markdown file that you write and maintain, loaded automatically at session start.

File Locations & Scope

All matching CLAUDE.md files are loaded and concatenated. If you're working in src/components/, Claude sees: global + project root + src/ CLAUDE.md files.

What to Put in CLAUDE.md

# My Project

## Build & Test Commands
- `npm run dev` - start dev server (port 3000)
- `npm test` - run Jest test suite
- `npm run lint` - ESLint + Prettier check
- `npm run build` - production build

## Architecture
- Next.js 15 app router in src/app/
- PostgreSQL database, Drizzle ORM
- Tailwind CSS + shadcn/ui components
- API routes in src/app/api/

## Conventions
- TypeScript strict mode, no `any`
- Functional React components with hooks
- Use server components by default
- Conventional commits (feat:, fix:, refactor:)
- Tests required for new features

## Important Notes
- Never commit .env files
- Use `bun` instead of `npm` for package management
- Always run tests before suggesting a commit

Creating CLAUDE.md Automatically

Use the /init slash command to have Claude analyze your project and generate a CLAUDE.md:

$ claude
> /init

Claude will scan your project structure, package files, config files, and README to generate an initial CLAUDE.md. Review and edit it — Claude's first draft is a starting point, not the final version.

CLAUDE.local.md: Personal Preferences

For preferences that shouldn't be shared with your team (they're gitignored), use .claude/CLAUDE.local.md:

# Personal Preferences

- I prefer verbose explanations when debugging
- Always use dark mode examples in code
- Don't auto-commit; let me review first
- Use bun instead of npm

Auto Memory: Persistent Learning

Auto memory is Claude Code's ability to learn and remember across sessions without you writing anything. When enabled, Claude saves important patterns, preferences, and project insights to a persistent directory.

How It Works

1. As you work, Claude identifies stable patterns: coding conventions, file organization, preferred tools, debugging approaches
2. Claude writes these observations to ~/.claude/projects/<project>/memory/MEMORY.md
3. For detailed topics, Claude creates separate files (e.g., debugging.md, patterns.md)
4. At the start of each session, MEMORY.md is loaded into context (first 200 lines)

Memory Directory Structure

What Gets Saved Automatically

• Stable patterns confirmed across multiple interactions
• Key architectural decisions and important file paths
• User preferences for workflow, tools, and communication style
• Solutions to recurring problems and debugging insights

What Doesn't Get Saved

• Session-specific context (current task details, temporary state)
• Unverified conclusions from reading a single file
• Information that duplicates CLAUDE.md instructions
• Speculative or incomplete observations

Manual Memory Control

You can explicitly ask Claude to remember things:

> Remember: always use bun instead of npm in this project
Claude saves this to MEMORY.md

> Forget the preference about using tabs
Claude removes the relevant entry from memory

Context Window Management

Claude Code uses Claude's full 200K token context window. But effective management matters more than raw size. Here's how context flows:

Tool outputs are the biggest context consumers. Every file read, every bash command output, every search result gets added to the conversation. A single large file read can consume 10-20K tokens.

Automatic Compaction

When the conversation approaches the context limit, Claude Code automatically compresses earlier messages into a summary. This happens transparently — you'll see a note that context was compressed, but your conversation continues seamlessly.

Using /compact Effectively

The /compact command manually triggers context compression. Use it proactively — don't wait for automatic compaction.

When to Use /compact

• After a research phase — Once Claude has explored your codebase and you're ready to start implementing, compact to free space for the actual work
• After a long debugging session — Debugging produces lots of verbose output. Compact once you've found the issue and are ready to fix it
• Before a complex task — If you're about to ask Claude to implement a large feature, compact first to maximize available context
• When Claude starts "forgetting" — If Claude references things incorrectly or loses track of the task, it may be running low on effective context

Custom Compact Prompts

You can provide a focus hint to guide what gets preserved:

> /compact Focus on the auth migration plan and database schema changes

This tells Claude to prioritize preserving information about auth and database schema while compressing everything else more aggressively.

The Memory Hierarchy

Understanding the full hierarchy helps you use the right mechanism for each type of information:

Higher-priority sources override lower ones. If your CLAUDE.md says "use tabs" but a compacted summary says "use spaces", the CLAUDE.md instruction wins.

Best Practices

CLAUDE.md Best Practices

1. Start with /init, then refine — Let Claude generate the first draft, then edit it based on what you know matters
2. Include build commands first — The most useful thing in CLAUDE.md is how to build, test, and lint your project
3. Document non-obvious conventions — Don't describe what Claude can see in the code. Document the "why" and hidden rules
4. Keep it under 200 lines — Every line costs tokens. Be ruthlessly concise
5. Update it regularly — CLAUDE.md should evolve with your project. Remove outdated info
6. Use CLAUDE.local.md for personal prefs — Don't pollute the shared CLAUDE.md with individual preferences

Context Window Best Practices

1. Use /compact proactively — Don't wait until Claude starts struggling
2. Use claude -c to continue sessions — Preserves context instead of starting fresh
3. Reference files by path instead of pasting content — Claude reads files efficiently with its Read tool
4. Use subagents for research — Subagents protect the parent context from verbose search results
5. Break large tasks into focused sessions — Don't try to do everything in one conversation

Auto Memory Best Practices

1. Let it learn organically — Don't try to front-load memory. Let Claude discover patterns naturally
2. Correct mistakes explicitly — If Claude remembers something wrong, say "forget that" or "actually, we use X"
3. Review MEMORY.md periodically — Check what Claude has learned and remove outdated entries
4. Keep MEMORY.md under 200 lines — Only the first 200 lines are auto-loaded

Troubleshooting

Claude isn't following my CLAUDE.md instructions

• Verify the file is in the right location (project root or ~/.claude/)
• Check for typos in the filename — it must be exactly CLAUDE.md (case-sensitive)
• Use /status to verify Claude has loaded the file
• Keep instructions clear and imperative — "Use TypeScript strict mode" not "We generally prefer TypeScript"

Claude keeps forgetting things mid-session

• Your conversation is likely hitting context limits. Use /compact
• Move critical information to CLAUDE.md so it persists across compaction
• Use subagents to offload verbose research tasks
• Check /cost to see token usage

Auto memory seems wrong or outdated

• Open ~/.claude/projects/<project>/memory/MEMORY.md and edit directly
• Or tell Claude: "Forget that we use library X, we switched to Y"
• Delete topic files that are no longer relevant

Frequently Asked Questions

Does CLAUDE.md work in all IDEs?

CLAUDE.md is loaded by Claude Code (the CLI). IDE integrations like the VS Code extension also support it. Other tools (Cursor, Windsurf) have their own configuration file formats but don't read CLAUDE.md.

Can I have multiple CLAUDE.md files?

Yes. Claude loads CLAUDE.md from the global directory, project root, and any parent directories of the file you're working in. They're concatenated, with more specific files taking priority.

Does auto memory sync across machines?

No. Auto memory is stored locally in ~/.claude/projects/. If you work on the same project from multiple machines, each will have its own memory. Consider using CLAUDE.md (committed to git) for shared context.

How do I see what's in my context window?

Use /cost to see token usage for the current session. There's no direct way to view the full context, but you can estimate: each file read adds roughly 1 token per 4 characters.

Can I disable auto memory?

Auto memory can be disabled in your settings. However, it's recommended to keep it enabled — it makes Claude significantly more effective over time as it learns your project's patterns.