claude-mem

What you will run into

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.

Path: Quick fix (30s, one command) -> Step by step (skimmable) -> How to confirm it works (success criteria). In a hurry? Jump to Quick fix.

Why this happens

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.

Step by step

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".

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.

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）；启动后显示端口与记忆数

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):

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.

How to confirm it works

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.

Other environments

• Other IDEs: claude-mem install --ide cursor (or codex etc., 13 IDEs supported), same syntax;
• Windows: npm global install works as usual; ~ is the user directory, same write paths;
• Co-exist with other tools: with ruflo judged possible-compatible (partially verified 2026-08-30: ruflo writes workspace + HOME CLAUDE.md pointer block, this tool writes HOME ~/.claude.json + ~/.claude/plugins/, write surfaces do not overlap; ruflo doctor unaffected in isolated run; this tool IDE registration not verified without Claude Code); cc-switch, oh-my-claudecode, code-review-graph share the ~/.claude.json registration surface with it — possible overwrite (inferred, not tested); if installing these after claude-mem, confirm the plugin is still present with claude-mem status;
• To remove: first claude-mem uninstall to unregister the plugin (auto-restores the ~/.claude.json backup), then npm rm -g claude-mem, finally rm -rf ~/.claude-mem to clear memory data; close all Claude Code sessions before uninstalling (active hooks recreate ~/.claude-mem).

Daily usage

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

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)

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/.

Uninstall & cleanup

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).

Dependency warnings

• Version: plugin itself [13.18.0, 13.18.0] (manifest locked, confirmed by isolated verify 2026-08-30); the npm CLI bootstrap lags at 12.4.7 — official phenomenon.
• Environment: Node >= 18; the worker runtime needs Bun (README requirement); in this environment uv is absent → status shows Dependencies: degraded (vector search degraded only, keyword search unaffected — environment, not a tool defect).
• 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).

FAQ

• 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.