记忆 LanceDB
memory-lancedb 是一个官方外部插件,使用 LanceDB 和向量搜索存储长期记忆。它可以在模型回合前自动召回相关记忆,并在响应后自动捕获重要事实。
将其用于本地向量数据库、OpenAI 兼容的嵌入端点,或默认内置内存后端之外的内存存储。
安装¶
该插件已发布到 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 离线,请在配置后启动它。检查应用结果并检查插件的运行时注册:
嵌入配置¶
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。
故障排除¶
输入长度超过上下文长度¶
嵌入模型拒绝了召回查询:
降低 recallMaxChars;新限制将应用于下一次记忆操作:
对于 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,然后运行:
如果禁用了 autoCapture,插件仍会召回现有记忆,但不会自动存储新记忆。请使用 memory_store 工具,或启用 autoCapture。
相关¶
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw