claude-mem: The Persistent Memory Plugin for Claude Code That Is Trending on GitHub

claude-mem, a "persistent memory compression system built for Claude Code," is trending on GitHub this week and shows about 104k stars. The pitch is simple and addresses a daily annoyance: Claude Code starts every session knowing nothing about yesterday. claude-mem records what the agent did, compresses it, and feeds the relevant parts back in next time.

This guide explains how it works, how to install it without the common mistake the README warns about, and where to be skeptical. We read the README and docs; we did not benchmark it.

TL;DR: questions answered #

How it works #

Six lifecycle hooks

claude-mem hangs off Claude Code's hooks system. According to the README it listens on six events: SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop and SessionEnd. Each runs a claude-mem hook claude-code <event> command. Those hooks are how it sees prompts, tool calls and their results without you doing anything.

A local worker, SQLite and Chroma

The hooks feed a local worker service: an HTTP API with a web viewer, managed by Bun. Observations, session summaries and metadata go into a SQLite database, and a Chroma vector database supports hybrid semantic and keyword search. A background observer model turns raw tool activity into compact summaries. That observer is where cost and privacy questions arise; more on both below.

A green thread looping around spools in a drawer, representing claude-mem persistent memory for Claude Code

Progressive-disclosure search

Memory only helps if retrieving it does not burn the context window you were trying to save. claude-mem exposes search through a mem-search skill and MCP tools following a three-step workflow: get a compact index, check chronological context around hits, then fetch full details only for selected IDs. The README names the tools search, timeline and get_observations, and claims roughly 10x token savings from this approach. One wrinkle: the README says "4 MCP tools" but lists three, a small sign the docs may lag the code.

If MCP is new to you, start with our guide to the Model Context Protocol.

Installing it the right way #

1. Make sure you have Node.js 20.0.0 or higher and a current Claude Code.
2. Run npx claude-mem install . Or, inside Claude Code, run/plugin marketplace add thedotmack/claude-mem and then/plugin install claude-mem .
3. Restart Claude Code, and open the web viewer the worker serves to see what it is recording.
4. Other agents use the same installer with an --ide flag, for examplenpx claude-mem install --ide opencode , and the README lists variants for OMP, T3 Code, Grok Bot and Pi. There is an OpenClaw install via a curl-to-bash script; as with any such script, read it before running.

The mistake to avoid: npm install -g claude-mem installs only the SDK or library. It does not register hooks or the worker, so nothing will be recorded. On Windows, Node and npm must be on PATH, and if hooks fail with "Executable not found" the README suggests npx claude-mem doctor. Changing CLAUDE_MEM_MODE needs a Claude Code restart.

What it stores, and what that means for privacy #

Because claude-mem sees every tool call, it can see everything a tool call touches: file contents the agent read, command output, and possibly credentials that appear in an environment dump. Three controls matter.

• <private> tags exclude sensitive content from storage, according to the README. Treat that as a convenience, not a guarantee; secrets you did not tag still flow through the hooks.
• Observer provider. You can choose the claude-mem hosted observer, your own OpenRouter or Gemini key, or your Anthropic plan. Each option sends session content to a model provider so it can be summarized. Pick the one whose data terms you accept.
• Cloud Sync and sign-in are optional. The README says Cloud Sync backs memories up to cmem.ai and that you can opt out of sign-in withCLAUDE_MEM_ONLINE_OPTIN=false or an explicit--provider flag. If your code is under NDA, keep everything local and use a provider you already have a contract with.

For a broader view of why memory stores and tool hooks are an attack surface, see our MCP security guide and the write-up of how a memory-theft path in Claude was demonstrated. A memory that persists across sessions is also a place where a prompt-injected instruction can persist, so inspect what gets stored. Teams running agents unattended can also look at AgentBeam, the agent security platform from the explainx.ai team. Shelves of dot clusters with one lit cell, representing the Chroma vector search behind claude-mem

Cost: the part the star count does not show #

Summarizing every session takes model calls. The README says the hosted observer has a 30-day free trial, and afterward memory falls back to your Anthropic plan unless you subscribe. In practice that means background summarization can eat your own usage limits, which matters if you are already close to your cap. If you track spend, compare a week with and without it; our piece on what a harness actually buys in tokens shows why overhead is easy to underestimate.

Does agent memory actually help? #

This is the honest question, and the 10x savings claim does not answer it. Two points from our own coverage. First, a UIUC study we covered, Memory Tax, reports that many agent memory systems lose to plain retrieval-augmented generation; that finding concerns the category, not claude-mem specifically, but it is a reason to measure rather than assume. Second, simpler alternatives exist: a well-kept CLAUDE.md, a notes file the agent updates, or open-source cross-harness tools such as Beacon.

A fair test is easy: pick a multi-day task, run it once with claude-mem and once with a hand-maintained notes file, and compare how many tokens the agent spends re-learning the project and how often it repeats an earlier mistake. If you cannot see a difference in a week, uninstall it. Anthropic itself has been moving in this direction; see our coverage of Claude's unified memory across chat and Cowork.

A one-week evaluation plan #

Rather than trusting the star count, run a small, honest trial. On day one, install it locally with sync off and choose an observer provider you already pay for. Work normally for two days, then open the web viewer and read what was stored: are the summaries accurate, are they too verbose, did any secret slip in? Delete anything that should not be there and add <private> tags to the patterns that caused it.

On days three to five, give Claude Code a task that depends on earlier decisions, such as "continue the migration we started Tuesday," and note whether it recovers the right context without you pasting it. Compare against a control: the same kind of task on a different branch with only a hand-written notes file. Count three things: tokens spent before the first useful edit, wrong assumptions the agent had to be corrected on, and your own time re-explaining.

On day six, check your usage dashboard for the background observer's cost. On day seven, decide. Keep it if the control lost clearly; drop it if the gap is within noise. Either outcome is useful, and it gives you data that a README claim cannot.

Limits and open questions #

• Docs drift. The "4 MCP tools" versus three listed is a small example; verify commands against the tool's--help .
• Fast release cadence. A 15.x version number suggests rapid iteration. Pin versions if you depend on it.
• Broad agent support is shallow in places. Where an agent has no hooks, the README says it falls back to watching log files, which is a weaker integration.
• Unverified benchmarks. The savings figure is the project's, not an independent test.

Should you use it? #

If your pain is re-explaining a large codebase every morning, claude-mem is a reasonable experiment: install locally, keep sync off, pick a provider you already trust, and check what it stores in the viewer after day one. If you work with secrets, regulated data or client code, start with a notes file and add automation only after you have read the hook and worker code. Whichever way you go, remember that memory is state the agent will trust, so keep it small, inspectable and deletable.

Related reading #

Install commands, versions and settings are accurate as of October 29, 2026 and may change with new releases.