记忆配置参考

本页列出 OpenClaw 记忆搜索的每一个配置开关。概念概览请参阅：

除非另有说明，所有记忆搜索设置都位于 openclaw.json 的 agents.defaults.memorySearch 下。

# 提供商选择

# 自动检测顺序

未设置 provider 时，OpenClaw 会选择第一个可用项：

支持 ollama，但不会自动检测（请显式设置）。

# 自定义提供商 ID

memorySearch.provider 可以指向自定义 models.providers.<id> 条目。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" }],
      },
    },
  },
  agents: {
    defaults: {
      memorySearch: {
        provider: "ollama-5080",
        model: "qwen3-embedding:0.6b",
      },
    },
  },
}

# API 密钥解析

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

# 远程端点配置

用于自定义 OpenAI 兼容端点或覆盖提供商默认值：

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

# 提供商特定配置

{
  agents: {
    defaults: {
      memorySearch: {
        provider: "openai",
        remote: {
          baseUrl: "https://embeddings.example/v1",
          apiKey: "env:EMBEDDINGS_API_KEY",
        },
        model: "asymmetric-embedder",
        queryInputType: "query",
        documentInputType: "passage",
      },
    },
  },
}

{
  agents: {
    defaults: {
      memorySearch: {
        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

# 内联嵌入超时

# 混合搜索配置

全部位于 memorySearch.query.hybrid 下：

# 完整示例

{
  agents: {
    defaults: {
      memorySearch: {
        query: {
          hybrid: {
            vectorWeight: 0.7,
            textWeight: 0.3,
            mmr: { enabled: true, lambda: 0.7 },
            temporalDecay: { enabled: true, halfLifeDays: 30 },
          },
        },
      },
    },
  },
}

# 其他记忆路径

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

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

对于按智能体限定的跨智能体 transcript 搜索，请使用 agents.list[].memorySearch.qmd.extraCollections，而不是 memory.qmd.paths。这些额外集合遵循相同的 { path, name, pattern? } 结构，但它们会按智能体合并，并且当路径指向当前工作区外部时，可以保留显式共享名称。如果同一个已解析路径同时出现在 memory.qmd.paths 和 memorySearch.qmd.extraCollections 中，QMD 会保留第一个条目并跳过重复项。

# 多模态记忆（Gemini）

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

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

# 嵌入缓存

在重新索引或转录更新期间，防止对未更改的文本重新生成嵌入。

# 批量索引

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

remote.nonBatchConcurrency 控制本地/自托管提供商使用的内联嵌入调用，以及提供商批处理 API 未启用时托管提供商使用的内联嵌入调用。Ollama 在非批量索引时默认值为 1，以避免压垮较小的本地主机；在更大的机器上可设置更高的值。

这与 sync.embeddingBatchTimeoutSeconds 分开，后者控制内联嵌入调用的超时时间。

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

索引会话转录，并通过 memory_search 展示：

# SQLite 向量加速（sqlite-vec）

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

# 索引存储

# QMD 后端配置

设置 memory.backend = "qmd" 以启用。所有 QMD 设置都位于 memory.qmd 下：

searchMode: "search" 仅使用词法/BM25。OpenClaw 不会为该模式运行语义向量就绪探测或 QMD embedding 维护，包括执行 memory status --deep 时；vsearch 和 query 仍然要求 QMD 向量就绪和 embeddings。

OpenClaw 优先使用当前的 QMD collection 和 MCP 查询形态，但会在需要时尝试兼容的 collection pattern 标志和较旧的 MCP 工具名称，以保持较旧的 QMD 版本可用。当 QMD 声明支持多个 collection 过滤器时，同源 collection 会使用一个 QMD 进程进行搜索；较旧的 QMD 构建仍使用逐 collection 的兼容路径。同源意味着持久化记忆 collection 会分组在一起，而会话 transcript collection 仍保持为单独分组，因此来源多样化仍然同时包含两类输入。

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

QMD 启动刷新会在 Gateway 网关启动期间使用一次性子进程路径。当记忆搜索为交互式使用而打开时，长驻 QMD 管理器仍负责常规文件 watcher 和间隔 timer。

# 完整 QMD 示例

{
  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" }],
    },
  },
}

# Dreaming

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

Dreaming 作为一次定时 sweep 运行，并使用内部 light/deep/REM 阶段作为实现细节。

关于概念行为和 slash commands，请参阅 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",
          },
        },
      },
    },
  },
}

# 相关

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