Claude Code Memory: How It Works and the Best Tools
How CLAUDE.md and auto memory carry knowledge between sessions, where they stop, and which add-on tools fill the gaps.
Claude Code starts every session with an empty context window, so anything it should remember has to be written to disk. That's the whole memory system: CLAUDE.md files you write, and auto memory Claude writes for itself, both plain Markdown loaded at startup.
It works well inside one repository. Auto memory doesn't sync across machines, other AI tools don't read either file, and both only know what happened in the terminal. Below: how the built-in memory works, then four tools people add on top.
How does Claude Code memory work?
Claude Code memory works through two complementary systems that load at the start of every conversation, per Anthropic's Claude Code docs:
| CLAUDE.md files | Auto memory | |
|---|---|---|
| Who writes it | You | Claude |
| What it holds | Instructions and rules | Learnings and patterns |
| Scope | Organization, user, project or local | One git repository, shared across worktrees |
| What loads | Every session | The first 200 lines or 25KB of MEMORY.md |
Claude treats both as context, not enforced configuration, so a rule that must hold every time belongs in a hook, which runs as a shell command whatever Claude decides.
What are the CLAUDE.md memory levels?
CLAUDE.md comes in four levels, loaded broadest first and concatenated rather than overridden: a managed policy file your organization deploys, ~/.claude/CLAUDE.md for you across every project, ./CLAUDE.md for the team, and a git-ignored ./CLAUDE.local.md for your private notes on one project.
Two mechanisms extend it. @path/to/file imports pull other files in, up to four hops deep, and Claude Code asks for approval the first time a project imports a file from outside the repo. Rules in .claude/rules/ with a paths: field load only when Claude touches matching files. Every location, with a full example file, is in CLAUDE.md: what it is, best practices and examples.
What does Claude Code's auto memory save, and where?
Auto memory saves four kinds of notes, recorded as a type field in each memory file:
user: your role, expertise and working preferencesfeedback: corrections you give and approaches you confirmproject: ongoing work, deadlines and decisions Claude can't see in the codereference: where outside information lives, such as an issue tracker
Claude skips anything it can derive from the codebase or that CLAUDE.md already says. The notes live in the memory directory ~/.claude/projects/<project>/memory/: a MEMORY.md index with one line per memory, plus one topic file per memory. Only the index loads at startup, and anything past its 200-line or 25KB limit is dropped, so Claude Code tells Claude to shorten it as it nears the cap. Topic files are read on demand.
Auto memory is on by default in local sessions; set "autoMemoryEnabled": false in a project's settings to turn it off there, or CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 to turn it off everywhere. How it fits with /init and @ references is in how to give Claude Code context.
How do you see and edit what Claude Code remembers?
Run /memory. It lists every CLAUDE.md, CLAUDE.local.md and memory location, toggles auto memory, and opens the auto memory folder, where every note is a Markdown file you can edit or delete. /context shows which files actually loaded this session.
What you say decides where a memory goes: "remember that the API tests need a local Redis" goes to auto memory, while "add this to CLAUDE.md" writes to the file your team shares. After /compact, the project-root CLAUDE.md is re-read from disk, but an instruction you only gave in chat survives only inside the summary. On v2.1.283 or later, /doctor prompt-audit finds outdated or conflicting lines; the habits that keep files current are in how to keep your CLAUDE.md from going stale.
Where does Claude Code's memory fall short?
It falls short at every boundary: machine, repository, tool and source.
- One machine. Auto memory isn't shared across machines or cloud sessions.
- One repository. Each repo gets its own memory directory, so what Claude learned about you in one project starts over in the next.
- One tool. Cursor, Codex and ChatGPT can't read it.
- One source. The decision from Tuesday's call, the Linear ticket, the client's email: none of it gets in unless you type it.
- No search. Claude finds old notes by reading files, so recall depends on the
MEMORY.mdindex staying short and accurate.
A hand-written file doesn't fix the source problem. In an August 2026 Unabyss benchmark of 20 tasks run 60 times in Claude Code, a hand-written CLAUDE.md reduced follow-ups but barely moved cost, time or quality, while structured context from Unabyss cut cost by 36% and time by 38% and raised output quality from 7.7 to 8.9 out of 10 (What Structured AI Context Is Worth).
What is claude-mem?
claude-mem is an open-source Claude Code plugin that records your sessions automatically and makes them searchable in later ones. Its README calls it a "persistent memory compression system built for Claude Code": Claude Code hooks capture tool usage observations, a model generates semantic summaries, and the next session starts with that context injected.
- Install:
npx claude-mem install, or/plugin marketplace add thedotmack/claude-meminside Claude Code. - Storage: a local SQLite database at
~/.claude-mem/claude-mem.db(claude-mem docs), plus a Chroma database for vector search. - Recall: MCP search tools (
search,timeline,get_observations) that return a compact index first and full details only for the results Claude picks.
It's the most-starred tool here, with about 101,900 GitHub stars when checked in October 2026, and it also installs into OpenCode, OpenClaw and Codex (through T3 Code). Use it when you want a full history of what Claude did, not just the facts it chose to save.
Is claude-mem free and safe to use?
The claude-mem engine is free and open source under Apache-2.0, and CMEM Pro, which adds a hosted observer, cloud sync and MCP recall from other clients, costs $30/month after a 30-day trial (cmem.ai pricing, checked October 2026).
On safety, your data sits on your machine by default, and <private> tags keep content out of storage. The summaries, though, are written by a model you choose (your Anthropic plan, your own OpenRouter or Gemini key, or claude-mem's hosted observer), so your tool calls go there, and cloud sync stores synced data with CMEM. The plugin runs hooks on every session event, so install it from the official repo and check what it registers.
What other memory tools work with Claude Code?
Three more are worth a look, and they differ mainly in where the memory lives.
Mem0
Mem0 integrates through a Claude Code plugin that needs a Mem0 Platform API key (Mem0 docs). Hooks send your messages, Claude's answers and changed files to Mem0 in batches, which splits what it extracts into shared project memory and personal memory, and a new session's first prompt gets up to five memories injected. The memories live in Mem0's cloud, so its hosted MCP server can serve them to Cursor and Claude Desktop too. Its older local server, OpenMemory, no longer appears in Mem0's docs or main repository, and openmemory.dev now redirects to mem0.ai.
Basic Memory
Basic Memory stores notes as plain Markdown files on your disk, linked into a knowledge graph, and serves them over MCP (Basic Memory). Add it with claude mcp add basic-memory -- uvx --prerelease=allow basic-memory mcp; an optional Claude Code plugin adds session-start briefings and pre-compaction checkpoints. It's the closest to Claude Code's own model, files you can read, but shared across Claude Desktop, Codex, Cursor and Obsidian.
Unabyss
Unabyss is a personal context layer: instead of waiting for you to correct Claude, it builds your context from 26 apps, including Gmail, Google Calendar, Slack, Notion, GitHub and Linear, keeps it current, and serves it over MCP to Claude Code, Cursor, ChatGPT and Codex. Connecting Claude Code takes one command: claude mcp add --transport http unabyss https://mcp.unabyss.com/.
How do the Claude Code memory tools compare?
They split by what they remember: what you write, what Claude did, or what's in your work apps. Prices were checked on each vendor's pricing page in October 2026.
| Tool | What it remembers | Where it lives | Read by other AI tools | Price |
|---|---|---|---|---|
| Built-in (CLAUDE.md + auto memory) | Instructions you write, notes Claude saves | Markdown on your machine | No | Included in Claude Code |
| claude-mem | Compressed record of every session | SQLite and Chroma on your machine, optional cloud sync | Partly: other coding agents, plus MCP recall on CMEM Pro | Free; CMEM Pro $30/mo |
| Mem0 | Facts extracted from your sessions | Mem0's cloud | Yes, over MCP | Free (10,000 adds/mo); Starter 249/mo |
| Basic Memory | Notes you and Claude write, linked as a graph | Markdown on your disk, optional cloud | Yes, over MCP | Free locally; cloud from $15/seat/mo |
| Unabyss | Your context from 26 work apps | Hosted, encrypted at rest and in transit | Yes: Claude, ChatGPT, Cursor, Codex over MCP | 7-day free trial; Pro 89/mo |
For memory servers you can plug into claude.ai and Claude Desktop as well, see the best memory MCP servers for Claude.
Where is another tool the better choice than Unabyss?
Unabyss is the wrong pick in four cases.
- You work in one repo on one machine. The built-in memory is free and already on. Keep
CLAUDE.mdshort and let auto memory collect your corrections. - You want to search what Claude did three weeks ago. claude-mem keeps the full session history; Unabyss doesn't record your terminal.
- You want everything local, in files you can grep. Basic Memory, or claude-mem without cloud sync.
- You're building memory into your own agent. Mem0 is an API for that; Unabyss is for the person using the tools.
Unabyss is the better choice when what Claude Code is missing lives outside the repo, in your inbox, tickets and meetings, and the same context should reach Cursor and ChatGPT too. To run Claude Code and Cursor on one context, see Claude Code and Cursor shared context.
→ Connect your apps to Unabyss and give Claude Code your context
