memory-lancedb-pro 是 OpenClaw 的增强型长期记忆插件，用于替代内置的 memory-lancedb 插件，提供高级检索能力、多作用域记忆隔离以及管理 CLI。仓库地址为 https://github.com/win4r/memory-lancedb-pro，采用 MIT 许可，语言为 TypeScript（ESM），通过 OpenClaw Gateway 在 Node.js 上运行。
用途 该插件为 OpenClaw 提供长期记忆的存储、检索与管理能力，适合需要跨会话保留偏好、事实、决策与实体信息的场景。它通过混合检索、作用域隔离和噪声过滤提升记忆质量，并附带 CLI 与 Agent 工具用于维护和调试。
主要能力
- 混合检索：结合向量搜索与 BM25 全文检索，检索管线包含融合、重排、时效性、重要性、长度归一化、时间衰减、硬性最小值、噪声过滤与 MMR 等阶段。
- 多作用域隔离：通过 MemoryScopeManager 实现多作用域访问控制。
- 嵌入系统：支持 OpenAI 兼容 API，具备任务感知与 LRU 缓存。
- 噪声过滤与自适应检索：过滤低质量内容，对问候、命令、表情等跳过检索。
- 自动捕获与自动召回：自动捕获默认开启，自动召回默认关闭。
- 迁移：支持从旧版 memory-lancedb 迁移。
- 管理 CLI：提供 list、search、stats、delete、delete-bulk、export、import、reembed、migrate 等命令。
- Agent 工具：提供 memory_recall、store、forget、update、stats、list 等工具。
- JSONL 会话蒸馏脚本：scripts/jsonl_distill.py。
使用方式 插件通过 OpenClaw Plugin API 注册，入口为 index.ts，配置由 openclaw.plugin.json 定义。CLI 通过 api.registerCli() 注册，命令模式为 memory.command("name <args>")。Agent 工具在 src/tools.ts 中定义并注册。自动捕获在 agent_end 钩子中运行，每轮最多 3 条，重复检测阈值为余弦相似度大于 0.95。自动召回使用 before_agent_start 钩子，默认关闭，注入为 <relevant-memories> XML 块并附带 UNTRUSTED DATA 警告，每轮最多注入 3 条记忆。环境变量使用 ${VAR} 语法在配置解析时解析。
适用场景 适用于需要长期记忆的 OpenClaw 智能体，尤其是需要多作用域隔离、高质量检索、可管理记忆库以及从旧版迁移的场景。
限制与注意事项
- 自动召回默认关闭，以防止模型回显注入的记忆上下文。
- 会话记忆默认关闭，因为原始会话摘要会降低检索质量，建议使用 JSONL 蒸馏。
- LanceDB 不支持原地更新，更新操作采用删除后重新添加。
- BM25 原始分数无界，使用 sigmoid 归一化：1 / (1 + exp(-score/5))。
- 启动检查为即发即忘，网关立即绑定 HTTP 端口，嵌入与检索测试在后台运行，超时 8 秒。
- 每日 JSONL 备份间隔 24 小时，保留最近 7 个文件，启动后 1 分钟运行。
- 重排器有 5 秒超时保护。
- CJK 感知阈值：中文、日文、韩文文本的最小长度较短（4–6 字符），英文为 10–15 字符。
- ID 前缀匹配：8 个以上十六进制字符前缀可解析为完整 UUID。
测试
- 冒烟测试：node test/cli-smoke.mjs
- 手动验证：openclaw plugins doctor、openclaw memory-pro stats
- 嵌入测试：embedder.test() 返回 { success, dimensions, error? }
- 检索测试：retriever.test() 返回 { success, mode, hasFtsSupport, error? }
开发工作流
- 添加嵌入提供方：若为 OpenAI 兼容则无需改代码，仅配置；若模型不在 EMBEDDING_DIMENSIONS 映射中则添加；若需特殊请求字段则扩展 buildPayload()；使用 embedder.test() 测试；在 README 表格中记录。
- 添加重排提供方：在 RerankProvider 类型中添加名称；在 buildRerankRequest() 与 parseRerankResponse() 中添加分支；在 openclaw.plugin.json 的 rerankProvider 枚举中添加；使用实际 API 调用测试。
- 添加评分阶段：在 MemoryRetriever 中创建私有 apply<StageName>() 方法；在 RetrievalConfig 接口中添加配置字段；在 hybridRetrieval() 与 vectorOnlyRetrieval() 的管线序列中插入；在 DEFAULT_RETRIEVAL_CONFIG 中添加默认值；在 openclaw.plugin.json 中添加 JSON Schema 字段。管线顺序：Fusion → Rerank → Recency → Importance → LengthNorm → TimeDecay → HardMin → Noise → MMR。
- 添加 Agent 工具：在 src/tools.ts 中创建 registerMemory<ToolName>Tool()；使用 @sinclair/typebox 的 Type.Object() 定义参数；使用 openclaw/plugin-sdk 的 stringEnum() 定义枚举参数；始终通过 context.scopeManager 验证作用域访问；在 registerAllMemoryTools() 中注册；返回 { content: [{ type: "text", text }], details: {...} }。
- 添加 CLI 命令：在 cli.ts 的 registerMemoryCLI() 中添加；支持 --json 标志；错误时使用 process.exit(1)。
- 修改自动捕获：shouldCapture(text) 控制捕获内容；MEMORY_TRIGGERS 正则数组定义触发模式（支持中英文）；detectCategory(text) 分类为 preference/fact/decision/entity/other。
- 修改自动召回：shouldSkipRetrieval() 控制是否跳过；sanitizeForContext() 去除 HTML、换行，每条记忆限制 300 字符。
文件参考
- index.ts：插件入口，注册 OpenClaw Plugin API、解析配置、挂载生命周期钩子。
- openclaw.plugin.json：插件元数据与完整 JSON Schema 配置。
- package.json：NPM 包，依赖 @lancedb/lancedb、openai、@sinclair/typebox。
- cli.ts：CLI 命令。
- src/store.ts：LanceDB 存储层，表创建、FTS 索引、CRUD、向量/BM25 搜索。
- src/embedder.ts：嵌入抽象，OpenAI 兼容 API、任务感知、LRU 缓存。
- src/retriever.ts：混合检索引擎与评分管线。
- src/scopes.ts：多作用域访问控制。
- src/tools.ts：Agent 工具定义。
- src/noise-filter.ts：噪声过滤。
- src/adaptive-retrieval.ts：自适应检索跳过。
- src/migrate.ts：从旧版 memory-lancedb 迁移。
- scripts/jsonl_distill.py：JSONL 会话蒸馏脚本。
详细子系统参考文件包括 references/retrieval_pipeline.md、references/storage_and_schema.md、references/embedding_system.md、references/plugin_lifecycle.md、references/scope_system.md、references/tools_and_cli.md、references/troubleshooting.md。