装 claude-mem 卡住时，先别急着删目录重来。它不是一个单纯的 npm 包，而是要把 Claude Code 插件、hooks、worker 服务、SQLite 数据目录和搜索工具串起来；失败也通常不是一个点坏了，而是某一层没有接上。

我会这样试：先把失败现象归类，再动手修。命令跑不过去，先查 Node 和安装方式；插件市场找不到，先补 marketplace；Claude Code 重开后没记忆，先看 worker；搜索工具不可用，再看 MCP、数据库和端口。按这个顺序排，能少走很多弯路。

先判断：你是哪一种安装失败

最常见的第一类，是命令本身失败。比如 npx claude-mem install 跑不完、提示依赖缺失、构建报错，或者卡在 Bun、uv、Python 相关步骤。这一类先查本机运行环境，不要先动 Claude Code 配置。

第二类，是 Claude Code 里执行 /plugin install claude-mem 失败。官方 Troubleshooting 把它归到 “Plugin Not Found”，通常要先加 marketplace，再安装插件：/plugin marketplace add thedotmack/claude-mem，然后执行 /plugin install claude-mem。装完以后，再去看 ~/.claude/plugins/marketplaces/thedotmack/ 是否存在。

第三类，是安装看起来成功，但新会话没有带入历史上下文，或者搜索工具不可见。这时候问题多半在 hooks、worker 服务、数据库或端口，不应该反复执行安装命令。我的做法是先确认 worker 有没有跑，再看数据目录有没有写入。

第一步：确认安装方式没有选错

claude-mem 官方文档强调，推荐入口是 npx claude-mem install，或者在 Claude Code 内用插件市场安装。容易踩的坑是执行 npm install -g claude-mem 后以为已经装好插件；这个方式更像装了库，并不会自动注册 Claude Code hooks，也不会把 worker 服务完整接起来。

我会这样试：如果你之前用过全局 npm 安装，先不要把它当成有效安装结果。重新走一次官方安装入口：

npx claude-mem install

如果你更习惯在 Claude Code 里装，就按这个顺序来：

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

装完一定要重启 Claude Code。claude-mem 的上下文注入依赖新会话触发，旧会话里看不到效果，不一定代表安装失败。

第二步：查 Node、Bun 和 uv

安装命令报错时，先查 Node 版本。官方安装页给出的系统要求是 Node.js 20.0.0 或更高版本；Bun 和 uv 通常会在 npx claude-mem install 或 npx claude-mem repair 时自动安装，但如果网络、权限或 shell 环境有问题，自动安装也可能失败。

我会这样试：

node --version
npx claude-mem repair

如果你是 macOS，Bun 手动安装可以用 Homebrew；如果是 Windows，可以用 winget。关键不是“装很多东西”，而是确认 worker 运行需要的 Bun 可用，并且当前终端能找到它。终端里能运行，不代表 Claude Code 启动后的环境也一定能找到，所以修完后要重新打开 Claude Code。

第三步：插件市场找不到，就先补 marketplace

如果 Claude Code 提示找不到 claude-mem，不要先怀疑项目坏了。官方 Troubleshooting 对这个现象给出的顺序很直接：先添加 thedotmack/claude-mem marketplace，再安装插件，最后检查 marketplace 目录。

我会这样试：

/plugin marketplace add thedotmack/claude-mem
/plugin install claude-mem
ls -la ~/.claude/plugins/marketplaces/thedotmack/

如果目录存在，但 Claude Code 仍然没有加载插件，先完全退出 Claude Code，再重新打开一个新会话。插件类问题很怕“半重启”：终端窗口还在、会话还在、hooks 没重新触发，表面就像没修好。

第四步：安装成功但没有记忆，查 worker

claude-mem 的核心不是把一段文字塞进配置文件，而是通过 worker 服务处理观察记录，再写入本地数据目录。官方 Worker Service 文档说明，worker 通常会在 SessionStart hook 触发时自动启动；手动启动只是排查手段。

我会这样试：先看状态和日志，而不是马上清库。

npm run worker:status
npm run worker:logs
npm run worker:restart

如果日志里出现 worker 无响应、端口不一致、进程残留等线索，再检查端口。claude-mem 的 worker 默认端口不是固定给所有人一个数，而是按用户计算，也可以通过 CLAUDE_MEM_WORKER_PORT 或 ~/.claude-mem/settings.json 覆盖。

jq -r .CLAUDE_MEM_WORKER_PORT ~/.claude-mem/settings.json
curl "http://127.0.0.1:$PORT/health"

这里的判断标准很简单：worker 能响应，再继续看数据库；worker 不响应，先不要纠结搜索工具为什么没有结果。

第五步：搜索没结果，查数据库是否真的有数据

搜索工具能打开，但搜不到历史，不一定是安装失败。可能是还没有产生 observation，也可能是数据库表没数据，或者 FTS5 索引没有内容。官方 Troubleshooting 建议先数表，再测简单查询。

我会这样试：

sqlite3 ~/.claude-mem/claude-mem.db "SELECT COUNT(*) FROM observations;"
sqlite3 ~/.claude-mem/claude-mem.db "SELECT COUNT(*) FROM observations_fts;"

如果 observations 是 0，说明记忆还没有真正写进去，要回头看 hooks、worker 和最近会话是否触发了工具使用。如果 observations 有数据但 observations_fts 异常，可以考虑按官方文档重建 FTS 表。不要一上来删除 ~/.claude-mem/claude-mem.db，那会把已有记忆一起清掉。

第六步：数据库或权限报错，先备份再修

如果你看到 SQLITE_CANTOPEN，通常是 ~/.claude-mem/ 不存在、不可写，或者权限被另一个用户/终端改乱了。看到 Database is locked，则更像多个进程同时访问数据库，或者旧 worker 没退出干净。

我会这样试：

ls -la ~/.claude-mem/
sqlite3 ~/.claude-mem/claude-mem.db "PRAGMA integrity_check;"

数据库能打开但很慢，可以先做 VACUUM 或重建索引；数据库损坏时，先复制一份备份，再按官方 Troubleshooting 的数据库修复步骤处理。这里要克制一点：故障排查不是比谁删得快，而是先保住已经积累的上下文。

一张快速排查表

现象	优先检查	我会先做的动作
npx claude-mem install 报错	Node 版本、Bun、uv、网络和权限	查 node --version，再跑 npx claude-mem repair
/plugin install claude-mem 找不到插件	marketplace 是否已添加	先执行 /plugin marketplace add thedotmack/claude-mem
安装后新会话没记忆	Claude Code 是否重启、worker 是否启动	重开 Claude Code，再查 worker 状态和日志
搜索工具没结果	数据库记录数和 FTS5 表	用 sqlite3 先数 observations 和 observations_fts
数据库打不开或被锁	目录权限、残留进程、数据库完整性	先备份，再查 PRAGMA integrity_check;

什么时候该重装

只有在你确认安装入口错了、依赖坏了、插件目录不完整，或者 repair 明确修不回来时，才考虑重装。更稳的顺序是：先 repair，再重启 Claude Code，再看 worker 日志；如果还不行，备份 ~/.claude-mem/ 后再卸载重装。

我会这样试：不要把 ~/.claude-mem/ 当成缓存随手删。这里面有数据库、日志、设置和 worker 状态文件。要清理也先备份，至少保留 claude-mem.db，否则问题可能修好了，记忆也没了。

结尾检查清单

排完一轮后，用这 6 条收尾：Node 是否是 20 以上；安装方式是否是 npx claude-mem install 或插件市场；Claude Code 是否重启过；worker health 是否能响应；~/.claude-mem/claude-mem.db 是否存在；搜索无结果时，数据库表里是否真的有 observation。

如果这 6 条都过了，claude-mem 通常已经不是“安装失败”，而是某个会话还没产生足够可总结的记录。我的习惯是新开一个 Claude Code 会话，做一次真实的小任务，再回头查最近记录。这样比盯着安装命令反复运行，更容易判断它到底有没有接上。