Memory

OpenClaw 的 Memory 是 Agent Workspace 中的纯 Markdown 文件。这些文件是唯一的真实来源；模型只会”记住”写入磁盘的内容。

Memory 搜索工具由活跃的 Memory Plugin 提供（默认是 memory-core）。可以用 plugins.slots.memory = "none" 禁用 Memory Plugin。

Memory 文件（Markdown）

默认的 Workspace 布局使用两层 Memory：

memory/YYYY-MM-DD.md
- 每日日志（只追加）。
- Session 启动时会读取今天和昨天的日志。
MEMORY.md（可选）
- 精选的长期记忆。
- 只在主 Session、私人 Session 中加载（不会在群组场景中加载）。

这些文件位于 Workspace 下（agents.defaults.workspace，默认是 ~/.openclaw/workspace）。完整布局请参考 Agent Workspace。

何时写入 Memory

决策、偏好和持久性事实写入 MEMORY.md。
日常笔记和运行时上下文写入 memory/YYYY-MM-DD.md。
如果有人说”记住这个”，就写下来（不要只保存在内存中）。
这个功能还在演进中。提醒模型存储记忆会有帮助；它知道该怎么做。
如果你想让某些内容持久保存，让 Agent 把它写入 Memory。

自动 Memory 刷新（Compaction 前的提醒）

当 Session 接近自动 Compaction 时，OpenClaw 会触发一个静默的 Agent 回合，提醒模型在 Context 被压缩之前写入持久 Memory。默认 Prompt 明确说明模型_可以回复_，但通常 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.",
        },
      },
    },
  },
}

详细说明：

软阈值：当 Session 的 Token 估算超过 contextWindow - reserveTokensFloor - softThresholdTokens 时触发刷新。
默认静默：Prompt 包含 NO_REPLY，所以不会有内容发送给用户。
两个 Prompt：一个用户 Prompt 加上一个系统 Prompt 来追加提醒。
每个 Compaction 周期只刷新一次（在 sessions.json 中跟踪）。
Workspace 必须可写：如果 Session 在沙箱中运行且 workspaceAccess: "ro" 或 "none"，则跳过刷新。

完整的 Compaction 生命周期请参考 Session 管理 + Compaction。

向量 Memory 搜索

OpenClaw 可以为 MEMORY.md 和 memory/*.md（以及你选择加入的额外目录或文件）构建一个小型向量索引，这样语义查询就能找到相关笔记，即使措辞不同。

默认设置：

默认启用。
监视 Memory 文件的变化（防抖）。
默认使用远程 Embeddings。如果没有设置 memorySearch.provider，OpenClaw 会自动选择：
1. 如果配置了 memorySearch.local.modelPath 且文件存在，使用 local。
2. 如果能解析到 OpenAI 密钥，使用 openai。
3. 如果能解析到 Gemini 密钥，使用 gemini。
4. 否则 Memory 搜索保持禁用状态，直到配置完成。
本地模式使用 node-llama-cpp，可能需要运行 pnpm approve-builds。
使用 sqlite-vec（如果可用）来加速 SQLite 内的向量搜索。

远程 Embeddings 需要 Embedding Provider 的 API 密钥。OpenClaw 从认证配置、models.providers.*.apiKey 或环境变量中解析密钥。Codex OAuth 只覆盖聊天/补全，不满足 Memory 搜索的 Embeddings 需求。对于 Gemini，使用 GEMINI_API_KEY 或 models.providers.google.apiKey。使用自定义 OpenAI 兼容端点时，设置 memorySearch.remote.apiKey（以及可选的 memorySearch.remote.headers）。

额外的 Memory 路径

如果你想索引默认 Workspace 布局之外的 Markdown 文件，添加明确的路径：

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

注意：

路径可以是绝对路径或相对于 Workspace 的路径。
目录会递归扫描 .md 文件。
只索引 Markdown 文件。
忽略符号链接（文件或目录）。

Gemini Embeddings（原生）

将 Provider 设置为 gemini 来直接使用 Gemini Embeddings API：

agents: {
  defaults: {
    memorySearch: {
      provider: "gemini",
      model: "gemini-embedding-001",
      remote: {
        apiKey: "YOUR_GEMINI_API_KEY"
      }
    }
  }
}

注意：

remote.baseUrl 是可选的（默认为 Gemini API 基础 URL）。
remote.headers 允许你在需要时添加额外的 Header。
默认模型：gemini-embedding-001。

如果你想使用自定义 OpenAI 兼容端点（OpenRouter、vLLM 或代理），可以在 OpenAI Provider 中使用 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、local 或 none。
回退 Provider 只在主 Embedding Provider 失败时使用。

批量索引（OpenAI + Gemini）：

默认为 OpenAI 和 Gemini Embeddings 启用。设置 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 批处理任务使用异步 Embeddings 批处理端点，需要 Gemini Batch API 可用。

为什么 OpenAI 批处理又快又便宜：

对于大型回填，OpenAI 通常是我们支持的最快选项，因为我们可以在单个批处理任务中提交许多 Embedding 请求，让 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 字符）、文件路径、行范围、分数、Provider/模型，以及是否从本地回退到远程 Embeddings。不返回完整文件内容。
memory_get 读取特定的 Memory Markdown 文件（相对于 Workspace），可选从起始行开始读取 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} 占位符）。
新鲜度：监视器监视 MEMORY.md、memory/ 和 memorySearch.extraPaths，标记索引为脏（防抖 1.5 秒）。同步在 Session 启动、搜索时或按间隔调度，并异步运行。Session 记录使用增量阈值来触发后台同步。
重新索引触发器：索引存储 Embedding Provider/模型 + 端点指纹 + 分块参数。如果其中任何一个改变，OpenClaw 会自动重置并重新索引整个存储。

混合搜索（BM25 + 向量）

启用后，OpenClaw 会结合：

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

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

为什么要混合搜索？

向量搜索擅长”意思相同”的匹配：

“Mac Studio Gateway 主机” vs “运行 Gateway 的机器”
“防抖文件更新” vs “避免每次写入都索引”

但它在精确、高信号 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))

按块 ID 合并候选项并计算加权分数：

finalScore = vectorWeight * vectorScore + textWeight * textScore

注意：

vectorWeight + textWeight 在配置解析时归一化为 1.0，所以权重表现为百分比。
如果 Embeddings 不可用（或 Provider 返回零向量），我们仍然运行 BM25 并返回关键词匹配。
如果无法创建 FTS5，我们保持纯向量搜索（不会硬失败）。

这不是”信息检索理论完美”的方案，但它简单、快速，并且在实际笔记上往往能提高召回率/精确度。如果以后想更高级，常见的下一步是倒数排名融合（RRF）或在混合前进行分数归一化（最小/最大或 z 分数）。

配置：

agents: {
  defaults: {
    memorySearch: {
      query: {
        hybrid: {
          enabled: true,
          vectorWeight: 0.7,
          textWeight: 0.3,
          candidateMultiplier: 4
        }
      }
    }
  }
}

Embedding 缓存

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

配置：

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

Session Memory 搜索（实验性）

你可以选择索引 Session 记录并通过 memory_search 展示它们。这个功能在实验性标志后面。

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

注意：

Session 索引是选择加入的（默认关闭）。
Session 更新会防抖，并在超过增量阈值后异步索引（尽力而为）。
memory_search 永远不会阻塞索引；结果可能会略微过时，直到后台同步完成。
结果仍然只包含片段；memory_get 仍然限于 Memory 文件。
Session 索引按 Agent 隔离（只索引该 Agent 的 Session 日志）。
Session 日志存储在磁盘上（~/.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 会将 Embeddings 存储在 SQLite 虚拟表（vec0）中，并在数据库中执行向量距离查询。这样可以保持搜索快速，而无需将每个 Embedding 加载到 JS 中。

配置（可选）：

agents: {
  defaults: {
    memorySearch: {
      store: {
        vector: {
          enabled: true,
          extensionPath: "/path/to/sqlite-vec"
        }
      }
    }
  }
}

注意：

enabled 默认为 true；禁用时，搜索会回退到对存储的 Embeddings 进行进程内余弦相似度计算。
如果 sqlite-vec 扩展缺失或加载失败，OpenClaw 会记录错误并继续使用 JS 回退（没有向量表）。
extensionPath 覆盖捆绑的 sqlite-vec 路径（对自定义构建或非标准安装位置有用）。

本地 Embedding 自动下载

默认本地 Embedding 模型：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"，我们会自动切换到远程 Embeddings（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 Header 合并；远程配置在键冲突时优先。省略 remote.headers 以使用 OpenAI 默认值。