AI创想

标题: OpenClaw - 03 记忆系统完全指南 [打印本页]
作者: 米落枫    时间: 昨天 13:44
标题: OpenClaw - 03 记忆系统完全指南
作者：小小工匠
文章目录


(, 下载次数: 0)


记忆（Memory）

OpenClaw 的记忆是代理工作区中的纯 Markdown 文件。文件是唯一的事实来源；模型只"记住"写入磁盘的内容。
记忆搜索工具由活跃的记忆插件提供（默认：memory-core）。可通过 plugins.slots.memory = "none" 禁用记忆插件。
记忆文件（Markdown）

默认工作区布局使用两个记忆层：
这些文件位于工作区目录下（agents.defaults.workspace，默认 ~/.openclaw/workspace）。完整布局请参阅 Agent workspace。
何时写入记忆

自动记忆刷新（压缩前提醒）

当会话接近自动压缩时，OpenClaw 会触发一个静默的代理轮次，提醒模型在上下文被压缩之前写入持久记忆。默认提示词明确表示模型可以回复，但通常 NO_REPLY 是正确的响应，这样用户永远不会看到这个轮次。
通过 agents.defaults.compaction.memoryFlush 控制：
  1. {
  2.   agents: {
  3.     defaults: {
  4.       compaction: {
  5.         reserveTokensFloor: 20000,
  6.         memoryFlush: {
  7.           enabled: true,
  8.           softThresholdTokens: 4000,
  9.           systemPrompt: "Session nearing compaction. Store durable memories now.",
  10.           prompt: "Write any lasting notes to memory/YYYY-MM-DD.md; reply with NO_REPLY if nothing to store.",
  11.         },
  12.       },
  13.     },
  14.   },
  15. }
复制代码
详细说明：
完整的压缩生命周期请参阅 Session management + compaction。
向量记忆搜索

OpenClaw 可以在 MEMORY.md 和 memory/*.md 上构建小型向量索引，使语义查询即使在措辞不同时也能找到相关笔记。
默认设置：
远程嵌入需要嵌入提供商的 API 密钥。OpenClaw 从认证配置文件、models.providers.*.apiKey 或环境变量中解析密钥。Codex OAuth 仅覆盖 chat/completions，不满足记忆搜索的嵌入需求。对于 Gemini，使用 GEMINI_API_KEY 或 models.providers.google.apiKey。对于 Voyage，使用 VOYAGE_API_KEY 或 models.providers.voyage.apiKey。使用自定义 OpenAI 兼容端点时，设置 memorySearch.remote.apiKey（以及可选的 memorySearch.remote.headers）。
QMD 后端（实验性）

设置 memory.backend = "qmd" 可将内置 SQLite 索引器替换为 QMD：一个本地优先的搜索 sidecar，结合了 BM25 + 向量 + 重排序。Markdown 仍然是事实来源；OpenClaw 通过 shell 调用 QMD 进行检索。
前置条件
Sidecar 运行方式
配置项（memory.qmd.*）
引用与回退
额外记忆路径

如果你想索引默认工作区布局之外的 Markdown 文件，可添加显式路径：
  1. agents: {
  2.   defaults: {
  3.     memorySearch: {
  4.       extraPaths: ["../team-docs", "/srv/shared-notes/overview.md"]
  5.     }
  6.   }
  7. }
复制代码
说明：
Gemini 嵌入（原生）

将 provider 设置为 gemini 以直接使用 Gemini 嵌入 API：
  1. agents: {
  2.   defaults: {
  3.     memorySearch: {
  4.       provider: "gemini",
  5.       model: "gemini-embedding-001",
  6.       remote: {
  7.         apiKey: "YOUR_GEMINI_API_KEY"
  8.       }
  9.     }
  10.   }
  11. }
复制代码
说明：
如果你想使用自定义 OpenAI 兼容端点（OpenRouter、vLLM 或代理），可以使用 OpenAI provider 的 remote 配置：
  1. agents: {
  2.   defaults: {
  3.     memorySearch: {
  4.       provider: "openai",
  5.       model: "text-embedding-3-small",
  6.       remote: {
  7.         baseUrl: "https://api.example.com/v1/",
  8.         apiKey: "YOUR_OPENAI_COMPAT_API_KEY",
  9.         headers: { "X-Custom-Header": "value" }
  10.       }
  11.     }
  12.   }
  13. }
复制代码
如果不想设置 API 密钥，使用 memorySearch.provider = "local" 或设置 memorySearch.fallback = "none"。
回退机制：
批量索引（OpenAI + Gemini + Voyage）：
记忆工具的工作原理

索引内容（及时机）

混合搜索（BM25 + 向量）

启用后，OpenClaw 结合：
如果你的平台上全文搜索不可用，OpenClaw 回退到仅向量搜索。
为什么使用混合搜索？

向量搜索擅长"这意味着同一件事"：
但对于精确的高信号 token 可能较弱：
BM25（全文）则相反：擅长精确 token，弱于释义。混合搜索是务实的折中方案：同时使用两种检索信号，使"自然语言"查询和"大海捞针"查询都能获得良好结果。
结果合并方式（当前设计）

实现概要：
说明：
配置：
  1. agents: {
  2.   defaults: {
  3.     memorySearch: {
  4.       query: {
  5.         hybrid: {
  6.           enabled: true,
  7.           vectorWeight: 0.7,
  8.           textWeight: 0.3,
  9.           candidateMultiplier: 4
  10.         }
  11.       }
  12.     }
  13.   }
  14. }
复制代码
嵌入缓存

OpenClaw 可以在 SQLite 中缓存块嵌入，这样重新索引和频繁更新（尤其是会话记录）不会重新嵌入未更改的文本。
配置：
  1. agents: {
  2.   defaults: {
  3.     memorySearch: {
  4.       cache: {
  5.         enabled: true,
  6.         maxEntries: 50000
  7.       }
  8.     }
  9.   }
  10. }
复制代码
会话记忆搜索（实验性）

你可以选择索引会话记录并通过 memory_search 呈现它们。此功能受实验性标志控制。
  1. agents: {
  2.   defaults: {
  3.     memorySearch: {
  4.       experimental: { sessionMemory: true },
  5.       sources: ["memory", "sessions"]
  6.     }
  7.   }
  8. }
复制代码
说明：
增量阈值（显示默认值）：
  1. agents: {
  2.   defaults: {
  3.     memorySearch: {
  4.       sync: {
  5.         sessions: {
  6.           deltaBytes: 100000,   // ~100 KB
  7.           deltaMessages: 50     // JSONL 行数
  8.         }
  9.       }
  10.     }
  11.   }
  12. }
复制代码
SQLite 向量加速（sqlite-vec）

当 sqlite-vec 扩展可用时，OpenClaw 将嵌入存储在 SQLite 虚拟表（vec0）中，并在数据库中执行向量距离查询。这使搜索保持快速，无需将每个嵌入加载到 JS 中。
配置（可选）：
  1. agents: {
  2.   defaults: {
  3.     memorySearch: {
  4.       store: {
  5.         vector: {
  6.           enabled: true,
  7.           extensionPath: "/path/to/sqlite-vec"
  8.         }
  9.       }
  10.     }
  11.   }
  12. }
复制代码
说明：
本地嵌入自动下载

自定义 OpenAI 兼容端点示例
  1. agents: {
  2.   defaults: {
  3.     memorySearch: {
  4.       provider: "openai",
  5.       model: "text-embedding-3-small",
  6.       remote: {
  7.         baseUrl: "https://api.example.com/v1/",
  8.         apiKey: "YOUR_REMOTE_API_KEY",
  9.         headers: {
  10.           "X-Organization": "org-id",
  11.           "X-Project": "project-id"
  12.         }
  13.       }
  14.     }
  15.   }
  16. }
复制代码
说明：
(, 下载次数: 0)



原文地址：https://blog.csdn.net/yangshangwei/article/details/158432933



欢迎光临 AI创想 (https://llms-ai.com/) Powered by Discuz! X3.4