OpenCLaw记忆功能调用方法与使用指南

在开发智能体应用时，如何让AI持久记住关键信息并在需要时精准调取，是提升用户体验的核心挑战。OpenClaw采用了一套清晰的设计哲学：将记忆持久化存储在磁盘的Markdown文件中，并以此作为唯一的事实来源。这一方案看似简单，实则通过一套精巧的机制，确保了记忆的可靠性、可检索性与可解释性。

记忆文件结构：以Markdown为基石

OpenClaw的记忆系统完全建立在工作空间内的纯Markdown文件之上。这意味着所有记忆都以人类可读、可编辑的文本形式存在，而非难以解读的黑盒数据库。

• 每日日志：memory/YYYY-MM-DD.md文件用于记录日常笔记和运行上下文。它采用追加写入模式，每次会话启动时会自动加载当天及前一天的日志内容，为AI模型提供最近的背景信息。
• 长期记忆：MEMORY.md文件则用于存储经过筛选的重要长期记忆，例如核心决策、用户偏好或必须持久化的事实。值得注意的是，这份长期记忆仅在主要的私人会话中加载，群组对话的上下文不会包含它，这有助于保护隐私并保持对话的专注性。
• 文件位置：所有记忆文件均位于智能体的工作空间内（由agents.defaults.workspace配置，默认为~/.openclaw/workspace）。

关键在于，模型只“记住”那些被明确写入这些磁盘文件的内容。如果信息仅停留在对话的短期上下文中，一旦会话因长度限制被压缩或清空，信息就会永久丢失。

记忆的写入时机与自动化机制

那么，信息何时会被写入记忆文件呢？主要有两种触发场景。

• 主动写入：当用户明确指示“记住这个”，或者开发者希望某个信息被长期保留时，应直接指示模型将其写入MEMORY.md（长期事实）或当日的日志文件（日常笔记）。切勿仅满足于模型在对话中回复“知道了”。
• 自动刷新：这是OpenClaw一项贴心的自动化设计。当一次会话的长度接近系统设定的自动压缩阈值时，系统会触发一次静默的智能体回合，专门提醒模型：“会话即将被压缩，请立即将需要持久化的记忆写入文件。”此过程对用户透明，旨在避免因上下文窗口限制而导致重要信息在压缩前被遗忘。当然，如果工作空间被设置为只读（如沙箱环境），此自动刷新功能会被跳过。

智能检索：向量搜索与混合策略

记忆存储之后，如何快速精准地找到？OpenClaw默认会为MEMORY.md和所有memory/**/*.md文件建立向量索引，支持强大的语义搜索。这意味着即使查询词与原文表述不同，系统也能理解意图并找到相关内容。

• 提供商自动选择：系统会智能选择可用的嵌入模型提供商，优先级依次为：配置了本地模型路径 > OpenAI > Gemini > Voyage。这为不同网络环境和性能需求的用户提供了灵活性。
• 混合搜索策略：为了兼顾搜索的准确性和召回率，OpenClaw采用了混合搜索策略。它结合了向量相似度（用于理解语义）和BM25关键词匹配（用于精确查找如ID、代码符号等）。默认权重为0.7（向量）和0.3（关键词），这一组合能有效应对“自然语言模糊查询”和“精确信息检索”两种典型场景。
• 索引管理：索引以每个智能体为单位，存储在SQLite数据库中（~/.openclaw/memory/.sqlite）。系统会持续监视记忆文件的变更，并在后台异步同步索引。如果嵌入模型、分块参数等核心配置发生变化，索引会自动触发全量重建，确保搜索结果的准确性。

系统提供了两个核心工具函数：memory_search用于执行搜索并返回带来源的文本片段；memory_get则用于按文件路径直接读取记忆内容。

通过命令行进行高效管理

OpenClaw提供了便捷的命令行工具来管理整个记忆系统：

• openclaw memory status：查看当前记忆索引的状态。添加--deep参数可以深度探测向量和嵌入模型的可用性；添加--index参数可以在索引被标记为“脏”时立即触发重建。
• openclaw memory index：手动触发索引重建。--verbose参数可以输出详细的处理日志。
• openclaw memory search “查询词”：直接通过命令行执行语义搜索，快速验证检索效果。
• 所有命令都支持--agent 参数，以限定仅对某个特定智能体进行操作，便于多智能体环境下的管理。

配置要点与实验性功能

记忆搜索的相关配置集中在agents.defaults.memorySearch下，您可以在此设置提供商、模型、回退策略、额外的索引路径、混合搜索的权重以及缓存行为等高级参数。

此外，还有一些值得关注的实验性功能：

• 会话记忆搜索：开启后，搜索范围可以扩展到历史会话记录，这需要启用experimental.sessionMemory并配置相应的数据来源。
• 可选后端：除了内置的SQLite方案，还可以选择QMD作为后端。QMD是一个本地优先的搜索侧车服务，集成了BM25、向量检索和重排序能力，能提供更强大的检索效果，但需要单独安装和配置。

常见问题与核心理念

最后，深入理解以下几个关键点，能帮助您更好地使用和排查记忆系统：

• 持久化与上下文限制：记忆文件一旦写入磁盘，就会永久保存（直到您手动删除）。但这并不意味着模型在单次会话中能记住所有事。会话上下文仍然受模型自身窗口大小的限制，因此才需要依赖记忆搜索工具，在需要时将相关的记忆片段动态“拉回”当前上下文。
• 如何确保不忘：如果发现模型频繁“忘记”关键信息，最有效的解决方法是明确要求它将信息写入MEMORY.md或当日的日志文件。同时，请确认Gateway服务在每次运行时都指向同一个工作区路径，以保证记忆文件的连续性。
• 功能可关闭性：整个记忆功能可以通过配置plugins.slots.memory = “none”来完全禁用，以满足特定场景下的需求。

总而言之，OpenClaw的记忆系统通过“Markdown文件作为单一事实来源”这一简洁而强大的设计，配合自动化的写入提醒和高效的语义检索能力，在AI的“记忆力”、系统的可控性以及结果的可解释性之间，找到了一个优雅的平衡点。