Memories are an anti-pattern for Claude Code :: keyboards downMemories are an anti-pattern for Claude Code<br>2026-07-15rob3 min read (636 words)<br>#claude<br>#claude-code<br>#agents<br>#ai<br>#adr<br>#documentation Memories are a feature that makes Claude feel magical, but in practice they’re a footgun. Because of that, I’ve come to see memories as an anti-pattern, and when Claude reaches for one, my first question is always: “Why?”<br>To be fair, they solve a very real limitation with agents. Repeated bits of information from past conversations get stored to a Markdown file in your home directory, and future sessions inherit that context. This addresses the frustration of feeling like you’ve told Claude something over and over again. Express that frustration and it apologizes and saves the detail to memory, as if it were taking notes.<br>That automatic note-taking can feel like magic in a chat experience. Claude remembers you have a cat when you’re talking about plants for your home (“that’s a good choice, but not safe for your cat if they eat it”). But the same behavior is poison for Claude Code.<br>Where memories go#<br>When Claude saves memories automatically, it’s almost always to your personal memory, stored in your home directory. From Claude’s perspective — don’t lose important information in the future — this feels safe. If you tell it you want a certain coding style and chastise it for not following it, it stores that as a preference so that in a different project it still knows what you like.<br>For messing around with solo projects, that can be nice. But it doesn’t make sense in a team setting.<br>Every project can have its own rules, and as a developer in an open source or professional setting, it’s important to stay flexible. The reasons can be both social and technical. One project may have 10 users and another 100k, and they may weigh the speed of implementation in a prototype very differently from the cost of optimization in a large-scale system. Other times it’s simply team agreements — conventions that work for one collection of people but not another.<br>Two problems with personal memory#<br>Storing preferences in your personal context causes two problems.<br>First, one project’s preferences may not be another’s — and may not even be your own. As developers in traditional settings, we’re often adapting to the existing patterns of a project, and Claude does that too. Saving preferences from one codebase can pollute how Claude works in others.<br>Second, if these are preferences that should apply to a codebase, no one else on the team has them. If you’re making decisions about how a project is built, those decisions should live in the codebase so that anyone contributing can see them. Personal memory recreates exactly the kind of undocumented decision we’ve spent decades trying to avoid.<br>A better answer than memory#<br>The easy answer is that Claude supports project-level memory, and that would address the issues above. But I think there are better options — ones that serve both humans and agents really well.<br>Memories are hidden. Project direction should be front and center, living in the documentation folder. We have patterns for documenting project decisions going back 40 years: specifications, RFCs, PRDs, ADRs, and more. These are well known to both agents and humans, and each carries structure that gives agents better context. Your project should decide which ones fit.<br>In my experience, ADRs are the software-development equivalent of memories, and they work best for agentic development — worthy of its own post. But decide which systems work for your project, and then tell Claude explicitly, in the CLAUDE.md file, that this is how the project records patterns and decisions. Reaching for alternatives it already knows well gives Claude direction it can hold to fairly reliably. If you tell it that it’s responsible for maintaining those docs, it will do that instead of falling back to memories — and that context stays in the codebase, findable by every contributor.
Read other posts<br>[Agent-first CLIs are about reducing turns, not JSON] >