DEV Community

Cover image for Claude Code Has a Hidden Memory System You Probably Don't Know About
Dawid M.
Dawid M.

Posted on

Claude Code Has a Hidden Memory System You Probably Don't Know About

#ai #claudecode #agents #memory

While building a CLI Coding Monitor "AgentHUD" I stumbled on something Claude Code revealed about itself:

~/.claude/projects/<project-path>/memory/
Enter fullscreen mode Exit fullscreen mode

Claude Code automatically maintains a MEMORY.md file there — scoped per project, persisting architecture decisions, conventions, and preferences across sessions. It writes to it as it learns about your project.

Two memory systems, not one

If you're using a .memory-bank/ pattern in your project root (like I do via my Autonomous Agent Law), you actually have two persistence mechanisms running:

  1. .memory-bank/ — project-level, checked into git, driven by your CLAUDE.md instructions
  2. ~/.claude/projects/.../memory/ — user-level, Claude Code's built-in auto-memory, not in git

The first is yours. The second is Claude Code's own. They don't talk to each other.

Why this matters

If you've ever started a new session and the agent somehow "remembered" things you didn't put in .memory-bank/ — this is why. Claude Code was reading its own auto-memory.

It also means context can drift between the two. Your .memory-bank/ says one thing, the auto-memory says another, and the agent has to reconcile both.

Worth knowing. Worth deciding which one you trust as source of truth.

If i had read the claude docs i would have known this earlier :)
https://code.claude.com/docs/en/memory

Dawid M. — Consultant. 20 years of strategy, systems, and data across manufacturing, finance, real estate, and telco. Working on making AI agents deliver business value.

Dawid M. — Consultant. 20 years of strategy, systems, and data across manufacturing, finance, real estate, and telco. Working on making AI agents deliver business value.

Top comments (0)