claude-mem 跨会话持久记忆指南：安装、三层搜索工作流与 CLAUDE_MEM

claude-mem 跨会话持久记忆指南：安装、三层搜索工作流与 CLAUDE_MEM_MODE 配置全解析

【免费下载链接】claude-memPersistent Context Across Sessions for Every Agent – Captures everything your agent does during sessions, compresses it with AI, and injects relevant context back into future sessions. Works with Claude Code, OpenClaw, Codex, Gemini, Hermes, Copilot, OpenCode + More项目地址: https://gitcode.com/GitHub_Trending/cl/claude-mem

本文基于 docs/i18n/README.th.md（泰语版项目文档）撰写，是 claude-mem 这一跨会话持久上下文（Persistent Context Across Sessions）系统的完整技术指南。读完本文，你将掌握 claude-mem 的四种安装路径（Claude Code、OpenCode、Antigravity CLI、OpenClaw 网关）、六大核心组件的工作机制、基于 MCP 工具的「search → timeline → get_observations」三层省 token 检索工作流，以及通过CLAUDE_MEM_MODE配置工作流模式与观察记录语言（含泰语）的完整方法。

一、claude-mem 是什么

claude-mem 是一套为 Claude Code）。

在仓库中，该文档存在 30+ 种语言的翻译版本（见 docs/i18n/），本文所依据的泰语版与英文主文档 README.md 在结构上完全对齐，覆盖快速开始、工作原理、MCP 搜索工具、系统要求、配置、排障与许可等全部章节。

二、快速开始：四种安装方式

2.1 Claude Code 一键安装

npx claude-mem install

安装完成后重启 Claude Code，历史会话的上下文即会自动出现在新会话中。

2.2 为其他 IDE 安装

OpenCode：

npx claude-mem install --ide opencode

Antigravity CLI（安装器会处理依赖、插件配置、AI provider 配置与 worker 启动）：

npx claude-mem install --ide antigravity

2.3 通过 Claude Code 插件市场安装

/plugin marketplace add thedotmack/claude-mem /plugin install claude-mem

2.4 OpenClaw 网关（🦞 网关插件模式）

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

该安装器会处理依赖安装、插件设置、AI provider 配置、worker 启动，以及可选的到 Telegram、Discord、Slack 等渠道的实时观察推送。

⚠️ 重要安装注意

claude-mem 同时发布在 npm 上，但npm install -g claude-mem只会安装 SDK/库本身——它不会注册插件 hooks，也不会启动 worker service。必须始终通过npx claude-mem install或上述/plugin命令安装。这一点与仓库package.json中的files字段相符：真正随包分发的是dist、plugin/hooks、plugin/modes、plugin/skills等插件运行时资源。

三、核心功能特性

特性	说明
🧠 持久记忆	上下文跨会话存活
📊 渐进式披露	分层记忆检索，并展示 token 成本
🔍 基于技能搜索	通过 mem-search 技能查询项目历史
🖥️ Web Viewer UI	在 worker 启动时打印的 URL 上实时查看记忆流
💻 Claude Desktop 技能	在 Claude Desktop 对话中搜索记忆
🔒 隐私控制	使用`<private>`标签将敏感内容排除在存储之外
⚙️ 上下文配置	细粒度控制注入哪些上下文
🤖 全自动运行	无需人工干预
🔗 引用（Citations）	通过 worker API 以 ID 引用历史观察，或在 web viewer 中浏览全部

四、工作原理：六大核心组件

claude-mem 的系统构成如下（详见英文文档 README.md 的 How It Works 一节）：

5 个生命周期 Hooks——SessionStart、UserPromptSubmit、PostToolUse、Stop、SessionEnd（对应 6 个 hook 脚本）；
Smart Install——带缓存的依赖检查器（属于 pre-hook 脚本，而非生命周期 hook）；
Worker Service——由 Bun 管理的本地 HTTP API，附带 web viewer UI 与 search 端点；
SQLite 数据库——存储 sessions、observations、summaries；
mem-search 技能——支持渐进式披露的自然语言查询；
Chroma 向量数据库——语义 + 关键词混合搜索，用于智能上下文检索。

从源码看，plugin/hooks/hooks.json 中实际注册的事件比文档列出的还要多：除 SessionStart、UserPromptSubmit、PostToolUse、Stop 之外，还有PreToolUse（matcher 为Read，触发 file-context 注入）以及Setup事件（每次启动时运行version-check.js做版本检查）。其中 PostToolUse 与 Stop 均声明为"async": true，观察生成与摘要生成不会阻塞主会话。Hook 的完整定义可继续阅读 docs/architecture/hooks.md（仓库英文文档中的 Hooks Reference）。

五、MCP 搜索工具：三层省 token 检索工作流

claude-mem 通过4 个 MCP 工具提供智能记忆搜索，遵循三层工作流模式（token 高效设计）：

search——获取带 ID 的紧凑索引（约 50–100 token/条结果）；
timeline——围绕感兴趣的结果获取时间线上下文；
get_observations——仅对筛选后的 ID 拉取完整详情（约 500–1,000 token/条结果）。

这种「先筛选、后取详情」的顺序可以带来约 10 倍的 token 节省。

5.1 工作方式

Claude 使用 MCP 工具搜索你的记忆；
先从search得到结果索引；
用timeline查看特定观察点周边发生了什么；
用get_observations为相关 ID 拉取完整详情。

5.2 可用 MCP 工具

工具	作用
`search`	全文查询记忆索引，可按类型/日期/项目过滤
`timeline`	获取围绕某个观察或查询的时间线上下文
`get_observations`	按 ID 获取完整观察详情（多个 ID 务必批量请求）

5.3 示例

// 第 1 步：搜索获取索引 search(query="authentication bug", type="bugfix", limit=10) // 第 2 步：浏览索引，识别相关 ID（如 #123、#456） // 第 3 步：拉取完整详情 get_observations(ids=[123, 456])

5.4 源码级实现印证

mem-search 技能：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、offset、orderBy；timeline支持anchor或query自动定位锚点、depth_before/depth_after（默认 5，最大 20）；get_observations的ids为必填数组。
MCP server 实现：src/servers/mcp-server.ts 中注册了完整的工具列表。其中search通过 worker 的/api/search端点执行、timeline走/api/timeline、get_observations走/api/observations/batch（批量取详情，印证文档「批量请求」的建议），并提供了important_workflow工具用于向 agent 输出「先 search → 再 timeline → 最后 get_observations」的强制指引；当 worker 未启动时，MCP server 还会通过ensureWorkerStarted自动拉起 worker。
技能文档还提示：如需得到综合答案而非原始记录，可以使用/knowledge-agent（在 docs/public/usage/knowledge-agents.mdx 有更详细介绍）。

六、发布分支策略

稳定版（Stable）从main分支发布并推送至 npm；core-dev与community-edge是从源码运行的分支，用于早期可靠性修复与社区集成。完整的分支流转与不稳定版本本地运行方法，见英文文档 docs/public/branches.mdx。

七、系统要求

组件	要求
Node.js	20.0.0 及以上（仓库`package.json`的`engines`字段标注为`>=20.12.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：从 https://nodejs.org 下载最新 Node.js 安装包，安装后重启终端。仓库中还提供了专门的 Windows 修复记录，见 docs/bug-fixes/windows-spaces-issue.md。

八、配置：settings.json 与 CLAUDE_MEM_MODE

8.1 配置文件位置与默认值

所有设置统一管理在~/.claude-mem/settings.json（首次运行时自动创建并写入默认值）。可配置项包括：AI 模型、worker 端口、数据目录、日志级别与上下文注入设置。

从源码 src/shared/SettingsDefaultsManager.ts 可以看到一批关键默认值：

配置项	默认值	说明
`CLAUDE_MEM_MODEL`	`claude-haiku-4-5-20251001`	观察生成默认模型
`CLAUDE_MEM_WORKER_PORT`	`37700 + (uid % 100)`	按 UID 派生端口，实现多账号隔离
`CLAUDE_MEM_DATA_DIR`	`~/.claude-mem`	数据目录
`CLAUDE_MEM_LOG_LEVEL`	`INFO`	日志级别
`CLAUDE_MEM_CONTEXT_OBSERVATIONS`	`50`	每次注入的观察条数
`CLAUDE_MEM_CHROMA_ENABLED`	`true`	是否启用 Chroma 向量搜索（设为`false`则退化为纯 SQLite 搜索）
`CLAUDE_MEM_MODE`	`code`	默认工作流模式

8.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/

可用模式示例（完整列表见 plugin/modes/）：

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

语言特定模式遵循code--[lang]命名规律，其中[lang]为 ISO 639-1 语言代码（如zh中文、ja日语、es西班牙语）。在当前仓库的 plugin/modes/ 目录中，实际存在包括code--zh.json、code--ja.json、code--th.json（泰语）在内的数十个语言模式文件，以及code--chill.json、email-investigation.json、law-study.json等工作流模式，覆盖范围远超文档表格所列。每个模式文件（以 plugin/modes/code.json 为例）内部定义了observation_types（如 bugfix、feature、refactor、decision、discovery、security_alert、sensitive 等 9 类）、observation_concepts（如 how-it-works、problem-solution、gotcha、trade-off 等）以及整套观察生成的 prompts 模板。

说明：code--zh（简体中文）已内置，无需额外安装或更新插件。

切换模式后：重启 Claude Code 即可生效。

九、开发、排障与 Bug 报告

开发：构建、测试与贡献流程详见英文文档 docs/public/development.mdx。仓库package.json中提供了完整的开发脚本：npm run build（构建插件）、bun test tests（运行测试）、npm run typecheck（类型检查）等。
排障：遇到问题可向 Claude 描述症状，troubleshoot 技能会自动诊断并给出修复方案；通用问题与解决方案见英文文档 docs/public/troubleshooting.mdx。
Bug 报告：使用仓库内置的自动化生成器生成完整报告：

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

贡献：欢迎任何形式的贡献。流程为 Fork 仓库 → 创建 feature 分支 → 带测试的改动 → 更新文档 → 提交 Pull Request。仓库从三条分支发布：main（stable）、core-dev、community-edge，其中只有main会发布到 npm，其余分支从源码运行。

十、许可证

claude-mem 采用Apache License 2.0。选择该许可证的原因在于：持久化 agent 记忆应当易于嵌入各类开发者工具、本地 agent、MCP server、企业系统、机器人技术栈与生产环境 agent harness 之中。

完整条款见 LICENSE；
许可范围与开源/商业边界见 docs/license.md 与 docs/ip-boundary.md；
关于 Ragtime：仓库中的ragtime/目录同样遵循 Apache License 2.0，详见 ragtime/LICENSE。

十一、更多资源

英文主文档 README.md 提供了完整的官方文档导航，覆盖：安装指南、使用指南、搜索工具、Context Engineering（AI agent 上下文优化原则）、Progressive Disclosure（渐进式披露设计哲学）、架构总览与演进（v3 → v5）、Hooks 架构与 7 个 hook 脚本详解、Worker Service（HTTP API 与 Bun 管理）、数据库（SQLite schema 与 FTS5 搜索）、搜索架构（Chroma 混合检索）、配置指南与 Release Branches 等主题，均可作为深入阅读的入口。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考