ClawMem如何为AI编程代理提供本地持久化记忆？（附开源架构解析）

专为 Claude Code、OpenClaw、Hermes 及 AI 代理设计的本地记忆系统。 集检索增强搜索、钩子（hooks）和 MCP 服务器于一体，完全本地化运行。无需 API 密钥，无云端依赖。

ClawMem 融合了多项前沿研究，构建了一个真正可用的检索增强记忆层。其混合架构结合了源自 QMD 的多信号检索（BM25 + 向量搜索 + 倒数排序融合 + 查询扩展 + 交叉编码器重排序）、受 SAME 启发的复合评分（近期衰减、置信度、内容类型半衰期、协同激活强化）、MAGMA 风格的多图遍历意图分类（语义、时序和因果波束搜索），以及 A-MEM 式的自演进记忆笔记（为文档添加关键词、标签和条目间的因果链接）。从 Engram 借鉴的模式提取功能，则增加了去重窗口、基于频率的持久性评分和时序导航。

可通过 Claude Code 钩子、MCP 服务器（兼容任何 MCP 客户端）、原生 OpenClaw 插件或 Hermes Agent 的 MemoryProvider 插件进行集成。所有路径都写入同一个本地 SQLite 保险库。在 Claude Code 会话中捕获的决策，当 OpenClaw 或 Hermes 代理接手同一项目时，会立即显现。

基于 Bun 的 TypeScript 实现。MIT 许可证。

核心功能

ClawMem 将您的 Markdown 笔记、项目文档和研究资料转化为 AI 编码代理的持久记忆。它能自动执行以下操作：

• 在每次提示时提供相关上下文（上下文浮现钩子）
• 引导会话启动：包含您的个人资料、最近的交接记录、近期决策和过时笔记
• 从会话记录中捕获决策、偏好、里程碑和问题：使用本地 GGUF 观察者模型
• 导入对话导出文件：支持 Claude Code、ChatGPT、Claude.ai、Slack 和纯文本，通过 clawmem mine 命令，并可选择在导入后使用 LLM 进行事实提取（--synthesize），从纯文本对话转储中提取结构化的决策/偏好/里程碑/问题以及跨事实链接（v0.7.2）
• 生成交接记录：在会话结束时生成，以便下一个会话能接着您离开的地方继续
• 学习重要内容：通过反馈循环提升被引用的笔记，衰减未使用的笔记
• 防范提示词注入：在浮现的内容中防范提示词注入攻击
• 分类查询意图（WHY / WHEN / ENTITY / WHAT）：以加权不同的搜索策略
• 遍历多图（语义、时序、因果）：通过自适应波束搜索
• 演进记忆元数据：随着新文档创建或完善连接关系
• 推断事实间的因果关系：从会话观察中提取的事实之间
• 检测矛盾：在新旧决策之间，自动衰减被取代的决策（在合并工作器中增加了额外的合并时矛盾门，阻止跨观察的矛盾在落地前发生，v0.7.1）
• 防范跨实体合并：在合并期间，基于名称感知的双阈值合并安全机制，在合并相似观察前比较实体锚点，防止“Alice 决定 X”合并到“Bob 决定 X”中（v0.7.1）
• 防止衍生见解中的上下文污染：第三阶段演绎合成流水线在写入跨会话演绎观察之前，通过反污染包装器（确定性实体污染检查 + LLM 验证器 + 去重）验证每个草稿（v0.7.1）
• 将浮现的事实框定为背景知识：context-surfacing 将注入的内容包装在 <instruction> + <facts> + <relationships> 块中，告诉模型将这些事实视为已知，并直接在提示中暴露浮现文档之间的记忆图边（v0.7.1）
• 将知识图谱事实作为结构化三元组注入：当用户的提示中提到保险库已知的实体时，context-surfacing 通过三路径仅提示提取器（规范 ID、专有名词、小写 n-gram）解析它们，查询 SPO 图获取当前状态三元组，并将一个原始 subject predicate object 行的 <vault-facts> 块附加到 <vault-context> 中 — 在 speed 模式下关闭，在 balanced 模式下为 200 个 token，在 deep 模式下为 250 个 token，在三元组边界处截断（v0.9.0）
• 会话范围的焦点主题增强：clawmem focus set "<topic>" --session-id <id> 写入一个仅针对该会话的焦点文件，引导查询扩展、重排序、块选择、片段提取以及后复合评分的主题增强（匹配项 1.4 倍提升 / 非匹配项 0.75 倍降级） — 仅限会话隔离，故障开放，从不写入 SQLite 或生命周期列（v0.9.0）
• 评估文档质量：使用结构、关键词和元数据丰富度信号
• 提升协同访问的文档：经常一起浮现的笔记会获得检索强化
• 分解复杂查询：将复杂查询分解为类型化的检索子句（BM25/向量/图），以处理多主题问题
• 自动清理过时的嵌入向量：在嵌入运行前，自动清理已删除/更改文档的孤儿向量
• 事务安全的索引：索引中途崩溃不会留下任何部分状态（原子提交与回滚）
• 钩子生成观察的去重：在 30 分钟窗口内使用规范化内容哈希，防止重复钩子输出导致记忆膨胀
• 在文档周围进行时序邻域导航：通过 timeline 工具 — 从搜索到按时间顺序的上下文再到完整内容的渐进式披露
• 提升频繁修订的记忆：修订次数较多的文档在复合评分中获得持久性信号（上限为 10%）
• 支持置顶/暂停生命周期管理：用于持久性提升和临时抑制
• 管理文档生命周期：策略驱动的归档扫描，支持恢复功能
• 自动路由查询：通过 memory_retrieve — 分类意图并分派到最优的搜索后端
• 同步项目问题：从 Beads 问题跟踪器同步到可搜索的记忆中
• 运行静默窗口重度维护通道：第二个合并工作器，默认关闭，通过 CLAWMEM_HEAVY_LANE=true 启用，仅在可配置的小时窗口内以更长的间隔运行。由 context_usage 查询速率控制，因此它从不与交互式会话竞争 CPU/GPU 资源，仅通过数据库支持的 worker_leases 进行范围限定，默认优先处理陈旧任务，可选择意外性选择器，并在 maintenance_runs 中记录每次尝试以供操作员查看（v0.8.0）

完全本地运行，无需 API 密钥和云服务。通过 Claude Code 钩子和 MCP 工具、原生 OpenClaw 插件或 Hermes Agent 的 MemoryProvider 插件集成。所有模式共享同一个保险库，实现跨运行时记忆。兼容任何 MCP 客户端。

完整版本历史记录在 RELEASE_NOTES.md 中。现有保险库的升级说明在 docs/guides/upgrading.md 中。

架构

安装指南

平台支持

先决条件

必需：

• Bun v1.0+ — ClawMem 的运行时。在 Linux 上，通过 curl -fsSL https://bun.sh/install | bash 安装（不要用 snap — snap 版 Bun 无法读取 stdin，这会破坏钩子）。
• SQLite with FTS5 — Bun 已包含。在 macOS 上，安装 brew install sqlite 以获得扩展加载支持（Cl

常见问题（FAQ）

ClawMem 如何实现完全本地化运行，无需云端依赖？

ClawMem 基于 Bun 的 TypeScript 实现，所有数据存储在本地 SQLite 保险库中，无需 API 密钥或云服务，确保隐私和离线可用性。

ClawMem 支持哪些 AI 编程代理集成？

支持 Claude Code 钩子、MCP 服务器（兼容任何 MCP 客户端）、原生 OpenClaw 插件和 Hermes Agent 的 MemoryProvider 插件，所有路径写入同一本地保险库。

ClawMem 的核心功能如何帮助 AI 代理提升编码效率？

它自动提供相关上下文、捕获决策和偏好、生成会话交接记录，并通过自演进记忆笔记维护跨会话知识图，使代理能持续学习项目历史。