Claude Code's Hidden Memory Directory

Claude Code has a memory system that’s not in the docs.

Buried in the system prompt is a reference to a per-project memory directory at ~/.claude/projects/<project-path>/memory/. Put a MEMORY.md file in there and it loads into the system prompt automatically, before every session.

The system prompt itself confirms this:

“You have a persistent auto memory directory at [path]. Its contents persist across conversations.”

And:

“MEMORY.md is always loaded into your system prompt - lines after 200 will be truncated, so keep it concise and link to other files in your auto memory directory for details.”

This is separate from the documented memory features added in v2.1.31 - conversation search tools, CLAUDE.md files, and .claude/rules/*.md. Those are all user-managed. This one is agent-managed. Claude Code creates the directory structure, populates it during sessions, and loads it automatically.

The directory structure: ~/.claude/projects/<project-path>/memory/

Why MEMORY.md matters

CLAUDE.md is for project conventions. Rules are for organizational policies. MEMORY.md is for patterns that only emerge after you’ve worked with an agent for a while.

Like: “When using gh api, always quote URLs containing ? characters for zsh compatibility.”

Or: “This project uses custom eslint rules - run npm run lint:fix before commits.”

Or: “Database migrations require manual approval - never auto-apply.”

These aren’t project guidelines. They’re learned behaviors specific to how you and Claude work together on this codebase. The context that makes collaboration smooth but doesn’t belong in repo documentation.

How it compares to other context mechanisms

Claude Code now has several ways to inject context: CLAUDE.md for project-level instructions, .claude/rules/*.md for organizational policies, conversation memory for recalling previous sessions, and now MEMORY.md for agent-maintained state.

The difference: MEMORY.md is write-accessible by Claude Code itself. The agent can update its own memory between sessions without touching your project files. This enables the task graph pattern Steve Yegge built into Beads - persistent state that survives across sessions without polluting your git history.

The truncation limit

200 lines, then it truncates. The system prompt explicitly tells Claude to “keep it concise and link to other files in your auto memory directory for details.”

This forces a natural hierarchy: keep frequently-accessed patterns in MEMORY.md, move detailed context to adjacent files, link between them. Similar to how you’d organize any knowledge base, but the line limit makes it structural rather than optional.

Still undocumented

I can’t find this feature mentioned in release notes, the official docs, or GitHub issues. It might be intentionally undocumented during active development. Or it might have shipped quietly while Anthropic focuses on the higher-level abstractions (Cowork plugins, skills, plan mode).

Either way, it’s production-stable. The system prompt references it. The directory structure persists. And it solves a real problem: giving agents memory without requiring users to maintain it manually.

Check if any of your projects have one:

find ~/.claude/projects/*/memory -name "MEMORY.md" 2>/dev/null

On my machine, one project had already written its own. Inside: 12 lines. An architecture map of key files and a hard-won bug discovery about a tool execution edge case. Exactly the kind of thing you debug once and never want to rediscover.