Claude-Mem：为 Claude Code 构建跨会话持久记忆——安装、Hooks 架构与 MCP 三层记忆检索实战

Claude-Mem 是一个为 Claude Code 等 AI 编码代理打造的"记忆压缩系统"：它通过生命周期 Hooks 自动捕获工具使用过程，将工作内容压缩为结构化的观察（observation）与进度摘要存入 SQLite，再在下一次会话启动时把相关上下文注入回来，让代理在多次会话之间保持对项目的知识连续性。读完本文，你将掌握 Claude-Mem 的四种安装方式、由 5 个生命周期 Hook 驱动的数据采集链路、search → timeline → get_observations 三层 MCP 检索工作流的真实参数，以及通过 CLAUDE_MEM_MODE 切换工作流模式与观察语言的完整配置方法。

1. 项目定位与核心特性

Claude-Mem 的核心主张是：上下文不应随会话结束而消失。它在后台持续运行一个"观察者"代理，监视你正在进行的 Claude Code 会话中的工具调用，把"学了什么、修了什么、部署了什么、配置了什么"沉淀为可全文/向量检索的记忆，并在后续会话的 SessionStart 阶段自动注入。

官方文档（本仓库的 Norwegian 版 README docs/i18n/README.no.md）列出的关键特性包括：

• 持久记忆（Vedvarende Minne）：上下文在会话之间存活，跨会话保持项目知识；
• 渐进式披露（Progressiv Avsløring）：分层获取记忆，token 成本透明可控；
• mem-search 技能：用自然语言询问项目历史；
• 浏览器 UI：在 worker 启动时打印的 URL 上查看实时记忆流；
• 隐私控制：用 <private> 标签把敏感内容排除在持久化存储之外；
• 上下文注入配置：精细控制每次会话注入哪些内容；
• 来源引用：通过 worker API 用 ID 引用历史观察，或在 Web Viewer 中浏览全部记忆。

需要特别区分的一点：Claude-Mem 虽发布在 npm 上，但 npm install -g claude-mem 只会安装 SDK/库，不会注册插件 Hooks、也不会启动 worker 服务。完整的插件安装必须走 npx claude-mem install 或 Claude Code 内的 /plugin 命令（见下文）。从 package.json 看，npm 包名即 claude-mem，当前仓库版本为 13.24.0，bin 入口指向 dist/npx-cli/index.js，引擎要求 Node >=20.12.0、Bun >=1.0.0。

2. 安装与快速开始

2.1 为 Claude Code 安装

npx claude-mem install

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

2.2 为 OpenCode / Antigravity CLI 安装

# OpenCode
npx claude-mem install --ide opencode

# Antigravity CLI（仓库内另有迁移计划文档 plans/2026-07-03-antigravity-cli-migration.md 记录该集成）
npx claude-mem install --ide antigravity

2.3 通过 Claude Code 插件市场安装

在 Claude Code 会话内直接执行：

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

2.4 作为 OpenClaw Gateway 的持久记忆插件

OpenClaw 集成支持一条 curl 命令完成安装（安装器负责依赖、插件配置、AI 供应商配置、worker 启动，以及可选的 Telegram/Discord/Slack 实时观察流）。仓库中的 openclaw/ 目录包含该插件的源码、openclaw.plugin.json 清单与端到端验证脚本（e2e-verify.sh）。

3. 核心架构：5 个生命周期 Hook + 智能预检

官方文档将核心组件归纳为 6 项：生命周期 Hooks、智能安装（缓冲的依赖检查）、Worker Service（Bun 管理的本地 HTTP API + 浏览器 UI）、SQLite 数据库、mem-search 技能、Chroma 向量数据库（混合语义 + 关键词检索）。

Hooks 的完整注册表位于 plugin/hooks/hooks.json。从源码结构看，实际注册的事件包括文档所说的 5 个生命周期事件 + 1 个 Setup 预检事件，每个事件最终都通过 node <plugin>/scripts/bun-runner.js <plugin>/scripts/worker-service.cjs hook claude-code <子命令> 委托给 worker 服务，具体如下：

Hook 事件	匹配器	worker 子命令	超时/特性	职责
Setup	*	version-check.js	300s	会话启动前的版本与依赖检查（属 pre-hook 脚本，非生命周期 Hook）
SessionStart	startup|clear|compact	worker-service.cjs start + context	60s	启动/复用 worker 服务，并注入上一次会话的上下文
UserPromptSubmit	—	session-init	60s	每轮用户提交时初始化/刷新会话状态
PostToolUse	*	observation	120s，async: true	每次工具调用后异步生成观察记录
PreToolUse	Read	file-context	60s，async: true	读取文件前的文件级上下文补充
Stop	—	summarize	120s，async: true	会话停止时生成进度摘要（checkpoint）

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

• 所有 hook 命令都先做插件根路径解析：优先使用 CLAUDE_PLUGIN_ROOT，否则在 ~/.claude/plugins/cache/thedotmack/claude-mem/ 下按语义化版本排序取最新缓存，并跳过带 .orphaned_at 标记的孤儿目录；在 Windows Git Bash 环境下还会用 cygpath -w 把路径转成 Windows 形式——这与 docs/bug-fixes/windows-spaces-issue.md 记录的 Windows 兼容工作一致。
• observation 与 summarize 均标记为 async: true，保证观察生成不阻塞主会话交互；超时上限（60–300s）由 src/shared/hook-constants.ts 统一维护。
• 默认跳过的工具列表由 CLAUDE_MEM_SKIP_TOOLS 控制（见 src/shared/SettingsDefaultsManager.ts 中的默认值：ListMcpResourcesTool,SlashCommand,Skill,TodoWrite,AskUserQuestion），避免无信息量的调用进入记忆。

3.1 数据存储与检索后端

• SQLite：持久化存储会话、观察与摘要，是默认检索后端；
• Chroma 向量库：默认开启（CLAUDE_MEM_CHROMA_ENABLED: 'true'），通过 uvx 拉起的持久化 chroma-mcp 进程提供混合语义检索；设为 'false' 则退化为纯 SQLite 检索；
• Worker Service：本地 HTTP API（默认绑定 127.0.0.1，端口按用户 ID 偏移自 37700 起分配，见 SettingsDefaultsManager 中 CLAUDE_MEM_WORKER_PORT 的计算逻辑），既承载 hook 的 hook claude-code * 子命令，也对外提供 /api/search、/api/timeline、/api/observations/batch 等检索端点和浏览器记忆流 UI。

4. MCP 搜索工具与三层工作流

Claude-Mem 通过 MCP 暴露记忆检索能力，遵循 token 高效的 3 层工作流模式（官方口径约为 10 倍 token 节省——先过滤、后取详情）。工具的正式定义在 src/servers/mcp-server.ts，其工具描述本身就把三步流程写进了 tools 元信息：

1. search —— 返回带 ID 的紧凑索引（约 50–100 tokens/条）；
2. timeline —— 围绕感兴趣的 ID 获取前后文（depth_before/depth_after 默认各 3 条）；
3. get_observations —— 仅为筛选后的 ID 批量拉取完整详情（约 500–1000 tokens/条，2 条以上务必批量传 ID）。

结合源码中各工具的 inputSchema，真实可用的参数如下：

工具	参数	说明
search	query	全文检索关键词
	limit	最大结果数（默认 20）
	project	按项目名过滤
	platformSource	按来源代理过滤（如 claude、codex、cursor），只看该代理自己的记忆
	type / obs_type	type 可取 observations/sessions/prompts；其余值按观察类型过滤。obs_type 支持逗号分隔多值（如 bugfix,feature）
	dateStart / dateEnd	ISO 日期范围
	offset / orderBy	分页偏移；date_desc 或 date_asc 排序
timeline	anchor 或 query	指定观察 ID 居中，或传查询自动定位锚点
	depth_before / depth_after	锚点前后各取多少条（默认 3）
	project	项目过滤
get_observations	ids（必填）	观察 ID 数组，走 worker 的 /api/observations/batch 批量端点

典型调用示例（即官方文档中的三步用法）：

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

// 步骤 2：审阅索引，识别相关 ID（例如 123、456）

// 步骤 3：只对这些 ID 拉取完整详情
get_observations(ids=[123, 456])

此外，MCP server 还提供 session_start_context 工具（调用 worker 的 /api/context/inject），可渲染出与 SessionStart hook 注入完全相同的上下文文本，便于排查"下次会话到底会看到什么"。检索行为的更多细节可参见仓库内的 docs/public/usage/search-tools.mdx 与 docs/public/architecture/search-architecture.mdx。

5. 模式与语言配置：CLAUDE_MEM_MODE

设置文件位于 ~/.claude-mem/settings.json（首次运行时自动以完整默认值生成——这一点可以从 src/shared/SettingsDefaultsManager.ts 的实现确认：新文件会写入每一个默认项，此后磁盘上的持久值优先于代码默认值）。

CLAUDE_MEM_MODE 一个设置同时控制两件事：工作流行为（如 code、code--chill、email-investigation、law-study）与生成观察所使用的语言。

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

模式文件位于仓库的 plugin/modes/。以默认的 plugin/modes/code.json 为例，一个模式定义包含三层内容：

• observation_types：9 种观察类型及其标签/emoji —— bugfix、feature、refactor、change、discovery、decision、security_alert、security_note、sensitive；观察器被强制要求只能从这 9 个值中选择；
• observation_concepts：7 个知识维度 —— how-it-works、why-it-exists、what-changed、problem-solution、gotcha、pattern、trade-off；
• prompts：观察器的完整提示词模板，包括"观察者角色"（单向记录、不得接触被观察会话）、"记录焦点"（只记录学到的/构建的/修复的/部署的/配置的，动词如 implemented、fixed、deployed、configured、migrated、optimized）、"跳过指引"（空状态检查、无错误的安装等例行操作直接跳过）以及 XML 输出结构。

语言型模式以 code--[ISO-639-1 语言码] 命名，如 code--zh（简体中文）、code--ja（日语）、code--es（西班牙语）等，仓库内共提供 26 种语言的 code--* 变体及 code--chill、meme-tokens 等行为变体。以挪威语模式 plugin/modes/code--no.json 为例，其实现方式正是覆写 prompts：把 XML 占位符替换为挪威语文本（Kort tittel som fanger kjernehandlingen...），并在观察与摘要提示词尾部追加 LANGUAGE REQUIREMENTS: Please write the observation data in norsk。修改模式后需重启 Claude Code 才能生效。

在 Claude Code 安装目录下可以本地查看已安装的全部模式：

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

code--zh 等语言模式随插件内置分发，无需额外安装或单独升级。

6. 隐私控制

文档提到的 <private> 标签机制在源码中对应 src/utils/tag-stripping.ts（标签剥离工具）与 plugin/sqlite/SessionStore.js 的入库路径：标记为 private 的内容不会进入可检索的记忆存储；配合观察类型 sensitive（"不完全是私密、但不应在错误语境中扩散的信息"，如内部 URL、未发布计划、客户名），构成两层敏感信息防线。相关策略的完整说明见 docs/public/usage/private-tags.mdx。

7. 配置、系统要求与故障排查

7.1 主要配置项（默认值来自 SettingsDefaultsManager）

配置项	默认值	说明
CLAUDE_MEM_MODE	code	工作流模式与观察语言
CLAUDE_MEM_DATA_DIR	~/.claude-mem	数据目录（SQLite 等）
CLAUDE_MEM_WORKER_HOST / CLAUDE_MEM_WORKER_PORT	127.0.0.1 / 37700 + 用户 ID 偏移	worker 监听地址
CLAUDE_MEM_MODEL	claude-haiku-4-5-20251001	观察生成所用模型
CLAUDE_MEM_CONTEXT_SESSION_COUNT	10	注入时回看的会话数
CLAUDE_MEM_CONTEXT_OBSERVATIONS	50	注入的观察条数上限
CLAUDE_MEM_SKIP_TOOLS	见 3.1	不产生观察的工具白名单
CLAUDE_MEM_CHROMA_ENABLED / CLAUDE_MEM_CHROMA_MODE	true / local	向量检索开关与本地/远端模式
CLAUDE_MEM_MAX_CONCURRENT_AGENTS	2	并发观察代理上限

完整配置参考可看仓库内的 docs/public/configuration.mdx 与 docs/public/installation.mdx。

7.2 系统要求

• Node.js：20.0.0 及以上（package.json 实际要求 >=20.12.0）；
• Claude Code：支持插件的最新版本；
• Bun：JavaScript 运行时兼进程管理器，缺失时自动安装；
• uv：Python 包管理器，用于向量检索（chroma-mcp），缺失时自动安装；
• SQLite 3：持久化存储，随环境提供。

Windows 注意事项：若在 PowerShell 中看到 npm : The term 'npm' is not recognized...，说明 Node.js/npm 未加入 PATH——安装最新版 Node.js 后需重新打开终端再执行安装命令。

7.3 故障排查与错误报告

出现问题时，可以直接把问题描述给 Claude，内置的 troubleshoot 能力会自动诊断并给出方案；常规故障对照见 docs/public/troubleshooting.mdx。

提交结构化错误报告使用自动化生成器：

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

生成器源码位于 scripts/bug-report/（CLI + 上下文采集器）。

8. 发布分支、许可证与边界

• 发布分支：稳定版从 main 发布到 npm；core-dev 与 community-edge 是源码运行分支，用于提前验证修复与社区集成，仅 main 进入 npm。分支策略详见 docs/public/branches.mdx 与 plans/2026-07-05-three-release-branches.md；
• 许可证：Claude-Mem 采用 Apache License 2.0（见 LICENSE），选择该许可的考量是持久化代理记忆应易于嵌入开发者工具、本地代理、MCP 服务器与生产级代理框架；开源与商业使用的边界见 docs/license.md 与 docs/ip-boundary.md；
• Ragtime 子目录：ragtime/ 是独立许可的组件，同样采用 Apache License 2.0，详见 ragtime/LICENSE。

9. 小结：从"每次从零开始"到"记忆驱动的代理"

Claude-Mem 的工程设计可以浓缩为一句话：用 5 个生命周期 Hook 做无感采集，用 SQLite + Chroma 做混合存储，用三层 MCP 工具做低 token 成本的按需取回，用 CLAUDE_MEM_MODE 做行为与语言的可插拔定制。其源码全部以 TypeScript 实现、基于 Claude Agent SDK 构建，plugin/hooks/hooks.json、src/servers/mcp-server.ts、src/shared/SettingsDefaultsManager.ts 与 plugin/modes/ 四个入口足以覆盖本文涉及的全部行为；若想继续深挖，可沿 docs/public/architecture/ 下的架构文档逐层阅读。