Memory

OpenClaw memory 是 agent 工作空间中的纯 Markdown。文件是事实来源；模型只"记住"写入磁盘的内容。

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

Memory 文件（Markdown）

默认工作空间布局使用两个 memory 层：

memory/YYYY-MM-DD.md
- 每日日志（仅追加）。
- 会话开始时读取今天 + 昨天。
MEMORY.md（可选）
- 策划的长期 memory。
- 仅在主私密会话中加载（从不在群组上下文中）。

这些文件位于工作空间下（agents.defaults.workspace，默认 ~/.openclaw/workspace）。参见 Agent workspace 了解完整布局。

Memory 工具

OpenClaw 为这些 Markdown 文件公开两个 agent 面向的工具：

memory_search — 对索引片段的语义回忆。
memory_get — 针对特定 Markdown 文件/行范围的定向读取。

memory_get 现在在文件不存在时优雅降级（例如，第一次写入之前的今日日志）。内置管理器和 QMD 后端都返回 { text: "", path } 而不是抛出 ENOENT，因此 agent 可以处理"尚未记录任何内容"并继续其工作流，而无需在 try/catch 逻辑中包装工具调用。

何时写入 memory

决策、偏好和持久事实写入 MEMORY.md。
日常笔记和运行上下文写入 memory/YYYY-MM-DD.md。
如果有人说"记住这个"，写下来（不要保存在 RAM 中）。
这个领域仍在发展中。提醒模型存储 memory 是有帮助的；它会知道该怎么做。
如果你想让某些东西持久，要求 bot 将其写入 memory。

自动 memory flush（预压缩 ping）

当会话接近自动压缩时，OpenClaw 触发静默 agentic 轮次，提醒模型在上下文被压缩之前写入持久 memory。默认提示明确说明模型_可以回复_，但通常 NO_REPLY 是正确的响应，因此用户永远不会看到此轮次。

这由 agents.defaults.compaction.memoryFlush 控制：

{
  agents: {
    defaults: {
      compaction: {
        reserveTokensFloor: 20000,
        memoryFlush: {
          enabled: true,
          softThresholdTokens: 4000,
          systemPrompt: "会话接近压缩。现在存储持久 memory。",
          prompt: "将任何持久笔记写入 memory/YYYY-MM-DD.md；如果没有要存储的内容，回复 NO_REPLY。",
        },
      },
    },
  },
}

详情：

软阈值：当会话 token 估计超过 contextWindow - reserveTokensFloor - softThresholdTokens 时触发 flush。
默认静默：提示包括 NO_REPLY，因此不会传递任何内容。
两个提示：用户提示加上系统提示附加提醒。
每个压缩周期一次 flush（在 sessions.json 中跟踪）。
工作空间必须可写：如果会话在沙箱中运行，带有 workspaceAccess: "ro" 或 "none"，则跳过 flush。

有关完整的压缩生命周期，参见 Session management + compaction。

向量 memory 搜索

OpenClaw 可以在 MEMORY.md 和 memory/*.md 上构建小型向量索引，因此语义查询可以在措辞不同时找到相关笔记。

默认：

默认启用。
监视 memory 文件的变化（去抖）。
在 agents.defaults.memorySearch 下配置 memory 搜索（不是顶层 memorySearch）。
默认使用远程嵌入。如果未设置 memorySearch.provider，OpenClaw 自动选择：
1. 如果配置了 memorySearch.local.modelPath 且文件存在，则为 local。
2. 如果可以解析 OpenAI 密钥，则为 openai。
3. 如果可以解析 Gemini 密钥，则为 gemini。
4. 如果可以解析 Voyage 密钥，则为 voyage。
5. 如果可以解析 Mistral 密钥，则为 mistral。
6. 否则 memory 搜索保持禁用直到配置。
本地模式使用 node-llama-cpp，可能需要 pnpm approve-builds。
使用 sqlite-vec（可用时）在 SQLite 内加速向量搜索。
memorySearch.provider = "ollama" 也支持本地/自托管 Ollama 嵌入（/api/embeddings），但它不是自动选择的。

远程嵌入需要嵌入提供者的 API 密钥。OpenClaw 从认证配置文件、models.providers.*.apiKey 或环境变量解析密钥。Codex OAuth 仅涵盖 chat/completions，不满足 memory 搜索的嵌入。对于 Gemini，使用 GEMINI_API_KEY 或 models.providers.google.apiKey。对于 Voyage，使用 VOYAGE_API_KEY 或 models.providers.voyage.apiKey。对于 Mistral，使用 MISTRAL_API_KEY 或 models.providers.mistral.apiKey。Ollama 通常不需要真正的 API 密钥（当本地策略需要时，像 OLLAMA_API_KEY=ollama-local 这样的占位符就足够了）。使用自定义 OpenAI 兼容端点时，设置 memorySearch.remote.apiKey（和可选的 memorySearch.remote.headers）。

QMD 后端（实验性）

设置 memory.backend = "qmd" 将内置 SQLite 索引器替换为 QMD：一个本地优先的搜索边车，结合 BM25 + 向量 + 重排序。Markdown 保持事实来源；OpenClaw 将检索外包给 QMD。要点：

前提条件

默认禁用。按配置选择（memory.backend = "qmd"）。
单独安装 QMD CLI（bun install -g https://github.com/tobi/qmd 或获取发布版）并确保 qmd 二进制文件在 gateway 的 PATH 上。
QMD 需要允许扩展的 SQLite 构建（macOS 上 brew install sqlite）。
QMD 通过 Bun + node-llama-cpp 完全本地运行，并在首次使用时从 HuggingFace 自动下载 GGUF 模型（不需要单独的 Ollama 守护进程）。
Gateway 在 ~/.openclaw/agents/<agentId>/qmd/ 下的自包含 XDG 家中运行 QMD，通过设置 XDG_CONFIG_HOME 和 XDG_CACHE_HOME。
OS 支持：一旦安装了 Bun + SQLite，macOS 和 Linux 可以直接使用。Windows 最好通过 WSL2 支持。

边车如何运行

Gateway 在 ~/.openclaw/agents/<agentId>/qmd/（配置 + 缓存 + sqlite DB）下写入自包含的 QMD 家。
集合通过 qmd collection add 从 memory.qmd.paths（加上默认工作空间 memory 文件）创建，然后在启动时和可配置间隔（memory.qmd.update.interval，默认 5 分钟）运行 qmd update + qmd embed。
Gateway 现在在启动时初始化 QMD 管理器，因此定期更新计时器即使在第一次 memory_search 调用之前也武装。
启动刷新现在默认在后台运行，因此聊天启动不会被阻塞；设置 memory.qmd.update.waitForBootSync = true 以保持之前的阻塞行为。
搜索通过 memory.qmd.searchMode 运行（默认 qmd search --json；也支持 vsearch 和 query）。如果所选模式在你的 QMD 构建上拒绝标志，OpenClaw 使用 qmd query 重试。如果 QMD 失败或二进制文件缺失，OpenClaw 自动回退到内置 SQLite 管理器，因此 memory 工具继续工作。
OpenClaw 今天不公开 QMD 嵌入批量大小调整；批量行为由 QMD 本身控制。
第一次搜索可能很慢：QMD 可能在第一次 qmd query 运行时下载本地 GGUF 模型（重排序器/查询扩展）。
- OpenClaw 在运行 QMD 时自动设置 XDG_CONFIG_HOME/XDG_CACHE_HOME。
- 如果你想手动预下载模型（并预热 OpenClaw 使用的相同索引），使用 agent 的 XDG 目录运行一次性查询。
  
  OpenClaw 的 QMD 状态位于你的状态目录下（默认 ~/.openclaw）。你可以通过导出 OpenClaw 使用的相同 XDG 变量将 qmd 指向完全相同的索引：
```
# 选择 OpenClaw 使用的相同状态目录
STATE_DIR="${OPENCLAW_STATE_DIR:-$HOME/.openclaw}"

export XDG_CONFIG_HOME="$STATE_DIR/agents/main/qmd/xdg-config"
export XDG_CACHE_HOME="$STATE_DIR/agents/main/qmd/xdg-cache"

# （可选）强制索引刷新 + 嵌入
qmd update
qmd embed

# 预热/触发首次模型下载
qmd query "test" -c memory-root --json >/dev/null 2>&1
```

配置表面（memory.qmd.*）

command（默认 qmd）：覆盖可执行文件路径。
searchMode（默认 search）：选择哪个 QMD 命令支持 memory_search（search、vsearch、query）。
includeDefaultMemory（默认 true）：自动索引 MEMORY.md + memory/**/*.md。
paths[]：添加额外目录/文件（path，可选 pattern，可选稳定 name）。
sessions：选择加入会话 JSONL 索引（enabled、retentionDays、exportDir）。
update：控制刷新节奏和维护执行：（interval、debounceMs、onBoot、waitForBootSync、embedInterval、commandTimeoutMs、updateTimeoutMs、embedTimeoutMs）。
limits：限制回忆负载（maxResults、maxSnippetChars、maxInjectedChars、timeoutMs）。
scope：与 session.sendPolicy 相同的 schema。默认是 DM 专用（deny 所有，allow 直接聊天）；放宽它以在群组/频道中显示 QMD 命中。
- match.keyPrefix 匹配规范化的会话键（小写，带任何前导 agent:<id>: 剥离）。例如：discord:channel:。
- match.rawKeyPrefix 匹配原始会话键（小写），包括 agent:<id>:。例如：agent:main:discord:。
- 遗留：match.keyPrefix: "agent:..." 仍被视为原始键前缀，但为了清晰优先使用 rawKeyPrefix。
当 scope 拒绝搜索时，OpenClaw 记录带有派生 channel/chatType 的警告，以便更容易调试空结果。
来自工作空间外的片段在 memory_search 结果中显示为 qmd/<collection>/<relative-path>；memory_get 理解该前缀并从配置的 QMD 集合根读取。
当 memory.qmd.sessions.enabled = true 时，OpenClaw 将清理的会话记录（用户/助手轮次）导出到 ~/.openclaw/agents/<id>/qmd/sessions/ 下的专用 QMD 集合，因此 memory_search 可以回忆最近的对话而无需触及内置 SQLite 索引。
当 memory.citations 是 auto/on 时，memory_search 片段现在包括 Source: <path#line> 页脚；设置 memory.citations = "off" 以保持路径元数据内部（agent 仍然接收路径用于 memory_get，但片段文本省略页脚，系统提示警告 agent 不要引用它）。

示例

memory: {
  backend: "qmd",
  citations: "auto",
  qmd: {
    includeDefaultMemory: true,
    update: { interval: "5m", debounceMs: 15000 },
    limits: { maxResults: 6, timeoutMs: 4000 },
    scope: {
      default: "deny",
      rules: [
        { action: "allow", match: { chatType: "direct" } },
        // 规范化会话键前缀（剥离 `agent:<id>:`）。
        { action: "deny", match: { keyPrefix: "discord:channel:" } },
        // 原始会话键前缀（包括 `agent:<id>:`）。
        { action: "deny", match: { rawKeyPrefix: "agent:main:discord:" } },
      ]
    },
    paths: [
      { name: "docs", path: "~/notes", pattern: "**/*.md" }
    ]
  }
}

引用和回退

memory.citations 适用于任何后端（auto/on/off）。
当 qmd 运行时，我们标记 status().backend = "qmd"，因此诊断显示哪个引擎服务结果。如果 QMD 子进程退出或无法解析 JSON 输出，搜索管理器记录警告并返回内置提供者（现有 Markdown 嵌入），直到 QMD 恢复。

额外 memory 路径

如果你想在默认工作空间布局之外索引 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"。

回退：

memorySearch.fallback 可以是 openai、gemini、voyage、mistral、ollama、local 或 none。
仅当主嵌入提供者失败时才使用回退提供者。

批量索引（OpenAI + Gemini + Voyage）：

默认禁用。设置 agents.defaults.memorySearch.remote.batch.enabled = true 以启用大语料库索引（OpenAI、Gemini 和 Voyage）。
默认行为等待批量完成；如果需要，调整 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 — 按路径读取 memory 文件内容。

本地模式：

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

memory 工具如何工作

memory_search 语义搜索 MEMORY.md + memory/**/*.md 中的 Markdown 块（~400 token 目标，80 token 重叠）。它返回片段文本（上限 ~700 字符）、文件路径、行范围、分数、提供者/模型，以及我们是否从本地回退到远程嵌入。不返回完整文件负载。
memory_get 读取特定 memory Markdown 文件（工作空间相对），可选从起始行和 N 行。MEMORY.md / memory/ 之外的路径被拒绝。
仅当 memorySearch.enabled 为 agent 解析为 true 时才启用这两个工具。

什么被索引（以及何时）

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

混合搜索（BM25 + 向量）

启用时，OpenClaw 结合：

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

如果你的平台上全文搜索不可用，OpenClaw 回退到仅向量搜索。

为什么混合？

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

"Mac Studio gateway host" vs "运行 gateway 的机器"
"去抖文件更新" vs "避免每次写入时索引"

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

ID（a828e60、b3b9895a…）
代码符号（memorySearch.query.hybrid）
错误字符串（"sqlite-vec 不可用"）

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

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

实现草图：

从双方检索候选池：

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

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

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

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

finalScore = vectorWeight * vectorScore + textWeight * textScore

注意：

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

这不是"IR-理论完美"，但它简单、快速，并且倾向于提高真实笔记的召回率/精确率。如果我们以后想要更花哨，常见的下一步是 Reciprocal Rank Fusion (RRF) 或分数归一化（最小/最大或 z-score）在混合之前。

后处理管道

合并向量和关键词分数后，两个可选的后处理阶段在结果列表到达 agent 之前优化它：

向量 + 关键词 → 加权合并 → 时间衰减 → 排序 → MMR → Top-K 结果

两个阶段都默认关闭，可以独立启用。

MMR 重排序（多样性）

当混合搜索返回结果时，多个块可能包含相似或重叠的内容。例如，搜索"home network setup"可能会从不同的每日笔记中返回五个几乎相同的片段，它们都提到相同的路由器配置。

MMR（最大边际相关性） 重新排序结果以平衡相关性与多样性，确保顶级结果覆盖查询的不同方面，而不是重复相同的信息。

工作原理：

结果按其原始相关性评分（向量 + BM25 加权分数）。
MMR 迭代选择最大化以下内容的结果：λ × 相关性 − (1−λ) × max_similarity_to_selected。
结果之间的相似度使用分词内容的 Jaccard 文本相似度测量。

lambda 参数控制权衡：

lambda = 1.0 → 纯相关性（无多样性惩罚）
lambda = 0.0 → 最大多样性（忽略相关性）
默认：0.7（平衡，略偏向相关性）

示例 — 查询："home network setup"

给定这些 memory 文件：

memory/2026-02-10.md  → "配置了 Omada 路由器，为 IoT 设备设置 VLAN 10"
memory/2026-02-08.md  → "配置了 Omada 路由器，将 IoT 移到 VLAN 10"
memory/2026-02-05.md  → "在 192.168.10.2 上设置 AdGuard DNS"
memory/network.md     → "路由器：Omada ER605，AdGuard：192.168.10.2，VLAN 10：IoT"

没有 MMR — 前 3 个结果：

1. memory/2026-02-10.md  (分数：0.92)  ← 路由器 + VLAN
2. memory/2026-02-08.md  (分数：0.89)  ← 路由器 + VLAN（近乎重复！）
3. memory/network.md     (分数：0.85)  ← 参考文档

使用 MMR (λ=0.7) — 前 3 个结果：

1. memory/2026-02-10.md  (分数：0.92)  ← 路由器 + VLAN
2. memory/network.md     (分数：0.85)  ← 参考文档（多样！）
3. memory/2026-02-05.md  (分数：0.78)  ← AdGuard DNS（多样！）

2 月 8 日的近乎重复项被淘汰，agent 获得三个不同的信息片段。

何时启用： 如果你注意到 memory_search 返回冗余或近乎重复的片段，尤其是对于经常在不同天重复类似信息的每日笔记。

时间衰减（最近提升）

带有每日笔记的 agent 随时间积累数百个 dated 文件。没有衰减，六个月前措辞良好的笔记可以超过昨天关于同一主题的更新。

时间衰减根据每个结果的年龄对分数应用指数乘数，因此最近的 memory 自然排名更高，而旧的 fading：

decayedScore = score × e^(-λ × ageInDays)

其中 λ = ln(2) / halfLifeDays。

使用默认的 30 天半衰期：

今天的笔记：100% 原始分数
7 天前：~84%
30 天前：50%
90 天前：12.5%
180 天前：~1.6%

常青文件从不衰减：

MEMORY.md（根 memory 文件）
memory/ 中的非 dated 文件（例如 memory/projects.md、memory/network.md）
这些包含持久的参考信息，应始终正常排名。

dated 每日文件（memory/YYYY-MM-DD.md）使用从文件名提取的日期。其他来源（例如会话记录）回退到文件修改时间（mtime）。

示例 — 查询："Rod 的工作时间表是什么？"

给定这些 memory 文件（今天是 2 月 10 日）：

memory/2025-09-15.md  → "Rod 周一至周五工作，站会 10 点，配对 14 点"  (148 天旧)
memory/2026-02-10.md  → "Rod 有 14:15 站会，14:45 与 Zeb 的 1:1"    (今天)
memory/2026-02-03.md  → "Rod 开始新团队，站会移到 14:15"        (7 天旧)

没有衰减：

1. memory/2025-09-15.md  (分数：0.91)  ← 最佳语义匹配，但过时！
2. memory/2026-02-10.md  (分数：0.82)
3. memory/2026-02-03.md  (分数：0.80)

使用衰减（半衰期=30）：

1. memory/2026-02-10.md  (分数：0.82 × 1.00 = 0.82)  ← 今天，无衰减
2. memory/2026-02-03.md  (分数：0.80 × 0.85 = 0.68)  ← 7 天，轻度衰减
3. memory/2025-09-15.md  (分数：0.91 × 0.03 = 0.03)  ← 148 天，几乎消失

尽管具有最佳原始语义匹配，过时的 9 月笔记下降到底部。

何时启用： 如果你的 agent 有数月的每日笔记，并且你发现旧的、过时的信息超过最近的上下文。30 天的半衰期适用于每日笔记繁重的工作流；如果你经常引用旧笔记，增加它（例如 90 天）。

配置

两个功能都在 memorySearch.query.hybrid 下配置：

agents: {
  defaults: {
    memorySearch: {
      query: {
        hybrid: {
          enabled: true,
          vectorWeight: 0.7,
          textWeight: 0.3,
          candidateMultiplier: 4,
          // 多样性：减少冗余结果
          mmr: {
            enabled: true,    // 默认：false
            lambda: 0.7       // 0 = 最大多样性，1 = 最大相关性
          },
          // 最近性：提升更新的 memory
          temporalDecay: {
            enabled: true,    // 默认：false
            halfLifeDays: 30  // 分数每 30 天减半
          }
        }
      }
    }
  }
}

你可以独立启用任一功能：

仅 MMR — 当你有许多相似笔记但年龄不重要时有用。
仅时间衰减 — 当最近性重要但结果已经多样时有用。
两者 — 推荐用于具有大量、长期运行的每日笔记历史的 agent。

嵌入缓存

OpenClaw 可以在 SQLite 中缓存块嵌入，因此重新索引和频繁更新（尤其是会话记录）不会重新嵌入未更改的文本。

配置：

agents: {
  defaults: {
    memorySearch: {
      cache: {
        enabled: true,
        maxEntries: 50000
      }
    }
  }
}

会话 memory 搜索（实验性）

你可以选择索引会话记录并通过 memory_search 显示它们。这由实验标志控制。

agents: {
  defaults: {
    memorySearch: {
      experimental: { sessionMemory: true },
      sources: ["memory", "sessions"]
    }
  }
}

注意：

会话索引是选择加入（默认关闭）。
会话更新去抖并在超过增量阈值时异步索引（尽力而为）。
memory_search 从不阻塞索引；结果可能略微过时，直到后台同步完成。
结果仍然仅包括片段；memory_get 仍然限于 memory 文件。
会话索引按 agent 隔离（仅索引该 agent 的会话日志）。
会话日志存在于磁盘上（~/.openclaw/agents/<agentId>/sessions/*.jsonl）。任何具有文件系统访问权限的进程/用户都可以读取它们，因此将磁盘访问视为信任边界。对于更严格的隔离，在不同的 OS 用户或主机下运行 agent。

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

agents: {
  defaults: {
    memorySearch: {
      sync: {
        sessions: {
          deltaBytes: 100000,   // ~100 KB
          deltaMessages: 50     // JSONL 行
        }
      }
    }
  }
}

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-qat-q8_0-GGUF/embeddinggemma-300m-qat-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 默认值。