记忆配置

本页列出 OpenClaw 记忆搜索的所有配置项。概念概览请参见：

记忆概览

记忆如何工作。

内置引擎

默认 SQLite 后端。

记忆搜索

搜索流程和调优。

Active Memory

用于交互式会话的记忆子代理。

所有共享记忆设置都位于 openclaw.json 中的顶级 memory 下。搜索默认值使用 memory.search；按代理的搜索覆盖使用 agents.entries.*.memory.search。

跨对话记忆¶

当只有受信任的个人代理应使用跨对话转录召回时，请为每个代理单独配置：

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

该值遵循常规的 memory.search 继承，并支持按代理覆盖。未设置时，只有当全局 session.dmScope 未设置或为 "main"，且没有任何绑定具有 session.dmScope 覆盖时，它才默认开启。任何已配置的 DM 隔离都会使其默认关闭。显式的 true 或 false 始终优先。启用它会隐含启用会话转录索引，并将 sessions 添加到该代理解析后的记忆来源中。

OpenClaw 的内置记忆提供商支持此受保护路径。其他记忆提供商可以继续保留自己的 召回钩子和高级 Active Memory 工具，但如果当前提供商不支持受保护的私有转录召回， 则会跳过此设置。 openclaw doctor 会报告不受支持的提供商，或显式 Active Memory toolsAllow 列表中遗漏了 memory_search 的情况。

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

• 仅同一代理的已识别私有对话符合条件
• 正在回答的对话会被排除
• 群组和频道作为来源和目标均被排除
• 未知对话类型会失败关闭
• 沙箱化召回不能使用特殊的跨对话授权

该设置不会更改 tools.sessions.visibility、会话密钥、 转录存储、投递路由，或 sessions_list、 sessions_history 和 sessions_send 的权限。Active Memory 执行一次有界的 只读检索；检索不可用或超时时不会阻塞回复。

提供商选择¶

当未设置 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 兼容模型 API（例如 openai-responses / openai-completions）。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 兼容提供商，models.providers.<id>.apiKey 可以指定使用 openclaw models auth 保存的 API 密钥或 bearer-token 配置文件，例如 my-embeddings:default。即使为该提供商保存了其他配置文件，字面量密钥仍保留其配置值。空密钥不会选择已保存的配置文件。

远程端点配置¶

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

remote.baseUrl string（路径）

自定义 API 基础 URL。仅当此 URL 解析到提供商配置的目的地时，才会继承提供商凭证和请求头。

remote.apiKey string（路径）

由远程目的地拥有的 API 密钥。当 remote.baseUrl 指向提供商配置目的地以外的位置时，请设置此项。

remote.headers object（路径）

由远程目的地拥有的额外 HTTP 请求头。仅针对提供商配置的目的地合并提供商默认值。

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

提供商特定配置¶

| 键                    | 类型     | 默认值                | 描述                                |
| ---------------------- | -------- | ---------------------- | ------------------------------------------- |
| `model`                | `string` | `gemini-embedding-001` | 也支持 `gemini-embedding-2`         |
| `outputDimensionality` | `number` | `3072`                 | 128-3072；推荐：768、1536 或 3072  |

旧版 `gemini-embedding-2-preview` 标识符在迁移到稳定模型期间仍会被接受。

{
  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 status --deep 报告从受管服务器观察到的服务器构建、模型路径、能力和端点事实，这些事实是在其处理嵌入请求之后观察到的。

对于本地 GGUF 嵌入，请显式设置 provider: "local"。显式本地配置支持完整的 hf: 文件引用和带有完整性信息的 HTTPS GGUF URL，但它们不会更改默认提供方。

索引行为¶

内存引擎负责同步、批处理、监视以及压缩后索引的启发式策略。OpenClaw 通过维护的默认值保持这些行为启用，而不是暴露按安装配置的时序开关。

文件监视器压力¶

“Memory file watching is tracking ...” 警告报告的是被监视路径或目录的建议数量，而不是实测的主机限制或已确认的耗尽。删除不必要的 memory.search.extraPaths 条目，或缩小其目录根。全局条目和 agents.entries.<id>.memory.search.extraPaths 条目会合并：空的按代理列表不会移除全局根。仅更改条目的 pattern 只会过滤被索引的文件，而不会改变被监视的目录树。当事件位于所有适用模式之外，且无法影响被索引的文件或目录时，会被忽略。当事件没有路径或条目类型未知，且被索引内容可能已更改时，系统会保持保守处理。

删除附加路径条目不会排除仍属于默认 MEMORY.md、USER.md 或 memory/ 根的文件。如果减少附加路径仍不足，请检查 Gateway 主机上的文件监视和打开文件限制。没有受支持的 memory.search.sync.watch 设置。

更改后，重启 Gateway。要刷新受影响的索引，请在 Gateway 主机上使用其配置文件和环境运行 openclaw memory index --force --agent <id>，包括任何 OPENCLAW_STATE_DIR 或 OPENCLAW_CONFIG_PATH 覆盖。使用受影响代理的 ID；警告中打印的命令包含该 ID 以及活动配置文件或容器提示。参见 memory index。

混合搜索配置¶

全部位于 memory.search.query 下：

如果没有每次调用的 maxResults，仅主 memory_search 调用会使用此配置限制，包括 corpus=memory 和 corpus=sessions。Wiki 和组合搜索（corpus=wiki 或 corpus=all）保留其单独的 10 条结果默认值。显式工具 maxResults 会覆盖适用的默认值。

混合检索保持启用。内置引擎始终对带日期的每日笔记应用固定的 30 天新鲜度半衰期，并在混合相关性之后应用固定的重要性乘数，然后应用具有固定 lambda 0.7 的 MMR 多样性排序。MEMORY.md、USER.md 和其他常青内存文件不会衰减。可空的重要性为中性，因此现有索引无需迁移或新的调优键。

在已提升、受信任条目上的强触发匹配可以在符合条件的交互轮次中注入最多三条紧凑内存。目前，根 MEMORY.md 和 USER.md 是精选的合格层级。每日笔记和转录内容永远不会自动注入。

完整示例¶

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

附加内存路径¶

{
  memory: {
    search: {
      extraPaths: ["../team-docs", { path: "/srv/shared-notes", pattern: "runbooks/**/*.md" }],
    },
  },
}

路径可以是绝对路径或相对于工作区的路径。目录会递归扫描受支持的文件。对象条目使用以 / 为分隔符的相对于根目录的 glob 来缩小目录范围；直接文件条目会精确索引。具有相同解析目录的条目共享一次扫描，扫描会跳过其模式可证明无关的子目录。复杂模式保留保守遍历。内置引擎会跳过符号链接。当配置的根是符号链接时，openclaw memory status 会在文本和 JSON 输出中列出被跳过的根，并建议改为配置其规范绝对目录。

对于共享笔记，请保持每个工作区的 memory/ 目录为本地目录，并将共享目录的规范路径添加到 extraPaths。此设置用于索引笔记；它不会授权通过符号链接进行旧版主机事件迁移。

如果 openclaw doctor --fix 报告了不安全的 Memory Core 主机事件源，请检查指定路径和权限。在替换任何符号链接之前，请备份旧版日志。要导入它，请在预期工作区内的常规目录下，将其内容作为常规文件保存在 memory/.dreams/events.jsonl，然后重新运行 openclaw doctor --fix。Doctor 不会改动被拒绝的源。支持指向工作区根本身的符号链接。当存在旧版事件源、导入声明或已迁移归档时，该根以下的符号链接会被拒绝；没有这些源的目录无需修复。

如果已检查点的 events.jsonl.migrated 归档发生了除追加以外的更改，Doctor 会发出警告，并同时保留该归档和已导入的 SQLite 事件。它会推迟该工作区中后续的事件生成，同时继续无关的修复。请保留归档以供检查；此警告并不意味着其编辑后的内容已被导入。不安全的源路径和失败的导入仍会停止 Doctor。

多模态记忆（Gemini）¶

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

支持的格式：.jpg、.jpeg、.png（图像）；.mp3、.wav（音频）。

嵌入缓存¶

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

批量索引¶

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

批量启用是唯一的远程批处理设置。并发、轮询和超时行为由提供商控制。

会话记忆搜索¶

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

内部 dreaming-narrative、cron 和 heartbeat 会话转录不会被索引，包括其活动会话元数据已不存在的保留压缩叙事归档。它们可能引用用户对话中的片段，但不是可搜索的记忆来源。使用 openclaw memory forget 清除的会话也会被持久排除，即使其源转录仍保留在会话存储中。强制重新索引会移除过期的转录记录，而不会重新纳入这两组。普通用户会话转录（包括保留、重置和已删除会话的归档）在未被明确指定之前仍保持可索引。

普通由模型发起的会话转录搜索遵循 tools.sessions.visibility。默认 all 可见性允许非沙箱调用方进行跨代理会话访问，包括其他用户的转录。memory_search 仍限定于所选代理的已索引语料库；如需 Gateway 范围的转录搜索，请使用 sessions_search。跨代理访问默认开启，并由 tools.agentToAgent 控制；设置 enabled: false 可阻止普通跨代理访问，或使用 allow 限制代理对；请求者拥有的原生子代理和 ACP 子会话在 tree 或 all 下仍保持可达。设置 agent 用于同代理回忆，设置 tree 用于当前加派生范围（主会话仍能看到所有同代理会话），或设置 self 用于严格的当前会话访问。仅设置每个对等方的 DM 范围不足以限制会话工具回忆。沙箱限制和隐身排除仍然适用。

rememberAcrossConversations 不会扩大该设置。它提供一项独立的仅限运行时的授权，仅限于有界 Active Memory 处理过程期间的同代理私有转录。

针对 sessions 语料库的显式 memory_search 请求要求已为该代理启用会话搜索。如果不可用，OpenClaw 会说明如何启用会话索引，而不是静默搜索记忆文件。

以下示例将这些设置放在顶层 memory.search 下。如果只有一个代理需要索引和搜索会话转录，也可以在按代理的 memory.search 覆盖中应用等效设置。

要将转录回忆限制为仅同代理，请将会话可见性从默认 all 收窄：

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

SQLite 向量加速（sqlite-vec）¶

对于 macOS 上的 Bun，请安装 Homebrew SQLite 以启用扩展加载；有关自动发现以及 OPENCLAW_SQLITE_LIBRARY 库覆盖，请参阅 Bun SQLite 设置。

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

索引存储¶

内置记忆索引位于每个代理的 OpenClaw SQLite 数据库中，路径为 agents/<agentId>/agent/openclaw-agent.sqlite。

使用 trigram 时，少于三个字符的查询词使用子串匹配， 因此像 AI 和 UK 这样的短词仍可搜索。较长的词保留 全文匹配，包括同时包含短词的查询。

引用¶

memory.citations 控制内置记忆结果的引用可见性：

被引用的片段保留前导缩进；在源页脚之前会移除尾部空白。

记忆准入策略¶

在 plugins.entries.memory-core.config.memoryPolicy.excludeSessions 下配置 做梦摄取和会话回填 的会话排除。这些 设置不会禁用转录搜索、限制工作区写入或删除现有记忆。有关覆盖范围和删除工作流，请参阅 记忆来源与删除。

每个设置都是可选的。省略或空数组不会添加排除项； 正常的来源和会话类型门控仍然适用。配置的字符串 会被修剪，空值会被丢弃，然后进行精确且区分大小写的匹配。 没有 glob 模式、子串匹配或消息内容搜索。

钩子来源是精确标识符：IMAP 使用 email，Gmail 钩子使用 gmail， 通用 webhook 使用 webhook。若要同时排除 IMAP 和 Gmail 摄取， 请设置 hookExternalContentSources: ["email", "gmail"]。

列表以 或 组合。例如，配置一个钩子来源和 chatTypes: ["group"] 会排除该钩子来源 以及所有群组会话， 而不仅仅是来自该来源的群组会话。匹配通过已配置的 session.store 使用保留的实时会话 元数据，包括自定义和共享 存储，并限定到源代理。缺失的元数据不会匹配规则。 较早的保留记录可能只包含粗略的 webhook 分类； 当原始精确来源消失时，不会推断 email 或 webhook 用于匹配。必要时通过完整 ID 显式忘记这些会话。 自动做梦会单独跳过保留的归档；这些列表不会 确定另一条记忆路径是否可以读取已归档的转录。

{
  plugins: {
    entries: {
      "memory-core": {
        config: {
          memoryPolicy: {
            excludeSessions: {
              hookExternalContentSources: ["gmail"],
            },
          },
        },
      },
    },
  },
}

自动摄取在读取转录之前检查这些规则。匹配会话的摄取检查点会按以下优先级顺序将 excludedReason 记录为 hookExternalContentSource:<source>、 channel:<channel> 或 chatType:<type>。 删除该规则会使会话在后续扫描中有资格被处理，但仍受其他摄取门控约束。

由 memory forget 选中的会话会首先被检查， 并接收原因 forgotten。其持久的每代理排除 也适用于会话回填和转录索引，并且删除已配置的规则不会撤销它。它排除所选的 ID，而不是来自同一来源的所有未来会话。

添加规则不会删除现有语料库、短期候选或已提升的记忆。使用 memory forget --dry-run 预览现有可归因产物，然后在应用前查看其 删除边界。 源会话转录仍保留在会话存储中。

做梦¶

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

Dreaming 作为一次计划扫描运行，并使用内部 light/deep/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",
          },
        },
      },
    },
  },
}

相关¶

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