openclaw-docs-zh

记忆系统

本文档描述 OpenClaw 的记忆系统，它使用”Agent 工作区中的纯 Markdown 文件”作为基础。文件本身就是真实来源——模型只保留持久化到磁盘的内容。

记忆文件结构

双层系统：

1. 每日日志（memory/YYYY-MM-DD.md）- 仅追加文件，在会话开始时读取（今天 + 昨天）
2. 长期记忆（MEMORY.md）- 精心整理的持久存储，仅在私人会话中加载

文件位于工作区目录（默认：~/.openclaw/workspace）。

写入指南

• 持久性事实和偏好 → MEMORY.md
• 运行上下文和每日笔记 → 日期文件
• 当用户说”记住这个”时，立即持久化
• 明确要求机器人写入可确保持久化

自动记忆刷新

在上下文压缩之前，会触发一个静默的 Agent 轮次，提示模型保存重要信息。关键设置包括 memoryFlush 配置块中的 softThresholdTokens、systemPrompt 和 prompt 字段。如果工作区访问是只读的，则跳过刷新。

向量记忆搜索

在记忆文件上构建语义索引，无论措辞如何都能找到相关笔记。

提供者优先级： local（如果已配置）→ OpenAI → Gemini → 禁用

支持的提供者： OpenAI、Gemini（原生）、local（node-llama-cpp）或自定义 OpenAI 兼容端点。

提供的工具：

• memory_search - 返回带有文件路径和行范围的片段
• memory_get - 读取特定记忆文件内容

混合搜索（BM25 + 向量）

结合语义匹配和关键词相关性。向量搜索擅长处理释义；BM25 擅长精确标记，如 ID 和代码符号。结果使用可配置的权重合并（默认：70% 向量，30% 文本）。

附加功能

• 额外路径： 通过 extraPaths 索引默认位置之外的 Markdown
• 批量索引： OpenAI/Gemini 默认启用异步处理
• 嵌入缓存： 基于 SQLite 的缓存防止重新嵌入未更改的块
• 会话记忆搜索： 用于索引对话记录的实验性可选功能
• sqlite-vec 加速： 使用虚拟表进行快速数据库内向量查询
• 本地嵌入自动下载： 默认模型（约 0.6 GB）在需要时自动下载

索引管理

• 存储：每个 Agent 的 SQLite 位于 ~/.openclaw/memory/<agentId>.sqlite
• 文件监视带有 1.5 秒防抖，标记索引为脏
• 当提供者、模型或分块参数更改时自动重新索引