记忆系统 (Memory System)

记忆

OpenClaw 的记忆是 Agent 工作区中的纯 Markdown 文件。文件是事实的来源；模型只“记住”写入磁盘的内容。

记忆搜索工具由活动的记忆插件提供（默认：memory-core）。使用 plugins.slots.memory = "none" 禁用记忆插件。

记忆文件 (Markdown)

默认的工作区布局使用两层记忆：

memory/YYYY-MM-DD.md
- 每日日志（仅追加）。
- 在会话开始时读取今天 + 昨天的内容。
MEMORY.md (可选)
- 精选的长期记忆。
- 仅在主私人会话中加载（绝不在群组上下文中加载）。

这些文件位于工作区下（agents.defaults.workspace，默认 ~/.openclaw/workspace）。有关完整布局，请参阅 Agent 工作区。

何时写入记忆

决策、偏好和持久事实进入 MEMORY.md。
日常笔记和运行上下文进入 memory/YYYY-MM-DD.md。
如果有人说“记住这个”，把它写下来（不要把它保存在 RAM 中）。
这个领域仍在发展中。提醒模型存储记忆会有所帮助；它会知道该怎么做。
如果你想让某件事留存下来，请让机器人把它写进 记忆中。

自动记忆刷新 (压缩前 ping)

当会话 接近自动压缩 时，OpenClaw 会触发一个 静默的、Agentic 轮次，提醒模型在上下文被压缩之前写入持久记忆。默认提示明确指出模型 可以回复，但通常 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."
        }
      }
    }
  }
}

详情：

软阈值 (Soft threshold)：当会话 token 估计值超过 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 密钥。OpenClaw 从 auth profiles, models.providers.*.apiKey, 或环境变量中解析密钥。Codex OAuth 仅涵盖 chat/completions，不满足记忆搜索的嵌入。对于 Gemini，使用 GEMINI_API_KEY 或 models.providers.google.apiKey。当使用自定义 OpenAI 兼容端点时，设置 memorySearch.remote.apiKey（和可选的 memorySearch.remote.headers）。

额外记忆路径

如果您想索引默认工作区布局之外的 Markdown 文件，请添加显式路径：

agents: {
  defaults: {
    memorySearch: {
      extraPaths: ["../team-docs", "/srv/shared-notes/overview.md"]
    }
  }
}

注意：

路径可以是绝对路径或相对于工作区的路径。
目录会被递归扫描以查找 .md 文件。
仅索引 Markdown 文件。
符号链接被忽略（文件或目录）。

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, 或代理），您可以使用带有 OpenAI 提供商的 remote 配置：

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" }
      }
    }
  }
}

如果您不想设置 API 密钥，请使用 memorySearch.provider = "local" 或设置 memorySearch.fallback = "none"。

回退 (Fallbacks)：

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 工作负载提供折扣定价，因此大型索引运行通常比同步发送相同请求便宜。
有关详细信息，请参阅 OpenAI Batch API 文档和定价：
- https://platform.openai.com/docs/api-reference/batch
- https://platform.openai.com/pricing

配置示例：

agents: {
  defaults: {
    memorySearch: {
      provider: "openai",
      model: "text-embedding-3-small",
      fallback: "openai",
      remote: {
        batch: { enabled: true, concurrency: 2 }
      },
      sync: { watch: true }
    }
  }
}

工具：

memory_search — 返回带有文件 + 行范围的片段。
memory_get — 按路径读取记忆文件内容。

本地模式：

设置 agents.defaults.memorySearch.provider = "local"。
提供 agents.defaults.memorySearch.local.modelPath（GGUF 或 hf: URI）。
可选：设置 agents.defaults.memorySearch.fallback = "none" 以避免远程回退。

记忆工具如何工作

memory_search 对来自 MEMORY.md + memory/**/*.md 的 Markdown 块（~400 token 目标，80 token 重叠）进行语义搜索。它返回片段文本（上限 ~700 字符）、文件路径、行范围、分数、提供商/模型，以及我们是否从本地回退到远程嵌入。不返回完整的文件有效负载。
memory_get 读取特定的记忆 Markdown 文件（相对于工作区），可选择从起始行读取 N 行。仅当在 memorySearch.extraPaths 中显式列出时，才允许 MEMORY.md / memory/ 之外的路径。
仅当 Agent 的 memorySearch.enabled 解析为 true 时，这两个工具才启用。

索引什么（以及何时）

文件类型：仅 Markdown（MEMORY.md, memory/**/*.md，加上 memorySearch.extraPaths 下的任何 .md 文件）。
索引存储：每个 Agent 的 SQLite 位于 ~/.openclaw/memory/<agentId>.sqlite（可通过 agents.defaults.memorySearch.store.path 配置，支持 {agentId} token）。
新鲜度：监视 MEMORY.md, memory/, 和 memorySearch.extraPaths 标记索引为脏（去抖动 1.5s）。同步安排在会话开始、搜索时或按间隔进行，并异步运行。会话脚本使用增量阈值触发后台同步。
重建索引触发器：索引存储嵌入 提供商/模型 + 端点指纹 + 分块参数。如果其中任何一个发生更改，OpenClaw 会自动重置并重新索引整个存储。

混合搜索 (BM25 + 向量)

启用后，OpenClaw 结合了：

向量相似度（语义匹配，措辞可以不同）
BM25 关键字相关性（精确 token，如 ID、环境变量、代码符号）

如果您的平台上无法使用全文搜索，OpenClaw 将回退到仅向量搜索。

为什么混合？

向量搜索擅长“这意味着同一件事”：

“Mac Studio gateway host” vs “the machine running the gateway”
“debounce file updates” vs “avoid indexing on every write”

但它在精确、高信号 token 方面可能较弱：

ID (a828e60, b3b9895a…)
代码符号 (memorySearch.query.hybrid)
错误字符串 (“sqlite-vec unavailable”)

BM25（全文）则相反：擅长精确 token，在释义方面较弱。混合搜索是务实的中间立场：使用两种检索信号，以便您在“自然语言”查询和“大海捞针”查询中都能获得良好的结果。

我们如何合并结果（当前设计）

实现草图：

从双方检索候选池：

向量：按余弦相似度排名前 maxResults * candidateMultiplier。
BM25：按 FTS5 BM25 排名（越低越好）排名前 maxResults * candidateMultiplier。

将 BM25 排名转换为 0..1 左右的分数：

textScore = 1 / (1 + max(0, bm25Rank))

按 chunk id 联合候选并计算加权分数：

finalScore = vectorWeight * vectorScore + textWeight * textScore

注意：

vectorWeight + textWeight 在配置解析中归一化为 1.0，因此权重表现为百分比。
如果嵌入不可用（或者提供商返回零向量），我们仍然运行 BM25 并返回关键字匹配。
如果无法创建 FTS5，我们保留仅向量搜索（无硬故障）。

这并非“IR 理论完美”，但它简单、快速，并且往往能提高实际笔记的召回率/精确度。如果我们以后想做得更花哨，通常的后续步骤是混合之前的倒数排名融合 (RRF) 或分数归一化（min/max 或 z-score）。

配置：

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 仍然仅限于记忆文件。
会话索引是按 Agent 隔离的（仅索引该 Agent 的会话日志）。
会话日志位于磁盘上（~/.openclaw/agents/<agentId>/sessions/*.jsonl）。任何具有文件系统访问权限的进程/用户都可以读取它们，因此请将磁盘访问视为信任边界。为了更严格的隔离，请在单独的操作系统用户或主机下运行 Agent。

增量阈值（显示的默认值）：

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；禁用时，搜索将回退到存储嵌入上的进程内余弦相似度。
如果 sqlite-vec 扩展丢失或加载失败，OpenClaw 会记录错误并继续使用 JS 回退（无向量表）。
extensionPath 覆盖捆绑的 sqlite-vec 路径（对于自定义构建或非标准安装位置很有用）。

本地嵌入自动下载

默认本地嵌入模型：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 默认值。