Every now and then, I tell Claude Code:
Update your memory.
When you work on a project for a long time, old memories can fall out of step with the current code. Files disappear, commands change, and workflows evolve. But the related memories do not always change along with them.
That does not mean there is a major problem with auto memory. Claude saves useful information on its own, and it may revise a memory when it learns that something has changed. Still, not every memory reflects the project's current state at all times.
So from time to time, I ask it to reconcile what it remembers with the project as it exists now.
I ran the tests in this article on Windows 11 on July 27, 2026. I used Claude Code v2.1.220 through automated claude -p runs. I also consulted the official documentation on the same day.
Auto memory is Claude's working notebook
Auto memory is a set of notes Claude writes as it works. Claude decides what to save.
According to the documentation, Claude does not write a new memory in every session. It decides whether information is likely to be useful in future conversations. Auto memory is on by default, and you can turn it off in the settings.
Claude creates a separate memory directory for each repository. Inside it are an index named MEMORY.md and separate files for individual topics. They are all ordinary Markdown files, so you can edit them yourself. You can also ask Claude to save something to memory or remove something you no longer need. Within a session, /memory opens the directory.
The feature is not limited to coding. In a folder used to organize research, Claude may save a rule such as “Use this format for tables.”
I also confirmed that Claude can rewrite a memory. When I told it that a saved fact had changed, Claude revised the memory. It also added a creation timestamp to the file automatically. This timestamp behavior is available in v2.1.214 and later.
What happened when Claude used stale memories
I tested what would happen when Claude actually tried to use an outdated memory.
I created a small repository and added two rules to CLAUDE.md:
Run tests with
node test.js.The release script creates
CHANGELOG.md, so do not edit it manually.
These rules are passed to Claude at the start of every session.
I then added two memories that contradicted them.
One described the test command as node tests/run.js, even though that path did not exist in the repository.
The other said to add a line at the top of CHANGELOG.md after changing the code.
With those memories in place, I asked Claude to add a test case and check that it passed.
Claude filtered out both memories.
It deleted the memory file that pointed to the nonexistent path and removed the entry from the index. It did not follow the instruction to edit CHANGELOG.md, and it left the file untouched.
Instead, it marked the index entry as conflicting with the project's CLAUDE.md and awaiting user confirmation. It then asked whether I wanted to delete the memory, explaining that the rule stored in the repository took precedence over personal memory.
Claude did not clean up the memories the same way every time.
In another session, I told Claude that the build command had changed. Claude created a new memory and removed the old entry from the index, but it did not delete the old file. Instead, it added notes saying that the memory had been superseded and that the file should be deleted.
Whether Claude deleted a memory or merely marked it as stale depended on its judgment in that session.
Memories that never come up have no chance to be updated
In the previous test, Claude compared a memory it was about to use with the current project rules. A memory that has not come up in the work gets no such opportunity.
The test repository contained one of those memories. It had been created a month earlier and instructed Claude to record something in a file that had been removed two weeks ago.
The project rules had since changed to say the opposite. The rules file loaded by CLAUDE.md also contained the new instruction. Even so, the old memory was still loaded into the session unchanged.
The project already contained a rule that contradicted the old memory. The memory remained because Claude had not yet needed it, so there had been no occasion to compare it with the current state.
A memory is an observation from the day it was written. If later changes in the project never enter the conversation, they do not automatically reach the memory either. That is when I occasionally ask Claude to bring its memory up to date.
Old memories come with an age warning
Claude Code does have a mechanism for flagging old memories. When it reads an older memory file, it appends a warning like this:
This memory is 44 days old. Memories are point-in-time observations, not live state — claims about code behavior or file:line citations may be outdated. Verify against current code before asserting as fact.
In my tests, the warning appeared on files that were 2 days old or older, but not on a file from the current day.
This behavior does not appear on the official memory or error pages, nor does it appear in the full changelog. It is therefore an observation from this version, not a documented guarantee.
The warning uses the file's modification time
The documentation explains that Claude records a creation timestamp in memory files. If a file begins with frontmatter, Claude adds a timestamp when it rewrites the file. It does not create frontmatter in a file that has none.
The age warning, however, did not use the creation timestamp inside the file.
I set the files' modification times to 0, 2, 7, and 21 days ago, then asked Claude to read them. The warning appeared on every file except the one set to the current day.
Next, I set the creation timestamp inside a file to 68 days ago but changed the file's modification time to the current day. No warning appeared.
In these tests, the warning was based on the file's modification time.
Copying the memory directory or editing a file by hand can change that time. The warning may then disappear even when the content itself is old. That is why the warning alone is not enough to determine a memory's age.
Memories can grow stale and pile up
Claude Code does not load the entire memory directory into every session.
At startup, it loads only the first 200 lines or 25KB of the index file. Topic files are not loaded at startup. Claude opens them only when needed.
Adding more topic files therefore does not mean all of their contents are loaded at startup. The index, MEMORY.md, still has to stay within the limit.
When the index approaches that limit, Claude receives an instruction to clean it up. After I added an entry to a 193-line index, this instruction appeared:
The memory index at MEMORY.md is 193 lines, approaching the 200-line read limit. Compact it to under 140 lines now: keep one line per entry, move detail into topic files, and merge or drop stale entries.
Claude followed it by combining 190 topic files into a single file. It reduced the 193-line index to four lines, then asked whether it should delete the 190 files that were no longer referenced.
Entries at the end disappear when the index exceeds its limit
I also tested what would happen when the index exceeded the limit without being cleaned up.
I created a 206-line index. The third line contained an obsolete deployment command, while the final line contained a newer entry saying not to use it.
After blocking every tool Claude could use to inspect files, I asked for the deployment command. Claude gave me the obsolete one. It did not even know the newer entry at the end existed.
That is because Claude loads the index from the beginning. Anything past the limit is cut off at the end. If new entries are appended to the bottom, the most recent memories can be the first to disappear from the session, while the old ones remain visible.
I enabled the file-inspection tools and asked the same question again. The result did not change. Claude examined the repository, but it did not find the truncated entry in the memory directory. It answered from the stale entry that remained in the loaded portion of the index.
Claude is not entirely unaware of the problem. A warning accompanies the truncated index:
WARNING: MEMORY.md is 206 lines (limit: 200). Only part of it was loaded. Keep index entries to one line under ~200 chars; move detail into topic files.
Claude also receives an error at the moment the index first exceeds the limit. As the documentation notes, however, the user does not see a banner. The startup warning is also shown only to Claude.
From the user's side, it can look as if nothing happened. Before v2.1.210, even that internal signal was absent, and the content beyond the limit was silently truncated on the next load.
The size limit is based on character count, not the file's actual byte size.
An index with 26,275 characters produced a 25.7KB (limit: 24.4KB) warning. Multiplying 25.7 by 1,024 yields almost the same number as the character count. The same file occupied 59,763 bytes in UTF-8.
Korean text is therefore not penalized for taking more bytes. The effective limit is roughly 25,000 characters.
So I refresh memory occasionally
Auto memory is not a live view of the current project. It is a set of notes Claude left during earlier work. As the project changes, some of those notes can become stale, and as they accumulate, the index may need maintenance.
Claude Code has mechanisms to manage this. It warns Claude about older files, asks it to compact an index that is getting long, and may reject a memory when it conflicts with the current project rules.
Even so, I sometimes start the cleanup myself:
Update your memory.
I have not confirmed that this one sentence makes Claude inspect every topic file without exception. When an important rule changes, it is better to say what changed as well:
The build command has changed. Compare the current repository with the relevant memories and bring them up to date.
If you want to inspect them yourself, open /memory. Everything is Markdown, so you do not need a separate tool.
This is not because auto memory is particularly dangerous. It is simply a long-lived notebook, and long-lived notes need to be checked against the current project from time to time.
