Claude-Mem 深度指南：跨会话持久上下文、Hooks 数据流与 MCP 三层记忆搜索工作流

Claude-Mem 是一个为 Claude Code 构建的"持久化记忆压缩系统"：它在每次会话中自动捕获工具使用观察（observations），用 AI 压缩成语义化摘要，并在未来会话启动时把相关上下文重新注入给 Agent。本文基于仓库中的丹麦语版 README（docs/i18n/README.da.md）及其对应的源码实现，完整讲解安装方式、六条 Hooks 生命周期数据流、SQLite/Chroma 存储架构、MCP 三层搜索工作流，以及 CLAUDE_MEM_MODE 多语言模式配置，帮助你在自己的项目中落地"跨会话不失忆"的 Agent 工作流。

一、Claude-Mem 是什么

用仓库原文的话说：Claude-Mem 通过在会话结束时自动捕获工具使用观察、生成语义化摘要（semantic summaries），并使其在未来会话中可检索，从而在会话之间无缝保留上下文。这让 Claude 在会话结束或断开重连后依然能维持对项目知识的连续性。

官方文档（丹麦语版 README）列出的核心能力包括：

• 持久化记忆（Persistent Memory）：上下文跨会话存活；
• 渐进式披露（Progressive Disclosure）：分层获取记忆，并让 token 开销可见；
• 技能化搜索（Skill-based Search）：通过 mem-search 技能用自然语言查询项目历史；
• Web Viewer UI：在 Worker 启动时打印的 URL 上实时查看记忆流；
• Claude Desktop 技能：在 Claude Desktop 对话中检索记忆；
• 隐私控制：用 <private> 标签将敏感内容排除在存储之外；
• 上下文配置：精细控制哪些上下文会被注入；
• 全自动运行：无需人工干预；
• 引用（Citations）：通过 Worker API 用 ID 引用历史观察，或在 Web Viewer 中浏览全部记录。

---

二、快速开始

2.1 安装

最简安装只需一条命令：

npx claude-mem install

按目标环境安装：

# 安装到 OpenCode
npx claude-mem install --ide opencode

# 安装到 Antigravity CLI
npx claude-mem install --ide antigravity

也可以在 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 命令。

2.2 OpenClaw Gateway 安装

如果要把 claude-mem 作为持久记忆插件安装到 OpenClaw 网关上，可用一条 curl 命令完成：

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

安装器会自动处理依赖、插件配置、AI 供应商配置、worker 启动，以及可选的 Telegram / Discord / Slack 实时观察流。仓库中 openclaw/ 目录包含该插件的完整实现与测试脚本（如 openclaw/install.sh、openclaw/e2e-verify.sh）。

2.3 系统要求

• Node.js：20.0.0 或更高（对应 package.json 中的 node >= 20.0.0 约束）；
• Claude Code：支持插件（plugin）机制的版本；
• Bun：JavaScript 运行时兼进程管理器，缺失时自动安装；
• uv：Python 包管理器，用于向量搜索，缺失时自动安装；
• SQLite 3：用于持久化存储（随包附带）。

2.4 Windows 注意事项

在 PowerShell 中若看到类似错误：

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

说明 Node.js 与 npm 未安装或未加入 PATH。从 nodejs.org 下载最新的 Node.js 安装包，安装后重启终端即可。

---

三、架构：五条生命周期 Hooks 如何驱动记忆数据流

README 给出的核心组件清单是：

1. 5 条生命周期 Hooks —— SessionStart、UserPromptSubmit、PostToolUse、Stop、SessionEnd（共 6 个 hook 脚本）；
2. Smart Installation（智能安装） —— 带缓存的依赖检查器（属于 pre-hook 脚本，不是生命周期 Hook）；
3. Worker Service —— 本地 HTTP API，带 Web Viewer UI 与搜索端点，由 Bun 托管；
4. SQLite 数据库 —— 存储会话、观察与摘要；
5. mem-search 技能 —— 自然语言查询 + 渐进式披露；
6. Chroma 向量数据库 —— 混合语义 + 关键词检索，实现智能上下文召回。

更完整的组件与数据流说明见 docs/public/architecture/overview.mdx，Hooks 机制详解见 docs/public/architecture/hooks.mdx。

3.1 从源码看真实的 Hook 注册表

仓库中的 plugin/hooks/hooks.json 是这份"数据流地图"的权威来源。当前版本实际注册了 6 个 Hook 事件，每一个都通过 bun-runner.js 调用 worker-service.cjs 的对应子命令：

Hook 事件	Matcher	worker 子命令	超时/模式	职责
Setup	*	version-check.js	300s	缓存式依赖检查（即"Smart Installation"），而非生命周期 Hook
SessionStart	startup|clear|compact	worker-service.cjs start + hook claude-code context	60s	拉起 worker 服务；然后把历史记忆上下文注入新会话
UserPromptSubmit	—	hook claude-code session-init	60s	用户提交 prompt 时初始化会话记录
PostToolUse	*	hook claude-code observation	120s，async: true	每次工具调用后异步生成/追加观察
PreToolUse	Read	hook claude-code file-context	60s，async: true	读取文件前注入该文件相关的历史上下文
Stop	—	hook claude-code summarize	120s，async: true	会话停止时生成进度摘要（summary）

几个值得注意的实现细节：

• 异步化观察：PostToolUse 与 Stop 都标记为 "async": true，观察与摘要生成不阻塞主会话，这与 README"自动运行、零人工干预"的承诺一致；
• 插件版本自解析：每条 Hook 命令的 shell 脚本都会先扫描 ~/.claude/plugins/cache/thedotmack/claude-mem/ 下的版本目录、按语义化版本排序选择最新非孤儿（无 .orphaned_at 标记）的缓存，再回落到 marketplaces/thedotmack/plugin，保证多版本共存时总是命中正确的脚本；
• 上下文注入入口：SessionStart 的第二条命令 hook claude-code context 正是"历史记忆回到新会话"的关键路径，MCP 侧对应的 session_start_context 工具会调用 worker 的 /api/context/inject 渲染完全相同的注入文本（见 src/servers/mcp-server.ts）。

3.2 Worker Service 与存储层

Worker Service 是本地 HTTP 服务，由 Bun 作为运行时与进程管理器托管，同时提供 Web Viewer UI（实时记忆流）和搜索端点。其架构文档见 docs/public/architecture/worker-service.mdx。

存储分两层：

• SQLite：主存储，保存会话（sessions）、观察（observations）、摘要（summaries），内置 FTS5 全文索引。Schema 与检索细节见 docs/public/architecture/database.mdx；
• Chroma 向量数据库：叠加语义向量检索，与全文检索组成混合搜索（hybrid search），为上下文召回排序。见 docs/public/architecture/search-architecture.mdx。

---

四、MCP 搜索工具：token 高效的三层工作流

Claude-Mem 通过 MCP 工具暴露记忆检索，遵循一个 token 高效的 3 层工作流模式（3-Layer Workflow）：

1. search —— 拿到带 ID 的紧凑索引（约 50–100 tokens/条结果）；
2. timeline —— 查看某个结果前后的时间线上下文；
3. get_observations —— 只对筛选后的 ID 拉取完整详情（约 500–1000 tokens/条）。

使用方式：Claude 用 search 获得结果索引 → 用 timeline 观察特定观察前后发生了什么 → 用 get_observations 批量取详情。先过滤再取详情，可节省约 10 倍 token。

官方示例：

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

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

// 第 3 步：批量拉取完整详情
get_observations(ids=[123, 456])

更详细的示例见 docs/public/usage/search-tools.mdx。

4.1 源码中的工具定义与参数全集

MCP 工具集中在 src/servers/mcp-server.ts 的 tools 数组中定义。值得注意的第一个工具是 important_workflow（L438-L471）——它没有实际查询逻辑，只是一个"自我说明书"工具，把三层工作流原样喂给调用方 Agent，强制其遵守"绝不未过滤就取详情"的约束，这就是"渐进式披露"哲学在协议层的落地。

search 工具的完整入参（L474-L523）：

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

timeline（L524-L541）支持 anchor（观察 ID）或直接给 query 自动定位锚点，depth_before / depth_after 默认各取 3 条；get_observations（L542-L560）要求 ids 数组参数，底层转发到 worker 的 /api/observations/batch，所以批量 ID 是一次 HTTP 调用。

此外，服务端运行时（server-beta）还额外暴露了 observation_add、observation_record_event、observation_search、observation_context 等 observation_* 工具，走 Postgres + GIN tsvector 索引的 /v1/* REST 路径（L583-L659）；search 工具内部也会在服务端可用且查询不含本地 Worker 才支持的过滤器时，自动路由到 PG 后端的 /v1/search——从这段分支逻辑可以推断，检索链路对"本地 SQLite + Chroma"与"服务端 Postgres"两种部署形态做了透明的双轨适配。

4.2 观察类型从哪里来

search(type="bugfix") 这类过滤值的定义不在 MCP 层，而在模式文件里。默认的 plugin/modes/code.json 精确约束了 9 种观察类型（observation_types）：bugfix、feature、refactor、change、discovery、decision、security_alert、security_note、sensitive，以及 7 种知识维度（concepts）：how-it-works、why-it-exists、what-changed、problem-solution、gotcha、pattern、trade-off。观察生成的提示词（observer 系统提示、跳过规则、XML 输出格式）也全部定义在该模式的 prompts 区块中——模式文件是"观察长什么样"的单一事实来源。

---

五、配置：settings.json 与 CLAUDE_MEM_MODE

5.1 配置文件

设置集中在 ~/.claude-mem/settings.json（首次运行自动以默认值创建），可配置项包括：AI 模型、worker 端口、数据目录、日志级别、上下文注入选项。完整参数清单与示例见 docs/public/configuration.mdx。

5.2 用 CLAUDE_MEM_MODE 切换工作流与语言

CLAUDE_MEM_MODE 同时控制两件事：

• 工作流行为（code、chill、investigation 等）；
• 生成观察所用的语言。

编辑 ~/.claude-mem/settings.json：

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

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

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

README 给出的基础模式表：

模式	说明
code	默认英语模式
code--zh	简体中文模式
code--ja	日语模式

语言模式的命名约定是 code--[lang]，[lang] 为 ISO 639-1 语言代码（zh 中文、ja 日语、es 西班牙语……）。code--zh 已内置，无需额外安装或升级插件。模式体系详解见 docs/public/modes.mdx。

5.3 从源码看模式加载与继承机制

模式加载由 src/services/domain/ModeManager.ts 实现，几个关键机制：

• 模式搜索路径（L16-L27）：依次查找环境变量 CLAUDE_MEM_MODES_DIR → 用户数据目录 modes/（跨插件升级持久化的用户自建模式）→ 包内 modes/ → 开发布局 plugin/modes，取第一个存在的 ${modeId}.json；
• 一级继承（parseInheritance）：parent--override 形式的模式 ID 会被拆成父模式 + 覆盖模式做 深度合并（deepMerge），且只支持一层继承，a--b--c 会直接抛错；
• 安全回退：找不到指定模式文件时回落到 code 模式，而不是让 worker 崩溃；
• ID 合法性：模式 ID 必须匹配 ^[a-z0-9]+(?:-[a-z0-9]+)*(?:--[a-z0-9]+(?:-[a-z0-9]+)*)?$，这也是 code--zh 这类命名的来源约束。

当前仓库 plugin/modes/ 目录实际内置的模式比 README 示例表丰富得多：除 code 外，还有 29 个语言变体（code--ar、code--bn、code--da、code--de、code--es、code--fr、code--ru、code--sv、code--zh 等，覆盖阿拉伯语到越南语），以及非代码场景模式 code--chill、email-investigation、law-study、law-study--chill（继承示例）和 meme-tokens。

重要：修改 CLAUDE_MEM_MODE 之后必须重启 Claude Code 才能生效。

---

六、Release 分支、开发、排障与 Bug 报告

6.1 三条 Release 分支

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

只有 main 会发布到 npm，其余两条需要从源码运行。分支流程与本地运行方式见 docs/public/branches.mdx。

6.2 开发与贡献

构建、测试与贡献工作流见 docs/public/development.mdx。贡献流程：Fork 仓库 → 建特性分支 → 带测试地修改 → 更新文档 → 提交 Pull Request。

6.3 故障排除

遇到问题时，直接把问题描述给 Claude，troubleshoot 技能会自动诊断并给出修复。常见问题清单见 docs/public/troubleshooting.mdx。

6.4 自动化 Bug 报告

在插件目录中运行生成器，自动收集环境信息生成结构化缺陷报告：

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

对应源码为 scripts/bug-report/（cli.ts 入口 + collector.ts 信息收集器）。

---

七、许可与边界

Claude-Mem 采用 Apache License 2.0 许可（见 LICENSE）。官方选择 Apache-2.0 的理由是：持久的 Agent 记忆应当容易嵌入开发者工具、本地 Agent、MCP 服务器、企业系统与生产级 Agent 框架。

• 许可范围与"开源 vs 商业"的边界说明：docs/license.md、docs/ip-boundary.md；
• Ragtime 特别说明：ragtime/ 目录同样在 Apache 2.0 下许可，详见 ragtime/LICENSE，其向量时间序列检索实现见 ragtime/ragtime.ts。

---

八、延伸阅读（仓库内文档索引）

主题	文档
安装（快速 + 进阶）	docs/public/installation.mdx
使用入门	docs/public/usage/getting-started.mdx
搜索工具详解	docs/public/usage/search-tools.mdx
上下文工程原则	docs/public/context-engineering.mdx
渐进式披露哲学	docs/public/progressive-disclosure.mdx
架构总览与数据流	docs/public/architecture/overview.mdx
从 v3 到 v5 的架构演进	docs/public/architecture-evolution.mdx
Hooks 参考（7 个 hook 脚本）	docs/public/architecture/hooks.mdx
Worker Service（HTTP API 与 Bun 管理）	docs/public/architecture/worker-service.mdx
SQLite Schema 与 FTS5	docs/public/architecture/database.mdx
Chroma 混合搜索架构	docs/public/architecture/search-architecture.mdx
全部配置项	docs/public/configuration.mdx

一句话总结：Claude-Mem 的工程骨架是"Hooks 捕获 → Observer 压缩 → SQLite/Chroma 双存储 → 三层 MCP 检索 → SessionStart 回注"的闭环；理解 plugin/hooks/hooks.json 的六条 Hook 与 src/servers/mcp-server.ts 的工具定义，基本就掌握了它的全部行为面。