Claude-Mem 实战指南：Claude Code 持久记忆插件的安装、架构、MCP 三层检索与模式配置

Claude-Mem 是一个为 Claude Code 等 Agent 环境构建的持久记忆压缩系统：它自动捕获会话中的工具使用行为、用 AI 将其压缩为结构化"观察"（observations），再在后续会话中把相关上下文注入回来。本篇以仓库内芬兰语版 README（docs/i18n/README.fi.md）为骨架，结合仓库源码逐项核实其安装命令、钩子架构、MCP 检索工具链与模式配置机制，帮助你在本地完整跑通这套跨会话记忆系统并理解其底层工作原理。

---

一、项目定位：跨会话的持久上下文

官方 README 对项目的核心定义是：Pysyvä muistinpakkausjärjestelmä（持久记忆压缩系统）——自动保存工具使用观察、生成语义摘要，并将其提供给未来的会话，使 Claude 在会话结束或重连之后仍保有对项目的知识连续性。

从源码与文档可以确认其实现要点：

• 语言与运行时：TypeScript（ES2022/ESNext 模块），Node.js 20+ 与 Bun；
• 存储：SQLite 3（bun:sqlite 驱动）+ FTS5 全文检索，可选 Chroma 向量库做语义检索；
• 服务层：Express.js 5 HTTP API + SSE 实时推送，React + TypeScript 构建 Web 查看器；
• 当前仓库版本：根据 package.json 为 13.24.0（engines 要求 node >=20.12.0、bun >=1.0.0），许可证为 Apache-2.0。

注：本文所依据的文档是该仓库的芬兰语 README 翻译版，其内容与英文主 README 保持同步（由 package.json 中的 translate-readme 脚本生成，芬兰语属于 translate:tier4 批次）。文中提到的各功能点均可在仓库对应源码中验证。

---

二、快速安装（Pikaopas）

2.1 标准安装

一条命令完成安装：

npx claude-mem install

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

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

重要提示：Claude-Mem 虽然也发布在 npm 上，但 npm install -g claude-mem 只会安装 SDK/库——它不会注册插件钩子，也不会配置 worker 服务。务必使用 npx claude-mem install 或上述 /plugin 命令完成安装。从 package.json 的 bin 与 files 字段可以印证：npm 包携带的是构建产物 dist/npx-cli、plugin/hooks、plugin/modes、plugin/skills 等分发件，真正的钩子注册由安装器完成。

2.2 OpenClaw Gateway 安装

如果要为 OpenClaw 接入网关安装持久记忆插件：

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

安装程序会负责依赖处理、插件配置、AI 服务商配置、worker 启动，以及可选的 Telegram/Discord/Slack 实时观察推送。仓库中 openclaw/ 目录（含 openclaw.install.sh、openclaw.plugin.json）与 install/public/install.sh 即为对应的安装器实现。

2.3 核心功能清单

原文档列出的关键能力如下，均可在仓库中找到对应实现：

能力	说明	仓库佐证
🧠 持久记忆	上下文跨会话保留	src/services/sqlite/ 存储层
📊 渐进式披露	分层记忆检索并显示 token 成本	plugin/skills/mem-search/SKILL.md
🔍 技能驱动检索	用 mem-search 技能查询项目历史	同上
🖥️ Web 查看器	启动时打印的 worker 地址提供实时记忆流	src/ui/viewer/（React）
📵 隐私控制	用 <private> 标签将敏感内容排除出存储	src/utils/tag-stripping.ts
⚙️ 上下文定义	精确控制注入哪些上下文	docs/public/configuration.mdx
🔗 引用机制	通过 worker API 按 ID 引用历史观察，或在 Web 查看器中查看全部	src/services/worker/ HTTP 路由

---

三、工作原理：钩子驱动的内存流水线

原文档"Miten se toimii"（它如何工作）一节列出了 6 个关键组件，这里逐条对照仓库实现加以核实：

1. 生命周期钩子（lifecycle hooks）：SessionStart、UserPromptSubmit、PostToolUse、Stop 等；
2. 智能安装：带缓存的依赖预检（作为钩子前置脚本，不属于生命周期钩子）；
3. Worker 服务：本地 HTTP API，带 Web 查看器与搜索端点，由 Bun 托管；
4. SQLite 数据库：存储会话、观察、摘要；
5. mem-search 技能：以渐进式披露方式执行自然语言查询；
6. Chroma 向量库：语义 + 关键词的混合检索。

3.1 钩子注册表（源码级证据）

查看 plugin/hooks/hooks.json，实际注册的钩子事件为：

钩子事件	Matcher	执行的 hook 子命令	超时	备注
Setup	*	version-check.js	300s	版本一致性预检，前置脚本
SessionStart	startup|clear|compact	worker-service.cjs start	60s	先启动 Bun worker
SessionStart	同上	worker-service.cjs hook claude-code context	60s	注入历史上下文
UserPromptSubmit	—	worker-service.cjs hook claude-code session-init	60s	建会话、存原始 prompt
PostToolUse	*	worker-service.cjs hook claude-code observation	120s	异步捕获工具执行
PreToolUse	Read	worker-service.cjs hook claude-code file-context	60s	异步读取文件上下文
Stop	—	worker-service.cjs hook claude-code summarize	120s	异步生成最终摘要

这与 docs/public/architecture/overview.mdx 中"Setup 版本检查 + 5 个生命周期钩子（SessionStart、UserPromptSubmit、Read 的 PreToolUse、PostToolUse、Stop）共 6 个钩子脚本"的描述完全一致。

3.2 内存数据流

同一架构文档给出的记忆流水线为：

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

1. 输入：Claude Code 通过 stdin 把工具执行数据发给钩子；
2. 存储：钩子把观察写入 SQLite；
3. 处理：Worker 服务读取观察，经 Claude Agent SDK（或 Gemini / OpenRouter）分析压缩；
4. 输出：处理后的摘要写回数据库；
5. 检索：下一个会话的 context 钩子从数据库读取摘要并注入。

会话生命周期为：Setup 版本检查 → SessionStart（启动 worker + 注入上下文）→ UserPromptSubmit（建会话）→ PostToolUse（每次工具调用触发，可触发上百次）→ Stop（生成含 request/completions/learnings 的最终摘要）→ 会话清理（/clear 时跳过，以保留进行中的会话）。

---

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

原文档强调，Claude-Mem 通过 4 个 MCP 工具提供记忆搜索，遵循 3 层工作流模型（3-kerroksinen työnkulku）：

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

使用方式：先用 search 拿到结果索引 → 用 timeline 查看特定观察前后的发生了什么 → 再用 get_observations 只取相关 ID 的完整信息。通过"先筛选、后取数"可获得约 10 倍的 token 节省。

原文档给出的示例用法：

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

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

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

4.1 源码印证

• MCP 服务端实现位于 src/servers/mcp-server.ts：其中定义了 get_observations 工具（第 543 行附近），并在工具描述中明确要求 get_observations(ids=[...]) 对 2 个及以上条目必须批量调用；
• plugin/skills/mem-search/SKILL.md 给出了 search 工具的完整参数说明：query（必填）、limit（默认 20，最大 100）、project、type（observations/sessions/prompts）、obs_type（bugfix、feature、decision、discovery、change 等）、dateStart/dateEnd（YYYY-MM-DD 或毫秒时间戳）、offset、orderBy（date_desc 默认 / date_asc / relevance）；
• 技能文档返回示例为带 ID、时间戳、类型图标的表格，例如 #11131 | 3:48 PM | 🟣 | Added JWT authentication | ~75，与 README 宣称的 token 预算一致。

从源码结构看，MCP 工具在 CLAUDE_MEM_RUNTIME=server 与 worker 两种运行时有不同行为（见 src/servers/mcp-server.ts 第 208 行附近的提示：worker 模式下应使用既有的 search/timeline/get_observations 工具）。

---

五、发布分支策略

原文档"Julkaisuhaarat"（发布分支）一节说明：

• 稳定发布从 main 分支交付，并发布到 npm；
• core-dev 与 community-edge 分支是"源码可运行"（lähdekoodista ajettava）的分支，分别面向早期可靠性修复和社区集成；
• 三者关系与"非稳定版本如何本地运行"的完整说明见 docs/public/branches.mdx。

贡献流程亦基于这套分支模型：fork 仓库 → 创建功能分支 → 提交带测试的修改 → 更新文档 → 发起 Pull Request（见 docs/public/development.mdx）。

---

六、系统要求

原文档列出的系统要求（Järjestelmävaatimukset）：

• Node.js：20.0.0 或更高（仓库 package.json 中 engines.node 实际为 >=20.12.0）；
• Claude Code：支持插件（plugin）的最新版本；
• 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 后重启终端再执行安装命令。

---

七、配置（Asetukset）

7.1 配置文件

所有配置集中在 ~/.claude-mem/settings.json 中管理，首次运行时自动以默认值创建。可配置项包括 AI 模型、worker 端口、数据目录、日志级别与上下文注入设置。完整参数表见 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_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_SKIP_TOOLS	ListMcpResourcesTool,SlashCommand,Skill,TodoWrite,AskUserQuestion	从观察中排除的工具（逗号分隔）

7.2 模式与语言（CLAUDE_MEM_MODE）

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 语言代码。修改模式后需重启 Claude Code 生效。

7.3 模式文件的实际结构（源码级补充）

仓库内 plugin/modes/ 目录实际内置了 27 个语言变体及多个行为变体（含 code--chill、email-investigation、law-study 等）。以芬兰语模式 plugin/modes/code--fi.json 为例（本 README 正是其芬兰语翻译版，二者可互为印证），模式文件是一个 JSON 配置档案，包含：

• name：模式显示名，如 "Code Development (Finnish)"；
• prompts.footer / summary_footer：约束记忆 Agent 只输出 XML 结构化观察/摘要，并追加 LANGUAGE REQUIREMENTS: Please write the observation data in suomi 之类的语言指令；
• xml_title_placeholder、xml_narrative_placeholder 等占位符：以目标语言书写的字段模板（如 [**subtitle**: Yhden lauseen selitys (enintään 24 sanaa)]），引导模型按语言与字数要求生成内容。

从源码结构看，模式档案即 docs/public/modes.mdx 所述的"Observer Role + Observation Types + Concepts + Language"四要素配置；用户可用 /mode-creator 技能交互式创建自定义模式，自定义模式安装在 ~/.claude-mem/modes/ 下，在插件升级后依然保留，且 worker 会优先查找用户模式再回落到内置模式。

---

八、故障排查与 Bug 报告

故障排查：遇到问题时，直接把问题描述给 Claude——内置的 troubleshoot 技能会自动诊断并给出修复建议；常见问题与解法汇总见 docs/public/troubleshooting.mdx。

Bug 报告：可用自动生成器产出结构完整的缺陷报告：

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

该命令对应 package.json 中的 "bug-report": "bun scripts/bug-report/cli.ts" 脚本，实现见 scripts/bug-report/cli.ts 与 scripts/bug-report/collector.ts。

开发参与：构建、测试与贡献流程见 docs/public/development.mdx；仓库本地可通过 npm run build（同步插件清单 + 构建钩子 + 生成 lockfile）与 npm test（bun test tests）复现 CI 流程。

---

九、许可证与支持

• Claude-Mem 采用 Apache License 2.0。原文档给出的选择理由：持久 Agent 记忆应当易于嵌入开发者工具、本地 Agent、MCP 服务器、企业系统与生产级 Agent 方案。完整条款见 LICENSE，许可证范围与开源/商业边界见 docs/license.md 与 docs/ip-boundary.md。
• 原文档特别注明：ragtime/ 目录单独采用 Apache License 2.0，详见 ragtime/LICENSE。
• 支持渠道：仓库内 docs/ 目录为文档根（芬兰语版首页即 docs/i18n/README.fi.md），问题反馈通过仓库 Issues 进行。
• 其他多语言 README 版本（中文、日语、德语等 30 余种）均位于 docs/i18n/ 目录，可按语言切换阅读。

---

十、小结：从安装到原理的完整闭环

环节	命令/位置	作用
安装	npx claude-mem install（或 /plugin 市场命令、--ide opencode/--ide antigravity）	注册钩子、配置 worker
钩子	plugin/hooks/hooks.json	Setup 预检 + 5 个生命周期钩子捕获工具行为
处理	Worker（Bun 托管，Express 5 + SSE）	Claude Agent SDK 压缩观察、生成摘要
存储	SQLite + FTS5（可选 Chroma）	会话、观察、摘要持久化与混合检索
检索	MCP search → timeline → get_observations	三层渐进披露，约 10 倍 token 节省
配置	~/.claude-mem/settings.json	模型、端口、日志、CLAUDE_MEM_MODE 模式/语言

按本文操作，你可以在重启 Claude Code 后验证：新会话启动时会注入历史上下文（context 钩子）、PostToolUse 持续捕获工具执行观察、Stop 时生成最终摘要，并通过 mem-search 技能以低 token 成本回答"我们上次是怎么解决 X 的？"这类跨会话问题。