DESKTOP-72TV0V4\caoxiaozhu
237ab9f6d7
移除已归档的 teams 目录下的需求分析文档 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
219 lines
8.7 KiB
Markdown
219 lines
8.7 KiB
Markdown
# OpenCLAW 记忆模块调研报告
|
||
|
||
## 调研目标
|
||
调研 OpenCLAW 的记忆模块（Memory Module）功能，了解其架构设计、核心功能和实现原理。
|
||
|
||
## 一、OpenCLAW 简介
|
||
|
||
OpenCLAW 是一个开源的个人 AI Agent 网关平台（GitHub: https://github.com/openclaw/openclaw），旨在让 AI 成为能实际操作用户设备、拥有持久化记忆并能主动发起任务的私人助理。
|
||
|
||
## 二、记忆模块架构设计
|
||
|
||
### 2.1 三层记忆架构
|
||
|
||
OpenCLAW 采用经典的三层类继承架构：
|
||
|
||
```
|
||
┌─────────────────────────────────────────────┐
|
||
│ 顶层：导览员（检索层） │
|
||
│ 负责处理用户查询，快速找到最相关的记忆 │
|
||
├─────────────────────────────────────────────┤
|
||
│ 中间层：翻译官（嵌入层） │
|
||
│ 把文字转化为机器能理解的数学向量 │
|
||
├─────────────────────────────────────────────┤
|
||
│ 底层：书架管理员（存储层） │
|
||
│ 负责文本块的入库、上架和盘点 │
|
||
└─────────────────────────────────────────────┘
|
||
```
|
||
|
||
### 2.2 三层记忆类型
|
||
|
||
| 记忆类型 | 描述 | 存储方式 |
|
||
|---------|------|---------|
|
||
| **短期记忆 (Short-term Context)** | 当前会话的上下文信息 | 存于 Context Window |
|
||
| **语义记忆 (Semantic Memory)** | 长期稳定的知识 | SQLite + 向量索引 |
|
||
| **情景记忆 (Episodic Memory)** | 具体事件和经历 | memory/YYYY-MM-DD.md |
|
||
|
||
## 三、核心功能特性
|
||
|
||
### 3.1 混合搜索（Hybrid Search）
|
||
|
||
OpenCLAW 实现了 **BM25 + 向量语义** 的混合搜索：
|
||
|
||
- **BM25 全文检索**：基于 SQLite FTS5 引擎，擅长精确关键词匹配
|
||
- **向量语义检索**：通过嵌入模型将文本转化为高维向量，基于余弦相似度捕捉语义关联
|
||
|
||
**权重配置**：默认 7:3（语义 70%，精确 30%）
|
||
|
||
### 3.2 时间衰减机制
|
||
|
||
引入**指数时间衰减模型**，模拟人类记忆的遗忘曲线：
|
||
|
||
```
|
||
衰减后得分 = 原始得分 × e^(-λ × 天数)
|
||
```
|
||
|
||
- 半衰期默认 30 天
|
||
- 30 天后检索权重衰减为原来的一半
|
||
- 60 天后只剩四分之一
|
||
|
||
**常青记忆（Evergreen Memory）**：
|
||
- `MEMORY.md`（根级记忆文件）不受时间衰减影响
|
||
- `memory/patterns.md` 等主题归纳文件也不衰减
|
||
- 按日期命名的记录（如 `memory/2024-01-15.md`）正常应用衰减
|
||
|
||
### 3.3 MMR 重排算法
|
||
|
||
使用 **MMR（Maximal Marginal Relevance，最大边际相关性）** 算法进行结果重排，避免信息冗余：
|
||
|
||
```
|
||
MMR(d) = λ × 相关性(d) - (1-λ) × max(与已选结果的相似度)
|
||
```
|
||
|
||
采用 **Jaccard 集合相似度** 替代余弦相似度，计算更轻量。
|
||
|
||
### 3.4 多提供商嵌入支持
|
||
|
||
| 提供商 | 默认模型 | 特点 |
|
||
|-------|---------|------|
|
||
| OpenAI | text-embedding-3-small | 业界主流，质量稳定 |
|
||
| Gemini | gemini-embedding-001 | 支持 API Key 自动轮换 |
|
||
| Voyage | voyage-4-large | 高维度，擅长长文本 |
|
||
| Mistral | mistral-embed | 多语言能力出色 |
|
||
| 本地 | embeddinggemma-300m (GGUF) | 完全离线，数据不出本机 |
|
||
|
||
**四级降级链条**：确保任何环境下都能提供服务
|
||
|
||
### 3.5 嵌入缓存与索引重建
|
||
|
||
- **Embedding 缓存**：以 `provider + model + 文本内容哈希` 为主键，同一段文本只需计算一次嵌入
|
||
- **原子化重建**：采用"双数据库原子交换"策略，索引重建期间用户无感知
|
||
|
||
### 3.6 实时同步机制
|
||
|
||
三条并行的同步通道：
|
||
|
||
1. **文件监控（chokidar）**：实时监听 `MEMORY.md` 和 `memory/` 目录变化，通过防抖机制避免重复触发
|
||
2. **会话增量同步**：维护 delta 追踪器，只在增量达到阈值时触发更新
|
||
3. **定时轮询**：兜底机制，确保不会遗漏
|
||
|
||
### 3.7 中文检索支持
|
||
|
||
采用**字级别 + bigram 策略**：
|
||
- 单字保证召回率
|
||
- bigram 捕捉常见双字词组合
|
||
- 内置约 80 个中文停用词过滤
|
||
|
||
## 四、数据流架构
|
||
|
||
```
|
||
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
|
||
│ 用户输入 │────▶│ 混合搜索 │────▶│ MMR重排 │
|
||
│ (查询) │ │ BM25+向量 │ │ 去冗余 │
|
||
└──────────────┘ └──────────────┘ └──────────────┘
|
||
│
|
||
┌───────────────────────────┘
|
||
▼
|
||
┌──────────────┐
|
||
│ 时间衰减 │
|
||
│ +常青记忆 │
|
||
└──────────────┘
|
||
│
|
||
▼
|
||
┌──────────────┐
|
||
│ 返回结果 │
|
||
│ 给 Agent │
|
||
└──────────────┘
|
||
```
|
||
|
||
## 五、存储结构
|
||
|
||
```
|
||
workspace/
|
||
├── MEMORY.md # 常青记忆（根级）
|
||
├── memory/
|
||
│ ├── patterns.md # 主题归纳（常青）
|
||
│ ├── 2024-01-15.md # 按日期的情景记忆
|
||
│ └── ...
|
||
└── .claude/
|
||
└── memory/ # SQLite 向量索引
|
||
└── index.db
|
||
```
|
||
|
||
## 六、总结与启发
|
||
|
||
### 设计哲学
|
||
|
||
| 原则 | 体现 |
|
||
|------|------|
|
||
| **混合优于单一** | BM25 和向量搜索各有盲区，融合才能互补 |
|
||
| **韧性优于性能** | 四级降级链条确保任何环境下都能提供服务 |
|
||
| **仿生优于机械** | 时间衰减与常青记忆模拟人类认知的自然规律 |
|
||
| **务实优于完美** | Jaccard 替代余弦相似度，bigram 替代专业分词 |
|
||
|
||
### 可借鉴点
|
||
|
||
1. **三层记忆架构**：短期/语义/情景记忆分离
|
||
2. **混合搜索**：BM25 + 向量检索结合
|
||
3. **时间衰减**：模拟人类遗忘曲线
|
||
4. **常青记忆**：区分核心知识和时效信息
|
||
5. **多级降级**：确保服务高可用
|
||
6. **实时同步**：文件监控 + 增量同步 + 定时轮询
|
||
|
||
## 七、参考资料
|
||
|
||
- OpenCLAW 官方 GitHub: https://github.com/openclaw/openclaw
|
||
- OpenCLAW 记忆系统深度解析: https://zhuanlan.zhihu.com/p/2010072734986702963
|
||
- OpenCLAW Design Patterns: https://kenhuangus.substack.com/p/the-openclaw-design-patternspart
|
||
- OpenCLAW 记忆系统架构: https://zhuanlan.zhihu.com/p/2005943466006438841
|
||
|
||
---
|
||
|
||
## 八、可行性评估（algorithm-dev）
|
||
|
||
### 8.1 与现有系统兼容性分析
|
||
|
||
| 维度 | 现有 X-Agents | OpenCLAW | 兼容性 |
|
||
|------|--------------|----------|--------|
|
||
| 存储格式 | Markdown 文件 | Markdown 文件 | ✅ 高度兼容 |
|
||
| 短期记忆 | SessionMemory（内存） | sessions/ 目录 | ✅ 可对齐 |
|
||
| 长期记忆 | AgentMemory（文件） | MEMORY.md | ✅ 可对齐 |
|
||
| 检索机制 | 无 | BM25+向量混合 | ❌ 需新增 |
|
||
| 嵌入服务 | 无 | 多种 provider | ❌ 需新增 |
|
||
| 分块策略 | 无 | 400 token 滑动窗口 | ❌ 需新增 |
|
||
|
||
### 8.2 工程落地技术难点
|
||
|
||
1. **嵌入服务集成** - 需要选择嵌入提供者（本地 ONNX vs 远程 API）
|
||
2. **向量数据库** - 需要集成 Milvus/Chroma/FAISS 等
|
||
3. **混合检索加权融合** - 需要实现 70/30 加权融合算法
|
||
4. **分块策略** - 需要实现带重叠的滑动窗口分块
|
||
5. **预压缩冲刷** - 需要监控 token 数量并触发自动保存
|
||
|
||
### 8.3 可行性结论
|
||
|
||
**✅ 可行性：高**
|
||
|
||
### 建议方案
|
||
|
||
#### 方案A（推荐）- 集成 memsearch 库
|
||
|
||
- Zilliz 提取并开源的 Python 库，完全复现 OpenCLAW 记忆架构
|
||
- 支持多种嵌入提供者（推荐本地 ONNX，无需 API key）
|
||
- 支持 Milvus Lite（单用户）/Milvus Server（团队）/Zilliz Cloud（生产）
|
||
- 开箱即用，集成成本低
|
||
|
||
#### 方案B - 自研轻量级实现
|
||
|
||
- 保持现有 Markdown 文件存储
|
||
- 简化检索：仅用关键词搜索或简单向量相似度
|
||
- 开发周期更长，但可控性更高
|
||
|
||
**推荐采用 memsearch 库**，可以快速获得成熟的 OpenCLAW 记忆能力，同时保持 Markdown 文件的可读性和版本可控性。
|
||
|
||
### 8.4 待确认事项
|
||
|
||
1. 是否需要新增向量数据库服务？（Milvus Lite vs 自建）
|
||
2. 嵌入模型选择本地 ONNX 还是远程 API？
|
||
3. 是否需要支持多用户协作场景？
|