当前位置： 首页 > news >正文

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

news 2026/4/25 10:52:25

通过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.provider，OpenClaw 会自动选择：
    1. 如果配置了memorySearch.local.modelPath且文件存在，则使用local。
    2. 如果可以解析到 OpenAI key，则使用openai。
    3. 如果可以解析到 Gemini key，则使用gemini。
    4. 如果可以解析到 Voyage key，则使用voyage。
    5. 如果可以解析到 Mistral key，则使用mistral。
    6. 否则记忆搜索将保持禁用状态，直到配置完成。
  • 本地模式使用 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_KEY=ollama-local就足够了）。
当使用自定义的 OpenAI 兼容端点时，设置memorySearch.remote.apiKey（以及可选的memorySearch.remote.headers）。

QMD 后端 (实验性)

设置memory.backend = "qmd"可以将内置的 SQLite 索引器替换为 QMD：一个结合了 BM25 + 向量 + 重排序的本地优先搜索辅助程序。Markdown 仍然是事实来源；OpenClaw 通过 shell 调用 QMD 进行检索。关键点：

前置条件

  • 默认禁用。按配置选择启用（memory.backend = "qmd"）。
  • 单独安装 QMD CLI（bun 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 + SQLite，macOS 和 Linux 即可直接使用。Windows 最好通过 WSL2 支持。

辅助程序如何运行

  • 网关在~/.openclaw/agents/<agentId>/qmd/下写入一个自包含的 QMD 主目录（配置 + 缓存 + sqlite 数据库）。
  • 通过qmd collection add从memory.qmd.paths（加上默认工作区记忆文件）创建集合，然后在启动时和可配置的时间间隔（memory.qmd.update.interval，默认 5 分钟）运行qmd update+qmd 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-config"exportXDG_CACHE_HOME="$STATE_DIR/agents/main/qmd/xdg-cache"# (可选) 强制刷新索引 + 嵌入qmd update qmd embed# 预热 / 触发首次模型下载qmd query"test"-cmemory-root--json>/dev/null2>&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相同的模式。
    默认仅为 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>/<path>；memory_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 = true，OpenClaw 还会在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 嵌入 API：

agents: { 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-preview：8192 令牌限制和可配置维度（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-001（768 维）切换到gemini-embedding-2-preview（3072 维）会改变向量大小。如果你在 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/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 令牌，80 令牌重叠）。它返回片段文本（上限 ~700 字符）、文件路径、行范围、分数、提供方/模型，以及我们是否从本地嵌入回退到了远程嵌入。不返回完整的文件负载。
  • memory_get读取特定的记忆 Markdown 文件（相对于工作区），可选地从起始行开始读取 N 行。拒绝MEMORY.md/memory/之外的路径。
  • 仅当memorySearch.enabled对 agent 解析为 true 时，这两个工具才启用。

索引的内容（和时机）

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

混合搜索 (BM25 + 向量)

启用后，OpenClaw 结合：

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

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

为什么选择混合？

向量搜索擅长于“含义相同”的匹配：

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

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

  • IDs (a828e60,b3b9895a…)
  • 代码符号 (memorySearch.query.hybrid)
  • 错误字符串 (“sqlite-vec unavailable”)

BM25（全文）则相反：擅长精确令牌，在释义上较弱。
混合搜索是务实的中庸之道：同时使用两种检索信号，这样你就能在“自然语言”查询和“大海捞针”查询上都获得良好结果。

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

实现草图：

  1. 从两边检索候选集：
  • 向量：按余弦相似度排序的前maxResults * candidateMultiplier个结果。
  • BM25：按 FTS5 BM25 排名（越小越好）排序的前maxResults * candidateMultiplier个结果。
  1. 将 BM25 排名转换为 0…1 左右的分数：
  • textScore = 1 / (1 + max(0, bm25Rank))
  1. 按块 ID 合并候选集并计算加权分数：
  • finalScore = vectorWeight * vectorScore + textWeight * textScore

注意：

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

这不是“完美的信息检索理论”，但它简单、快速，并且倾向于提高真实笔记的召回率/精确度。
如果我们以后想做得更复杂，常见的下一步是在混合之前使用倒数排名融合（RRF）或分数归一化（最小/最大或 z-score）。

后处理流程

合并向量和关键词分数后，两个可选的后处理阶段会在结果到达 agent 之前对其进行细化：

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

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

MMR 重排序（多样性）

当混合搜索返回结果时，多个块可能包含相似或重叠的内容。
例如，搜索“家庭网络设置”可能会从不同的日常笔记中返回五个几乎相同的片段，它们都提到了相同的路由器配置。

MMR（最大边际相关性）重新排列结果，以平衡相关性和多样性，
确保最靠前的结果涵盖查询的不同方面，而不是重复相同的信息。

工作原理：

  1. 结果按其原始相关性（向量 + BM25 加权分数）评分。
  2. MMR 迭代选择结果，以最大化：λ × 相关性 − (1−λ) × 与已选结果的最大相似度。
  3. 结果之间的相似度使用对 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 ER605，AdGuard：192.168.10.2，VLAN 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:
http://www.jsqmd.com/news/697533/

相关文章：

  • 炉石传说脚本终极指南：5分钟实现游戏自动化解放双手
  • 淘宝API限流应对策略：令牌桶算法+指数退避的优雅降级方案
  • 总结储备型应急包优质厂家，口碑好的是哪几家？ - 工业推荐榜
  • 别再死记硬背了！用Markdown笔记整理对数公式，效率翻倍（附LaTeX语法模板）
  • Bebas Neue字体架构解析：开源几何无衬线字体的技术实现与工程哲学
  • Python asyncio 调度机制性能优化
  • Ahk2Exe实战指南：AutoHotkey脚本编译与EXE转换深度解析
  • Rust的#[derive(Hash, PartialEq, Eq)]派生宏
  • 不止于部署：给你的File Browser (v2.27.0) 加上Nginx反向代理和HTTPS，打造安全私有的文件共享站
  • 别再瞎调参数了！手把手教你用PCL的MLS上采样，让稀疏点云瞬间‘丰满’起来
  • 别再只会用OpenCV了！用Pillow给Python新手准备的5个图像处理小项目（附完整代码）
  • 如何在Windows 11上完美运行DirectX 1-7经典游戏：DDrawCompat终极兼容方案
  • STM32H7的MPU实战：用内存保护单元给你的代码加把锁，防止数组越界和野指针
  • 2026年台州GEO优化服务商行业分析与3家主流机构选型参考 - 商业小白条
  • Skillz框架：从AI技能到智能体的工程化构建指南
  • 通过阿里云百炼平台调用DeepSeek大模型
  • 如何彻底解决AutoCAD字体缺失问题：FontCenter字体管理神器完整指南
  • 手把手教你用rEFInd解决Ubuntu和Windows双系统引导混乱问题（附.conf文件配置详解）
  • 使用 MATLAB 实现支持向量回归 (SVR) 预测未来数据
  • 2026届必备的五大降AI率网站实测分析
  • 别再死记硬背了！用Python的SymPy库5分钟搞定有理函数积分（附完整代码）
  • 提高私域转化率：如何通过 API 自动发送小程序卡片？
  • 实战指南：如何构建企业级金融数据采集框架的7个核心场景
  • 淘宝商品类目属性获取：叶子类目与属性值的递归采集方案
  • 3个智能功能彻底改变你的英雄联盟游戏体验
  • 我们为什么从Hadoop转向了Spark和Flink？
  • C++编写MCP网关必须绕开的8个STL陷阱（std::string隐式分配、std::shared_ptr引用计数竞争、std::function类型擦除开销实测对比）
  • 基于 Jenkins 搭建一套 CI/CD 系统！
  • 别再手动跑审批了！用Flowable工作流5分钟搞定一个发工资流程（附完整Java代码）
  • 解锁AMD Ryzen处理器潜能：免费开源工具SMUDebugTool终极指南