内置记忆引擎

内置引擎是默认记忆后端。它会将你的记忆索引存储在每个智能体的 SQLite 数据库中，并且无需额外依赖即可开始使用。

它提供什么

• 关键字搜索，通过 FTS5 全文索引实现（BM25 评分）。
• 向量搜索，通过任何受支持提供商的 embeddings 实现。
• 混合搜索，结合两者以获得最佳结果。
• CJK 支持，通过 trigram 分词支持中文、日文和韩文。
• sqlite-vec 加速，用于数据库内向量查询（可选）。

入门指南

默认情况下，内置引擎使用 OpenAI embeddings。如果已经配置了 OPENAI_API_KEY 或 models.providers.openai.apiKey，向量搜索无需额外记忆配置即可工作。

要显式设置提供商：

{  agents: {    defaults: {      memorySearch: {        provider: "openai",      },    },  },}

如果没有 embedding 提供商，则只有关键字搜索可用。

要强制使用本地 GGUF embeddings，请安装官方 llama.cpp provider 插件，然后将 local.modelPath 指向一个 GGUF 文件：

openclaw plugins install @openclaw/llama-cpp-provider

{  agents: {    defaults: {      memorySearch: {        provider: "local",        fallback: "none",        local: {          modelPath: "~/.node-llama-cpp/models/embeddinggemma-300m-qat-Q8_0.gguf",        },      },    },  },}

支持的 embedding 提供商

设置 memorySearch.provider 可切换为不使用 OpenAI。

索引如何工作

OpenClaw 会将 MEMORY.md 和 memory/*.md 索引为块（默认 400 个 token，80 个 token 重叠），并将它们存储在每个智能体的 SQLite 数据库中。

• 索引位置： 所属智能体数据库，位于 ~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite
• 存储维护： SQLite WAL sidecar 会通过定期和关闭时 checkpoint 进行限制。
• 文件监视： 记忆文件的更改会触发防抖重新索引（默认 1.5 秒）。
• 自动重新索引： 当 embedding 提供商、模型、分块配置、配置的来源或作用域发生变化时，索引会自动重建。
• 按需重新索引： openclaw memory index --force

何时使用

内置引擎适合大多数用户：

• 开箱即用，无需额外依赖。
• 能很好地处理关键字和向量搜索。
• 支持所有 embedding 提供商。
• 混合搜索结合了两种检索方法的优势。

如果你需要重排序、查询扩展，或想要索引工作区之外的目录，请考虑切换到 QMD。

如果你想要带自动用户建模的跨会话记忆，请考虑 Honcho。

故障排查

记忆搜索被禁用？ 检查 openclaw memory status。如果未检测到提供商，请显式设置一个，或添加 API key。

未检测到本地提供商？ 确认本地路径存在并运行：

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

独立 CLI 命令和 Gateway 网关都使用相同的 local 提供商 ID。当你想使用本地 embeddings 时，设置 memorySearch.provider: "local"。

结果过旧？ 运行 openclaw memory index --force 进行重建。在少数边缘情况下，监视器可能会漏掉更改。

sqlite-vec 未加载？ OpenClaw 会自动回退到进程内余弦相似度。openclaw memory status --deep 会将本地向量存储与 embedding 提供商分开报告，因此 Vector store: unavailable 指向 sqlite-vec 加载问题，而 Embeddings: unavailable 指向提供商/凭证或模型就绪问题。请检查日志以查看具体加载错误。

配置

关于 embedding 提供商设置、混合搜索调优（权重、MMR、时间衰减）、批量索引、多模态记忆、sqlite-vec、额外路径以及所有其他配置选项，请参见Memory 配置参考。

相关

• 记忆概览
• 记忆搜索
• 主动记忆