Claude Code memory: what it remembers, what it forgets, and where I keep the rest

If you use Claude Code every day, you’ve probably had the moment where it forgets something you told it last week, then remembers something you’d rather it didn’t. This piece is for you. It explains how Claude Code memory actually works, checked against Anthropic’s own docs on 9 October 2026, what it can’t do, and how I give it one memory across every project and tool I use.

The short version: Claude Code remembers through two sets of files on your machine. You write one (CLAUDE.md). Claude writes the other (auto memory). Both are local, and auto memory is per project. If you want the same memory in every project, on every machine and in other AI tools, you need something outside Claude Code, and the supported way to plug that in is an MCP server.

The day I asked Claude Code what it knew about me

A few weeks ago I asked Claude Code to show me everything it remembers about me. I’d been using it every day for months, piling up rules, skills and corrections, and I’d just assumed it was all working.

It built me a page mapping everything it reads at the start of a session. 236 memory files at the time. It’s 307 now. The index file alone is 137 lines and about 20KB.

The bit that changed how I use it: most of that memory only loads when something I say happens to match it. Anything that has to happen every single time needs to be a rule, not a memory. I’d been relying on memories for things that were really rules, and wondering why they only worked some of the time.

How does Claude Code memory work?

Claude Code starts every session with a fresh context window. Two things carry knowledge from one session to the next, and Anthropic’s docs describe them as “CLAUDE.md files” and “auto memory: notes Claude writes itself based on your corrections and preferences”.

CLAUDE.md files are instructions you write. There are four places they can live:

They don’t override each other. Claude Code reads them all, from the top of your file system down to the folder you’re working in, so the closest one is read last. There’s also a rules folder (~/.claude/rules/ for you, .claude/rules/ for a project) for splitting instructions into separate files. I have seven: writing, working habits, client work and so on.

Auto memory is the notes Claude writes for itself. Say “remember that we deploy on Fridays” and it saves a small file in ~/.claude/projects/<project>/memory/, then adds a line to an index called MEMORY.md. Each memory has a type: user, feedback, project or reference.

What loads every session, and what only loads when it’s needed

Most people get this bit wrong. I did for months.

• Every CLAUDE.md above your working folder loads at launch, in full. Anthropic suggests keeping each one under 200 lines.
• Imports load at launch too. You can pull another file in with @path/to/file, up to four hops deep. It keeps things tidy, but the docs are clear it doesn’t save any context, because the imported file loads straight away as well.
• Only the start of the auto memory index loads: “the first 200 lines of MEMORY.md, or the first 25KB, whichever comes first”. Mine is at about 20KB, so I’m closer to that ceiling than I’d like.
• The memory files themselves load on demand. Claude reads a topic file when the conversation looks like it needs it. That’s why a memory can seem to work one day and not the next.
• CLAUDE.md files in subfolders also load on demand, the first time Claude touches a file in that folder.
• Your project’s CLAUDE.md survives /compact. Claude re-reads it from disk afterwards. Anything you only said in chat doesn’t.

To see what’s loaded, run /memory (it lists every memory file and opens the auto memory folder) or /context.

What Claude Code memory doesn’t do

Once you know where the files live, the limits make sense. They’re also where people get caught out.

It doesn’t follow you between projects. Auto memory is kept per git repository. Something Claude learns in one repo isn’t there when you open another. Only ~/.claude/CLAUDE.md and ~/.claude/rules/ apply everywhere.

It doesn’t follow you between machines. In Anthropic’s words, “auto memory is machine-local … files are not shared across machines or cloud environments”. Your user CLAUDE.md is a local file too. There are several requests on GitHub asking for built-in sync, so you’re not alone if this annoys you.

It isn’t shared with claude.ai or Claude Desktop. The Claude apps have their own memory, and it’s on by default on Free, Pro and Max plans. But Anthropic’s help article on it doesn’t describe any link to Claude Code. So what you tell Claude in a chat on your phone isn’t something Claude Code knows, and the other way round.

Subagents don’t get it. A subagent gets the CLAUDE.md files, but “the main conversation’s auto memory isn’t loaded”. It can have its own memory folder if you set one up.

Claude can still ignore it. The docs say Claude treats memory “as context, not enforced configuration”. If something must happen every time, like a check before a commit, use a hook.

How I set mine up

I’m not a memory purist. I just got fed up of explaining the same things twice. This is what I’ve ended up with after a lot of trial and error.

• Rules for anything that must always happen. My writing rules (UK spelling, no em dashes, sentence case) are in ~/.claude/rules/, so they load in every project at launch. They used to be memories, and they used to get missed.
• Auto memory for what Claude learns about a project. Deploy quirks, which API key lives where, the trap that cost me an afternoon. I let it write these and I prune the index when it gets long.
• ~/.claude in a private git repository. My rules, skills and settings go everywhere I work. I keep memory files out of it on purpose, because they’re specific to a machine and a project.
• A knowledge base for everything else, connected over MCP. That’s the bit that works across tools, and it’s the next section.

How to give Claude Code one memory across projects and tools

The one route Anthropic’s docs support for the same memory reaching every project is an MCP server added at user scope. MCP, the Model Context Protocol, is “an open-source standard for connecting AI applications to external systems”. Claude Code, Claude Desktop, Cursor and plenty of others speak it.

Add a server with --scope user and Claude Code can use it in every project on that machine. Point Claude Desktop or Cursor at the same server and they share it too. Because the memory sits in the server, not in Claude Code’s folders, it’s the same memory wherever you open it.

There are a few kinds of memory server worth knowing about:

• Anthropic’s reference memory server stores a small knowledge graph of people, things and facts in a local file. Good for structured facts, and it’s free and open source.
• Markdown-based servers, such as basic-memory, keep memories as plain notes you can open in Obsidian.
• A knowledge base you already use, connected over MCP. This is what I do, with Ultrathink.

I built Ultrathink because I lose things: links, screenshots, voice notes, the ChatGPT answer I swore I’d come back to. It’s where all of that goes, and AI tidies it up afterwards. Its MCP server gives Claude two tools: save something to my knowledge base, and search it in plain English. So the memory Claude Code uses is the same one I add to from my browser and read myself, rather than a folder of files on one laptop.

Setting it up takes a device key from Ultrathink’s settings and one command. Today the server installs from GitHub:

git clone https://github.com/Fifty-Five-and-Five/ultrathink-mcp
cd ultrathink-mcp && npm install
claude mcp add --scope user ultrathink -e ULTRATHINK_DEVICE_KEY=your-key -- node /full/path/to/ultrathink-mcp/index.js

Then ask Claude Code something like “search my knowledge base for what I saved about pricing pages”. It’s early and a bit nerdy to set up. If you try it, tell me what breaks.

Which memory should hold what?

A rough guide from my own setup:

Claude Code’s memory is good, and it’s getting better quickly. It’s just built for one project on one machine. For everything that spans more than that, put it somewhere every tool can reach.