Memory & Persistence
Claude Code retains knowledge between sessions through several mechanisms. Understanding how memory works lets you build persistent project context that makes every conversation more effective than the last.
How Claude Remembers
Claude uses a layered memory system. Each layer serves a different scope and lifetime:
| Layer | Scope | Lifetime | Source |
|---|---|---|---|
CLAUDE.md | Project-level | Permanent (until edited) | File in project root |
~/.claude/CLAUDE.md | Global | Permanent (until edited) | File in home directory |
| Conversation history | Session | Current session | Automatic |
/remember entries | Project-level | Permanent | User command |
CLAUDE.md — Project Memory
The CLAUDE.md file in your project root is the primary way to persist instructions,
context, and conventions. Claude reads this file at the start of every conversation.
# My Project
## Architecture
- Next.js App Router with server components
- Convex for backend and real-time data
## Conventions
- Use named exports for components
- Prefix server actions with "action"
- Write tests for all utility functions
Global Memory
The file at ~/.claude/CLAUDE.md applies across all projects. Use it for personal
preferences and universal conventions.
# Global Preferences
- Always use TypeScript strict mode
- Prefer functional patterns over classes
- Use concise variable names in tests
The /remember Command
Use /remember to save important context without manually editing CLAUDE.md. Claude
appends the information to your project's memory file.
/remember Our API uses snake_case for all JSON field names
/remember The staging database is read-only on weekends
/remember Run "npm run typecheck" before committing
Project-Level vs Global Memory
| Feature | Project (CLAUDE.md) | Global (~/.claude/CLAUDE.md) |
|---|---|---|
| Location | Project root | Home directory |
| Applies to | One project | All projects |
| Best for | Architecture, conventions | Personal preferences |
| Shared with team | Yes (committed to repo) | No (personal file) |
Context Across Sessions
When you start a new Claude Code session in the same project, Claude automatically:
- Reads the project
CLAUDE.mdfile. - Reads the global
~/.claude/CLAUDE.mdfile. - Loads any
/rememberentries stored in the project.
This means you do not need to re-explain your project every time. The memory system handles continuity for you.
Best Practices
- Keep CLAUDE.md concise. Long files consume context window space. Focus on what Claude needs to know for every task.
- Update regularly. As your project evolves, prune outdated instructions.
- Use /remember for discoveries. When Claude learns something important during a session, save it immediately.
- Separate concerns. Put project standards in project memory, personal style in global.
- Commit project memory. Your team benefits when
CLAUDE.mdis version controlled. - Review periodically. Audit memory files quarterly to remove stale information.
A well-maintained memory system means Claude starts every session already understanding your project, your conventions, and your preferences.