Claude-Mem: memory across Claude Code sessions
Claude-Mem is a Claude Code plugin by Alex Newman that watches each session through hooks, has a model compress what happened into short observations, stores them in a local database and injects the relevant ones when a new session starts.
npx claude-mem installClaude Code doesn't remember yesterday. It starts every session with an empty context, apart from your CLAUDE.md files. Claude-Mem fills the gap automatically. Its hooks capture what Claude does while it works, a model turns that into short "observations" (a bug fixed, a decision made, a file explained), and the next session opens with the observations that matter for the project. It's open source under Apache 2.0 and one of the most-starred Claude Code plugins on GitHub. For the basics of skills and plugins, see Claude Code skills.
How it works
The README lists these parts:
- Lifecycle hooks on session start, each prompt, each tool call, stop and session end. They collect what happened.
- A worker service, a local HTTP API run with Bun, with a web viewer that shows the memory stream as it is written.
- A SQLite database for sessions, observations and summaries, plus a Chroma vector database for search by meaning as well as keywords.
- A mem-search skill and four MCP tools, so Claude can look up past work on its own.
Search runs in three layers to save tokens: search returns a compact index (roughly 50 to 100 tokens per result), timeline shows what happened around a hit, and get_observations fetches full details only for the IDs Claude picks. The README puts the saving at about ten times compared with loading everything.
Which model writes the memory
Turning raw tool calls into observations takes a model, and you choose which. After install the README offers four options:
| Provider | What it means |
|---|---|
| Claude-Mem observer | The project's hosted service. Sign in by email; a 30-day free trial, then a subscription. It does not use your Claude plan's limits. |
| Your Anthropic plan | The summaries count against your own Claude usage. This is where the trial falls back if you don't subscribe. |
| Your OpenRouter key | Pay per use through OpenRouter. |
| Your Gemini key | Pay per use through Google. |
Whichever you pick, that provider sees the session activity it summarizes. To skip the sign-in step, pass an explicit --provider flag or set CLAUDE_MEM_ONLINE_OPTIN=false. Wrap anything you never want stored in <private> tags.
How to install it
The one-command installer sets up the plugin, hooks and worker:
npx claude-mem installOr from inside Claude Code:
/plugin marketplace add thedotmack/claude-mem
/plugin install claude-memRestart Claude Code afterwards. Skip npm install -g claude-mem. Per the README it installs the library only, and the hooks and worker never get set up. You'll need Node.js 20 or later; Bun and the Python tool uv are installed for you if they're missing, and the same installer covers OpenCode, Codex through T3 Code and several other agents with --ide <name>.
When to use it
- Long projects where you keep re-explaining the same architecture, conventions or old bugs.
- Switching between many repositories in a week.
- Questions like "how did we fix the auth bug last month?", answered from your own history instead of from memory you don't have.
For one task that spans a few sessions, planning-with-files is lighter: three markdown files you can read yourself, no database and no model calls. For stable facts about a project, a well-kept CLAUDE.md still comes first; our Claude Code cheat sheet covers it.
Limits
- It runs several moving parts: hooks, a background worker, two databases. When something breaks, the README suggests describing the problem to Claude so its troubleshoot skill can diagnose it, or running
npm run bug-reportin the plugin folder. - Every summary is a model call, so on your own plan or key memory isn't free.
- The README also promotes a third-party crypto token, CMEM, which its author has endorsed. Nothing in the plugin requires it.
Sources
- thedotmack/claude-mem README — GitHub, accessed October 2026
- Plugins — Claude Code Docs, accessed October 2026