内存

OpenClaw 内存是代理工作空间中的纯 Markdown 文件。这些文件是真实的数据源;模型只"记住"写入磁盘的内容。

内存搜索工具由活动内存插件提供(默认: memory-core)。使用 plugins.slots.memory = "none" 禁用内存插件。

内存文件 (Markdown)

默认工作空间布局使用两层内存:

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

这些文件存储在工作空间下(agents.defaults.workspace,默认为 ~/clawd)。请参阅代理工作空间了解完整布局。

何时写入内存

决策、偏好和持久事实写入 MEMORY.md。
日常笔记和运行上下文写入 memory/YYYY-MM-DD.md。
如果有人说"记住这个",请将其写下(不要保存在 RAM 中)。
这个领域仍在发展。提醒模型存储记忆会有帮助;它会知道该怎么做。
如果你想让某些内容持久化,让机器人将其写入内存。

自动内存刷新(预压缩提示)

当会话接近自动压缩时,OpenClaw 会触发一个静默的、智能的回合,提醒模型在上下文被压缩之前写入持久内存。默认提示明确说明模型_可以回复_,但通常 NO_REPLY 是正确的响应,因此用户永远看不到这个回合。

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

json5

{
  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. 如果配置了 memorySearch.local.modelPath 且文件存在,则使用 local。
2. 如果可以解析 OpenAI 密钥,则使用 openai。
3. 如果可以解析 Gemini 密钥,则使用 gemini。
4. 否则内存搜索保持禁用状态,直到配置完成。
本地模式使用 node-llama-cpp,可能需要 pnpm approve-builds。
使用 sqlite-vec(如果可用)在 SQLite 内加速向量搜索。

远程嵌入需要嵌入提供商的 API 密钥。OpenClaw 从身份验证配置文件、models.providers.*.apiKey 或环境变量解析密钥。Codex OAuth 仅涵盖聊天/完成,不满足内存搜索的嵌入需求。对于 Gemini,使用 GEMINI_API_KEY 或 models.providers.google.apiKey。使用自定义 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 github.com/tobi/qmd 或获取发布版本),并确保 qmd 二进制文件在网关的 PATH 上。
QMD 需要允许扩展的 SQLite 构建(macOS 上的 brew install sqlite)。
QMD 通过 Bun + node-llama-cpp 完全在本地运行,并在首次使用时从 HuggingFace 自动下载 GGUF 模型(不需要单独的 Ollama 守护进程)。
网关通过设置 XDG_CONFIG_HOME 和 XDG_CACHE_HOME,在 ~/.openclaw/agents/<agentId>/qmd/ 下运行 QMD 的独立 XDG 主目录。
操作系统支持:安装 Bun + SQLite 后,macOS 和 Linux 可以直接使用。Windows 最好通过 WSL2 支持。

辅助程序如何运行

网关在 ~/.openclaw/agents/<agentId>/qmd/ 下写入独立的 QMD 主目录(配置 + 缓存 + sqlite 数据库)。
集合从 memory.qmd.paths(加上默认工作空间内存文件)重写为 index.yml,然后在启动时和可配置间隔上运行 qmd update + qmd embed(memory.qmd.update.interval,默认 5 分钟)。
搜索通过 qmd query --json 运行。如果 QMD 失败或二进制文件缺失,OpenClaw 会自动回退到内置 SQLite 管理器,以便内存工具继续工作。

首次搜索可能很慢:QMD 可能在首次 qmd query 运行时下载本地 GGUF 模型(重新排序器/查询扩展)。

OpenClaw 在运行 QMD 时自动设置 XDG_CONFIG_HOME/XDG_CACHE_HOME。

如果你想手动预下载模型(并预热 OpenClaw 使用的同一索引),请使用代理的 XDG 目录运行一次性查询。

OpenClaw 的 QMD 状态位于你的状态目录下(默认为 ~/.openclaw)。你可以通过导出 OpenClaw 使用的相同 XDG 变量,将 qmd 指向完全相同的索引:

bash

# Pick the same state dir OpenClaw uses
STATE_DIR="${OPENCLAW_STATE_DIR:-$HOME/.openclaw}"
if [ -d "$HOME/.moltbot" ] && [ ! -d "$HOME/.openclaw" ] \
  && [ -z "${OPENCLAW_STATE_DIR:-}" ]; then
  STATE_DIR="$HOME/.moltbot"
fi

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

# (Optional) force an index refresh + embeddings
qmd update
qmd embed

# Warm up / trigger first-time model downloads
qmd query "test" -c memory-root --json >/dev/null 2>&1

配置表面 (memory.qmd.*)

command(默认 qmd):覆盖可执行文件路径。
includeDefaultMemory(默认 true):自动索引 MEMORY.md + memory/**/*.md。
paths[]:添加额外的目录/文件(path,可选 pattern,可选稳定的 name)。
sessions:选择加入会话 JSONL 索引(enabled,retentionDays,exportDir)。
update:控制刷新频率(interval,debounceMs,onBoot,embedInterval)。
limits:限制召回负载(maxResults,maxSnippetChars,maxInjectedChars,timeoutMs)。
scope:与 session.sendPolicy 相同的架构。默认仅限 DM(deny 全部,allow 直接聊天);放宽它以在群组/频道中显示 QMD 结果。
工作空间外的源片段在 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" 以保持路径元数据为内部(代理仍接收 memory_get 的路径,但片段文本省略页脚,系统提示警告代理不要引用它)。

示例

json5

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" } }]
    },
    paths: [
      { name: "docs", path: "~/notes", pattern: "**/*.md" }
    ]
  }
}

引用和回退

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

其他内存路径

如果要索引默认工作空间布局之外的 Markdown 文件,请添加显式路径:

json5

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

注意:

路径可以是绝对路径或工作空间相对路径。
目录递归扫描 .md 文件。
仅索引 Markdown 文件。
忽略符号链接(文件或目录)。

Gemini 嵌入(原生)

将提供商设置为 gemini 以直接使用 Gemini 嵌入 API:

json5

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 配置:

json5

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

配置示例:

json5

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 令牌目标,80 令牌重叠)。它返回片段文本(限制~700 字符)、文件路径、行范围、分数、提供商/模型,以及我们是否从本地→远程嵌入回退。不返回完整文件负载。
memory_get 读取特定的内存 Markdown 文件(工作空间相对),可选从起始行读取 N 行。拒绝 MEMORY.md / memory/ 之外的路径。
只有当 memorySearch.enabled 对代理解析为 true 时,才启用这两个工具。

索引内容(和时间)

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

混合搜索(BM25 + 向量)

启用后,OpenClaw 结合:

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

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

为什么是混合?

向量搜索擅长"这意味着同样的事情":

"Mac Studio 网关主机" vs "运行网关的机器"
"防抖文件更新" vs "避免在每次写入时索引"

但对于精确、高信号令牌可能较弱:

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

BM25(全文)则相反:擅长精确令牌,对释义较弱。混合搜索是务实的中间方案:使用两种检索信号,因此你可以为"自然语言"查询和"大海捞针"查询获得良好的结果。

我们如何合并结果(当前设计)

实现草图:

从两侧检索候选池:

向量:按余弦相似度排名前 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 分数)。

配置:

json5

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

嵌入缓存

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

配置:

json5

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

会话内存搜索(实验性)

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

json5

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

注意:

会话索引是选择加入(默认关闭)。
会话更新被防抖并在超过增量阈值后异步索引(尽力而为)。
memory_search 从不阻止索引;结果可能略微过时,直到后台同步完成。
结果仍仅包含片段;memory_get 仍限于内存文件。
会话索引按代理隔离(仅索引该代理的会话日志)。
会话日志存储在磁盘上(~/.openclaw/agents/<agentId>/sessions/*.jsonl)。任何具有文件系统访问权限的进程/用户都可以读取它们,因此将磁盘访问视为信任边界。为了更严格的隔离,在单独的操作系统用户或主机下运行代理。

增量阈值(显示默认值):

json5

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

SQLite 向量加速(sqlite-vec)

当 sqlite-vec 扩展可用时,OpenClaw 将嵌入存储在 SQLite 虚拟表(vec0)中,并在数据库中执行向量距离查询。这使搜索保持快速,而无需将每个嵌入加载到 JS 中。

配置(可选):

json5

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 兼容端点示例

json5

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 默认值。

内存 ​

内存文件 (Markdown) ​

何时写入内存 ​

自动内存刷新(预压缩提示) ​

向量内存搜索 ​

QMD 后端(实验性) ​

其他内存路径 ​

Gemini 嵌入(原生) ​

内存工具的工作原理 ​

索引内容(和时间) ​

混合搜索(BM25 + 向量) ​

为什么是混合? ​

我们如何合并结果(当前设计) ​

嵌入缓存 ​

会话内存搜索(实验性) ​

SQLite 向量加速(sqlite-vec) ​

本地嵌入自动下载 ​

自定义 OpenAI 兼容端点示例 ​

内存

内存文件 (Markdown)

何时写入内存

自动内存刷新(预压缩提示)

向量内存搜索

QMD 后端(实验性)

其他内存路径

Gemini 嵌入(原生)

内存工具的工作原理

索引内容(和时间)

混合搜索(BM25 + 向量)

为什么是混合?

我们如何合并结果(当前设计)

嵌入缓存

会话内存搜索(实验性)

SQLite 向量加速(sqlite-vec)

本地嵌入自动下载

自定义 OpenAI 兼容端点示例