---

系列说明：本系列共计 20 余篇，全面介绍 OpenClaw 开源 AI 智能体框架，从历史背景到核心原理，从安装部署到应用生态。本文为系列第 012 篇，聚焦于 OpenClaw 独特的"文件即真相"记忆系统，深入解析其上下文压缩、向量搜索等核心机制。

---

摘要

OpenClaw 的记忆系统是其区别于传统聊天机器人的核心创新之一。与依赖向量数据库存储对话历史的方案不同，OpenClaw 采用"文件即真相"（File is Truth）的设计理念，将所有记忆以 Markdown 文件的形式存储在本地文件系统。本文深入剖析 OpenClaw 记忆系统的工作原理，包括 Memory.md 文件结构、上下文压缩机制（Compaction）、向量搜索功能以及会话管理策略。通过本文，读者将全面理解如何利用 OpenClaw 的记忆系统实现跨会话的持续对话和个性化智能助手体验。

一、"文件即真相"设计理念

1.1 传统方案的局限性

在探讨 OpenClaw 的记忆系统之前，有必要回顾一下传统 AI 助手处理记忆的方式。早期的大多数 AI 聊天机器人采用简单的会话隔离模式：每次对话都是独立的，关闭聊天窗口后，所有的对话历史就会被遗忘。如果想让 AI 记住之前的信息，需要使用向量数据库（如 Pinecone、Weaviate、Chroma 等）将对话历史转换为向量嵌入并存储在云端，然后在后续对话中通过相似度搜索检索相关历史。

这种方案虽然有效，但存在几个显著问题。首先是复杂性：向量数据库的部署、维护和扩展都需要专业技术知识，对普通用户不够友好。其次是隐私问题：将对话历史存储在第三方云服务可能引发数据安全担忧，尤其是在处理敏感信息时。第三是成本问题：向量存储和搜索需要额外的计算资源，增加了整体运营成本。第四是厂商锁定：一旦选择某一款向量数据库服务，迁移数据和切换供应商的成本很高。

1.2 OpenClaw 的革新方案

OpenClaw 提出了一个优雅而实用的解决方案：将所有记忆存储在本地文件系统中。用户创建的每个会话都会对应生成一个 Memory.md 文件，记录该会话的所有关键信息。这种设计有几个核心理念：第一，所有数据都存储在用户自己的设备上，隐私安全完全由用户自己掌控；第二，使用人类可读的 Markdown 格式存储，方便用户直接查看、编辑和导出；第三，无需额外的基础设施依赖，降低了使用门槛；第四，文件格式的通用性使得数据迁移极为简单。

"文件即真相"这一口号的含义是：文件系统是所有信息的唯一真实来源。与其依赖数据库查询或者 API 调用来获取历史信息，不如让用户直接读写文件系统中的 Markdown 文件。这种设计不仅简化了系统架构，还赋予了用户更大的控制权。用户可以随时打开 Memory.md 文件，删除不想要的记忆，修改错误的记录，或者添加特定的个人偏好设置，这些修改会立即生效并影响后续对话。

1.3 记忆系统的核心组件

OpenClaw 的记忆系统由几个核心组件构成。Memory.md 是存储会话记忆的核心文件，记录了用户信息、偏好设置、会话历史等关键数据。Context Manager 负责管理对话上下文的动态组装和压缩，确保在有限的模型上下文窗口内传递最相关的信息。Vector Search 模块（可选）提供基于嵌入向量的语义搜索能力，增强记忆检索的准确性。Message Store 负责持久化和管理消息历史，支持会话的恢复和继续。

这种模块化的设计使得各个组件可以独立演进和优化，同时保持整体的协调性。用户可以根据自己的需求选择性地启用或配置各个模块。例如，对于隐私要求极高的用户，可以只使用基础的 Memory.md 功能而不启用向量搜索；对于需要更智能记忆检索的高级用户，可以配置本地 embedding 模型来实现语义搜索。

二、Memory.md 文件结构详解

2.1 文件格式与存储位置

Memory.md 文件采用标准 Markdown 格式存储，每个 OpenClaw 会话对应一个独立的文件。在默认配置下，这些文件存储在用户数据目录的 memory 子目录中。文件的命名通常采用会话标识符（如 UUID 或用户自定义名称），方便用户识别和管理。

一个典型的 Memory.md 文件结构包含以下几个主要部分：文件头部包含会话元数据，如创建时间、最后更新时间、会话状态等；用户画像部分记录用户的背景信息、偏好设置、技能水平等；对话历史部分按时间顺序记录所有对话内容；工具调用记录部分保存 Agent 执行过的操作历史；总结摘要部分（如果启用了压缩功能）包含早期对话的浓缩版本。

2.2 用户画像与偏好设置

Memory.md 中最重要的一部分是用户画像（User Profile）。这部分信息由 OpenClaw 自动从对话中提取并持续更新，涵盖用户的基本信息、偏好设置、已知事实等多个维度。

用户画像的典型内容包括：基本信息如姓名、工作领域、所在时区等；技术背景如编程语言偏好、技术栈熟练程度等；沟通偏好如回复详细程度、是否偏好代码示例等；个人习惯如常用时间段、常用渠道等。这些信息会在每次对话中自动更新和丰富，使得 AI 助手能够越来越精准地理解用户，提供更加个性化的服务。

偏好设置部分还支持用户手动添加特定指令。例如，用户可以直接在 Memory.md 中添加"请始终使用中文回复"或"代码示例优先使用 TypeScript"等指令，OpenClaw 会将这些指令作为系统提示词的一部分，确保用户的明确需求得到满足。

2.3 对话历史的组织方式

Memory.md 中的对话历史采用分层结构组织。顶层按照时间顺序记录每轮对话的用户输入和 AI 输出，每条记录包含时间戳、消息内容、使用的模型、执行的工具等信息。对于包含工具调用的对话，系统会详细记录工具名称、输入参数、执行结果等完整信息。

这种结构化的历史记录有几个重要用途。首先，它使得上下文压缩成为可能——当对话长度超过模型限制时，系统可以识别出对话的关键节点，生成浓缩摘要。其次，它支持精确的历史检索——用户可以查找特定时间或特定主题的对话内容。第三，它为调试和问题排查提供了完整的执行轨迹。

三、上下文压缩机制详解

3.1 问题的起源

在上一篇文章介绍 Agent 循环时，我们提到每次 LLM 调用都会将完整的消息历史发送给模型。随着对话的持续进行，消息数组会不断增长，逐渐逼近模型的上下文窗口上限。当达到上限时，对话将无法继续。这就是所谓的"上下文耗尽"问题。

传统的解决方案是简单地截断早期对话，丢弃超出的部分。这种方式简单但粗糙，可能导致重要信息的丢失，尤其是对话早期提到的关键背景信息或用户偏好设置。OpenClaw 采用了更智能的解决方案：上下文压缩（Compaction）。

3.2 Compaction 工作原理

OpenClaw 的上下文压缩机制是一种智能的"记忆提炼"技术。当对话长度接近上下文窗口阈值时（默认设置为上下文上限的 80%），系统会触发压缩流程。压缩过程分为几个步骤：

第一步是消息选择。系统会分析整个对话历史，识别出每个消息的重要程度评分。评分算法会考虑多个因素：消息是否包含用户提供的关键信息（如姓名、偏好、事实等）、消息是否包含重要的决策或结论、消息是否包含后续对话依赖的上下文、消息的距离（越近的消息通常越重要）。基于这些因素，系统会选择需要保留的核心消息。

第二步是摘要生成。对于被标记为"可压缩"的早期消息，系统会调用 LLM 生成一段简洁的摘要。摘要不是简单的文本压缩，而是理解消息核心含义后的重新表达。例如，一段详细的代码调试过程可能被摘要为"用户解决了某模块的登录问题，使用了重新安装依赖的方法"。

第三步是上下文重组。压缩后的对话历史会重新组装为新的消息数组：保留核心的原始消息（作为精确参考），插入摘要消息（作为背景参考），最后是近期的完整消息。这种结构确保了最近对话的精确性，同时保留了早期对话的关键信息。

3.3 压缩效果的量化评估

OpenClaw 的压缩机制可以显著延长对话的有效长度。以 GPT-4o 为例，其上下文窗口为 128K tokens，假设每轮对话平均消耗 500 tokens（包含用户输入、模型输出和工具结果），不使用压缩的情况下大约可以维持 250 轮对话。启用压缩后，通过将早期对话浓缩为摘要，单个摘要可以压缩约 10-20 倍的信息量，使得有效对话轮数可以提升到 500 轮甚至更多。

更重要的是，压缩后的摘要仍然保留了对话的连贯性。经过合理压缩的对话历史，LLM 仍然能够理解之前讨论的上下文，不会出现"断片"现象。这使得用户可以与 OpenClaw 进行长达数周甚至数月的持续对话，而无需频繁开启新会话。

3.4 压缩配置的调整

OpenClaw 允许用户根据自己的需求调整压缩相关的参数。核心配置项包括：触发阈值（compressionThreshold），控制何时触发压缩流程，默认为上下文窗口的 80%；压缩比（compressionRatio），控制每个原始消息被压缩为摘要后的目标长度比例；保留策略（retentionPolicy），决定哪些类型的消息永远不被压缩（如用户明确声明的重要信息）。

在 auth-profiles.json 中的典型配置：

{
  "memory": {
    "compressionThreshold": 0.8,
    "compressionRatio": 10,
    "retentionPolicy": {
      "userFacts": "never",
      "preferences": "never",
      "toolResults": "keep_last_50"
    }
  }
}

四、向量搜索与语义检索

4.1 向量搜索的价值

虽然 Memory.md 文件系统提供了可靠的记忆存储和简单的文本检索能力，但在某些场景下，用户需要根据语义相似性而非精确关键词来查找历史记录。例如，用户可能记得"上次讨论过某个项目管理工具"，但忘记了具体是哪个工具，或者想找"关于 API 设计的讨论"而不是搜索精确的关键词。

向量搜索通过将文本转换为高维向量（嵌入），然后计算向量之间的相似度来解决这个问题。当用户提出一个查询时，系统会将查询也转换为向量，然后在向量空间中找出最相似的记忆片段。这种方式不依赖于关键词的精确匹配，而是理解语义层面的相似性。

4.2 本地 Embedding 模型

OpenClaw 支持使用本地部署的 embedding 模型来生成向量表示，这与依赖 OpenAI API（使用 text-embedding-ada-002 等模型）的方案形成对比。本地 embedding 的优势包括：完全离线可用，无需网络连接；数据完全不离开用户设备，隐私安全性更高；长期使用成本为零，无需支付 API 调用费用。

根据技术社区的反馈，本地 embedding 可以在多种硬件配置上运行。在现代 Mac 电脑上，可以使用 Apple Silicon 的 Neural Engine 加速推理；在 AMD 锐龙 AI Max 处理器上，可以高效运行 7B 参数的 embedding 模型；在普通 PC 上，可以选择更小的模型（如 MiniLM 系列）以平衡性能和速度。

4.3 向量搜索的配置与使用

启用 OpenClaw 的向量搜索功能需要在配置中指定 embedding 模型。配置示例：

{
  "memory": {
    "vectorSearch": {
      "enabled": true,
      "model": "bge-small-zh-v1.5",
      "embeddingDimension": 512,
      "indexPath": "./data/vector-index"
    }
  }
}

在实际使用中，向量搜索通常与关键词搜索结合使用。系统会同时执行两种搜索策略，然后合并结果并根据相关性排序。这种混合搜索方式既能处理精确匹配的查询，也能处理语义相似但表达方式不同的查询。

五、会话管理与持久化策略

5.1 会话的生命周期

OpenClaw 中的每个会话（Session）都有其完整的生命周期。新会话的创建可以由用户主动发起（通过命令行或渠道消息），也可以由系统根据配置自动创建（如定时任务触发的会话）。每个会话都有独立的状态，包括：活动状态（Active）、暂停状态（Paused）、已完成状态（Completed）。

当会话处于活动状态时，Memory.md 文件会实时更新，记录所有新的对话内容和系统观察。每条记录都包含精确的时间戳，方便后续检索和回溯。当会话暂停或完成时，Memory.md 进入只读状态，可以被归档或导出。

5.2 跨会话的记忆传递

OpenClaw 设计中有一个重要的概念：跨会话记忆传递。虽然每个会话有独立的 Memory.md 文件，但用户可以选择让新会话继承旧会话的记忆。这种设计支持两种模式：连续模式，新会话自动加载历史 Memory.md 的内容作为起始上下文；独立模式，每个会话完全独立，不继承任何历史记忆。

连续模式对于构建长期助手关系非常有用。例如，用户可以让 OpenClaw 记住自己的项目背景、技术偏好、工作习惯等信息，然后在后续会话中继续基于这些背景进行深入交流。随着使用时间的增长，AI 助手会变得越来越"了解"用户，提供更加精准和个性化的服务。

5.3 备份与导出功能

由于所有数据都存储在本地文件中，OpenClaw 的备份和导出操作变得极为简单。用户只需复制整个数据目录即可完成完整备份。导出的格式可以是 Markdown（保持 Memory.md 原格式）、JSON（便于程序处理）或纯文本。

这种设计还使得数据迁移变得非常简单。如果需要更换设备或在新机器上部署 OpenClaw，只需将旧设备的 memory 目录复制过去即可。OpenClaw 会自动识别并加载这些历史数据，无需额外的导入操作。

六、隐私与安全考量

6.1 数据存储的安全性

OpenClaw 的"本地优先"设计为数据安全提供了坚实基础。所有对话历史、用户偏好、工具调用记录都存储在用户自己的设备上，不依赖任何云服务。这意味着即使用户使用 OpenClaw 处理敏感信息（如公司内部资料、个人隐私数据等），这些数据也不会离开用户的控制范围。

对于企业用户，这种设计尤其重要。企业通常对数据存储有严格的合规要求，如 GDPR、CCPA 等数据保护法规。OpenClaw 的本地存储模式使得企业可以完全掌控数据存储位置，满足数据驻留要求，而无需担心第三方服务商的数据处理实践。

6.2 Memory.md 的访问控制

虽然 Memory.md 文件存储在本地文件系统，但用户仍然需要注意适当的访问控制。建议的实践包括：为 OpenClaw 使用专用用户账户运行，避免与其他应用共享文件系统权限；定期检查 Memory.md 文件的权限设置，确保只有授权账户可以读取；在多用户环境下，使用文件系统加密（如 Linux 的 eCryptfs、Windows 的 BitLocker）保护敏感数据。

6.3 清理与数据删除

用户可以随时手动清理或删除 Memory.md 中的特定内容。最简单的方式是直接编辑 Memory.md 文件，删除不需要保留的记录。系统会在下次对话时自动读取更新后的文件。用户也可以启用自动清理功能，设置某些类型的记忆在特定时间后自动过期。

对于希望完全重置记忆的用户，OpenClaw 提供了会话重置功能，可以清除单个会话的所有记忆，恢复到初始状态。这一操作不可撤销，因此在执行前系统会要求用户确认。

七、记忆系统的高级应用

7.1 构建个人知识库

利用 OpenClaw 的记忆系统，用户可以构建一个个人化的 AI 知识库。具体做法是：在 Memory.md 中预先录入需要 AI 了解的知识内容，如个人项目文档、技术笔记、产品需求等；利用向量搜索功能让 AI 能够根据语义检索这些知识；当用户提问涉及这些知识时，AI 会自动结合记忆中的相关内容给出更准确的回答。

这种应用场景特别适合需要 AI 辅助工作的专业人士。例如，软件开发者可以将项目的架构设计、编码规范、API 文档等信息录入 Memory.md，后续在讨论项目相关问题时，AI 就能基于这些背景知识提供更精准的建议。

7.2 多角色记忆隔离

对于需要在同一 OpenClaw 实例中服务多个用户的场景（如家庭共享或小型团队使用），可以使用多角色记忆隔离功能。每个用户可以拥有独立的 Memory.md 文件，系统会根据当前交互的用户自动切换到对应的记忆上下文。

这种设计的配置需要在 auth-profiles.json 中为每个用户定义独立的 profile，每个 profile 指向不同的 Memory.md 文件路径。系统会根据消息来源的渠道标识（如 Telegram 用户 ID、飞书用户 OpenID 等）自动选择对应的 profile 和记忆文件。

7.3 与外部知识库的集成

虽然 OpenClaw 默认使用本地文件系统存储记忆，但它也支持与外部知识库的集成。对于需要引用大量外部文档的场景（如企业知识库、学术论文库等），可以通过 Skills 机制接入外部知识检索系统，然后在对话中动态引用检索结果。

这种混合架构结合了本地记忆和外部知识的优势：本地记忆存储用户的个人偏好和会话特定信息，确保对话的连续性和个性化；外部知识库提供大规模的信息检索能力，满足复杂的信息查询需求。

八、总结

OpenClaw 的记忆系统是其区别于传统 AI 助手的核心创新之一。通过"文件即真相"的设计理念，OpenClaw 将所有记忆以人类可读的 Markdown 格式存储在本地文件系统，既保证了数据隐私和安全，又提供了极大的灵活性和可控制性。

本文详细介绍了 Memory.md 的文件结构、上下文压缩机制的工作原理、向量搜索功能的配置方法、会话管理的策略以及隐私安全方面的考量。掌握这些知识后，用户可以充分利用 OpenClaw 的记忆系统，构建具有持久记忆的个性化 AI 助手。

记忆系统是实现真正智能助手的关键技术。随着对话的持续积累，OpenClaw 会越来越了解用户，提供越来越精准的服务。这种"越用越聪明"的特性，正是 OpenClaw 作为下一代 AI 智能体平台的魅力所在。在后续的文章中，我们将继续探讨 OpenClaw 的更多高级特性，包括安全机制、云端部署、实战案例等内容。

---

上一篇：[第 011 篇] OpenClaw 多模型支持与接入配置——OpenAI、Claude、国产大模型全指南

下一篇：[第 013 篇] OpenClaw 安全机制深度解析——沙盒隔离、权限控制与安全最佳实践

---

参考资料

1. OpenClaw 官方文档 - 记忆系统
2. OpenClaw 官方文档 - 上下文压缩（Compaction）
3. OpenClaw GitHub - Memory 模块源码
4. How OpenClaw Works: Skills, Heartbeat, Memory, and Channels
5. OpenClaw 架构深度解析：从 Gateway 到 Skills 的完整数据流
6. OpenClaw Memory.md 文件格式详解 - 知乎
7. 一文彻底搞懂 OpenClaw 的架构设计与运行原理
8. OpenClaw Context Window Management 最佳实践
9. BGE Embedding 模型中文文档
10. OpenClaw 本地向量搜索配置指南 - CSDN
11. AI Agent 上下文管理综述 - 机器之心

---