跳转至

记忆 LanceDB

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

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

安装

openclaw plugins install @openclaw/memory-lancedb

该插件已发布到 npm;它未打包到 OpenClaw 运行时镜像中。安装它会写入插件条目、启用它,并将 plugins.slots.memory 切换为 memory-lancedb。如果另一个插件当前拥有内存插槽,该插件会被禁用并显示警告。

Note

诸如 memory-wiki 之类的配套插件可以与 memory-lancedb 一起运行,但同一时间只有一个插件拥有活动内存插槽。

Note

LanceDB 的 memory_recall 不会接收 memory.search.rememberAcrossConversations 使用的受保护私有转录授权。请通过 高级 Active Memory 使用 LanceDB 的 autoRecall 或其 memory_recall 工具。当当前内存提供者不可用“跨对话记住”功能时,openclaw doctor 会报告。

快速开始

{
  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。

字段 类型 说明
embedding.provider 字符串 适配器 id,例如 openai、github-copilot、ollama。默认 openai。
embedding.model 字符串 默认 text-embedding-3-small。
embedding.apiKey 字符串 可选;支持 ${ENV_VAR} 展开和实时凭据轮换。
embedding.baseUrl 字符串 可选;支持 ${ENV_VAR} 展开和实时端点轮换。
embedding.dimensions 整数 (>=1) 对于不在内置表中的模型是必需的(见下文)。

存在两种请求路径:

  • 提供者适配器路径(默认):设置 embedding.provider 并省略 embedding.apiKey/embedding.baseUrl。插件会通过 memory-core 使用的相同内存嵌入适配器,解析提供者已配置的授权配置文件、环境变量或 models.providers.<provider>.apiKey。这是 github-copilot、ollama 以及任何其他支持嵌入的捆绑提供者的路径。
  • 直接 OpenAI 兼容客户端路径:保持 embedding.provider 未设置 (或 "openai"),并设置 embedding.apiKey 和 embedding.baseUrl。对于没有捆绑提供者适配器的原始 OpenAI 兼容嵌入端点,请使用此路径。

embedding.apiKey 和 embedding.baseUrl 会从实时插件配置中重新读取,用于下一次内存操作,只要 provider、model 和 dimensions 保持不变。

Warning

embedding.provider、embedding.model 和 embedding.dimensions 定义持久化的 LanceDB 索引身份。在更改其中任何一项之前,请规划 LanceDB 重新嵌入或重建,使每个存储行都使用新的向量空间和维度。自动插件重载会创建一个具有更改后身份的新实例;它不会重新嵌入现有行。

OpenAI 提供者适配器可以在账户授予嵌入访问权限时使用已存储的 Codex OAuth 配置文件。单独的 Sign in with ChatGPT 令牌共享授权不会授权嵌入。API 密钥授权仍可通过配置文件、OPENAI_API_KEY 或 models.providers.openai.apiKey 使用。其他支持嵌入的提供者包括 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 提供者适配器路径(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 1000 100-10000 召回查询长度以及每条经过转义、对模型可见的召回项。
captureMaxChars 500 100-10000 memory_store 输入限制和自动捕获资格。
customTriggers [] 0-50 项,每项 ≤100 字符 使自动捕获考虑某条消息的字面短语。

recallMaxChars 限制 before_prompt_build 自动召回查询、memory_recall 工具、memory_forget 查询路径以及 openclaw ltm search。自动召回会在移除媒体附件说明并规范化空白后,对当前轮次的提示进行嵌入。同一限制还会在提示转义之后、文本到达模型之前,限制每条召回项。

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

customTriggers 添加不带正则表达式的字面自动捕获短语。内置触发器覆盖常见的英语、捷克语、中文、日语和韩语记忆短语(remember、prefer、记住、覚えて、기억해 以及类似短语)。

自动捕获还会拒绝看起来像信封/传输元数据、提示注入载荷或已注入的 <relevant-memories> 上下文的文本,并且每个代理轮次最多捕获 3 条记忆。

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

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

隐身会话会跳过自动召回和捕获。它们的提示不会被发送到嵌入提供商以进行自动召回,并且 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
标志 默认值 说明
--agent <id> 已配置的默认代理 选择私有代理命名空间。可用于 list、search、query 和 stats。
--cols <columns> id,text,importance,category,createdAt 逗号分隔的列允许列表。
--filter <condition> 无 针对输出列的一次比较,例如 category = 'preference' 或 importance >= 0.8。字符串值必须加引号。
--limit <n> 10 正整数。
标志 默认值 说明
--order-by <column>:<asc\|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。

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw