claude-mem 跨会话持久记忆系统深解：从一键安装、生命周期 Hooks 到三层 MCP 搜索工作流

本文基于 claude-mem 仓库的阿拉伯语官方 README（docs/i18n/README.ar.md，由 translate-readme 脚本自动生成）整理而成，完整覆盖其快速安装、核心架构、MCP 搜索工具、配置与模式（Mode）机制，并结合仓库源码（hooks 注册、MCP 服务器、CLI 入口）逐一印证文档所述行为的真实实现，帮助你在 Claude Code、OpenCode、Antigravity CLI 或 OpenClaw 环境中把 claude-mem 装好、配好并用起来。

1. claude-mem 是什么

claude-mem 是一套为 AI 编码代理（尤其是 Claude Code）设计的跨会话持久记忆系统：它在会话过程中自动记录工具使用观察（observations），用 AI 将其压缩成语义摘要，并把这些上下文注入未来的会话，使代理在会话结束或断开重连后依然保有对项目知识的连续性。

仓库 package.json 中定义的当前版本为 13.24.0（README 徽章上的 13.4.0 为翻译快照时的旧版本号，以仓库实际为准），运行环境要求 Node.js >=20.12.0 且 bun >=1.0.0（见 engines 字段），许可证为 Apache 2.0。

1.1 核心特性一览

官方 README 列出的关键特性包括：

• 持久记忆（Persistent Memory）：上下文跨会话延续；
• 渐进式披露（Progressive Disclosure）：分层检索记忆，token 成本透明可控；
• 基于技能的搜索（mem-search Skill）：用自然语言查询项目历史，对应 plugin/skills/mem-search/SKILL.md；
• Web 查看器 UI：通过 worker 启动时打印的 worker URL 直播记忆内容，对应 plugin/ui/viewer.html；
• Claude Desktop 技能：从 Claude Desktop 对话中搜索记忆；
• 隐私控制：用 <private> 标签将敏感内容排除出存储；
• 上下文注入配置：精细控制注入新会话的上下文内容；
• 全自动化：安装后无需人工干预；
• 可引用性（Citations）：通过 worker HTTP API 按观察 ID 回溯，或在 Web 查看器中浏览全部记忆。

2. 快速开始

2.1 标准安装（Claude Code）

npx claude-mem install

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

重要提示：claude-mem 也发布在 npm 上，但 npm install -g claude-mem 只安装 SDK/库——不会注册插件 hooks，也不会配置 worker 服务。完整安装必须走 npx claude-mem install 或下文 /plugin 命令。

2.2 其他 IDE 的安装

针对 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

2.3 CLI 提供的完整命令面

从 src/npx-cli/index.ts 的帮助文本可以确认，npx claude-mem 支持比 README 更多的非交互参数与运维命令：

npx claude-mem install --provider claude|gemini|openrouter|host   # 非交互指定 LLM provider
npx claude-mem install --model <id>          # 指定 Claude 模型（provider=claude 时）
npx claude-mem install --no-auto-start      # 跳过结尾的 worker 自启动
npx claude-mem install --runtime worker|server   # 选择运行时（server 会拉起 Docker pg+redis 并注入 IDE MCP 配置）
npx claude-mem repair      # 重跑 Bun/uv 环境修复与插件缓存内的 bun install
npx claude-mem update      # 升级到最新版
npx claude-mem uninstall   # 移除插件与配置
npx claude-mem doctor       # 诊断 bun、uv、worker 的健康状态
npx claude-mem start|stop|restart|status   # worker 生命周期管理
npx claude-mem search <query>              # 直接搜索观察
npx claude-mem telemetry status|enable|disable  # 管理匿名遥测（默认开启，可退出）

支持的一等 IDE 标识符包括 claude-code、cursor、grok-bot、opencode、openclaw、antigravity 等。

2.4 OpenClaw 网关安装

将 claude-mem 作为 OpenClaw 网关上的持久记忆插件，官方提供一行式安装脚本（脚本内容即仓库内的 openclaw/install.sh）。该安装器会自动完成：依赖安装（要求 Bun >=1.1.14，见脚本头部 MIN_BUN_VERSION 常量）、插件配置、AI 供应商初始化、worker 启动，以及可选的将观察实时广播到 Telegram/Discord/Slack 等渠道。脚本支持的非交互参数包括：

--non-interactive      # 非交互模式
--upgrade              # 升级模式
--branch=<name>        # 指定安装分支
--provider=<name>     # 指定 AI 供应商
--api-key=<key>        # 指定 API key

OpenClaw 侧的技能与插件清单见 openclaw/SKILL.md、openclaw/openclaw.plugin.json。

3. 文档体系索引

阿拉伯语 README 将官方文档站点链接映射到本地仓库时，对应的 Markdown 源文件如下，可按需深入：

主题	仓库文档
安装指南（快速开始 + 进阶安装）	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 架构	docs/public/hooks-architecture.mdx、docs/public/architecture/hooks.mdx
Worker 服务（HTTP API + Bun 管理）	docs/public/architecture/worker-service.mdx
数据库（SQLite + FTS5 模式）	docs/public/architecture/database.mdx
搜索架构（Chroma 混合检索）	docs/public/architecture/search-architecture.mdx
配置与环境变量	docs/public/configuration.mdx
开发指南（构建/测试/贡献）	docs/public/development.mdx
发布分支策略	docs/public/branches.mdx
故障排查	docs/public/troubleshooting.mdx

4. 工作原理：六个核心组件

README 将系统归纳为六个组件：生命周期 Hooks、智能安装、Worker 服务、SQLite 数据库、mem-search 技能、Chroma 向量库。下面结合源码逐一验证。

4.1 生命周期 Hooks（真实注册表）

当前 hooks 注册表位于 plugin/hooks/hooks.json，采用「单一分发器 + 快速版本检查」的结构：除 Setup 外，所有事件都通过 bun-runner.js 启动 worker-service.cjs hook claude-code <event> 子命令。实际注册的事件与 docs/public/configuration.mdx 中的描述一致：

Hook 事件	matcher	分发到	作用	备注
Setup	*	version-check.js	子 100ms 的 .install-version 标记检查	不是生命周期 hook，属 Setup 阶段快速门
SessionStart	startup|clear|compact	worker-service.cjs start → hook ... context	先确保 worker 运行，再注入历史上下文	两个命令串行
UserPromptSubmit	—	hook claude-code session-init	会话初始化	—
PreToolUse	Read	hook claude-code file-context	文件读取前的上下文门	async: true
PostToolUse	*	hook claude-code observation	每次工具调用后捕获观察	async: true，timeout 120s
Stop	—	hook claude-code summarize	会话结束时生成摘要	async: true，timeout 120s

注意 README 文字中提到「SessionStart、UserPromptSubmit、PostToolUse、Stop、SessionEnd」5 个生命周期 hooks，而从当前 plugin/hooks/hooks.json 的结构看，实际落盘的是上述 6 个事件（含 Setup 与 PreToolUse(Read)），以仓库当前源码为准。此外，每条 hook 命令在运行前都会做一段路径解析：优先 CLAUDE_PLUGIN_ROOT，再按版本号排序扫描 ~/.claude/plugins/cache/thedotmack/claude-mem/[0-9]*/ 中非孤儿（无 .orphaned_at 标记）的缓存版本，最后回退到市场目录 ~/.claude/plugins/marketplaces/thedotmack/plugin，并在存在 cygpath 时做 Windows 路径转换——这正是 README 所称「智能安装：带缓存的依赖探测器」的体现。

4.2 Worker 服务与其余组件

• Worker 服务：本地 HTTP API，带 Web 查看器与搜索端点，由 Bun 作为常驻后台进程管理（worker-service.cjs start）。管理入口 plugin/scripts/worker-service.cjs；
• SQLite 数据库：存储 sessions、observations、summaries，路径为 ~/.claude-mem/claude-mem.db，插件侧核心实现在 plugin/sqlite/SessionStore.js；
• mem-search 技能：自然语言查询 + 渐进式披露，见 plugin/skills/mem-search/SKILL.md；
• Chroma 向量库：语义 + 关键词混合检索，通过 uv 管理的 Python 环境运行（缺失时自动安装）。

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

claude-mem 通过 4 个 MCP 工具提供记忆搜索，遵循 token 高效的三层工作流。MCP 服务器源码位于 src/servers/mcp-server.ts（构建产物为 plugin/scripts/mcp-server.cjs），其中可确认工具定义包括 important_workflow、search、timeline、get_observations。

5.1 三层工作流

1. search — 获取带 ID 的紧凑索引（约 50–100 tokens/条），先「调研有什么」；
2. timeline — 获取感兴趣结果前后的时间线上下文；
3. get_observations — 只为筛选出的 ID 拉取完整细节（约 500–1,000 tokens/条）。

第 4 个工具 important_workflow 是一个常驻可见的工作流提醒，自动展示、无需调用，帮助模型理解如何高效使用搜索工具。

用法示例（与 docs/public/usage/search-tools.mdx 一致）：

// Step 1: Search for index
search(query="authentication bug", type="bugfix", limit=10)

// Step 2: Review index, identify relevant IDs (e.g., #123, #456)

// Step 3: Fetch full details
get_observations(ids=[123, 456])

官方对比：一次性拉取 20 条完整观察约需 10,000–20,000 tokens；而「搜索索引 → 时间线 → 批量拉取 3 条详情」的三层路径总计约 2,500–4,000 tokens，官方据此宣称最高可达 10 倍的 token 节省。

5.2 各工具参数

search 参数（来自 docs/public/usage/search-tools.mdx）：

参数	说明
query	全文检索查询（支持 AND / OR / NOT、短语搜索）
limit	最大结果数（默认 20）
offset	跳过前 N 条，用于分页
type	按观察类型过滤：bugfix、feature、decision、discovery、refactor、change
obs_type	按记录类型过滤：observation、session、prompt
project	按项目名过滤
dateStart / dateEnd	日期范围过滤（YYYY-MM-DD）
orderBy	排序：date_desc、date_asc、relevance

timeline 参数：anchor（观察 ID，提供 query 时可省）、query（自动定位锚点）、depth_before / depth_after（默认各 3）、project。

get_observations 参数：ids（必填，ID 数组）、orderBy、limit、project。务必在单次调用中批量传入多个 ID，避免逐条请求。

5.3 查询语法与实战场景

query 支持 SQLite FTS5 语法：

query="authentication AND JWT"     # 两个词都要出现
query="OAuth OR JWT"               # 任一即可
query="security NOT deprecated"    # 排除项
query='"database migration"'       # 精确短语
query="title:authentication"       # 指定列：title / content / concepts
query='"user auth" AND (JWT OR session) NOT deprecated'  # 组合

文档给出的典型场景包括：排障（先 search 定位 bugfix 观察 → timeline 看修复前后发生了什么 → get_observations 拿细节）、复盘架构决策（type="decision"）、代码考古（追踪某文件何时被改动）、特性演化史（orderBy="date_asc"）、上下文恢复（离开项目后重新进入）等。

5.4 Token 成本参考

操作	每条结果约
search（索引）	50–100 tokens
timeline（每条观察）	100–200 tokens
get_observations（完整细节）	500–1,000 tokens

最佳实践：永远先 search 建索引；limit 从小开始（3–5）；用 type/date/project 先过滤再拉取；get_observations 永远批量；仅在需要叙事上下文时用 timeline。

5.5 底层技术栈

从 docs/public/usage/search-tools.mdx 确认：MCP 工具是对本地 Worker HTTP API 的薄封装——MCP 服务器把工具调用翻译成对 worker 服务的 HTTP 请求，由 worker 处理业务逻辑、数据库查询与 Chroma 向量搜索。全文检索基于 ~/.claude-mem/claude-mem.db 的 SQLite FTS5 索引。

6. 发布分支策略

稳定版从 main 分支发布并推送到 npm；core-dev 与 community-edge 两个分支仅供「从源码运行」，分别服务于早期的可靠性修复验证和社区集成实验。策略与分支间的不稳定运行说明见 docs/public/branches.mdx。

7. 系统要求

• Node.js：20.0.0+（package.json engines 实际要求 >=20.12.0，另有 bun >=1.0.0）；
• Claude Code：支持插件（plugin）机制的最新版本；
• Bun：JavaScript 运行时兼进程管理器，缺失时自动安装；
• uv：向量检索所需的 Python 包管理器，缺失时自动安装；
• SQLite 3：持久化存储（内置）。

Windows 环境说明

若遇到如下错误：

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

说明 Node.js/npm 未安装或未加入 PATH。请安装最新的 Node.js 安装包并在安装后重启终端。

8. 配置

配置集中在 ~/.claude-mem/settings.json，首次运行时自动以默认值创建。核心设置项（完整表格见 docs/public/configuration.mdx）：

设置项	默认值	说明
CLAUDE_MEM_MODEL	claude-haiku-4-5-20251001	压缩观察所用的 Claude 模型（provider=claude 时）
CLAUDE_MEM_PROVIDER	claude	AI 供应商：claude、gemini、openrouter
CLAUDE_MEM_CLAUDE_AUTH_METHOD	subscription	Claude 认证方式：subscription、api-key、gateway
CLAUDE_MEM_MODE	code	激活的模式配置（如 code--es、email-investigation）
CLAUDE_MEM_CONTEXT_OBSERVATIONS	50	注入的观察条数
CLAUDE_MEM_WORKER_PORT	37700 + (uid % 100)	worker 端口（按用户取模的默认值，可覆盖为固定端口）
CLAUDE_MEM_WORKER_HOST	127.0.0.1	worker 监听地址
CLAUDE_MEM_DATA_DIR	~/.claude-mem	数据根目录——数据库、chroma、日志、settings.json、worker.pid 全部由此派生
CLAUDE_MEM_LOG_LEVEL	INFO	日志级别：DEBUG、INFO、WARN、ERROR、SILENT
CLAUDE_MEM_PYTHON_VERSION	3.13	chroma-mcp 使用的 Python 版本
CLAUDE_MEM_SKIP_TOOLS	ListMcpResourcesTool,SlashCommand,Skill,TodoWrite,AskUserQuestion	逗号分隔的、排除在观察之外的工具
CLAUDE_MEM_FOLDER_CLAUDEMD_ENABLED	false	是否自动生成文件夹级 CLAUDE.md

Claude 模型可选值：claude-haiku-4-5-20251001（默认，最快，适合压缩）、claude-sonnet-5（均衡）、claude-opus-4-8（质量最高、最慢）；npx claude-mem install 交互过程中会提示选择并把结果持久化进 settings.json。

数据目录结构：

~/.claude-mem/
├── claude-mem.db           # SQLite 数据库
├── .install-version        # 安装版本标记（由 npx claude-mem install/repair 写入）
├── settings.json           # worker 端口 + 供应商/模型设置
└── logs/
    ├── worker-out.log      # worker stdout
    └── worker-error.log   # worker stderr

8.1 模式与语言设置（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 语言代码。从仓库 plugin/modes/ 目录实际看，可用模式远不止这三种：还包括 code--chill、code--es、code--fr、code--de、code--ko、code--ar、code--ru 等约 30 个语言变体，以及非语言的工作流模式如 email-investigation、law-study、meme-tokens。

修改模式后需重启 Claude Code 使设置生效。

9. 故障排查与错误报告

遇到故障时，直接把你的问题描述给 Claude——其内置的 troubleshoot 技能会自动诊断并给出解决方案；常见问题的完整清单见 docs/public/troubleshooting.mdx。

生成结构化错误报告使用仓库自带的生成器（实现位于 scripts/bug-report/cli.ts、scripts/bug-report/collector.ts）：

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

该命令对应 package.json 中的 "bug-report": "bun scripts/bug-report/cli.ts" 脚本。另外，npx claude-mem doctor 可以快速诊断 bun、uv、worker 三者的安装与健康状态；worker 日志可通过 npm run worker:logs（即 scripts/worker-logs.cjs）查看，--follow 可实时跟踪。

10. 开发与贡献

构建、测试与贡献流程见 docs/public/development.mdx。package.json 提供了完整的开发脚本面：npm run build（同步插件清单 + 构建 hooks + 生成 lockfile）、npm test（bun test tests，仓库含数百个测试文件，覆盖 sqlite、worker、server、telemetry 等模块）、npm run typecheck、npm run dev（构建 + 同步市场 + 重启 worker）、npm run translate-readme（本阿拉伯语 README 即由该脚本从英文 README 翻译生成，支持 zh、ja、ar 等 30 个语言的分层批量翻译）。

贡献流程：Fork 仓库 → 创建特性分支 → 带测试地修改代码 → 更新文档 → 提交 Pull Request。发布方面，claude-mem 从三个分支出包：main（稳定，发布到 npm）、core-dev、community-edge（从源码运行）。

11. 许可证与支持

claude-mem 采用 Apache 2.0 许可证。选择该许可的原因：持久代理记忆（durable agentic memory）应当能够轻松被嵌入开发者工具、本地代理、MCP 服务器、企业系统与生产级代理框架。完整条款见 LICENSE；许可证范围与开源/商业边界的说明见 docs/license.md 和 docs/ip-boundary.md。

注意：仓库内的 ragtime/ 目录同样采用 Apache 2.0 许可证，见 ragtime/LICENSE。

社区支持入口：仓库 docs/ 目录（本仓库的官方文档源）、GitHub Issues（缺陷与讨论）、Discord 官方社区。项目作者为 Alex Newman（@thedotmack）。

11.1 关于 CMEM

README 末尾说明：CMEM 是第三方创建的代币，但获得 claude-mem 作者 Alex Newman 的官方背书，作为社区增长激励与向开发者/知识工作者推广 CMEM 的渠道。其官方合约地址（BASE 链）：0x76b1967eec0ccaeb001bbbb2b40dc4badba31ba3。