Two Memory Systems
Claude Code has two distinct ways to persist information across sessions:
| System | Written by | Stored in | Best for |
|---|---|---|---|
| CLAUDE.md | You (human) | Project root / ~/.claude/ |
Team conventions, tech stack, always-on rules |
| Auto-memory | Claude (AI-managed) | ~/.claude/projects/<path>/memory/ |
Personal preferences, feedback, evolving context |
CLAUDE.md — Project Instructions
CLAUDE.md is a plain Markdown file that Claude reads automatically at the start of every session in a directory. It's the equivalent of a standing brief: things Claude should always know, without you repeating yourself.
Where to put CLAUDE.md
./CLAUDE.md— project-level, read for sessions in this directory~/.claude/CLAUDE.md— global, read for every Claude Code session anywhere- Parent directories — Claude reads CLAUDE.md files up the directory tree to the repo root
What to put in CLAUDE.md
Include things that would otherwise require you to repeat context every session:
# My Project
## Tech stack
- Node 20 + TypeScript (strict)
- Postgres 16 via Prisma ORM
- Vitest for tests — run `npm test`
## Conventions
- All new functions need a JSDoc comment
- Prefer async/await over .then() chains
- Never commit directly to main — always use a branch
## Deploy
- Staging: `npm run deploy:staging`
- Production requires manual approval in GitHub Actions
## Do NOT
- Modify migration files after they've been committed
- Add console.log to production code
- Use `any` type in TypeScript/init in Claude Code to auto-generate a CLAUDE.md from your existing codebase. Claude reads your files and writes a structured brief covering tech stack, conventions, and project structure.
Auto-Memory — AI-Managed Persistent Context
Auto-memory is Claude's built-in system for saving facts it learns about you and your work. Unlike CLAUDE.md (which you write), auto-memory is written and maintained by Claude itself, across conversations.
Where auto-memory lives
~/.claude/projects/
-home-shash-myproject/
memory/
MEMORY.md ← index (always loaded)
user_role.md ← who you are
feedback_testing.md ← how you want Claude to work
project_launch.md ← current project context
reference_linear.md ← pointers to external systemsMEMORY.md is a one-line-per-memory index that Claude loads at the start of every session. Individual memory files are loaded on demand when relevant.
The 4 Memory Types
User memory
Facts about who you are: your role, expertise level, tech preferences, and background. Claude uses this to calibrate explanations — it won't explain what a promise is to a senior JavaScript engineer.
Example:I'm a backend Python engineer, 8 years experience.
First time touching React — explain frontend patterns
by analogy to Python/Django equivalents.Feedback memory
Guidance you've given Claude about how to work: what to avoid, what approach worked well, workflow preferences. These prevent Claude from repeating the same mistakes across sessions.
Example:Do NOT mock the database in tests — we had a production
incident where mocked tests passed but a real migration failed.
Always use the test database for integration tests.Project memory
Ongoing context about the work: who's doing what, why decisions were made, current blockers, deadlines. Helps Claude understand the "why" behind requests without needing re-explanation.
Example:Auth middleware rewrite is driven by a legal/compliance
requirement (session token storage), not tech debt.
Scope decisions should favor compliance over ergonomics.
Deadline: 2026-06-01.Reference memory
Pointers to external systems: Linear projects, Grafana dashboards, Slack channels, Notion docs. Claude uses these to know where to look when you reference external state.
Example:Pipeline bugs tracked in Linear project "INGEST".
Oncall dashboard: grafana.internal/d/api-latency
(pages someone if latency p99 > 800ms).How to Use Memory
Tell Claude to remember something
User: "remember: always use tabs not spaces in this project"
Claude: [writes a feedback memory — applies to all future sessions]Tell Claude to forget something
User: "forget the thing about tabs — we switched to spaces"
Claude: [finds and removes the relevant memory file]Ask Claude what it remembers
User: "what do you remember about our testing approach?"
Claude: [reads relevant memory files, summarizes]Claude saves memories proactively
You don't have to ask. When Claude learns something worth keeping — your tech stack preference, a correction you gave it, a project deadline — it writes a memory automatically. You'll see [saves user memory: ...] or similar notes in responses.
CLAUDE.md vs Auto-Memory: When to Use Each
| Use CLAUDE.md when… | Use auto-memory when… |
|---|---|
| The rule applies to everyone on the team | It's personal to your workflow |
| It's stable — won't change often | It evolves as work progresses |
| You want it version-controlled in git | You don't want it in the repo |
| It's about the codebase itself | It's about how you prefer to work |
| New team members need to see it | It's between you and Claude |
What NOT to Put in Memory
Memory works best for things that can't be derived from the code. Avoid saving:
- Code patterns or architecture — Claude can read these from the files directly
- Git history —
git logis authoritative and always up-to-date - Debugging solutions — the fix is in the code; put context in commit messages
- In-progress task state — use TodoWrite/task tracking, not memory files
- Anything documented in CLAUDE.md already — don't duplicate
Best Practices for CLAUDE.md
Keep it concise
CLAUDE.md is always loaded into the context window. If it's 5,000 words, that's 5,000 tokens on every request. Keep it to essential, high-signal content — aim for under 500 words.
Structure with headers
Use Markdown headers so Claude can quickly scan relevant sections. Common structure:
# Project Name
## Tech stack
## Build & test commands
## Code conventions
## Architecture notes
## What NOT to doUse the /init skill
If you're starting fresh, type /init to have Claude auto-generate a CLAUDE.md from your existing codebase. It reads your package.json, test setup, existing code conventions, and produces a structured brief.
Update it when conventions change
Outdated instructions are worse than no instructions — Claude will follow them confidently. When your tech stack or conventions change, update CLAUDE.md. Consider adding it to your onboarding checklist.
Memory File Format
Auto-memory files follow this YAML frontmatter format:
---
name: feedback-testing-approach
description: Integration tests must use real DB, not mocks
metadata:
type: feedback
---
Do NOT mock the database in integration tests.
**Why:** Prior incident (Q3 2025) where mock/prod divergence
masked a broken migration that reached production.
**How to apply:** Any test touching data access must use
the test database. Use `vitest.integration.config.ts`.Related Guides
- Claude Code Hooks — auto-run shell commands on events
- Full Cheatsheet — all CLI flags, slash commands, keyboard shortcuts
- Setup Guide — install, configure, and get started
- All Claude Code Skills — back to the full directory