OpenClaw 记忆：架构与工程要点

罗光宣

1. 先把话说清：问题是什么

大模型接口常常是无状态的：一次请求带一块上下文，窗口外的内容默认不存在——俗称「金鱼记忆」。              要做长期助手、要沉淀偏好与事实，必须把记忆工程化：存哪里、怎么查、何时写、压缩时怎么不丢。

OpenClaw 是跑在 Node.js / TypeScript 上的 Agent 编排框架（常被称为 Agentic Harness）：把工具和你选的模型接起来。它不是某个大模型本体；记忆是它要解决的系统能力之一。

2. 核心直觉：文件给人看，数据库给机器搜

OpenClaw 记忆里最醒目的选择，是 Markdown 当「真源（source of truth）」：

·人能用任意编辑器打开、diff、Git 管理。

·模型读写的文本形态简单，少一层业务自定义序列化。

这不等于「只要记事本」。常见做法是：磁盘上的 Markdown 一变，监听程序就触发 分块 → 嵌入 → 索引，落到 SQLite（及 sqlite-vec、FTS5 等扩展）里，供检索用。              一句话：文件负责「可审计、可协作」；索引负责「快、准、可混合策略」。

3. 日常最打交道的两层文件

长期层往往有更细的加载策略（例如仅主会话加载），具体以你的配置为准。

4. SQLite 里通常在管什么

思路可以记成两步：

1.写：对话进 Markdown → 监听变更 → 切块、向量化 → 写入一组表。 

2.查：同一记忆既可走 向量相似度，又可走 BM25 全文，再按策略融合。

常见表角色（名称以版本为准）：

·files：文件内容哈希，判断要不要重索引。 

·chunks：文本块 + 向量。 

·chunks_vec：向量索引（维度常与当前嵌入模型一致；换模型可能要重建）。 

·chunks_fts：全文检索。 

·embedding_cache：避免重复算嵌入。

5. 检索：三种模式，各管一类问题

·embedding：偏语义、「说法不完全一样也能撞上」。 

·context：偏关键词、时间、专有名词。 

·hybrid：先缩小候选再重排，在召回与精确之间折中。

工程上还常见两层栈：主通道偏 BM25 + 重排序；嵌入侧可用本地 gguf 等方案降延迟——具体默认与超时以你本机配置为准。媒体上「比旧 CPU 方案快两个数量级」一类说法，多半是特定实现对比，写材料前请自己压测。

6. 何时写入：四条常见触发

1.你明确说「记住……」

2.对话里自然出现稳定偏好或决定

3.预压缩刷新：上下文快满、要做摘要之前，先静默写一轮，把该留的落到盘里——避免「一压缩，细节蒸发」。 

4.心跳 / 定期：把近日记要的事精炼进 MEMORY.md 一类长期载体。

预压缩这条最值得单独记：压缩往往是破坏性的（原文被摘要替换），所以先持久化再压缩是产品体验上的关键细节。触发阈值一类公式会随版本调整，以文档为准。

7. 「十二层」地图：当示意图用

社区文档里常出现一张 12 层记忆分工表（策略、项目、事实、日志、插件等），用来讨论隔离与职责。要牢记三点：

·它多是能力拆解模型，不是你装完就自动拥有十二块独立子系统。 

·表里写「向量数据库」可能是 sqlite-vec 或外接 Qdrant 等——以插件为准。 

·结构化事实（facts）的路径、类别键名会迭代；部署前对照源码或配置，不要背死表格。

8. 和几条常见路线比：一张表够了

网上偶有 Mem0 / OpenAI Memory / LangMem 的准确率、延迟、token 对比表：任务与模型一变，名次就变，只适合感受权衡，不能当采购依据。

9. 值得爱的点 vs 要接受的代价

值得爱的点

·透明：记忆与配置大量落在文本文件，合规与排障友好。 

·混合检索：比「只信向量」更扛真实查询形态。 

·压缩前刷新：直接打在「长对话必丢细节」的痛点上。 

·本地优先叙事：嵌入与数据可本地化，成本与隐私多一手牌（仍要付运维与安全成本）。

要接受的代价

·安全面大：网关 + 工具 + 可写记忆 = 注入与越权是常态威胁，必须最小权限与审计。 

·复杂：不是装完即用的聊天 App。 

·生态绑定：深度用 OpenClaw，就要接受其插件与社区节奏；想记忆层完全中立，多看中间件路线。

10. 场景粗分

较合适：个人或团队助理、要强审计的知识沉淀、你愿意管一台「长期跑的 Agent」、嵌入想本地化。              要谨慎：直接对公网用户暴露、强资源约束环境、只想三天出个 Demo、记忆需高频程序化改写且要强事务。

11. 趋势（短）：行业在往哪走

多模态记忆、细粒度遗忘与权限、分布式同步、端到端审计——都是方向，不是 OpenClaw 已全实现的清单。对你有用的态度是：按业务挑两三条真正痛的，再对齐路线图。

12. 若你动手：四条纪律

「威胁建模」若你听过：安全领域里的 threat modeling（威胁建模），「威胁」指可能对系统造成的伤害（注入、越权、误删数据等），不是日常说的「威胁某个人」。下面第 1 条用白话写了同一件事。

1.先梳理安全风险与攻击面（谁会滥用工具、能写到哪些路径），再开工具与写盘权限。 

2.记忆写入先灰度，观察「记了什么、检索回了什么」。 

3.做最小评测：同一批问题，有记忆 / 无记忆差多少。 

4.默认支持删改与导出——记忆与隐私同一条线。

结语

OpenClaw 记忆最值得记住的形状是：Markdown 真源 + SQLite 索引 + 混合检索 + 压缩前刷新。              选型上：要文件级可审计的一体化 Agent，把它放进短名单；要绑在既有框架上，先把手头生态用透；要记忆服务化，看 Mem0 / MemOS 一类。