> ## Documentation Index
> Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 内置记忆引擎

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

## 它提供什么

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

## 入门指南

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

要显式设置提供商：

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  agents: {
    defaults: {
      memorySearch: {
        provider: "openai",
      },
    },
  },
}
```

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

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

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw plugins install @openclaw/llama-cpp-provider
```

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  agents: {
    defaults: {
      memorySearch: {
        provider: "local",
        fallback: "none",
        local: {
          modelPath: "~/.node-llama-cpp/models/embeddinggemma-300m-qat-Q8_0.gguf",
        },
      },
    },
  },
}
```

## 支持的 embedding 提供商

| 提供商            | ID                  | 说明                             |
| -------------- | ------------------- | ------------------------------ |
| Bedrock        | `bedrock`           | 使用 AWS 凭证链                     |
| DeepInfra      | `deepinfra`         | 默认值：`BAAI/bge-m3`              |
| Gemini         | `gemini`            | 支持多模态（图像 + 音频）                 |
| GitHub Copilot | `github-copilot`    | 使用你的 Copilot 订阅                |
| LM Studio      | `lmstudio`          | 本地/自托管                         |
| 本地             | `local`             | `@openclaw/llama-cpp-provider` |
| Mistral        | `mistral`           |                                |
| Ollama         | `ollama`            | 本地/自托管                         |
| OpenAI         | `openai`            | 默认值：`text-embedding-3-small`   |
| OpenAI 兼容      | `openai-compatible` | 通用 `/v1/embeddings` 端点         |
| Voyage         | `voyage`            |                                |

设置 `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`

<Info>
  你也可以使用 `memorySearch.extraPaths` 索引工作区之外的 Markdown 文件。参见[配置参考](/zh-CN/reference/memory-config#additional-memory-paths)。
</Info>

## 何时使用

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

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

如果你需要重排序、查询扩展，或想要索引工作区之外的目录，请考虑切换到 [QMD](/zh-CN/concepts/memory-qmd)。

如果你想要带自动用户建模的跨会话记忆，请考虑 [Honcho](/zh-CN/concepts/memory-honcho)。

## 故障排查

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

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

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw memory status --deep --agent main
openclaw 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 配置参考](/zh-CN/reference/memory-config)。

## 相关

* [记忆概览](/zh-CN/concepts/memory)
* [记忆搜索](/zh-CN/concepts/memory-search)
* [主动记忆](/zh-CN/concepts/active-memory)