How to Install claude-mem (2026): Persistent Memory for Claude Code, Setup and Fixes

Every new Claude Code session starts with a blank memory. You explain the project again, Claude rediscovers the same bugs, and yesterday’s decisions are gone. claude-mem fixes that by quietly taking notes while you work and feeding the useful bits back into your next session.

Here is how to install claude-mem step by step on Windows, Mac and Linux, check it is really working, tune it, keep secrets out of it, and remove it cleanly if you change your mind.

What claude-mem Does

claude-mem is an open-source memory layer for coding agents by Alex Newman (thedotmack). The main repository has more than 114,000 GitHub stars and an Apache-2.0 licence, with version 15.11.0 on its badge at the time of writing.

It is a plugin, not an MCP server. That matters: plugins fire on lifecycle hooks automatically, while an MCP server only runs when Claude decides to call it.

1. SessionStart: injects a short index of recent observations and summaries for the current project.
2. UserPromptSubmit: logs the session and stores your prompt.
3. PostToolUse: sends each tool result to a background worker, which compresses it into an “observation” with the Claude Agent SDK.
4. Stop: writes a session summary (what you asked, what was learned, what is next).
5. SessionEnd: marks the session complete.

Next time, Claude sees a compact index and pulls full details only when it needs them, so your context window does not fill up with old logs. Beyond Claude Code, it also supports Codex, OpenCode, Gemini CLI, Antigravity CLI and several other agents.

If hooks are new to you, my Claude Code hooks guide explains every event.

Requirements

Do not have Claude Code yet? Follow how to install Claude Code on Windows, Mac and Linux first.

Method 1: Install With npx (Recommended)

The interactive installer sets up hooks, the worker and a claude-mem launcher on your PATH in one go.

1. Close Claude Code if it is running.
2. Open a terminal. PowerShell on Windows, Terminal on Mac or Linux.
3. Run the installer. Type npx claude-mem install and press Enter.
4. Pick your agent. Choose Claude Code when asked. You can skip the prompt with npx claude-mem install --ide claude-code.
5. Answer the auto-memory question. The installer asks whether to keep Claude Code’s own auto memory on. Add --disable-auto-memory if you want claude-mem to be the only memory.
6. Choose a provider. Leave it on Claude to compress with your Claude plan, or pick gemini or openrouter with --provider.
7. Restart your terminal, then Claude Code. On Windows the launcher goes to %LOCALAPPDATA%\claude-mem\bin\claude-mem.exe and is added to your user Path, which needs a fresh terminal.

Note: newer versions offer an optional email sign-in that unlocks a hosted “claude-mem observer” with a 30-day free trial. You do not need it; without it, memory compression simply uses your Anthropic plan.

Method 2: Install From the Claude Code Plugin Marketplace

If you prefer to stay inside Claude Code, use the plugin commands. Updates then arrive automatically through the marketplace.

1. Start Claude Code in any project folder.
2. Add the marketplace. Type /plugin marketplace add thedotmack/claude-mem.
3. Install the plugin. Type /plugin install claude-mem.
4. Restart Claude Code. Hooks only load at startup.
5. Give it one session. The first session after a marketplace install may have no memory while the launcher compiles. That is normal.

Warning: npm install -g claude-mem looks like the obvious command, but it only installs the SDK library. No hooks are registered and the worker never starts, so nothing is saved.

How to Check claude-mem Is Working

The worker prints its URL when it starts. Older versions always used port 37777, so if you followed an older tutorial, try http://localhost:37777 too.

Tip: the quickest real test is to fix a small bug, close Claude Code, open a new session and ask “What did we fix last session?”. A working install answers from memory.

How to Use It Day to Day

• Just work normally. Capture is automatic and non-blocking (about 8 ms per tool call in DataCamp’s test).
• Ask about the past in plain English. “Why did we switch to Postgres?” or “What was the auth bug last week?” Claude searches memory itself.
• Memory is per project. Injected context is scoped to the folder you open, so projects do not leak into each other.
• Search is tiered to save tokens. Claude first sees a compact index (about 50 to 100 tokens per result), then a timeline, then full observations only by ID.
• Folder context files. claude-mem can generate a CLAUDE.md activity timeline per folder. Read my AGENTS.md and CLAUDE.md guide to see how those files are used.

Settings Worth Changing

Settings live in ~/.claude-mem/settings.json, in the viewer’s Settings tab, or as environment variables.

What it costs

Compression uses tokens on your plan. DataCamp measured roughly 16,500 tokens per session with Haiku, and estimated heavy monthly use at well under a dollar. Switching the provider to a free OpenRouter or cheap Gemini model can bring that close to zero.

Watching your Claude Code usage closely? See Claude Code pricing and add a usage meter with the Claude Code status line.

Privacy and Security

• Local by default: memory is stored in SQLite on your own disk.
• Keep secrets out: wrap anything sensitive in <private>...</private> in your prompt and it is not stored. Newer versions also auto-redact common secret patterns.
• Cloud features are opt-in: Cloud Sync and screenshots are off unless you turn them on.
• Local API: the worker runs an HTTP API on your machine. A community audit in February 2026 flagged that early versions had no authentication and could bind to all network interfaces.

Warning: until you have checked the current version’s settings, run claude-mem on your personal development machine only, not on shared servers or cloud VMs, and keep your firewall on.

claude-mem vs Built-in Memory and Alternatives

For small projects, Claude Code’s own CLAUDE.md memory may be enough. claude-mem shines on long-running codebases where you want a searchable history of decisions and fixes. For other ways to extend Claude Code, see my Claude Skills guide and Claude Code commands cheat sheet.

Update and Uninstall

Update

• Marketplace install: updates arrive automatically.
• npx install: run npx claude-mem update.
• Missing dependencies after an update: run npx claude-mem@latest install.

Uninstall

1. Remove the launcher. Run npx claude-mem uninstall. It prints a line you may need to remove from your shell profile or Path by hand.
2. Remove the plugin. In Claude Code, use the /plugin menu to uninstall claude-mem if you added it from the marketplace.
3. Delete your memory (optional). Delete the ~/.claude-mem folder. This permanently removes all saved observations.

Troubleshooting

“memory hooks are not active” at session start

The hooks did not register. Run npx claude-mem install again and fully restart Claude Code.

“claude-mem: command not found” in hooks

Open a new terminal so the PATH change takes effect. If you ever ran npm install -g claude-mem, uninstall it with npm uninstall -g claude-mem, because it can shadow the real launcher.

Nothing is being saved

Check your Claude Code version with claude --version. Below 2.1.139, claude-mem only prints its usage text. Run claude update, then restart.

The worker will not start

Usually an old Node.js. Run node -v; install Node 20 or newer, then reinstall. Logs are in ~/.claude-mem/logs/.

Session start times out on an Apple Silicon Mac

With Chroma semantic search enabled, the worker’s cold start can be slow. Turn Chroma off and use the default SQLite full-text search.

My context fills up too fast

Lower CLAUDE_MEM_CONTEXT_OBSERVATIONS to 20 or 30, especially in the first week on a busy new project.

My Take

claude-mem is one of the few Claude Code add-ons that changes how a project feels after a week. Claude stops asking the same questions and remembers why things are the way they are.

Install it with npx claude-mem install, keep secrets in <private> tags, and keep it on your own machine. If you only work on small scripts, Claude Code’s built-in memory is fine and you can skip it.

FAQ

Is claude-mem free?

Yes. The plugin is open source under Apache-2.0. It uses a small number of tokens from your Claude plan to compress notes, and an optional hosted service has a free trial.

Does claude-mem work on Windows?

Yes. The installer puts a launcher in %LOCALAPPDATA%\claude-mem\bin and adds it to your Path. Runtime hooks do not need Git Bash.

Where does claude-mem store data?

In ~/.claude-mem/: the database is claude-mem.db, settings are in settings.json and logs are in logs/.

Is claude-mem an MCP server?

No. It is a Claude Code plugin that runs on lifecycle hooks. It does provide search tools that Claude calls when you ask about past work.

Why does npm install -g claude-mem not work?

That package is only the SDK library. It does not register hooks or start the worker, so use npx claude-mem install instead.

Can I use claude-mem with Codex or Gemini CLI?

Yes. Run the installer and choose your agent, or pass --ide. Some agents can only search memory without recording sessions.

How do I stop claude-mem saving something private?

Wrap it in <private> tags in your prompt. Content inside those tags is not stored.

Sources

• thedotmack/claude-mem on GitHub
• claude-mem docs: Installation
• claude-mem docs: Introduction
• claude-mem docs: Getting started
• DataCamp: Claude-Mem guide