记忆 LanceDB

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

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

安装¶

openclaw plugins install @openclaw/memory-lancedb

该插件发布在 npm 上；它没有打包到 OpenClaw 运行时镜像中。安装时会写入插件条目、启用插件，并将 plugins.slots.memory 切换为 memory-lancedb。如果当前有另一个插件占用了 memory 槽位，该插件会被禁用并给出警告。

快速开始¶

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

安装会自动应用于正在运行的 Gateway，配置更改会以默认的混合重载模式生效。如果 Gateway 处于离线状态，请在配置完成后启动它。检查应用结果并查看插件的运行时注册信息：

openclaw plugins inspect memory-lancedb --runtime --json

参见应用更改并检查和热重载。

嵌入配置¶

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

存在两条请求路径：

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

只要 provider、model 和 dimensions 保持不变，embedding.apiKey 和 embedding.baseUrl 会在下一次记忆操作时从实时插件配置中重新读取。

OpenAI Codex / ChatGPT OAuth 不是 OpenAI Platform 的 embeddings（嵌入）凭证。对于 OpenAI 嵌入，请使用 OpenAI API key 认证配置文件、OPENAI_API_KEY 或 models.providers.openai.apiKey。仅使用 OAuth 的用户应选择其他支持嵌入的 provider，例如 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 创建向量列，例如 ZhiPu 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 provider 适配器路径（embedding.provider: "ollama"）。它会调用 Ollama 原生的 /api/embed 端点，并遵循与 Ollama provider 相同的认证/base 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。自动召回会对当前回合的 prompt 进行嵌入，在此之前会移除媒体附件说明并规范化空白字符。该限制同样作用于每个召回项经 prompt 转义后、在文本到达模型之前的大小。

captureMaxChars 决定来自该回合 agent_end 事件的用户消息是否足够短，从而可以被考虑进行自动捕获。memory_store 会在嵌入或存储前拒绝更长的文本；该设置不影响召回查询。

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

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

已完成的整条消息实例只要仍保留在对话记录中，就不会被再次处理，包括在压缩之后。最近 60 个已完成的文本块在其消息离开对话记录后也会保持去重。该历史记录包含与既有记忆匹配的文本，以及部分失败消息中成功的文本块。后续消息仍然可以捕获先前出现时因每回合限制而跳过的文本。如果没有不同的时间戳或保留的上下文，相同的替换内容可能与未更改的重放难以区分。重置或结束对话会清除该进度。同一对话中重叠的完成事件共享捕获进度；其他对话可以独立进行。在关闭时，插件会停止新的捕获工作，并在关闭其存储之前等待待处理的捕获完成。

每条记忆都由一个智能体拥有。召回、重复检测、捕获、列出、原始查询和删除都会在返回或修改行之前强制执行该拥有关系。如果智能体在其 agents.entries.* 配置中将 memory.search.enabled 设为 false，或者继承了已禁用的顶级搜索设置，那么它也不会获得 memory_recall、memory_store 或 memory_forget 工具，并且不会参与自动召回或自动捕获，即使插件级别的 autoRecall/autoCapture 标志已开启。

无痕会话会跳过自动召回和自动捕获。它们的 prompt 不会被发送到嵌入提供方以进行自动召回，memory_store 也拒绝保存它们。显式工具调用仍遵循其正常的数据处理规则。

命令¶

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 stats 会在插件注册 60 秒后执行其数据库读取。它会在报告超时之前停止隔离的读取器，而不会创建记忆表或更改现有记忆数据。没有记忆表的数据库会报告零。插件发现和源捕获发生在此截止时间开始之前。

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：保存事实、偏好、决策或实体（拒绝看起来像提示注入载荷的文本；在规范化换行符、Unicode NFC 和周围空白后跳过完全重复项，但会存储文本不同但语义相似的记忆）。
• 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 捆绑了 LanceDB 的 JavaScript。其插件包将原生 @lancedb/lancedb-* 包声明为可选依赖项，因此安装时会为主机平台选择匹配的二进制文件。Gateway 启动不会修复插件依赖项；如果原生依赖项缺失或加载失败，请重新安装或更新插件包并重启 Gateway。

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

故障排查¶

输入长度超出上下文长度¶

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

memory-lancedb: recall failed: Error: 400 the input length exceeds the context length

降低 recallMaxChars；新限制将应用于下一次记忆操作：

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

对于 Ollama，还请从 Gateway 主机使用其原生 embed 端点验证嵌入服务器是否可达：

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。

相关¶

• 记忆概览
• 活动记忆
• 记忆搜索
• 记忆 Wiki
• Ollama