OpenClaw从入门到应用——Agent：记忆（Memory）

通过OpenClaw实现副业收入《OpenClaw赚钱实录从“养龙虾“到可持续变现的实践指南》OpenClaw 的记忆是agent 工作区中的纯 Markdown 文件。这些文件是事实来源模型只“记住”写入磁盘的内容。记忆搜索工具由活动的记忆插件提供默认memory-core。使用plugins.slots.memory none禁用记忆插件。记忆文件 (Markdown)默认工作区布局使用两层记忆memory/YYYY-MM-DD.md日常日志仅允许追加。会话开始时读取今天和昨天的日志。MEMORY.md(可选)精挑细选的长期记忆。如果MEMORY.md和memory.md同时存在于工作区根目录OpenClaw 仅加载MEMORY.md。小写的memory.md仅在MEMORY.md不存在时作为后备使用。仅在主要的私有会话中加载绝不在群组上下文中加载。这些文件位于工作区下agents.defaults.workspace默认为~/.openclaw/workspace。完整布局请参阅 Agent 工作区。记忆工具OpenClaw 为这些 Markdown 文件提供了两个面向 agent 的工具memory_search— 对索引片段进行语义召回。memory_get— 针对性地读取特定 Markdown 文件/行范围。memory_get现在在文件不存在时会优雅降级例如首次写入前的日常日志。内置管理器和 QMD 后端都会返回{ text: , path }而不是抛出ENOENT错误这样 agents 就能处理“尚未记录任何内容”的情况并无需将工具调用包装在 try/catch 逻辑中。何时写入记忆决策、偏好和持久性事实写入MEMORY.md。日常笔记和持续上下文写入memory/YYYY-MM-DD.md。如果有人让你“记住这个”就把它写下来不要留在内存中。这个功能仍在发展中。提醒模型存储记忆会有所帮助它会知道该怎么做。如果你想让某些内容被固定下来要求机器人将其写入记忆。自动记忆刷新预压缩提醒当会话接近自动压缩时OpenClaw 会触发一个静默的、agent驱动的回合提醒模型在上下文被压缩之前写入持久性记忆。默认提示明确说明模型可以回复但通常NO_REPLY是正确的响应这样用户就永远不会看到这个回合。这由agents.defaults.compaction.memoryFlush控制{ agents: { defaults: { compaction: { reserveTokensFloor: 20000, memoryFlush: { enabled: true, softThresholdTokens: 4000, systemPrompt: 会话即将压缩。现在存储持久性记忆。, prompt: 将任何持久的笔记写入 memory/YYYY-MM-DD.md如果没有要存储的内容请回复 NO_REPLY。, }, }, }, }, }细节软阈值当会话令牌估计值超过contextWindow - reserveTokensFloor - softThresholdTokens时触发刷新。默认静默提示包含NO_REPLY因此不会传递任何内容。两个提示一个用户提示和一个系统提示附加提醒。每个压缩周期只刷新一次在sessions.json中跟踪。工作区必须是可写的如果会话在沙箱中以workspaceAccess: ro或none运行则跳过刷新。完整的压缩生命周期请参见会话管理 压缩。向量记忆搜索OpenClaw 可以在MEMORY.md和memory/*.md上构建一个小型向量索引这样即使措辞不同语义查询也能找到相关的笔记。默认设置默认启用。监听记忆文件的更改防抖处理。在agents.defaults.memorySearch而不是顶层的memorySearch下配置记忆搜索。默认使用远程嵌入。如果未设置memorySearch.providerOpenClaw 会自动选择如果配置了memorySearch.local.modelPath且文件存在则使用local。如果可以解析到 OpenAI key则使用openai。如果可以解析到 Gemini key则使用gemini。如果可以解析到 Voyage key则使用voyage。如果可以解析到 Mistral key则使用mistral。否则记忆搜索将保持禁用状态直到配置完成。本地模式使用 node-llama-cpp可能需要运行pnpm approve-builds。使用 sqlite-vec可用时加速 SQLite 内的向量搜索。也支持memorySearch.provider ollama用于本地/自托管的 Ollama 嵌入/api/embeddings但不会自动选择。远程嵌入需要嵌入提供方的 API key。OpenClaw 从认证配置文件、models.providers.*.apiKey或环境变量中解析 key。Codex OAuth 仅涵盖聊天/补全不满足记忆搜索的嵌入要求。对于 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 key当本地策略需要时使用一个占位符如OLLAMA_API_KEYollama-local就足够了。当使用自定义的 OpenAI 兼容端点时设置memorySearch.remote.apiKey以及可选的memorySearch.remote.headers。QMD 后端 (实验性)设置memory.backend qmd可以将内置的 SQLite 索引器替换为 QMD一个结合了 BM25 向量 重排序的本地优先搜索辅助程序。Markdown 仍然是事实来源OpenClaw 通过 shell 调用 QMD 进行检索。关键点前置条件默认禁用。按配置选择启用memory.backend qmd。单独安装 QMD CLIbun install -g https://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/下运行一个自包含的 XDG 主目录。操作系统支持一旦安装了 Bun SQLitemacOS 和 Linux 即可直接使用。Windows 最好通过 WSL2 支持。辅助程序如何运行网关在~/.openclaw/agents/agentId/qmd/下写入一个自包含的 QMD 主目录配置 缓存 sqlite 数据库。通过qmd collection add从memory.qmd.paths加上默认工作区记忆文件创建集合然后在启动时和可配置的时间间隔memory.qmd.update.interval默认 5 分钟运行qmd updateqmd embed。网关现在在启动时初始化 QMD 管理器因此即使在第一次memory_search调用之前周期性更新计时器也会被激活。启动刷新现在默认在后台运行因此聊天启动不会被阻塞设置memory.qmd.update.waitForBootSync true以保持先前的阻塞行为。通过memory.qmd.searchMode默认qmd search --json也支持vsearch和query运行搜索。如果所选模式在你的 QMD 版本上不支持某些标志OpenClaw 会使用qmd query重试。如果 QMD 失败或二进制文件缺失OpenClaw 会自动回退到内置的 SQLite 管理器以便记忆工具继续工作。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}exportXDG_CONFIG_HOME$STATE_DIR/agents/main/qmd/xdg-configexportXDG_CACHE_HOME$STATE_DIR/agents/main/qmd/xdg-cache# (可选) 强制刷新索引 嵌入qmd update qmd embed# 预热 / 触发首次模型下载qmd querytest-cmemory-root--json/dev/null21配置面 (memory.qmd.*)command(默认qmd)覆盖可执行文件路径。searchMode(默认search)选择哪个 QMD 命令来支持memory_searchsearch,vsearch,query。includeDefaultMemory(默认true)自动索引MEMORY.mdmemory/**/*.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相同的模式。默认仅为 DM拒绝所有允许直接聊天放宽它以在群组/频道中显示 QMD 结果。match.keyPrefix匹配标准化的会话键小写移除任何前导的agent::。例如discord:channel:。match.rawKeyPrefix匹配原始的会话键小写包括agent::。例如agent:main:discord:。遗留match.keyPrefix: agent:...仍被视为原始键前缀但为了清晰推荐使用rawKeyPrefix。当scope拒绝搜索时OpenClaw 会记录一个包含派生出的channel/chatType的警告以便更容易调试空结果。来源于工作区之外的片段在memory_search结果中显示为qmd://collection/pathmemory_get能够理解此前缀并从配置的 QMD 集合根目录读取。当memory.qmd.sessions.enabled true时OpenClaw 将清理过的会话记录用户/助手对话轮次导出到~/.openclaw/agents/agentId/qmd/sessions/下的专用 QMD 集合中以便memory_search能够召回最近的对话而不影响内置的 SQLite 索引。当memory.citations设置为auto/on时memory_search片段现在包含一个来源页脚设置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::。 { action: deny, match: { keyPrefix: discord:channel: } }, // 原始的会话键前缀包括 agent::。 { 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 恢复。额外的记忆路径如果你想索引默认工作区布局之外的 Markdown 文件请添加明确的路径agents: { defaults: { memorySearch: { extraPaths: [../team-docs, /srv/shared-notes/overview.md] } } }注意路径可以是绝对路径或相对于工作区的路径。目录会被递归扫描以查找.md文件。默认情况下仅索引 Markdown 文件。如果memorySearch.multimodal.enabled trueOpenClaw 还会在extraPaths下索引支持的图像/音频文件。默认的记忆根目录MEMORY.md,memory.md,memory/**/*.md仍然是纯 Markdown。符号链接会被忽略文件或目录。多模态记忆文件 (Gemini 图像 音频)当使用 Gemini embedding 2 时OpenClaw 可以从memorySearch.extraPaths索引图像和音频文件agents: { defaults: { memorySearch: { provider: gemini, model: gemini-embedding-2-preview, extraPaths: [assets/reference, voice-notes], multimodal: { enabled: true, modalities: [image, audio], // 或 [all] maxFileBytes: 10000000 }, remote: { apiKey: 你的_GEMINI_API_KEY } } } }注意多模态记忆目前仅支持gemini-embedding-2-preview。多模态索引仅适用于通过memorySearch.extraPaths发现的文件。此阶段支持的模态图像和音频。当启用多模态记忆时memorySearch.fallback必须保持为none。匹配的图像/音频文件字节在索引期间会上传到配置的 Gemini 嵌入端点。支持的图像扩展名.jpg,.jpeg,.png,.webp,.gif,.heic,.heif。支持的音频扩展名.mp3,.wav,.ogg,.opus,.m4a,.aac,.flac。搜索查询仍然是文本但 Gemini 可以将这些文本查询与索引的图像/音频嵌入进行比较。memory_get仍然只读取 Markdown二进制文件是可搜索的但不会作为原始文件内容返回。Gemini 嵌入 (原生)将提供方设置为gemini以直接使用 Gemini 嵌入 APIagents: { defaults: { memorySearch: { provider: gemini, model: gemini-embedding-001, remote: { apiKey: 你的_GEMINI_API_KEY } } } }注意remote.baseUrl是可选的默认为 Gemini API 基础 URL。remote.headers允许你在需要时添加额外的头部。默认模型gemini-embedding-001。也支持gemini-embedding-2-preview8192 令牌限制和可配置维度768 / 1536 / 3072默认 3072。Gemini Embedding 2 (预览版)agents: { defaults: { memorySearch: { provider: gemini, model: gemini-embedding-2-preview, outputDimensionality: 3072, // 可选: 768, 1536, 或 3072 (默认) remote: { apiKey: 你的_GEMINI_API_KEY } } } }⚠️ 需要重新索引从gemini-embedding-001768 维切换到gemini-embedding-2-preview3072 维会改变向量大小。如果你在 768、1536 和 3072 之间更改outputDimensionality情况也是如此。当 OpenClaw 检测到模型或维度更改时它会自动重新索引。如果你想使用自定义的 OpenAI 兼容端点OpenRouter、vLLM 或代理你可以将remote配置与 OpenAI 提供方一起使用agents: { defaults: { memorySearch: { provider: openai, model: text-embedding-3-small, remote: { baseUrl: https://api.example.com/v1/, apiKey: 你的_OPENAI_COMPAT_API_KEY, headers: { X-Custom-Header: value } } } } }如果你不想设置 API key请使用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 key。Gemini 批处理作业使用异步嵌入批处理端点需要 Gemini Batch API 的可用性。为什么 OpenAI 批处理既快又便宜对于大量回填OpenAI 通常是我们支持的最快选项因为我们可以在单个批处理作业中提交许多嵌入请求并让 OpenAI 异步处理它们。OpenAI 为批处理 API 工作负载提供折扣定价因此大规模索引运行通常比同步发送相同请求更便宜。有关详细信息请参阅 OpenAI 批处理 API 文档和定价https://platform.openai.com/docs/api-reference/batchhttps://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.modelPathGGUF 或hf:URI。可选设置agents.defaults.memorySearch.fallback none以避免远程回退。记忆工具如何工作memory_search从MEMORY.mdmemory/**/*.md中语义搜索 Markdown 块目标 ~400 令牌80 令牌重叠。它返回片段文本上限 ~700 字符、文件路径、行范围、分数、提供方/模型以及我们是否从本地嵌入回退到了远程嵌入。不返回完整的文件负载。memory_get读取特定的记忆 Markdown 文件相对于工作区可选地从起始行开始读取 N 行。拒绝MEMORY.md/memory/之外的路径。仅当memorySearch.enabled对 agent 解析为 true 时这两个工具才启用。索引的内容和时机文件类型仅 MarkdownMEMORY.md,memory/**/*.md。索引存储每个 agent 的 SQLite 数据库位于~/.openclaw/memory/.sqlite可通过agents.defaults.memorySearch.store.path配置支持{agentId}令牌。新鲜度MEMORY.mdmemory/上的监视器将索引标记为脏防抖 1.5 秒。同步在会话启动时、搜索时或按时间间隔调度并异步运行。会话记录使用增量阈值触发后台同步。重新索引触发索引存储嵌入提供方/模型 端点指纹 分块参数。如果其中任何一项发生变化OpenClaw 会自动重置并重新索引整个存储。混合搜索 (BM25 向量)启用后OpenClaw 结合向量相似度语义匹配措辞可以不同BM25 关键词相关性精确令牌如 ID、环境变量、代码符号如果你的平台上无法使用全文搜索OpenClaw 会回退到纯向量搜索。为什么选择混合向量搜索擅长于“含义相同”的匹配“Mac Studio 网关主机” vs “运行网关的机器”“对文件更新进行防抖” vs “避免每次写入都索引”但它在精确、高信号令牌上可能较弱IDs (a828e60,b3b9895a…)代码符号 (memorySearch.query.hybrid)错误字符串 (“sqlite-vec unavailable”)BM25全文则相反擅长精确令牌在释义上较弱。混合搜索是务实的中庸之道同时使用两种检索信号这样你就能在“自然语言”查询和“大海捞针”查询上都获得良好结果。我们如何合并结果当前设计实现草图从两边检索候选集向量按余弦相似度排序的前maxResults * candidateMultiplier个结果。BM25按 FTS5 BM25 排名越小越好排序的前maxResults * candidateMultiplier个结果。将 BM25 排名转换为 0…1 左右的分数textScore 1 / (1 max(0, bm25Rank))按块 ID 合并候选集并计算加权分数finalScore vectorWeight * vectorScore textWeight * textScore注意vectorWeighttextWeight在配置解析中被归一化为 1.0因此权重表现为百分比。如果嵌入不可用或提供方返回零向量我们仍然运行 BM25 并返回关键词匹配结果。如果无法创建 FTS5我们保持纯向量搜索不会硬失败。这不是“完美的信息检索理论”但它简单、快速并且倾向于提高真实笔记的召回率/精确度。如果我们以后想做得更复杂常见的下一步是在混合之前使用倒数排名融合RRF或分数归一化最小/最大或 z-score。后处理流程合并向量和关键词分数后两个可选的后处理阶段会在结果到达 agent 之前对其进行细化向量 关键词 → 加权合并 → 时间衰减 → 排序 → MMR → 前K个结果这两个阶段默认都是关闭的可以独立启用。MMR 重排序多样性当混合搜索返回结果时多个块可能包含相似或重叠的内容。例如搜索“家庭网络设置”可能会从不同的日常笔记中返回五个几乎相同的片段它们都提到了相同的路由器配置。MMR最大边际相关性重新排列结果以平衡相关性和多样性确保最靠前的结果涵盖查询的不同方面而不是重复相同的信息。工作原理结果按其原始相关性向量 BM25 加权分数评分。MMR 迭代选择结果以最大化λ × 相关性 − (1−λ) × 与已选结果的最大相似度。结果之间的相似度使用对 token 化内容的 Jaccard 文本相似度来衡量。lambda参数控制权衡lambda 1.0→ 纯相关性无多样性惩罚lambda 0.0→ 最大多样性忽略相关性默认0.7平衡略微偏向相关性示例 — 查询“家庭网络设置”给定这些记忆文件memory/2026-02-10.md → “配置了 Omada 路由器为物联网设备设置 VLAN 10” memory/2026-02-08.md → “配置了 Omada 路由器将物联网设备移至 VLAN 10” memory/2026-02-05.md → “在 192.168.10.2 上设置 AdGuard DNS” memory/network.md → “路由器Omada ER605AdGuard192.168.10.2VLAN 10物联网”不使用 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返回冗余或近乎重复的片段尤其是在日常笔记中这些笔记经常在不同日期重复类似信息。时间衰减新鲜度提升拥有日常笔记的 agents 会随时间积累数百个带日期的文件。如果没有衰减六个月前措辞良好的笔记在相同主题上可能比昨天的更新排名更高。时间衰减根据每个结果的存在时间应用指数乘数因此最近的记忆自然地排名更高而旧的记忆逐渐淡出decayedScore score × e^(-λ × ageInDays)其中λ ln(2) / halfLifeDays。使用默认的半衰期 30 天今天的笔记100%的原始分数7 天前~84%30 天前50%90 天前12.5%180 天前~1.6%永久文件从不衰减MEMORY.md根记忆文件memory/中非日期的文件例如memory/projects.md,memory/network.md这些文件包含持久的参考信息应该始终正常排名。带日期的日常文件memory/YYYY-MM-DD.md使用从文件名中提取的日期。其他来源例如会话记录回退到文件修改时间mtime。示例 — 查询“Rod 的工作时间表是怎样的”给定这些记忆文件今天是 2 月 10 日memory/2025-09-15.md → “Rod 工作时间为周一至周五早上 10 点站会下午 2 点结对” (148 天前) memory/2026-02-10.md → “Rod 下午 2:15 开站会下午 2:45 与 Zeb 进行 1对1” (今天) memory/2026-02-03.md → “Rod 开始新团队站会移至下午 2: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 最大相关性 }, // 新鲜度提升较新的记忆 temporalDecay: { enabled: true, // 默认: false halfLifeDays: 30 // 每30天分数减半 } } } } } }你可以独立启用任一特性仅 MMR— 当你有很多相似的笔记但时间不重要时很有用。仅时间衰减— 当新鲜度很重要但你的结果已经多样化时很有用。两者都启用— 推荐用于拥有大量、长期运行的日常笔记历史的 agents。嵌入缓存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。任何具有文件系统访问权限的进程/用户都可以读取它们因此请将磁盘访问视为信任边界。为了更严格的隔离请在单独的操作系统用户或主机下运行 agents。增量阈值显示默认值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: