claude-mem 跨会话记忆系统完全指南：安装、Hooks 架构与 MCP 三层检索工作流-港品优选

claude-mem 跨会话记忆系统完全指南：安装、Hooks 架构与 MCP 三层检索工作流

【免费下载链接】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

本文基于 claude-mem 仓库的越南语官方 README（docs/i18n/README.vi.md）整理成文，系统讲解这套"为 Claude Code 构建的持续记忆压缩系统"的核心能力：一条命令完成安装、5 个生命周期 Hook 如何驱动观察捕获与语义摘要、4 个 MCP 工具构成的三层 token 高效检索模型，以及CLAUDE_MEM_MODE模式与语言配置。读完后你将掌握从安装配置到源码级原理的完整知识链路，并能直接在实际项目中落地跨会话记忆能力。

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

Claude-Mem 通过自动记录工具使用观察（observations）、生成语义摘要，并将这些上下文回注到未来的会话中，实现工作会话之间的连贯记忆。正如 README 所述："Claude-Mem 通过自动记录工具使用观察、创建语义摘要并将其提供给未来会话来维护连贯的上下文"——这使 AI 代理在项目会话结束或重连后仍能保持对项目知识的连续性。

当前 package.json 显示项目版本为13.24.0，engines字段要求node >=20.12.0与bun >=1.0.0（README 徽章标注 Node 20+，实际约束以 package.json 为准）。项目采用 TypeScript 编写，基于 Claude Agent SDK 构建，使用 Apache-2.0 许可证。

快速开始

一条命令安装

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/库——它不会注册插件的 hooks，也不会配置 worker 服务。必须通过npx claude-mem install或上述/plugin命令安装。这一点可以从 package.json 的bin字段得到印证：可执行入口是./dist/npx-cli/index.js，即 npx CLI，而不是一个全局 SDK。

OpenClaw Gateway 安装

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

安装器负责处理依赖、配置插件、设置 AI 提供商、启动 worker，并可选择将实时观察流推送到 Telegram、Discord、Slack 等。仓库内 openclaw/ 目录包含该集成的插件定义与脚本，docs/public/openclaw-integration.mdx 提供完整集成说明。

核心特性一览

持续记忆：上下文跨会话保留
渐进式披露：分层记忆检索，附带 token 成本可视化
技能化搜索：通过 mem-search 技能以自然语言查询项目历史
Web Viewer：worker 启动时打印的 URL 处提供实时记忆流界面
Claude Desktop 技能：从 Claude Desktop 对话中搜索记忆
隐私控制：使用<private>标签将敏感内容排除在存储之外
上下文配置：精细控制被注入的上下文
自动运行：无需人工干预
引用机制：通过 worker API 按 ID 引用过往观察，或在 web viewer 中浏览

工作原理：六大核心组件

README 列出了系统骨架，我们逐一对照源码验证：

5 个生命周期 Hooks— SessionStart、UserPromptSubmit、PostToolUse、Stop、SessionEnd（6 个 hook 脚本）
Smart Install— 依赖检查工具（pre-hook script，不是 lifecycle hook）
Worker Service— 由 Bun 管理的本地 HTTP API，提供 web viewer 与搜索端点
SQLite 数据库— 存储会话、观察与摘要
mem-search 技能— 带渐进披露的自然语言查询
Chroma 向量数据库— 语义 + 关键词混合检索

从 plugin/hooks/hooks.json 的源码结构看，实际注册的 Hook 事件比 README 的概括更细致：

Hook 事件	Matcher	执行的 worker 子命令	说明
`Setup`	`*`	`version-check.js`	预检查版本与插件路径（即"Smart Install"式的前置脚本）
`SessionStart`	`startup\\|clear\\|compact`	`worker-service.cjs start`+`hook claude-code context`	启动 worker 并注入历史上下文
`UserPromptSubmit`	—	`hook claude-code session-init`	用户提交提示词时初始化会话记录
`PostToolUse`	`*`（async）	`hook claude-code observation`	每次工具调用后异步捕获观察
`PreToolUse`	`Read`（async）	`hook claude-code file-context`	读文件前注入文件相关历史上下文
`Stop`	—（async）	`hook claude-code summarize`	会话停止时异步生成语义摘要

每个 hook 命令都会先在CLAUDE_PLUGIN_ROOT或~/.claude/plugins/cache/thedotmack/claude-mem/*/中按版本号排序定位插件脚本目录，再通过bun-runner.js执行worker-service.cjs（见 plugin/scripts/worker-service.cjs 与 plugin/scripts/bun-runner.js）。PostToolUse、PreToolUse、Stop 三个 hook 均设置"async": true并配置了 60–120 秒超时，说明观察捕获与摘要生成不阻塞用户交互——这与"自动运行、无感"的产品定位一致。

更完整的 hooks 生命周期说明见 docs/public/hooks-architecture.mdx 与 docs/public/architecture/hooks.mdx；worker 服务架构见 docs/public/architecture/worker-service.mdx，SQLite 与 FTS5 全文检索的数据库设计见 docs/public/architecture/database.mdx，Chroma 向量混合检索见 docs/public/architecture/search-architecture.mdx。

MCP 搜索工具：三层 token 高效检索模型

Claude-Mem 通过4 个 MCP 工具提供智能记忆搜索，遵循一套按 token 优化的三层流程（three-layer workflow）：

三层流程：

search— 获取带 ID 的轻量索引（约 50–100 token/条结果）
timeline— 获取有趣结果周围的时间线上下文
get_observations— 仅对筛选后的 ID 获取完整详情（约 500–1000 token/条）

工作方式：先用search拿到结果索引，再用timeline查看特定观察前后发生了什么，最后用get_observations只取相关 ID 的完整细节——"先筛选再取详情"带来约10 倍 token 节省。

这一工作流在 MCP server 源码中得到直接印证：src/servers/mcp-server.ts 中的工具描述明确写着三步：search(query) → Get index with IDs (~50-100 tokens/result)、timeline(anchor=ID) → Get context around interesting results、get_observations([IDs]) → Fetch full details ONLY for filtered IDs。该文件同时表明：当CLAUDE_MEM_RUNTIME=server时，另有observation_search等服务端观察工具（worker 模式下则使用现有的 search/timeline/get_observations 工具）。

各工具参数详解

结合 plugin/skills/mem-search/SKILL.md 的完整参数定义：

search工具参数：

参数	说明
`query`(string)	搜索词
`limit`(number)	最大结果数，默认 20，上限 100
`project`(string)	项目名过滤
`type`(string, 可选)	`"observations"`、`"sessions"`或`"prompts"`
`obs_type`(string, 可选)	逗号分隔：bugfix, feature, decision, discovery, change
`dateStart`/`dateEnd`(string, 可选)	`YYYY-MM-DD`或 epoch 毫秒
`offset`(number, 可选)	跳过 N 条结果（分页）
`orderBy`(string, 可选)	`"date_desc"`（默认）、`"date_asc"`、`"relevance"`

timeline工具参数：

参数	说明
`anchor`(number, 可选)	以其为中心的观察 ID
`query`(string, 可选)	未提供 anchor 时自动定位锚点
`depth_before`(number, 可选)	锚点前取 N 条，默认 5，上限 20
`depth_after`(number, 可选)	锚点后取 N 条，默认 5，上限 20
`project`(string)	项目名过滤

get_observations工具参数：

参数	说明
`ids`(array of numbers, 必填)	要获取的观察 ID 列表
`orderBy`(string, 可选)	`"date_desc"`（默认）或`"date_asc"`
`limit`(number, 可选)	最大返回条数
`project`(string, 可选)	项目名过滤

使用示例：

// 步骤 1：搜索获取索引 search(query="authentication bug", type="bugfix", limit=10) // 步骤 2：审视索引，确定相关 ID（例如 #123、#456） // 步骤 3：获取完整详情 get_observations(ids=[123, 456])

更多实战示例（查找上周发生的事、围绕某条 discovery 建立时间线、批量获取详情等）见 plugin/skills/mem-search/SKILL.md 与 docs/public/usage/search-tools.mdx。

发行分支策略

稳定版从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，从 nodejs.org 下载最新安装器，安装后重启终端。

配置

配置文件位于~/.claude-mem/settings.json（首次运行自动以默认值创建），可配置 AI 模型、worker 端口、数据目录、日志级别与上下文注入设置。完整的配置项清单与示例见 docs/public/configuration.mdx。

模式与语言配置（CLAUDE_MEM_MODE）

Claude-Mem 通过CLAUDE_MEM_MODE设置支持多种工作模式与语言，它同时控制：

工作流行为（如 code、chill、investigation）
生成的观察所使用的语言

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

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

各模式定义在plugin/modes/目录下（本仓库 plugin/modes/ 中包含code.json、code--zh.json、code--ja.json、code--chill.json、law-study.json、meme-tokens.json等 30 余个模式文件）。查看本机已安装的全部模式：

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

内置模式：

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

语言模式遵循code--[lang]命名规则，[lang]为 ISO 639-1 语言代码（如zh中文、ja日语、es西班牙语）。code--zh（简体中文）已内置，无需额外安装或更新插件。

更改模式后：重启 Claude Code 使新配置生效。

开发、排错与错误报告

开发指南：构建、测试与贡献流程见 docs/public/development.mdx
自动排错：遇到问题时可直接向 Claude 描述，troubleshoot 技能会自动诊断并给出修复方案；常见故障与解法见 docs/public/troubleshooting.mdx
自动错误报告：

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

该命令对应仓库中的 scripts/bug-report/ 目录（含cli.ts与collector.ts），用于采集环境信息并生成全面的错误报告。

许可证

Claude-Mem 采用Apache License 2.0授权。选择 Apache-2.0 的考量是：代理式持久记忆应能轻松集成进开发者工具、本地 agent、MCP 服务器、企业系统、机器人平台与生产级 agent 框架。完整条款见 LICENSE，授权范围与开源/商业边界见 docs/license.md 与 docs/ip-boundary.md。

关于 Ragtime：ragtime/目录同样采用 Apache License 2.0，详见 ragtime/LICENSE。

贡献流程

Fork 仓库
创建功能分支
提交变更并附带测试
更新文档
提交 Pull Request

Claude-Mem 从三个分支发布：main（稳定版，唯一发布到 npm 的分支）、core-dev与community-edge（从源码运行）。

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

企业官网建设流程全解析