Memory System

Claude Code does not remember the conversation once a session ends. But there are six memory layers that compensate for this. Use this system well and you keep a consistent AI partner without the hassle of explaining everything from scratch each time.

Memory Layer Hierarchy

┌─────────────────────────────────────────────────────────────┐
│  Managed policy   (system path/CLAUDE.md)                    │
│  ─ Enforced org-wide, managed by IT/DevOps, top priority     │
├─────────────────────────────────────────────────────────────┤
│  User memory      (~/.claude/CLAUDE.md, ~/.claude/rules/)    │
│  ─ Personal global settings, applies to all projects         │
├─────────────────────────────────────────────────────────────┤
│  Project memory   (./CLAUDE.md, .claude/CLAUDE.md)           │
│  ─ Shared with the whole team, committed to git, permanent   │
├─────────────────────────────────────────────────────────────┤
│  Project rules    (.claude/rules/*.md)                       │
│  ─ Modular per-topic rules, conditional per-path application │
├─────────────────────────────────────────────────────────────┤
│  Local memory     (./CLAUDE.local.md)                        │
│  ─ Personal, per-project, not tracked by git                 │
├─────────────────────────────────────────────────────────────┤
│  Auto memory      (~/.claude/projects/<project>/memory/)     │
│  ─ Saved automatically by Claude, per-project learnings      │
└─────────────────────────────────────────────────────────────┘

All memory is loaded automatically at session start. More specific (narrower-scoped) instructions take precedence over broader ones.

1. Managed Policy (Enterprise)

A CLAUDE.md deployed at the system level by an organization administrator. It is enforced for all users and cannot be overridden by any setting.

OS	Path
macOS	/Library/Application Support/ClaudeCode/CLAUDE.md
Linux	/etc/claude-code/CLAUDE.md
Windows	C:\Program Files\ClaudeCode\CLAUDE.md

Deploy it with configuration management systems such as MDM, Group Policy, or Ansible.

2. User Memory

Location: ~/.claude/CLAUDE.md (Windows: C:\Users\{name}\.claude\CLAUDE.md) Lifetime: permanent Scope: all of my projects

What to Store in User Memory

# Personal Settings

## Coding Style Preferences
- Prefer functional programming
- Dislike short variable names (avoid things like i, j, k)
- Comments should focus on "why" (the "what" belongs in the code)

## Communication Style
- Always explain the plan before changing code
- Don't change too much at once — work incrementally

## Frequently Used Technologies
- Mostly use Next.js, TypeScript, Prisma
- Prefer Vitest for testing
- Tailwind CSS for styling

User-Level Rules

Create personal rule files in ~/.claude/rules/ and they apply to all your projects:

~/.claude/rules/
├── preferences.md    # Personal coding preferences
└── workflows.md      # Preferred workflows

Initial Global Memory Setup

If you just installed Claude Code, start by creating the global CLAUDE.md:

mkdir -p ~/.claude
claude
> Interview me about my coding style and preferences. Save the results to ~/.claude/CLAUDE.md.

Claude Code asks a few questions and creates your global settings.

3. Project Memory: CLAUDE.md

Location: {project root}/CLAUDE.md or .claude/CLAUDE.md Lifetime: permanent (committed to git) Scope: every team member on the project

Covered in depth in the Writing CLAUDE.md chapter.

What to Store in Project Memory

# My Project

## Tech Stack
[Permanent tech stack information]

## Team Conventions
[Rules the whole team must share]

## Architecture Decision Records (ADR)
[Important technical decisions and their rationale]

## Build/Test Commands
[Frequently used commands — avoids repeated lookups]

Auto-generate with /init

The /init command can automatically generate a CLAUDE.md tailored to your current project.

4. Project Rules: .claude/rules/

In large projects, manage modular rule files instead of a single CLAUDE.md.

.claude/rules/
├── code-style.md      # Code style
├── testing.md         # Testing rules
├── frontend/
│   ├── react.md       # React conventions
│   └── styles.md      # Style guide
└── backend/
    └── api.md         # API rules

The paths field in the YAML frontmatter enables conditional rules that apply only to specific files:

---
paths:
  - "src/api/**/*.ts"
---

# API Development Rules
- Include input validation on every endpoint
- Use the standard error response format

See the Writing CLAUDE.md → .claude/rules/ section for details.

5. Local Memory: CLAUDE.local.md

Location: {project root}/CLAUDE.local.md Lifetime: permanent (local only) Scope: just me, just this project

It is automatically added to .gitignore, so you can safely store personal information. Useful for testing instructions before sharing them with the team, or for machine-specific settings.

6. Auto Memory: Claude's Automatic Memory

Auto Memory is a feature where Claude automatically saves learnings, patterns, and insights it discovers while working. Unlike CLAUDE.md, it isn't something you write — it's notes Claude keeps for itself.

Enabled by default

Auto Memory is enabled by default. You can toggle it on and off with the /memory command.

What Claude Remembers

• Project patterns: build commands, testing conventions, code style
• Debugging insights: solutions to tricky problems, common error causes
• Architecture notes: key files, module relationships, important abstractions
• User preferences: communication style, workflow habits, tool choices

Auto Memory File Structure

Each project has its own memory directory:

~/.claude/projects/<project>/memory/
├── MEMORY.md          # Concise index (auto-loaded every session)
├── debugging.md       # Detailed debugging pattern notes
├── api-conventions.md # API design decisions
└── ...                # Created by Claude as needed

The <project> path is derived from the git repository root. All worktrees and subdirectories of the same git repository share a single Auto Memory directory.

The 200-Line Limit of MEMORY.md

Only the first 200 lines of MEMORY.md are auto-loaded at session start. Content beyond 200 lines is not loaded. Claude automatically splits detailed notes into separate topic files (e.g., debugging.md, patterns.md) to keep MEMORY.md concise.

Topic files are not loaded at session start; Claude reads them directly when needed.

Managing Auto Memory

/memory     # Open memory files + toggle

You can also tell Claude directly what to remember:

> Remember that this project uses pnpm
> Save to memory that API tests need a local Redis

Disabling Auto Memory

// ~/.claude/settings.json (disable globally)
{ "autoMemoryEnabled": false }

// .claude/settings.json (disable per project)
{ "autoMemoryEnabled": false }

An environment variable overrides all settings (useful in CI/managed environments):

export CLAUDE_CODE_DISABLE_AUTO_MEMORY=1  # Force disable
export CLAUDE_CODE_DISABLE_AUTO_MEMORY=0  # Force enable

Auto-dream: Automatic Memory Cleanup (Unofficial, Undocumented)

Not officially documented + signs the UI toggle was pulled (as of 2026-04-23)

Auto-dream is a feature not listed in Anthropic's official documentation (code.claude.com/docs/en/memory, /settings, or the /changelog up to v2.1.117). Anthropic's release plans and rollout policy are unannounced — this chapter is a synthesis of external user reports and GitHub Issues.

Observed exposure change (verified firsthand):

When	Environment	/memory toggle
About a month ago (around v2.1.81)	macOS	✅ Showed "Auto-dream: on · never · /dream to run"
Now (v2.1.117)	Windows	❌ Only "Auto-memory: on" shown; Auto-dream toggle gone

The changelog contains no withdrawal or deprecation notice. The settings.json autoDreamEnabled key remains, but whether it works is unknown. It is safest to assume the toggle is generally not visible in your audience's environments.

If Auto Memory stores learnings, Auto-dream is a background task that organizes the accumulated memory. It automatically deduplicates, merges related content, and consolidates stale information.

Currently verified status:

Item	Status
Background memory cleanup behavior	✅ Confirmed working (multiple user reports)
autoDreamEnabled: true key in ~/.claude/settings.json	✅ Recognized in some environments
"AutoDream" toggle exposed in the /memory menu	⚠️ Varies by user (Anthropic's exposure criteria unpublished)
dreaming indicator in the status bar	❌ Not implemented; bug reported (Issue #38461)
Manual trigger /dream command	❌ Returns "Unknown skill" — not implemented (Issue #38426)

How to try enabling it:

1. Run /memory → if the "AutoDream" toggle is visible, turn it on
2. If the toggle isn't visible, add it directly to ~/.claude/settings.json:

   { "autoDreamEnabled": true }

3. In some environments this setting alone may not work (Anthropic's activation conditions are unpublished)

Mechanism (synthesized from external reports — no official confirmation):

• The system prompt reportedly includes the phrase "You are performing a dream — a reflective pass over your memory files" (source: Sakeeb Rahman's Threads analysis)
• A background subagent reportedly reviews memory files → deduplicates → refreshes → reorganizes topic files (source: multiple external builder reports)
• Trigger conditions: reported as a dual condition of session count + time (source: Tessl and Skool blogs)
• Duration example: one reported case of about 8-9 minutes to consolidate 913 sessions of memory (source: Antonio Cortes blog post)

All four items above are external user/builder reports with no official confirmation from Anthropic. Behavior may vary by environment and version.

Verified external report sources:

• Multiple reports of the /memory toggle appearing in v2.1.83+ environments
• Tessl blog: "Anthropic tests 'auto dream'" (framed as a testing phase)
• Around ten pieces of English-language builder content confirmed (Korean-market coverage not surveyed)

Required disclaimers when citing in videos or content

Auto-dream is not an officially released feature (not listed anywhere in Anthropic's official docs, news, changelog, or support, as of 2026-04-22). When citing it, always include these three disclaimers:

1. "Officially undocumented, gradual rollout in progress"
2. "The toggle may not be visible depending on your environment"
3. "The manual trigger /dream and status bar indicator are currently in a buggy state (GitHub Issues 38461 and 38426)"

Teaching it as a stable feature risks damaging your credibility when it doesn't reproduce in your viewers' or readers' environments.

Session Memory: The Conversation Context

The contents of the current conversation. It disappears when the session ends.

A Pattern for Making Session Memory Permanent

Save important decisions or information before the session ends:

> I finished the payment module today.
  If there are important decisions, update CLAUDE.md with them.

Claude: I updated CLAUDE.md:
- Refund policy: within 72 hours, direct Stripe API calls
- Webhook secret: STRIPE_WEBHOOK_SECRET environment variable
- Payment failure retries: 3 attempts, exponential backoff

Strategies by Memory Layer

Team Projects

Managed policy (IT/DevOps)
  └─ Org security policies, coding standards

Project CLAUDE.md (committed to git)
  └─ Team conventions, tech stack, architecture

.claude/rules/ (committed to git)
  └─ Fine-grained per-topic rules

Personal ~/.claude/CLAUDE.md
  └─ Personal coding style, communication style

CLAUDE.local.md
  └─ Personal test environment, local settings

Auto Memory
  └─ Each person's work patterns, debugging experience

Personal Projects

Project CLAUDE.md
  └─ Project status, technical decisions

Personal ~/.claude/CLAUDE.md
  └─ Global settings (applies to all projects)

Auto Memory
  └─ Project patterns, learnings

Memory Management Tips

Review and Edit with /memory

/memory

The /memory command opens memory files in your system editor and includes the Auto Memory toggle. You can see the full list of loaded memory files.

Update CLAUDE.md Regularly

Update the status whenever a piece of work is done:

> Done for today. Update the status section in CLAUDE.md.

Clean Out Stale Information

Accumulated memory eventually creates confusion:

> Clean up the completed items in CLAUDE.md.
  Keep only what's currently in progress.

Loading Memory from Additional Directories

CLAUDE.md files in directories added with --add-dir are not loaded by default. To load them:

CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 claude --add-dir ../shared-config

The Memory System End to End

New session starts
│
├─ Load managed CLAUDE.md (org policy)
├─ Load ~/.claude/CLAUDE.md + rules/ (user memory)
├─ Load ./CLAUDE.md + .claude/rules/ (project memory)
├─ Load ./CLAUDE.local.md (local memory)
└─ Load first 200 lines of MEMORY.md (auto memory)
│
│    [Work proceeds]
│
│    Important decision mid-session
│    → Record it in CLAUDE.md immediately
│
│    Claude discovers a pattern
│    → Saved automatically to Auto Memory
│
│    /compact (context compression)
│    → Key summary retained
│
Session ends
│
└─ "Update CLAUDE.md with today's work"
    → Saves what the next session needs to continue