claude-mem 详细指南

版本 13.16.1~13.16.1 ｜分类 retro ｜安全（已审查）｜素材：项目官方文档（英文 README/docs）+ 本市场实测（2026-08-28）
配套：站内文档（manifest + guide + 证据）｜快速版：站内文档

1. 场景：什么时候会用它

Claude-Mem（thedotmack 出品，Apache-2.0，约 9.2 万星）是编码 agent 的跨会话持久记忆：捕获每次会话的内容，AI 压缩成观察，之后自动注入相关上下文——下次开新会话它还记得上次的部署问题、架构决定、踩过的坑。形态 = Claude Code/Cursor/Codex 等 13 种 IDE 的插件 + MCP 服务器 + 本地 worker（记忆 UI 在 localhost:37700）。

一句话：装一次，之后每个新会话都"带着记忆上班"。

你上周和 AI 一起花三个小时排查的部署问题，结论都在那个会话里。这周开个新会话，AI 一脸茫然，你又从头讲一遍。Claude-Mem 就是干这个的：每次会话它默默捕获、压缩成记忆，下次新会话自动把相关的记忆带回来。

2. 能力清单

能力	作用
跨会话记忆	见 Agent 执行版 guide
会话捕获（transcript watch）	见 Agent 执行版 guide
记忆搜索（/mem-search）	见 Agent 执行版 guide
AI 上下文压缩	见 Agent 执行版 guide
worktree 记忆整合（adopt）	见 Agent 执行版 guide
本地记忆 UI（端口 37700）	见 Agent 执行版 guide

3. 快速安装

下面这一条命令完成安装与注册（已合并成一段，可整体复制）：

# 来源: Trove 详细指南 · 验证于 2026-08-28
npm_config_registry=https://registry.npmmirror.com npm install -g claude-mem && claude-mem install --ide claude-code

预期输出: Installation Complete（Plugin dir: ~/.claude/plugins/marketplaces/thedotmack；Worker port: 37700）

跑完看到 Installation Complete 就装好了。国内网络保留开头的 npmmirror 前缀，避免 npm 超时。

claude-mem status 显示 worker 在跑，不再提示未安装；
浏览器打开 http://localhost:37700 能看到记忆 UI；
开一个全新会话，问上周讨论过的问题，AI 能接上上下文。

安装变体

路径	命令	实测
主路径（实测）	`npm_config_registry=https://registry.npmmirror.com npm install -g claude-mem && …`	✅ 本市场实测
镜像/代理	见快速版与 semi_auto_note；国内安装按 claude-mem 指引	实测

半自动说明：实测命令 = npm 全局装 claude-mem CLI（12.4.7）→ claude-mem install --ide claude-code（2026-08-28 隔离 HOME 验证；交互提示用默认应答即完成）；插件本体版本 13.16.1（GitHub release tag 同步；npm CLI 版本号滞后为 12.4.7）；安装写面 = ~/.claude.json（插件注册）+ ~/.claude/plugins/（marketplaces/cache）+ ~/.claude/backups/ + ~/.claude-mem/（settings/logs/记忆存储）；worker 端口 37700（记忆 UI + MCP mcp-search）；runtime 需 Bun（本环境已装）

其他 IDE：claude-mem install --ide cursor（或 codex 等，支持 13 种 IDE），写法不变；
Windows：npm 全局装照常，~ 指用户目录，写面路径相同；
和别的工具共存：与 ruflo 判定 possible-compatible（2026-08-30 部分实测：ruflo 写工作区 + HOME CLAUDE.md 指针块，本工具写 HOME ~/.claude.json + ~/.claude/plugins/，写面不重叠；隔离实测 ruflo doctor 不受影响；本工具 IDE 注册段在无 Claude Code 环境未验证）；cc-switch、oh-my-claudecode、code-review-graph 与它共用 ~/.claude.json 注册面，存在互相覆盖的可能（推断，未实测）——装了这些再装 claude-mem，装完用 claude-mem status 确认插件仍在；
不想用了：先 claude-mem uninstall 注销插件（会自动恢复 ~/.claude.json 备份），再 npm rm -g claude-mem，最后 rm -rf ~/.claude-mem 清掉记忆数据；卸载前关闭所有 Claude Code 会话（活跃 hooks 会重建 ~/.claude-mem）。

4. 为什么会这样（机制与共享面）

AI 会话默认是一次性的：每个新会话都是干净起点，不继承上次讨论。Claude-Mem 的解法是加一个后台 worker——会话进行时记录，用 AI 压缩成结构化记忆，下次会话开始时按相关性注入。它不是聊天记录备份，而是「压缩过、会主动带回来的」记忆。

它由三件套组成：npm 全局 CLI（引导器）负责安装与注册；Claude Code 插件（claude-mem install --ide claude-code 注册）负责会话内命令；worker（后台进程，端口 37700）负责捕获与记忆 UI。注意：CLI 版本号（12.4.7）与插件本体（13.16.1）不一致，是官方现象，不影响使用。代价是它要写你的 Claude Code 配置（~/.claude.json 和 ~/.claude/plugins/），安装前会自动备份到 ~/.claude/backups/。

实测命令 = npm 全局装 claude-mem CLI（12.4.7）→ claude-mem install --ide claude-code（2026-08-28 隔离 HOME 验证；交互提示用默认应答即完成）；插件本体版本 13.16.1（GitHub release tag 同步；npm CLI 版本号滞后为 12.4.7）；安装写面 = ~/.claude.json（插件注册）+ ~/.claude/plugins/（marketplaces/cache）+ ~/.claude/backups/ + ~/.claude-mem/（settings/logs/记忆存储）；worker 端口 37700（记忆 UI + MCP mcp-search）；runtime 需 Bun（本环境已装）

5. 常用操作

第 1 步：装引导器 + 注册插件（两步都要）

为什么是两步：npm install -g claude-mem 装的只是命令行引导器（CLI 12.4.7），它本身不干活；claude-mem install --ide claude-code 才把插件注册进 Claude Code（写 ~/.claude.json + ~/.claude/plugins/，安装前自动备份到 ~/.claude/backups/）。漏掉第二步，之后所有 runtime 命令都会提示未安装。

# 来源: Trove 详细指南 · 验证于 2026-08-28
npm_config_registry=https://registry.npmmirror.com npm install -g claude-mem
claude-mem install --ide claude-code

预期输出: Installation Complete（Plugin dir: ~/.claude/plugins/marketplaces/thedotmack；Worker port: 37700）

装好确认：

输出 Installation Complete 且给出 Plugin dir 与 Worker port；
claude-mem status 不再提示未安装（见下一步）。

卡住怎么办：

bun-missing → 前置检查提示 bun-missing：worker 运行时需要 Bun，先装 Bun 再继续；
install 报错写 ~/.claude.json → 检查 Claude Code 是否在运行/占用该文件；~/.claude/backups/ 里有安装前快照可回滚；
npm 慢/超时 → 确认用了 npm_config_registry=https://registry.npmmirror.com 前缀。

第 2 步：启动 worker，让记忆跑起来

讲解：status 看 worker 状态（已 install 未启动时显示 Worker is not running）；start 拉起 worker（记忆 UI http://localhost:37700），之后 Claude Code 内 /mem-search 可用。

# 来源: Trove 详细指南 · 验证于 2026-08-28
claude-mem status

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

# 来源: Trove 详细指南 · 验证于 2026-08-28
claude-mem start

预期输出: worker 启动（记忆 UI http://localhost:37700；Claude Code 内 /mem-search 可用）

装好确认：

status 不再提示未安装；
start 后浏览器能打开 http://localhost:37700（记忆 UI）。

卡住怎么办：

start 失败 → 确认 Bun 已安装且版本可用；看 ~/.claude-mem/ 下日志；
端口 37700 被占 → 先 claude-mem stop 再 start，或检查占用进程。

第 3 步：日常用起来

讲解：装完不用管，worker 自己捕获会话、写记忆；需要主动操作时用下面四条（合并成一个块，按需取用）：

# 来源: Trove 详细指南 · 验证于 2026-08-28
claude-mem status              # 看 worker 状态与记忆数
claude-mem search "部署问题"    # 主动搜记忆
claude-mem adopt --dry-run     # worktree 记忆整合（合并分支后；确认后去掉 --dry-run）
claude-mem stop                # 停止 worker

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

多 worktree 并行干活时，合并分支后跑 adopt 把记忆并回来；search 是主动搜，/mem-search 是 Claude Code 内的同款命令。记忆与设置都存在 ~/.claude-mem/。

卡住怎么办：

search 没结果 → 先确认 worker 在跑（claude-mem status），新装的工具需要先有捕获过的会话；
adopt 报错 → 确认当前在合并后的分支上、且记忆目录可写；拿不准先 --dry-run 看清单。

6. 冲突逐条（摘要）

与工具页矩阵同源，共 19 对（4 实测兼容 / 11 推断可能兼容 / 4 推断可能冲突）；完整对子、状态与证据见冲突对子（共装矩阵）。

7. 排障速查

症状：marketplace 克隆失败：SSH 认证失败 / 克隆卡死
症状：worker/UI 端口占用："Is port 37777 in use?"
症状：首会话重复 SessionStart hook 错误（worker 竞态）
症状：npm 依赖安装失败
症状：Chroma 进程泄漏 / zombie 链
症状：第三方模型鉴权切换后 "No previous sessions found"

四段式全文（症状→原因→解法→验证证据）：站内文档

8. 卸载与残留检查

# 来源: Trove 详细指南 · 验证于 2026-08-28
claude-mem uninstall 2>/dev/null || true; npm rm -g claude-mem 2>/dev/null || true; rm -rf ~/.claude-mem

9. FAQ

运行环境预检（需 Node >= 18；worker 运行时需 Bun）
官方 npm 路径（本环境实测）；国内用 npmmirror
安装写面 = ~/.claude.json（插件注册）+ ~/.claude/plugins/（marketplaces/cache）+ ~/.claude/backups/（安装前备份）+ ~/.claude-mem/（settings/logs/记忆存储）
每条操作 = 一个命令块 + 预期输出；worker 需先启动
共享注册面：它写 ~/.claude.json + ~/.claude/plugins/ + MCP 注册——与 omc（Claude 插件）、ruflo/code-review-graph（MCP）、cc-switch（~/.claude.json 管理）存在同面风险（本市场判定 possible-conflict）

问：为什么装了 CLI 还是提示未安装？答：CLI 12.4.7 只是引导器，必须再跑 claude-mem install --ide claude-code 注册插件（写 ~/.claude.json）；runtime 命令还依赖 Bun。
问：卸载会不会弄坏 Claude Code 配置？答：官方 uninstall 会用 ~/.claude/backups/ 恢复 ~/.claude.json；卸载前务必关闭所有 Claude Code 会话，否则活跃 hooks 会重建 ~/.claude-mem。
问：记忆存哪、多大？答：~/.claude-mem/（记忆库/设置/日志）；长期使用注意目录大小，可定期清理或按需保留。
问：端口 37700 被占用？答：先 stop 再 start；或排查占用进程。
问：使用问题向谁反馈？答：本市场安装/卸载问题走条目反馈入口；项目自身问题请向作者仓库反馈。

版本：插件本体 [13.16.1, 13.16.1]（manifest 锁定）；npm CLI 版本号滞后为 12.4.7，属官方现象。
环境：Node >= 18；worker 运行时需 Bun（前置检查会报 bun-missing）。
网络：npm 用 npmmirror 前缀（国内实测路径）。
写面（大）：~/.claude-mem/、~/.claude.json、~/.claude/backups/、~/.claude/plugins/marketplaces/thedotmack/——共享注册面，装前确认。
端口：worker 默认 37700（记忆 UI）。

10. 出处

条目签名：thedotmack/claude-mem（Apache-2.0，原样收录 13.16.1 插件）

实测：实测记录（本地留存）（2026-08-28/29 CLI 冒烟：install/status/start/stop）；实测记录（本地留存）（装/卸循环）；实测记录（本地留存）（网络预检）。
未实测：三个 possible-conflict 对子（oh-my-claudecode / code-review-graph / cc-switch）的共装实测（当前判定为共享注册面推断）；ruflo 对子已部分实测（2026-08-30：写面不重叠，IDE 注册段未验证）。

外部教学（来源未实测）

第三方教学未逐条实测，仅供学习；有出入以本页与官方文档为准。

官方 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 端口、数据目录、日志级别、上下文注入设置

收录来源（已合并）

本页内容由多篇来源文章按哈希去重、实测验证、AI 重写后合并而来——来源不散落，全部挂在这一个页面上。

暂无已合并来源：本页为本地实测与多来源重写的沉淀；来源与验证细节见站内对应方案页。

← 返回 claude-mem 方案页｜会话与记忆问题域