Memory LanceDB

memory-lancedb 是一个官方外部插件，它使用 LanceDB 和向量搜索存储长期记忆。它可以在模型轮次前自动召回相关记忆，并在响应后自动捕获重要事实。

可将其用于本地向量数据库、兼容 OpenAI 的嵌入端点，或默认内置记忆后端之外的记忆存储。

安装

openclaw plugins install @openclaw/memory-lancedb

该插件发布在 npm 上；它并未内置于 OpenClaw 运行时镜像中。安装会写入插件条目、启用插件，并将 plugins.slots.memory 切换为 memory-lancedb。如果当前由另一个插件占用记忆槽位，系统会禁用该插件并发出警告。

快速开始

{
  plugins: {
    slots: {
      memory: "memory-lancedb",
    },
    entries: {
      "memory-lancedb": {
        enabled: true,
        config: {
          embedding: {
            provider: "openai",
            model: "text-embedding-3-small",
          },
          autoRecall: true,
          autoCapture: false,
        },
      },
    },
  },
}

更改插件配置后重启 Gateway 网关，然后验证插件是否已加载：

openclaw gateway restart
openclaw plugins list

嵌入配置

embedding 是必需的，并且必须至少包含一个字段。provider 默认为 openai；model 默认为 text-embedding-3-small。

有两种请求路径：

• 提供商适配器路径（默认）：设置 embedding.provider，并省略 embedding.apiKey/embedding.baseUrl。插件会通过 memory-core 所使用的同一套记忆嵌入适配器，解析提供商已配置的身份验证配置文件、环境变量或 models.providers.<provider>.apiKey。这是 github-copilot、ollama 以及其他任何支持嵌入的内置提供商所使用的路径。
• 直接兼容 OpenAI 的客户端路径：不设置 embedding.provider（或设置为 "openai"），并设置 embedding.apiKey 和 embedding.baseUrl。此路径用于没有内置提供商适配器的原始兼容 OpenAI 的嵌入端点。

OpenAI Codex / ChatGPT OAuth 不是 OpenAI Platform 嵌入凭据。若要使用 OpenAI 嵌入，请使用 OpenAI API 密钥身份验证配置文件、OPENAI_API_KEY 或 models.providers.openai.apiKey。仅使用 OAuth 的用户应选择其他支持嵌入的提供商，例如 github-copilot 或 ollama。

{
  plugins: {
    entries: {
      "memory-lancedb": {
        enabled: true,
        config: {
          embedding: {
            provider: "github-copilot",
            model: "text-embedding-3-small",
          },
        },
      },
    },
  },
}

某些兼容 OpenAI 的嵌入端点会拒绝 encoding_format 参数；另一些则会忽略它，并始终返回 number[]。memory-lancedb 会在请求中省略 encoding_format，并接受浮点数组或采用 base64 编码的 float32 响应，因此两种响应格式都无需配置即可使用。

维度

OpenClaw 仅为 text-embedding-3-small（1536）和 text-embedding-3-large（3072）提供内置维度。其他任何模型都需要显式设置 embedding.dimensions，以便 LanceDB 创建向量列。例如，智谱 embedding-3 的维度为 2048：

{
  plugins: {
    entries: {
      "memory-lancedb": {
        enabled: true,
        config: {
          embedding: {
            apiKey: "${ZHIPU_API_KEY}",
            baseUrl: "https://open.bigmodel.cn/api/paas/v4",
            model: "embedding-3",
            dimensions: 2048,
          },
        },
      },
    },
  },
}

Ollama 嵌入

使用内置 Ollama 提供商适配器路径（embedding.provider: "ollama"）。它会调用 Ollama 的原生 /api/embed 端点，并遵循与 Ollama 提供商相同的身份验证/基础 URL 规则。

{
  plugins: {
    slots: {
      memory: "memory-lancedb",
    },
    entries: {
      "memory-lancedb": {
        enabled: true,
        config: {
          embedding: {
            provider: "ollama",
            baseUrl: "http://127.0.0.1:11434",
            model: "mxbai-embed-large",
            dimensions: 1024,
          },
          recallMaxChars: 400,
          autoRecall: true,
          autoCapture: false,
        },
      },
    },
  },
}

mxbai-embed-large 不在内置维度表中，因此必须设置 dimensions。对于小型本地嵌入模型，如果本地服务器返回上下文长度错误，请降低 recallMaxChars。

召回和捕获限制

recallMaxChars 会限制 before_prompt_build 自动召回查询、memory_recall 工具、memory_forget 查询路径和 openclaw ltm search。自动召回会嵌入该轮次中的最新用户消息；仅当不存在用户消息时，才回退到完整提示词，从而避免将渠道元数据和大型提示词块包含在嵌入请求中。

captureMaxChars 用于判断该轮次 agent_end 事件中的用户消息是否足够短，可以纳入自动捕获考虑；它不会影响召回查询。

customTriggers 可添加不使用正则表达式的字面自动捕获短语。内置触发器涵盖常见的英语、捷克语、中文、日语和韩语记忆短语（remember、prefer、记住、覚えて、기억해 等）。

自动捕获还会拒绝看起来像信封/传输元数据、提示词注入载荷或已注入的 <relevant-memories> 上下文的文本，并将每个智能体轮次捕获的记忆数量限制为最多 3 条。

每条记忆都归一个智能体所有。召回、重复检测、捕获、列出、原始查询和删除操作都会先强制检查该所有者，再返回或修改行。如果某个智能体的 agents.entries.* 条目中含有 memory.search.enabled: false，或者继承了已禁用的顶层搜索设置，那么即使插件级 autoRecall/autoCapture 标志已开启，该智能体也不会获得 memory_recall、memory_store 或 memory_forget 工具，也不会参与自动召回或捕获。

命令

只要安装了 memory-lancedb，它就会注册 ltm CLI 命名空间（并非仅在它占用活动记忆槽位时注册）：

openclaw ltm list [--agent <id>] [--limit <n>] [--order-by-created-at]
openclaw ltm search <query> [--agent <id>] [--limit <n>]
openclaw ltm stats [--agent <id>]

ltm query 会直接针对 LanceDB 表运行非向量查询：

openclaw ltm query --agent research --cols id,text,createdAt --limit 20
openclaw ltm query --filter "category = 'preference'" --order-by createdAt:desc

智能体会从活动记忆插件获得三个工具：

• memory_recall：对已存储的记忆执行向量搜索。
• memory_store：保存事实、偏好、决策或实体（拒绝看起来像提示词注入载荷的文本；跳过近似重复的存储内容）。
• memory_forget：按 memoryId 或 query 删除（若单个匹配项的得分高于 90%，则自动删除；否则列出候选 ID 以消除歧义）。

存储

LanceDB 数据默认存储在 ~/.openclaw/memory/lancedb。可通过 dbPath 覆盖：

{
  plugins: {
    entries: {
      "memory-lancedb": {
        enabled: true,
        config: {
          dbPath: "~/.openclaw/memory/lancedb",
          embedding: {
            apiKey: "${OPENAI_API_KEY}",
            model: "text-embedding-3-small",
          },
        },
      },
    },
  },
}

该插件维护一个 LanceDB 表，并在每行中存储规范化的智能体所有者。这是存储边界，而不是搜索后筛选器：智能体所有权会在向量排名之前应用，并包含在列表、查询、计数和删除谓词中。ltm query --filter 接受一项针对公共输出列且经过验证的比较。存储会将该比较与强制所有者谓词分开构建，因此筛选器无法将查询范围扩大到另一个智能体。

在引入按智能体所有权之前创建的数据库不包含可靠的行来源信息。升级时，openclaw doctor --fix 会将这些旧版行一次性分配给已配置的默认智能体。在该迁移完成之前，运行时访问会采用故障关闭策略；其他智能体绝不会继承旧的共享行。

storageOptions 接受用于 LanceDB 存储后端（例如 S3 兼容的对象存储）的字符串键值对，并支持 ${ENV_VAR} 展开：

{
  plugins: {
    entries: {
      "memory-lancedb": {
        enabled: true,
        config: {
          dbPath: "s3://memory-bucket/openclaw",
          storageOptions: {
            access_key: "${AWS_ACCESS_KEY_ID}",
            secret_key: "${AWS_SECRET_ACCESS_KEY}",
            endpoint: "${AWS_ENDPOINT_URL}",
          },
          embedding: {
            apiKey: "${OPENAI_API_KEY}",
            model: "text-embedding-3-small",
          },
        },
      },
    },
  },
}

运行时依赖和平台支持

memory-lancedb 依赖由插件包（而非 OpenClaw 核心发行包）负责管理的原生 @lancedb/lancedb 软件包。Gateway 网关启动时不会修复插件依赖；如果缺少原生依赖或加载失败，请重新安装或更新插件包，然后重启 Gateway 网关。

@lancedb/lancedb 不提供适用于 darwin-x64（Intel Mac）的原生构建。在该平台上，插件会在加载时记录 LanceDB 不可用；请使用默认记忆后端、在受支持的平台/架构上运行 Gateway 网关，或禁用 memory-lancedb。

故障排除

输入长度超过上下文长度

嵌入模型拒绝了召回查询：

memory-lancedb: 召回失败：错误：400 输入长度超过上下文长度

降低 recallMaxChars，然后重启 Gateway 网关：

{
  plugins: {
    entries: {
      "memory-lancedb": {
        config: {
          recallMaxChars: 400,
        },
      },
    },
  },
}

对于 Ollama，还应使用其原生嵌入端点验证能否从 Gateway 网关主机访问嵌入服务器：

curl http://127.0.0.1:11434/api/embed \
  -H "Content-Type: application/json" \
  -d '{"model":"mxbai-embed-large","input":"hello"}'

不受支持的嵌入模型

如果未设置 embedding.dimensions，则仅已知内置 OpenAI 嵌入模型的维度（text-embedding-3-small、text-embedding-3-large）。对于任何其他模型，请将 embedding.dimensions 设置为该模型报告的向量大小。

插件已加载，但未显示任何记忆

确认 plugins.slots.memory 指向 memory-lancedb，然后运行：

openclaw ltm stats
openclaw ltm search "recent preference"

如果已禁用 autoCapture，插件仍会召回现有记忆，但不会自动存储新记忆。请使用 memory_store 工具，或启用 autoCapture。

相关内容

• 记忆概览
• 主动记忆
• 记忆搜索
• Memory Wiki
• Ollama