How Claude Code Memory Works: CLAUDE.md and Auto Memory Explained

When I first began working with Claude Code and, frankly, didn't know much about it, I experienced some issues that puzzled me.

It would forget things, things we had talked about ad nauseum. Commands we had performed dozens of times. All vanished as if they never existed.

Or,even worse, Claude Code would not only forget something, but it would replace that something with something else. If you've read articles about AI, you may have come across the term hallucination, and that's exactly happened here. Instead of using a file path that we'd used a dozen times, Claude Code would come up with its own filepath, which would inevitably fail during execution because the path didn't exist. In this Claude Code tutorial, I want to explain how the memory works, and what you can do to get better results.

Claude Code works like many other AI code augmentation programs, and that's with context. Context is the information surrounding the project and it's this context that Claude Code ingests and analyzes to make decisions. But, much like RAM in your computer, Claude Code only allocates so much space for context before it's filled. At that point, Claude Code performs a compaction, which is essentially a mechanism to summarize details, freeing up context space. However, this compaction risks losing key details, like the filepath I mentioned earlier.

This led me to discover more about how Claude Code works, which led me to the CLAUDE.md file.

For those of you new to the CLAUDE.md file, it is essentially a configuration file for Claude Code written in a markdown format. It's unstructured and can contain information that you want Claude Code to retain about your project, such as file folders, links to documentation, and even the project's name.

You can simply add a line to the CLAUDE.md file to give it any kind of information and it will retain it. But remember something about this file before you begin stuffing it with the collective knowledge of the universe: the official Anthropic documentation recommends the CLAUDE.md file be 500 lines or less. There are things you can do to help shrink the size of of it when your CLAUDE.md file gets too long.

Now if you want Claude Code to remember something, all you need to do is add it to your CLAUDE.md file.

But Claude Code also has what's called an auto memory, which is a file it populates automatically based on what it chooses to save, automatically, and without your input.

And the first 200 lines of this auto memory file is read by Claude Code at the beginning of every session.

The best part about Claude Code's automatic memory is that you can explicitly add instructions to it, just like you can to the CLAUDE.md file, like this:

And when you invoke your command, Claude Code responds in kind:

If you're having a difficult time getting Claude Code to remember something, try adding it into the first 200 lines of the auto memory file next time. It might make a difference. And if your CLAUDE.md file really isn't cooperating, you have a couple of other options. There are multiple places to put a CLAUDE.md file (you can have more than one!) or you can try using Claude Code hooks to force your instructions to be executed every time.

I hope now you have a better understanding of not only the CLAUDE.md file, but also Claude Code's auto memory file, and are comfortable enough to customize one or both of them during your next project.

Preparing for the CCA exam? Start with our overview: What Is Anthropic's Claude Certified Architect Exam?