记忆
OpenClaw 内存如何工作（工作区文件 + 自动内存刷新）
OpenClaw 内存是代理工作区中的纯 Markdown。这些文件是
真理的来源；该模型仅"记住"写入磁盘的内容。
内存搜索工具由活动内存插件提供（默认：
''memory-core'')。使用 ''plugins.slots.memory = "none"'' 禁用内存插件。
内存文件（Markdown）
默认工作区布局使用两个内存层：
- ''memory/YYYY-MM-DD.md''
- 每日日志（仅附加）。
- 今天+昨天在课程开始时阅读。
- ''MEMORY.md''（可选）
- 精心策划的长期记忆。
- 仅在主私人会话中加载（绝不在组上下文中加载）。
这些文件位于工作区下（''agents.defaults.workspace''，默认
何时写入内存
- 决定、偏好和持久事实交给''MEMORY.md''。
- 日常笔记和运行环境请参见 ''memory/YYYY-MM-DD.md''。
- 如果有人说"记住这一点"，请将其写下来（不要将其保存在 RAM 中）。
- 这个领域仍在不断发展。有助于提醒模型储存记忆；它会知道该怎么做。
- 如果您想要保留某些内容，请机器人将其写入到内存中。
自动内存刷新（预压缩 ping）
当会话接近自动压缩时，OpenClaw 会触发**静默，
代理转向，提醒模型在**写入持久内存**
before the'' context is compacted. The default prompt explicitly states the model _may reply_,
但通常 ''NO_REPLY'' 是正确的响应，因此用户永远不会看到这个回合。
这是由 ''agents.defaults.compaction.memoryFlush'' 控制的：
{
agents: {
defaults: {
compaction: {
reserveTokensFloor: 20000,
memoryFlush: {
enabled: true,
softThresholdTokens: 4000,
systemPrompt: "Session nearing compaction. Store durable memories now.",
prompt: "Write any lasting notes to memory/YYYY-MM-DD.md; reply with NO_REPLY if nothing to store.",
},
},
},
},
}详情：
- 软阈值：当会话令牌估计值超过时刷新触发
''contextWindow - reserveTokensFloor - softThresholdTokens''。
- 默认情况下''静默''：提示包括 ''NO_REPLY''，因此不会传送任何内容。
- 两个提示：用户提示加上系统提示附加提醒。
- ''每个压实周期一次冲洗''（在 ''sessions.json'' 中跟踪）。
- 工作区必须可写：如果会话在沙盒中运行
''workspaceAccess: "ro"'' 或 ''"none"''，跳过刷新。
有关完整的压缩生命周期，请参阅
''会话管理+压缩''。
向量内存搜索
OpenClaw 可以在 ''MEMORY.md'' 和 ''memory/*.md'' 上构建一个小向量索引（加上
您选择加入的任何额外目录或文件），以便语义查询可以找到相关的
即使措辞不同，也要注明。
默认值：
- 默认启用。
- 监视内存文件的变化（去抖）。
- 默认情况下使用远程嵌入。如果未设置 ''memorySearch.provider''，OpenClaw 会自动选择：
1. ''local''（如果配置了 ''memorySearch.local.modelPath'' 并且该文件存在）。
2. ''openai'' 如果可以解析 OpenAI 密钥。
3. ''gemini'' 如果可以解析 Gemini 密钥。
4. 否则，在配置之前，内存搜索将保持禁用状态。
- 本地模式使用node-llama-cpp，可能需要''pnpm approve-builds''。
- 使用 sqlite-vec（如果可用）来加速 SQLite 内的向量搜索。
远程嵌入 需要 嵌入提供程序的 API 密钥。开爪
解析来自身份验证配置文件、''models.providers.*.apiKey'' 或环境的密钥
#
附加内存路径
如果要在默认工作区布局之外对 Markdown 文件建立索引，请添加
agents: {
defaults: {
memorySearch: {
extraPaths: ["../team-docs", "/srv/shared-notes/overview.md"]
}
}
}显式路径：
注意事项：
- 路径可以是绝对路径或相对于工作空间的路径。
- 递归扫描目录中的 ''.md'' 文件。
#
Gemini 嵌入（原生）
将提供程序设置为 ''gemini'' 以直接使用 Gemini 嵌入 API：
agents: {
defaults: {
memorySearch: {
provider: "gemini",
model: "gemini-embedding-001",
remote: {
apiKey: "YOUR_GEMINI_API_KEY"
}
}
}
}注意事项：
- ''remote.baseUrl'' 是可选的（默认为 Gemini API 基本 URL）。
- ''remote.headers'' 允许您根据需要添加额外的标头。
- 默认型号：''gemini-embedding-001''。
如果您想使用自定义 OpenAI 兼容端点（OpenRouter、vLLM 或代理），
agents: {
defaults: {
memorySearch: {
provider: "openai",
model: "text-embedding-3-small",
remote: {
baseUrl: "https://api.example.com/v1/",
apiKey: "YOUR_OPENAI_COMPAT_API_KEY",
headers: { "X-Custom-Header": "value" }
}
}
}
}您可以将 ''remote'' 配置与 OpenAI 提供程序一起使用：
如果您不想设置 API 密钥，请使用 ''memorySearch.provider = "local"'' 或设置
''memorySearch.fallback = "none"''。
后备方案：
- ''memorySearch.fallback'' 可以是 ''openai''、''gemini''、''local'' 或 ''none''。
- 仅当主嵌入提供程序失败时才使用后备提供程序。
批量索引（OpenAI + Gemini）：
- 默认情况下启用 OpenAI 和 Gemini 嵌入。将 ''agents.defaults.memorySearch.remote.batch.enabled = false'' 设置为禁用。
- 默认行为等待批处理完成；如果需要，调整 ''remote.batch.wait''、''remote.batch.pollIntervalMs'' 和 ''remote.batch.timeoutMinutes''。
- 设置 ''remote.batch.concurrency'' 来控制我们并行提交的批处理作业数量（默认值：2）。
- 批处理模式适用于 ''memorySearch.provider = "openai"'' 或 ''"gemini"'' 并使用相应的 API 密钥。
- Gemini 批处理作业使用异步嵌入批处理端点，并且需要 Gemini Batch API 可用性。
为什么 OpenAI 批处理速度快且便宜：
- 对于大型回填，OpenAI 通常是我们支持的最快选项，因为我们可以在单个批处理作业中提交许多嵌入请求，并让 OpenAI 异步处理它们。
- OpenAI 为 Batch API 工作负载提供折扣定价，因此大型索引运行通常比同步发送相同请求更便宜。
记忆工具如何工作
- ''memory_search'' 从 ''MEMORY.md'' + ''memory/**/*.md'' 语义上搜索 Markdown 块（约 400 个标记目标，80 个标记重叠）。它返回片段文本（上限为 700 个字符）、文件路径、行范围、分数、提供者/模型，以及我们是否从本地 → 远程嵌入中退回。不返回完整的文件负载。
- ''memory_get'' 读取特定的内存 Markdown 文件（相对于工作空间），可选择从起始行开始读取 N 行。仅当在 ''memorySearch.extraPaths'' 中明确列出时，才允许使用 ''memorySearch.extraPaths'' / ''memorySearch.extraPaths'' 之外的路径。
- 仅当代理的 ''memorySearch.enabled'' 解析为 true 时，才会启用这两个工具。
#
什么被索引（以及何时）
- 文件类型：仅限 Markdown（''MEMORY.md''、''memory/**/*.md''，以及 ''memorySearch.extraPaths'' 下的任何 ''memorySearch.extraPaths'' 文件）。
- Index storage: Per-agent SQLite at ''~/.openclaw/memory/<agentId>.sqlite'' (configurable via ''agents.defaults.memorySearch.store.path'', supports ''{agentId}'' token).
- 新鲜度：''MEMORY.md''、''memory/'' 和 ''memorySearch.extraPaths'' 上的观察者将索引标记为脏（去抖 1.5 秒）。同步计划在会话启动时、搜索时或按一定时间间隔进行，并异步运行。会话记录使用增量阈值来触发后台同步。
- 重新索引触发器：索引存储嵌入提供者/模型+端点指纹+分块参数。如果其中任何一个发生变化，OpenClaw 会自动重置整个存储并重新索引。
#
混合搜索（BM25 + 矢量）
启用后，OpenClaw 结合：
- 矢量相似性（语义匹配，措辞可能不同）
- BM25 关键字相关性（确切的标记，如 ID、环境变量、代码符号）
如果您的平台上不支持全文搜索，OpenClaw 会退回到纯矢量搜索。
##
为什么是混合动力？
矢量搜索擅长"这意味着同样的事情"：
- "Mac Studio 网关主机"与"运行网关的计算机"
- "去抖文件更新"与"避免每次写入时建立索引"
但它在精确、高信号标记方面可能很弱：
- ID（''a828e60''、''b3b9895a…''）
- 代码符号 (''memorySearch.query.hybrid'')
- 错误字符串（"sqlite-vec 不可用"）
BM25（全文）则相反：精确标记较强，释义较弱。
混合搜索是务实的中间立场：使用两种检索信号，这样你就可以得到
对于"自然语言"查询和"大海捞针"查询都有很好的结果。
##
我们如何合并结果（当前设计）
实现草图：
1. 从双方检索候选池：
- ''矢量''：按余弦相似度计算顶部 ''maxResults * candidateMultiplier''。
- ''BM25''：按 FTS5 BM25 排名排名前 ''maxResults * candidateMultiplier''（越低越好）。
2. 将 BM25 排名转换为 0..1 左右的分数：
- ''textScore = 1 / (1 + max(0, bm25Rank))''
3. 按块 id 联合候选并计算加权分数：
- ''finalScore = vectorWeight * vectorScore + textWeight * textScore''
注意事项：
- ''vectorWeight'' + ''textWeight'' 在配置分辨率中标准化为 1.0，因此权重表现为百分比。
agents: {
defaults: {
memorySearch: {
query: {
hybrid: {
enabled: true,
vectorWeight: 0.7,
textWeight: 0.3,
candidateMultiplier: 4
}
}
}
}
}#
嵌入缓存
OpenClaw 可以在 SQLite 中缓存块嵌入，因此重新索引和频繁更新（尤其是会话记录）不会重新嵌入未更改的文本。
配置：
agents: {
defaults: {
memorySearch: {
cache: {
enabled: true,
maxEntries: 50000
}
}
}
}#
会话内存搜索（实验性）
您可以选择索引 ''会话记录'' 并通过 ''memory_search'' 显示它们。
这是在实验标志后面进行的。
agents: {
defaults: {
memorySearch: {
experimental: { sessionMemory: true },
sources: ["memory", "sessions"]
}
}
}注意事项：
- 会话索引是选择加入（默认情况下关闭）。
- 一旦会话更新超过增量阈值（尽力而为），会话更新就会被反跳并异步索引。
- ''memory_search'' 从不阻塞索引；在后台同步完成之前，结果可能会稍微陈旧。
- 结果仍然仅包含片段； ''memory_get'' 仍然仅限于内存文件。
- 每个代理的会话索引是隔离的（仅对该代理的会话日志进行索引）。
- Session logs are stored on disk (''~/.openclaw/agents/<agentId>/sessions/*.jsonl''). Any process/user with filesystem access can read them, so treat disk access as a trust boundary. For stricter isolation, run agents under separate OS users or hosts.
agents: {
defaults: {
memorySearch: {
sync: {
sessions: {
deltaBytes: 100000, // ~100 KB
deltaMessages: 50 // JSONL lines
}
}
}
}
}#
SQLite向量加速（sqlite-vec）
当 sqlite-vec 扩展可用时，OpenClaw 将嵌入存储在
SQLite 虚拟表 (''vec0'') 并在中执行向量距离查询
数据库。这可以保持快速搜索，而无需将每个嵌入加载到 JS 中。
agents: {
defaults: {
memorySearch: {
store: {
vector: {
enabled: true,
extensionPath: "/path/to/sqlite-vec"
}
}
}
}
}配置（可选）：
注意事项：
- ''enabled'' 默认为 true；禁用后，搜索将退回到进程中
存储嵌入的余弦相似度。
#
本地嵌入自动下载
- 默认本地嵌入模型：''hf:ggml-org/embeddinggemma-300M-GGUF/embeddinggemma-300M-Q8_0.gguf'' (~0.6 GB)。
- 当 ''memorySearch.provider = "local"'' 时，''node-llama-cpp'' 解析 ''modelPath''；如果 GGUF 丢失，它会''自动下载''到缓存（或 ''local.modelCacheDir'' 如果设置），然后加载它。重试时下载会恢复。
- 本机构建要求：运行 ''pnpm approve-builds''，选择 ''node-llama-cpp''，然后选择 ''pnpm rebuild node-llama-cpp''。
- 后备：如果本地设置失败且 ''memorySearch.fallback = "openai"''，我们会自动切换到远程嵌入（''openai/text-embedding-3-small'' 除非被覆盖）并记录原因。
#
自定义 OpenAI 兼容端点示例
agents: {
defaults: {
memorySearch: {
provider: "openai",
model: "text-embedding-3-small",
remote: {
baseUrl: "https://api.example.com/v1/",
apiKey: "YOUR_REMOTE_API_KEY",
headers: {
"X-Organization": "org-id",
"X-Project": "project-id"
}
}
}
}
}注意事项：
- ''remote.*'' 优先于 ''models.providers.openai.*''。
- ''remote.headers'' 与 OpenAI 标头合并；远程在关键冲突上获胜。省略 ''remote.headers'' 以使用 OpenAI 默认值。