# 概述

> 了解 Unified Memory 是什么，它如何工作，以及它与其他记忆系统有何不同。

## 🤔 什么是 Unified Memory？

**Unified Memory** 是一个为企业级 AI 代理和应用设计的记忆管理系统。它提供：

1. **持久存储** - 跨会话存储记忆
2. **智能搜索** - 使用混合搜索（BM25 + 向量 + RRF）查找相关记忆
3. **原子操作** - 通过事务保证数据一致性
4. **插件架构** - 使用自定义插件扩展功能

## 🎯 它解决的核心问题

| 问题 | 解决方案 |
|------|----------|
| 记忆不会跨会话持久化 | 持久化 JSON + SQLite 存储 |
| 简单关键词搜索不够准确 | 混合搜索结合 BM25、向量和 RRF 融合 |
| 崩溃时数据丢失 | WAL（预写日志）+ fsync |
| 无法与其他记忆系统集成 | 插件系统与同步桥接 |

## 🏗️ 架构概述

```
┌─────────────────────────────────────────────────────────────┐
│                    您的应用程序                             │
│            (OpenClaw, CLI, API, Web UI 等)                 │
└───────────────────────────┬─────────────────────────────────┘
                            │ 调用 MCP 工具
                            ▼
┌─────────────────────────────────────────────────────────────┐
│                    Unified Memory                           │
├─────────────────────────────────────────────────────────────┤
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐         │
│  │   记忆      │  │   搜索      │  │   插件      │         │
│  │   存储      │  │   引擎      │  │   系统      │         │
│  └─────────────┘  └─────────────┘  └─────────────┘         │
├─────────────────────────────────────────────────────────────┤
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐         │
│  │    WAL     │  │   向量      │  │   缓存      │         │
│  │   记录器   │  │   存储      │  │   层        │         │
│  └─────────────┘  └─────────────┘  └─────────────┘         │
└─────────────────────────────────────────────────────────────┘
```

## 🔍 搜索如何工作

Unified Memory 使用**混合搜索**方法，结合多种排名算法：

### 1. BM25（关键词搜索）
基于词频和逆文档频率的传统相关性排名。适用于精确匹配。

### 2. 向量搜索（语义搜索）
将文本转换为嵌入向量并找到语义相似的记忆。适用于概念匹配。

### 3. RRF（倒数排名融合）
使用公式组合多个算法的排名：

```
RRF_score = Σ(1 / (k + rank_i))
```

其中 `k` 是常数（默认：60），`rank_i` 是算法 `i` 的排名。

## 💾 数据存储

### 记忆 JSON 文件
记忆内容的主要存储：
```
~/.unified-memory/memories.json
```

### 向量数据库
存储用于语义搜索的嵌入：
```
~/.unified-memory/vector.lance  (LanceDB)
~/.unified-memory/vector/        (ChromaDB 备选)
```

### WAL 日志
确保原子性和崩溃恢复：
```
~/.unified-memory/wal/
~/.unified-memory/transactions.log
```

## 🔐 数据安全特性

### 原子事务
两阶段提交确保：
- 记忆内容和向量一起写入
- 失败时回滚部分写入
- 系统崩溃时无数据丢失

### WAL 协议
预写日志保证：
- 在应用之前记录所有更改
- 系统可以从崩溃中恢复
- 启用 fsync 时零数据丢失

## 🔌 插件系统

插件使用自定义功能扩展 Unified Memory：

| 插件类型 | 描述 |
|---------|------|
| **同步桥接** | 连接到外部记忆系统（Workspace Memory 等） |
| **处理器** | 存储前转换记忆 |
| **搜索引擎** | 添加自定义搜索算法 |
| **导出器** | 导出到外部格式 |

## 📊 性能指标

| 指标 | 数值 | 说明 |
|------|------|------|
| 搜索速度 | 平均 45ms | 向量优化后快 5-10 倍 |
| 存储 | 减少 60% | 与未压缩存储相比 |
| 缓存命中率 | 78% | 智能语义缓存 |
| 内存使用 | 约 245 MB | 1,760 条记忆时 |

## 🎓 记忆生命周期

记忆自动转换层级：

| 层级 | 年龄 | 描述 |
|------|------|------|
| **HOT** | ≤ 7 天 | 活跃，经常访问 |
| **WARM** | 7-30 天 | 不太活跃，轻压缩 |
| **COLD** | > 30 天 | 很少访问，重压缩 |

**固定的记忆**被排除在层级转换和压缩之外。

## 🔄 版本历史

Unified Memory 为所有记忆维护版本历史：
- 跟踪随时间的变化
- 比较版本（差异）
- 恢复以前的版本

## 🚀 下一步是什么？

- [安装 Unified Memory](./installation.md)
- [快速入门教程](./quickstart.md)
- [配置指南](./configuration.md)
- [基础使用指南](../guides/basic-usage.md)
