Claude Code's Experimental Memory System

Today I was reading about the Anthropic SDK memory tool and immediately wondered whether I could replicate something similar as a custom Claude Code skill.

But before going down that road I wanted to check whether Anthropic was already building something native, so I tasked Claude Code to research its own minified CLI bundle. Turns out they are already building it.

Note: I asked the agent to verify the discoveries a few times but haven't verified them myself manually so some information might be inaccurate or go out of date quickly.

Enable it

Add to ~/.claude/settings.json:

{ "autoMemoryEnabled": true }

Described in the source as "Enable auto-memory (research preview)".

Some accounts already have it on via a server-side flag - if ~/.claude/projects/<your-project>/memory/ already exists you're already enrolled.

To disable: CLAUDE_CODE_DISABLE_AUTO_MEMORY=1.

How it works

Claude Code maintains a file at ~/.claude/projects/<encoded-path>/memory/MEMORY.md and injects its contents into the system prompt at the start of every session. It's local to your machine and never touches git.

When the file is empty Claude sees:

Your MEMORY.md is currently empty. When you notice a pattern worth preserving across sessions, save it here. Anything in MEMORY.md will be included in your system prompt next time.

There's a 200-line hard limit (found verbatim in the bundle: var U_ = "MEMORY.md", pZ = 200). If exceeded Claude only gets the first 200 lines plus this warning:

WARNING: MEMORY.md is N lines (limit: 200). Only the first 200 lines were loaded. Move detailed content into separate topic files and keep MEMORY.md as a concise index.

The system is nudging toward a pattern where MEMORY.md is a short index and details live in separate topic files. Reading those topic files isn't automatic yet - that's behind a feature flag (tengu_coral_fern, off by default).

Agent memory scopes

For custom agents created through Claude Code's agent wizard there's a separate system with three scopes:

• Project - .claude/agent-memory/<name>/ - inside the repo, can be committed to git
• Local - ~/.claude/agent-memory-local/<name>/ - local to your machine
• User - ~/.claude/agent-memory/<name>/ - global across all projects

The project scope is the interesting one. Commit .claude/agent-memory/ and your whole team shares the same agent memory.

The gap

The main Claude Code session only gets local memory with MEMORY.md (layer 1).

Shared project memory that teammates can benefit from is only available for custom agents and requires explicitly setting one up. Arguably that's the most useful thing and it's not there yet for the main session.

Which brings me back to where I started. The SDK memory tool does exactly this. A Claude Code skill could fill the same gap allowing to save atomic memories in project files, but given how close Anthropic already is I'll probably just wait and see if this gets built natively first.