Claude Code's Memory Crisis: How a Simple Config File Is Breaking Anthropic's AI Developer Tool

A seemingly minor configuration feature in Anthropic's Claude Code -- the company's AI-powered command-line coding assistant -- has become a persistent source of frustration for developers who rely on it daily. The problem: the tool's memory system, built on a file called , doesn't work the way users expect it to. And in some cases, it doesn't work at all.

The issue, cataloged as #42796 on GitHub, was opened on July 10, 2025, by a user named seanoliver. The complaint is straightforward. When developers tell Claude Code to "remember" something -- a coding preference, a project convention, a workflow instruction -- the tool is supposed to write that information into a file so it persists across sessions. Instead, users report that Claude Code frequently ignores these stored memories, overwrites them without warning, or fails to read them altogether when starting a new conversation.

"Claude regularly ignores instructions in CLAUDE.md," seanoliver wrote. "It also frequently overwrites or removes existing memories when adding new ones."

The response from other developers was immediate. Within hours, dozens of users chimed in with similar experiences, suggesting the problem isn't isolated but systemic. Some described spending significant time carefully curating their files only to find Claude Code disregarding the contents entirely during subsequent sessions. Others reported that the AI would acknowledge the file existed but then proceed to violate every instruction contained within it.

This matters more than it might appear at first glance. Claude Code isn't a toy. It's Anthropic's bid to compete directly with tools like GitHub Copilot, Cursor, and Google's Gemini Code Assist in the rapidly growing market for AI-assisted software development. The tool operates in the terminal, reading and writing code, running commands, and managing entire development workflows with minimal human intervention. For it to function effectively in real projects, it needs persistent context -- the ability to remember how a particular codebase is structured, what conventions the team follows, which libraries are preferred.

That's exactly what is supposed to provide. Think of it as a project-specific instruction manual that the AI reads before doing anything. Anthropic's own documentation describes it as the primary mechanism for customizing Claude Code's behavior on a per-project basis. Developers can place the file at the root of their repository, and Claude Code should treat its contents as standing orders.

Should. The gap between design intent and actual behavior is what's driving the frustration.

One commenter on the GitHub issue described a scenario where they had explicitly instructed Claude Code, via , to always use TypeScript strict mode in a particular project. Claude Code ignored the instruction repeatedly, generating JavaScript files instead. When confronted, the AI would apologize, acknowledge the instruction, and then immediately violate it again on the next task. The pattern -- acknowledge, apologize, repeat -- is a familiar one to anyone who has worked extensively with large language models, but it's especially problematic in a tool marketed for professional development workflows.

Another user reported that Claude Code would sometimes read the file at the start of a session but then "forget" its contents partway through a long interaction, reverting to default behaviors. This suggests the issue may be related to context window management -- the way the tool handles the finite amount of text it can process at any given time. As conversations grow longer and more complex, earlier context, including the contents of , may get pushed out or deprioritized.

The overwriting problem is arguably worse. Multiple users described situations where they asked Claude Code to add a new memory, and it replaced the entire contents of with a single new entry, destroying carefully organized instructions that had been built up over weeks. No warning. No confirmation. Just gone.

"I had about 30 lines of project-specific instructions," one developer wrote. "Asked Claude to remember one new thing. It replaced everything with a single bullet point."

Anthropic has not publicly responded to the specific GitHub issue as of this writing, though the company's engineers have been active in other Claude Code issue threads. The tool is still technically in beta, which Anthropic has used as a general disclaimer for known limitations. But beta or not, developers are building real workflows around it, and broken memory fundamentally undermines trust in the tool.

The timing is notable. Anthropic has been aggressively pushing Claude Code as a differentiator in its competition with OpenAI and Google. The company released Claude Code publicly in February 2025 and has since rolled out features including GitHub integration, multi-file editing, and agentic task execution -- the ability for Claude Code to autonomously plan and carry out complex development tasks across multiple files and commands. Memory persistence is foundational to all of these capabilities. An agent that can't remember its instructions is an agent that can't be trusted with autonomy.

The broader AI coding tool market is watching. GitHub Copilot, powered by OpenAI's models, has its own approach to persistent context through custom instructions and repository-level indexing. Cursor, the AI-first code editor that has attracted significant developer enthusiasm, uses files for similar purposes and has generally received better marks for adherence to stored instructions, though it has its own issues. Google's Gemini Code Assist takes yet another approach, integrating with Google's broader cloud infrastructure for context management.

What distinguishes the Claude Code memory problem from typical AI inconsistency is the explicit contract it creates. When a tool provides a specific mechanism for persistent instructions -- a named file, a documented format, a clear promise that "Claude will read this" -- and then fails to honor that mechanism, it breaks a fundamentally different kind of trust than when an AI simply generates an imperfect response. Developers aren't complaining that Claude Code writes buggy code sometimes. They're complaining that it ignores its own instruction manual.

Some users on the GitHub thread have proposed workarounds. One popular approach is to include redundant instructions both in and in the initial prompt of every session. Others have started using version control specifically for their files, committing them to git so that overwrites can be quickly reverted. A few have written wrapper scripts that automatically re-inject contents at regular intervals during long sessions.

These are clever hacks. They're also exactly the kind of thing that shouldn't be necessary.

The issue touches on a deeper tension in AI tool development: the gap between what these systems can do in demos and what they can do reliably in production. Claude Code is remarkably capable in many respects. It can understand complex codebases, generate sophisticated implementations, and reason about architectural decisions in ways that would have seemed impossible two years ago. But capability without reliability is a hard sell to professional developers who need their tools to behave predictably.

Anthropic's challenge is clear. The company needs to fix the memory system -- not just patch it, but make it deterministic enough that developers can trust it implicitly. That likely means changes to how contents are weighted in the model's context, how the file is protected from accidental overwrites, and how memory persistence is maintained across long sessions. It may also mean rethinking the architecture entirely, moving from a simple file-based approach to something more structured and harder for the model to accidentally ignore or destroy.

Until then, developers are left in an uncomfortable position. They have a powerful AI coding assistant that can't reliably remember what they told it yesterday. For a tool that aspires to autonomous agency -- one that Anthropic wants developers to trust with significant, unsupervised coding tasks -- that's not a minor bug. It's a credibility problem.

And credibility, once lost with developers, is extraordinarily difficult to win back.