Auto Memory and Knowledge Files

You close a session. Open a new one the next morning. Claude already knows your build command, your preferred package manager, that weird Postgres workaround from last Tuesday. You never told it to save any of that.

That is auto memory. Claude Code watches what happens during sessions and decides what is worth writing down for next time. No setup, no config. It runs in the background and quietly accumulates project knowledge.

How It Works

Auto memory is on by default. During a session, Claude picks up on things worth persisting: build commands, debugging insights, architecture decisions, code style preferences, workflow patterns. It writes these to plain markdown files on disk.

You'll see brief messages like "Writing memory" or "Recalled memory" in the interface. Not every session triggers a write. Claude filters for what's genuinely useful.

Storage is local. Nothing goes to the cloud. Nothing syncs across devices. Files live at:

~/.claude/projects/<project>/memory/

The <project> path comes from your git repo. All worktrees sharing the same repo share the same memory directory. Outside a git repo, Claude uses the project root directory instead.

The Memory Directory

Inside that folder:

~/.claude/projects/<project>/memory/
├── MEMORY.md          # Index file, loaded every session
├── debugging.md       # Topic-specific notes
├── api-conventions.md # API design decisions
└── ...

Two types of files. One is special.

MEMORY.md is the index. The first 200 lines load at the start of every conversation. Always-on knowledge. Think of line 1 through 200 as prime real estate.

Actually, wait. This is worth emphasizing. Content beyond line 200 does NOT load at session start. Claude keeps MEMORY.md concise on purpose. When detailed notes pile up, it moves them into topic files to stay under that limit.

Topic files (like debugging.md, patterns.md) are the overflow. They do NOT load at startup. Claude reads them on demand when something relevant comes up. This keeps your context window lean while deep knowledge stays available.

Try It

Start a session and say:

always use pnpm, not npm for this project

Claude saves that preference. Close the session, open a new one, ask it to install a package. It will use pnpm.

Run /memory to see what is loaded:

/memory

This shows all CLAUDE.md files and rules files currently active. You can toggle auto memory on or off, or open the memory folder in your editor. Select any file to view or edit it.

Want something saved to CLAUDE.md instead? Be specific:

add "always use pnpm" to CLAUDE.md

That writes to CLAUDE.md (version-controlled, team-visible) rather than local memory.

Shaping What Gets Remembered

You don't need to micromanage this. But audit it occasionally.

These are plain markdown files. Open them in any editor. Delete lines that are wrong. Edit things that have drifted. Add structure if the notes are getting messy. You own these files completely.

Disabling auto memory. Three ways. The /memory command has a toggle. You can set autoMemoryEnabled: false in project settings. Or the environment variable:

export CLAUDE_CODE_DISABLE_AUTO_MEMORY=1

Nudging what gets saved. Being explicit during sessions helps. "Remember that we switched to Vitest" is a strong signal that gets picked up reliably. "Our CI uses Node 20" said in passing might or might not stick. More declarative, more reliable.

MEMORY.md vs CLAUDE.md. Different tools for different jobs. CLAUDE.md is checked into your repo, shared, versioned, team-visible. Auto memory is local, personal, somewhat ephemeral. Project rules everyone should follow go in CLAUDE.md. Your own workflow preferences and debugging context go in auto memory.

The 200-line budget. If you are editing MEMORY.md manually, keep the important stuff near the top. Architecture decisions, key commands, active conventions. Push detailed debugging notes into topic files.

Subagents. If Claude spawns subagents for complex tasks, those subagents can maintain their own auto memory. Mostly invisible to you, but it explains why you might see memory files you didn't create.

The Short Version

• On by default. Stores plain markdown at ~/.claude/projects/your-project/memory/. Local only, never synced.
• MEMORY.md is the index. First 200 lines load every session. Everything else is on-demand topic files.
• /memory to see what is loaded, toggle the feature, or edit files directly.
• For shared project rules, use CLAUDE.md. Auto memory is personal.
• Audit periodically. Delete what is wrong, edit what changed, keep MEMORY.md lean.