OpenClaw `memory-lancedb` 技术文档

1. 概述

memory-lancedb 是 OpenClaw 的长期记忆插件，插件 ID 为 memory-lancedb，kind 为 memory。它基于 LanceDB 向量存储 + OpenAI Embeddings，提供三类能力：

记忆检索：memory_recall
记忆写入：memory_store
记忆删除：memory_forget

并支持两个生命周期自动化能力：

before_agent_start 自动召回（Auto-Recall）
agent_end 自动捕获（Auto-Capture）

源码位置：

extensions/memory-lancedb/index.ts
extensions/memory-lancedb/config.ts
extensions/memory-lancedb/openclaw.plugin.json

2. 架构图（ASCII）

+------------------------- OpenClaw Runtime -------------------------+
|                                                                    |
|   +----------------------+      register()      +----------------+ |
|   |  Plugin Loader       | -------------------> | memory-lancedb | |
|   +----------------------+                      +-------+--------+ |
|                                                        |          |
|   +----------------------+      Tools/CLI/Hooks        |          |
|   |  Agent Loop          | <----------------------------+          |
|   |  - before_agent_start|                                        |
|   |  - tool execution    |                                        |
|   |  - agent_end         |                                        |
|   +----------+-----------+                                        |
|              |                                                    |
+--------------|----------------------------------------------------+
               |
               | tool call / hook event
               v
+----------------------------- Plugin Core ------------------------------+
| +----------------------+     +----------------------+                 |
| | Embeddings (OpenAI)  |     | MemoryDB (LanceDB)  |                 |
| | - embed(text)->vec   |<--->| - store/search/delete|                |
| +----------+-----------+     +----------+-----------+                 |
|            |                              |                            |
|            v                              v                            |
|      OpenAI Embedding API           LanceDB Table: memories           |
|                                     fields:                           |
|                                     id,text,vector,importance,        |
|                                     category,createdAt                |
+------------------------------------------------------------------------+

Auto-Recall Flow:
User Prompt -> embed(prompt) -> vectorSearch(top3) -> formatRelevantMemoriesContext()
            -> prependContext 注入到模型输入

Auto-Capture Flow:
agent_end(user messages) -> shouldCapture/filter -> detectCategory
-> embed(text) -> duplicate check (score>=0.95) -> store(top3)

3. 核心模块说明

3.1 `MemoryDB`

职责：LanceDB 连接与表管理，负责持久化和向量检索。

懒初始化：ensureInitialized() + initPromise 防重入。
表名固定：memories。
首次建表会插入并删除 __schema__ 占位行，确保 schema 建立。
search() 使用 LanceDB 默认 L2 距离，并转换为相似度：score = 1 / (1 + distance)。
delete() 对 memoryId 做 UUID 格式校验，降低注入风险。

3.2 `Embeddings`

职责：调用 OpenAI embeddings 接口生成向量。

默认模型：text-embedding-3-small
支持自定义：model/baseUrl/dimensions
支持 OpenAI 兼容网关（通过 baseUrl）

3.3 自动捕获规则

shouldCapture() 只捕获“更可能是长期事实”的用户输入，避免污染：

长度限制（默认最大 500 字）
命中触发词（偏好、决定、联系方式等）
跳过注入/系统片段/agent 总结样式/emoji-heavy 文本

3.4 自动召回安全包装

formatRelevantMemoriesContext() 会把召回记忆封装在 <relevant-memories> 标签内，并显式声明“仅作为不可信历史上下文”，同时做 HTML 转义，降低 prompt injection 风险。

4. 工具接口

4.1 `memory_recall`

并显式声明“仅作为不可信历史上下文”，同时做 HTML 转义，降低 prompt injection 风险。

输入：query, limit?（默认 5）
过程：embed(query) -> db.search(vector, limit, 0.1)
输出：文本摘要 + details.memories（去除向量字段，便于序列化）

4.2 `memory_store`

输入：text, importance?（默认 0.7）, category?
去重策略：先检索 minScore=0.95，命中则返回 duplicate
未命中则写入并返回新 ID

4.3 `memory_forget`

支持按 memoryId 直接删除
支持按 query 语义查找候选后删除
当候选多条时返回候选列表让调用方二次确认

5. 生命周期钩子

5.1 `before_agent_start`（Auto-Recall）

触发条件：autoRecall=true 且 prompt 有效。

处理步骤：

对 prompt 生成 embedding
检索 top3，阈值 0.3
将结果格式化后通过 prependContext 注入

5.2 `agent_end`（Auto-Capture）

触发条件：autoCapture=true 且 agent 成功结束。

处理步骤：

仅遍历 role=user 的消息内容
文本块提取后做 shouldCapture 过滤
对每条文本分类、向量化、去重
每轮最多写入 3 条

6. CLI 能力

插件注册了 ltm 命令组：

openclaw ltm list：记忆总量
openclaw ltm search <query> [--limit n]：语义检索
openclaw ltm stats：统计信息

7. 配置说明

配置 schema 定义在 config.ts 与 openclaw.plugin.json。

必填项：

embedding.apiKey

关键配置：

embedding.model：默认 text-embedding-3-small
embedding.baseUrl：可对接兼容端点
embedding.dimensions：自定义维度（非标准模型时建议显式配置）
dbPath：默认 ~/.openclaw/memory/lancedb
autoCapture：默认 false
autoRecall：默认 true
captureMaxChars：默认 500，范围 [100,10000]

环境变量替换：支持 ${ENV_VAR} 形式。

8. 数据模型

MemoryEntry 字段：

id: string（UUID）
text: string
vector: number[]
importance: number（0~1）
category: preference|fact|decision|entity|other
createdAt: number（epoch ms）

9. 启用方式

在 OpenClaw 配置里将 memory 槽位切换为 memory-lancedb：

{
  "plugins": {
    "slots": {
      "memory": "memory-lancedb"
    },
    "entries": {
      "memory-lancedb": {
        "enabled": true,
        "config": {
          "embedding": {
            "apiKey": "${OPENAI_API_KEY}",
            "model": "text-embedding-3-small"
          },
          "autoRecall": true,
          "autoCapture": true,
          "captureMaxChars": 500
        }
      }
    }
  }
}

10. 实现特点与注意事项

优点：
- 与 Agent 生命周期深度集成，自动召回/自动捕获闭环。
- 去重和分类策略内置，开箱即可用。
- 对召回内容做了不可信上下文隔离，安全性比直接拼接更好。
风险/限制：
- 当前 embeddings provider 固定为 OpenAI 协议（provider: "openai"）。
- MemoryDB.search 当前主要依赖向量相似度，尚无 metadata 过滤。
- memory_forget(query) 多候选时需外层交互确认，自动化删除要谨慎。

11. 测试覆盖（`index.test.ts`）

已覆盖的关键点：

插件注册与 schema 解析
环境变量替换
captureMaxChars 校验
dimensions 参数是否透传到 embeddings API
shouldCapture、looksLikePromptInjection、formatRelevantMemoriesContext 行为

OpenClaw memory-lancedb 技术文档