memory-lancedb-pro 与 scope-recall 综合深度分析报告

Codex 核验（2026-10-10）：当前 Scope Recall 为 v3.9.3：SQLite 是权威持久化层，向量伴随索引可重建，已有 Hermes 以及 Codex/Claude Code 等适配器；本文旧版本与实验数字保留原日期。数据库中的“事实”指系统记录，SQL 统计和 scope 分类不会独立证实内容真实，也不是操作系统安全隔离。重建向量必须保留原文本、来源与相关配置，不能由“索引可重建”推出删除原始记忆也无损。嵌入/LLM 后端是否本地要单独确认。

调研时间：2026-05-27 调研方式：GitHub API 检索、源码分析、文档阅读、npm/PyPI 元数据查询

目录

1. memory-lancedb-pro 深度分析
2. scope-recall 深度分析
3. 两大项目对比
4. 总结与建议

1. memory-lancedb-pro 深度分析

1.1 基本信息

1.2 核心定位

memory-lancedb-pro 并不是 LanceDB 的”企业版”或”Pro 版本”，而是 OpenClaw Agent 的一个长期记忆插件，使用 LanceDB 作为其向量存储后端。项目名称中的 “pro” 表示”增强版/专业版”的记忆插件。

一句话：它是面向 OpenClaw 智能体（如 Claude Code / Codex 等）的生产级 AI 记忆插件，负责自动捕捉、存储和回忆会话中的关键信息。

1.3 解决的核心问题

大多数 AI 智能体在每个新会话中都会”失忆”——忘记用户偏好、忘记过去的决策、忘记项目上下文。memory-lancedb-pro 通过持久化向量存储 + 智能提取 + 自动回忆机制来解决这个问题。

1.4 架构总览

1.4.1 源码目录结构

memory-lancedb-pro/
├── index.ts                  # 插件入口：注册、配置解析、Hook 装配
├── cli.ts                    # CLI 管理界面
├── openclaw.plugin.json      # 插件清单（版本 1.1.0-beta.11）
├── package.json              # npm 包配置
├── tsconfig.json             # TypeScript 配置
├── src/                      # 核心源码目录（~50 个模块）
│   ├── store.ts              # LanceDB 存储层：CRUD、向量检索、FTS/BM25
│   ├── embedder.ts           # 统一 Embedding 适配层
│   ├── retriever.ts          # 混合检索 + 重排序 + 评分
│   ├── tools.ts              # Agent 工具定义
│   ├── scopes.ts             # 多作用域访问控制
│   ├── smart-extractor.ts    # LLM 驱动的智能提取
│   ├── decay-engine.ts       # Weibull 生命周期衰减引擎
│   ├── tier-manager.ts       # Tier（核心/工作/外围）升降级管理
│   ├── noise-prototypes.ts   # 嵌入噪声检测与预处理
│   ├── admission-control.ts  # A-MAC 准入控制
│   ├── memory-compactor.ts   # 渐进式记忆压缩
│   ├── corpus-indexer.ts     # 规范语料索引
│   ├── reflection-*.ts       # AI 反思/梦境系统（多个模块）
│   ├── query-expander.ts     # 查询扩展
│   ├── intent-analyzer.ts    # 意图分析
│   ├── temporal-classifier.ts # 时间分类器
│   ├── identity-addressing.ts # 身份寻址
│   ├── clawteam-scope.ts     # 团队作用域
│   └── ...                   # 更多模块
├── dist/                     # 编译后的 JS 产物
├── docs/                     # 文档
│   ├── memory_architecture_analysis.md
│   ├── long-context-chunking.md
│   ├── openclaw-integration-playbook.md
│   └── openclaw-integration-playbook.zh-CN.md
├── test/                     # 40+ 测试文件
├── scripts/                  # 构建/CI 脚本
└── skills/                   # OpenClaw Skill 定义

1.4.2 架构分层

┌─────────────────────────────────────────────────────────┐
│                 OpenClaw Runtime Surface                  │
│  用户消息 ↔ Agent 对话 ↔ Tools ↔ CLI ↔ Hooks (/new)    │
└──────────────────────┬──────────────────────────────────┘
                       │
┌──────────────────────▼──────────────────────────────────┐
│                   index.ts (插件入口)                      │
│   配置解析 → Hook 注册 → Tool 注册 → CLI 注册 → Service   │
└──────────────────────┬──────────────────────────────────┘
                       │
┌──────────────────────▼──────────────────────────────────┐
│                   写入链路 (Write Path)                    │
│                                                           │
│  agent_end → NoisePrototypeBank (噪声过滤)                  │
│           → SmartExtractor (LLM 6类提取)                    │
│           → AdmissionControl (准入评分)                     │
│           → BatchDedup (去重) → store.ts (持久化)           │
│                                                           │
│  CanonicalCorpus → 索引 MEMORY.md / 会话记录                │
└──────────────────────┬──────────────────────────────────┘
                       │
┌──────────────────────▼──────────────────────────────────┐
│                   存储层 (Storage)                         │
│                                                           │
│  LanceDB (单表 + JSON metadata 扩展)                       │
│    ├── 向量列 (vector) — 语义搜索                          │
│    ├── FTS 索引 (BM25) — 全文搜索                          │
│    └── metadata 字段 — 分类/置信度/生命周期等               │
│                                                           │
│  辅助: MD Mirror (可选 Markdown 副本) + Canonical Files    │
└──────────────────────┬──────────────────────────────────┘
                       │
┌──────────────────────▼──────────────────────────────────┐
│                   检索链路 (Retrieve Path)                  │
│                                                           │
│  用户查询 → Embedder (向量化)                               │
│          → Retriever (混合搜索: Vector + BM25)              │
│          → Reranker (Cross-Encoder 重排序)                  │
│          → Scoring (长度归一化 + 时间衰减 + 噪声过滤)        │
│          → TierManager (生命周期重排)                       │
│          → Context Injection (注入到 Agent 上下文)           │
└──────────────────────┬──────────────────────────────────┘
                       │
┌──────────────────────▼──────────────────────────────────┐
│               生命周期维护 (Lifecycle)                      │
│                                                           │
│  DecayEngine (Weibull 衰减)                                │
│  TierManager (核心/工作/外围 升降级)                        │
│  MemoryCompactor (渐进式压缩)                               │
│  Reflection/Dreaming (反思/梦境系统)                        │
└─────────────────────────────────────────────────────────┘

1.4.3 核心技术依赖

1.5 核心功能详解

1.5.1 混合检索（Hybrid Retrieval）

• 向量搜索：使用 LanceDB 原生向量索引（IVF-PQ 或 flat），支持 cosine 距离
• BM25 全文搜索：LanceDB 内置的 FTS 索引
• 融合策略：加权 RRF（Reciprocal Rank Fusion），默认向量权重 0.7，BM25 权重 0.3
• 重排序：Cross-Encoder 模型（默认 Jina Reranker v3），支持 SiliconFlow、Voyage、Pinecone、DashScope、TEI 等多种 provider
• 候选池：默认 20 条候选 → 重排序后精选前 N 条

{
  "retrieval": {
    "mode": "hybrid",
    "vectorWeight": 0.7,
    "bm25Weight": 0.3,
    "minScore": 0.3,
    "rerank": "cross-encoder",
    "rerankModel": "jina-reranker-v3",
    "candidatePoolSize": 20
  }
}

1.5.2 智能提取（Smart Extraction）

使用 LLM 将对话内容分类为 6 类记忆：

提取流程：对话累积 → 噪声预过滤 → LLM 提取 → 准入评分（A-MAC）→ 批处理去重 → 语义合并 → 持久化

1.5.3 生命周期管理

• Weibull 衰减模型：不同 tier 有不同的 β 参数
• 3 级 Tier 体系：Core（核心）→ Working（工作）→ Peripheral（外围）
  • 高频回忆 + 高价值 → 晋升 Core
  • 长时间未访问 + 低价值 → 降级 Peripheral → 最终遗忘
• Recall 增强：频繁被回忆的记忆衰减更慢
• 渐进式压缩（Memory Compaction）：将语义相似的旧记忆合并优化

1.5.4 多作用域隔离（Multi-Scope Isolation）

┌─────────────────────────────────────────┐
│              Global Scope                │
│  ┌──────────┐  ┌──────────┐             │
│  │ Agent A  │  │ Agent B  │             │
│  │  ┌──────┐│  │  ┌──────┐│             │
│  │  │User 1││  │  │User 2││             │
│  │  │Project││  │  │Project││           │
│  │  │ X     ││  │  │ Y     ││           │
│  │  └──────┘│  │  └──────┘│             │
│  └──────────┘  └──────────┘             │
└─────────────────────────────────────────┘

支持按 agent、user、project 维度隔离记忆，确保数据不跨边界泄露。

1.5.5 规范语料（Canonical Corpus）

• 将 MEMORY.md、memory/**/*.md、会话转录等文件作为”源文件”
• LanceDB 作为语义索引，检索时返回文件路径、行范围、摘要和引用
• 保持”源文件即真理”的原则

1.5.6 AI 反思/梦境（Reflection/Dreaming）

• 在会话间隙自动运行”反思”，生成摘要和洞察
• 可配置 cron 定时任务
• 结果存入 memory/dreaming/**/*.md

1.6 提供的内存工具（Agent Tools）

memory_recall     — 语义回忆
memory_store      — 存储记忆
memory_forget     — 删除记忆
memory_update     — 更新记忆
memory_list       — 列出记忆
memory_stats      — 统计信息
memory_debug      — 调试工具
memory_compact    — 渐进式压缩
memory_archive    — 归档
memory_promote    — 提升 tier
memory_explain_rank — 解释评分
self_improvement_log      — 自我改进日志
self_improvement_extract_skill — 提取技能
self_improvement_review   — 审查

1.7 安装方式

# 推荐：OpenClaw CLI 安装
openclaw plugins install memory-lancedb-pro@beta
 
# npm 安装
npm i memory-lancedb-pro@beta
 
# 社区一键脚本
curl -fsSL https://raw.githubusercontent.com/CortexReach/toolbox/main/memory-lancedb-pro-setup/setup-memory.sh -o setup-memory.sh
bash setup-memory.sh

1.8 生态系统

1.9 与竞品的差异

2. scope-recall 深度分析

2.1 基本信息

2.2 核心定位

scope-recall 是 Hermes Agent 的一个本地记忆提供者（Memory Provider），采用两层设计：SQLite 作为”真理存储层”（source of truth），LanceDB 作为”向量伴侣层”（semantic companion）。

一句话：它是为 Hermes Agent 设计的当前轮次回忆记忆插件，强调作用域隔离和真理可审计。

2.3 解决的核心问题

1. 跨窗口记忆断裂：用户在一个窗口中告诉智能体的偏好，换到另一个窗口就忘了
2. 话题/分组污染：群聊 A 的临时聊天不应影响群聊 B
3. 向量存储作为唯一真理的风险：向量数据库可能损坏，需要可审计的确定性存储

2.4 架构总览

2.4.1 源码目录结构

scope-recall/
├── provider.py                 # Hermes Provider 主入口
├── scope_recall.py             # 核心模块
├── config.py                   # 配置解析
├── config.json                 # 默认配置
├── plugin.yaml                 # Hermes 插件清单
├── models.py                   # 数据模型（dataclass）
├── schemas.py                  # Tool Schema 定义
├── scope.py                    # 作用域计算
├── recall.py                   # 回忆引擎
├── scoring.py                  # 评分系统
├── capture.py                  # 捕捉逻辑
├── capture_filters.py          # 捕捉过滤器
├── embedders.py                # 嵌入器适配层
├── sql_store.py                # SQLite 存储层
├── vector_store.py             # LanceDB 向量存储
├── vector_runtime.py           # 向量运行时
├── storage_views.py            # 存储视图
├── gating.py                   # 回忆门控（问候语/噪声过滤）
├── governance.py               # 治理（去重、合并、管理）
├── hygiene.py                  # 存储卫生工具
├── memory_ops.py               # 记忆操作
├── migration.py                # 迁移工具
├── tooling.py                  # 工具注册
├── aliases.py                  # 别名
├── tests/                      # 15 个测试文件
│   ├── test_provider.py
│   ├── test_embedders.py
│   ├── test_sql_store_fts.py
│   ├── test_scoring.py
│   ├── test_capture_filters.py
│   └── ...
├── scripts/                    # 运维脚本
│   ├── import.openclaw.memory_lancedb_pro.py  # OpenClaw 导入器
│   ├── repair.vector_index.py                 # 向量索引修复
│   ├── report.hygiene.py                      # 卫生报告
│   └── check.release.py                       # 发布检查
└── docs/                       # 文档
    ├── DESIGN.md
    ├── differences-from-memory-lancedb-pro.md
    ├── memory.stack.contract.md
    ├── migration.md
    ├── stability.md
    └── plans/

2.4.2 核心架构：两层设计

┌─────────────────────────────────────────────────────────┐
│                 Hermes Runtime Surface                    │
│  用户消息 ↔ Agent 对话 ↔ Tools ↔ Hooks (on_turn_start)   │
└──────────────────────┬──────────────────────────────────┘
                       │
┌──────────────────────▼──────────────────────────────────┐
│                   Provider Layer                          │
│  provider.py + scope_recall.py + tooling.py              │
│  作用域计算 → 门控过滤 → 回忆引擎 → 工具注册              │
│  钩子: on_turn_start / on_session_end / on_memory_write   │
└──────────┬────────────────────────────────┬─────────────┘
           │                                │
┌──────────▼──────────┐    ┌───────────────▼──────────────┐
│   Layer A: SQLite    │    │   Layer C: Curated Memory     │
│    真理存储层         │    │   (Hermes 内置)               │
│                      │    │                                │
│  memory.sqlite3      │    │  $HERMES_HOME/memories/       │
│  ├── 作用域字段      │    │  ├── USER.md                  │
│  ├── 原始内容        │    │  ├── MEMORY.md                │
│  ├── 摘要            │    │  └── ...                      │
│  ├── FTS5 全文索引   │    │                                │
│  └── 审计追踪        │    │  (live-read, 不镜像)           │
└──────────┬──────────┘    └──────────────────────────────┘
           │
┌──────────▼──────────┐
│   Layer B: LanceDB   │
│    向量伴侣层         │
│                      │
│  lancedb/            │
│  ├── 向量列          │
│  ├── 检索辅助字段    │
│  └── 可重建索引      │
│                      │
│  (非真理, 可从头重建) │
└─────────────────────┘

2.4.3 与传统 memory-lancedb-pro 的关键架构差异

2.5 核心功能详解

2.5.1 作用域模型（Scope Model）

共享持久作用域（跨窗口/会话共享）：

• platform + agent_workspace + agent_identity + user_id
• 存储目标为 user / memory / project / ops 的记忆

本地运行时作用域（仅当前对话可见）：

• 共享持久作用域基础上 + gateway_session_key（或 chat_id） + thread_id
• 存储目标为 general 的原始轮次捕捉

访问规则：

可访问作用域集合 = [当前本地运行时作用域, 共享持久作用域]

• 同一用户 + 同一智能体身份 → 跨窗口共享持久记忆
• 不同用户 / 不同智能体 / 不同本地临时上下文 → 完全隔离

2.5.2 SQLite 存储层

路径：$HERMES_HOME/scope-recall/memory.sqlite3

Schema 包含字段：

scope_id, platform, user_id, chat_id, thread_id,
gateway_session_key, agent_identity, agent_workspace,
session_id, source, target, content, summary,
timestamps (created_at, updated_at), metadata

额外：FTS5 全文搜索索引提供快速词法检索

2.5.3 LanceDB 向量伴侣

路径：$HERMES_HOME/scope-recall/lancedb/

• 同步模式：增量同步（sync_mode: "incremental"，默认），而非全量重建
• 同步逻辑：比较 stable_id + updated_at，仅增量更新
• 故障模式：如果 LanceDB 操作失败，SQLite 仍然权威，标记 needs_repair

2.5.4 嵌入器策略

2.5.5 配置示例

{
  "auto_recall": true,
  "auto_capture": true,
  "retrieval": {
    "mode": "hybrid",
    "lexical_weight": 0.45,
    "vector_weight": 0.55,
    "candidate_pool": 12
  },
  "vector": {
    "enabled": true,
    "backend": "lancedb",
    "sync_mode": "incremental",
    "embedder": {
      "provider": "openai-compatible",
      "model": "gemini-embedding-001",
      "dimensions": 3072,
      "api_key_env": ["SCOPE_RECALL_GEMINI_EMBEDDING_API_KEY"],
      "base_url": "https://generativelanguage.googleapis.com/v1beta/openai"
    },
    "fallback_embedder": {
      "provider": "local-hash",
      "dimensions": 256,
      "model": "hash-v1"
    }
  }
}

2.5.6 提供的工具

默认工具（primary agent）：

• scope_recall_store — 存储记忆
• scope_recall_search — 搜索记忆
• scope_recall_forget — 删除记忆
• scope_recall_update — 更新记忆
• scope_recall_merge — 合并记忆
• scope_recall_export — 导出（scope_only=true）
• scope_recall_stats — 统计

运维工具（需 maintenance_tools_enabled: true）：

• scope_recall_dedupe — 去重
• scope_recall_govern — 治理
• scope_recall_hygiene — 卫生检查
• scope_recall_repair — 修复向量索引
• scope_recall_export — 导出（scope_only=false）

2.6 与 OpenClaw memory-lancedb-pro 的异同

继承的设计理念

• 当前轮次优先检索（无队列式 topic bleed）
• 强作用域隔离
• 保守门控（问候语/噪声过滤）
• 有限回忆预算
• 混合检索方向

有意差异

剩余差距（scope-recall 未实现的功能）

• LLM 驱动的创建/合并/跳过分类器
• 全自动语义合并 - 通用矛盾解决器
• 多层摘要 / 晋升 / 压缩编排管道
• 旧 OpenClaw LanceDB 存储的自动复用

2.7 安装方式

# 克隆到 Hermes 插件目录
cd "$HERMES_HOME/plugins"
git clone https://github.com/410979729/scope-recall.git scope-recall
cd scope-recall
python -m pip install -e .
 
# 配置 Hermes
# memory:
#   provider: scope-recall

3. 两大项目对比

3.1 总体对比

3.2 技术架构理念对比

memory-lancedb-pro 的设计哲学：
   "LanceDB 是中心，一切围绕向量存储构建"

scope-recall 的设计哲学：
   "SQLite 是真理，LanceDB 只是检索工具"

3.3 适用场景

4. 总结与建议

4.1 关键发现

1. memory-lancedb-pro 是 OpenClaw 生态的现象级项目：在短短 3 个月内获得 4,378 星，反映出 AI 记忆管理需求的强烈。它不是一个”LanceDB 企业版”，而是一个基于 LanceDB 的 AI Agent 记忆插件。

2. scope-recall 是 Hermes 生态的精心设计：虽然 stars 较少（41），但其设计文档（DESIGN.md）非常详尽，架构决策明确，体现了”SQLite 真理 + LanceDB 伴侣”的务实哲学。

3. 两者不是直接竞争关系：它们服务不同的平台（OpenClaw vs Hermes），解决类似问题但有完全不同的架构取舍。

4. scope-recall 明确从 memory-lancedb-pro 继承理念：其 docs/differences-from-memory-lancedb-pro.md 文件坦诚地列出了继承的设计和有意差异。

4.2 技术趋势观察

• 混合检索成为标配：两个项目都采用 Vector + BM25 + Rerank 的混合检索策略
• 作用域隔离成为关键：多 Agent、多用户、多项目的记忆隔离是刚需
• 智能提取 + 生命周期管理：不再是简单的存/取，而是包含提取→评估→衰减→遗忘的完整管道
• SQLite + LanceDB 双层架构趋势：scope-recall 的设计思路值得关注——向量数据库作为检索加速器而非唯一真理

4.3 调研数据统计