Claude-Mem：AI 编码助手的跨会话持久记忆系统——安装、配置与三层 MCP 检索工作流实战

本文为 Claude-Mem 的完整技术指南。Claude-Mem 是一个为 Claude Code（及 OpenCode、Codex、OpenClaw 等多种 Agent 宿主）构建的持久化记忆压缩系统：它自动捕获会话中的工具使用观察，用 AI 压缩为结构化摘要，并在后续会话启动时把相关上下文重新注入。读完本文，你将掌握从一行命令安装、生命周期钩子与 Worker 服务的工作原理、~/.claude-mem/settings.json 的完整配置项、CLAUDE_MEM_MODE 多语言模式切换，到 search → timeline → get_observations 三层 MCP 检索工作流的全部实操细节，并能对照仓库源码理解每一处行为的实现依据。

快速开始

Claude-Mem 的 npm 包名是 claude-mem（当前仓库版本见 package.json，为 13.24.0，要求 Node.js ≥ 20 与 Bun ≥ 1.0）。安装方式有以下几种：

方式一：npx 一行安装（推荐）

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/库本身——它不会注册插件钩子，也不会配置 Worker 服务。要获得完整的记忆能力，必须始终通过 npx claude-mem install 或上面的 /plugin 命令安装。这一点在 根 README 中有明确说明。

OpenClaw 网关安装

如果使用的是 OpenClaw 网关（仓库内含完整的 OpenClaw 插件实现与技能定义），可以用一条命令把 claude-mem 作为持久记忆插件装入：

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

安装程序会处理依赖、插件配置、AI 提供方设置、Worker 启动，以及可选的 Telegram / Discord / Slack 等实时观察推送渠道。仓库中的 openclaw/install.sh 与 openclaw/plugin 配置 即为该安装流程在源码层面的对应物。

核心特性

• 持久记忆：上下文跨会话保留，会话结束或被重连后知识连续性不断裂
• 渐进式公开（Progressive Disclosure）：分层记忆检索，带明确的 token 成本可视化
• 技能式检索：通过 mem-search 技能以自然语言查询项目历史
• Web 查看器 UI：在 Worker 启动时打印的 URL 上实时查看记忆流
• Claude Desktop 技能：在 Claude Desktop 对话中检索记忆
• 隐私控制：用 <private> 标签把敏感内容排除出存储
• 上下文配置：精细控制哪些上下文被注入
• 自动运行：无需手动干预
• 引用溯源：通过 Worker API 用 ID 引用历史观察，或在 Web 查看器中浏览全部记录

工作原理：六大核心组件

Claude-Mem 作为 Claude Code 插件运行，核心组件如下（与 docs/public/architecture/overview.mdx 的架构总览一致）：

1. 5 个生命周期钩子：SessionStart、UserPromptSubmit、PostToolUse、Stop、SessionEnd（外加 1 个 Read 的 PreToolUse 钩子脚本，合计 6 个钩子脚本，另有 1 个 Setup 预钩子）
2. 智能安装（Smart Install）：带缓存的依赖检查器——它是一个预钩子脚本（pre-hook script），不是生命周期钩子
3. Worker 服务：本地 HTTP API，带 Web 查看器 UI 和检索端点，由 Bun 管理进程生命周期
4. SQLite 数据库：存储会话（sessions）、观察（observations）、摘要（summaries），配合 FTS5 全文检索
5. mem-search 技能：以渐进式公开模式执行的自然语言查询
6. Chroma 向量数据库：可选，用于"语义 + 关键词"混合检索

从源码结构看，钩子的真实注册清单在 plugin/hooks/hooks.json 中，可以看到每个事件如何映射到 Worker 的具体子命令：

生命周期事件	matcher	Worker 子命令	超时/模式
Setup	*	version-check.js（版本/完整性自检）	300s
SessionStart	startup|clear|compact	worker-service.cjs start + hook claude-code context	60s
UserPromptSubmit	—	hook claude-code session-init	60s
PreToolUse	Read	hook claude-code file-context	60s，async
PostToolUse	*	hook claude-code observation	120s，async
Stop	—	hook claude-code summarize	120s，async

数据流可以概括为：

Hook (stdin) → Database → Worker Service → SDK Processor → Database → Next Session Hook

即：Claude Code 通过 stdin 把工具执行数据发给钩子 → 钩子写入 SQLite → Worker 服务读取观察并经 Claude Agent SDK（或 Gemini / OpenRouter）处理 → 摘要写回数据库 → 下一次会话的 context 钩子从数据库读取摘要注入。会话生命周期的完整六步（Setup 自检 → SessionStart 启动 Worker 并注入上下文 → UserPromptSubmit 建会话 → PostToolUse 捕获工具执行 → Stop 生成最终摘要 → SessionEnd 优雅收尾）在 docs/public/architecture/overview.mdx 中有详细图解。

技术栈方面：TypeScript（ES2022/ESNext 模块）、Node.js 20+ 与 Bun ≥ 1.0 双运行时、bun:sqlite 驱动、Express 5 HTTP 服务、SSE 实时推送、React 查看器 UI、esbuild 构建、bun test 测试。钩子内部的超时策略由 src/shared/hook-constants.ts 集中定义，例如健康检查 3s、API 请求 30s、Worker 就绪等待 30s，且 Windows 上所有超时会乘以 1.5 的系数（WINDOWS_MULTIPLIER），这正是 Windows 上行为略慢的原因。

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

Claude-Mem 通过 4 个 MCP 工具（important_workflow、search、timeline、get_observations）提供智能记忆检索，核心是遵循一套 token 高效的三层工作流：

1. search——获取带 ID 的压缩索引（每条结果约 50-100 token）
2. timeline——获取感兴趣结果前后的时间线上下文
3. get_observations——仅对筛选后的 ID 获取完整详情（每条约 500-1,000 token）

工作节奏是：先用 search 拿索引 → 用 timeline 看某条观察前后发生了什么 → 用 get_observations 批量拉取相关 ID 的完整详情。先过滤、后取详情，可获得约 10 倍的 token 节省。

search 工具的完整参数（来自 src/servers/mcp-server.ts 的 schema 定义）：

• query（string）——检索词
• limit（number）——最大结果数，默认 20
• project（string）——按项目名过滤
• platformSource（string）——按平台来源过滤（如 claude、codex、cursor），把结果限定在某一个 Agent 自己的记忆里
• type（string）——文档类别：observations / sessions / prompts（默认全部）；其他取值会被当作观察类型过滤（等价于 obs_type）
• obs_type（string）——观察类型过滤，如 bugfix、feature、decision、discovery、change，可逗号分隔
• dateStart / dateEnd（string）——日期过滤（ISO 格式）
• offset（number）——分页偏移
• orderBy（string）——date_desc（默认）或 date_asc

timeline 与 get_observations 的参数详见 plugin/skills/mem-search/SKILL.md：

• timeline：anchor（观察 ID，可选）或 query（自动定位锚点）；depth_before / depth_after（锚点前后各取多少条，默认 3，最大 20）；project 过滤
• get_observations：ids（必填，数组）、orderBy、limit、project；对 2 条及以上观察务必批量获取——1 次 HTTP 请求替代 N 次

典型调用序列：

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

// 第 2 步：审查索引，识别相关 ID（例如 #123、#456），
//         可用 timeline(anchor=123) 查看其前后上下文

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

从源码结构看，search 工具在运行时还有一个智能路由：当 server-beta 运行时可用、请求带文本查询、类型限定为 observations 且没有 /v1/search 不支持的过滤器时，请求会被路由到服务端 PG 后端；否则回落到本地 Worker 的 /api/search（读取本地 SQLite，可配 Chroma 语义检索）。这段路由逻辑在 src/servers/mcp-server.ts 中有注释说明。

除了 MCP 工具，mem-search 技能会在用户提出"我们之前修过这个吗？""上次是怎么解决 X 的？"这类问题时自动触发，其触发条件与三层流程都写在 plugin/skills/mem-search/SKILL.md 中。

系统要求与 Windows 注意事项

系统要求（以 根 README 与 package.json 为准）：

• Node.js：20.0.0 以上（package.json engines 声明为 >=20.12.0，bun >=1.0.0）
• Claude Code：支持插件的最新版本
• Bun：JavaScript 运行时兼进程管理器，缺失时自动安装
• uv：向量检索所需的 Python 包管理器，缺失时自动安装
• SQLite 3：持久化存储，已捆绑

Windows 安装注意事项

如果在 PowerShell 中看到类似报错：

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

说明 Node.js/npm 未安装或不在 PATH 中。请安装最新版 Node.js 并确认 npm 已在 PATH 里，然后重启终端再执行安装。

配置：settings.json 与 CLAUDE_MEM_MODE

所有设置集中在 ~/.claude-mem/settings.json（首次运行自动以默认值创建）。可配置 AI 模型、Worker 端口、数据目录、日志级别、上下文注入行为等。从 src/shared/SettingsDefaultsManager.ts 的 SettingsDefaults 接口可以确认完整配置面，代表性的键包括：

配置键	作用
CLAUDE_MEM_MODEL	摘要生成使用的 AI 模型（支持 $TIER:fast/$TIER:smart 分层占位符）
CLAUDE_MEM_PROVIDER / CLAUDE_MEM_GEMINI_* / CLAUDE_MEM_OPENROUTER_*	AI 提供方选择与各家 API 配置
CLAUDE_MEM_WORKER_PORT / CLAUDE_MEM_WORKER_HOST	Worker HTTP 服务的监听地址
CLAUDE_MEM_API_TIMEOUT_MS	钩子到 Worker 的 API 超时
CLAUDE_MEM_SKIP_TOOLS	跳过观察捕获的工具列表
CLAUDE_MEM_DATA_DIR	数据目录
CLAUDE_MEM_LOG_LEVEL	日志级别
CLAUDE_MEM_CONTEXT_OBSERVATIONS 及 CLAUDE_MEM_CONTEXT_* 系列	控制启动注入的观察条数、字段、是否显示 token 数/节省比例/上次摘要/最后消息等
CLAUDE_MEM_SEMANTIC_INJECT / CLAUDE_MEM_SEMANTIC_INJECT_LIMIT	语义注入开关与条数上限
CLAUDE_MEM_CHROMA_*	Chroma 向量库开关、host/port/SSL/密钥/租户/库名与预热超时
CLAUDE_MEM_FOLDER_CLAUDEMD_ENABLED / CLAUDE_MEM_FOLDER_USE_LOCAL_MD	目录级 CLAUDE.md 行为
CLAUDE_MEM_EXCLUDED_PROJECTS	排除不记录的项目
CLAUDE_MEM_QUEUE_ENGINE / CLAUDE_MEM_REDIS_*	队列引擎（含 Redis/BullMQ 配置）
CLAUDE_MEM_CLOUD_SYNC_*	Worker 原生云同步（Token + UserId + HubUrl 三者齐全才生效，无单独开关）
CLAUDE_MEM_TELEGRAM_*	Telegram 实时通知（token、chat id、触发类型/概念）

模式与语言配置

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/

仓库内 plugin/modes/ 目录当前包含 code.json（默认英语模式）、code--zh.json（简体中文）、code--ja.json（日语）等约 30 个语言/风格变体，以及 law-study、email-investigation、meme-tokens 等特殊工作流模式。

模式	说明
code	默认英语模式
code--zh	简体中文模式（已内置，无需额外安装或插件更新）
code--ja	日语模式

语言模式遵循 code--[lang] 命名规律，其中 [lang] 是 ISO 639-1 语言代码（如 zh 中文、ja 日语、es 西班牙语）。修改模式后需要重启 Claude Code 才能生效。

发布分支

稳定版从 main 分支发布并推送到 npm；core-dev 与 community-edge 是用于早期可靠性修复和社区集成的"源码运行"分支——只有 main 会发布到 npm，其余分支从源码运行。分支策略详见 docs/public/branches.mdx。

开发、排障与问题报告

• 开发：构建、测试与贡献流程见 docs/public/development.mdx。测试命令为 bun test tests，仓库附带大量分域测试（如 tests/worker/search/、tests/sqlite/、tests/server/），Worker 端点可用 npm run worker:status / worker:logs 查看状态与日志。
• 排障：遇到问题时直接向 Claude 描述问题，troubleshoot 技能会自动诊断并给出修复；常见问题见 docs/public/troubleshooting.mdx。
• Bug 报告：用自动化生成器产出完整的 bug 报告：

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

对应源码为 scripts/bug-report/ 下的 collector 与 CLI。

贡献流程：fork 仓库 → 创建功能分支 → 带测试提交变更 → 更新文档 → 提交 Pull Request。

许可证与支持渠道

Claude-Mem 采用 Apache License 2.0（见 LICENSE）。选择 Apache-2.0 的考量是：耐久的 Agent 记忆应当能方便地嵌入开发工具、本地 Agent、MCP 服务器、企业系统、机器人栈与生产级 Agent 框架。许可证范围与开源/商业边界另有 docs/license.md 与 docs/ip-boundary.md 说明。特别注意：ragtime/ 目录同样是 Apache License 2.0（见 ragtime/LICENSE）。

支持渠道（仓库内对应资源）：

• 文档：docs/ 目录（含架构、配置、故障排查等全部指南）
• 翻译版 README：docs/i18n/ 提供中、繁中、日、韩等 30+ 语言版本（本文参考的 docs/i18n/README.ko.md 即韩语版）
• 作者：Alex Newman（@thedotmack）

关于 CMEM：CMEM 是一个第三方创建的 token，但已被 Claude-Mem 作者官方接纳，作为社区增长催化剂，把 CMEM 带给最需要它的开发者与知识工作者。原文档给出了官方 BASE CA：0x76b1967eec0ccaeb001bbbb2b40dc4badba31ba3。

---

适用前提说明：本文基于当前仓库（package.json 版本 13.24.0）撰写；韩语 README 徽章标注的版本号为 13.4.0，属于文档翻译时的历史版本，实际能力以仓库当前源码为准。