Claude-Mem 跨会话持久记忆系统：安装、生命周期 Hook 与 MCP 三层搜索工作流实践

Claude-Mem（现已更名为 Grok Mem，npm 包名仍为 claude-mem）是一个为 AI 编程代理设计的持久记忆压缩系统：它自动捕获会话中的工具调用观察（observations），用 AI 压缩成语义摘要，并在后续会话启动时把相关上下文重新注入。读完本文，你将掌握它的完整安装方式（含 OpenCode、Antigravity、Claude Code 插件市场与 OpenClaw 网关）、7 个生命周期 Hook 的触发链路、settings.json 的关键配置项（含 CLAUDE_MEM_MODE 多语言模式），以及 search → timeline → get_observations 三层 MCP 搜索工作流的用法与 Token 优化原理。

核心特性

Claude-Mem 通过自动捕获工具使用观察、生成语义摘要并在未来会话中复用它们，让上下文在会话之间无缝延续。即使会话结束或重连，代理也能保持对项目知识的连续性。其核心特性包括：

• 持久记忆：上下文在会话之间存活，跨会话保留项目知识；
• 渐进式披露（Progressive Disclosure）：分层记忆访问，带有 Token 成本可见性——先看索引，再按需取详情；
• 技能化搜索：通过 mem-search 技能以自然语言查询项目历史；
• Web 查看器界面：在启动时打印的 Worker URL 中查看实时记忆流；
• Claude Desktop 技能：从 Claude Desktop 对话中搜索记忆；
• 隐私控制：使用 <private> 标签把敏感内容排除在存储之外；
• 上下文配置：对注入哪些上下文拥有细粒度控制；
• 自动运行：无需人工干预，全程由 Hook 驱动；
• 引用：通过 Worker API 使用 ID 引用历史观察，或在 Web 查看器中浏览全部。

快速开始：四种安装方式

单命令安装

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/库——它不会注册插件 Hook，也不会安装 Worker 服务。请始终使用 npx claude-mem install 或上面的 /plugin 命令完成安装。

从 package.json 可以确认这一区分：bin 字段指向 ./dist/npx-cli/index.js，即 npx claude-mem 实际执行的是仓库 src/npx-cli/ 下的安装器 CLI，而非直接引入库本身；files 字段同时打包了 plugin/hooks、plugin/modes、plugin/skills 等插件资产，这正是安装器负责注册到用户目录的部分。

OpenClaw 网关一键安装

将 Claude-Mem 作为持久记忆插件安装到 OpenClaw 网关：

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

该安装器会管理依赖、插件安装、AI 提供方配置、Worker 启动，以及向 Telegram、Discord、Slack 等的可选实时观察流。仓库内的 openclaw/ 目录包含对应的插件实现（含 openclaw.plugin.json、E2E 验证脚本与 SSE 消费者测试），仓库根目录的 openclaw/install.sh 与 openclaw/e2e-verify.sh 可供深入查看其安装与验证流程。

工作原理：六个核心组件与 Hook 链路

文档列出的核心组件为：

1. 5 个生命周期 Hook —— SessionStart、UserPromptSubmit、PostToolUse、Stop、SessionEnd（共 6 个 Hook 脚本）；
2. 智能安装（Setup） —— 带缓存的依赖检查器（前置 Hook 脚本，不属于生命周期 Hook）；
3. Worker 服务 —— 本地 HTTP API，含 Web 查看器界面与搜索端点，由 Bun 管理进程；
4. SQLite 数据库 —— 存储会话、观察与摘要；
5. mem-search 技能 —— 带渐进式披露的自然语言查询；
6. Chroma 向量数据库 —— 混合语义 + 关键词的智能上下文检索。

plugin/hooks/hooks.json 是上述 Hook 声明的实际落点，从中可以看到完整注册表：

Hook 事件	触发条件	执行的 Worker 命令	超时
Setup	始终（matcher *）	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	任意工具（matcher *，异步）	hook claude-code observation（捕获观察）	120s
PreToolUse	Read 工具（异步）	hook claude-code file-context（文件读取门控）	60s
Stop	回合结束（异步）	hook claude-code summarize（生成摘要）	120s

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

• 每个 Hook 命令内嵌了一段版本解析逻辑：优先使用 CLAUDE_PLUGIN_ROOT，否则按语义化版本倒序枚举 ~/.claude/plugins/cache/thedotmack/claude-mem/ 下的缓存目录，最终回落到 ~/.claude/plugins/marketplaces/thedotmack/plugin——这保证了陈旧缓存目录不会覆盖新版本的 Worker；
• PostToolUse 与 Stop 均声明 "async": true，避免阻塞代理主流程；观察捕获（observation）与摘要生成（summarize）都在后台完成；
• 所有 Hook 统一通过 node bun-runner.js worker-service.cjs <command> 形式调用，由 bun-runner 按需保证 Bun 运行时可用，这正是系统要求中"Bun 缺失时自动安装"的落点。

Worker 侧的进程与存储由 src/services/worker-service.ts、src/services/sqlite/ 等模块实现；插件打包后的 SQLite 会话层见 plugin/sqlite/SessionStore.js。

MCP 搜索工具：三层 Token 高效工作流

Claude-Mem 通过 MCP（Model Context Protocol）工具暴露智能记忆搜索，遵循 Token 高效的 3 层工作流：

1. search —— 获取带 ID 的紧凑索引（约 50–100 token/条结果）；
2. timeline —— 获取感兴趣结果周围的时序上下文；
3. get_observations —— 仅对筛选后的 ID 获取完整详情（约 500–1000 token/条结果）。

先过滤再取详情，可带来 约 10 倍 Token 节省。

工具参数详解（源码级）

以下参数定义来自 src/servers/mcp-server.ts 中的工具 schema（L474–L560），可直接作为调用参考：

search —— 全文搜索记忆索引：

参数	类型	说明
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 —— 获取锚点周围的时序上下文：

参数	类型	说明
anchor	number	作为时间线中心的观察 ID
query	string	用查询自动定位锚点（与 anchor 二选一）
depth_before	number	锚点前取多少条（默认 3）
depth_after	number	锚点后取多少条（默认 3）
project	string	按项目名过滤

get_observations —— 按 ID 批量取完整详情：

参数	类型	说明
ids	number[]	观察 ID 数组（必填，2 条以上务必批量处理）

示例调用：

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

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

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

MCP 服务器还内置了一个 important_workflow 工具，其返回内容本身就是给代理的工作流说明书（"3-LAYER WORKFLOW (ALWAYS FOLLOW)… NEVER fetch full details without filtering first. 10x token savings"，见 src/servers/mcp-server.ts）。三个工具在本地 Worker 模式下分别转发到 /api/search、/api/timeline、/api/observations/batch 端点；从源码结构看，search 在 server-beta 运行时且无本地 Chroma 时，会改走 Postgres 支撑的 /v1/search 路径，但仅在不存在 /v1/search 无法处理的过滤器（project、obs_type、日期等）时才路由过去，否则会保持本地 Worker 路径——这是保证过滤器不被静默丢弃的路由策略。

配置：settings.json 与多语言模式

配置统一由 ~/.claude-mem/settings.json 管理（首次运行时自动创建，写入默认值）。你可以配置 AI 模型、Worker 端口、数据目录、日志级别和上下文注入参数。关键默认值可从 src/shared/SettingsDefaultsManager.ts 确认：

配置键	默认值	说明
CLAUDE_MEM_MODEL	claude-haiku-4-5-20251001	观察/摘要生成使用的模型
CLAUDE_MEM_MODE	code	工作流模式（含语言），见下文
CLAUDE_MEM_WORKER_PORT	37700 + (uid % 100)	Worker HTTP 端口，按用户偏移避免多用户冲突
CLAUDE_MEM_WORKER_HOST	127.0.0.1	Worker 绑定地址
CLAUDE_MEM_DATA_DIR	~/.claude-mem	数据目录
CLAUDE_MEM_LOG_LEVEL	INFO	日志级别
CLAUDE_MEM_CONTEXT_OBSERVATIONS	50	注入的观察数量
CLAUDE_MEM_CONTEXT_SESSION_COUNT	10	注入的会话数量
CLAUDE_MEM_PROVIDER	claude	AI 提供方（无头安装默认；另有 Gemini、OpenRouter 等）
CLAUDE_MEM_CHROMA_ENABLED	true	设为 false 可禁用 Chroma，退化为纯 SQLite 搜索
CLAUDE_MEM_SKIP_TOOLS	ListMcpResourcesTool,SlashCommand,Skill,TodoWrite,AskUserQuestion	不产生观察的工具列表
CLAUDE_MEM_MAX_CONCURRENT_AGENTS	2	最大并发 Claude SDK 代理子进程

CLAUDE_MEM_WORKER_PORT 的默认值是一个计算表达式 37700 + (uid % 100)——从源码看，这样同一台机器上不同系统用户各自得到错开的端口，避免 Worker 端口抢占。

模式与语言配置

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--[语言] 命名规则，其中 [语言] 为 ISO 639-1 代码（如 zh、ja、es）。当前仓库 plugin/modes/ 下实际提供 27 个语言变体（含 code--zh.json、code--ja.json、code--tr.json 等），另有 email-investigation.json、law-study.json 等专题模式——远超文档表格所列的 code / code--zh / code--ja 三个。code--zh（简体中文）已内置，无需额外安装或插件更新。

切换模式后：请重启 Claude Code 使新配置生效。

系统要求与 Windows 安装注意事项

• Node.js：20.0.0 或更高（package.json 的 engines 实际声明为 node >=20.12.0、bun >=1.0.0）；
• Claude Code：支持插件的最新版本；
• Bun：JavaScript 运行时与进程管理器（缺失时自动安装）；
• uv：Python 包管理器，用于向量检索（缺失时自动安装）；
• SQLite 3：持久化存储（随 SQLite 内建提供）。

Windows 用户若看到如下错误：

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

请确认 Node.js 与 npm 已安装并加入 PATH，安装完成后重启终端再执行安装命令。

发布分支、排障与维护

发布分支：稳定版从 main 分支发布并推送到 npm；core-dev 与 community-edge 是用于早期可靠性修复与社区集成的源码运行分支，仅 main 会发布到 npm。仓库当前版本为 13.24.0（见 package.json）。

排障：遇到问题时，直接向 Claude 描述问题，troubleshoot 技能会自动诊断并给出修复建议。

Bug 报告：在插件目录中运行自动报告生成器：

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

该命令对应仓库 scripts/bug-report/ 下的 cli.ts 与 collector.ts 实现（package.json 中 "bug-report": "bun scripts/bug-report/cli.ts"）。

测试与开发：仓库使用 Bun 作为测试运行器，bun test tests 执行全量测试，测试覆盖 Hook IO 纪律、SQLite 会话存储、Worker HTTP 端点、MCP 工具可见性等（见 tests/）。Worker 日志可通过 bun plugin/scripts/worker-service.cjs logs 相关脚本查看。

许可与边界

Claude-Mem 采用 Apache License 2.0 许可——选择它是因为持久代理记忆需要能够方便地嵌入开发者工具、本地代理、MCP 服务器、企业系统乃至生产代理基础设施。范围与开放/商业边界见 LICENSE、docs/license.md 与 docs/ip-boundary.md。

关于 Ragtime：ragtime/ 目录单独以 Apache License 2.0 许可，详见 ragtime/LICENSE。

CMEM 说明：CMEM 是第三方铸造、被 Claude-Mem 作者（Alex Newman，@thedotmack）官方采纳的代币，定位为社区增长催化剂与触达工具的社区符号，与系统的安装、配置、开发流程无关。