企业官网建设流程全解析

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 是一个为 Claude Code 构建的"持久化记忆压缩系统"：它在每次会话中自动捕获工具使用观察（observations），用 AI 压缩成语义化摘要，并在未来会话启动时把相关上下文重新注入给 Agent。本文基于仓库中的丹麦语版 README（docs/i18n/README.da.md）及其对应的源码实现，完整讲解安装方式、六条 Hooks 生命周期数据流、SQLite/Chroma 存储架构、MCP 三层搜索工作流，以及CLAUDE_MEM_MODE多语言模式配置，帮助你在自己的项目中落地"跨会话不失忆"的 Agent 工作流。

一、Claude-Mem 是什么

用仓库原文的话说：Claude-Mem 通过在会话结束时自动捕获工具使用观察、生成语义化摘要（semantic summaries），并使其在未来会话中可检索，从而在会话之间无缝保留上下文。这让 Claude 在会话结束或断开重连后依然能维持对项目知识的连续性。

官方文档（丹麦语版 README）列出的核心能力包括：

• 持久化记忆（Persistent Memory）：上下文跨会话存活；
• 渐进式披露（Progressive Disclosure）：分层获取记忆，并让 token 开销可见；
• 技能化搜索（Skill-based Search）：通过mem-search技能用自然语言查询项目历史；
• Web Viewer UI：在 Worker 启动时打印的 URL 上实时查看记忆流；
• Claude Desktop 技能：在 Claude Desktop 对话中检索记忆；
• 隐私控制：用<private>标签将敏感内容排除在存储之外；
• 上下文配置：精细控制哪些上下文会被注入；
• 全自动运行：无需人工干预；
• 引用（Citations）：通过 Worker API 用 ID 引用历史观察，或在 Web Viewer 中浏览全部记录。

二、快速开始

2.1 安装

最简安装只需一条命令：

npx claude-mem install

按目标环境安装：

# 安装到 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命令。

2.2 OpenClaw Gateway 安装

如果要把 claude-mem 作为持久记忆插件安装到 OpenClaw 网关上，可用一条 curl 命令完成：

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

安装器会自动处理依赖、插件配置、AI 供应商配置、worker 启动，以及可选的 Telegram / Discord / Slack 实时观察流。仓库中 openclaw/ 目录包含该插件的完整实现与测试脚本（如 openclaw/install.sh、openclaw/e2e-verify.sh）。

2.3 系统要求

• Node.js：20.0.0 或更高（对应 package.json 中的node >= 20.0.0约束）；
• Claude Code：支持插件（plugin）机制的版本；
• Bun：JavaScript 运行时兼进程管理器，缺失时自动安装；
• uv：Python 包管理器，用于向量搜索，缺失时自动安装；
• SQLite 3：用于持久化存储（随包附带）。

2.4 Windows 注意事项

在 PowerShell 中若看到类似错误：

npm : The term 'npm' is not recognized as the name of a cmdlet

说明 Node.js 与 npm 未安装或未加入 PATH。从 nodejs.org 下载最新的 Node.js 安装包，安装后重启终端即可。

三、架构：五条生命周期 Hooks 如何驱动记忆数据流

README 给出的核心组件清单是：

1. 5 条生命周期 Hooks—— SessionStart、UserPromptSubmit、PostToolUse、Stop、SessionEnd（共 6 个 hook 脚本）；
2. Smart Installation（智能安装）—— 带缓存的依赖检查器（属于 pre-hook 脚本，不是生命周期 Hook）；
3. Worker Service—— 本地 HTTP API，带 Web Viewer UI 与搜索端点，由 Bun 托管；
4. SQLite 数据库—— 存储会话、观察与摘要；
5. mem-search 技能—— 自然语言查询 + 渐进式披露；
6. Chroma 向量数据库—— 混合语义 + 关键词检索，实现智能上下文召回。

更完整的组件与数据流说明见 docs/public/architecture/overview.mdx，Hooks 机制详解见 docs/public/architecture/hooks.mdx。

3.1 从源码看真实的 Hook 注册表

仓库中的 plugin/hooks/hooks.json 是这份"数据流地图"的权威来源。当前版本实际注册了 6 个 Hook 事件，每一个都通过bun-runner.js调用 worker-service.cjs 的对应子命令：

几个值得注意的实现细节：

• 异步化观察：PostToolUse与Stop都标记为"async": true，观察与摘要生成不阻塞主会话，这与 README"自动运行、零人工干预"的承诺一致；
• 插件版本自解析：每条 Hook 命令的 shell 脚本都会先扫描~/.claude/plugins/cache/thedotmack/claude-mem/下的版本目录、按语义化版本排序选择最新非孤儿（无.orphaned_at标记）的缓存，再回落到marketplaces/thedotmack/plugin，保证多版本共存时总是命中正确的脚本；
• 上下文注入入口：SessionStart的第二条命令hook claude-code context正是"历史记忆回到新会话"的关键路径，MCP 侧对应的session_start_context工具会调用 worker 的/api/context/inject渲染完全相同的注入文本（见 src/servers/mcp-server.ts）。

3.2 Worker Service 与存储层

Worker Service 是本地 HTTP 服务，由 Bun 作为运行时与进程管理器托管，同时提供 Web Viewer UI（实时记忆流）和搜索端点。其架构文档见 docs/public/architecture/worker-service.mdx。

存储分两层：

• SQLite：主存储，保存会话（sessions）、观察（observations）、摘要（summaries），内置 FTS5 全文索引。Schema 与检索细节见 docs/public/architecture/database.mdx；
• Chroma 向量数据库：叠加语义向量检索，与全文检索组成混合搜索（hybrid search），为上下文召回排序。见 docs/public/architecture/search-architecture.mdx。

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

Claude-Mem 通过 MCP 工具暴露记忆检索，遵循一个 token 高效的3 层工作流模式（3-Layer Workflow）：

1. search—— 拿到带 ID 的紧凑索引（约 50–100 tokens/条结果）；
2. timeline—— 查看某个结果前后的时间线上下文；
3. get_observations—— 只对筛选后的 ID 拉取完整详情（约 500–1000 tokens/条）。

使用方式：Claude 用search获得结果索引 → 用timeline观察特定观察前后发生了什么 → 用get_observations批量取详情。先过滤再取详情，可节省约 10 倍 token。

官方示例：

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

更详细的示例见 docs/public/usage/search-tools.mdx。

4.1 源码中的工具定义与参数全集

MCP 工具集中在 src/servers/mcp-server.ts 的tools数组中定义。值得注意的第一个工具是important_workflow（L438-L471）——它没有实际查询逻辑，只是一个"自我说明书"工具，把三层工作流原样喂给调用方 Agent，强制其遵守"绝不未过滤就取详情"的约束，这就是"渐进式披露"哲学在协议层的落地。

search工具的完整入参（L474-L523）：

timeline（L524-L541）支持anchor（观察 ID）或直接给query自动定位锚点，depth_before/depth_after默认各取 3 条；get_observations（L542-L560）要求ids数组参数，底层转发到 worker 的/api/observations/batch，所以批量 ID 是一次 HTTP 调用。

此外，服务端运行时（server-beta）还额外暴露了observation_add、observation_record_event、observation_search、observation_context等observation_*工具，走 Postgres + GIN tsvector 索引的/v1/*REST 路径（L583-L659）；search工具内部也会在服务端可用且查询不含本地 Worker 才支持的过滤器时，自动路由到 PG 后端的/v1/search——从这段分支逻辑可以推断，检索链路对"本地 SQLite + Chroma"与"服务端 Postgres"两种部署形态做了透明的双轨适配。

4.2 观察类型从哪里来

search(type="bugfix")这类过滤值的定义不在 MCP 层，而在模式文件里。默认的 plugin/modes/code.json 精确约束了 9 种观察类型（observation_types）：bugfix、feature、refactor、change、discovery、decision、security_alert、security_note、sensitive，以及 7 种知识维度（concepts）：how-it-works、why-it-exists、what-changed、problem-solution、gotcha、pattern、trade-off。观察生成的提示词（observer 系统提示、跳过规则、XML 输出格式）也全部定义在该模式的prompts区块中——模式文件是"观察长什么样"的单一事实来源。

五、配置：settings.json 与 CLAUDE_MEM_MODE

5.1 配置文件

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

5.2 用 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/

README 给出的基础模式表：

语言模式的命名约定是code--[lang]，[lang]为 ISO 639-1 语言代码（zh中文、ja日语、es西班牙语……）。code--zh已内置，无需额外安装或升级插件。模式体系详解见 docs/public/modes.mdx。

5.3 从源码看模式加载与继承机制

模式加载由 src/services/domain/ModeManager.ts 实现，几个关键机制：

• 模式搜索路径（L16-L27）：依次查找环境变量CLAUDE_MEM_MODES_DIR→ 用户数据目录modes/（跨插件升级持久化的用户自建模式）→ 包内modes/→ 开发布局plugin/modes，取第一个存在的${modeId}.json；
• 一级继承（parseInheritance）：parent--override形式的模式 ID 会被拆成父模式 + 覆盖模式做深度合并（deepMerge），且只支持一层继承，a--b--c会直接抛错；
• 安全回退：找不到指定模式文件时回落到code模式，而不是让 worker 崩溃；
• ID 合法性：模式 ID 必须匹配^[a-z0-9]+(?:-[a-z0-9]+)*(?:--[a-z0-9]+(?:-[a-z0-9]+)*)?$，这也是code--zh这类命名的来源约束。

当前仓库plugin/modes/目录实际内置的模式比 README 示例表丰富得多：除code外，还有29 个语言变体（code--ar、code--bn、code--da、code--de、code--es、code--fr、code--ru、code--sv、code--zh等，覆盖阿拉伯语到越南语），以及非代码场景模式code--chill、email-investigation、law-study、law-study--chill（继承示例）和meme-tokens。

重要：修改CLAUDE_MEM_MODE之后必须重启 Claude Code 才能生效。

六、Release 分支、开发、排障与 Bug 报告

6.1 三条 Release 分支

• main：稳定版发布分支，发布到 npm；
• core-dev：源码运行的早期可靠性修复分支；
• community-edge：社区集成分支。

只有main会发布到 npm，其余两条需要从源码运行。分支流程与本地运行方式见 docs/public/branches.mdx。

6.2 开发与贡献

构建、测试与贡献工作流见 docs/public/development.mdx。贡献流程：Fork 仓库 → 建特性分支 → 带测试地修改 → 更新文档 → 提交 Pull Request。

6.3 故障排除

遇到问题时，直接把问题描述给 Claude，troubleshoot 技能会自动诊断并给出修复。常见问题清单见 docs/public/troubleshooting.mdx。

6.4 自动化 Bug 报告

在插件目录中运行生成器，自动收集环境信息生成结构化缺陷报告：

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

对应源码为 scripts/bug-report/（cli.ts入口 +collector.ts信息收集器）。

七、许可与边界

Claude-Mem 采用Apache License 2.0许可（见 LICENSE）。官方选择 Apache-2.0 的理由是：持久的 Agent 记忆应当容易嵌入开发者工具、本地 Agent、MCP 服务器、企业系统与生产级 Agent 框架。

• 许可范围与"开源 vs 商业"的边界说明：docs/license.md、docs/ip-boundary.md；
• Ragtime 特别说明：ragtime/ 目录同样在 Apache 2.0 下许可，详见 ragtime/LICENSE，其向量时间序列检索实现见 ragtime/ragtime.ts。

八、延伸阅读（仓库内文档索引）

一句话总结：Claude-Mem 的工程骨架是"Hooks 捕获 → Observer 压缩 → SQLite/Chroma 双存储 → 三层 MCP 检索 → SessionStart 回注"的闭环；理解 plugin/hooks/hooks.json 的六条 Hook 与 src/servers/mcp-server.ts 的工具定义，基本就掌握了它的全部行为面。

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