claude-mem: How It Works, Install, Cost and Limits

claude-mem is an Apache 2.0 plugin that gives a coding agent memory of its own past sessions. Lifecycle hooks capture what the agent does, an LLM compresses that into observations and summaries, a local worker stores them in SQLite, and the next session starts with the relevant parts already in context.

It is one of the most starred agent memory projects on GitHub: 101,326 stars on 17 October 2026, from a repo created on 31 August 2025 by Alex Newman (@thedotmack). Every fact below comes from the claude-mem README and docs.claude-mem.ai, checked on 17 October 2026. For Claude Code’s own built-in memory, which is a separate thing, see Claude Code memory.

What is claude-mem?

claude-mem is a persistent memory layer for coding agents, built first for Claude Code. It hooks into the agent’s session lifecycle, turns tool use into compressed observations, keeps them in a local SQLite database with hybrid vector and keyword search, and primes each new session with what matters. Nothing is written by hand; capture is automatic.

The README’s own summary: it “captures everything your agent does during sessions, compresses it with AI, and injects relevant context back into future sessions.”

That is a different design from an instruction file. CLAUDE.md holds rules you write. claude-mem holds a searchable record of what happened, which you never write and mostly never read.

How claude-mem works

The README lists six components:

1. Lifecycle hooks. SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop and SessionEnd. Each is a single command, claude-mem hook claude-code <event>, run through a small launcher the installer puts on your PATH. No shell scripting, so it works on Windows without Git Bash.
2. Smart install. A cached dependency checker that also runs on claude --init and --maintenance, plus npx claude-mem install and npx claude-mem repair.
3. Worker service. A local HTTP API with a web viewer, managed by Bun. It prints its URL on startup.
4. SQLite database. Sessions, observations and summaries, with FTS5 full-text search.
5. mem-search skill. Natural language queries over the history, using progressive disclosure so a search doesn’t dump everything into context.
6. Chroma vector database. Semantic search combined with keyword search for retrieval.

Memory writes go through the worker, not the agent’s own turn, so capture does not eat your context window. The architecture overview documents the data flow in full.

How to install claude-mem

Two paths for Claude Code. From inside a session, use the plugin marketplace:

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

Or from a terminal:

1npx claude-mem install

Restart the agent afterwards. One thing to get right: npm install -g claude-mem installs the SDK and library only. It does not register the hooks or set up the worker, so the plugin will not actually run. Use npx claude-mem install or the /plugin commands.

For other agents, pass --ide:

Settings live in ~/.claude-mem/settings.json, created with defaults on first run: model, worker port, data directory, log level and context injection. CLAUDE_MEM_MODE picks a workflow mode and the language of generated observations (code, code--zh, code--ja, following code--<ISO 639-1>). By default a session only sees observations from the current agent; set CLAUDE_MEM_SESSION_START_INCLUDE_ALL_SOURCES to "true" to pool them across harnesses.

Requirements: Node 20+, Bun and uv (both auto-installed if missing), SQLite 3 (bundled).

Searching your history without burning context

claude-mem exposes its memory to the agent through MCP tools in a deliberate three-step pattern, because fetching whole observations is expensive:

1. search returns a compact index with IDs, roughly 50 to 100 tokens per result, filterable by type, date and project.
2. timeline shows what was happening chronologically around an interesting result.
3. get_observations fetches full detail, roughly 500 to 1,000 tokens per result, only for the IDs you picked.

The README puts the saving at about 10x versus fetching details first. In practice the agent searches an index, decides what is relevant, then pulls two or three full records. The search tools guide has worked examples.

What claude-mem costs

The code is free. The compression is not, because it calls a model on your sessions.

npx claude-mem install sets everything up and then asks you to sign in with an email magic link, no card. Signing in provisions a memory key and unlocks the hosted claude-mem observer with a 30-day free trial, which runs memory off your Anthropic plan. When the trial ends, memory falls back to your Anthropic plan unless you subscribe. After sign-in you choose the provider: the observer, your own OpenRouter or Gemini key, or your Anthropic plan.

To avoid the account step entirely, pass an explicit --provider flag, set CLAUDE_MEM_ONLINE_OPTIN=false, or run the installer in CI or a non-interactive shell.

Storage is local by default. Optional cloud sync backs memories up to cmem.ai, with the worker syncing on write rather than through a daemon. TeamBrain adds an optional shared workspace with team work lists, member attribution and linked findings, where each person chooses what to share. For privacy, <private> tags keep content out of storage.

One oddity worth knowing: the README ends by noting that CMEM, a token created by a third party, is “officially embraced” by the author. The plugin does not require it, but it explains some of the project’s promotion.

claude-mem vs built-in memory vs Hindsight

Sources: the claude-mem README, the Hindsight README.

Where Hindsight fits

claude-mem keeps a compressed log of what happened. Hindsight tries to keep conclusions instead: each write extracts facts, times, entities and relationships, and related facts are merged into observations, evidence-backed beliefs with supporting quotes and a proof count that get refined as later sessions add evidence rather than overwritten. Mental models are standing answers kept current in the background, so reading one is a database read with no retrieval and no LLM call. reflect reasons across many memories to answer a question like “why did we drop the Redis cache?”, which a log search cannot do.

That matters most as history grows. On the BEAM long-history benchmark, Hindsight scores 73.9 at 1M tokens and 64.1 at 10M, against 64.1 and 48.6 for Mem0’s Platform. Those figures are from Mem0’s own comparison page, and every number in this space is vendor-run, including the “Agent Memory Benchmark” site, which Vectorize operates. Months of coding sessions on one repo are exactly this kind of history. Hindsight is also MIT with nothing held back: graph and temporal recall, consolidation, observations, mental models and reflect are all in the self-hosted server, and it runs against 25+ LLM providers including local Ollama, so it needs no extra API key.

Its limits are real too. It returns about 4x more context per retrieval than Mem0 by default (Mem0’s measurement), so set max_tokens lower. Each write calls an LLM, which costs more than appending to a log. Its README says it “may be overkill” for simple workflows, and it publishes no compliance certifications, where Mem0 lists SOC 2 Type 1 and HIPAA. A side-by-side is on Mem0 vs Hindsight.

When claude-mem is the right choice, and when it isn’t

Pick claude-mem if you work mostly on one machine, want zero configuration, and the question you keep asking is “what did I do last week on this repo”. The hook capture is thorough, the install is one command per agent, and the token-aware search design means a lookup costs a few hundred tokens rather than thousands.

Look further if any of these apply:

• Several people or machines share the work. Local SQLite is the default; sharing means cloud sync or TeamBrain, and the memory is still a per-person log.
• You want the agent to reason over history, not search it. Nothing in claude-mem consolidates conflicting records or answers “why” questions.
• You cannot send code summaries to a model you don’t control. Check which provider the installer selected, and prefer your own key.
• You want no vendor account at all. Possible, but you have to opt out explicitly.

Other options are compared in open-source memory systems compared and the best AI memory framework. For how Cursor, Copilot and Codex handle this, see AI coding agent memory and Codex memory.