How to Install Claude-Mem for Claude Code

You finish a long Claude Code session, close the terminal, and open a new one the next morning. Claude has no idea what you fixed yesterday. claude-mem is a plugin built to close that gap. It records what Claude does during a session, compresses it into short notes with a model, and feeds the relevant notes back into your next session.

Here's the short version of how to install claude-mem:

• Inside Claude Code: run /plugin marketplace add thedotmack/claude-mem, then /plugin install claude-mem, then restart.
• From your shell: run npx claude-mem install and follow the prompts.
• Not this: npm install -g claude-mem. The project's own docs say that installs the library only and never registers the hooks.

One thing to know before you start: claude-mem is third-party, open-source software by an independent developer, not an Anthropic product. It runs code on every session and stores what it sees. This guide covers the install, what happens under the hood, where your data goes, and how to turn it off.

What the claude-mem plugin is

The claude-mem repository on GitHub is maintained by Alex Newman (thedotmack). Its README describes it as a "persistent memory compression system built for Claude Code." As of late October 2026 the repo is on version 15.3.0, and the LICENSE file is the Apache License, Version 2.0.

Claude Code is still the main target, but the project has grown. The installer also offers integrations for Cursor, Codex CLI, OpenCode, Antigravity CLI, OpenClaw and others, all under the same claude-mem package name.

How it works

Claude-mem plugs into Claude Code's hooks, the lifecycle events that run a command at fixed points in a session. According to the project documentation, the cycle looks like this:

1. Session start: a hook pulls recent observations and session summaries for the current project from a local database and injects them into Claude's starting context.
2. Your prompts: saved to the database as part of the session.
3. Every tool call: after Claude reads a file, edits code, or runs a Bash command, a hook captures that as an observation.
4. Compression: a background worker sends those observations to a model, which turns them into structured notes with a title, facts, a type such as bugfix or decision, and the files involved.
5. When Claude stops: a summary of the request, what was learned and what's next gets written for the next session.

Injection is deliberately thin. The docs call it progressive disclosure: the session opens with an index of observation titles, and Claude fetches full details only when it needs them, through search tools named search, timeline and get_observations. By default, the setting CLAUDE_MEM_CONTEXT_OBSERVATIONS caps the startup index at 50 observations.

How to install claude-mem

The installation guide lists two supported routes. Both register the hooks and start the worker.

Option 1: the Claude Code plugin marketplace

In a Claude Code session, run:

/plugin marketplace add thedotmack/claude-mem
/plugin install claude-mem

The marketplace registers under the name thedotmack, so the fully qualified plugin ID is claude-mem@thedotmack. In recent Claude Code versions, /plugin install inside a session opens the plugin's details panel so you can review it and pick a scope before anything installs. Anthropic's plugin docs point out that a plugin can run hooks and MCP servers, so read that panel. If you're new to plugins, our Claude Code plugins guide explains scopes and marketplaces.

Restart Claude Code when it finishes. One quirk: a marketplace-only install builds the claude-mem hook launcher on your first session start, so that first session may run without memory. The next one has it.

Option 2: the npx installer

From your terminal:

npx claude-mem install

The interactive installer runs in three stages:

1. Pick agents and install the runtime. It detects supported tools, checks for Bun and uv, copies the plugin files, registers the plugin and puts a small claude-mem launcher on your PATH (~/.local/bin on macOS and Linux).
2. Sign in. It opens a browser sign-in for the developer's hosted service, cmem.ai.
3. Choose a memory provider. This decides which model compresses your observations.

Step 3 is the one to read carefully. The installer pre-selects CMEM Pro, a hosted observer run by the developer, which starts on a trial and then asks you to subscribe. The alternatives are your own OpenRouter key, your own Gemini API key, or your Anthropic plan. If you'd rather skip the sign-in entirely, pass --provider claude and memory runs on your own Claude plan. The docs say a local install on that path still contacts cmem.ai once at signup, with a numbers-only usage summary and no prompts, paths, or project names.

Why npm install -g claude-mem isn't enough

Claude-mem is published on npm, which makes the global install look like the obvious move. It isn't. The docs say npm install -g claude-mem installs the SDK and library only. It doesn't register the plugin hooks or start the worker service, so nothing gets captured. Worse, a global claude-mem that sits earlier on your PATH can shadow the hook launcher. If you already ran it, remove it with npm uninstall -g claude-mem and use one of the two routes above.

Requirements and where your data lives

Run npx claude-mem doctor if memory doesn't show up. It checks the launcher, your PATH and your Claude Code version.

Everything lives under ~/.claude-mem/ on your machine:

• claude-mem.db, the SQLite database of sessions, observations and summaries
• settings.json, where every option lives
• logs/, the worker logs

Set CLAUDE_MEM_DATA_DIR to move it. Because it's plain SQLite, you can open ~/.claude-mem/claude-mem.db with sqlite3 and read exactly what was stored. That's worth doing once, just to see how much it keeps.

The worker also serves a local web viewer, so you can browse the memory stream in a browser instead of a database shell.

Privacy controls, costs and caveats

This is the part most install guides skip. Claude-mem sees every file Claude reads and every command it runs, and it sends that material to a model for compression. Treat it the way you'd treat any tool with that level of access.

Keep secrets out with <private> tags. Wrap anything you don't want stored in <private> and </private> tags inside your prompt. Per the private tags docs, Claude still sees the content during the session, but it's stripped from prompts, tool inputs and tool outputs before anything reaches the database.

Turn on auto-redaction. It's off by default. Set "CLAUDE_MEM_REDACT_ENABLED": "true" in ~/.claude-mem/settings.json and claude-mem replaces common secret patterns, such as AWS keys, GitHub tokens and API keys, with placeholders before storage. This catches the key a curl command printed, which a <private> tag can't.

Exclude tools and projects. CLAUDE_MEM_SKIP_TOOLS lists tools whose calls are never recorded, and CLAUDE_MEM_EXCLUDED_PROJECTS takes glob patterns for folders you never want remembered.

Telemetry is on by default. The telemetry page says claude-mem sends anonymous usage analytics, keyed to a random install ID. The installer asks about it once. To opt out later, run npx claude-mem telemetry disable or set DO_NOT_TRACK.

Compression costs tokens. Every observation gets summarized by a model. With the default Claude provider, that's a Haiku model on your own plan, so memory shares your Claude usage. With OpenRouter or Gemini it spends your credit with those providers. With CMEM Pro it goes through the developer's hosted gateway. The project says progressive disclosure keeps injected context small, but the compression calls happen on every session either way.

It's someone else's code running as you. Anthropic's hooks reference warns that command hooks run with your full user permissions. Claude-mem's hooks fire on every tool call. That's how it works, and it's also why you should pin a version you've reviewed if you use it on client or work code.

How to disable or uninstall claude-mem

You have three levels:

• Turn it off without removing it: run /plugin, open the Installed tab, and disable claude-mem. From your shell, claude plugin disable claude-mem@thedotmack does the same.
• Remove the plugin: /plugin uninstall claude-mem@thedotmack, or claude plugin uninstall from the shell.
• Remove everything the installer set up: npx claude-mem uninstall removes the plugin files and the launcher, and stops the worker.

Your memories survive all three. The uninstaller's own source says ~/.claude-mem is preserved and prints rm -rf ~/.claude-mem as the way to remove it. Delete that folder yourself if you want the data gone. The installer also adds ~/.local/bin to your shell rc file if it wasn't on your PATH, and the uninstaller leaves that line for you to remove.

Claude-mem vs Claude Code's built-in memory

Before you install anything, check whether Claude Code's own memory already covers you. Anthropic's memory documentation describes two built-in systems:

The CLAUDE.md file is for rules you want followed every time. Auto memory is on by default in local sessions, and Claude decides what's worth saving. It also skips anything it can work out from the code or git history. Toggle it from /memory.

Claude-mem goes further. It records what actually happened, every tool call and every summary, and makes it searchable. That's useful if you want to ask "what did we change in the auth flow last week?" and get an answer. It's overkill if all you need is for Claude to remember that you use pnpm. For a wider look at how agents remember things at all, see our guide to AI agent memory.

A sensible order: write a good CLAUDE.md, let auto memory run for a week, and add claude-mem only if you still keep re-explaining past work.

Run AI setups without the plumbing

Claude-mem is a good example of a setup power users rave about and most people never get running: Node, Bun, hooks, PATH entries and a provider choice before the first memory appears. Taku is built for the other side of that gap. It's an AI-native desktop workspace where you mirror an AI app or workflow someone already got working, run it and keep it. Taku is in Beta, and the Mac app is available now.

FAQ

How do I install claude-mem?

In Claude Code, run /plugin marketplace add thedotmack/claude-mem and then /plugin install claude-mem, and restart. Or run npx claude-mem install from your terminal. Don't use npm install -g claude-mem, which installs only the library.

Is claude-mem made by Anthropic?

No. It's an open-source project by an independent developer, Alex Newman, published under the Apache License 2.0. Anthropic's own memory features are CLAUDE.md files and auto memory.

Is claude-mem free?

The code is open source. Running it costs model usage, because every observation is compressed by a model. That usage comes from your Claude plan, your own OpenRouter or Gemini key, or the developer's hosted CMEM Pro service, depending on the provider you choose.

Where does claude-mem store data?

In ~/.claude-mem/ on your machine, mainly a SQLite database called claude-mem.db. Set CLAUDE_MEM_DATA_DIR to move it.

How do I stop claude-mem from saving passwords or API keys?

Wrap sensitive text in <private> tags and turn on auto-redaction with CLAUDE_MEM_REDACT_ENABLED in ~/.claude-mem/settings.json. Neither is a guarantee, so keep production secrets out of sessions where you can.

Why isn't claude-mem showing context in new sessions?

Run npx claude-mem doctor. The usual causes are a Claude Code version older than 2.1.139, a PATH that doesn't include the hook launcher, or a global npm claude-mem shadowing it. After a marketplace-only install, the first session can also be empty while the launcher builds.

Does claude-mem work with Cursor or Codex?

The installer offers integrations for several agents beyond Claude Code, including Cursor, Codex CLI and OpenCode. Check the project docs for the exact setup for each one.