Claude Code Memory: How Persistent Context Works

Claude Code forgets everything the moment a session ends. Close the terminal, come back tomorrow, and it has no idea which build command you use, why you picked one library over another, or that the staging database is read-only. You end up re-explaining the same context every single day. That is the problem "memory" is supposed to solve, and Claude Code has a real, file-based system for it that most people never configure past the defaults.

This guide covers exactly how Claude Code memory works: where the files live, how the /memory and # shortcuts behave, how imports and precedence resolve, and where the built-in system hits a ceiling. Then it shows how to layer persistent, self-updating context on top over MCP so the memory reflects your real work instead of a snapshot you wrote once and forgot.

Key takeaways

• Claude Code memory is plain Markdown. It lives in CLAUDE.md files that get loaded into context at the start of every session, not in a hidden database.
• There are three tiers: enterprise, project (./CLAUDE.md, shared with your team), and user (~/.claude/CLAUDE.md, personal and global across all projects).
• The # shortcut appends a quick memory mid-session; the /memory command opens the files in your editor for real edits.
• Files can pull in other files with @path/to/file imports, so you can keep memory modular instead of one giant file.
• The catch: CLAUDE.md is static. It says whatever you last typed, so it drifts out of date the moment your stack, pricing, or decisions change.
• To keep persistent context current without hand-editing, connect a memory layer over MCP that updates itself and serves facts to Claude Code on demand.

---

What "memory" actually means in Claude Code

There are two different things people mean when they say Claude Code memory, and mixing them up causes most of the confusion.

The first is conversation context: everything inside the current session. Claude Code holds the files it has read, the commands it has run, and what you have said so far in its context window. That is powerful but temporary. It is gone when the session ends or gets compacted.

The second is persistent memory: instructions and facts that survive across sessions. This is the CLAUDE.md system. These files are read automatically at launch and injected into context before you type anything, so Claude Code starts every session already knowing your conventions. When people ask about "claude code persistent memory," this is the part that matters, because it is the only part that carries over.

The important mental model: CLAUDE.md is not a chat log Claude Code writes to on its own. It is a set of instruction files you own. The tool reads them; by default it only writes to them when you explicitly ask.

The three memory tiers and where the files live

Claude Code loads memory from a hierarchy of files. Higher-priority files win when instructions conflict, and everything gets combined into the context.

Two of these do the heavy lifting.

./CLAUDE.md at the project root is the one you commit to the repo. It travels with the codebase, so every teammate and every fresh clone gets the same instructions. This is where the "run npm run build, not npm build" kind of knowledge belongs.

~/.claude/CLAUDE.md in your home directory is personal and applies to every project you touch. Preferences like "always use absolute paths" or "be concise" live here.

Claude Code also walks up the directory tree. If you launch it deep inside a monorepo, it will pick up CLAUDE.md files from parent directories on the way to the repo root, which lets a large repo layer general rules at the top and specific rules in subfolders.

Writing to memory: the # shortcut and /memory command

You have two fast paths to edit memory, and they serve different purposes.

The # shortcut is for capturing something on the fly. Start any message with # and Claude Code treats it as a memory to save, then asks which file to put it in. It is the quickest way to record a fact the moment you notice it.

# the API base URL for staging is api-staging.internal, not the prod one

The /memory command is for deliberate editing. Run it and Claude Code opens your memory files in your configured editor so you can restructure, delete stale lines, and organize sections properly. Use this when you want to clean up rather than append.

There is also the bootstrap step: running /init in a new project asks Claude Code to scan the codebase and generate a starter CLAUDE.md for you. It is a decent first draft, but treat it as a starting point, not the finished article. It captures structure, not the hard-won reasons behind your decisions.

Import syntax: keeping memory modular

A single CLAUDE.md file gets unwieldy fast. Claude Code supports imports so you can split memory into focused files and pull them in.

Use the @ prefix with a path:

See @docs/architecture.md for the service layout and @docs/testing.md for how we run tests. @~/.claude/my-personal-defaults.md

Imports work with both relative and absolute paths, including your home directory. They can nest a few levels deep, which lets you keep one lean top-level CLAUDE.md that composes several specialized files. One practical guard: imports are not evaluated inside code spans or code blocks, so a path written as literal code will not accidentally trigger a file load.

This is how you keep memory readable. A short root file that imports architecture notes, testing conventions, and your personal defaults beats a 400-line wall of text that nobody rereads.

The honest limit: static files go stale

Here is where the built-in system runs out of road, and it is worth being blunt about it because it is the single biggest reason "AI memory" disappoints people.

CLAUDE.md is a snapshot. It contains exactly what you last typed into it, frozen in time. The day you write "we use Redux for state," it is accurate. Three months later you have migrated to Zustand, nobody updated the file, and now Claude Code confidently reaches for Redux on every new component. The memory did not just stop helping. It started actively misleading the tool.

This is the maintenance tax on every static memory system, and it is not unique to Claude Code. The same failure hits Obsidian vaults, Notion workspaces, and NotebookLM notebooks the moment the underlying facts change. The context is only as current as the last time a human remembered to update it by hand. For a solo project you can stay on top of it. Across several repos, a moving stack, and shifting decisions, keeping every CLAUDE.md accurate becomes a job you will not do.

The problem is not that Claude Code memory is badly designed. It is that a plain file cannot know when the fact inside it has changed. That is a job for a system that watches your real work and revises itself, which is a different layer than a text file.

Adding self-updating memory over MCP

Claude Code can pull context from external tools through MCP, the Model Context Protocol. This is the door for persistent memory that maintains itself instead of waiting for you to hand-edit a file.

The pattern is straightforward. Instead of hard-coding facts into CLAUDE.md, you connect a memory server over MCP. Claude Code then calls that server's tools when it needs context, and the server returns the current, distilled version of what you know. Your CLAUDE.md shrinks to a short pointer that tells Claude Code the memory layer exists and when to query it. The facts themselves live in a system built to keep them accurate.

Locul is built for exactly this layer. It is a local-first desktop app that builds a searchable second brain from what you already produce, then serves it to Claude Code and other AI tools over MCP. A few things make it fit the "claude code memory mcp" gap specifically:

• It updates itself. When a fact changes, the old version is marked superseded and the new one takes over, with the history preserved. This is the mechanism that keeps memory current, so your context reflects the Zustand migration without you touching a file. That is the living memory that actually lasts rather than a snapshot.
• It builds passively. Memory comes from local Markdown files, PDFs, dictation, Notion, and your work, so there is no capture habit, tagging, or weekly review to keep up.
• It is local-first. Everything stays on your machine by default, and it works with local models through Ollama, so your context is not shipped to a cloud you did not choose.
• It exposes real MCP tools Claude Code can call, including search_notes, recall_memories, get_entity_profile, and get_brain_index, all gated by an access policy you set (blocked words, private folders, per-tool toggles).

The distinction that matters: CLAUDE.md tells Claude Code the rules. A memory layer over MCP tells it the current facts about you, your people, and your projects, and keeps those facts honest as they change. You can also package a set of those facts as an installable Memory Pack to share a domain's context.

A practical setup that stays current

Here is a division of labor that works. Keep the stable, structural stuff in CLAUDE.md, where it belongs, and push the volatile stuff to a memory layer that updates itself.

• In ./CLAUDE.md: build and test commands, directory layout, code style, hard rules that rarely change. Commit it so the team shares it.
• In ~/.claude/CLAUDE.md: your personal defaults across projects. A one-line pointer to your MCP memory server and when to query it.
• In the memory layer over MCP: decisions and their reasoning, current pricing, who owns what, live opinions, anything that changes. This is the part that would rot if it lived in a static file.

That split gives you the fast, always-loaded instructions of CLAUDE.md plus a persistent context source that does not silently go out of date. The static file handles "how we work here." The living layer handles "what is true right now."

Frequently asked questions

Where is Claude Code memory stored?

In plain Markdown files. Project memory is ./CLAUDE.md in your repo root, and user memory is ~/.claude/CLAUDE.md in your home directory. Claude Code also reads CLAUDE.md files in parent directories on the way to the repo root. There is no hidden database. You can open, edit, and version-control every memory file directly.

Does Claude Code remember between sessions automatically?

Only what you put in a CLAUDE.md file. The conversation itself is not saved across sessions; when a session ends, that context is gone. Persistent memory comes from the CLAUDE.md files that get loaded at launch, or from an external source you connect over MCP. Claude Code does not auto-write your chat history into long-term memory on its own.

What is the difference between CLAUDE.md and MCP memory?

CLAUDE.md is a static instruction file you edit by hand; it says whatever you last typed. MCP memory is a live source Claude Code queries at runtime, so it can return current facts and update itself as things change. Files are great for stable rules. An MCP memory layer is better for facts that go stale, because a plain file cannot know when its own contents are outdated.

How do I stop my CLAUDE.md from going out of date?

Move the volatile facts out of it. Keep stable rules (build commands, structure, code style) in CLAUDE.md, and put anything that changes (decisions, pricing, ownership, opinions) into a memory system that revises itself, connected over MCP. That way the static file only holds things that rarely move, so it stays accurate on its own.

Can Claude Code memory work with local models?

The CLAUDE.md files themselves are just text and work regardless of model. For the external memory layer, Locul is local-first and supports local embeddings through Ollama, so you can keep your persistent context and its indexing entirely on your own machine rather than sending it to a cloud provider.

How many CLAUDE.md files should I have?

As many as keeps things readable. A common setup is one committed ./CLAUDE.md per repo, one personal ~/.claude/CLAUDE.md, and additional focused files (architecture, testing) pulled in with @ imports. Splitting by concern beats a single long file, because you and your team are more likely to keep short, focused files current.

---

Claude Code memory gives you the file layer: solid, transparent, version-controlled instructions that load on every session. The gap it leaves is currency, because a static file cannot update itself. If you want persistent context that reflects your real, current work instead of a snapshot you have to babysit, Locul builds that second brain from what you already do, keeps it current as facts change, and serves it to Claude Code over MCP. It is free to start with 500 memories and local AI, no credit card. Point your CLAUDE.md at it once and stop re-explaining yourself.