Claude-Mem 持久化记忆系统实战指南:安装、架构、MCP 检索与多语言模式配置全解析

本文以仓库中的波兰语版 README(docs/i18n/README.pl.md)为主体,完整覆盖 Claude-Mem 的安装方式、核心特性、生命周期 Hook 架构、4 个 MCP 检索工具的三层工作流、~/.claude-mem/settings.json 配置与 CLAUDE_MEM_MODE 多语言模式体系,并结合 plugin/hooks/hooks.json、src/servers/mcp-server.ts、src/services/domain/ModeManager.ts 等源码逐一印证文档描述,帮助你在 Claude Code 中落地一套"跨会话持久记忆"能力。

一、项目定位:给 Agent 装上一块"持久记忆"

Claude-Mem 是一个为 Claude Code 打造的持久记忆压缩系统(memory compression system),其工作原理在波兰语 README 中概括为:在会话过程中自动捕获工具使用观察(observation),用 AI 生成语义化摘要,并在未来会话中自动注入相关上下文——即使会话结束或重新连接,Claude 依然保留对项目知识的连续性认知。

需要说明的是,docs/i18n/README.pl.md 文件首行即声明"这是一份自动翻译,欢迎社区修正"。从仓库脚本看,该文件由 scripts/translate-readme/cli.ts 从根目录 README.md 批量翻译生成(package.json 中定义了 translate:tier1 ~ translate:tier4 分级翻译脚本,波兰语属于 tier2 批次)。因此本文以波兰语文档的骨架展开,同时以英文原 README 和当前仓库源码为准校准细节(例如波兰语版徽章显示版本 13.4.0,而 package.json 当前版本已是 13.24.0,翻译文件存在正常的时间滞后)。

二、快速开始:四种安装路径

文档给出的安装入口按 IDE/平台分为四类,全部可复制执行:

1. 默认安装(Claude Code):

npx claude-mem install

2. 为 OpenCode 安装:

npx claude-mem install --ide opencode

3. 为 Antigravity CLI 安装:

npx claude-mem install --ide antigravity

4. 在 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,即命令行入口本身是安装器,而非运行时。

OpenClaw Gateway 安装

对于 OpenClaw 网关,claude-mem 可作为持久记忆插件一条命令安装:

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

安装器会处理依赖、插件配置、AI 提供方配置、worker 启动,以及可选的实时观察流推送到 Telegram、Discord、Slack 等渠道。仓库中 openclaw/ 目录(含 openclaw/src/index.ts 与 openclaw/SKILL.md)即对应这一集成形态。

核心特性清单(继承自原文档)

特性	说明
持久记忆	上下文跨会话存活
渐进式披露	分层获取记忆,并可见 token 成本
基于技能的搜索	用 mem-search 技能查询项目历史
Web 查看器	worker 启动时打印的 URL 提供实时记忆流界面
Claude Desktop 技能	从 Claude Desktop 对话中检索记忆
隐私控制	用 <private> 标签将敏感内容排除在存储之外
上下文配置	精细控制注入哪些上下文
自动运行	无需人工干预
引用机制	通过 worker API 按 ID 引用历史观察,或在 Web 中浏览全部

三、工作原理:六大核心组件

原文档列出系统由六个核心组件构成,下面逐项给出源码级印证:

1. 5 个生命周期 Hook(6 个 hook 脚本):SessionStart、UserPromptSubmit、PostToolUse、Stop、SessionEnd;
2. 智能安装器:带缓存的依赖检查器(属于 pre-hook 脚本,不是生命周期 Hook);
3. Worker 服务:本地 HTTP API,含 Web 查看器 UI 与搜索端点,由 Bun 托管;
4. SQLite 数据库:存储会话、观察、摘要;
5. mem-search 技能:支持自然语言查询与渐进式披露;
6. Chroma 向量库:语义 + 关键词混合检索,支撑智能上下文提取。

从源码结构看,当前仓库的 plugin/hooks/hooks.json 实际注册了六组 Hook,且都通过 bun-runner.js 转发到 worker-service.cjs 的对应子命令:

• Setup:匹配 *,执行版本检查脚本 version-check.js(即组件 2 的"pre-hook");
• SessionStart:匹配 startup|clear|compact,先 worker-service.cjs start 拉起 worker,再执行 hook claude-code context 注入上下文;
• UserPromptSubmit:执行 hook claude-code session-init;
• PostToolUse:匹配 *,async: true,执行 hook claude-code observation——这就是"捕获工具使用观察"的落点;
• PreToolUse:仅匹配 Read,async: true,执行 hook claude-code file-context;
• Stop:执行 hook claude-code summarize 生成进度摘要。

每条 Hook 命令都带有内嵌的路径解析逻辑(优先 $CLAUDE_PLUGIN_ROOT,否则在 ~/.claude/plugins/cache/thedotmack/claude-mem/ 下按语义化版本降序挑选最新缓存,最终回退到 ~/.claude/plugins/marketplaces/thedotmack/plugin),并针对 Windows Git Bash 做了 cygpath 转换——这是"自动运行、无需干预"体验背后的健壮性设计。Worker 侧的 HTTP 路由与 SQLite 存储可分别在 src/services/worker/http/routes/ 与 src/storage/sqlite/ 中查证。

四、MCP 检索工具:4 个工具、3 层工作流

Claude-Mem 通过 4 个 MCP 工具提供智能记忆检索,遵循 token 高效的 3 层工作流模式:

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

典型用法(继承自原文档):

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

// 第 2 步:审阅索引,识别相关 ID(例如 #123、#456)

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

先过滤、再取详情,可带来约 10 倍 token 节省。

源码印证: src/servers/mcp-server.ts 中实际注册了 search、timeline、get_observations、session_start_context 等工具,并额外内置一个名为 important_workflow 的元工具,其描述文本直接硬编码了上述 3-LAYER WORKFLOW("NEVER fetch full details without filtering first. 10x token savings."),用于在每次会话中向模型强调这一纪律。参数细节与原文档一致且更完整:

• search:支持 query、limit(默认 20)、project、platformSource(按 claude/codex/cursor 等隔离各 Agent 自己的记忆)、type(observations/sessions/prompts,其他值视为 obs_type 别名)、obs_type(可逗号分隔多值)、dateStart/dateEnd(ISO 日期)、offset 分页、orderBy(date_desc/date_asc);
• timeline:anchor(观察 ID)或 query(自动定位 anchor),depth_before/depth_after(默认各 3),可按 project 过滤;
• get_observations:ids(数字数组,必填),handler 直接调用 worker 的 /api/observations/batch 批量端点;
• session_start_context:渲染与 SessionStart Hook 注入完全一致的上下文文本,便于调试查看器行为。

五、发布分支策略

稳定版从 main 分支发布并推送到 npm;core-dev 与 community-edge 是"从源码运行"的分支,分别面向早期可靠性修复和社区集成。项目从三条分支出货,只有 main 会发布到 npm,其余分支需要按 docs/public/branches.mdx 中的流程从源码运行。

六、系统要求与 Windows 注意事项

依赖	要求
Node.js	20.0.0 及以上(package.json engines 实际声明 >=20.12.0)
Claude Code	支持插件的最新版本
Bun	JS 运行时与进程管理器,缺失时自动安装
uv	Python 包管理器,向量搜索用,缺失时自动安装
SQLite 3	持久化存储(内置)

Windows 注意: 若出现 npm : The term 'npm' is not recognized as the name of a cmdlet 之类的报错,说明 Node.js/npm 未加入 PATH——安装最新版 Node.js 后重启终端即可。仓库中 tests/infrastructure/windows-hide-regressions.test.ts、tests/worker-wrapper-windows-hide.test.ts 等测试专门守护 Windows 下的行为。

七、配置体系:settings.json 与多语言模式

配置统一放在 ~/.claude-mem/settings.json,首次运行自动以默认值创建。从 src/shared/SettingsDefaultsManager.ts 可以看到默认值种子的关键项:CLAUDE_MEM_MODEL 默认为 claude-haiku-4-5-20251001,CLAUDE_MEM_MODE 默认为 code,另有 tier 模型别名(CLAUDE_MEM_TIER_FAST_MODEL/CLAUDE_MEM_TIER_SMART_MODEL,配合 $TIER:fast/$TIER:smart 解析)等。你可以配置 AI 模型、worker 端口、数据目录、日志级别与上下文注入参数,完整字段说明见 docs/public/configuration.mdx。

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/

模式	描述
code	默认英文模式
code--zh	简体中文模式
code--ja	日语模式

语言模式遵循 code--[lang] 命名,[lang] 为 ISO 639-1 语言代码(如 zh、ja、es)。原文档提示 code--zh 已内置,无需额外安装。当前仓库 plugin/modes/ 目录下实际存在 30 余个模式文件,覆盖 ar/bn/cs/da/de/el/es/fi/fr/he/hi/hu/id/it/ja/ko/nl/no/pl/pt-br/ro/ru/sv/th/tr/uk/ur/vi 等语言,以及 code--chill、email-investigation、law-study、meme-tokens 等工作流变体,与 README 的"多模式"描述一致。

源码级机制(锦上添花): 模式加载由 src/services/domain/ModeManager.ts 完成,几个值得注意的实现细节:

1. 继承语法:模式 ID 用 -- 分隔父模式与覆盖层,如 code--zh 表示"在 code 基础上应用 zh 覆盖",且仅支持一层继承(超过两段直接抛错);
2. 深度合并:覆盖文件通过 deepMerge 与父模式逐键合并,code.json 定义观察类型(bugfix/feature/refactor/change/discovery/decision/security_alert/security_note/sensitive 共 9 类)与知识概念(how-it-works/why-it-exists/what-changed/problem-solution/gotcha/pattern/trade-off 共 7 类),语言覆盖文件通常只替换提示词;
3. 查找顺序:依次为环境变量 CLAUDE_MEM_MODES_DIR → 数据目录下的 modes/(用户自建模式,跨插件升级持久)→ 包内 modes/(生产,即 plugin/modes)→ 开发布局 plugin/modes;
4. 优雅降级:模式文件缺失时回退到 code;若连 code 都丢失则视为致命错误。

以 plugin/modes/code.json 为例,其中 prompts 字段包含观察者的系统身份、"静默设计"(被观察会话不知道自己在被观察)、记录焦点、跳过指引、9 类观察类型的硬约束、XML 输出格式等提示词模板——这就是"语义化压缩"在提示词层的完整实现。

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

八、开发、故障排查与缺陷报告

• 开发:构建、测试与协作流程见 docs/public/development.mdx;
• 故障排查:直接把问题描述给 Claude,troubleshoot 技能会自动诊断并给出修复;常见问题见 docs/public/troubleshooting.mdx;
• 缺陷报告:使用自动生成的报告工具:

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

该命令对应仓库根 package.json 中的 bug-report 脚本(bun scripts/bug-report/cli.ts),收集器实现见 scripts/bug-report/collector.ts。

九、许可与边界

Claude-Mem 采用 Apache License 2.0(见 LICENSE)。官方解释:持久型 Agent 记忆应当易于嵌入开发者工具、本地 Agent、MCP 服务器、企业系统、机器人栈与生产级 Agent 框架,因此选择了 Apache-2.0。许可范围与开源/商业边界详见 docs/license.md 与 docs/ip-boundary.md。ragtime/ 目录单独声明 Apache License 2.0(见 ragtime/LICENSE)。

最后,波兰语文档末尾保留了 CMEM 相关说明:CMEM 是第三方创建、但被 Claude-Mem 作者官方认可的社区代币,定位为社区增长催化剂——这部分属于社区生态说明,与技术实现无关,仅作完整继承记录。

小结

这篇波兰语 README 浓缩了 Claude-Mem 的完整用户面:一条命令安装(npx claude-mem install,注意区分 npm -g 仅装 SDK)、5 个生命周期 Hook 驱动的自动记忆管线、Bun 托管的 worker + SQLite + Chroma 存储栈、3 层工作流的 4 个 MCP 检索工具(约 10 倍 token 节省)、code--[lang] 命名模式体系(由 ModeManager 的继承/深合并机制支撑)以及 Apache-2.0 许可边界。所有关键结论均可在仓库对应文件中复核:安装命令对应 src/npx-cli/commands/install.ts,Hook 注册对应 plugin/hooks/hooks.json,MCP 工具对应 src/servers/mcp-server.ts,模式系统对应 src/services/domain/ModeManager.ts 与 plugin/modes/,配置默认值对应 src/shared/SettingsDefaultsManager.ts。