I Built Claude's Memory Wrong
I was using Claude’s memory wrong.
I have been building with Claude Code for nine months now, and I thought I had understood how memory and context worked. I do understand the concepts, don’t get me wrong.
A while back, I was noticing that Claude wasn’t saving the notable parts of the conversation into memory and seemed like it had amnesia. So, I built a skill ‘/save’ which basically asks it to identify key decisions from a conversation and save them to memory and create any relevant context files. Over time, as I learned how it was doing, I got into the habit of asking it to ‘validate’ its work before I exited the conversation.
Memory.md has a 200-line, 25KB file limit. Since Claude Dreaming came out in May, I created a rule that I would do memory cleanups in one go when no other conversations are ongoing. Recently, Claude had been flagging to me that I was reaching 175 lines and that I should clean up the memory. So a week ago I spent a chunk of Saturday afternoon cleaning up outdated parts of the memory (completed projects, irrelevant references, feedback consolidations, etc.). After last week’s cleanup, Claude kept reminding me that memory at 181 lines needed to be cleaned up (again!).
In addition, I was starting to feel brain-fry reading AI-written content for hours, and my writing-style rules (for Claude to edit my writing) had drifted. That rules file was also 35KB, grown over time.
I wondered whether I had misunderstood how memory works or if my setup was right. So this past weekend, I sat down to understand how to optimize memory.md. I started with the basics. Refreshing my own memory (pun intended) on how context and memory work and best practices to engineer them. The guidance on how to use claude.md and memory.md has been updated as the technology has evolved. Mine was operating from the initial setup. I didn’t just want to clean up or change the harness. I wanted to make it better. So, I looked at Anthropic’s own guidance on best practices.
Here are my lessons:
Audit for conflicts: Over time, Claude had written rules (sometimes conflicting) in multiple places, so it was referencing stale information where it wasn’t updated. My writing-style, LinkedIn-rules, blog-writer, and humanize skill all had a different levels of detail in my writing voice, operational rules like publishing cadence, and AI slop to avoid. So depending on how I phrased my ask, it would invoke a different rule. Fix: If possible, write once and point to it from other places. One writing-style, cleaned up with my original writing as examples, one humanize skill that points to the writing-style, and one operational file with platform and publishing mechanics - kept separate with purpose.
Audit what doesn’t get flagged: The system reliably flagged that memory was reaching its limit. But instead of flagging that the writing had drifted, it updated the writing-style with feedback, and that drift increased the file size with conflicting information in the same file. I found out through brain-fry after hours of trying to comprehend the AI-written content. Fix: I added a ceiling to the writing-style to not go over 220 lines, which will force a cleanup next time it starts to drift.
‘/Save’ identified key decisions and wrote them accurately. It also had a step to “update a file,” but not all files with relevant references. My validation habit checked that things got written, not whether the old thing stopped being true. So I updated the step to look for all references.
When I ran the new cleanup again, the gate accurately loaded my writing-style for drafting but not reviewing, and Claude reviewed my voice without actually reading my voice file. So the narrow trigger had to be updated to cover both reviewing and judging.
The verdict on whether this worked is still pending. At least Claude isn’t reminding me that the memory is reaching a limit. My memory.md file now reads at 58 lines.
Stale memory is worse than no memory. Append-only memory scored 0.210 against a no-memory baseline of 0.309 under drift, and “falls below no memory because the stale precedent remains active.” As I discovered in my own setup, my /save was appending selectively, and it cost me two Saturday afternoons.