How to Install Claude Mem for Claude Code: A Step-by-Step Setup Guide
Install Claude Mem for Claude Code the right way: the provider flag, telemetry, redaction, and the privacy settings to check first.
What is Claude Mem and why install it?
Claude Mem is an open source memory system for coding agents, built primarily for Claude Code. It solves a specific problem: every new Claude Code session starts blank. You explain a bug, fix it, close the terminal, and the next session has no memory of any of it. You re-explain the context, Claude re-reads the same files, and you pay for those tokens again.
Claude Mem fixes this by watching what your agent does during a session, compressing the important parts into short notes called observations, and feeding only the relevant notes back into future sessions. It runs in the background using Claude Code’s lifecycle hooks, so there’s nothing to call manually once it’s set up. The project is popular enough (well over 100,000 GitHub stars, thousands of forks) that it’s clearly past the experimental stage, and it ships under the Apache 2.0 license.
TL;DR
- Claude Mem hooks into Claude Code’s session lifecycle to record tool calls, edits, and decisions as compact “observations” stored locally in a SQLite database with a vector index for semantic search.
- The correct install command is
npx claude-mem install, not a global npm install, because only the npx installer wires up the hooks and background worker service. - Passing
--provider claudeduring setup skips the hosted sign-in flow entirely and runs memory on your existing Anthropic plan instead of a separate paid tier. - A progressive disclosure design means new sessions only get a lightweight index of recent observations (titles, types, token cost), not a full dump of history, which keeps context usage low.
- A past version uploaded 30 days of local prompt history to the vendor’s servers without asking first; this was fixed in version 15.8.3, so updating before install matters.
- Redaction is opt-in, not on by default, so enabling it manually is a necessary step if you want API keys and secrets automatically scrubbed from stored memories.
- Telemetry is on by default (anonymous, documented) but can be turned off with a single command right after installation.
How do you install Claude Mem?
The installer is a single command:
npx claude-mem installThis is the important part: don’t use npm install -g claude-mem. A global npm install only pulls down the library code. It does not configure the Claude Code hooks, does not set up the local worker service, and will leave the tool essentially inert. The npx installer is what actually wires everything together.
When you run it, the installer checks for and installs its runtime dependencies (Bun and UV) if they’re missing. It then prompts you to sign in and choose a memory provider, with the vendor’s own hosted option pre-selected by default. That hosted tier comes with a free trial period before billing kicks in.
If you want to skip the hosted service and sign-in step entirely, pass the provider flag:
npx claude-mem install --provider claudeThis runs the memory system on your own Anthropic account and plan rather than a separate subscription. Claude Mem also supports other backends: Open Router, Gemini, or any OpenAI-compatible API endpoint, which is useful if you want to control costs or keep everything on infrastructure you already pay for.
How does the memory and recall system actually work?
Once installed, Claude Mem hooks into several points in Claude Code’s session lifecycle: when a session starts, when you submit a prompt, before and after each tool call, when Claude stops responding, and when the session ends. Every file read, edit, or command Claude runs passes through these hooks to a local worker service.
That worker hands raw tool-call data to an “observer,” a separate background model (Haiku, on the Claude provider) that converts raw activity into structured observations. Each observation includes a title, a type (bug fix, decision, etc.), a short narrative, relevant facts, and the files touched. These get written to a local SQLite database, paired with a Chroma vector database for semantic search. At the end of a session, you also get a summary covering what was asked, what was investigated, what was learned, and suggested next steps.
The recall side is where the design gets interesting. Rather than dumping your entire history into context (expensive and mostly irrelevant), Claude Mem uses what it calls progressive disclosure. A new session starts with just an index: titles and types of your most recent observations (50 by default), plus the token cost of reading each one in full. The agent decides what’s worth opening based on that index. If it needs more, it has search tools that return compact lists of observation IDs, costing roughly 50 to 100 tokens per result, before fetching full detail only on what’s relevant. The project claims meaningful token savings from this filter-then-fetch approach, though the actual savings depend heavily on your workload and provider.
What should you check before installing it?
There’s a real privacy issue worth knowing about. In version 15.2, Claude Mem added a browser-based setup step that scanned local prompt history from Claude Code, Codex, Gemini CLI, and other tools, then uploaded the full text of up to 30 days of prompts, along with project names, folder paths, and timestamps, to the vendor’s servers. This happened automatically on page load, without an explicit opt-in, despite the privacy policy stating that nothing leaves your device unless cloud sync is enabled. According to a user-reported GitHub issue, those prompts were routed through Open Router without blocking providers that may retain or train on submitted data.
This was fixed in version 15.8.3 (released November 2), which now asks first and offers a clear “keep everything local” option. If you’re installing today, confirm you’re on 15.8.3 or later. One caveat: the release notes for that fix state that prompts already uploaded under earlier versions are not retroactively removed.
Two other things worth checking at install time:
Telemetry is anonymous and documented, but it’s on by default (opt-out, not opt-in). Disable it with:
npx claude-mem telemetry disableYou can also set the standard DO_NOT_TRACK environment variable.
Redaction is also opt-in. Claude Mem includes about 30 built-in patterns to catch things like API keys before they’re stored, but you have to enable it manually with a redact enabled setting. Given that this tool is quietly logging everything your agent touches, turning this on immediately is a reasonable default for anyone installing it.
Is Claude Mem worth installing?
If you work on the same codebase for weeks and keep re-explaining the same architectural decisions or past bug fixes, Claude Mem solves a real, recurring cost. The progressive disclosure approach, index first, fetch on demand, is a sensible way to avoid bloating every session with irrelevant history. In practical use, a fresh session was able to correctly recall why a specific date-parsing decision was made weeks earlier, using the search and retrieval tools instead of re-reading code.
If your usage is mostly short, one-off tasks, the overhead isn’t worth it. A well-maintained CLAUDE.md file covers most of the same ground for free, without any background services or data handling considerations.
Cost is also a factor to plan around. On the Claude provider, the observer model’s usage draws from your existing Anthropic plan limits. There’s at least one reported case of a user burning through hundreds of hidden background runs in a few days due to a feature refresh, consuming quota they didn’t expect to spend. The hosted tier, once the free trial ends, runs on a monthly subscription with multiple pricing levels depending on usage volume.
Frequently Asked Questions
What’s the correct command to install Claude Mem?
Run npx claude-mem install. Avoid npm install -g claude-mem, which only installs the library without configuring the required hooks or background worker.
How do I avoid the hosted subscription and sign-in step?
Add the --provider claude flag during installation. This runs memory on your existing Anthropic plan rather than requiring sign-up for the hosted service.
Does Claude Mem send my code or prompts to a remote server?
By default, observations are stored locally in SQLite and Chroma databases. A prior version uploaded prompt history without clear consent; that behavior was fixed in version 15.8.3, which now requires explicit opt-in and offers a local-only mode.
Is redaction of secrets and API keys automatic?
No. Redaction is opt-in and must be enabled manually through the redact enabled setting, even though the underlying pattern matching for things like API keys is built in.
Does Claude Mem only work with Claude Code?
No. Despite the name, it supports other coding agents and tools through an --id flag, including Codex, Cursor, OpenCode, Windsurf, Copilot, and several others, with new integrations added in recent releases.
