文件即真理：深度解析 OpenClaw 的 Markdown 记忆系统
大多数 AI Agent 的记忆，存在于对话窗口里，窗口关闭，记忆消失。 OpenClaw 选择了一条不同的路：把文件系统当成 Agent 的大脑。
一、问题的起点：AI Agent 为什么会"失忆"？
用过 AI Agent 的人都有过这种体验------
你昨天跟它聊了两个小时，把项目背景、技术选型、你的偏好全都解释了一遍。今天打开新对话，它又变成了一个什么都不知道的陌生人。你只能重新解释一遍，然后再重新解释一遍。
这不是 AI 不够聪明，是记忆层没有设计好。
传统 Agent 的记忆存在于上下文窗口里。上下文窗口是易失的、有限的，一旦超出长度限制，早期的内容就会被截断丢弃。每次新对话，一切清零。
OpenClaw 给出的答案很简单，也很彻底：
文件不会消失。把记忆写进文件。
二、文件即 OS：OpenClaw 的核心哲学
OpenClaw 最底层的设计理念，是把文件系统当成 Agent 的操作系统。
在这套体系里，一切皆是文件：
| 组件 | 文件 | 作用 |
|---|---|---|
| Agent 人格 | SOUL.md |
定义语气、个性、角色边界 |
| 行为准则 | policy.md |
约束 Agent 的行为边界 |
| 长期记忆 | MEMORY.md |
跨会话持久保存的核心知识 |
| 短期日志 | memory/YYYY-MM-DD.md |
当日操作记录，仅追加 |
| 工具说明 | TOOLS.md |
用户维护的工具笔记和配置 |
| 自动任务 | HEARTBEAT.md |
定期执行任务的检查清单 |
不是数据库，不是向量存储，不是云端服务。 就是一堆 Markdown 文件，放在你的本地文件系统里，Git 可以追踪，文本编辑器可以打开，人类可以直接读写。
这种设计有一个好处，大多数系统都做不到：透明。你不需要猜测 Agent "记得什么"，打开文件夹就能看到。
三、记忆的三层模型
OpenClaw 的记忆不是一个扁平的键值对，而是三层结构，对应人类记忆的三个层次：
markdown
┌─────────────────────────────────┐
│ 工作记忆（Working Memory） │ ← 当前上下文窗口，易失
│ 系统提示 + 对话历史 + 工具结果 │
└────────────────┬────────────────┘
│ 超限时自动压缩
▼
┌─────────────────────────────────┐
│ 短期记忆（Compaction） │ ← 压缩摘要，保留要点
│ 当前会话的历史摘要 │
└────────────────┬────────────────┘
│ 重要信息手动写入
▼
┌─────────────────────────────────┐
│ 长期记忆（Memory Files） │ ← 持久文件，永不消失
│ MEMORY.md + memory/日期.md │
└─────────────────────────────────┘工作记忆：存在于当前 Token 窗口，最快最近，但会消失。
短期记忆（Compaction）：当上下文快满时，系统自动把旧对话压缩成摘要，保留关键信息，释放窗口空间。这是 Agent 的"工作台清理"机制。
长期记忆（Memory Files）：只有写进文件的东西才能跨越会话边界存活。这是 OpenClaw 的核心创新，也是"文件即真理"这个说法的来源。
文件是唯一持久的记忆层。 没有写进文件的东西，不算真正被记住。
四、两类核心文件：MEMORY.md vs 日期日志
MEMORY.md ------ 长期知识库
MEMORY.md 是 Agent 的"长期记忆中枢"，存放的是需要永久保留的核心知识：
markdown
# 用户偏好
- 技术博客风格：口语化，有数据，结尾要有金句
- 代码语言偏好：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 ------ 每日操作日志
日期日志是仅追加的流水账，记录当天发生的事：
markdown
# 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后删除，防止积累过多
五、检索引擎：让文件"活"起来
光有文件还不够。文件多了，如何快速找到相关内容，是另一个工程问题。
OpenClaw 为此设计了一套混合检索系统，通过两个工具暴露给 Agent：
memory_search ------ 语义搜索
arduino
查询："用户喜欢什么代码风格"
→ 返回：MEMORY.md 第 12 行，相关度 0.94
→ 片段："代码语言偏好：Python > Go > TypeScript"memory_search 支持混合检索：
- 70% BM25 全文检索：SQLite FTS5 驱动，精确关键词匹配
- 30% 向量语义检索：嵌入模型捕捉语义关联
两者加权融合，再叠加时间衰减模型 （近期文件权重更高）和 MMR 多样性重排（避免返回内容重复的片段），最终召回最相关的记忆片段。
memory_get ------ 精确读取
arduino
memory_get("MEMORY.md", line=1, count=50)
→ 返回 MEMORY.md 的前50行完整内容当你知道记忆存在哪个文件哪一行时，直接用 memory_get 精确读取，比搜索更高效。
六、系统韧性：永不崩溃的四级降级链
OpenClaw 的记忆系统有一个细节设计值得单独说：四级降级链。
嵌入模型的优先级顺序是：
arduino
本地模型（Ollama/LM Studio）
↓ 不可用时
OpenAI text-embedding-3
↓ 不可用时
Gemini / Voyage / Mistral
↓ 全部不可用时
SQLite FTS5 全文检索（纯关键词）即使所有嵌入 API 全部挂掉，系统仍然可以通过关键词检索提供服务，记忆系统永远不会因为外部依赖失效而完全崩溃。
这是一种工程上的谦逊：不假设外部服务永远可用，在最坏情况下也保住核心功能。
七、实践指南：怎么用好这套系统
写入策略
arduino
跨会话需要记住的 → MEMORY.md（更新已有内容）
今天做了什么事 → memory/YYYY-MM-DD.md（追加）
工具配置和路径 → TOOLS.md
用户偏好设定 → MEMORY.md 的"用户偏好"节
重要架构决策 → MEMORY.md 的"决策记录"节黄金法则：如果你希望下次会话还能用到它，就写进文件。
检索优化建议
- 启用混合检索 ：在配置里设置
memorySearch.enabled: true，不要只用关键词搜索 - 设置时间衰减 ：
halfLifeDays: 30，让近期记忆自动优先 - 定期蒸馏日志 ：每月把日期日志的精华提炼进
MEMORY.md，删除原文件 - 结构化内容：用 Markdown 标题分节，让向量检索的分块更精准
安全注意事项
因为 Agent 有写文件的权限，需要防范记忆注入攻击 ：恶意指令可能通过某些输入，被写入 MEMORY.md，影响后续会话的行为。
建议：
- 敏感信息（密码、密钥）不写入工作区文件，用环境变量
- 定期检查
MEMORY.md内容，确认没有异常写入 MEMORY.md设置为私有，不暴露在群组/公共上下文中
八、为什么"文件即真理"是一个好答案
回到最开始的问题：AI Agent 的记忆应该存在哪里？
数据库？版本不透明，迁移麻烦。
云端服务？隐私风险，依赖网络。
向量数据库？黑盒检索，难以调试。
OpenClaw 的回答是：纯文本文件。
- 可读性：人类可以直接打开、阅读、修改
- 可追踪性：Git 版本控制，每次改动有记录
- 可移植性：复制文件夹就能迁移全部记忆
- 可调试性：检索结果可疑时，直接打开文件对照
这不是什么黑科技，恰恰相反------这是对过度工程化的一种对抗。
最好的系统，往往是最简单的系统。
文件不会失忆，文件不会宕机，文件永远在那里。
文件即真理（Files are the source of truth）------这六个字，是 OpenClaw 整个记忆系统的设计宣言，也是它区别于其他 AI Agent 框架最根本的地方。