claude-mem: How the Claude Code Memory Plugin Works
claude-mem is a persistent memory plugin for Claude Code. Its GitHub repository had 113,406 stars when we checked on November 5, 2026, and version 15.9.0 shipped on November 2. Write-ups disagree on basics such as where it keeps your data, so everything below comes from the project's own docs and code. It covers what claude-mem records, which model compresses it and who pays for that model. It also shows what loads into a new session and where the data lives. We build memU, a different take on the same problem, so the comparison at the end sticks to facts stated here.
What is claude-mem, in one sentence?
claude-mem is an open-source Claude Code plugin that records an agent's work through hooks, has a second model compress it into notes, and loads recent notes into the next session.
Alex Newman (thedotmack on GitHub) started the repository on August 31, 2025. The README still describes it as a memory compression system "built for Claude Code." Its installer now sets it up for 19 agent hosts, and the code is under Apache-2.0. Do not mix it up with claudemem, an unrelated Go CLI with a similar name.
How does claude-mem differ from Claude Code's built-in memory?
Claude Code already has auto memory. The two work at different layers, and you can run both.
| Claude Code auto memory | claude-mem | |
|---|---|---|
| Who writes it | Claude, during the session | A separate observer model, from hook events |
| What it records | Notes Claude decides to keep | Every tool call and your prompts |
| Where it lives | MEMORY.md plus topic files per project | A SQLite database plus a Chroma vector index |
| What loads at start | The first 200 lines or 25KB of MEMORY.md | Recent observations for the project, 50 by default |
| How you look at it | Edit the Markdown or use /memory | A local web viewer and search tools |
| Extra model cost | None beyond the session | Observer calls: a hosted trial, your Claude plan or your own key |
Claude Code facts come from Anthropic's memory docs. The claude-mem column uses its getting started guide and database docs. Defaults are from the configuration reference.
What does claude-mem capture?
claude-mem registers hooks on six Claude Code events, per its architecture overview. At session start it launches a local worker and injects context. Each prompt you submit is saved. After every tool call, a PostToolUse hook queues the event, so each file edit or shell command becomes raw material. Before a file read, it adds that file's history. Stop writes a summary of the turn, and SessionEnd marks the session complete.
Claude's own replies are not stored as observations, the private tags page notes.
Each tool event becomes an observation: a title and narrative, a list of facts, and the files touched. It also gets a type such as decision or bugfix. The Stop summary records what you asked for and what Claude learned. It also lists what is done and what comes next.
Which model compresses the memory, and who pays?
A background worker, run by Bun on your machine, sends queued tool events to an "observer" model. That model writes the observations. Which model it is depends on how you installed.
The settings file defaults use the Claude provider with the haiku alias, which follows the newest Haiku. It runs on your Claude Code login. The install guide says that option "shares your Claude plan usage."
The interactive installer asks you to sign in through the browser, with no card. It then pre-selects CMEM Pro, the project's hosted observer, which runs off your plan with a 30-day free trial. When the hosted gateway stops serving your account, memory falls back to your Anthropic plan unless you subscribe. You can also bring your own key for OpenRouter or Gemini. A Codex subscription login and any OpenAI-compatible endpoint work too. An install run by an agent, with no terminal to answer prompts, defaults to your Anthropic plan.
On your own plan, the project adds a quota guard. With subscription login, the observer stops when a usage window reaches its threshold, 95% of the five-hour window by default. Queued work then waits or moves to a fallback provider you configure. That leaves the rest of the window for your own sessions.
Where does claude-mem store memory: JSONL, SQLite or Chroma?
claude-mem keeps its notes in SQLite and reads JSONL transcripts as input. The store is a SQLite database at ~/.claude-mem/claude-mem.db with full-text search. A Chroma vector index sits beside it for semantic search. The docs call Chroma optional, and the code turns it on by default, with a switch for SQLite-only search.
Claude Code writes each session transcript as a JSONL file, and claude-mem's summary hook reads it. The database docs say those transcripts "remain the spine for session history," and the tables hold claude-mem's own notes and indexes.
Everything stays on your machine unless you turn on Cloud Sync, a cmem.ai Pro feature. It uploads your observations and summaries, plus the prompts you typed, so other devices can pull them.
What does claude-mem inject when a session starts?
At SessionStart, claude-mem queries the recent observations for the current project, 50 by default. It shows them as a timeline with session markers, along with summaries from the last 10 sessions. The newest summary appears in full only when nothing new was captured after it.
The injected block is an index. Each item shows a title, a type and its token count. The project's progressive disclosure page estimates about 800 tokens for an index of 50 observations. Claude then fetches details on demand through the project's search tools. The README puts an index row at 50 to 100 tokens and a full observation at 500 to 1,000. It claims about 10x token savings from filtering first.
Two settings change the default. Per-prompt injection adds the 5 best matches to each prompt, and it is off by default. Startup context covers only the current host unless you allow every source, which matters if you run Claude Code and Codex side by side.
What privacy controls does claude-mem have?
Wrap text in <private> tags and claude-mem strips it before anything is stored. Claude still sees it during the session. Regex redaction of API keys and other secrets also exists, but it is opt-in, so turn it on if your tool output prints credentials. Screenshot capture is off by default.
Anonymous usage analytics through PostHog are on by default, per the telemetry page. The installer asks once. You can turn them off later with npx claude-mem telemetry disable or the DO_NOT_TRACK variable.
Which agents does claude-mem support, and how do you install it?
The installer's host list has 19 entries: Claude Code, Codex CLI, Cursor, Windsurf, OpenCode, OpenClaw, Copilot CLI, Hermes Agent, Devin, Antigravity, T3 Code, Kimi Code, Grok Bot, OMP, Pi, DeepSeek Harness, Goose, Roo Code and Warp. The depth varies. Claude Code is marked recommended. Four of them, Copilot CLI among them, connect through MCP search tools only. Gemini appears as an observer provider, and Gemini CLI is not in the list. Devin arrived in 15.9.0.
Install from a terminal:
npx claude-mem install
Or install from the plugin marketplace inside Claude Code:
/plugin marketplace add thedotmack/claude-mem
/plugin install claude-mem
You need Node.js 20 or later and Claude Code 2.1.139 or later. The installer adds Bun and uv if they are missing. A plain global npm install gives you the SDK only, without the hooks. After a restart, a web viewer on a local port shows the memory stream and settings.
What should you read in the fine print?
The open core is under Apache-2.0, including the memory engine and the host adapters. The project's license notes reserve hosted cloud and team sync as commercial areas. In practice, local memory is free to run. The hosted observer and Cloud Sync are paid cmem.ai services, as is the TeamBrain team workspace.
Every token figure in this post is the project's own estimate, and we found no independent test of them. The docs also include a token benchmark for its code-navigation tools, run by the project on its own codebase. We found no published test of how much the memory improves an agent's work. Telemetry is on by default, as noted above.
The release pace is fast. Five releases landed between November 1 and 2, 2026. Settings and defaults in this post may move, so check the configuration reference before you rely on one.
The bottom line
If you work mostly in Claude Code and want a full record of what the agent did, claude-mem is a strong choice. It records every tool call, where built-in auto memory keeps only the notes Claude chooses. It also stays on your machine by default and installs with one command. Decide up front who runs the observer, because that choice sets your cost. Turn on auto-redaction if secrets ever show up in tool output.
How do you keep claude-mem's memory across machines and agents?
Say you spend Monday on a desktop, and claude-mem records how your deploy script works. On Tuesday you open a laptop. Its ~/.claude-mem database starts empty. Cloud Sync, a paid cmem.ai Pro feature, is the built-in way to carry Monday's notes over.
The core difference: claude-mem has a separate observer model record every tool call live into a local database. memU has the agent you already use distill its session logs into Markdown memory that syncs across machines.
| claude-mem | memU | |
|---|---|---|
| Who writes the memory | A separate observer model, on a hosted trial, your plan or your own key | The host agent itself, on its own model usage. memU's service makes no LLM calls |
| When it records | Live, on every tool call through hooks | A scheduled background task slices new session logs into jobs the agent distills |
| What you can open | Structured notes (title, narrative, facts, files), in a local web viewer and through search tools | Readable Markdown memory and skill files |
| Where data lives | Your machine, unless you turn on Cloud Sync | memu.so when hosted, or your own machine when self-hosted |
| Across devices | One local database. Cloud Sync is a paid cmem.ai Pro feature | Hosted on memu.so, free and cross-device |
| Across hosts | One local database for 19 installer targets. Startup context is per host by default, and one setting includes all | One memory shared by Codex, Claude Code, Cursor, OpenClaw, Hermes Agent and more |
claude-mem is the right pick if you work mostly in Claude Code and want every tool call captured live and searchable on your own machine. Teams can add the TeamBrain workspace. memU fits when you want your own agent to write memory as readable Markdown. Hosted sync across machines is free, and the agent also distills reusable skills from your history.
To try memU hosted, get an API key from memu.so and send your agent one message:
Read https://memu.pro/SKILL.md, follow its instructions to install and configure memU, API Key is
YOUR_MEMU_API_KEY.
The self-hosted setup and the per-host support matrix are in the memU GitHub repository. For a wider survey, see our AI agent memory frameworks guide. Our guide to sharing memory between Claude Code and Codex covers instruction files. The Claude Code hooks post shows how hooks put context back into a session. More on the design is at memu.pro.
FAQ
Is claude-mem free?
The plugin is free and open source under Apache-2.0. The observer model still costs something. CMEM Pro has a 30-day trial and then a subscription. Otherwise it uses your Claude plan or a key you supply.
Does claude-mem use my Claude subscription?
It does if you pick the Anthropic plan, if the hosted trial ends without a subscription, or if an agent ran the install. The observer then defaults to Haiku and stops near your usage limits.
Where is claude-mem data stored?
In a SQLite database at ~/.claude-mem/claude-mem.db, with a Chroma vector index beside it. Claude Code's JSONL transcripts are an input it reads.
Does claude-mem work with Codex and Cursor?
Yes. Its installer sets up Codex CLI and Cursor among 19 hosts. Startup context includes only the current host unless you enable the setting that includes all sources.
How do I stop claude-mem from saving secrets?
Wrap sensitive text in private tags, which are stripped before storage. Also turn on auto-redaction, which is off by default and replaces common key patterns before they are saved.