The most common frustration with Claude Code is re-explaining the same context at the start of every session. "We use Drizzle, not Prisma." "Don't use any in TypeScript." "The auth is in /src/lib/auth.ts."
Claude has three mechanisms for remembering across sessions. They solve different problems and are appropriate in different situations. Using the wrong one means either re-explaining constantly or contaminating context you didn't want shared.
The Three Mechanisms at a Glance
| CLAUDE.md | Projects | Memory | |
|---|---|---|---|
| Scope | Per project / directory | Per Claude.ai Project | Global across all conversations |
| Where it lives | Your filesystem | Claude's servers | Claude's servers |
| Shared with team | ✅ Yes (git) | ❌ No | ❌ No |
| Works in Claude Code CLI | ✅ Primary method | ✅ When in a Project | ⚠️ Limited |
| Works in Claude.ai web | ❌ No | ✅ Yes | ✅ Yes |
CLAUDE.md — The Primary Tool for Claude Code
CLAUDE.md is a Markdown file that Claude Code reads automatically at the start of every session. Write it once, and it persists forever, version-controlled, team-shared.
Hierarchical structure
~/.claude/CLAUDE.md # Global — applies to every project
~/projects/myapp/CLAUDE.md # Project-level — this project only
~/projects/myapp/src/CLAUDE.md # Subdirectory — extra context for src/
What to put in it
# MyApp — Claude Context
## Stack
- Next.js 15 App Router, TypeScript strict mode
- Drizzle ORM with Neon Postgres (NOT Prisma)
- Clerk for authentication (NOT NextAuth)
- Bun as package manager (NOT npm or yarn)
## Conventions
- API routes go in /src/app/api/
- Server actions go in /src/actions/ with 'use server'
- Database queries go in /src/lib/db/ — never inline in components
- Never use `any`. Use `unknown` with type guards instead.
## Key Files
- /src/lib/auth.ts — Clerk auth helpers and session logic
- /src/lib/db/schema.ts — Complete Drizzle schema
## What to Avoid
- Don't install new packages without asking first
- Don't modify schema.ts without mentioning the migration
This loads into every Claude Code session. Claude knows your stack, conventions, and constraints without you saying anything.
Global CLAUDE.md for personal preferences
# Global Preferences (~/.claude/CLAUDE.md)
- TypeScript strict mode always on
- Prefer explicit return types on public functions
- Use early returns over nested conditionals
- Show the plan before implementing large changes
- Ask before installing packages I didn't mention
The team advantage
CLAUDE.md committed to git gives every developer on the team the same starting context. New developer joins → they clone the repo → Claude Code already knows the conventions. Update a convention → update the file → everyone picks it up next session.
This is what neither Projects nor Memory can do. They're personal, not shared.
Claude Projects — Conversation History That Persists
Projects maintain persistent conversation history across sessions. You can also upload files — PDFs, specs, architecture docs — and Claude references them throughout the Project's lifetime.
What Projects persist
- Conversation history — previous exchanges available as context
- Uploaded files — documents and specs you've added
- Project instructions — a persistent system prompt you define
When Projects add value
Projects are useful when you need the history of decisions, not just the current state of the codebase:
- Long-running features where previous decisions inform new ones
- Debugging sessions where you need to remember what you've already tried
- Architecture work where the reasoning behind choices matters
The key distinction: CLAUDE.md tells Claude what your codebase is like right now. Projects tell Claude what you've discussed and decided over time.
Projects are personal — your team doesn't get your accumulated context.
Memory — Personal Facts Across All Conversations
Memory is the simplest: ask Claude to remember something, and it does — across all your conversations, regardless of project.
"Remember that I prefer tabs over spaces in all my projects."
"Remember that my main database is on Railway, not local."
What Memory is good for
Personal preferences that don't belong in a project's CLAUDE.md because they're about you, not the project:
- Communication style preferences
- Cross-project personal conventions
- Work context ("I'm currently focused on the payments feature")
What Memory is bad for
Technical project context. Memory is global and can create conflicts across projects. "Use Drizzle not Prisma" in Memory might bleed into unrelated projects. Use CLAUDE.md for project-specific technical context.
In Claude Code CLI, CLAUDE.md is the equivalent of Memory — more precise, version-controlled, and project-scoped.
The Right Tool for Each Situation
Use CLAUDE.md when:
- Context applies every time you open Claude Code in this project
- It's technical: stack, conventions, file structure, constraints
- You want your team to share the same context
Use Projects when:
- Extended work across many sessions where history matters
- You've uploaded reference documents Claude needs to consult
- You need a running record of decisions and reasoning
Use Memory when:
- It's a personal preference, not a project constraint
- Context applies across all your work
- You're in Claude.ai web interface
The Practical Setup for a New Project
touch CLAUDE.md
Fill it with:
- Stack — every library and framework, including what you're NOT using
- Conventions — naming, file organization, patterns
- Key files — where the important pieces live
- Constraints — things Claude should ask about before doing
Commit it on day one. From that point forward, every session starts with full context.
Why Most Developers Under-Use CLAUDE.md
The most common mistake: treating CLAUDE.md as documentation — writing it once and never updating it.
CLAUDE.md is a living document. Every time you make an architectural decision, add it. Every time Claude makes a wrong assumption about your stack, correct it in the file. Every time you establish a new convention, write it down.
The developers who get consistent output from Claude Code are the ones who maintain a detailed CLAUDE.md. Not because Claude is smarter with it — because it's not making assumptions about your project. It knows.
Full article at stacknotice.com/blog/claude-code-memory-vs-projects-vs-claude-md
Top comments (0)