Claude-mem is a free, Apache-2.0 plugin that gives Claude Code a memory: it watches what the agent does in each session, compresses that into short notes with a small model, and feeds the relevant ones back the next time you open the project. It picked up 627 GitHub stars today on the way to about 96,000, and with Node.js 20 or newer the install is one npx command and a restart, roughly five minutes end to end.

The problem it solves is familiar to anyone who uses an agent daily. Every new session starts cold, so you re-explain the codebase, the bug you chased yesterday and the decision you already made. Claude-mem turns that history into something the agent can search instead of something you retype.

RelatedHow to Stop AI Agents Building Generic UIs with Impeccable

  • Works across agents: the installer wires up Claude Code by default and has --ide targets for OpenCode, Antigravity, Grok Bot and OMP, plus an OpenClaw script.
  • Everything lives on your machine: a local worker on 127.0.0.1 stores sessions in SQLite under ~/.claude-mem/ and serves a web viewer.
  • You choose who pays for compression: your Anthropic plan, your own Gemini or OpenRouter key, or the hosted CMEM Pro observer with a free trial of up to 14 days.
  • Current version: v13.29.0, released 3 October 2026, requiring Node 20.0.0 or later. Bun and uv are installed for you if missing.

The exact steps, start to finish

  1. Check your prerequisites. Node 20 or newer, npm, and a working Claude Code install. 
    node --version
npm --version
claude --version
  2. Run the installer. It checks the runtime, finds your IDEs, copies the plugin and registers its hooks. 
    npx claude-mem install
  3. Or install from inside Claude Code instead. Type these in the Claude Code prompt, not your shell. 
    /plugin marketplace add thedotmack/claude-mem

/plugin install claude-mem
  4. Pick a memory provider. The installer opens a browser sign-in for the CMEM Pro trial (email magic link, no card). To skip any account and use your own Claude plan, run npx claude-mem install --provider claude instead. To run memory on a free Gemini key, create one at Google AI Studio and add these lines to ~/.claude-mem/settings.json: 
    "CLAUDE_MEM_PROVIDER": "gemini",
"CLAUDE_MEM_GEMINI_API_KEY": "your-api-key-here"
  5. Restart Claude Code. Close every session and open a new one so the SessionStart hook can run.
  6. Confirm the worker is up. Read the port from the settings file, then hit the health endpoint. 
    PORT=$(jq -r .CLAUDE_MEM_WORKER_PORT ~/.claude-mem/settings.json)
curl http://127.0.0.1:$PORT/health
  7. Open the viewer. Go to the worker URL printed on startup, http://localhost:<port>, and leave it open while you work. Observations stream in live.
  8. Use the memory. Do some real work, start a fresh session in the same project, and ask in plain language, or run the search skill directly. 
    What bugs did we fix last session?
/mem-search
How claude-mem turns a session into memoryClaude Code fires five lifecycle hooks during a session. They send tool observations to a local worker on 127.0.0.1, which asks a compression model (your Claude plan, Gemini, OpenRouter or CMEM Pro) to summarise them, then stores the result in SQLite with a Chroma vector index. The next session gets recent observations injected at start and can search older ones with mem-search. ONE SESSION IN, CONTEXT OUT Claude Code 5 lifecycle hooks LOCAL WORKER HTTP API + viewer 127.0.0.1, run by Bun Compression model Claude, Gemini, CMEM SQLite + Chroma ~/.claude-mem/ Next session: 50 notes injected, mem-search for more Wrap anything in <private> tags and it is never written to the database genztech.blog
Fig 1 The hooks only report what happened. The worker does the summarising and the storage, and the loop closes when the next session starts.

What claude-mem writes down while you work

The plugin hangs off five Claude Code lifecycle events: SessionStart, UserPromptSubmit, PostToolUse, Stop and SessionEnd. Every Read, Edit, Bash call or search the agent makes becomes a raw observation sent to the worker. The worker then asks a model, Claude Haiku 4.5 by default, to turn it into a structured note with a title, a narrative, a few facts, a type such as bugfix or decision, and the files involved. When Claude finishes replying, the Stop hook writes a session summary: what you asked, what was investigated, what was learned, what got done and what comes next.

The clever part is how little of that lands in your context window. At session start the agent sees an index of the 50 most recent observations with token costs, not the full text. If it needs more, the MCP tools work in three layers: search returns compact IDs at about 50 to 100 tokens a result, timeline shows what happened around one, and get_observations fetches full detail only for the IDs worth reading. The README puts the saving at about ten times versus fetching everything.

Installing claude-mem with npx on macOS, Linux and Windows

The same npx claude-mem install works on all three. It runs in three stages: install the runtime (it adds Bun and uv when they are missing, since the worker runs on Bun and the vector search needs Python through uv), sign in, then pick a provider. If you run it from a script or an agent with no terminal attached, it skips the sign-in, defaults to your Anthropic plan on a fresh install, and prints an optional sign-in link at the end.

Other agents get their own flag, one host per command:

npx claude-mem install --ide opencode
npx claude-mem install --ide antigravity
npx claude-mem install --ide grok-bot

One trap is worth knowing before you start. The package is on npm, but npm install -g claude-mem installs only the SDK library. It registers no hooks and starts no worker, so nothing gets remembered. Use npx or the /plugin commands.

Choosing who pays for the memory: your plan, Gemini or CMEM Pro

Every observation costs a model call, so the provider choice decides whose quota claude-mem burns. The default Claude provider shares your Claude plan. The health endpoint on our test worker reported it reading the Claude Code OAuth token from the system keychain, so no separate key is needed, but heavy sessions mean real extra usage. Gemini and OpenRouter keys move that cost off your plan, and the hosted CMEM Pro observer does the same for a trial period before falling back to your Anthropic plan unless you subscribe. Provider and model can also be switched later from the gear icon in the viewer, under Advanced.

If you run big multi-agent workflows, set "CLAUDE_MEM_SKIP_SUBAGENT_OBSERVATIONS": "true". The docs warn that one dynamic workflow can emit hundreds or thousands of low-value subagent observations and hit a free-tier rate limit.

Two more switches from the CLI's own help text are worth knowing on day one. Anonymous telemetry is on by default and opt-out, and --disable-auto-memory turns off Claude Code's native auto-memory at install time if you want claude-mem to be the only memory layer. Getting out is one command too:

npx claude-mem telemetry disable
npx claude-mem uninstall

Trying the claude-mem worker in a sandbox before it touches your setup

We did not want hooks firing inside a production Claude Code profile on the first try, so we cloned the repo into a scratch folder and started only the worker, with its data directory and port pointed somewhere disposable. The source-build route from the installation docs looks like this:

git clone https://github.com/thedotmack/claude-mem.git
cd claude-mem
npm install
npm run build
npm run worker:start
npm run worker:status

Because the built worker is already in the repo, we skipped the build and ran worker-service.cjs start directly with a local copy of Bun. With CLAUDE_MEM_DATA_DIR and CLAUDE_MEM_WORKER_PORT=38000 set, it came up on Windows 10 in a couple of seconds, created a default settings.json, and /api/health returned version 13.29.0. The viewer showed a welcome card, an empty timeline and a settings panel for how many observations and sessions to inject. That is a cheap way to see what you are installing before you let it into your real agent.

RelatedSuperpowers Setup: Give Your AI Coding Agent a Real Workflow

Claude-mem versus CLAUDE.md and Claude Code's own memory

ApproachClaude-memCLAUDE.md fileClaude Code auto memory
Who writes itHooks capture, a model summarisesYou, by handThe agent, when it decides to
What it holdsEvery tool call, as searchable notesRules and conventionsFacts the agent chose to save
SearchKeyword plus vector, via MCPNone, loaded wholeNone, an index file is loaded
Extra costA model call per observationNoneNone
Extra moving partsWorker, Bun, SQLite, ChromaNoneNone

Our view: keep a CLAUDE.md regardless, because rules you want enforced belong in a file you control. Add claude-mem if you work on the same few repos for weeks and lose real time re-explaining, and run it on a Gemini key so it does not eat your Claude plan. Skip it on a machine that runs many unattended agent jobs, where a per-tool-call hook and a model call on every observation add up fast. Also note that the README promotes CMEM, a third-party crypto token it says the creator has officially embraced. The plugin works without it, but it tells you where the project's business model is heading.

Fixing "npm is not recognized" and a viewer that will not load

Start with the built-in doctor. It checks Bun, uv and the worker in one pass: npx claude-mem doctor. If the runtime itself is broken, npx claude-mem repair re-runs the Bun and uv setup.

"The term 'npm' is not recognized" on Windows. Node is not on your PATH. Install the current release from nodejs.org, then open a new terminal before running npx again.

The viewer URL does not respond. Check the worker with npm run worker:status and curl http://127.0.0.1:$PORT/health, read npm run worker:logs, then npm run worker:restart. Trust the port in /health over the one you expect: the documented default is 37700 plus a per-user offset, but our Windows run wrote 37777 into settings.json while an environment variable moved the live worker to 38000.

"Port already in use." Pin a free port and restart:

export CLAUDE_MEM_WORKER_PORT=38000
npm run worker:restart

A console window flashes on every tool call on Windows. That is Claude Code starting the hook through bash, tracked as issue #3605. Adding "CLAUDE_MEM_DISABLE_TOOL_HOOKS": "1" under env in ~/.claude/settings.json stops tool capture, though the docs say the window itself still appears.

Chroma or Python errors during install. Search falls back to SQLite full-text only, so memory keeps working. Check python --version and run npm run chroma:health from the plugin folder.

Primary sources