claude-mem 跨会话持久记忆系统：从快速安装、三层 MCP 检索到配置实战

Claude-Mem 是一个为 Claude Code 等 AI 编码代理构建的持久化记忆压缩系统：它在会话运行期间自动捕获工具使用观察（observation），用 AI 压缩成语义摘要，并在未来会话中把相关上下文重新注入回来。本文基于官方 README（葡语版 docs/i18n/README.pt.md）与仓库源码，完整覆盖安装方式、生命周期 Hook 工作机制、MCP 三层检索工作流、系统要求与 settings.json 配置，帮你把"会话间记忆"真正落地到自己的开发环境。

一、它解决什么问题

大模型代理每次新会话都"失忆"：上次修过的坑、做过的架构决策、踩过的依赖陷阱，全部清零。Claude-Mem 透明地保留跨会话上下文——自动捕获工具使用观察、生成语义摘要、供未来会话使用，使代理在项目知识上保持连续性，即使会话结束或断开重连也不丢失。

核心功能一览（与原文档一致）：

• 持久化记忆：上下文在会话之间存活
• 渐进式披露（Progressive Disclosure）：分层取回记忆，并可见 token 成本
• 基于 Skill 的搜索：通过 mem-search skill 用自然语言查询项目历史
• Web Viewer 界面：worker 启动时展示 URL，可在浏览器里实时查看记忆流
• Claude Desktop Skill：从 Claude Desktop 对话中检索记忆
• 隐私控制：用 <private> 标签将敏感内容排除在存储之外
• 上下文注入配置：细粒度控制注入哪些上下文
• 全自动运行：无需人工干预
• 引用机制：通过 worker API 按 ID 引用既往观察，或在 Web Viewer 中查看全部

二、快速开始（Quick Start）

安装只需一条命令：

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 命令安装。

OpenClaw Gateway 安装

也可以把 claude-mem 作为持久记忆插件装入 OpenClaw gateway：

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

安装器会处理依赖、插件配置、AI 供应商配置、worker 启动，以及 Telegram/Discord/Slack 等可选的实时观察推送流。仓库内 openclaw/ 目录提供了该插件的完整实现与测试（如 openclaw/src/index.ts）。

三、如何工作：六大核心组件

原文档列出六个主要组件，逐一对照源码说明：

1. 生命周期 Hooks（SessionStart、UserPromptSubmit、PostToolUse、Stop、SessionEnd，共 6 个 hook 脚本）
2. 智能安装器：带缓存的依赖校验器（是 pre-hook 脚本，不是生命周期 hook）
3. Worker 服务：本地 HTTP API，带 Web Viewer 与检索端点，由 Bun 管理
4. SQLite 数据库：存储会话、观察与摘要
5. mem-search Skill：支持渐进式披露的自然语言查询
6. Chroma 向量库：语义 + 关键词混合检索，用于智能上下文取回

Hook 机制的源码级印证

从源码结构看，plugin/hooks/hooks.json 与官方文档"5 个生命周期事件、6 个脚本"的描述完全吻合，实际注册了以下条目：

生命周期事件	matcher	执行动作（worker-service.cjs 子命令）	超时	异步
Setup	*	version-check.js（版本标记检查，提示 npx claude-mem repair）	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	是

几个值得注意的设计点：

• 非侵入性：Claude-Mem 不修改 Claude Code 本体，全部从外部通过命令 hook 观察主会话；PostToolUse/PreToolUse/Stop 均标记 "async": true，不阻塞主会话交互。
• 健壮的路径解析：每条 hook 命令内嵌一段 shell 逻辑，优先取 CLAUDE_PLUGIN_ROOT，否则遍历 ~/.claude/plugins/cache/thedotmack/claude-mem/* 缓存目录按语义化版本排序取最新，最后回退到 marketplace 目录；并含 Windows Git-Bash 的 cygpath 路径转换。
• Setup 只做版本检查：安装 Bun/uv 等运行时的重活由 npx claude-mem install / repair 完成，Setup hook 本身只读 .install-version 标记，保证 <100ms 且始终 exit 0，绝不卡住会话。

详细流程可参阅仓库文档 docs/public/hooks-architecture.mdx。

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

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

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

工作方式是：先用 search 拿到结果索引，再用 timeline 查看特定观察前后发生了什么，最后用 get_observations 批量拉取相关 ID 的完整内容。先过滤再取详情，可节省约 10 倍 token。

各工具参数（源自 src/servers/mcp-server.ts 的 inputSchema）

search（第一步，检索索引）：

参数	说明
query	全文检索查询（支持 AND/OR/NOT 与短语搜索）
limit	最大结果数（默认 20）
project	按项目名过滤
type	文档类别：observations / sessions / prompts（默认全部）；其他值视为观察类型过滤（obs_type 别名）
obs_type	按观察类型过滤（bugfix、feature 等，可逗号分隔多个）
dateStart / dateEnd	ISO 日期过滤
offset	分页偏移
orderBy	排序：date_desc / date_asc

timeline（第二步，时间线上下文）：

参数	说明
anchor	作为时间线中心的观察 ID（提供 query 时可省略）
query	用于自动定位锚点的搜索词（提供 anchor 时可省略）
depth_before	锚点之前取多少条（默认 3）
depth_after	锚点之后取多少条（默认 3）
project	按项目名过滤

get_observations（第三步，批量取详情）：

参数	说明
ids	观察 ID 数组（必填，多条 ID 务必合并为一次批量调用）
orderBy / limit / project	排序、数量与项目过滤

此外还有一个 important_workflow 工具：无参数，返回三段式工作流的固定说明，用于提醒代理"先检索、再取时间线、最后才批量取详情"。

使用示例（与原文档一致）：

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

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

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

源码中的路由细节

从 src/servers/mcp-server.ts 可以推断出三层工具背后的实际调用路径：search → worker GET /api/search、timeline → GET /api/timeline、get_observations → POST /api/observations/batch。源码还处理了一种运行时分流：当 CLAUDE_MEM_RUNTIME=server 且请求是"纯文本查询 + 观察类型 + 无不支持的过滤条件"时，search 会改道到服务端 /v1/search（Postgres 支撑），否则保留本地 worker 路径——因为服务端的 /v1/search 只接受 {projectId, query, limit}，带日期/类型/分页过滤的查询必须走本地 SQLite 路径才能忠实执行过滤。另外，observation_add、memory_search 等服务端 Beta 专属工具在 worker 运行时会被 src/servers/mcp-tool-visibility.ts 中的 SERVER_BETA_ONLY_TOOL_NAMES 过滤隐藏，不会向代理暴露。

更完整的参数示例与调试场景可参阅 docs/public/usage/search-tools.mdx。

五、系统要求

• Node.js：20.0.0 或更高
• Claude Code：支持插件的最新版本
• 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 官网下载最新安装器，安装后重启终端。

六、配置：settings.json 与模式语言

配置统一存放在 ~/.claude-mem/settings.json（首次运行自动创建并写入全部默认值）。可配置 AI 模型、worker 端口、数据目录、日志级别与上下文注入行为。

核心默认值（源自 src/shared/SettingsDefaultsManager.ts）

配置项	默认值	说明
CLAUDE_MEM_MODEL	claude-haiku-4-5-20251001	用于压缩观察的模型（Claude 供应商下）
CLAUDE_MEM_PROVIDER	claude	AI 供应商：claude / gemini / openrouter
CLAUDE_MEM_CLAUDE_AUTH_METHOD	subscription	Claude 认证方式：订阅登录 / API key / 网关
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_SKIP_TOOLS	ListMcpResourcesTool,SlashCommand,Skill,TodoWrite,AskUserQuestion	不产生观察的工具（逗号分隔）
CLAUDE_MEM_CHROMA_ENABLED	true	设为 false 可关闭 Chroma，退化为纯 SQLite 检索
CLAUDE_MEM_TIER_ROUTING_ENABLED	true	按观察复杂度把生成任务路由到不同档位模型（$TIER:fast / $TIER:smart 等）

完整的配置项参考见 docs/public/configuration.mdx。

模式与语言配置

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	日文模式

语言模式遵循 code--[lang] 命名，[lang] 为 ISO 639-1 语言码（zh 中文、ja 日语、es 西班牙语……）。仓库 plugin/modes/ 目录中实际包含 code.json、29 种 code--xx.json 语言变体，以及 email-investigation.json、law-study.json、meme-tokens.json 等专用模式——即除语言外还有非代码工作流模式可选。

修改模式后需重启 Claude Code 才能生效。

七、发布分支（Release Branches）

• stable 发布从 main 分支发出，并推送到 npm；
• core-dev 与 community-edge 是直接从源码运行的分支，分别面向早期可靠性修复与社区集成。

三者中只有 main 会被 npm 发布，其余分支需以源码方式运行；本地非 stable 分支的运行方式见官方文档"Ramos de Lançamento / Release Branches"章节（仓库内 docs/public/branches.mdx）。

八、故障排查与错误报告

• 智能排查：遇到问题时直接把问题描述给 Claude，内置的故障排查 skill 会自动诊断并给出修复建议。
• 自动生成 Bug 报告：仓库提供报告生成器，收集环境信息以便复现：

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

生成器源码位于 scripts/bug-report/。

九、许可证

Claude-Mem 采用 Apache License 2.0 授权。选择 Apache-2.0 的考量是：持久化的代理记忆应当易于嵌入编码工具、本地代理、MCP 服务器、企业系统与生产级 agent 框架。详见 LICENSE 与 docs/license.md（许可范围）、docs/ip-boundary.md（开源与商业的边界）。ragtime/ 目录单独以 Apache License 2.0 授权，见 ragtime/LICENSE。

---

小结：Claude-Mem 的落地路径很短——npx claude-mem install 后重启 Claude Code 即自动生效；它的工程价值在于"hook 观察 + 后台 worker 压缩 + 三层渐进式检索"的组合：观察捕获不阻塞主会话，检索时先拿几十 token 的索引、再定点取详情，用约 10 倍的 token 节省换回跨会话的项目记忆。配置层面只需关注 ~/.claude-mem/settings.json 中的模型、模式（CLAUDE_MEM_MODE）与注入条数（CLAUDE_MEM_CONTEXT_OBSERVATIONS）等少数关键项。