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 restartopenclaw 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 创建向量列，例如维度为 2048 的智谱 embedding-3：

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

命令

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

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

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

openclaw ltm query --cols id,text,createdAt --limit 20openclaw 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",          },        },      },    },  },}

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/lancedb 包，该依赖由插件包拥有，而不属于 OpenClaw 核心发行版。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，然后重启 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 statsopenclaw ltm search "recent preference"

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

相关内容

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