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

大多数 AI Agent 的记忆存在于对话窗口里窗口关闭记忆消失。OpenClaw 选择了一条不同的路把文件系统当成 Agent 的大脑。一、问题的起点AI Agent 为什么会失忆用过 AI Agent 的人都有过这种体验——你昨天跟它聊了两个小时把项目背景、技术选型、你的偏好全都解释了一遍。今天打开新对话它又变成了一个什么都不知道的陌生人。你只能重新解释一遍然后再重新解释一遍。这不是 AI 不够聪明是记忆层没有设计好。传统 Agent 的记忆存在于上下文窗口里。上下文窗口是易失的、有限的一旦超出长度限制早期的内容就会被截断丢弃。每次新对话一切清零。OpenClaw 给出的答案很简单也很彻底文件不会消失。把记忆写进文件。二、文件即 OSOpenClaw 的核心哲学OpenClaw 最底层的设计理念是把文件系统当成 Agent 的操作系统。在这套体系里一切皆是文件组件文件作用Agent 人格SOUL.md定义语气、个性、角色边界行为准则policy.md约束 Agent 的行为边界长期记忆MEMORY.md跨会话持久保存的核心知识短期日志memory/YYYY-MM-DD.md当日操作记录仅追加工具说明TOOLS.md用户维护的工具笔记和配置自动任务HEARTBEAT.md定期执行任务的检查清单不是数据库不是向量存储不是云端服务。就是一堆 Markdown 文件放在你的本地文件系统里Git 可以追踪文本编辑器可以打开人类可以直接读写。这种设计有一个好处大多数系统都做不到透明。你不需要猜测 Agent “记得什么”打开文件夹就能看到。三、记忆的三层模型OpenClaw 的记忆不是一个扁平的键值对而是三层结构对应人类记忆的三个层次┌─────────────────────────────────┐ │ 工作记忆Working Memory │ ← 当前上下文窗口易失 │ 系统提示 对话历史 工具结果 │ └────────────────┬────────────────┘ │ 超限时自动压缩 ▼ ┌─────────────────────────────────┐ │ 短期记忆Compaction │ ← 压缩摘要保留要点 │ 当前会话的历史摘要 │ └────────────────┬────────────────┘ │ 重要信息手动写入 ▼ ┌─────────────────────────────────┐ │ 长期记忆Memory Files │ ← 持久文件永不消失 │ MEMORY.md memory/日期.md │ └─────────────────────────────────┘工作记忆存在于当前 Token 窗口最快最近但会消失。短期记忆Compaction当上下文快满时系统自动把旧对话压缩成摘要保留关键信息释放窗口空间。这是 Agent 的工作台清理机制。长期记忆Memory Files只有写进文件的东西才能跨越会话边界存活。这是 OpenClaw 的核心创新也是文件即真理这个说法的来源。文件是唯一持久的记忆层。没有写进文件的东西不算真正被记住。四、两类核心文件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后删除防止积累过多五、检索引擎让文件活起来光有文件还不够。文件多了如何快速找到相关内容是另一个工程问题。OpenClaw 为此设计了一套混合检索系统通过两个工具暴露给 Agentmemory_search—— 语义搜索查询用户喜欢什么代码风格 → 返回MEMORY.md 第 12 行相关度 0.94 → 片段代码语言偏好Python Go TypeScriptmemory_search支持混合检索70% BM25 全文检索SQLite FTS5 驱动精确关键词匹配30% 向量语义检索嵌入模型捕捉语义关联两者加权融合再叠加时间衰减模型近期文件权重更高和MMR 多样性重排避免返回内容重复的片段最终召回最相关的记忆片段。memory_get—— 精确读取memory_get(MEMORY.md, line1, count50) → 返回 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 的决策记录节黄金法则如果你希望下次会话还能用到它就写进文件。检索优化建议启用混合检索在配置里设置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 框架最根本的地方。参考资料OpenClaw 官方文档 · 记忆系统AI Agent 记忆系统实战OpenClaw Memory 最佳实践OpenClaw 记忆系统深度拆解AI Agent 是如何记住你的OpenClaw MEMORY.md 完整指南