内置记忆引擎
内置引擎是默认的记忆后端。它将你的记忆索引存储在按代理划分的 SQLite 数据库中,无需额外依赖即可开始使用。
它提供什么¶
- 关键词搜索 通过 FTS5 全文索引(BM25 评分)。
- 向量搜索 通过任意受支持提供方的嵌入。
- 混合搜索 将两者结合以获得最佳结果。
- 确定性排序 按相关性、新近性和写入时重要性。
- 多样性感知排序 默认在混合结果上启用 MMR。
- 可信触发器召回 为有界的回复前上下文,无需召回模型。
- CJK 支持 通过三元组分词支持中文、日文和韩文。
- sqlite-vec 加速 用于数据库内向量查询(可选)。
原生 sqlite-vec 查询在独立的只读进程中运行,因此慢查询不会阻塞 Gateway 事件循环。取消搜索会终止其查询进程;OpenClaw 不会在 Gateway 线程上重试该原生查询。每个数据库的查询会复用一个进程,最多有两个进程存活。空闲进程在 30 分钟后或当另一个数据库需要容量时退出。每个查询都会重新打开数据库,因此已提交的更新和替换的索引仍然可见。
关键词检索、召回元数据、精选触发器和项目候选项以及源时间戳使用记忆搜索工作进程。Gateway 等待投影行并应用相同排序。仅会话搜索将最终元数据和时间戳读取保留在调用方上,因为额外的工作进程请求会增加实测延迟;其他检索读取在 Gateway 事件循环之外运行。搜索会保留其索引代际,直到工作进程关闭其读取器;召回元数据在候选项检索之后读取,因此被遗忘的块会被排除。这不会更改存储数据、配置或升级行为。
在 Gateway 就绪后,空闲预热会在首次搜索之前加载活动的 Memory Core 检索工作进程。它不会打开索引、启动嵌入提供方或延迟就绪。在预热完成前到达的请求仍会正常初始化检索;工作进程保留其现有的空闲退出策略。
如果语义检索在来自记忆文件的关键词匹配已就绪后达到 30 秒工具截止时间,memory_search 会返回这些匹配项并附带部分结果警告。会话转录命中需要新的可见性检查,并且被排除在超时恢复之外。部分响应不会将整个记忆语料库放入超时冷却。当代理未提供最终回复时,回退警告会说明超时时长以及是否有部分结果可用。
何时使用¶
内置引擎是大多数用户的正确选择:
- 开箱即用,无需额外依赖。
- 很好地处理关键词搜索和向量搜索。
- 支持所有嵌入提供方。
- 混合搜索结合了两种检索方法的优点。
内置引擎可以使用 memory.search.extraPaths 索引工作区外的目录。它使用有界的词汇查询扩展来改善对话召回,但不提供学习式或基于模型的相关性重排序阶段。其 MMR 处理是确定性的且本地的。
如果你希望具有自动用户建模的跨会话记忆,请考虑 Honcho。
快速开始¶
默认情况下,内置引擎使用 OpenAI 嵌入。如果已配置 OPENAI_API_KEY 或 models.providers.openai.apiKey,则无需额外记忆配置即可使用向量搜索。
显式设置提供方:
如果没有嵌入提供方,则仅可用关键词搜索。
若要强制使用本地 GGUF 嵌入,请安装并配置官方 llama.cpp 提供方,然后将 local.modelPath 指向一个 GGUF 文件:
{
memory: {
search: {
provider: "local",
fallback: "none",
local: {
modelPath: "~/.openclaw/models/llama.cpp/hf_ggml-org_embeddinggemma-300m-qat-Q8_0.gguf",
},
},
},
}
支持的嵌入提供方¶
| 提供方 | ID | 说明 |
|---|---|---|
| Bedrock | bedrock |
使用 AWS 凭据链 |
| DeepInfra | deepinfra |
默认:BAAI/bge-m3 |
| Gemini | gemini |
支持多模态(图像 + 音频) |
| GitHub Copilot | github-copilot |
使用你的 Copilot 订阅 |
| LM Studio | lmstudio |
本地/自托管 |
| Local | local |
OpenClaw 管理的 llama.cpp 服务器 |
| Mistral | mistral |
|
| Ollama | ollama |
本地/自托管 |
| OpenAI | openai |
默认:text-embedding-3-small |
| OpenAI-compatible | openai-compatible |
通用 /v1/embeddings 端点 |
| Voyage | voyage |
设置 memory.search.provider 可从 OpenAI 切换。
索引如何工作¶
OpenClaw 将 MEMORY.md、已存在的根目录 USER.md 以及 memory/*.md 索引为块(默认 400 个 token,80 个 token 重叠),并将它们存储在按代理划分的 SQLite 数据库中。OpenClaw 不会自动创建 USER.md。
每个块都可以携带可空的重要性和触发器元数据。空值是中性的,因此旧索引仍然可用。搜索在应用 MMR 多样性之前,会结合混合相关性、新近性衰减和重要性;触发器召回仅注入精选或已提升为可信的条目。
每个已索引的块还具有 SQLite 拥有的来源信息:来源类别(owner、agent、untrusted 或 system)、会话类型、观察时间以及可选的取代键。此元数据与 Markdown 分开存储,因此召回的文本无法重写其自身的信任分类。自动会话摄取还会为其暂存条目记录源会话来源,以支持提升后的选择性删除。有关覆盖范围和限制,请参阅 记忆来源与删除。
- 索引位置: 所属代理数据库位于
~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite - 存储维护: SQLite WAL 附属文件通过周期性检查点和关闭检查点进行限制。
- 文件监视: 记忆文件的变化会触发防抖重建索引 (默认 1.5 秒)。
- 索引兼容性: 更改嵌入提供方、模型、设置、 已配置的来源或范围可能会暂停搜索,直到你显式重建。 参见提供方选择。
- 按需重建索引:
openclaw memory index --force --agent <id>
当 Memory Core 拥有记忆槽位时,其 Gateway 服务会安排每个已配置代理的记忆管理器在启动时和插件替换后打开。此后台激活会等待该代理的数据库准备,包括升级或重启后,而不会延迟 Gateway 就绪。准备失败会报告数据库的修复指引。被监视的文件变化随后可以在没有搜索或代理轮次的情况下更新索引。退役实例会关闭其管理器,包括文件监视器、定时器和会话监听器。仍在进行中的会话启动扫描会在当前步骤后停止,因此禁用或替换插件不会等待它。插件重新加载还会在发布前后停止并重启保留的 Memory Core 服务,因此其管理器会使用当前嵌入提供方,包括按需加载的提供方,而无需等待搜索或轮次。如果在排空管理器后重新加载失败,恢复会重启其先前服务,并在报告先前运行时已恢复之前安排其索引激活。服务停止会等待待处理激活完成后再关闭其管理器。仅作为另一个记忆插件的整合附属组件运行的 Memory Core 不会自动启动这些索引。
当索引标识报告 OpenClaw 分块实现变更时,普通搜索或 CLI 搜索会在返回结果前重建它。重建使用代理当前的嵌入设置;状态检查保持只读。
搜索触发的维护会增量应用待处理的记忆和会话变更,同时搜索保持可用。失败的全量重建会保留其全量重试状态;普通脏内容本身不会强制重建。增长的会话转录会保留未更改的已索引分块,并仅嵌入新增或已更改的分块,即使嵌入缓存已禁用也是如此。显式全量重建仍会替换完整索引。 如果记忆文件在索引期间发生变化或消失,只会增量重试该文件未完成的工作。其他文件完成索引,并且已更改文件的过期分块不会被发布。
自动全量重建重试在失败后等待 30 秒。重复失败会将该延迟加倍,最多 30 分钟;成功重建会重置它。搜索继续读取已发布索引,并且当目标会话更新的标识有效时,仍可以发布。显式 CLI 修复会绕过进程本地冷却。
当原生文件监视不可用时,Memory Core 使用默认间隔为 30 秒的后台轮询,包括通过 CHOKIDAR_USEPOLLING 显式启用轮询的情况。有效的 CHOKIDAR_INTERVAL 会覆盖此默认值,最小值为 20 毫秒。更短的间隔会增加后台扫描成本,尤其对于大型记忆树。原生事件仍会触发及时的防抖更新。自动回退会在每个监视器生命周期内记录一条警告。正在运行的记忆管理器会在其状态下的 custom.watcher 中公开每个本地观察的模式、轮询间隔和 pollingFallback;独立状态检查不会启动监视器。文件系统库当前不会保留回退原因或重试原生选择;警告会说明未报告原因的情况。在解决原生后端问题后重启 Gateway,以再次尝试原生监视。
如果主机耗尽原生文件监视容量,Memory Core 会记录一条警告并禁用其监视器。后续搜索会触发增量同步以发现文件变化。在该后台工作完成期间,搜索可以返回先前索引;后续搜索会看到更新后的内容。在恢复监视容量后重启 Gateway,以再次启用原生监视。
当另一个 SQLite 写入器处于活动状态时,增量索引、过期来源清理和缓存修剪会异步等待。缓存修剪以有界批次删除最旧的条目,在批次之间让出,同时保留现有缓存上限。
全量重建索引会在临时数据库中构建替换项,并原子地发布记忆表。并发搜索和状态读取继续使用已发布索引;失败的重建会使该索引保持完整。嵌入缓存会在发布前进行限制,而不是在将超额条目复制到共享数据库之后。
其他代理状态,包括同一数据库中的会话和转录,会被保留。使用记忆索引命令进行仅记忆修复。
openclaw memory status 报告每个来源的已存储分块文本和二进制嵌入字节(JSON 中的 sourceCounts[].chunkBytes)。这些是负载大小,不是总磁盘使用量:嵌入缓存、FTS/向量表、SQLite 开销和 WAL/空闲页被排除在外。
分块和嵌入缓存向量使用小端 64 位浮点 BLOB。软件搜索回退直接在 worker 中对这些全精度 BLOB 进行评分,无需为每个分块分配数值数组,即使可选的 sqlite-vec 加速器不可用也是如此;sqlite-vec 保留其独立的 32 位向量索引。关键词索引使用每个分块稳定的整数标识,因此编辑和删除会直接更新对应的 FTS 行。
代理架构 23 会在本地转换现有 JSON 向量,而不联系嵌入提供方。它保留分块 ID、来源、召回元数据和缓存标识。格式错误的旧版向量会保留其可搜索文本,并将其来源标记为需要重建索引。无法保留的未知架构扩展会导致迁移停止,而不重写这些表。升级或返回到旧版本构建时,请遵循数据库版本控制和回滚契约。
升级后,自动项目与触发器召回可能需要修复旧版溯源信息。该修复在后台运行。在受影响的来源被重新分类之前,回复会继续,而自动召回保持为空。
Info
您还可以使用 memory.search.extraPaths 索引工作区之外的 Markdown 文件。请参阅
配置参考。
从 QMD 迁移¶
QMD 已被移除;builtin 是唯一的内存引擎。升级后,运行:
Doctor 会移除已弃用的 memory.backend、memory.qmd 和 memory.search.qmd 设置,包括 agent 作用域的 memory.search.qmd 形式。它会将 QMD 路径和额外集合保留为相应的 memory.search.extraPaths 条目,包括 { path, pattern } 通配符。当 QMD 会话索引已启用时,Doctor 还会启用 builtin 会话索引,并将 sessions 添加到 memory.search.sources,但不会启用更广泛的跨会话召回。保留的会话重置记录仍位于 agent 的 sessions 目录中,并从这些原始工件进行索引。
Doctor 仅移除 ~/.openclaw/agents/<agentId>/qmd/ 下空的 per-agent QMD 目录。非空目录保持不变:OpenClaw 已弃用的 QMD 后端使用与独立 QMD 相同的布局,没有所有权标记。保留的目录不会阻止迁移或 Gateway 启动。在备份它们之后,如果您已确认没有独立 QMD 安装使用这些内容,可以手动删除旧的索引、模型下载、集合元数据和会话导出。
规范内存仍保留在 MEMORY.md、USER.md、memory/*.md 以及迁移后的额外路径中。Builtin 会在下次同步时索引这些相同的 Markdown 来源。切换本质上无损:不会复制或删除任何规范内存内容;仅重建派生状态。
Builtin 现在通过以下功能覆盖了大多数 QMD 用例:
- 默认采用混合 BM25 和向量检索,随后在 MMR 多样性之前应用时间衰减、重要性和项目亲和性,
- 针对对话式搜索的有界词法查询扩展,
memory.search.extraPaths中的字符串或{ path, pattern }条目,以及- 仅在
extraPaths下可选的图像和音频索引。
QMD 查询模式的学习型交叉编码器重排序和 HyDE 生成不属于 builtin 内存。MMR 会减少重复结果,但它不是学习型相关性重排序器。要替换 QMD 的进程内、零密钥 GGUF 嵌入,请安装 llama.cpp provider 并设置 memory.search.provider: "local";如果没有嵌入提供程序,builtin 仅使用 BM25 关键字搜索。
故障排除¶
内存搜索已禁用? 请检查 openclaw memory status。如果未检测到提供程序,请显式设置一个或添加 API 密钥。
未检测到本地提供程序? 使用 openclaw onboard 运行一次交互式 llama.cpp 设置,确认本地路径存在,然后运行:
独立 CLI 命令和 Gateway 都使用相同的 local 提供程序 ID。当您需要本地嵌入时,请设置 memory.search.provider: "local"。
结果过期? 运行 openclaw memory index --force 进行重建。在极少数边界情况下,监视器可能会错过更改。
sqlite-vec 无法加载? OpenClaw 会自动回退到进程内余弦相似度。openclaw memory status --deep 会分别报告本地向量存储和嵌入提供程序,因此 Vector store: unavailable 指向 sqlite-vec 加载问题,而 Embeddings: unavailable 指向提供程序/认证或模型就绪状态。请检查日志以了解具体的加载错误。
安全索引恢复¶
要在结果过期或嵌入提供程序更改后重建,请显式选择受影响的 agent:
openclaw memory status --agent <agent-id> --deep
openclaw memory index --agent <agent-id> --force --verbose
openclaw memory status --agent <agent-id> --deep
Warning
索引与规范会话、记录(transcripts)和其他持久化 agent 状态共享 openclaw-agent.sqlite。切勿删除该数据库或其 -wal、-shm 或 -journal 附属文件来重置内存。内存索引无法重建以这种方式丢失的对话历史。
要在重建前丢弃派生的索引和嵌入缓存,请使用 memory reset:
Reset 会要求确认;在非交互式使用中添加 --yes。它仅清除内存拥有的派生表,保留非内存数据库表(包括会话和记录)以及内存源文件。它会在不重启 Gateway 的情况下与现有内存维护协调,之后 Gateway 可以重新索引保留的来源。如果索引正忙,请让其完成,然后重试 reset。Reset 不会缩小数据库文件,也不会恢复已删除的数据。
如果索引失败或数据库意外增长,请保留数据库及其附属文件,保留详细错误,并在手动恢复之前创建并验证备份。仅凭数据库庞大无法显示哪些表导致了问题。重新索引不是会话历史恢复:如果在移动或删除数据库后历史记录丢失,请使用恢复工作流从经过验证的备份中恢复。
回收磁盘空间¶
从 openclaw memory status --agent <agent-id> --json 开始。比较数据库和 WAL 大小、可重用字节、保留的嵌入缓存负载以及每个来源的分块(chunk)负载。可重用字节是 SQLite 中已经空闲的页面;它们不是额外数据。缓存和分块负载不包括索引和 SQLite 开销,因此它们不能解释共享文件中的每一个字节。
如果需要丢弃派生的索引,请创建并验证备份,然后通过其部署所有者停止 Gateway,并停止其他写入者。在 reset 和压缩(compaction)期间保持它们停止,以便后台索引无法在命令之间重新填充缓存:
openclaw memory reset --agent <agent-id> --yes
openclaw doctor --session-sqlite compact --session-sqlite-agent <agent-id>
openclaw memory index --agent <agent-id>
openclaw memory status --agent <agent-id>
如果只需要回收未使用的页面,请跳过重置并保留现有索引。 Doctor 会压缩整个 agent 数据库,验证完整性,并报告压缩前后的数据库和 WAL 大小。压缩需要临时磁盘空间;如果卷已满,请先释放空间,或将已验证的备份移动到容量充足的卷,然后再尝试。重建可能会调用嵌入提供商并产生费用。验证后,通过其部署所有者重启 Gateway。重置和压缩均不会删除规范会话或更改保留策略。
配置¶
有关嵌入提供商设置、搜索结果限制和阈值、批量索引、多模态内存、sqlite-vec、额外路径以及所有其他配置项,请参阅 内存配置参考。
相关¶
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw