Claude-Mem (by thedotmack, Apache-2.0, ~92k stars) is persistent cross-session memory for coding agents: it captures each session's content, AI-compresses it into observations, then automatically injects relevant context — the next new session still remembers last time's deployment issues, architecture decisions and pitfalls. Form = plugins for 13 IDEs (Claude Code/Cursor/Codex etc.) + MCP server + local worker (memory UI at localhost:37700).

In one sentence: install once, then every new session "goes to work with memory".

Last week you and the AI spent three hours debugging a deployment issue, and the conclusions all live in that session. This week you open a new session, the AI has no idea, and you explain it all from scratch again. Claude-Mem does exactly this: during every session it quietly captures and compresses memories, and the next new session automatically brings back the relevant ones.

This single command installs and registers (merged into one block, copy as a whole):

# Source: Trove detailed guide · verified 2026-08-28
npm_config_registry=https://registry.npmmirror.com npm install -g claude-mem && claude-mem install --ide claude-code

Expected output: Installation Complete（Plugin dir: ~/.claude/plugins/marketplaces/thedotmack；Worker port: 37700）

Seeing Installation Complete means it's installed. On mainland networks keep the npmmirror prefix to avoid npm timeouts.

1. claude-mem status shows the worker running, no more "not installed";
2. Opening http://localhost:37700 in the browser shows the memory UI;
3. Open a brand-new session and ask about last week's topic — the AI picks up the context.

AI sessions are one-shot by default: every new session starts clean and doesn't inherit the previous discussion. Claude-Mem's fix is a background worker — it records while the session runs, compresses with AI into structured memories, and injects by relevance when the next session starts. It's not a chat-log backup; it's "compressed, actively brought back" memory.

It is three pieces: the npm global CLI (bootstrap) handles install and registration; the Claude Code plugin (registered via claude-mem install --ide claude-code) provides in-session commands; the worker (background process, port 37700) handles capture and the memory UI. Note: the CLI version (12.4.7) differs from the plugin itself (13.16.1) — an official phenomenon, doesn't affect usage. The cost: it writes your Claude Code config (~/.claude.json and ~/.claude/plugins/), and backs it up to ~/.claude/backups/ automatically before installing.

• ~/.claude.json: plugin registration (install writes)
• ~/.claude/plugins/: marketplaces/cache
• ~/.claude/backups/: pre-install backups
• ~/.claude-mem/: settings/logs/memory store
• Runtime: worker service on port 37700 (memory UI + MCP mcp-search); requires Bun

Step 1: Install the bootstrap + register the plugin (both steps required)

Why two steps: npm install -g claude-mem only installs the command-line bootstrap (CLI 12.4.7), which does nothing by itself; claude-mem install --ide claude-code is what registers the plugin into Claude Code (writes ~/.claude.json + ~/.claude/plugins/, auto-backing up to ~/.claude/backups/ before installing). Skip the second step and every runtime command will say "not installed".

# Source: Trove detailed guide · verified 2026-08-28
npm_config_registry=https://registry.npmmirror.com npm install -g claude-mem
claude-mem install --ide claude-code

Expected output: Installation Complete（Plugin dir: ~/.claude/plugins/marketplaces/thedotmack；Worker port: 37700）

After install, confirm:

• output shows Installation Complete with the Plugin dir and Worker port;
• claude-mem status no longer says "not installed" (see next step).

Stuck? How to recover:

• bun-missing → the precheck reports bun-missing: the worker runtime needs Bun, install Bun first then continue;
• install errors writing ~/.claude.json → check whether Claude Code is running and holding the file; ~/.claude/backups/ has a pre-install snapshot to roll back;
• npm slow/timeout → confirm the npm_config_registry=https://registry.npmmirror.com prefix.

Step 2: Start the worker so memory runs

Why: status shows worker state (installed but not started shows Worker is not running); start launches the worker (memory UI http://localhost:37700), after which /mem-search works inside Claude Code.

# Source: Trove detailed guide · verified 2026-08-28
claude-mem status

Expected output: Worker is not running（已 install、未启动时）；未 install 时输出 claude-mem is not installed. Run: npx claude-mem install（2026-08-29 实测：CLI 12.4.7 为引导器，runtime 命令依赖 Bun）；启动后显示端口与记忆数

# Source: Trove detailed guide · verified 2026-08-28
claude-mem start

Expected output: worker 启动（记忆 UI http://localhost:37700；Claude Code 内 /mem-search 可用）

After install, confirm:

• status no longer says "not installed";
• after start, the browser opens http://localhost:37700 (memory UI).

Stuck? How to recover:

• start failed → confirm Bun is installed and usable; check logs under ~/.claude-mem/;
• port 37700 taken → claude-mem stop first then start, or check the process holding the port.

Step 3: Daily use

Why: after install there's nothing to manage — the worker captures sessions and writes memories by itself; use these four commands when you want to act (one block, pick as needed):

# Source: Trove detailed guide · verified 2026-08-28
claude-mem status              # 看 worker 状态与记忆数
claude-mem search "部署问题"    # 主动搜记忆
claude-mem adopt --dry-run     # worktree 记忆整合（合并分支后；确认后去掉 --dry-run）
claude-mem stop                # 停止 worker

Expected output: status 显示端口与记忆数；search 返回相关记忆片段列表；adopt --dry-run 列出待整合清单；stop 输出 worker stopped

When working across multiple worktrees in parallel, run adopt after merging branches to fold the memories back; search is the manual search, /mem-search is the same command inside Claude Code. Memories and settings live in ~/.claude-mem/.

Stuck? How to recover:

• search returns nothing → confirm the worker is running (claude-mem status); a fresh install needs sessions already captured;
• adopt errors → confirm you're on the merged branch and the memory directory is writable; when unsure, run --dry-run first to see the list.

Startup and entry

• Worker: claude-mem start (background process, port 37700); inside Claude Code, /mem-search;
• Status: claude-mem status.

Common operations

Operation 1: Check worker status and memory count

# Source: Trove detailed guide · verified 2026-08-28
claude-mem status

Expected output: port and memory count when running; "Worker is not running" when installed but not started

Operation 2: Search / adopt / stop (from Step 3, one block)

# Source: Trove detailed guide · verified 2026-08-28
claude-mem status              # 看 worker 状态与记忆数
claude-mem search "部署问题"    # 主动搜记忆
claude-mem adopt --dry-run     # worktree 记忆整合（合并分支后；确认后去掉 --dry-run）
claude-mem stop                # 停止 worker

Expected output: status 显示端口与记忆数；search 返回相关记忆片段列表；adopt --dry-run 列出待整合清单；stop 输出 worker stopped

Data and directories

• Memory/settings/logs: ~/.claude-mem/;
• Registered surfaces: ~/.claude.json, ~/.claude/plugins/marketplaces/thedotmack/, backups ~/.claude/backups/.

Same source as the tool-page matrix — 19 pairs total (4 measured compatible / 11 inferred possibly compatible / 4 inferred possibly conflicting); full pairs, states and evidence: Conflict pairs (co-install matrix).

• Symptom: marketplace clone failure: SSH auth failure / clone hangs
• Symptom: worker/UI port in use: "Is port 37777 in use?"
• Symptom: repeated SessionStart hook errors on the first session (worker race)
• Symptom: npm dependency install failure
• Symptom: Chroma process leak / zombie chain
• Symptom: "No previous sessions found" after third-party model auth switch

Full four-part write-up (symptom → cause → fix → verification evidence): site docs

# Source: Trove detailed guide · verified 2026-08-28
claude-mem uninstall 2>/dev/null || true; npm rm -g claude-mem 2>/dev/null || true; rm -rf ~/.claude-mem

note: unregister first (auto-restores the config backup), then remove the npm package and the memory directory; close all Claude Code sessions first

Steps (no single command — do them in order):

• claude-mem uninstall — unregister the plugin (restores ~/.claude.json from backup);
• npm rm -g claude-mem — remove the CLI bootstrap;
• rm -rf ~/.claude-mem — clear memory data;
• Close all Claude Code sessions before uninstalling — active hooks recreate ~/.claude-mem.

Expected output: no residual commands; confirm with command -v claude-mem (empty = removed).

• Runtime precheck (needs Node >= 18; worker runtime needs Bun)
• Official npm path (measured in this environment); China uses npmmirror
• Install write surfaces = ~/.claude.json (plugin registration) + ~/.claude/plugins/ (marketplaces/cache) + ~/.claude/backups/ (pre-install backup) + ~/.claude-mem/ (settings/logs/memory store)
• Each operation = one command block + expected output; the worker must be started first
• Shared registration surface: writes ~/.claude.json + ~/.claude/plugins/ + MCP registration — same-surface risk with omc (Claude plugin), ruflo/code-review-graph (MCP), cc-switch (~/.claude.json management) (judged possible-conflict in this marketplace)

• Q: Installed the CLI but still says not installed? A: CLI 12.4.7 is only the bootstrap — you must run claude-mem install --ide claude-code to register the plugin (writes ~/.claude.json); runtime commands also depend on Bun.
• Q: Will uninstall break my Claude Code config? A: the official uninstall restores ~/.claude.json from ~/.claude/backups/; close all Claude Code sessions before uninstalling, otherwise active hooks recreate ~/.claude-mem.
• Q: Where do memories live and how big? A: ~/.claude-mem/ (memory store/settings/logs); watch the directory size over long-term use, clean periodically or keep as needed.
• Q: Port 37700 taken? A: stop first then start; or investigate the process holding the port.
• Q: Where to report problems? A: install/uninstall issues on this marketplace go through the entry feedback channel; project issues go to the author's repository.

• Version: plugin itself [13.16.1, 13.16.1] (manifest locked); the npm CLI version lags at 12.4.7 — official phenomenon.
• Environment: Node >= 18; the worker runtime needs Bun (precheck reports bun-missing).
• Network: npm via the npmmirror prefix (verified mainland path).
• Write surface (large): ~/.claude-mem/, ~/.claude.json, ~/.claude/backups/, ~/.claude/plugins/marketplaces/thedotmack/ — shared registration surface, confirm before installing.
• Port: worker default 37700 (memory UI).

• Verified: local repro log (2026-08-28/29 CLI smoke: install/status/start/stop); local repro log (install/uninstall cycle); local repro log (network precheck).
• Not tested: co-install with the three possible-conflict pairs (oh-my-claudecode / code-review-graph / cc-switch) — currently judged as shared-registration-surface inference; the ruflo pair is partially verified (2026-08-30: write surfaces do not overlap, IDE registration not verified).

Third-party tutorials are not individually verified; check against this page and official docs.

• 官方 README：Quick Start（npx 安装路径 / IDE 注册 / 插件市场安装） [官方文档 · claude-mem 官方 · 2026-08-30（README 当前版本，npm claude-mem 12.4.7 / 插件本体 13.18.0）]
  官方推荐安装：`npx claude-mem install`（交互式）或 `npx claude-mem install --ide <id>`（claude-code/cursor/codex-cli 等 13 种）；Claude Code 内也可 `/plugin marketplace add thedotmack/claude-mem` + `/plugin install claude-mem`；README 明确 `npm install -g claude-mem` 只装 SDK/引导器，不注册插件钩子
• 官方 README：Worker 启动链路（start / status / stop + 37700 viewer） [官方文档 · claude-mem 官方 · 2026-08-30（插件本体 13.18.0）]
  `npx claude-mem start` 启动 worker（本地 HTTP API + 记忆查看 UI）→ `npx claude-mem status` 看状态/端口/记忆数 → `npx claude-mem stop` 停止；记忆库与设置存 `~/.claude-mem/`（settings.json、claude-mem.db、logs/）
• 官方 README：MCP Search Tools（三层检索工作流） [官方文档 · claude-mem 官方 · 2026-08-30（插件本体 13.18.0）]
  4 个 MCP 工具按 token 高效三层流程——`search`（紧凑索引，50~100 token/条）→ `timeline`（命中结果的时序上下文）→ `get_observations`（仅对筛选后的 ID 取全文，500~1000 token/条）；约 10 倍 token 节省；`/mem-search` 为 Claude Code 内同款命令
• 官方 README：Configuration（~/.claude-mem/settings.json） [官方文档 · claude-mem 官方 · 2026-08-30（插件本体 13.18.0）]
  设置存 `~/.claude-mem/settings.json`，首次运行自动创建默认值；可配 AI 模型、worker 端口、数据目录、日志级别、上下文注入设置