Earlier this year, Claude Code added an auto-memory feature, meant to enable the harness to develop contextual familiarity with your way of working in particular projects. Each project gets its own memory folder, with a MEMORY.md index and separate individual markdown files for each thematic entry.
This system represents a straightforward attempt to compensate for the lack of durable memory formation in Claude, by creating a structured set of artifacts that are available to “remind” the agent should something from the past become relevant in a later session. The MEMORY.md index file for the current working directory is injected into context on session start. That file includes shortform descriptions of each of the project’s specific files, so the agent knows to look at those files when they come up.
This system has the same basic defect of any memory system grounded in textual artifacts: texts are not self-interpreting, and they do not readily capture the durability, priority, context, or occasion of a given piece of historical knowledge the way human memory does. Trivia that were important for one session or task get placed alongside durable user preferences. Preferences that were expressed one time in a narrow context become permanent, etc. The agent has no guaranteed way of distinguishing these things from each other or placing them within the information space in order to properly guide its own behavior, and LLMs are often bad at contextualizing guidance and information.
The auto-memory system has two features that make it especially awful, though. First, the memory files are written and read by the agent silently. The updates happen without consultation, often very quickly in the middle of a given turn, and are easy to miss. Because the index file is injected on session start, every session begins primed with whatever was in that file, a file the user does not maintain, and probably never looks at.
Even worse, the memory files are stored outside of the associated project. They live in ~/.claude/projects/, not in the project directory they’re associated with. That means two things: (1) they’re non transferrable between users, so durable context that shapes the way an agent behaves in a given project for a given person will not carry over to collaborators on that project. (2) They are not versioned with the project itself, nor are they visible to readers of the project code. If I don’t work on a given repository for a couple of months, and go into it with a new Claude session, my agent is going to be primed to treat the, probably outdated, dictates of the project auto-memories as if they are still relevant. Maybe they are, maybe not.
Furthermore, nothing in the memory files automatically expires memories. They do not necessarily get updated or overwritten. They just accrue. I checked today and found that one of my most active personal projects still has stored memories relating to long-deprecated features and experiments from April, six months ago. That means the harness is guiding the agent to build up a never-ending log of stale docs which are treated as evergreen guidance for a project. Docs I do not read or write, which are consulted without my knowledge.
I understand why this feature might be appealing to Anthropic in abstract. It puts a bandaid one one of the biggest defects of LLM coding agents. Additionally, storing these files in ~/.claude establishes a kind of lock-in effect where Claude Code ends up building up more knowledge of your way of working and your codebase than any other harness does, and that knowledge is private to Claude. But from the user side I think it’s an unequivocally bad feature.
If you want a document-based memory system, it should be colocated with the code it describes, it should have a healthy lifecycle attached to it, and it should be vendor-neutral.
That said, document-based memory systems are pretty bad, for all the reasons excess documentation is bad: they’re brittle, they go stale, and they compete with the code.