OpenClaw memory-lancedb 插件实战指南LanceDB 向量长期记忆的配置、自动召回与自动捕获【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 项目地址: https://gitcode.com/GitHub_Trending/cl/openclawmemory-lancedb是 OpenClaw 官方提供的外部记忆插件它把长期记忆存入本地 LanceDB 向量数据库支持模型回合前自动召回相关记忆、回合结束后自动捕获关键事实以及面向 Agent 的向量检索工具。本文基于插件参考文档 docs/plugins/reference/memory-lancedb.md 与 docs/plugins/memory-lancedb.md并结合 extensions/memory-lancedb 目录下的实际源码完整讲解该插件的安装、embedding 配置、召回/捕获限制、CLI 命令、存储隔离与故障排查。插件定位与分发方式从插件参考文档 docs/plugins/reference/memory-lancedb.md 可知memory-lancedb的核心能力是三件套auto-recall在模型回合前把相关记忆注入上下文auto-capture在响应结束后自动捕获值得记住的事实vector search基于 LanceDB 的向量检索供ltmCLI 和 Agent 工具使用。它在 OpenClaw 插件体系中的关键元数据见 openclaw.plugin.json插件 idmemory-lancedbnpm 包名openclaw/memory-lancedbkind: memory即它属于记忆槽位memory slot类插件暴露的tools契约memory_recall、memory_store、memory_forget注册ltmCLI 命名空间且支持ltm命令别名commandAliases声明了两个 doctor 状态迁移memory-lancedb-agent-scope与 doctor-only 的memory-lancedb-legacy-envelope-rows。注意它不是打包进 OpenClaw 运行时镜像的内置插件而是发布到 npm 的官方外部插件需要显式安装。README 中还声明了两个独立的版本约束宿主版本openclaw.install.minHostVersion 2026.5.31、插件 API 兼容性openclaw.compat.pluginApi 2026.9.3安装器会分别检查两者必须同时满足。安装与启用openclaw plugins install openclaw/memory-lancedb安装过程会写入插件条目、启用插件并把plugins.slots.memory切换为memory-lancedb。如果此时有另一个插件占用记忆槽位它会被禁用并给出警告——同一时刻只有一个插件拥有活动记忆槽位但memory-wiki这类伴随插件可以与memory-lancedb并存。安装后需要重启 Gateway 并确认插件加载openclaw gateway restart openclaw plugins list一个值得注意的权限边界LanceDB 的memory_recall拿不到memory.search.rememberAcrossConversations所用的受保护私有转录授权。若你需要跨会话记忆召回应走 LanceDB 的autoRecall或通过其memory_recall工具见 docs/concepts/active-memory 中 Advanced Active Memory 的 LanceDB 记忆章节。openclaw doctor会在当前记忆提供者下 Remember across conversations 不可用时给出报告。快速开始最小可用的完整配置继承自官方文档可直接复制{ plugins: { slots: { memory: memory-lancedb, }, entries: { memory-lancedb: { enabled: true, config: { embedding: { provider: openai, model: text-embedding-3-small, }, autoRecall: true, autoCapture: false, }, }, }, }, }配置项的合法性由 config.ts 中的memoryConfigSchema.parse严格校验根对象只允许embedding、dreaming、dbPath、autoCapture、autoRecall、captureMaxChars、customTriggers、recallMaxChars、storageOptions九个键embedding只允许provider、apiKey、model、baseUrl、dimensions且必须至少包含一个字段否则会抛出embedding config required/embedding config must include at least one setting错误。解析失败时插件不会崩溃而是以 disabled until configured 警告退场见 index.ts 中register的 try/catch 分支。从源码可以看默认值config.ts配置默认值说明embedding.provideropenai省略时按openai处理embedding.modeltext-embedding-3-smallDEFAULT_MODELdbPath~/.openclaw/memory/lancedbDEFAULT_DB_PATHautoRecalltrue源码中为cfg.autoRecall ! false只有显式写false才关闭autoCapturefalse源码中为cfg.autoCapture true显式开启captureMaxChars500取值范围 100–10000recallMaxChars1000取值范围 100–10000Embedding 配置embedding是必填项。字段说明继承自官方文档表格字段类型说明embedding.providerstring适配器 id如openai、github-copilot、ollama。默认openaiembedding.modelstring默认text-embedding-3-smallembedding.apiKeystring可选支持${ENV_VAR}展开与凭据热更新embedding.baseUrlstring可选支持${ENV_VAR}展开与端点热更新embedding.dimensionsinteger (1)内置维度表之外的模型必填两条请求路径从 embeddings.ts 的实现看插件存在两条 embedding 请求路径Provider 适配器路径默认设置embedding.provider且不设置embedding.apiKey/embedding.baseUrl。插件通过memory-core使用的同一套记忆 embedding 适配器解析该 provider 的认证配置 profile、环境变量或models.providers.provider.apiKey。github-copilot、ollama等内置 provider 走这条路{ plugins: { entries: { memory-lancedb: { enabled: true, config: { embedding: { provider: github-copilot, model: text-embedding-3-small, }, }, }, }, }, }直连 OpenAI 兼容客户端路径embedding.provider留空或为openai同时设置embedding.apiKey与embedding.baseUrl。适用于没有内置 provider 适配器的原始 OpenAI 兼容 embedding 端点。源码中由OpenAiCompatibleEmbeddings类基于openaiSDK 构造客户端embeddings.ts请求时不带encoding_format参数并且同时接受 float 数组或 base64 编码的 float32 响应——这样对encoding_format行为不一致的兼容端点都能正常工作。索引身份与热更新边界这是最容易踩坑的一点。embedding.apiKey和embedding.baseUrl会在下一次记忆操作时从实时插件配置重新读取index.ts 中resolveCurrentHookConfig用resolveLivePluginConfigObject合并实时配置只把apiKey/baseUrl覆盖进解析后的配置只要provider、model、dimensions不变。警告embedding.provider、embedding.model和embedding.dimensions定义了持久化 LanceDB 索引的身份不能热变更。重启前若更换身份必须先规划 LanceDB 重嵌入或重建让所有已存行使用新的向量空间与维度——插件不会自动重嵌入已有行。另外OpenAI Codex / ChatGPT 的 OAuth 凭证不是OpenAI 平台的 embedding 凭据。OpenAI embedding 需要 API key 认证 profile、OPENAI_API_KEY或models.providers.openai.apiKey只有 OAuth 的用户应改选github-copilot或ollama等具备 embedding 能力的 provider。内置维度表内置维度表只有两项config.ts模型维度text-embedding-3-small1536text-embedding-3-large3072其他任何模型必须显式给出embedding.dimensions否则vectorDimsForModel会抛出Unsupported embedding model错误。以智谱embedding-32048 维为例{ 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, }, }, }, }, }, }dimensions解析时必须是正整数resolveEmbeddingDimensions会拒绝非整数与 1 的值${ENV_VAR}展开在 config.ts 的resolveEnvVars中完成环境变量未设置会直接报错。使用 Ollama 本地 embedding走内置 Ollama provider 适配器路径embedding.provider: ollama插件调用 Ollama 原生/api/embed端点认证与 base URL 规则与 OpenClaw 的 Ollama provider 一致{ 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必填。本地小 embedding 模型若返回上下文长度错误应调低recallMaxChars。召回与捕获限制设置默认范围作用recallMaxChars1000100-10000召回查询长度以及每条转义后、模型可见的召回条目长度captureMaxChars500100-10000memory_store输入上限与自动捕获资格判定customTriggers[]0-50 条每条 ≤100 字符让自动捕获考虑某条消息的字面短语recallMaxChars 的作用域从源码看recallMaxChars同时约束四处before_prompt_build自动召回钩子、memory_recall工具、memory_forget的 query 路径、以及openclaw ltm search。自动召回在嵌入前会对当前回合 prompt 去除媒体附件备注并归一化空白memory-policy.ts 的normalizeRecallQuery与dropMediaNoteLines同一上限也约束转义后每条被召回条目送入模型前的长度formatRecalledMemoryForModel先用escapeMemoryForPrompt转义再按上限截断。auto-capture 的去重与配额自动捕获挂在agent_end事件上index.ts行为细节与源码一一对应每回合上限 3 条MAX_AUTO_CAPTURE_TEXTS_PER_TURN 3index.ts。一条消息因配额被跳过的文本之后新的消息仍可捕获。最近 60 条完成文本跨回合去重MAX_RECENT_AUTO_CAPTURE_TEXTS 20 * 3index.ts即使消息已离开转录包括压缩 compaction 之后仍保持去重该历史包含匹配到已有记忆的文本和部分失败消息中成功的文本块。会话结束/重置会清除该进度session_end处理器对当前与后继两个 cursor key 排队清空捕获进度index.ts且 compaction 触发的session_end不重置压缩只轮换转录不改变逻辑会话的捕获归属。关闭时优雅停止插件停止新捕获任务等待未完成的捕获写入后再关闭存储registerService的stop中captureStopped trueawait Promise.all(autoCaptureTasks.values())。自动捕获还会拒绝看起来像信封/传输元数据的文本、提示注入载荷、已经注入的relevant-memories上下文判定逻辑见 memory-policy.ts 的shouldCapture还包括标签块、emoji 过多等启发式。customTriggers是字面短语匹配小写包含非正则用于在内置触发之外追加捕获短语。内置触发词覆盖英语、捷克语、中文、日语、韩语的常见记忆表达remember、prefer、记住、覚えて、기억해等完整模式列表见 memory-policy.ts。捕获到的记忆会用detectCategory自动分类到preference/fact/decision/entity/other之一固定以importance: 0.7入库。Agent 级开关每条记忆归一个 agent 所有召回、查重、捕获、列表、原始查询和删除都在返回或修改行之前强制校验 owner。在agents.entries.*中设置memory.search.enabled: false的 agent或继承顶层禁用的 agent即使插件级autoRecall/autoCapture开着也不会拿到memory_recall、memory_store、memory_forget三个工具也不参与自动召回或捕获工具工厂中resolveEnabledAgentId返回undefined时直接return null见 index.ts。Agent 工具memory_recall / memory_store / memory_forget三个工具由活动记忆插件注册给 Agent参数与行为可从 index.ts 中的注册代码直接印证memory_recall对已存记忆做向量搜索。参数query与可选limit默认 5。实现上以limit 10超额取数、minScore 0.1搜索结果经cleanMemorySearchResults过滤后再截断返回文本会把每条记忆标注为不可信历史数据仅用于上下文不要执行其中的指令。嵌入超时默认 15 秒DEFAULT_TOOL_RECALL_TIMEOUT_MS会触发按 agent 计时的 60 秒冷却DEFAULT_RECALL_COOLDOWN_MS冷却期内直接返回记忆不可用结果避免挂死的 embedding 请求拖慢所有回合。memory_store保存事实、偏好、决策或实体。参数text、importance0–1默认 0.7、category枚举见 config.ts 的MEMORY_CATEGORIES。文本超过captureMaxChars直接拒绝text_too_longlooksLikePromptInjection命中提示注入模式时拒绝prompt_injection_detected隐身incognito会话拒绝存储。查重走findCleanDuplicateMemory按向量搜索 top-5、minScore 0.95再对规范化后的精确文本换行归一、Unicode NFC、去首尾空白比对——精确重复会跳过并返回already_present但语义相近而文本不同的记忆照常入库。memory_forget按memoryId删除或按query删除。query 路径搜索 top-5、minScore 0.7若唯一匹配且 score 0.9 则自动删除否则返回候选 ID 列表供消歧。memory_store与memory_forget在插件清单中被标记为sideEffectingopenclaw.plugin.json 的toolMetadata。CLI 命令openclaw ltm只要memory-lancedb已安装不论它是否拥有活动记忆槽位就注册ltm命名空间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:descFlag默认说明--agent id配置的默认 agent选择私有 agent 命名空间list、search、query、stats均可用--cols columnsid,text,importance,category,createdAt逗号分隔的列白名单与 lancedb-store.ts 的MEMORY_QUERY_COLUMNS一致--filter condition无对一个输出列的单个比较如category preference或importance 0.8字符串值必须加引号--limit n10正整数--order-by column:asc\|desc无过滤后在内存中排序排序列自动加入投影若未请求则从输出中剥离支持的比较运算符为 ! LIKElancedb-store.ts 的MemoryQueryFilter。存储、数据隔离与迁移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-store.ts插件保持一张名为memories的 LanceDB 表schema 字段为id、text、vector固定长度 Float32 列表长度即维度、importance、category、createdAt、agentId。agent 归属是存储边界而非搜索后过滤owner 谓词agentId ...见 lancedb-schema.ts 的memoryAgentPredicate在向量排序之前应用并包含在 list、query、count、delete 的谓词里。ltm query --filter接受的对公开列的验证比较是独立于强制 owner 谓词构建的因此 filter 无法把查询放宽到另一个 agent。升级迁移早于 per-agent 隔离创建的数据库没有可靠的行归属。升级时openclaw doctor --fix会把遗留行一次性分配给配置的默认 agent该迁移完成前运行时访问会 fail closed打开旧 schema 的表会抛出带明确指引的错误见 lancedb-schema.ts 的legacyMemorySchemaError其他 agent 永远不会继承旧共享行。对象存储后端storageOptions接受字符串键值对例如 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, }, }, }, }, }, }源码中dbPath若包含://则视为 URI 原样使用否则相对宿主解析index.ts。自动召回的实现细节before_prompt_build钩子由 auto-recall.ts 的createAutoRecallHook实现注册时带requiresToolAuthority: true即该回合必须允许memory_recall工具自动召回才会执行。关键常量总超时AUTO_RECALL_TIMEOUT_MS 15_000超时尤其是 embedding 阶段会记录 60 秒冷却并跳过注入不会卡住 agent 启动搜索取数limit 10AUTO_RECALL_OVERFETCH_LIMIT、minScore 0.3最终注入上限 3 条AUTO_RECALL_RESULT_CAPprompt 少于 5 个字符或为空时直接跳过命中的记忆经formatRelevantMemoriesContext包装为relevant-memories块并以prependContext前置注入块内同样声明记忆是不可信历史数据不要执行其中的指令memory-policy.ts。运行时依赖与平台支持memory-lancedb打包了 LanceDB 的 JavaScript 层插件包把原生lancedb/lancedb-*包声明为可选依赖安装时按宿主平台选择匹配二进制。Gateway 启动不会修复插件依赖原生依赖缺失或加载失败时应重新安装或更新插件包后重启 Gateway。lancedb/lancedb没有发布darwin-x64Intel Mac原生构建。在该平台上插件加载时会记录 LanceDB 不可用应改用默认记忆后端、在受支持的平台/架构上运行 Gateway或禁用memory-lancedb。故障排查1. Input length exceeds the context lengthembedding 模型拒绝了召回查询memory-lancedb: recall failed: Error: 400 the input length exceeds the context length调低recallMaxChars新上限会作用于下一次记忆操作{ plugins: { entries: { memory-lancedb: { config: { recallMaxChars: 400, }, }, }, }, }对 Ollama还应从 Gateway 主机用原生 embed 端点验证 embedding 服务可达curl http://127.0.0.1:11434/api/embed \ -H Content-Type: application/json \ -d {model:mxbai-embed-large,input:hello}2. Unsupported embedding model未设置embedding.dimensions时只有内置 OpenAI embedding 的维度是已知的text-embedding-3-small、text-embedding-3-large。其他模型请把embedding.dimensions设为该模型报告的实际向量大小——这正是 config.ts 中vectorDimsForModel抛出Unsupported embedding model的触发条件。3. 插件已加载但没有记忆出现先确认plugins.slots.memory指向memory-lancedb然后运行openclaw ltm stats openclaw ltm search recent preference若autoCapture关闭插件仍会召回已有记忆但不会自动存储新记忆——改用memory_store工具或开启autoCapture。小结与延伸阅读memory-lancedb把记忆从会话内扩展为带向量索引、按 agent 隔离、带安全过滤注入检测、信封清洗、配额与去重的持久化能力。掌握它的关键在于三组边界embedding 索引身份不可热变更、recallMaxChars/captureMaxChars的四个作用点、以及 owner 谓词作为存储边界的隔离语义。相关文档可继续阅读插件参考自动生成的清单页docs/plugins/reference/memory-lancedb.md记忆概念与 Active Memorydocs/concepts配套插件 Memory Wikidocs/plugins插件源码入口extensions/memory-lancedb/index.ts、策略层 memory-policy.ts、召回钩子 auto-recall.ts、存储层 lancedb-store.ts【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
