记忆

OpenClaw 内存是 代理工作区中的纯 Markdown。 OpenClaw 记忆是智能体工作空间中的纯 Markdown 文件。这些文件是唯一的事实来源；模型只”记住”写入磁盘的内容。
内存搜索工具由活动的内存插件提供（默认： memory-core）。 Disable memory plugins with plugins.slots.memory = "none".

记忆文件（Markdown）

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

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

这些文件位于工作空间下（agents.defaults.workspace，默认 ~/.openclaw/workspace）。完整布局参见智能体工作空间。 See Agent workspace for the full layout.

何时写入记忆

决策、偏好和持久性事实写入 MEMORY.md。
日常笔记和运行上下文写入 memory/YYYY-MM-DD.md。
如果有人说”记住这个”，就写下来（不要只保存在内存中）。
This area is still evolving. 这个领域仍在发展中。提醒模型存储记忆会有帮助；它会知道该怎么做。
如果你想让某些内容持久保存，请要求机器人将其写入记忆。

自动记忆刷新（压缩前触发）

当会话接近自动压缩时，OpenClaw 会触发一个静默的智能体回合，提醒模型在上下文被压缩之前写入持久记忆。默认提示明确说明模型_可以回复_，但通常 NO_REPLY 是正确的响应，因此用户永远不会看到这个回合。 The default prompts explicitly say the model may reply, but usually NO_REPLY is the correct response so the user never sees this turn. 这由 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.",
        },
      },
    },
  },
}

详情：

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

完整的压缩生命周期参见会话管理 + 压缩。

向量记忆搜索

OpenClaw 可以在 MEMORY.md 和 memory/*.md（以及你选择加入的任何额外目录或文件）上构建小型向量索引，以便语义查询可以找到相关笔记，即使措辞不同。默认值：

默认启用。
监视记忆文件的更改（去抖动）。
记忆搜索工具由活动的记忆插件提供（默认：memory-core）。使用 plugins.slots.memory = "none" 禁用记忆插件。
Uses remote embeddings by default. 默认使用远程嵌入。如果未设置 memorySearch.provider，OpenClaw 自动选择：
1. 如果配置了 memorySearch.local.modelPath 且文件存在，则使用 local。
2. 如果可以解析 OpenAI 密钥，则使用 openai。
3. 如果可以解析 Gemini 密钥，则使用 gemini。
4. voyage if a Voyage key can be resolved.
5. 否则记忆搜索保持禁用状态直到配置完成。
本地模式使用 node-llama-cpp，可能需要运行 pnpm approve-builds。
使用 sqlite-vec（如果可用）在 SQLite 中加速向量搜索。

Remote embeddings require an API key for the embedding provider. OpenClaw resolves keys from auth profiles, models.providers.*.apiKey, or environment variables. Codex OAuth only covers chat/completions and does not satisfy embeddings for memory search. For Gemini, use GEMINI_API_KEY or models.providers.google.apiKey. For Voyage, use VOYAGE_API_KEY or models.providers.voyage.apiKey. When using a custom OpenAI-compatible endpoint, set memorySearch.remote.apiKey (and optional memorySearch.remote.headers).

QMD backend (experimental)

Set memory.backend = "qmd" to swap the built-in SQLite indexer for QMD: a local-first search sidecar that combines BM25 + vectors + reranking. Markdown stays the source of truth; OpenClaw shells out to QMD for retrieval. Key points: Prereqs

Disabled by default. Opt in per-config (memory.backend = "qmd").
Install the QMD CLI separately (bun install -g https://github.com/tobi/qmd or grab a release) and make sure the qmd binary is on the gateway’s PATH.
QMD needs an SQLite build that allows extensions (brew install sqlite on macOS).
QMD runs fully locally via Bun + node-llama-cpp and auto-downloads GGUF models from HuggingFace on first use (no separate Ollama daemon required).
The gateway runs QMD in a self-contained XDG home under ~/.openclaw/agents/<agentId>/qmd/ by setting XDG_CONFIG_HOME and XDG_CACHE_HOME.
OS support: macOS and Linux work out of the box once Bun + SQLite are installed. Windows is best supported via WSL2.

How the sidecar runs

The gateway writes a self-contained QMD home under ~/.openclaw/agents/<agentId>/qmd/ (config + cache + sqlite DB).
Collections are created via qmd collection add from memory.qmd.paths (plus default workspace memory files), then qmd update + qmd embed run on boot and on a configurable interval (memory.qmd.update.interval, default 5 m).
gateway 现在会在启动时初始化 QMD 管理器，因此即使在首次调用 memory_search 之前也会启动周期性更新计时器。
Boot refresh now runs in the background by default so chat startup is not blocked; set memory.qmd.update.waitForBootSync = true to keep the previous blocking behavior.
搜索通过 memory.qmd.searchMode 运行（默认 qmd search --json；也支持 vsearch 和 query）。如果所选模式在你的 QMD 构建中拒绝某些标志参数，OpenClaw 会使用 qmd query 重试。如果 QMD 失败或缺少二进制文件，OpenClaw 会自动回退到内置的 SQLite 管理器，以确保 memory 工具继续正常工作。
OpenClaw does not expose QMD embed batch-size tuning today; batch behavior is controlled by QMD itself.
First search may be slow: QMD may download local GGUF models (reranker/query expansion) on the first qmd query run.
- OpenClaw sets XDG_CONFIG_HOME/XDG_CACHE_HOME automatically when it runs QMD.
- If you want to pre-download models manually (and warm the same index OpenClaw uses), run a one-off query with the agent’s XDG dirs. OpenClaw’s QMD state lives under your state dir (defaults to ~/.openclaw). You can point qmd at the exact same index by exporting the same XDG vars OpenClaw uses:
  # 选择与 OpenClaw 使用的相同 state 目录 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" # （可选）强制刷新索引并生成 embeddings qmd update qmd embed # 预热 / 触发首次模型下载 qmd query "test" -c memory-root --json >/dev/null 2>&1

Config surface (memory.qmd.*)

command (default qmd): override the executable path.
searchMode（默认 search）：选择用于支持 memory_search 的 QMD 命令（search、vsearch、query）。
includeDefaultMemory (default true): auto-index MEMORY.md + memory/**/*.md.
paths[]: add extra directories/files (path, optional pattern, optional stable name).
sessions: opt into session JSONL indexing (enabled, retentionDays, exportDir).
update: controls refresh cadence and maintenance execution: (interval, debounceMs, onBoot, waitForBootSync, embedInterval, commandTimeoutMs, updateTimeoutMs, embedTimeoutMs).
limits: clamp recall payload (maxResults, maxSnippetChars, maxInjectedChars, timeoutMs).
scope: same schema as session.sendPolicy. Default is DM-only (deny all, allow direct chats); loosen it to surface QMD hits in groups/channels.
- match.keyPrefix 匹配规范化后的 session key（转换为小写，并去除任何前导的 agent:<id>:）。示例：discord:channel:。
- match.rawKeyPrefix 匹配原始 session key（小写），包括 agent:<id>:。示例：agent:main:discord:。
- 兼容旧版：match.keyPrefix: "agent:..." 仍会被视为原始 key 前缀，但为清晰起见，建议使用 rawKeyPrefix。
When scope denies a search, OpenClaw logs a warning with the derived channel/chatType so empty results are easier to debug.
memory_get 读取特定的记忆 Markdown 文件（工作空间相对路径），可选从起始行开始读取 N 行。MEMORY.md / memory/ 之外的路径仅在明确列在 memorySearch.extraPaths 中时才允许。
When memory.qmd.sessions.enabled = true, OpenClaw exports sanitized session transcripts (User/Assistant turns) into a dedicated QMD collection under ~/.openclaw/agents/<id>/qmd/sessions/, so memory_search can recall recent conversations without touching the builtin SQLite index.
memory_search snippets now include a Source: <path#line> footer when memory.citations is auto/on; set memory.citations = "off" to keep the path metadata internal (the agent still receives the path for memory_get, but the snippet text omits the footer and the system prompt warns the agent not to cite it).

Example

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" } },
        // 规范化后的 session-key 前缀（去除 `agent:<id>:`）。
        { action: "deny", match: { keyPrefix: "discord:channel:" } },
        // 原始 session-key 前缀（包含 `agent:<id>:`）。
        { action: "deny", match: { rawKeyPrefix: "agent:main:discord:" } },
      ]
    },
    paths: [
      { name: "docs", path: "~/notes", pattern: "**/*.md" }
    ]
  }
}

引用与回退

1. memory.citations 不论后端（auto/on/off）如何都适用。
当 qmd 运行时，我们会标记 status().backend = "qmd"，以便诊断信息显示是哪个引擎提供了结果。如果 QMD 子进程退出或 JSON 输出无法解析，搜索管理器会记录一条警告，并返回内置提供方（现有的 Markdown 嵌入），直到 QMD 恢复。

额外记忆路径

如果你想索引默认工作空间布局之外的 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 或代理），可以使用 remote 配置与 OpenAI 提供商：

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。
回退提供商仅在主嵌入提供商失败时使用。

批量索引（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 个字符）、文件路径、行范围、分数、提供商/模型，以及我们是否从本地回退到远程嵌入。不返回完整文件内容。 It returns snippet text (capped ~700 chars), file path, line range, score, provider/model, and whether we fell back from local → remote embeddings. No full file payload is returned.
1. memory_get 读取一个特定的内存 Markdown 文件（相对于工作区），可选择从起始行开始并读取 N 行。 Paths outside MEMORY.md / memory/ are rejected.
两个工具仅在智能体的 memorySearch.enabled 解析为 true 时启用。

索引内容（及时机）

文件类型：仅 Markdown（MEMORY.md、memory/**/*.md，以及 memorySearch.extraPaths 下的任何 .md 文件）。
索引存储：每个智能体的 SQLite 位于 ~/.openclaw/memory/<agentId>.sqlite（可通过 agents.defaults.memorySearch.store.path 配置，支持 {agentId} 令牌）。
1. 新鲜度：监视 MEMORY.md + memory/，将索引标记为脏（防抖 1.5s）。 Sync is scheduled on session start, on search, or on an interval and runs asynchronously. Session transcripts use delta thresholds to trigger background sync.
重新索引触发器：索引存储嵌入的提供商/模型 + 端点指纹 + 分块参数。如果其中任何一个发生变化，OpenClaw 会自动重置并重新索引整个存储。如果其中任何一项发生变化，OpenClaw 会自动重置并重新索引整个存储。

混合搜索（BM25 + 向量）

启用时，OpenClaw 结合：

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

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

17. 为什么要混合？

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

“Mac Studio gateway host” vs “运行 gateway 的机器”
“debounce file updates” vs “避免每次写入都索引”

但它在精确的高信号令牌上可能较弱：

ID（a828e60、b3b9895a…）
代码符号（memorySearch.query.hybrid）
错误字符串（“sqlite-vec unavailable”）

BM25 (full-text) is the opposite: strong at exact tokens, weaker at paraphrases. Hybrid search is the pragmatic middle ground: use both retrieval signals so you get good results for both “natural language” queries and “needle in a haystack” queries.

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

实现概述：

从双方检索候选池：

向量：按余弦相似度取前 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 理论完美”的，但它简单、快速，并且往往能提高真实笔记的召回率/精确率。如果我们以后想要更复杂的方案，常见的下一步是倒数排名融合（RRF）或在混合之前进行分数归一化（最小/最大或 z 分数）。 If we want to get fancier later, common next steps are Reciprocal Rank Fusion (RRF) or score normalization (min/max or z-score) before mixing. 配置：

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 呈现它们。这由实验性标志控制。 2. 此功能受一个实验性标志控制。

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

说明：

会话索引是选择加入的（默认关闭）。
会话更新被去抖动并在超过增量阈值后异步索引（尽力而为）。
memory_search 永远不会阻塞索引；在后台同步完成之前，结果可能略有延迟。
结果仍然只包含片段；memory_get 仍然仅限于记忆文件。
1. 会话索引按代理隔离（只索引该代理自身的会话日志）。
会话日志存储在磁盘上（~/.openclaw/agents/<agentId>/sessions/*.jsonl）。任何具有文件系统访问权限的进程/用户都可以读取它们，因此将磁盘访问视为信任边界。对于更严格的隔离，在单独的操作系统用户或主机下运行智能体。 11. 任何具有文件系统访问权限的进程/用户都可以读取它们，因此请将磁盘访问视为信任边界。 12. 若需要更严格的隔离，请在不同的操作系统用户或主机下运行代理。

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

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

SQLite 向量加速（sqlite-vec）

当 sqlite-vec 扩展可用时，OpenClaw 将嵌入存储在 SQLite 虚拟表（vec0）中，并在数据库中执行向量距离查询。这使搜索保持快速，无需将每个嵌入加载到 JS 中。 17. 这可以在不将所有嵌入加载到 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，如果已设置），然后加载它。下载在重试时会续传。 27. 下载在重试时会继续（断点续传）。
原生构建要求：运行 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 优先。省略 remote.headers 以使用 OpenAI 默认值。 35. 省略 remote.headers 以使用 OpenAI 的默认值。

基础

引导初始化

会话与内存

多智能体

消息与传递

记忆

记忆

记忆文件（Markdown）

何时写入记忆

自动记忆刷新（压缩前触发）

向量记忆搜索

QMD backend (experimental)

额外记忆路径

Gemini 嵌入（原生）

记忆工具的工作原理

索引内容（及时机）

混合搜索（BM25 + 向量）

17. 为什么要混合？

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

嵌入缓存

会话记忆搜索（实验性）

SQLite 向量加速（sqlite-vec）

本地嵌入自动下载

自定义 OpenAI 兼容端点示例

基础

引导初始化

会话与内存

多智能体

消息与传递

​记忆

​记忆文件（Markdown）

​何时写入记忆

​自动记忆刷新（压缩前触发）

​向量记忆搜索

​QMD backend (experimental)

​额外记忆路径

​Gemini 嵌入（原生）

​记忆工具的工作原理

​索引内容（及时机）

​混合搜索（BM25 + 向量）

​17. 为什么要混合？

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

​嵌入缓存

​会话记忆搜索（实验性）

​SQLite 向量加速（sqlite-vec）

​本地嵌入自动下载

​自定义 OpenAI 兼容端点示例

记忆

记忆文件（Markdown）

何时写入记忆

自动记忆刷新（压缩前触发）

向量记忆搜索

QMD backend (experimental)

额外记忆路径

Gemini 嵌入（原生）

记忆工具的工作原理

索引内容（及时机）

混合搜索（BM25 + 向量）

17. 为什么要混合？

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

嵌入缓存

会话记忆搜索（实验性）

SQLite 向量加速（sqlite-vec）

本地嵌入自动下载

自定义 OpenAI 兼容端点示例