Claude Code Memory Files: How Auto-Memory, CLAUDE.md, and Project Memory Work

TL;DR

CLAUDE.md in your repo root is for team-shared project knowledge: architecture, commands, conventions. Auto-memory at ~/.claude/projects/ is for personal, per-project notes Claude accumulates across sessions. ~/.claude/CLAUDE.md is for global preferences that apply to all projects.

The Three Memory Systems

All three are loaded into the system prompt at session start. They stack: global user memory applies everywhere, then project CLAUDE.md layers on project-specific context, then auto-memory adds your personal session history for that project.

CLAUDE.md (Project Memory)

The most important memory file. It lives at your project root and is committed to the repo. Every developer on the team, and every CI run, gets the same context.

# CLAUDE.md

## Commands
```bash
bun install          # Install dependencies
bun run dev          # Dev server on port 3000
bun run build        # Production build
bun run test         # Run tests
bun run lint         # ESLint
```

## Architecture
- Next.js 15 App Router, React 19, TypeScript
- Database: PostgreSQL with Drizzle ORM
- Auth: Clerk
- Payments: Stripe

## Conventions
- Server Components by default. Client components only for interactivity.
- All mutations via server actions in `actions.ts` files.
- Database operations through Drizzle ORM only.
- Run `bun run typecheck:fast` before committing.

This gives Claude everything it needs to work in your project: how to build, what the stack is, and what patterns to follow. 40 lines, loaded into every session.

For detailed examples of CLAUDE.md files for different project types, see the CLAUDE.md examples page.

Auto-Memory

Auto-memory is Claude's scratchpad. It lives at ~/.claude/projects/<project-path>/memory/ and persists across sessions. Claude writes to it during conversations when it learns something worth remembering.

## Lessons
- Always run `bun run typecheck:fast` after editing, not `tsc --noEmit` (project alias is faster).
- The request_type for WarpGrep in the DB is 'warpgrep', not 'warp_grep'.

## Agent Preferences
- Prefer agent teams over task agents for complex work.

## Project Quirks
- The Stripe webhook handler at /api/webhooks/stripe needs raw body parsing. Don't add JSON middleware.
- Drizzle migrations are in /drizzle, not /migrations.

Key behaviors:

• MEMORY.md is auto-loaded (first 200 lines) into every session. Keep it concise.
• Topic files (e.g., debugging.md, patterns.md) can be created for detailed notes. Claude reads them on demand, not automatically.
• Claude self-maintains it. When you correct Claude or confirm a pattern, it updates MEMORY.md. You can also say "remember this" or "forget that".
• Not shared with team. Auto-memory is in your home directory, not the project repo.

User Memory (~/.claude/CLAUDE.md)

Global preferences that apply to every project. Put things here that are always true about how you work:

# Global Preferences

## Tools
- Always use bun, never npm or yarn.
- Use edit_file over full file writes when possible.

## Style
- No emojis in code comments or commit messages.
- Commit messages in imperative mood: "Add feature" not "Added feature".

## Workflow
- Always commit and push when done with a task.
- Run builds/tests to verify work before reporting done.

This file is loaded into every session across all projects. Keep it short, 20-50 lines. Project-specific rules belong in the project CLAUDE.md, not here.

What to Put Where

Structuring CLAUDE.md

The best CLAUDE.md files share a pattern: they are short (under 200 lines), start with commands, describe the architecture in one paragraph, and list conventions as bullet points.

• Commands first. Claude uses these every session. Build, test, lint, dev server.
• Architecture second. Tech stack, key directories, data flow. One paragraph, not a whitepaper.
• Conventions third. Naming, file organization, patterns to follow. Bullet points.
• Gotchas last. Things that have tripped Claude up before. "Don't use X, use Y instead."

Avoid putting full API documentation or long code examples in CLAUDE.md. It consumes context tokens on every session. Link to docs instead: Claude can read them when needed.

Memory and Context Window

Memory files consume context tokens. A 150-line CLAUDE.md uses roughly 3,000-4,000 tokens. With auto-memory MEMORY.md (200 lines) and user memory (50 lines), you're spending 5,000-8,000 tokens before the first message.

On Claude Opus 4.6 with its 200K context window, this is 2.5-4% of the total. Acceptable. On Haiku with a shorter window, the percentage is higher. If you notice context rot (degraded output quality late in sessions), trim your memory files first.

Memory Files vs MCP Memory Servers

MCP memory servers (like memory-bank-mcp) provide structured, queryable memory with embedding-based retrieval. They are more powerful than flat files but add setup complexity.

Start with memory files. If you find yourself maintaining a MEMORY.md over 200 lines with increasingly niche details, consider an MCP memory server. For details on MCP setup, see the MCP servers guide.

FAQ