🧠 memory-lancedb-pro · OpenClaw Plugin

📺 视频教程

观看完整教程 — 涵盖安装、配置，以及混合检索的底层原理。

🔗 https://youtu.be/MtukF1C8epQ

🔗 https://www.bilibili.com/video/BV1zUf2BGEgn/

为什么需要这个插件？

OpenClaw 内置的 memory-lancedb 插件仅提供基本的向量搜索。memory-lancedb-pro 在此基础上进行了全面升级：

架构概览

┌─────────────────────────────────────────────────────────┐
│                   index.ts (入口)                        │
│  插件注册 · 配置解析 · 生命周期钩子 · 自动捕获/回忆       │
└────────┬──────────┬──────────┬──────────┬───────────────┘
         │          │          │          │
    ┌────▼───┐ ┌────▼───┐ ┌───▼────┐ ┌──▼──────────┐
    │ store  │ │embedder│ │retriever│ │   scopes    │
    │ .ts    │ │ .ts    │ │ .ts    │ │    .ts      │
    └────────┘ └────────┘ └────────┘ └─────────────┘
         │                     │
    ┌────▼───┐           ┌─────▼──────────┐
    │migrate │           │noise-filter.ts │
    │ .ts    │           │adaptive-       │
    └────────┘           │retrieval.ts    │
                         └────────────────┘
    ┌─────────────┐   ┌──────────┐
    │  tools.ts   │   │  cli.ts  │
    │ (Agent API) │   │ (CLI)    │
    └─────────────┘   └──────────┘

文件说明

核心特性

1. 混合检索 (Hybrid Retrieval)

Query → embedQuery() ─┐
                       ├─→ RRF 融合 → Rerank → 时效加成 → 重要性加权 → 过滤
Query → BM25 FTS ─────┘

• 向量搜索: 语义相似度搜索（cosine distance via LanceDB ANN）
• BM25 全文搜索: 关键词精确匹配（LanceDB FTS 索引）
• 融合策略: Vector score 为基础，BM25 命中给予 15% 加成（非传统 RRF，经过调优）
• 可配置权重: vectorWeight、bm25Weight、minScore

2. 跨编码器 Rerank

• Jina Reranker API: jina-reranker-v2-base-multilingual（5s 超时保护）
• 混合评分: 60% cross-encoder score + 40% 原始融合分
• 降级策略: API 失败时回退到 cosine similarity rerank

3. 多层评分管线

4. 多 Scope 隔离

• 内置 Scope 模式: global、agent:<id>、custom:<name>、project:<id>、user:<id>
• Agent 级访问控制: 通过 scopes.agentAccess 配置每个 Agent 可访问的 Scope
• 默认行为: Agent 可访问 global + 自己的 agent:<id> Scope

5. 自适应检索

• 跳过不需要记忆的 query（问候、slash 命令、简单确认、emoji）
• 强制检索含记忆相关关键词的 query（"remember"、"之前"、"上次"等）
• 支持 CJK 字符的更低阈值（中文 6 字符 vs 英文 15 字符）

6. 噪声过滤

在自动捕获和工具存储阶段同时生效：

• 过滤 Agent 拒绝回复（"I don't have any information"）
• 过滤 Meta 问题（"do you remember"）
• 过滤寒暄（"hi"、"hello"、"HEARTBEAT"）

7. Session 记忆

• /new 命令触发时可保存上一个 Session 的对话摘要到 LanceDB
• 默认关闭（enabled: false），因为 OpenClaw 已有原生 .jsonl 会话保存
• 开启会导致大段摘要污染检索质量，建议仅在需要语义搜索历史会话时开启
• 可配置消息数量（默认 15 条）

8. 自动捕获 & 自动回忆

• Auto-Capture（agent_end hook）: 从对话中提取 preference/fact/decision/entity，去重后存储（每次最多 3 条）
• Auto-Recall（before_agent_start hook）: 注入 <relevant-memories> 上下文（最多 3 条）

安装

什么是 “OpenClaw workspace”？

在 OpenClaw 中，agent workspace（工作区） 是 Agent 的工作目录（默认：~/.openclaw/workspace）。 根据官方文档，workspace 是 OpenClaw 的 默认工作目录（cwd），因此 相对路径会以 workspace 为基准解析（除非你使用绝对路径）。

说明：OpenClaw 的配置文件通常在 ~/.openclaw/openclaw.json，与 workspace 是分开的。

最常见的安装错误： 把插件 clone 到别的目录，但在配置里仍然写 "paths": ["plugins/memory-lancedb-pro"]（这是相对路径）。OpenClaw 会去 workspace 下找 plugins/memory-lancedb-pro，导致加载失败，于是出现“安装位置不对”的反馈。

方案 A（推荐）：克隆到 workspace 的 plugins/ 目录下

# 1) 进入你的 OpenClaw workspace（默认：~/.openclaw/workspace）
#    （可通过 agents.defaults.workspace 改成你自己的路径）
cd /path/to/your/openclaw/workspace

# 2) 把插件克隆到 workspace/plugins/ 下
git clone https://github.com/win4r/memory-lancedb-pro.git plugins/memory-lancedb-pro

# 3) 安装依赖
cd plugins/memory-lancedb-pro
npm install

然后在 OpenClaw 配置（openclaw.json）中使用相对路径：

{
  "plugins": {
    "load": {
      "paths": ["plugins/memory-lancedb-pro"]
    },
    "entries": {
      "memory-lancedb-pro": {
        "enabled": true,
        "config": {
          "embedding": {
            "apiKey": "${JINA_API_KEY}",
            "model": "jina-embeddings-v5-text-small",
            "baseURL": "https://api.jina.ai/v1",
            "dimensions": 1024,
            "taskQuery": "retrieval.query",
            "taskPassage": "retrieval.passage",
            "normalized": true
          }
        }
      }
    },
    "slots": {
      "memory": "memory-lancedb-pro"
    }
  }
}

方案 B：插件装在任意目录，但配置里必须写绝对路径

{
  "plugins": {
    "load": {
      "paths": ["/absolute/path/to/memory-lancedb-pro"]
    }
  }
}

重启

openclaw gateway restart

注意： 如果之前使用了内置的 memory-lancedb，启用本插件时需同时禁用它。同一时间只能有一个 memory 插件处于活动状态。

验证是否安装成功（推荐）

1）确认插件已被发现/加载：

openclaw plugins list
openclaw plugins info memory-lancedb-pro

2）如果发现异常，运行插件诊断：

openclaw plugins doctor

3）确认 memory slot 已指向本插件：

# 期望看到：plugins.slots.memory = "memory-lancedb-pro"
openclaw config get plugins.slots.memory

配置

{
  "embedding": {
    "apiKey": "${JINA_API_KEY}",
    "model": "jina-embeddings-v5-text-small",
    "baseURL": "https://api.jina.ai/v1",
    "dimensions": 1024,
    "taskQuery": "retrieval.query",
    "taskPassage": "retrieval.passage",
    "normalized": true
  },
  "dbPath": "~/.openclaw/memory/lancedb-pro",
  "autoCapture": true,
  "autoRecall": true,
  "retrieval": {
    "mode": "hybrid",
    "vectorWeight": 0.7,
    "bm25Weight": 0.3,
    "minScore": 0.3,
    "rerank": "cross-encoder",
    "rerankApiKey": "jina_xxx",
    "rerankModel": "jina-reranker-v2-base-multilingual",
    "candidatePoolSize": 20,
    "recencyHalfLifeDays": 14,
    "recencyWeight": 0.1,
    "filterNoise": true,
    "lengthNormAnchor": 500,
    "hardMinScore": 0.35,
    "timeDecayHalfLifeDays": 60
  },
  "enableManagementTools": false,
  "scopes": {
    "default": "global",
    "definitions": {
      "global": { "description": "共享知识库" },
      "agent:discord-bot": { "description": "Discord 机器人私有" }
    },
    "agentAccess": {
      "discord-bot": ["global", "agent:discord-bot"]
    }
  },
  "sessionMemory": {
    "enabled": false,
    "messageCount": 15
  }
}

Embedding 提供商

本插件支持 任意 OpenAI 兼容的 Embedding API：

CLI 命令

# 列出记忆
openclaw memory-pro list [--scope global] [--category fact] [--limit 20] [--json]

# 搜索记忆
openclaw memory-pro search "query" [--scope global] [--limit 10] [--json]

# 查看统计
openclaw memory-pro stats [--scope global] [--json]

# 按 ID 删除记忆（支持 8+ 字符前缀）
openclaw memory-pro delete <id>

# 批量删除
openclaw memory-pro delete-bulk --scope global [--before 2025-01-01] [--dry-run]

# 导出 / 导入
openclaw memory-pro export [--scope global] [--output memories.json]
openclaw memory-pro import memories.json [--scope global] [--dry-run]

# 使用新模型重新生成 Embedding
openclaw memory-pro reembed --source-db /path/to/old-db [--batch-size 32] [--skip-existing]

# 从内置 memory-lancedb 迁移
openclaw memory-pro migrate check [--source /path]
openclaw memory-pro migrate run [--source /path] [--dry-run] [--skip-existing]
openclaw memory-pro migrate verify [--source /path]

数据库 Schema

LanceDB 表 memories：

依赖

License

MIT

Buy Me a Coffee

我的微信群和微信二维码