Claude-Mem: Persistent Memory Plugin for Claude Code
Claude-Mem is a third-party plugin that watches what your agent does, has a second agent compress it into observations, and injects a short index of them into the next session. Here is what it actually does, how to install and configure it, and where it stops and CLAUDE.md begins.
Claude-Mem at a glance
- It is a memory layer, not a rules file: hooks hand every tool call to a local worker, a second agent turns that activity into short observations, and the next session starts with a compact index of them.
- Two supported install routes: npx claude-mem install (prepares the runtime and opens a browser setup), or the pair /plugin marketplace add thedotmack/claude-mem then /plugin install claude-mem.
- Apache-2.0, TypeScript, maintained by Alex Newman (thedotmack). Memory is stored locally in SQLite at ~/.claude-mem/claude-mem.db; cloud sync is opt-in.
- It does not replace CLAUDE.md or Claude Code's auto memory — all three load at session start and answer different questions. The comparison table below is the short version.
thedotmack/claude-mem — README
Sourcegithub.comchecked 2026-11-13
.claude-plugin/marketplace.json — claude-mem 15.18.3
Sourceraw.githubusercontent.comchecked 2026-11-13
Installation Guide
Sourcedocs.claude-mem.aichecked 2026-11-13
Configuration
Sourcedocs.claude-mem.aichecked 2026-11-13
Telemetry — what is collected and how to opt out
Sourcedocs.claude-mem.aichecked 2026-11-13
How Claude remembers your project — CLAUDE.md vs auto memory
Sourcecode.claude.comchecked 2026-11-13
dsh-claude-mem — DeepSeek Harness port (unofficial)
Sourcedeepseekharnessplugins.comchecked 2026-11-13
Commands, settings, defaults and paths on this page were read from the upstream repository and the official docs on 2026-11-13. Commands and setting names are left untranslated on purpose, because a translated command is a broken one.
Repository facts from the GitHub API on 2026-11-13: 116,640 stars, 10,120 forks, created 2025-08-31, latest release v15.18.3 published 2026-11-12. Star counts move daily — treat them as a snapshot, not a score.
What Claude-Mem actually is
Claude-Mem is an open-source plugin for Claude Code (and a dozen other coding agents) that gives the agent memory of its own work. The project describes the problem plainly: every new session starts from zero, re-reads the same files, re-asks the same questions and walks back into mistakes you already fixed together.
Its answer is a second agent running beside yours. Hooks installed into the host agent hand each tool call — what was read, edited and run — to a small local worker. That worker runs an observer model over the activity, writes short structured observations and an end-of-session summary, and stores them in a local SQLite database. When a new session starts, the host agent receives a compact index of the observations that matter for this project and pulls full details only when it asks for them.
So the unit of memory here is an observation about work that happened, not an instruction you wrote. That is the whole difference from CLAUDE.md, and it is why the two coexist rather than compete.
- License
- Apache-2.0
- Latest release
- v15.18.3 · 2026-11-12
- Memory lives in
~/.claude-mem/claude-mem.db- Stars (2026-11-13)
- 116,640
How it works, in three moves
The README states the loop in three sentences, and every other feature hangs off it:
- 1
Your agent works
Lifecycle hooks in the host agent hand each tool call to a small local worker. For Claude Code the hooks cover SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, PostToolUseFailure, Stop, SubagentStop and SessionEnd, plus a Setup entry for claude --init and --maintenance. Each hook is one shell-free command, claude-mem hook claude-code <event>.
- 2
The observer takes notes
A second agent turns that activity into short observations and writes a summary when the session ends. By default the compression model is Haiku (CLAUDE_MEM_MODEL=haiku), running on your Anthropic plan; you can point it at an OpenRouter or Gemini key instead, or at the vendor's hosted observer.
- 3
The next session starts with them
At SessionStart the agent receives a compact index of observations for this project — 50 by default, set with CLAUDE_MEM_CONTEXT_OBSERVATIONS — and fetches full details only when it needs them. Injection starts on your second session in a project, because the first one has nothing to inject yet.
Search uses the same layered idea. Three MCP tools — search, timeline, get_observations — return an index first, chronological context second, and full records last, so the agent pays for detail only on the rows it chose. The mem-search skill drives those tools for you, and the README's own figures put an index row at roughly 50–100 tokens against 500–1,000 for a full record — a per-row ratio the README explicitly says is not a measured end-to-end saving.
What the worker also gives you
The local worker serves a viewer at the URL printed on startup — memory, sessions and settings at /viewer, plus My Work at the root — and exposes tools beyond search: smart_search, smart_outline and smart_unfold for code navigation, save_memory to write a note on purpose, and work-state tracking. Every observation has an ID you can cite through the worker API.
Install and verify
Both routes below are copied from the upstream docs. The installer route is the one the project recommends, because it prepares the runtime and compiles the hook launcher; the plugin route is two prompts inside Claude Code.
Route 1 — the installer
Run this in a terminal. The installer checks Bun and uv, copies the plugin files, installs dependencies, puts the claude-mem launcher on your PATH and opens a browser setup where you pick agents, integrations, skills and the memory provider. Keep the terminal running while you use that page.
npx claude-mem installDo not install it with npm install -g claude-mem. The README is explicit that a global npm install puts the SDK/library on your machine only — it registers no plugin hooks and starts no worker, and it can shadow the real launcher on PATH.
Route 2 — the plugin marketplace
Send these as two separate prompts inside Claude Code, then restart it. Both routes configure the hooks and start the worker; context from previous sessions then appears automatically in new sessions.
/plugin marketplace add thedotmack/claude-mem/plugin install claude-memA marketplace-only install has no installer step, so the plugin places its launcher on the first session start while it compiles — that first session can run without memory context, and the next one has it. Running npx claude-mem install once removes the gap.
Check that it is actually running
Run npx claude-mem doctor: it checks Bun, uv, the hook launcher and the worker, and tells you what to fix. claude-mem --version prints the launcher protocol number, and the worker URL printed at startup serves the viewer. If hooks report "Executable not found in $PATH", doctor shows which claude-mem resolves on PATH and whether it is the launcher.
npx claude-mem doctorclaude-mem --versionRequirements before you start
- 1Node.js 20.19 or later in the 20.x line, or 22.12 or later.
- 2Bun 1.2.16 or newer — the hook launcher is compiled with it; the installer installs Bun if it is missing.
- 3uv, auto-installed if missing: it provides the Python side of Chroma's embedding service for semantic search.
- 4Claude Code 2.1.139 or later — the first release that runs exec-form hook arguments. Older builds ignore args and run a bare claude-mem, so nothing is captured. SQLite ships bundled via bun:sqlite.
The settings that actually change behaviour
Everything lives in ~/.claude-mem/settings.json, auto-created with defaults on first run, and an environment variable of the same name overrides the file. These are the rows worth knowing; the configuration page documents the rest.
| Setting | Default | What it does |
|---|---|---|
CLAUDE_MEM_MODEL | haiku | Model used to compress observations when the provider is Claude. haiku follows the newest Haiku; a full ID pins one version. |
CLAUDE_MEM_PROVIDER | claude | Which provider runs the observer: claude, codex, gemini, openrouter or openai-compatible. |
CLAUDE_MEM_CONTEXT_OBSERVATIONS | 50 | How many observations are injected at session start. Lower it if the startup block feels heavy. |
CLAUDE_MEM_MODE | code | Workflow profile and the language of generated observations, e.g. code, code--chill for fewer observations, or code--zh for Chinese. |
CLAUDE_MEM_DATA_DIR | ~/.claude-mem | Data root. Every other path — database, Chroma index, logs, settings, worker pid and port files — derives from it. |
CLAUDE_MEM_WORKER_PORT | 37700 + (uid % 100) | Worker port. The default is per-user, so two users on one machine do not collide; set a fixed port if you script against the HTTP API. |
CLAUDE_MEM_CONTEXT_PROJECTS | current | Which projects SessionStart reads memory for: current means this checkout, all means every project except the ones you exclude by glob pattern. |
CLAUDE_MEM_SKIP_TOOLS | ListMcpResourcesTool, SlashCommand, Skill, TodoWrite, AskUserQuestion | Tools excluded from observations. Useful for tools whose output is noise rather than knowledge. |
CLAUDE_MEM_SESSION_START_INCLUDE_ALL_SOURCES | false | Whether SessionStart context includes observations from every harness, not only the one you are in. Default false. |
CLAUDE_MEM_SKILLS_DISABLED | (none) | Hides bundled skills from Claude Code's listing and slash commands, by bare folder name. |
Two more worth knowing: CLAUDE_MEM_SKIP_BASH_PATTERNS takes a regex matched against each shell command, so noisy commands never become observations, and CLAUDE_MEM_REDACT_ENABLED (off by default) turns on auto-redaction of recognised secret patterns before they are stored.
Claude-Mem vs Claude Code's built-in memory
Claude Code already carries knowledge across sessions in two ways, and Anthropic's documentation treats them as complementary: CLAUDE.md files you write, and auto memory Claude writes itself. Claude-Mem is a third, independent layer on top.
| Dimension | Built into Claude Code | Claude-Mem plugin |
|---|---|---|
| Who writes it | You write CLAUDE.md; Claude writes auto memory from your corrections. | A second observer agent, from the tool activity your session produced. |
| Where it lives | CLAUDE.md at the project root or ~/.claude/CLAUDE.md; auto memory at ~/.claude/projects/<project>/memory/ with a MEMORY.md index. | SQLite at ~/.claude-mem/claude-mem.db, plus settings and logs in the same folder. Optional Chroma index for semantic search. |
| What goes in | Instructions and rules; auto memory holds learnings and patterns, and only its first 200 lines or 25KB are loaded. | Observations about work that happened — decisions, bug fixes, what was read and changed — compressed by a model. |
| When it loads | Every session, automatically, as context after the system prompt. | At SessionStart through a hook, from your second session in a project onward. |
| How it is read | The whole file or the auto-memory index is simply present in context; /memory lists and opens the files. | A compact index is injected; details come back through three MCP tools — search, timeline, get_observations. |
| Dependencies and cost | Nothing extra — it ships with Claude Code. | Node, Bun and uv, a local worker process, and a model that compresses: your Anthropic plan by default, your own key, or the paid hosted observer. |
The practical split: put rules and conventions in CLAUDE.md, let auto memory collect preferences, and let Claude-Mem carry the history of what you actually did. If a session's detail matters only once, none of the three needs it; if a rule must be followed every time, only CLAUDE.md is the right home for it. The two are not even mutually exclusive in storage — claude-mem memory ingest imports Claude Code's auto-memory topic files into its own database as observations, without spending model tokens.
Claude Code memory tutorialPrivacy, limits and honest caveats
This plugin records your working sessions, so the defaults are worth reading before it lands in a work repository.
- 1Local by default. Sessions, observations and summaries are written to SQLite at ~/.claude-mem/claude-mem.db; settings and logs sit in the same folder. Cloud sync is opt-in, not automatic.
- 2Wrap anything in <private> tags and it is never stored — the README's own wording. Auto-redaction of recognised secret patterns is a separate opt-in switch, CLAUDE_MEM_REDACT_ENABLED, and it is off by default.
- 3Anonymous telemetry is on by default (PostHog, keyed only to a random install UUID). Turn it off with npx claude-mem telemetry disable; DO_NOT_TRACK is honoured and overrides everything.
- 4Compression is a model call, so tool activity leaves the machine for whichever provider you chose — your Anthropic plan, your OpenRouter or Gemini key, or the vendor's hosted observer. Pick deliberately.
- 5It is third-party software, not an Anthropic product, and it installs executable hooks. Read plugin/hooks/hooks.json and the settings before rolling it out to a team; treat the plugin as code you are running, because that is what it is.
- 6It costs context as well as tokens: an injected index, a worker process, and Bun and uv on the machine. If your sessions are already short and self-contained, the win is small — measure on your own repo instead of trusting a headline number.
None of that makes it a bad install. It makes it a tool to try on one real project first — with the repositories you never want recorded excluded by glob pattern, and telemetry turned off if you prefer — before you make it the default on everything you open.
Telemetry is one command to turn off:
npx claude-mem telemetry disable