X-Agents/teams/openclaw-memory-research.md

# 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. 是否需要支持多用户协作场景？