Claude-Mem 完整上手指南：安装、架构、MCP 三层检索与模式配置（基于仓库 README 日文版）

本文以当前仓库的日文版项目 README docs/i18n/README.ja.md 为主体，系统讲解 Claude-Mem 这套「会话间持久记忆压缩系统」的全部核心内容：四种安装方式（含 npm 全局安装的常见误区）、六大核心组件的工作机制、基于 MCP 工具的三层记忆检索工作流、settings.json 与 CLAUDE_MEM_MODE 模式/语言配置的实操方法，并结合同仓库的 hooks.json、mcp-server.ts、SettingsDefaultsManager.ts 等源码补充参数默认值与底层实现证据。读完后，你可以独立完成安装、理解其数据流，并通过 search → timeline → get_observations 三层工作流以约 10 倍 token 节省查询项目历史。

---

1. Claude-Mem 是什么

用日文 README 原文的表述（中文转述）：Claude-Mem 会自动捕获工具使用过程、生成语义摘要、并在未来的会话中使其可用，从而在会话之间无缝保持上下文。也就是说，当 Claude 的某个会话结束或重新连接后，它对项目的认知依然保持连续，而不需要从空白开始。

一句话概括其技术形态：基于 Claude Code 生命周期钩子的记忆捕获 + AI 压缩 + 本地 SQLite/向量混合检索 + 上下文回注。

---

2. 快速开始：四种安装方式

2.1 一行命令安装（Claude Code）

npx claude-mem install

2.2 为 OpenCode 安装

npx claude-mem install --ide opencode

2.3 为 Antigravity CLI 安装

npx claude-mem install --ide antigravity

（README 原文此处链接到外部站点 docs.claude-mem.ai 的 antigravity-cli 设置页；仓库内的对应文档为 docs/public/antigravity-cli/setup.mdx，安装器实现位于 src/npx-cli/commands/。）

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

2.5 OpenClaw 网关（可选）

仓库内 openclaw/ 目录提供了 OpenClaw 网关的持久记忆插件（openclaw.plugin.json、openclaw/install.sh）。README 原文给出的安装方式为一条 curl | bash 远程脚本，安装器会处理依赖、插件配置、AI 提供商配置、worker 启动以及 Telegram/Discord/Slack 的可选实时观察流。仓库内可参考 openclaw/TESTING.md 了解其验证方式。

主要特性（README 原文清单）

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

---

3. 工作机制：六大核心组件

README「仕組み（仕組み）」一节列出的核心组件，以及同仓库源码中的对应实现：

1. 生命周期钩子 —— README 原文写「5 个生命周期钩子：SessionStart、UserPromptSubmit、PostToolUse、Stop、SessionEnd（6 个钩子脚本）」。从源码看，plugin/hooks/hooks.json 实际注册了 6 个事件键：Setup、SessionStart、UserPromptSubmit、PostToolUse、PreToolUse（仅匹配 Read 工具）、Stop。每个钩子都是一条 bash 命令，先定位插件安装目录（含 ~/.claude/plugins/cache 下的版本排序逻辑与 Windows 下 cygpath 转换），再通过 bun-runner.js 启动 worker-service.cjs 并传入子命令，例如：

   • SessionStart（matcher 为 startup|clear|compact）→ hook claude-code context（注入上下文）
   • UserPromptSubmit → hook claude-code session-init
   • PostToolUse（matcher *，async: true，超时 120s）→ hook claude-code observation（捕获观察）
   • PreToolUse（matcher Read，async: true）→ hook claude-code file-context
   • Stop（async: true，超时 120s）→ hook claude-code summarize（生成摘要）

   钩子架构文档见 docs/public/hooks-architecture.mdx 与 docs/public/architecture/hooks.mdx。

2. 智能安装 —— 带缓存的依赖检查器（pre-fix 脚本，非生命周期钩子）。从源码结构看，Setup 钩子实际执行的是 plugin/scripts/version-check.js，负责版本一致性与依赖就绪检查；依赖检查逻辑集中在 src/shared/dependency-health.ts。

3. Worker 服务 —— 本地 HTTP API，带 Web 查看器 UI 与检索端点，由 Bun 管理。服务入口为 plugin/scripts/worker-service.cjs，检索路由实现在 src/services/worker/http/routes/SearchRoutes.ts（/api/search、/api/timeline、/api/context/inject 等），批量取观察在 src/services/worker/http/routes/DataRoutes.ts（POST /api/observations/batch）。文档见 docs/public/architecture/worker-service.mdx。

4. SQLite 数据库 —— 存储会话、观察、摘要。文档见 docs/public/architecture/database.mdx，实现集中在 src/services/sqlite/ 与 src/storage/sqlite/。

5. mem-search Skill —— 带渐进式披露的自然语言查询，skill 定义见 plugin/skills/mem-search/SKILL.md。

6. Chroma 向量数据库 —— 用于智能上下文获取的混合（语义 + 关键词）检索。从 SettingsDefaultsManager.ts 可确认相关配置默认值：CLAUDE_MEM_CHROMA_ENABLED: 'true'、CLAUDE_MEM_CHROMA_MODE: 'local'（本地模式通过 uvx 运行持久化 chroma-mcp）、CLAUDE_MEM_CHROMA_HOST: '127.0.0.1'、CLAUDE_MEM_CHROMA_PORT: '8000'。文档见 docs/public/architecture/search-architecture.mdx。

系统整体数据流可参考 docs/public/architecture/overview.mdx 与 docs/public/architecture-evolution.mdx（v3 到 v5 的演进）。

---

4. MCP 检索工具：三层工作流

这是 README 的技术核心之一。Claude-Mem 通过遵循 token 高效的三层工作流 的 MCP 工具提供智能记忆检索。

三层工作流：

1. search —— 获取含 ID 的紧凑索引（约 50～100 token/条）
2. timeline —— 获取感兴趣结果周边的时间线上下文
3. get_observations —— 仅对筛选后的 ID 获取完整详情（约 500～1,000 token/条）

机制：Claude 先用 search 拿索引，再用 timeline 查看某条观察周边发生了什么，最后用 get_observations 批量拉取相关 ID 的完整详情。因为「先筛选、后取详情」，可实现约 10 倍 token 节省。

使用示例（README 原文）：

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

// 步骤 2: 检查索引、确定相关 ID（例如 #123、#456）

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

4.1 源码级参数印证

从 src/servers/mcp-server.ts 可以看到，除 README 提到的三个工具外，MCP 服务器还定义了一个 important_workflow 工具（向模型注入上述三层工作流的说明，强调「NEVER fetch full details without filtering first. 10x token savings.」）以及 session_start_context 工具（调用 /api/context/inject，渲染与 SessionStart 钩子注入完全相同的上下文文本）。三个核心工具的真实参数 schema 为：

• search：query（检索词）、limit（默认 20）、project（按项目过滤）、platformSource（按平台源过滤，如 claude、codex、cursor）、type（observations/sessions/prompts，其他值被当作 obs_type 别名）、obs_type（如 bugfix、feature，可逗号分隔多个）、dateStart/dateEnd（ISO 日期）、offset、orderBy（date_desc 或 date_asc）。handler 最终转发到 worker 的 /api/search。
• timeline：anchor（要围绕展开的观察 ID）或 query（自动定位锚点）、depth_before/depth_after（默认各 3）、project。转发到 /api/timeline。
• get_observations：ids（观察 ID 数组，必填，始终建议批量处理）。转发到 /api/observations/batch。

mem-search skill 给出了 search 返回的表格形态示例（| ID | Time | T | Title | Read |，每条约 50～75 token），并把适用场景明确写为「用户询问之前的会话：『我们修过这个吗？』『上次 X 是怎么做的？』」。

---

5. 系统要求与 Windows 注意事项

系统要求（README 原文）：

• Node.js：20.0.0 及以上（package.json 的 engines 与徽章一致；注意当前仓库 package.json 版本为 13.24.0，而 README 徽章上的 13.4.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 后重启终端。仓库内有对应的 Windows 回归测试，如 tests/windows-hide-regressions.test.ts 与 tests/codex-transcript-watcher-windows.test.ts，说明 Windows 平台行为是被测试覆盖的一等场景。

---

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

6.1 配置文件位置与加载机制

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

源码 src/shared/SettingsDefaultsManager.ts 完整实现了「自动创建 + 默认值合并 + 环境变量覆盖」机制，关键事实：

• 文件不存在时，调用 writeJsonFileAtomic 原子写入全部默认值（loadFromFile），日志写到 stderr 而非 stdout（保持钩子框架的 stdout JSON 契约）。
• 加载顺序为：代码内 DEFAULTS ← settings.json 已持久化值 ← 环境变量（applyEnvOverrides 让 process.env 最终生效）。
• 还包含两个自动迁移：嵌套 { "env": {...} } 结构自动扁平化（有平级键时保守保留），以及 Telegram 触发类型的旧默认值迁移。

6.2 与 README 主题直接相关的默认值（摘自 SettingsDefaultsManager.ts）

配置键	默认值	说明
CLAUDE_MEM_MODEL	claude-haiku-4-5-20251001	生成观察/摘要所用模型
CLAUDE_MEM_WORKER_PORT	37700 + (uid % 100)	worker 本地 HTTP 端口，按 UID 派生实现多账户隔离
CLAUDE_MEM_WORKER_HOST	127.0.0.1	仅本地回环监听
CLAUDE_MEM_DATA_DIR	~/.claude-mem	数据目录（settings.json 所在处）
CLAUDE_MEM_LOG_LEVEL	INFO	日志级别
CLAUDE_MEM_MODE	code	默认模式（见 6.3）
CLAUDE_MEM_CONTEXT_OBSERVATIONS	50	上下文注入的观察数量
CLAUDE_MEM_SKIP_TOOLS	ListMcpResourcesTool,SlashCommand,Skill,TodoWrite,AskUserQuestion	观察捕获时跳过的工具
CLAUDE_MEM_PROVIDER	claude	无头安装缺省提供商
CLAUDE_MEM_CHROMA_ENABLED	true	设为 false 则退化为纯 SQLite 检索
CLAUDE_MEM_MAX_CONCURRENT_AGENTS	2	最大并发 SDK agent 子进程数

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

6.3 模式与语言设置（CLAUDE_MEM_MODE）

Claude-Mem 通过 CLAUDE_MEM_MODE 支持多工作流模式与多语言，同时控制两件事：工作流行为（code、chill、investigation 等）与生成观察所用的语言。

设置方法 —— 编辑 ~/.claude-mem/settings.json：

{
  "CLAUDE_MEM_MODE": "code--zh"
}

查看本地可用模式：

ls ~/.claude/plugins/marketplaces/thedotmack/plugin/modes/

README 列出的模式表：

模式	说明
code	默认英文模式
code--zh	简体中文模式
code--ja	日文模式

语言模式遵循 code--[lang] 命名，[lang] 为 ISO 639-1 语言代码。README 特别注明：code--zh 已内置，无需额外安装或更新插件。

源码纵深：从当前仓库看，plugin/modes/ 目录实际包含 code.json、code--zh.json、code--ja.json 以及大量其他语言变体（code--de、code--es、code--ko、code--ru、code--fr 等 20 余个 -- 后缀文件），另有 code--chill、email-investigation、law-study 等自定义工作流模式，与 README「code、chill、investigation 等」的表述一致。模式解析由 src/services/domain/ModeManager.ts 负责，值得注意的实现细节：

• 模式 ID 必须匹配 ^[a-z0-9]+(?:-[a-z0-9]+)*(?:--[a-z0-9]+(?:-[a-z0-9]+)*)?$，即 parent--override 单层继承，超过一层直接抛错（parseInheritance）。
• 语言模式（如 plugin/modes/code--ja.json）本质上是对基础 code 模式的提示词深度合并覆盖，其 footer/summary_footer 中携带 LANGUAGE REQUIREMENTS: Please write the observation data in 日本語 之类的语言约束，XML 占位符（title、subtitle、narrative 等）也被翻译成对应语言。
• 模式目录按优先级合并：CLAUDE_MEM_MODES_DIR 环境变量 → ~/.claude-mem/modes（用户自建模式，插件升级后依然持久）→ 包内 plugin/modes。

修改模式后：需重启 Claude Code 才能应用新配置。

---

7. 发布分支与贡献

• 稳定版从 main 分支发布并发布到 npm；core-dev 与 community-edge 是用于早期可靠性修复与社区集成的源码运行分支。完整分支策略见 docs/public/branches.mdx。

• 贡献流程（README 原文）：fork 仓库 → 创建功能分支 → 附测试提交变更 → 更新文档 → 提 PR。

• Bug 报告：仓库提供自动 bug 报告生成器，在插件安装目录下执行：

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

  其实现位于 scripts/bug-report/（index.ts、cli.ts、collector.ts）。

• 故障排查：遇到问题时可直接向 Claude 描述问题，troubleshoot skill 会自动诊断并给出修复建议；常见问题手册见 docs/public/troubleshooting.mdx。

• 开发：构建、测试与贡献工作流见 docs/public/development.mdx；本地测试可参考 bunfig.toml 与 tests/ 目录（覆盖钩子、worker、同步、遥测、SQLite 存储等模块）。

---

8. 许可证

Claude-Mem 采用 Apache License 2.0 授权（见 LICENSE）。作者在 README 中说明选择 Apache-2.0 的意图：让持久 agent 记忆能够被轻松地嵌入开发者工具、本地 agent、MCP 服务器、企业系统、机器人技术栈与生产级 agent 运行时。许可范围与开源/商业边界说明见 docs/license.md 与 docs/ip-boundary.md。

Ragtime 特别说明：ragtime/ 目录同样以 Apache License 2.0 授权（见 ragtime/LICENSE）。

---

9. 小结与延伸阅读

本文覆盖了日文 README 的全部主体内容：四种安装路径与 npm 全局安装的陷阱、六大核心组件、三层 MCP 检索工作流、系统要求与 Windows 前置条件、settings.json 与 CLAUDE_MEM_MODE 模式/语言配置、分支策略、贡献与 bug 报告流程、Apache-2.0 许可。若要进一步深入，建议按以下仓库内文档继续：

• 安装细节：docs/public/installation.mdx
• 使用入门：docs/public/usage/getting-started.mdx
• 检索工具：docs/public/usage/search-tools.mdx
• 钩子架构：docs/public/hooks-architecture.mdx
• 渐进式披露哲学：docs/public/progressive-disclosure.mdx
• OpenClaw 集成：docs/public/openclaw-integration.mdx