文件即真理：深度解析 OpenClaw 的 Markdown 记忆系统

OpenClaw：当AI的记忆，不再只存在于对话窗口里

大多数AI Agent的记忆，仿佛一场限时的烟火，绽放在对话窗口里，窗口一关，记忆也随之消散。

OpenClaw选择了一条截然不同的道路：它把最古老、最可靠的文件系统，直接当成了AI的大脑。

一、问题的起点：AI Agent为什么会“失忆”？

但凡深度使用过AI Agent的朋友，恐怕都体验过这种熟悉又无奈的场景——

昨天你和它促膝长谈两小时，从项目蓝图到技术选型，甚至包括你个人的一些独特癖好，都掰开揉碎讲了个遍。今天，你满心期待地打开一个新聊天窗口，却发现坐在对面的，又是一位需要你从头认识的“陌生人”。一切归零，一切重来。

问题根源，往往不在于模型的智商，而在于记忆层的架构缺陷。

传统方案将记忆局限在上下文窗口里。这个窗口本质上是易失的、有容量上限的。对话一旦变长，早期的信息就会被无情地裁剪、丢弃。每一次新对话的开启，都是一次彻底的“清零重启”。

OpenClaw给出的答案，简单得有些“叛逆”，却也彻底得令人信服：

文件不会消失。那就把记忆，写进文件里。

二、文件即OS：OpenClaw的核心哲学

从最底层的设计哲学来看，OpenClaw几乎是把文件系统直接提升为整个Agent的操作系统。

在这套理念下，一切皆为文件：

没有复杂的数据库，没有抽象的向量存储，更没有依赖网络的云端服务。就是一堆实实在在的Markdown文件，安静地躺在你的本地文件系统里。它们可以用Git追踪版本，可以用文本编辑器直接打开读写，一切对用户来说都直观可见。

这种设计带来的一个巨大优势，是其他系统难以企及的：透明的可见性。你永远不需要去猜测Agent“脑子里”到底记住了什么，直接打开文件夹，一切便了然于胸。

三、记忆的三层模型

OpenClaw的记忆不是一个简单的扁平化存储，而是精心设计的三层结构，巧妙地对应了人类记忆的工作方式：

┌─────────────────────────────────┐│ 工作记忆（Working Memory） │← 当前上下文窗口，易失│系统提示 + 对话历史 + 工具结果 │└────────────────┬────────────────┘ │ 超限时自动压缩 ▼┌─────────────────────────────────┐│ 短期记忆（Compaction）│← 压缩摘要，保留要点│ 当前会话的历史摘要│└────────────────┬────────────────┘ │ 重要信息手动写入 ▼┌─────────────────────────────────┐│ 长期记忆（Memory Files）│← 持久文件，永不消失│MEMORY.md + memory/日期.md │└─────────────────────────────────┘

工作记忆：存放在当前模型的Token窗口内，访问速度最快，信息最新鲜，但会话结束即消失。

短期记忆（Compaction）：当上下文窗口即将填满时，系统会自动将旧的对话内容压缩成精炼摘要，保留关键信息梗概，从而为新的对话腾出空间。你可以把这看作是Agent的“工作台定时清理”机制。

长期记忆（Memory Files）：这才是OpenClaw的核心创新所在。只有被明确写入文件的信息，才有资格跨越不同的会话周期持久保存下来。“文件即真理”的说法，正是源于此。

文件是唯一真正持久的记忆层。 任何没有被写进文件的信息，都不算真正被Agent“记住”。

四、两类核心文件：MEMORY.md vs 日期日志

MEMORY.md —— 长期知识库

MEMORY.md是Agent的“长期记忆中枢”，专门存放那些需要被永久记住的核心知识：

# 用户偏好- 技术博客风格：口语化，有数据，结尾要有金句- 代码语言偏好：Python > Go > TypeScript- 不喜欢使用 emoji，认为不专业# 项目约定- 博客文件统一保存在 /Users/xxx/WorkBuddy/Claw/- 文件命名格式：主题-kebab-case.md- 每日自动博客任务：每天 8:00 自动生成，主题聚焦 AI Agent# 重要决策记录- 2026-03-01：选择 FastAPI 作为后端框架，原因是团队熟悉度高- 2026-03-08：暗号机制：必须先报暗号才执行任务

总结一下MEMORY.md的核心特点：

• 仅在私有会话中加载，确保信息不会泄露到群组等公共上下文。
• 采用更新而非追加模式，始终维持文件的简洁性，避免信息臃肿。
• 内容高度结构化，按主题分节，极大方便了后续的检索。

memory/YYYY-MM-DD.md —— 每日操作日志

日期日志则扮演“流水账”的角色，采用仅追加的方式，如实记录当天发生的各项事务：

# 2026-03-14 日志## 任务：撰写 Vibe Coding 生存法则博文- 参考文章：https://juejin.cn/post/7615229750572236809- 主题：443个真实项目/84亿Token实战报告- 文件：/Users/xxx/WorkBuddy/Claw/vibe-coding-survival-guide.md## 任务：发布文章到三个平台- CSDN 编辑器已打开，等待权限- 掘金、知乎标签页已就位

日期日志的设计注重连续性与历史追溯：

• 每次会话开始时，会自动读取今天和昨天的日志内容，保证了上下文的自然衔接。
• 坚持只追加、不修改的原则，确保操作历史的完整轨迹得以保留。
• 超过30天的日志建议进行“蒸馏”，将其中的精华提炼进MEMORY.md后即可删除，防止日志文件无限膨胀。

五、检索引擎：让文件“活”起来

光有静态的文件存储是远远不够的。文件一旦多了，如何让Agent快速、准确地找到所需信息，就成了另一个关键的工程挑战。

为此，OpenClaw设计了一套混合检索系统，并通过两个核心工具暴露给Agent使用：

memory_search —— 语义搜索

查询：“用户喜欢什么代码风格”→ 返回：MEMORY.md 第 12 行，相关度 0.94→ 片段：“代码语言偏好：Python > Go > TypeScript”

memory_search的强大之处在于其混合检索机制：

• 70%权重来自BM25全文检索：基于SQLite的FTS5驱动，擅长精确的关键词匹配。
• 30%权重来自向量语义检索：利用嵌入模型捕捉文字背后的语义关联。

这两部分结果会进行加权融合。系统还会叠加时间衰减模型（让近期文件的检索结果权重更高）和MMR多样性重排（避免返回大量内容重复的片段），最终召回最相关、最有价值的记忆片段。

memory_get —— 精确读取

memory_get(“MEMORY.md”, line=1, count=50)→ 返回 MEMORY.md 的前50行完整内容

当你确切地知道某段记忆存在于哪个文件、甚至哪几行时，直接使用memory_get进行精确读取，效率远高于盲目的搜索。

六、系统韧性：永不崩溃的四级降级链

OpenClaw记忆系统有一个值得称道的细节设计：四级降级链。它确保了核心的检索功能在任何情况下都不会完全失效。

系统调用嵌入模型的优先级顺序如下：

本地模型（Ollama/LM Studio）↓ 不可用时OpenAI text-embedding-3↓ 不可用时Gemini / Voyage / Mistral↓ 全部不可用时SQLite FTS5 全文检索（纯关键词）

这意味着，即便所有依赖的外部嵌入API服务全部瘫痪，系统依然可以回退到最基础的关键词全文检索模式，继续提供服务。记忆系统永远不会因为某个外部环节的故障而彻底“崩溃”。

这体现了一种工程上的务实与谦逊：不假设外部服务永远完美可用，从而在最坏的情况下，依然能守住核心功能的底线。

七、实践指南：怎么用好这套系统

写入策略

跨会话需要记住的 → MEMORY.md（更新已有内容）今天做了什么事→ memory/YYYY-MM-DD.md（追加）工具配置和路径→ TOOLS.md用户偏好设定 → MEMORY.md 的“用户偏好”节重要架构决策 → MEMORY.md 的“决策记录”节

可以牢记一条黄金法则：如果你希望下次开启会话时Agent还能用上某条信息，那么最好的办法，就是把它写进对应的文件里。

检索优化建议

• 启用混合检索：在配置中务必设置memorySearch.enabled: true，不要仅仅依赖单一的关键词搜索。
• 设置时间衰减：配置halfLifeDays: 30等参数，让系统自动优先召回近期的记忆。
• 定期蒸馏日志：养成每月将日期日志的精华提炼到MEMORY.md的习惯，然后删除旧的日志文件。
• 结构化内容：在文件中积极使用Markdown标题进行分节，这能有效提升向量检索时文本分块的精准度。

安全注意事项

由于Agent被赋予了写文件的权限，一个不可忽视的风险是“记忆注入攻击”：恶意指令有可能通过特定的输入，被写入MEMORY.md这样的核心文件，从而影响甚至操控Agent后续的所有行为。

为此，建议采取以下措施：

• 敏感信息隔离：密码、API密钥等敏感信息，绝对不要写入工作区的记忆文件，应使用环境变量等更安全的方式管理。
• 定期审计：定期检查MEMORY.md等核心文件的内容，确认没有被异常写入或篡改。
• 访问控制：确保MEMORY.md被设置为私有模式，不会在群组或公共会话的上下文中暴露。

八、为什么“文件即真理”是一个好答案

让我们回到最初那个根本性的问题：AI Agent的记忆，到底应该存储在哪里？

数据库？版本不透明，迁移起来也麻烦。

云端服务？存在隐私泄露风险，并且高度依赖网络。

向量数据库？检索过程宛如黑盒，出了问题难以调试。

OpenClaw旗帜鲜明地给出了自己的答案：纯文本文件。

• 可读性：人类可以直接打开阅读、编辑修改，没有任何理解障碍。
• 可追踪性：天然支持Git等版本控制工具，每一次修改都有迹可循。
• 可移植性：复制整个文件夹，就能完整迁移Agent的全部记忆。
• 可调试性：当对检索结果存疑时，直接打开源文件对照验证即可。

这套方案并非什么惊世骇俗的黑科技，恰恰相反——它更像是对当前AI领域普遍存在的“过度工程化”倾向的一种温和对抗。

很多时候，最好的系统，往往就是那个最直接、最简单的系统。

文件不会“失忆”，文件不会“宕机”，文件永远安静而忠诚地待在那里。

文件即真理（Files are the source of truth）——这短短的六个字，不仅是OpenClaw整个记忆系统的设计宣言，也构成了它区别于其他所有AI Agent框架最根本、最独特的底色。

参考资料

• OpenClaw 官方文档 · 记忆系统
• AI Agent 记忆系统实战：OpenClaw Memory 最佳实践
• OpenClaw 记忆系统深度拆解：AI Agent 是如何“记住你”的
• OpenClaw MEMORY.md 完整指南