While building a CLI Coding Monitor "AgentHUD" I stumbled on something Claude Code revealed about itself:
~/.claude/projects/<project-path>/memory/
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:
-
.memory-bank/— project-level, checked into git, driven by your CLAUDE.md instructions -
~/.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 (2)
Some comments may only be visible to logged-in visitors. Sign in to view all comments.