Claude Code memory is a set of plain files that load before I say a word, so my agent already knows my blogs, my rules, and the things I’ve corrected it on. Mine holds 475 files and exactly one of them opens automatically. The rest wait until something needs them. This post walks through what’s in it, what deliberately stays out, and gives you a generator that builds the starting version of your own.
The thing I’d have to say out loud every morning
If I had to repeat everything Claude knows about me every day, I wouldn’t be doing any of this. It would be maddening.
Picture the version without it. I open a session and start with: I run four blogs, here’s what each one is about, here’s how I write, no em dashes, always use contractions, the workflows run on my own server, the apps go to Cloudflare, and here are the eleven things you got wrong last month, please don’t do those again. Then I could start working. Every morning, in every tab.
I’d have quit in week two. Not because it’s hard, because it’s boring, and boring is the thing my brain refuses to do twice.
Worth saying up front: I built this by describing what I wanted rather than by designing it. I said what kept going wrong, Claude proposed a shape, and we changed it as it broke. That’s how most of what I build starts, and the version in your head where you have to understand the whole thing before you begin is the version that stops you.
What is Claude Code memory?
It’s a folder of markdown files that get read in before you type anything. One index file loads automatically at the start of every session, and that part is built in. Everything after that, which files exist, what goes in them, and how they connect, is a system you build.
The confusion worth clearing up is that this is not your CLAUDE.md. They do different jobs:
| CLAUDE.md | Memory files | |
|---|---|---|
| What it holds | How this project works: structure, commands, conventions | What you’ve decided, corrected and learned |
| Who it’s about | The code | You |
| Where it lives | In the repo, next to the project | In your own Claude folder, outside the repo |
| Who else sees it | Anyone with the repo | Nobody |
| How it grows | You edit it when the project changes | It builds up as you work |
I run both and they barely overlap. My CLAUDE.md says which Python to use and where my workflows live. My memory holds the fact that nothing gets published without me seeing it first, which is not a fact about a codebase.
Who needs a memory system like this?
You want one if you work with an agent most days and keep correcting the same things. The tell is repetition. If you’ve explained your voice, your stack, or your one hard rule more than three times, that’s a memory file you haven’t written yet.
It’s overkill for a lot of people:
- You use Claude Code now and then. A good CLAUDE.md in the project covers you, and a memory system on top is maintenance you’ll resent.
- Your work doesn’t carry preferences. If nothing about the job depends on how you like things done, there’s nothing to remember.
- You want it to remember conversations. This holds decisions and rules, not what was said. Treating it like a diary is how you end up with 400 files nobody reads.
What goes in Claude Code memory, and what doesn’t?
One fact per file, and the file is named after the fact. Mine sort into four kinds, and the split says something about what this is really for:
| Kind | How many | What it holds |
|---|---|---|
| Feedback | 148 | Corrections I’ve given, and why |
| Project | 129 | State of ongoing work the code doesn’t record |
| Reference | 119 | Pointers to real things: dashboards, IDs, gotchas |
| Who I am | 1 | How I work, what I’m bad at, what to lead with |
That feedback number is the honest one. The biggest part of what my agent knows about me is a record of things it got wrong, written down so it stops doing them. Not a personality profile. A list of corrections.
One of mine says not to describe me as a mom, because I’m not one. It exists because a draft cover letter came back describing me as an ordinary mom in Illinois, I said no, and instead of just fixing that sentence we wrote the rule down. That’s the whole pattern, and it’s smaller than people expect. A correction becomes a file, and the file is why it doesn’t come back.
What stays out matters as much:
- Anything the repo already says. Code structure, past fixes, commit history. If it’s discoverable, remembering it is duplication that goes stale.
- Anything true only today. A note saying “waiting on the deploy” is garbage by tomorrow. Dates go in as real dates, never as “last week”.
- Secrets. Keys and tokens live in an env file. A memory file is plain text you’ll forget you wrote.
How do you keep it from eating your context?
This is the part that decides whether the system works, and it’s where mine went wrong first. The auto-loaded index is the only thing you pay for on every single session, so it has a hard size limit and it isn’t allowed to hold detail. Its job is routing: one line per topic saying what exists and which file to open.
Mine is capped at 17.1 kilobytes. Underneath it sit four topic files, one for blog work, one for apps, one for workflows, one for everything parked. None of them load on their own. When I start a post, the index says to open the blog one, and only then does it come in. The other three never enter the session at all.
The numbers are the argument. The full folder is 3.9 megabytes across 475 files. The part that loads every time is 17 kilobytes, under half a percent of it. Without the routing split I’d either carry all of it, which nothing can do, or carry a summary so thin it’s useless.
The cap needs teeth, because the index grows every time I learn something. Mine is enforced by a small script that runs after any write to that file and refuses to let it sit over the limit. It exists because the index crept past the budget twice on its own, and a rule that only lives in a document is a rule that gets skipped at eleven at night.
Get the generator
The generator writes your starting version, which is the part that’s easy to stall on. A blank folder gives you no clue what belongs in it.
You answer what you work on, what you keep having to repeat, and how strict you want to be about size. It gives you your index with the routing laid out, the topic files it points at, and a skill or prompt that saves new memories in the right shape as you go, so the thing grows without you maintaining it by hand.
Change two things in what it gives you: your own topics, and your cap. Set the cap smaller than feels right. It’s the only thing standing between this and a file that eats your session.
What it doesn’t do
There’s no automatic recall. If a fact isn’t named in the index, it doesn’t get found, and a file nothing points at is the same as a file that doesn’t exist. I tested that, and it’s the most important thing to understand here, because writing the memory feels like the work and indexing it is the work.
It can be confidently wrong. A file reflects what was true when it was written. If a tool changed, or I changed my mind out loud and never wrote it down, the file still says the old thing and gets read as current. Anything naming a file, a flag or a price gets checked against reality before it’s used, and that rule exists because I got burned in exactly that way.
Mine kept creeping over that limit. Every new memory added a line to the index, so it grew back every week no matter how much I trimmed. Trimming wasn’t the fix. What worked was routing: the index holds pointers now, and the detail lives in the topic files it points at. It’s sitting at 8.5 kilobytes today, about half the cap.
And it doesn’t remember conversations. It holds decisions and rules. If what you want is the thread of a discussion you had last Thursday, this won’t give you that.
Frequently asked questions
Does Claude Code remember previous sessions?
Not on its own. Each session starts fresh apart from the files it loads at the beginning, so anything you want carried across has to be written down where it will read it. That’s all a memory system is: the part you decided to write down.
What is the difference between CLAUDE.md and memory files?
CLAUDE.md describes the project and lives in the repo, so anyone working on that code gets it. Memory files describe you and your decisions, live outside the repo, and stay private. If the fact would still be true for a stranger working on the same code, it belongs in CLAUDE.md.
Where do Claude Code memory files live?
In your own Claude folder rather than inside the project, which is why they survive switching between repos. The exact path depends on your setup, and what matters more than the location is that one index file is the entry point and everything else hangs off it.
How big should the memory index be?
Small enough that you’d be happy paying for it on every session, because you are. Mine is capped at 17.1 kilobytes against a folder of 3.9 megabytes. Pick a number, enforce it with something automatic, and push the detail down into files the index points at.
What should you put in Claude Code memory first?
The thing you’ve explained most often. For me that was how I write, because I was pasting the same list of don’ts into every session. Write that one file, use it for a week, and let the next one come from the next thing you repeat.
Will a memory system slow Claude down?
Only if you let the auto-loaded part grow. Anything loaded at the start of a session is context you spend before any work happens, which is the whole argument for routing instead of one big file. Mine loads under half a percent of the folder on a normal session.
Try it yourself
Write down the last three things you had to tell your agent twice. That’s your first memory file, and it’s usually a rule about how you want things done rather than a fact about your code.
Then write the index above it: one line per topic, saying what exists and where to look. If you never build more than that, you’ve got most of the value, because the repetition that wears you down is a short list and it’s the same list every week.
The generator in this post writes both, shaped around what you actually work on. Set a size limit while you’re in there. The version of this that fails isn’t the one that’s too small, it’s the one that grew until every session opened with a wall of your own notes.
A tool I built
Emergency Fund Aquarium
Log what you save at your own bank and watch your tank fill with creatures. Your money never moves through the app.
Start your tank →I run an affiliate program on the tools I build. Approved affiliates earn 20% on what their referrals pay, for up to a year. US only for now. See the program →
Related reading
- The Claude Code To-Do List That Works Before I Do
- My Claude Code Setup: VS Code and a Mess of Folders
- What a Claude Code Skill Is, and How to Make One
- How I Update Old Blog Posts Without Remembering To
Subscribe if you haven’t already, and go forth and automate the boring stuff.
