记忆配置参考

此页面列出了 OpenClaw 记忆搜索的所有配置项。有关概念性概览，请参阅：

• 记忆概览：记忆的工作原理。
• 内置引擎：默认 SQLite 后端。
• QMD 引擎：本地优先的边车服务。
• 记忆搜索：搜索流程和调优。
• 主动记忆：用于交互式会话的记忆子智能体。

所有共享记忆设置都位于 openclaw.json 的顶层 memory 下。搜索默认值使用 memory.search；每个智能体的搜索覆盖项使用 agents.entries.*.memory.search。

跨对话记忆

如果只有受信任的个人智能体应使用跨对话的记录回忆，请为该智能体配置：

{
  agents: {
    entries: {
      personal: {
        memory: {
          search: {
            rememberAcrossConversations: true,
          },
        },
      },
    },
  },
}

该值遵循常规 memory.search 继承规则，并可按智能体覆盖。未设置时，仅当全局 session.dmScope 未设置或为 "main"，且没有任何绑定包含 session.dmScope 覆盖项时，才默认开启。配置任何私信隔离都会使其默认关闭。显式设置的 true 或 false 始终优先。启用此设置意味着为会话记录建立索引，并将 sessions 添加到智能体解析后的记忆来源中。使用 QMD 时，还会启用该智能体的会话导出；此模式不需要单独配置 memory.qmd.sessions.enabled。

OpenClaw 的内置记忆提供商通过内置和 QMD 后端支持此受保护路径。其他记忆提供商仍可使用其自身的回忆钩子和高级主动记忆工具，但除非当前提供商支持受保护的私密记录回忆，否则会跳过此设置。 openclaw doctor 会报告不受支持的提供商，或报告显式主动记忆 toolsAllow 列表遗漏了 memory_search。

此检索边界比常规会话搜索更窄：

• 只有同一智能体已识别的私密对话才符合条件
• 排除当前正在回复的对话
• 群组和频道均不能作为来源或目标
• 遇到未知对话类型时以关闭状态失败
• 沙箱隔离的回忆无法使用特殊的跨对话授权

此设置不会更改 tools.sessions.visibility、会话键、记录存储、投递路由，也不会更改 sessions_list、sessions_history 和 sessions_send 的权限。主动记忆会执行有界的只读检索过程；检索不可用或超时不会阻止回复。

提供商选择

未设置 provider 时，OpenClaw 使用 OpenAI 嵌入。显式设置 provider 以使用 Bedrock、DeepInfra、Gemini、GitHub Copilot、Mistral、Ollama、Voyage、本地 GGUF 模型或兼容 OpenAI 的 /v1/embeddings 端点。 仍使用 provider: "auto" 的旧版配置会解析为 openai。

当 provider 未设置、存在旧版 provider: "auto"，或 provider: "none" 有意选择仅 FTS 模式时，嵌入不可用的情况下，记忆回忆仍可使用词法 FTS 排序。

显式指定的非本地提供商会以关闭状态失败。如果将 memory.search.provider 设置为具体的远程后端提供商，例如 Bedrock、DeepInfra、Gemini、GitHub Copilot、LM Studio、Mistral、Ollama、OpenAI、Voyage 或兼容 OpenAI 的自定义提供商，而该提供商在运行时不可用，则 memory_search 会返回不可用结果，而不会静默改用仅 FTS 回忆。请修复提供商或身份验证配置、切换到可访问的提供商，或者如果希望有意使用仅 FTS 回忆，请设置 provider: "none"。

自定义提供商 ID

memory.search.provider 可以指向自定义 models.providers.<id> 条目，用于 ollama 等记忆专用提供商适配器，或 openai-responses / openai-completions 等兼容 OpenAI 的模型 API。OpenClaw 会为嵌入适配器解析该提供商的 api 所有者，同时保留自定义提供商 ID，以便处理端点、身份验证和模型前缀。这样，多 GPU 或多主机设置就能将记忆嵌入专用于特定本地端点：

{
  models: {
    providers: {
      "ollama-5080": {
        api: "ollama",
        baseUrl: "http://gpu-box.local:11435",
        apiKey: "ollama-local",
        models: [{ id: "qwen3-embedding:0.6b", name: "Qwen3 Embedding 0.6B" }],
      },
    },
  },
  memory: {
    search: {
      provider: "ollama-5080",
      model: "qwen3-embedding:0.6b",
    },
  },
}

API 密钥解析

远程嵌入需要 API 密钥。Bedrock 则使用 AWS SDK 默认凭证链（实例角色、SSO、访问密钥或 Bedrock API 密钥）。

远程端点配置

对于不应继承全局 OpenAI 聊天凭证的通用兼容 OpenAI 的 /v1/embeddings 服务器，请使用 provider: "openai-compatible"。

自定义 API 基础 URL。

覆盖 API 密钥。

额外的 HTTP 标头（与提供商默认值合并）。

{
  memory: {
    search: {
      provider: "openai-compatible",
      model: "text-embedding-3-small",
      remote: {
        baseUrl: "https://api.example.com/v1/",
        apiKey: "YOUR_KEY",
      },
    },
  },
}

提供商特定配置

{
  memory: {
    search: {
      provider: "openai-compatible",
      remote: {
        baseUrl: "https://embeddings.example/v1",
        apiKey: "${EMBEDDINGS_API_KEY}",
      },
      model: "asymmetric-embedder",
      queryInputType: "query",
      documentInputType: "passage",
    },
  },
}

{
  memory: {
    search: {
      provider: "bedrock",
      model: "amazon.titan-embed-text-v2:0",
    },
  },
}

{
  "Effect": "Allow",
  "Action": "bedrock:InvokeModel",
  "Resource": "*"
}

arn:aws:bedrock:*::foundation-model/amazon.titan-embed-text-v2:0

openclaw memory status --deep --agent main
openclaw memory index --force --agent main

索引行为

记忆引擎负责同步、批处理、监视以及压缩后的 索引启发式策略。OpenClaw 使用持续维护的默认值启用这些行为， 而不会公开按安装实例设置的时序开关。

混合搜索配置

以下各项均位于 memory.search.query 下：

混合检索保持启用；内置引擎策略仍会禁用 MMR 和时间衰减。

完整示例

{
  memory: {
    search: {
      query: {
        maxResults: 6,
        minScore: 0.35,
      },
    },
  },
}

其他记忆路径

{
  memory: {
    search: {
      extraPaths: ["../team-docs", "/srv/shared-notes"],
    },
  },
}

路径可以是绝对路径，也可以相对于工作区。系统会递归扫描目录中的 .md 文件。符号链接的处理方式取决于当前后端：内置引擎会跳过符号链接，而 QMD 则遵循底层 QMD 扫描器的行为。

对于 Agent 范围内的跨 Agent 记录搜索，请使用 agents.entries.*.memory.search.qmd.extraCollections，而不是 memory.qmd.paths。这些额外集合遵循相同的 { path, name, pattern? } 结构，但它们会按 Agent 合并；当路径指向当前工作区之外时，还可以保留显式共享名称。如果同一解析路径同时出现在 memory.qmd.paths 和 memory.search.qmd.extraCollections 中，QMD 会保留第一个条目并跳过重复项。

多模态记忆（Gemini）

使用 Gemini Embedding 2 将图像和音频与 Markdown 一同索引：

支持的格式：.jpg、.jpeg、.png、.webp、.gif、.heic、.heif（图像）；.mp3、.wav、.ogg、.opus、.m4a、.aac、.flac（音频）。

嵌入缓存

避免在重新索引或更新记录期间对未更改的文本重复生成嵌入。

批量索引

适用于 gemini、openai 和 voyage。对于大规模回填，OpenAI 批处理通常速度最快且成本最低。

并发、轮询和超时行为由提供商负责。

会话记忆搜索

索引会话记录，并通过 memory_search 提供：

由模型调用的普通会话记录搜索遵循 tools.sessions.visibility。默认的 tree 可见性会公开当前会话、由其派生的会话，以及 通过环境群组感知功能监视的同一智能体群组会话。其他 不相关的会话需要 agent 可见性（仅当还需要跨智能体 回忆，并且智能体间策略允许时，才需要 all 可见性）。

rememberAcrossConversations 不会扩大该设置的范围。它提供一项 仅限运行时的独立授权，在有界的主动记忆处理过程中，仅允许访问同一智能体的私有 会话记录。

以下示例将这些设置放在顶层 memory.search 下。如果只有一个 智能体应索引和搜索会话记录，也可以在该智能体的 memory.search 覆盖配置中 应用等效设置。

对于同一智能体从 Gateway 网关到私信的回忆：

内置后端

{
  memory: {
    search: {
      experimental: { sessionMemory: true },
      sources: ["memory", "sessions"],
    },
  },
  tools: {
    sessions: { visibility: "agent" },
  },
}

QMD 后端

{
  memory: {
    backend: "qmd",
    search: {
      experimental: { sessionMemory: true },
      sources: ["memory", "sessions"],
    },
    qmd: {
      sessions: { enabled: true },
    },
  },
  tools: {
    sessions: { visibility: "agent" },
  },
}

使用 QMD 时，仅设置 sources: ["sessions"] 不会将会话记录导出到 QMD。还需设置 memory.qmd.sessions.enabled: true。更高层级的 rememberAcrossConversations: true 设置是例外：它隐含启用该智能体所需的 QMD 会话导出。隐含导出始终保持私有： 它们始终使用默认的内部导出位置（配置的 sessions.exportDir 仅适用于显式导出），仅在该智能体进行跨对话回忆时 被搜索，并且普通的 memory_get 无法读取它们。显式设置 memory.qmd.sessions.enabled: true 会保持其现有行为，使 导出的会话记录成为普通记忆语料库的一部分。

SQLite 向量加速（sqlite-vec）

当 sqlite-vec 不可用时，OpenClaw 会自动回退到进程内余弦相似度计算。

索引存储

内置记忆索引存储在每个智能体的 OpenClaw SQLite 数据库中，路径为 agents/<agentId>/agent/openclaw-agent.sqlite。

QMD 后端配置

将 memory.backend = "qmd" 设为启用。所有 QMD 设置均位于 memory.qmd 下：

searchMode: "search" 仅使用词法/BM25。在该模式下，OpenClaw 不会运行语义向量就绪探测或 QMD 嵌入维护，包括在 memory status --deep 期间；vsearch 和 query 仍然要求 QMD 向量就绪并具备嵌入。

rerank: false 仅更改 QMD 的 query 模式，并要求 QMD 2.1 或更高版本。在直接 CLI 模式下，OpenClaw 会传递 --no-rerank；在由 mcporter 支持的 MCP 模式下，它会将 rerank: false 传递给 QMD 的统一查询工具。保持未设置即可使用 QMD 默认的查询重排序行为。

OpenClaw 优先使用当前的 QMD 集合和 MCP 查询结构，但会在需要时尝试兼容的集合模式标志和旧版 MCP 工具名称，以保持旧版 QMD 可用。当 QMD 声明支持多个集合筛选器时，同源集合会由一个 QMD 进程搜索；旧版 QMD 构建仍使用按集合处理的兼容路径。“同源”是指持久记忆集合（默认记忆文件加自定义路径）会被分为一组，而会话记录集合仍作为单独的一组，以便来源多样化仍可同时使用这两类输入。

{
  memory: {
    qmd: {
      scope: {
        default: "deny",
        rules: [{ action: "allow", match: { chatType: "direct" } }],
      },
    },
  },
}

QMD 在首次使用记忆时延迟初始化；其适配器负责刷新和嵌入调度。

完整 QMD 示例

{
  memory: {
    backend: "qmd",
    citations: "auto",
    qmd: {
      includeDefaultMemory: true,
      update: { interval: "5m", debounceMs: 15000 },
      limits: { maxResults: 4, timeoutMs: 4000 },
      scope: {
        default: "deny",
        rules: [{ action: "allow", match: { chatType: "direct" } }],
      },
      paths: [{ name: "docs", path: "~/notes", pattern: "**/*.md" }],
    },
  },
}

Dreaming

Dreaming 配置在 plugins.entries.memory-core.config.dreaming 下，而不是 memory.search 下。

Dreaming 作为一次定时扫描运行，并将内部的轻度/深度/REM 阶段作为实现细节。

有关概念行为和斜杠命令，请参阅 Dreaming。

用户设置

示例

{
  plugins: {
    entries: {
      "memory-core": {
        subagent: {
          allowModelOverride: true,
          allowedModels: ["anthropic/claude-sonnet-4-6"],
        },
        config: {
          dreaming: {
            enabled: true,
            frequency: "0 3 * * *",
            model: "anthropic/claude-sonnet-4-6",
          },
        },
      },
    },
  },
}

相关内容

• 配置参考
• 记忆概览
• 记忆搜索