memory-lancedb-pro

memory-lancedb-pro 插件维护指南

概述

memory-lancedb-pro 是一款面向 OpenClaw 的增强型长期记忆插件。它以高级检索能力、多范围记忆隔离和管理 CLI 取代内置的 memory-lancedb 插件。

仓库：https://github.com/win4r/memory-lancedb-pro 许可证：MIT | 语言：TypeScript（ESM）| 运行时：通过 OpenClaw Gateway 运行的 Node.js

架构

┌─────────────────────────────────────────────────────────┐
│                   index.ts (Entry Point)                │
│  Plugin Registration · Config Parsing · Lifecycle Hooks │
└────────┬──────────┬──────────┬──────────┬───────────────┘
         │          │          │          │
    ┌────▼───┐ ┌────▼───┐ ┌───▼────┐ ┌──▼──────────┐
    │ store  │ │embedder│ │retriever│ │   scopes    │
    │ .ts    │ │ .ts    │ │ .ts    │ │    .ts      │
    └────────┘ └────────┘ └────────┘ └─────────────┘
         │                     │
    ┌────▼───┐           ┌─────▼──────────┐
    │migrate │           │noise-filter.ts │
    │ .ts    │           │adaptive-       │
    └────────┘           │retrieval.ts    │
                         └────────────────┘
    ┌─────────────┐   ┌──────────┐
    │  tools.ts   │   │  cli.ts  │
    │ (Agent API) │   │ (CLI)    │
    └─────────────┘   └──────────┘

文件参考（快速导航）

文件	用途	主要导出项
index.ts	插件入口。向 OpenClaw Plugin API 注册、解析配置、挂载生命周期钩子	memoryLanceDBProPlugin（默认）、shouldCapture、detectCategory
openclaw.plugin.json	插件元数据 + 完整的 JSON Schema 配置，包含 uiHints	—
package.json	NPM 包。依赖项：@lancedb/lancedb、openai、@sinclair/typebox	—
cli.ts	CLI：memory-pro list/search/stats/delete/delete-bulk/export/import/reembed/migrate	createMemoryCLI、registerMemoryCLI
src/store.ts	LanceDB 存储层。表创建、FTS 索引、CRUD、向量/BM25 搜索	MemoryStore、MemoryEntry、loadLanceDB
src/embedder.ts	嵌入抽象层。兼容 OpenAI 的 API、任务感知、LRU 缓存	Embedder、createEmbedder、getVectorDimensions
src/retriever.ts	混合检索引擎。完整评分流程	MemoryRetriever、createRetriever、DEFAULT_RETRIEVAL_CONFIG
src/scopes.ts	多范围访问控制	MemoryScopeManager、createScopeManager
src/tools.ts	Agent 工具定义：memory_recall/store/forget/update/stats/list	registerAllMemoryTools
src/noise-filter.ts	低质量内容噪声过滤器	isNoise、filterNoise
src/adaptive-retrieval.ts	对问候语、命令、表情符号跳过检索	shouldSkipRetrieval
src/migrate.ts	从旧版 memory-lancedb 迁移	MemoryMigrator、createMigrator
scripts/jsonl_distill.py	JSONL 会话提炼脚本（Python）	—

核心子系统参考

如需深入了解各个子系统，请阅读相应的参考文件：

• 检索流程（评分计算、RRF 融合、重排、所有评分阶段）：参见 references/retrieval_pipeline.md
• 存储与数据模型（LanceDB Schema、FTS 索引、CRUD、向量维度）：参见 references/storage_and_schema.md
• 嵌入系统（提供方、任务感知 API、缓存、维度）：参见 references/embedding_system.md
• 插件生命周期与配置（钩子、注册、配置解析）：参见 references/plugin_lifecycle.md
• 范围系统（多范围隔离、Agent 访问、模式）：参见 references/scope_system.md
• 工具与 CLI（Agent 工具、CLI 命令、参数）：参见 references/tools_and_cli.md
• 常见问题与故障排除：参见 references/troubleshooting.md

开发工作流

添加新的嵌入提供方

1. 检查它是否兼容 OpenAI（大多数都兼容）。如果兼容，无需更改代码，只需配置
2. 如果模型不在 src/embedder.ts 的 EMBEDDING_DIMENSIONS 映射中，将其添加进去
3. 如果提供方需要 task 和 normalized 之外的特殊请求字段，请扩展 src/embedder.ts 中的 buildPayload()
4. 使用 embedder.test() 方法测试
5. 在 README.md 表格中记录该提供方

添加新的重排提供方

1. 将提供方名称添加到 src/retriever.ts 中的 RerankProvider 类型
2. 在 buildRerankRequest() 中添加对应分支，处理请求格式（标头 + 正文）
3. 在 parseRerankResponse() 中添加对应分支，解析响应
4. 将其添加到 openclaw.plugin.json 的 rerankProvider 枚举中
5. 使用实际 API 调用进行测试——重排器设有 5s 超时保护

添加新的评分阶段

1. 在 MemoryRetriever 中创建 private apply<StageName>(results: RetrievalResult[]): RetrievalResult[] 方法
2. 为 RetrievalConfig 接口添加相应的配置字段
3. 在 hybridRetrieval() 和 vectorOnlyRetrieval() 中的管道顺序里插入该阶段
4. 为 DEFAULT_RETRIEVAL_CONFIG 添加默认值
5. 为 openclaw.plugin.json 添加 JSON Schema 字段
6. 管道顺序：Fusion → Rerank → Recency → Importance → LengthNorm → TimeDecay → HardMin → Noise → MMR

添加新的 Agent 工具

1. 在 src/tools.ts 中创建 registerMemory<ToolName>Tool()
2. 使用 @sinclair/typebox 中的 Type.Object() 定义参数
3. 枚举参数使用 openclaw/plugin-sdk 中的 stringEnum()
4. 始终通过 context.scopeManager 验证作用域访问权限
5. 在 registerAllMemoryTools() 中注册——决定将其设为核心工具（始终启用）还是管理工具（可选）
6. 返回 { content: [{ type: "text", text }], details: {...} }

添加新的 CLI 命令

1. 在 cli.ts 的 registerMemoryCLI() 中添加命令
2. 格式：memory.command("name <args>").description("...").option("--flag", "...").action(async (args, opts) => { ... })
3. 支持 --json 标志，以输出机器可读内容
4. 出错时使用 process.exit(1)
5. CLI 通过 index.ts 中的 api.registerCli() 注册

修改自动捕获逻辑

1. index.ts 中的 shouldCapture(text) 控制自动捕获的内容
2. MEMORY_TRIGGERS 正则表达式数组定义触发模式（支持 EN/CJK）
3. detectCategory(text) 将捕获内容归类为 preference/fact/decision/entity/other
4. 自动捕获在 agent_end 钩子中运行，每轮最多捕获 3 条
5. 重复检测阈值：余弦相似度 > 0.95

修改自动回忆逻辑

1. 自动回忆使用 before_agent_start 钩子（默认关闭）
2. src/adaptive-retrieval.ts 中的 shouldSkipRetrieval() 控制是否执行检索
3. 注入为 <relevant-memories> XML 块，并附带不可信数据警告
4. sanitizeForContext() 会移除 HTML 和换行符，并将每条记忆限制在 300 个字符以内
5. 每轮最多注入 3 条记忆

关键设计决策

• autoRecall 默认关闭——防止模型复述注入的记忆上下文
• autoCapture 默认开启——透明地累积记忆
• sessionMemory 默认关闭——原始会话摘要会降低检索质量；请改用 JSONL 提炼
• LanceDB 动态导入——异步加载以避免阻塞；在单例 Promise 中缓存
• 启动检查采用即发即弃方式——网关立即绑定 HTTP 端口；嵌入和检索测试在后台运行，超时时间为 8s
• 每日 JSONL 备份——间隔 24h，保留最近 7 个文件，启动 1 min 后运行
• BM25 分数归一化——原始 BM25 分数没有上限，使用 sigmoid 归一化：1 / (1 + exp(-score/5))
• 更新 = 删除 + 重新添加——LanceDB 不支持原地更新
• ID 前缀匹配——长度为 8 个或以上十六进制字符的前缀会解析为完整 UUID，方便用户使用
• 兼顾 CJK 字符的阈值——中文、日文和韩文文本采用更短的最小长度（4–6 个字符，英文为 10–15 个字符）
• 环境变量解析——在解析配置时解析 ${VAR} 语法；网关服务可能不会继承 shell 环境变量

测试

• 冒烟测试：node test/cli-smoke.mjs
• 手动验证：openclaw plugins doctor、openclaw memory-pro stats
• 嵌入测试：embedder.test() 返回 { success, dimensions, error? }
• 检索测试：retriever.test() 返回 { success, mode, hasFtsSupport, error? }