YouTip

> Every time a Claude Code session ends, the context is cleared. > > > Sometimes we have to tell Claude again and again "use pnpm instead of npm" or "our indentation is 2 spaces"? **Memory System** is exactly for this purpose. * * * ## What is Claude Code's Memory System? Claude Code does not have automatic cross-session memory—each new session starts with a fresh context window. The Memory System uses two complementary mechanisms to enable knowledge to **persist across sessions** and automatically load at the start of each conversation: | Mechanism | Who Writes | Suitable For | | --- | --- | --- | | **CLAUDE.md File** | You (developer) manually write | Project specifications, team conventions, build commands, etc. | | **Auto Memory** | Claude automatically writes | Accumulated experience from your corrections and preferences | Both mechanisms are loaded into the context at the start of each session. Claude treats them as **reference context**, not mandatory configuration—the more specific and concise the instructions, the more consistently Claude follows them. * * * ## Memory File Hierarchy Claude Code uses a **four-level memory hierarchy**, with priority from highest to lowest: 1. Enterprise policy ← Highest priority, read-only 2. User-level CLAUDE.md ← ~/.claude/CLAUDE.md, applies to all projects 3. Project-level CLAUDE.md ← Project root directory, shared with team via Git commits 4. Subdirectory-level CLAUDE.md ← src/, api/, tests/, etc., loaded by context **Most specific rules take precedence**: Subdirectory CLAUDE.md files override similar rules from upper levels. * * * ## CLAUDE.md File Detailed Explanation ### What is CLAUDE.md? `CLAUDE.md` is a Markdown file placed in the project root directory (or subdirectories). Claude Code **automatically injects it into the system prompt** each time a new session starts. It is the long-term memory you can configure. ### Creating CLAUDE.md **Method 1: Use `/init` command to auto-generate** # Execute /init in Claude Code session Claude will analyze your directory structure and automatically generate a CLAUDE.md skeleton tailored to your tech stack. For example, running `/init` in a Node.js project will automatically detect frameworks, testing tools, build commands, and generate an initial file with 80% completeness within 30 seconds. **Method 2: Manual creation** touch CLAUDE.md ### Recommended CLAUDE.md Structure # Project Conventions ## Tech Stack - Frontend: Next.js 15, TypeScript 5.7, Tailwind CSS 4 - Backend: Node.js 22, Prisma 6 - Testing: Vitest 3.2 ## Code Standards - Always use functional React components - Use kebab-case for file names - Test files in the same directory as source code ## Common Commands - Build: `pnpm build` - Test: `pnpm test` - Start dev server: `pnpm dev` ## API Conventions - All API routes start with `/api/v1/` - Error response format: `{ error: string, code: number }` ### Golden Rules for Writing Good CLAUDE.md **✅ Do this:** * Use imperative sentences and short lists, not narrative paragraphs * Include specific version numbers and commands * Add code examples (5 lines of examples beat 50 words of explanation) * Keep it under **200 lines** (excess content won't load at session start) **❌ Avoid this:** * Vague instructions like "follow best practices" or "write clean code" * Too many generic rules (only include conventions unique to this project) * Outdated information (recommended to review monthly) ### Subdirectory CLAUDE.md my-project/ ├── CLAUDE.md # Global project conventions ├── src/ │ └── CLAUDE.md # Loaded only when processing src/ files ├── api/ │ └── CLAUDE.md # API-specific conventions └── tests/ └── CLAUDE.md # Test-specific rules Claude Code only loads subdirectory CLAUDE.md files when processing files in the corresponding directory, saving tokens while providing more precise context. * * * ## Auto Memory Detailed Explanation ### How Does It Work? Auto Memory enables Claude to **self-accumulate knowledge** across sessions without you manually writing anything. Claude automatically saves notes during work, including: * Build commands and debugging techniques * Architecture decision notes * Code style preferences * Workflow habits Claude doesn't save content every time—it judges which information will be **useful in future sessions** before writing. ### Auto Memory File Structure ~/.claude/projects//memory/ ├── MEMORY.md # Concise index file, loaded at the start of each session (first 200 lines) ├── debugging.md # Detailed notes on debugging patterns ├── api-conventions.md # API design decisions └── ... # Other topic files created by Claude `MEMORY.md` is the index for the entire memory directory, which Claude uses to track content stored across files. ### Triggering Auto Memory When you tell Claude something, it automatically saves to memory: You: Always use pnpm, not npm You: Remember that API tests need a local Redis instance running You: Our date format should use ISO 8601 **Want to save to CLAUDE.md instead of Auto Memory?** Be explicit: You: Add this to CLAUDE.md ### Enabling / Disabling Auto Memory **Method 1: Toggle via `/memory` command** (see next section) **Method 2: Configure in project settings** // .claude/settings.json { "autoMemoryEnabled": false } **Method 3: Environment variable** export CLAUDE_CODE_DISABLE_AUTO_MEMORY=1

**Note:** Auto Memory is **local machine-level**—all worktrees and subdirectories of the same Git repository share one memory directory, but it **does not sync across machines or cloud environments**.

* * * ## `/memory` Command Usage Guide `/memory` is the core command for managing the memory system. ### `/memory` Command Features Entering `/memory` in a Claude Code session allows you to: * **View** all currently loaded CLAUDE.md and rule file lists for the session * **Toggle** Auto Memory on/off state * **Open** Auto Memory folder link * **Select any file** to open and edit in the editor ### `#` Shortcut—Quick Add Memory This is a hidden productivity gem: # Always use named parameters in function arguments Press the `#` key, enter what you want to remember, press enter—Claude Code will automatically write it to the appropriate CLAUDE.md file. Perfect for: * Recording project conventions * Saving common Bash commands * Noting code style details * * * ## Common Questions and Debugging ### Claude Ignored CLAUDE.md Instructions? 1. Run `/memory` to confirm the CLAUDE.md file is loaded 2. Ensure Claude Code is running in the directory where CLAUDE.md is located (or its subdirectories) 3. Check if instructions are specific enough—"follow best practices" is too vague, "use named imports (tree-shaking compatibility)" is more effective 4. Check if the file exceeds 200 lines (excess content doesn't load) ### CLAUDE.md Is Context, Not Enforcement Claude **reads** and tries to follow CLAUDE.md, but there is no strict compliance guarantee, especially when instructions are vague or conflicting. Think of it as "a work guide for Claude" rather than "rules that cannot be violated." * * * ## Practical Workflow Examples ### Scenario 1: Initialize a New Project # 1. Start Claude Code in the project root directory cd my-project claude # 2. Generate memory file skeleton /init # 3. Review and refine the generated CLAUDE.md /memory # Open file for editing # 4. Start working, Claude will automatically accumulate memory ### Scenario 2: Record Debugging Discoveries You: Remember, you must start Docker Compose before running integration tests Claude: Got it, I've recorded this in Auto Memory. In the next session, Claude will automatically know about this dependency. ### Scenario 3: Team Collaboration Commit the `CLAUDE.md` in the project root directory to the Git repository—every team member's Claude assistant will read the same specifications, achieving consistent AI-assisted experience. git add CLAUDE.md git commit -m "feat: add Claude Code memory configuration" * * * ## Best Practices Summary | Scenario | Recommended Approach | | --- | --- | | Team-shared conventions | CLAUDE.md in project root, commit to Git | | Personal preferences | `~/.claude/CLAUDE.md` (user-level) | | Module-specific rules | Subdirectory CLAUDE.md | | Let Claude self-learn | Enable Auto Memory, verbally state preferences | | Temporary context sharing | `@docs/filename.md` reference on demand, don't stuff into CLAUDE.md | | Task tracking | Use `` checkboxes in Markdown files | * * * ## Reference Resources * [Official Documentation: Memory System](https://code.claude.com/docs/en/memory) * (https://docs.claude.com/en/docs/claude-code/overview) * (https://docs.anthropic.com/en/docs/build-with-claude/prompt-engineering/overview)