Claude-Mem 持久记忆系统详解：从一键安装、Lifecycle Hooks 到 MCP 三层搜索工具与模式配置

本文基于仓库中的荷兰语版说明文档 docs/i18n/README.nl.md 编写，完整覆盖 Claude-Mem 的安装方式、核心架构（Hooks + Worker + SQLite + Chroma）、MCP 搜索工具的三层工作流、CLAUDE_MEM_MODE 模式配置与故障排查入口，并结合 plugin/hooks/hooks.json、src/servers/mcp-server.ts 与 src/shared/SettingsDefaultsManager.ts 等源码逐条印证。读完后，你将能够独立安装并理解 Claude-Mem 如何自动捕获会话、压缩记忆并在后续会话中注入上下文，以及如何用 MCP 工具以最低 token 成本检索项目历史。

一、项目定位：跨会话的持久记忆压缩

Claude-Mem（仓库包名仍为 claude-mem，当前版本 13.24.0，见 package.json）是一个为 Claude Code 等 AI 编码代理构建的持久记忆压缩系统。它在会话运行期间自动记录工具使用观察（observations）、生成语义化摘要，并把这些记忆提供给未来的会话——即使会话结束或断开重连，项目知识的连续性依然保留。

核心能力一览（继承自原文档）：

• 持久记忆：上下文在会话之间保持；
• 渐进式披露（Progressive Disclosure）：分层记忆检索，并展示 token 成本；
• 技能化搜索：通过 mem-search 技能（plugin/skills/mem-search/SKILL.md）用自然语言询问项目历史；
• Web Viewer UI：在 Worker 启动时打印的 URL 上查看实时记忆流；
• 隐私控制：使用 <private> 标签可将敏感内容排除出存储；
• 引用（Citations）：通过 Worker API 用 ID 指回更早的观察，或在 Web Viewer 中浏览；
• 全自动运行，无需人工干预。

二、快速开始：四种安装方式与一个常见陷阱

2.1 标准安装（Claude Code）

npx claude-mem install

2.2 安装到 OpenCode / Antigravity CLI

npx claude-mem install --ide opencode
npx claude-mem install --ide antigravity

2.3 通过 Claude Code 插件市场安装

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

安装完成后重启 Claude Code，之前会话的上下文会自动出现在新会话中。

原文档强调的陷阱：Claude-Mem 虽也发布在 npm 上，但 npm install -g claude-mem 只安装 SDK/库——它不会注册插件 Hooks，也不会启动 Worker 服务。必须使用 npx claude-mem install 或上面的 /plugin 命令完成完整安装。这一区分在源码层面得到印证：install/public/installer.js 是安装器入口，而 src/npx-cli/index.ts 中封装了安装子命令（--ide 参数即由该 CLI 解析）。

2.4 OpenClaw 网关安装

在 OpenClaw 网关上以单命令安装持久记忆插件：

curl -fsSL https://install.cmem.ai/openclaw.sh | bash

安装器会处理依赖、插件配置、AI 提供方配置、Worker 启动，以及可选的实时观察推送（Telegram / Discord / Slack 等）。仓库中 openclaw/ 目录包含对应插件（openclaw/install.sh、openclaw/SKILL.md）。

三、工作原理：六大核心组件与 Hooks 真实现

原文档列出六大核心组件，下面逐条给出仓库中的对应实现：

1. 5 个 Lifecycle Hooks（SessionStart、UserPromptSubmit、PostToolUse、Stop、SessionEnd），共 6 个 Hook 脚本；
2. 智能安装检查——带缓存的依赖校验（pre-hook 脚本，不是 lifecycle hook）；
3. Worker 服务——由 Bun 管理的本地 HTTP API，提供 Web Viewer UI 与搜索端点；
4. SQLite 数据库——存储会话、观察、摘要；
5. mem-search 技能——自然语言查询 + 渐进式披露；
6. Chroma 向量数据库——混合语义 + 关键词检索。

3.1 Hook 注册表：plugin/hooks/hooks.json 说了什么

plugin/hooks/hooks.json 是全部 Hook 的注册中心，可以看到每条 Hook 都以 bash 脚本定位插件根目录后调用 node scripts/bun-runner.js scripts/worker-service.cjs hook claude-code <action> 这一统一入口，且普遍做了 nvm PATH 修复、孤儿缓存目录跳过（.orphaned_at 标记）与 Windows cygpath 路径转换等健壮性处理：

Hook 事件	匹配器	执行的 action	超时/特性
Setup	*	运行 scripts/version-check.js（即“智能安装”的依赖预检）	300s
SessionStart	startup|clear|compact	① worker-service.cjs start 启动 Worker；② hook claude-code context 注入上下文	各 60s
UserPromptSubmit	—	hook claude-code session-init 初始化会话	60s
PostToolUse	*	hook claude-code observation 捕获工具观察	120s，异步
PreToolUse	Read	hook claude-code file-context 文件读取门控	60s，异步
Stop	—	hook claude-code summarize 会话结束生成摘要	120s，异步

这解释了原文档的两个细节：其一，“6 个 Hook 脚本”指的是 5 个生命周期事件 + 1 个安装预检（Setup 阶段的 version-check）；其二，PostToolUse / PreToolUse / Stop 都标记为 "async": true，即观察捕获与摘要生成不阻塞主对话，这是“自动运行、零感知”体验的关键。

3.2 各组件在仓库中的落点

• Worker 服务：src/services/worker-service.ts、plugin/scripts/worker-service.cjs；
• SQLite 存储：src/services/sqlite/、src/storage/sqlite/，schema 说明见 docs/public/architecture/database.mdx；
• Chroma 混合检索：docs/public/architecture/search-architecture.mdx 与 src/services/worker/ 中的搜索编排；
• 上下文注入逻辑：src/utils/context-injection.ts。

架构数据流的完整描述可继续参考 docs/public/architecture/overview.mdx 与 docs/public/hooks-architecture.mdx。

四、MCP 搜索工具：三层工作流与真实参数签名

Claude-Mem 通过 4 个 MCP 工具提供智能记忆检索，遵循 token 高效的三层工作流：

1. search——获得带 ID 的紧凑索引（约 50–100 tokens/条结果）；
2. timeline——获得感兴趣结果前后的时间线上下文；
3. get_observations——仅为筛选后的 ID 拉取完整细节（约 500–1000 tokens/条）。

先过滤、后取详情，可带来约 10 倍的 token 节省。src/servers/mcp-server.ts 中这三个工具的注册顺序与描述和文档完全一致（描述里甚至直接标注了 "Step 1 / Step 2 / Step 3"），源码给出的完整参数比文档更细：

search（mcp-server.ts 第 474 行起）

参数	类型	说明
query	string	搜索查询
limit	number	最大结果数，默认 20
project	string	按项目名过滤
platformSource	string	按平台源过滤（如 claude、codex、cursor），限定只看该代理自己的记忆
type	string	文档类别：observations / sessions / prompts（默认全部）；其他值视为观察类型过滤（obs_type 的别名）
obs_type	string	按观察类型过滤（如 bugfix、feature），逗号分隔多个
dateStart / dateEnd	string	ISO 日期区间
offset	number	分页偏移
orderBy	string	date_desc 或 date_asc

timeline（mcp-server.ts 第 525 行起）

• anchor：number，时间线中心观察 ID；与 query 二选一；
• query：string，自动查找锚点；
• depth_before / depth_after：锚点前后各取几条，默认各 3 条；
• project：项目过滤。

get_observations（mcp-server.ts 第 543 行起）

• ids：number 数组，必填，要拉取的观察 ID 列表（文档强调：务必批量传多个 ID 以减少往返）；
• 另支持 orderBy、limit、project。

标准用法示例（继承原文档）：

// 第 1 步：搜索索引
search(query="authentication bug", type="bugfix", limit=10)

// 第 2 步：查看索引，识别相关 ID（例如 #123、#456）

// 第 3 步：拉取完整细节
get_observations(ids=[123, 456])

从源码结构看，这些工具底层通过 callWorker 调用本地 Worker 的 /api/search、/api/timeline、/api/observations/batch 端点；在 server 运行时下 search 还会按条件智能路由到远端 /v1/search。完整的工具演示可参考 docs/public/usage/search-tools.mdx。

五、Release Branches：三条分支的发布模型

• main：稳定发布分支，唯一发布到 npm 的分支；
• core-dev：面向早期可靠性修复的源码运行分支；
• community-edge：面向社区集成的源码运行分支。

分支流转策略与本地运行非稳定版本的步骤见 docs/public/branches.mdx。

六、系统要求与 Windows 安装注意

系统要求（原文档）：

• Node.js：20.0.0 或更高（package.json 的 engines 要求一致）；
• Claude Code：支持插件机制的最新版本；
• Bun：JavaScript 运行时与进程管理，缺失时自动安装（见 plugin/scripts/bun-runner.js 的运行时引导）；
• uv：向量检索所需的 Python 包管理器，缺失时自动安装；
• SQLite 3：持久化存储（随环境自带）。

Windows 注意：如果看到类似报错：

npm : The term 'npm' is not recognized as the name of a cmdlet

说明 Node.js/npm 未安装或未加入 PATH。请从 Node.js 官方渠道下载最新安装包，安装后重启终端再试。相关回归问题在 tests/infrastructure/windows-hide-regressions.test.ts 等测试中有覆盖。

七、配置：settings.json 与 CLAUDE_MEM_MODE

7.1 设置文件与内置变量清单

所有设置保存在 ~/.claude-mem/settings.json（首次运行时自动创建默认值）。src/shared/SettingsDefaultsManager.ts 定义了全部受支持键及默认值，是这份清单的权威来源，常用的包括：

设置项	默认值	用途
CLAUDE_MEM_MODEL	claude-haiku-4-5-20251001	摘要/观察生成所用 AI 模型
CLAUDE_MEM_WORKER_PORT	37700 + (uid % 100)	Worker 本地 HTTP 端口（按用户错开，避免多用户冲突）
CLAUDE_MEM_WORKER_HOST	127.0.0.1	Worker 监听地址
CLAUDE_MEM_CONTEXT_OBSERVATIONS	50	会话启动时注入的观察条数
CLAUDE_MEM_SKIP_TOOLS	若干工具名	记录观察时跳过的工具
CLAUDE_MEM_DATA_DIR	（用户目录）	数据目录（SQLite、日志）
CLAUDE_MEM_LOG_LEVEL	—	日志级别
CLAUDE_MEM_PROVIDER	claude	AI 提供方（另有 gemini、openrouter 等）
CLAUDE_MEM_SEMANTIC_INJECT / _LIMIT	—	会话启动时的语义检索注入开关与条数
CLAUDE_MEM_CHROMA_ENABLED / _MODE / _HOST / _PORT	—	Chroma 向量库连接（混合检索）
CLAUDE_MEM_CONTEXT_SHOW_READ_TOKENS 等展示类开关	—	控制上下文头部的 token 成本显示

完整键表与示例见 docs/public/configuration.mdx。

7.2 模式与语言：CLAUDE_MEM_MODE

Claude-Mem 通过 CLAUDE_MEM_MODE 同时控制工作流行为（如 code、chill、investigation）与生成观察所用的语言。编辑 ~/.claude-mem/settings.json：

{
  "CLAUDE_MEM_MODE": "code--zh"
}

模式定义在 plugin/modes/ 目录，本地查看已安装模式：

ls ~/.claude/plugins/marketplaces/thedotmack/plugin/modes/

原文档的示例表格（code 英文默认、code--zh 简体中文、code--ja 日语）在仓库中得到完整印证：plugin/modes/ 目录下共约 33 个模式文件，遵循 code--[lang] 命名（[lang] 为 ISO 639-1 语言码），除语言系列外还有 chill、email-investigation、law-study、meme-tokens 等专用工作流。例如 plugin/modes/code.json 声明了该模式的观察类型分类：bugfix、feature、refactor、change、discovery、decision、security_alert、security_note 等——这些类型正是 MCP search 工具中 obs_type 过滤参数的取值来源，形成了“模式定义 → 观察打标 → 按类型检索”的闭环。

注意：code--zh 已内置，无需额外安装或更新插件。修改模式后需重启 Claude Code 生效。

八、故障排查、Bug 报告与开发

• 自助诊断：遇到问题时直接把问题描述给 Claude，troubleshoot 技能会自动诊断并给出解决方案；常见问题的清单见 docs/public/troubleshooting.mdx。

• 自动化 Bug 报告：使用报告生成器（scripts/bug-report/ 提供采集器与 CLI）：

  cd ~/.claude/plugins/marketplaces/thedotmack
  npm run bug-report
  

• 开发：构建、测试与贡献流程见 docs/public/development.mdx；贡献步骤为 fork → 建 feature 分支 → 带测试修改 → 更新文档 → 提 PR。

九、许可与边界

Claude-Mem 采用 Apache License 2.0 发布（LICENSE）。选择 Apache-2.0 的考虑是：持久化的 agent 记忆需要能够顺畅嵌入开发者工具、本地 agent、MCP 服务器、企业系统、机器人栈与生产级 agent 框架。许可证范围与开源/商业使用的边界说明见 docs/license.md 与 docs/ip-boundary.md。另注：ragtime/ 目录单独采用 Apache License 2.0，见 ragtime/LICENSE。

十、延伸阅读地图

主题	仓库内文档
安装指南	docs/public/installation.mdx
系统架构总览	docs/public/architecture/overview.mdx
Hooks 参考	docs/public/hooks-architecture.mdx
Worker 服务	docs/public/architecture/worker-service.mdx
数据库与 FTS5	docs/public/architecture/database.mdx
混合检索架构	docs/public/architecture/search-architecture.mdx
搜索工具用法	docs/public/usage/search-tools.mdx
配置全表	docs/public/configuration.mdx
故障排查	docs/public/troubleshooting.mdx
分支策略	docs/public/branches.mdx

适用前提：本文所有命令、参数与默认值均以当前仓库实际内容为准（package 版本 13.24.0、Node ≥ 20）；不同发行分支（main / core-dev / community-edge）行为可能存在差异，请以对应分支的文档为准。