# powermem 架构 {#powermem-architecture}

powermem 是一个由 AI 驱动的智能记忆管理系统，模仿人类记忆机制，为 LLM 应用提供持久化记忆能力。本文档全面概述了系统架构。

## 目录 {#table-of-contents}

- [系统概述](#system-overview)
- [架构层次](#architecture-layers)
- [记忆生命周期](#memory-lifecycle)
- [核心组件](#core-components)
- [数据存储层](#storage-layer)
- [AI 服务层](#model-layer)
- [API 接入层](#api-layer)
- [Multi-Agent 支持](#multi-agent-support)

## 系统概述 {#system-overview}

powermem 实现了一个复杂的记忆管理系统，其灵感来源于认知科学，特别是艾宾浩斯遗忘曲线理论。该系统通过多层架构智能地处理、评估、存储和检索记忆。

### 核心设计原则 {#key-design-principles}

1. **类人记忆管理**：实现工作记忆、短期记忆和长期记忆层
2. **智能评估**：基于 AI 的重要性和周期性评估
3. **强化学习**：根据使用模式动态调整记忆保留
4. **自动优化**：遗忘衰减和自动清理机制
5. **Multi-Agent 支持**：隔离的记忆空间与协作能力

## 架构层次 {#architecture-layers}

powermem 系统分为五个主要层次：
```
┌──────────────────────────────────────────────┐
│  用户应用层：Multi-Agent 与用户              │
└──────────────────────────────────────────────┘
                    ↓
┌──────────────────────────────────────────────┐
│  API 接入层                                  │
│  (Python SDK、CLI、MCP Server)               │
└──────────────────────────────────────────────┘
                    ↓
┌──────────────────────────────────────────────┐
│  记忆管理层（记忆引擎）                      │
│  • 记忆生命周期管理                          │
│  • 智能记忆处理器                            │
│  • 分层记忆结构                              │
└──────────────────────────────────────────────┘
                    ↓
┌──────────────────────────────────────────────┐
│  AI 服务层（Embedding/LLM）                  │
│  (Qwen、OpenAI、Anthropic 等)                │
└──────────────────────────────────────────────┘
                    ↓
┌──────────────────────────────────────────────┐
│  数据存储层（标量/向量/图）                  │
│  (OceanBase、PostgreSQL、SQLite 等)          │
└──────────────────────────────────────────────┘
```
### 1. 用户应用层 {#1-external-layer}

用户应用层包括：
- **Multi-Agents**：与系统交互的自动化 AI Agent
- **用户**：访问记忆系统的人类用户

Agent 和用户均通过 API 接入层与系统交互。

### 2. API 接入层 {#2-api-layer}

API 接入层提供多种接口以访问记忆系统：

- **Python SDK**：Python 应用程序的主要编程接口
- **CLI (`pmem`)**：用于记忆操作、配置、备份/恢复以及交互式 Shell 的命令行接口（参见 [CLI 使用指南](../guides/0012-cli_usage.md)）
- **MCP (Model Context Protocol)**：用于模型上下文管理的标准化协议

API 接入层负责请求路由、身份验证，并为记忆管理层提供统一接口。

### 3. 记忆管理层（记忆引擎） {#3-core-layer-memory-engine}

记忆管理层是 PowerMem 的核心，包含三个主要子组件：

#### 3.1 记忆全生命周期管理 {#31-memory-full-lifecycle-management}

此组件管理完整的记忆生命周期，模拟人类记忆过程：

- **时间/频率强化学习**：基于信息访问的频率和时间实现学习机制
- **艾宾浩斯遗忘曲线理论**：基于赫尔曼·艾宾浩斯的心理学研究，用于记忆保持和衰退的核心算法

#### 3.2 智能记忆处理器 {#32-intelligent-memory-processor}

智能记忆处理器处理核心记忆操作：

- **Memory Add**：通过智能处理创建新记忆
- **Memory Update**：根据新信息修改现有记忆
- **Memory Query**：通过智能排序检索记忆
- **Memory Compression**：通过整合相似记忆优化存储

#### 3.3 分层记忆结构 {#33-layered-memory-structure}

系统将记忆组织为不同的层和范围：

- **用户档案**：与特定用户相关的个性化记忆和数据
- **私有**：为个人专用的记忆
- **短期**：具有自动过期功能的短期记忆存储
- **长期**：用于重要信息的持久记忆存储
- **共享**：可供多个实体（Agent 或用户）访问的记忆

### 4. AI 服务层 {#4-model-layer}

AI 服务层提供 AI 能力：

- **Embedding Models**：将文本转换为向量表示，用于语义搜索
  - 支持的提供商：Qwen、OpenAI、HuggingFace、Azure、AWS Bedrock、Ollama 等
- **LLM Providers**：用于重要性评估和内容理解的大型语言模型
  - 支持的提供商：Qwen、OpenAI、Anthropic、DeepSeek、Ollama 等

记忆管理层与 AI 服务层进行双向通信，以利用 AI 能力进行记忆处理。

### 5. 数据存储层 {#5-storage-layer}

数据存储层负责持久化数据存储：

- **标量存储**：传统的关系型数据存储
- **向量存储**：用于 Embedding 的高维向量存储
- **图存储**：基于关系的图存储，用于复杂记忆关系

支持的存储后端：
- **OceanBase**：默认的企业级可扩展向量数据库
- **PostgreSQL**：带有 pgvector 扩展的开源向量数据库解决方案
- **SQLite**：用于开发的轻量级文件存储
- **自定义适配器**：用于扩展其他存储后端的可扩展架构

## 记忆生命周期 {#memory-lifecycle}

记忆生命周期遵循一个复杂的流程，模拟人类记忆处理：
```
        新信息输入
              ↓
        临时存储
              ↓
        工作记忆
             ↓
    AI 智能评估 / 多维分析
             ↓
        周期性评估
             ↓
        重要性评估
             ↓
    ┌────────┴──────────────────┐
    │                           │
    │                           │
┌───┴──────┐  ┌─────────┐  ┌──────────┐
│ 中等     │  │ 高      │  │ 低       │
│ 重要性   │  │ 重要性  │  │ 重要性   │
└───┬──────┘  └───┬─────┘  └────┬─────┘
    │             │              │
    │             │              │
    │      ┌──────┴──────┐       │
    │      │ 强化学习    │       │
    │      └──────┬──────┘       │
    │             │              │
    │      ┌──────┴──────┐       │
    │      │ 重要性提升  │       │
    │      └──────┬──────┘       │
    │             │              │
    │      ┌──────┴──────┐       │
    │      │ 长期记忆    │       │
    │      └──────┬──────┘       │
    │             │              │
    │      ┌──────┴──────┐       │
    │      │ 永久存储    │       │
    │      └──────┬──────┘       │
    │             │              │
    │      ┌──────┴──────┐       │
    │      │ 知识库      │       │
    │      └─────────────┘       │
    │                            │
    │                  ┌─────────┴─────────┐
    │                  │  遗忘衰减         │
    │                  └─────────┬─────────┘
    │                            │
    │                  ┌─────────┴─────────┐
    │                  │  重要性降低       │
    │                  └─────────┬─────────┘
    │                            │
    │                  ┌─────────┴─────────┐
    │                  │  自动清理         │
    │                  └───────────────────┘
┌───┴───────────────┐
│  短期记忆         │
└───────────────────┘
```
### 阶段 1：信息输入与临时存储 {#stage-1-information-input--temporary-storage}

新信息进入系统后，最初存储在临时存储中。这确保了信息的即时可用性，同时评估过程开始进行。

### 阶段 2：工作记忆 {#stage-2-working-memory}

信息转移到工作记忆中进行主动处理。工作记忆容量有限，用于对信息进行主动操作。

### 阶段 3：AI智能评估 {#stage-3-ai-intelligent-evaluation}

系统使用AI模型进行多维分析：

- **语义分析**：理解信息的意义和上下文
- **重要性评估**：确定信息的重要性
- **周期性评估**：评估频率和规律性模式

### 阶段 4：基于重要性的路由 {#stage-4-importance-based-routing}

根据评估结果，记忆被路由到不同路径：

#### 高重要性 / 高频使用 {#high-importance--frequent-use}
- 触发 **强化学习** 机制
- 导致 **重要性增加**
- 提升为 **长期记忆**
- 转移到 **永久存储**
- 最终存储在 **知识库**
- 使用 **艾宾浩斯遗忘曲线算法** 进行保留管理

#### 中等重要性 {#medium-importance}
- 直接路由到 **短期记忆**
- 进行周期性复习并可能被提升

#### 低重要性 / 很少使用 {#low-importance--seldom-used}
- 触发 **遗忘衰减** 过程
- 导致 **重要性降低**
- 转移到 **自动清理**
- 最终从活动存储中移除

## 核心组件 {#core-components}

### 智能记忆管理器 {#intelligent-memory-manager}

`IntelligentMemoryManager` 协调整个记忆管理过程：

- **元数据处理**：通过重要性评分和记忆类型增强记忆元数据
- **搜索结果处理**：对搜索结果应用智能排序和衰减因子
- **记忆优化**：根据使用模式自动提升、降级或移除记忆

### 重要性评估器 {#importance-evaluator}

`ImportanceEvaluator` 使用LLM能力评估记忆的重要性：

- 分析内容的语义意义
- 考虑上下文和元数据
- 生成重要性评分（0.0 - 1.0）
- 确定适当的记忆类型分类

### 艾宾浩斯算法 {#ebbinghaus-algorithm}

`EbbinghausAlgorithm` 实现遗忘曲线理论：

- **衰减计算**：`R = e^(-t/S)`，其中R为保留率，t为时间，S为强度
- **强化**：当记忆被访问时增加保留强度
- **记忆提升**：根据保留评分自动在层级间提升记忆
- **遗忘检测**：识别应被遗忘或归档的记忆

### 记忆处理器 {#memory-processor}

记忆处理器负责CRUD操作：

- **添加**：通过智能处理创建新记忆
- **更新**：修改现有记忆，可能与相似记忆合并
- **查询**：通过语义搜索和智能排序检索记忆
- **压缩**：合并相似记忆以优化存储

## 数据存储层 {#storage-layer}

### 存储类型 {#storage-types}

powermem 支持多种存储范式：

1. **标量存储**：用于元数据和结构化数据的传统关系型数据库存储
2. **向量存储**：用于基于嵌入的语义搜索的高维向量存储
3. **图存储**：用于复杂记忆互联的关系型存储

### 存储后端 {#storage-backends}

#### OceanBase（默认） {#oceanbase-default}

OceanBase 是 powermem 的默认和推荐存储后端。它提供企业级分布式数据库能力，并支持原生向量存储，非常适合需要高可扩展性和高性能的生产部署。

**关键特性：**
- 企业级分布式数据库
- 原生向量存储支持，优化的向量索引
- 高可扩展性和高性能
- 生产就绪，支持ACID保证
- 高级混合搜索能力（向量 + 全文）
- 支持复杂记忆关系的图存储

**OceanBase 优化**

powermem 包含专为 OceanBase 设计的大量优化，以最大化性能和效率：

##### 1. 自动向量索引配置 {#1-automatic-vector-index-configuration}

系统自动配置 OceanBase 的向量索引设置以实现最佳性能：

- **记忆优化**：自动设置 `ob_vector_memory_limit_percentage = 30`，优化向量操作的内存使用
- **索引类型选择**：支持多种向量索引类型，针对不同用例优化：
  - **HNSW**：分层可导航小世界 - 最适合高维相似性搜索
  - **HNSW_SQ**：带标量量化的HNSW - 内存高效版本
  - **IVFFLAT**：倒排文件平面 - 速度与准确性的良好平衡
  - **IVFSQ**：带标量量化的倒排文件 - 内存高效的IVF版本
  - **IVFPQ**：带乘积量化的倒排文件 - 最大压缩
- **索引参数**：根据索引类型和数据特性自动配置最佳索引参数

##### 2. 混合搜索架构 {#2-hybrid-search-architecture}

powermem 实现了一个复杂的混合搜索系统，将向量相似性搜索与全文搜索结合：
- **并行执行**: 向量搜索和全文搜索通过线程池并发执行，以实现最大性能
- **多种融合方法**:
  - **RRF (Reciprocal Rank Fusion)**: 使用基于排名的评分将两种搜索结果结合（默认，推荐）
  - **加权融合**: 传统的加权分数组合，用于精细化控制
- **全文搜索支持**:
  - 多种解析器支持: `ik`、`ngram`、`ngram2`、`beng`、`space`
  - 自动创建和管理全文索引
  - 参数化查询以确保安全性和性能
  - 回退机制以提高兼容性

##### 3. 数据库操作优化 {#3-database-operation-optimizations}

多种优化措施确保高效的数据库操作：

- **Snowflake ID 生成**: 使用 Snowflake 算法生成分布式 ID，替代自增 ID，实现：
  - 分布式系统中的唯一 ID
  - 多实例部署中无冲突
  - 按时间排序的 ID，支持时间查询
- **Upsert 操作**: 使用 `REPLACE INTO`（upsert）进行高效的插入/更新操作：
  - 原子操作确保数据一致性
  - 自动处理重复数据
  - 减少更新的往返操作
- **事务管理**: 自动事务处理支持：
  - 原子化的多步骤操作
  - 一致性保证
  - 错误时自动回滚
- **复杂查询构建**: 高级 WHERE 子句生成支持：
  - 嵌套的 AND/OR 逻辑
  - 多种比较操作符（eq、ne、gt、gte、lt、lte、in、nin、like、ilike）
  - JSON 元数据过滤
  - 高效的查询优化

##### 4. 图存储优化 {#4-graph-storage-optimizations}

针对基于图的记忆存储的专门优化：

- **多跳图遍历**: 高效的多跳搜索（最多 3 跳），包括：
  - 达到结果限制时提前停止
  - 防止循环以避免无限循环
  - 基于事务的跨跳一致性
  - 内存高效的边限制（max_edges_per_hop）
- **性能优化**:
  - 按提及次数和创建时间对查询结果排序
  - 高效的索引策略（覆盖索引）
  - 实体和关系更新的批量操作
  - 提及计数以评估关系相关性

##### 5. 性能增强 {#5-performance-enhancements}

额外的性能优化：

- **并发操作**: 独立操作的并行执行：
  - 并发向量和全文搜索
  - 在适用情况下的多线程查询执行
- **查询优化**:
  - 基于索引的查询规划
  - 高效的结果分页
  - 在可能情况下提前终止结果
- **内存管理**:
  - 可配置的向量操作内存限制
  - 高效的数据结构用于结果处理
  - 基于堆的 Top-K 选择，用于大结果集

##### 6. 高级功能 {#6-advanced-features}

- **向量维度验证**: 自动验证向量维度以防止运行时错误
- **表结构管理**: 自动创建具有正确结构的表，包括：
  - 具有正确维度的向量列
  - 元数据列（JSON 类型）
  - 标准字段（user_id、agent_id、run_id 等）
  - 全文搜索列
- **索引管理**: 自动索引创建和验证：
  - 具有适当参数的向量索引
  - 使用指定解析器的全文索引
  - 针对常见查询模式的常规索引

这些优化确保 PowerMem 在使用 OceanBase 作为存储后端时能够提供最佳性能，使其适用于高吞吐量和低延迟需求的企业级部署。

#### PostgreSQL (pgvector) {#postgresql-pgvector}

- 开源向量数据库解决方案
- 支持向量操作的 pgvector 扩展
- 强大的生态系统和工具支持

#### SQLite {#sqlite}

- 轻量级、基于文件的存储
- 适合开发和测试
- 单文件部署

#### 自定义适配器 {#custom-adapters}

数据存储层采用适配器模式设计，便于集成新的存储后端。

## AI 服务层 {#model-layer}

### Embedding 提供商 {#embedding-providers}

Embedding 模型将文本转换为向量表示：

- **Qwen**: 阿里云的 Embedding 模型
- **OpenAI**: text-embedding-3-large 及其他模型
- **HuggingFace**: 社区驱动的 Embedding 模型
- **Azure OpenAI**: 微软 Azure 托管的 Embedding
- **AWS Bedrock**: 亚马逊的 Embedding 服务
- **Ollama**: 本地 Embedding 模型支持

### LLM 提供商 {#llm-providers}

大型语言模型提供智能能力：

- **Qwen**: 阿里云的 LLM 模型
- **OpenAI**: GPT-4、GPT-3.5 及其他模型
- **Anthropic**: Claude 模型
- **DeepSeek**: 高级推理模型
- **Ollama**: 本地 LLM 支持
- **Google Gemini**: 谷歌的语言模型

## API 接入层 {#api-layer}

### Python SDK {#python-sdk}

Python 应用的主要接口：
```python
from powermem import Memory, create_memory

# 简单创建
memory = create_memory()

# 添加记忆
memory.add("User prefers Python programming", user_id="user123")

# 搜索记忆
results = memory.search("programming preferences", user_id="user123")
```
### MCP Server {#mcp-server}

MCP Server 提供标准化访问：

- RESTful API 端点
- JSON-RPC 协议支持
- 标准化记忆操作
- 多语言客户端支持

## Multi-Agent 支持 {#multi-agent-support}

PowerMem 提供全面的 Multi-Agent 功能：

### Agent 隔离 {#agent-isolation}

每个 Agent 拥有独立的记忆空间：
- **私有记忆**: 特定于 Agent 的记忆，不与其他 Agent 共享
- **工作记忆**: 每个 Agent 的活动处理记忆
- **短期记忆**: 每个 Agent 的临时存储
- **长期记忆**: 每个 Agent 的持久存储

### Agent 协作 {#agent-collaboration}

Agents 可以通过以下方式协作：
- **Shared Memory**: 多个 Agent 可访问的记忆
- **Collaborative Memory**: 通过 Agent 交互创建的记忆
- **Group Consensus**: 由多个 Agent 验证的记忆

### Memory 作用域 {#memory-scopes}

系统支持不同的记忆范围：

- **Private**: 单个 Agent 或用户的记忆
- **Agent Group**: 在一组 Agents 内共享
- **User Group**: 在一组用户之间共享
- **Public**: 公开可访问的记忆

### 访问控制 {#access-control}

细粒度的权限控制：
- 每个 Agent 的读/写权限
- 基于范围的访问控制
- 隐私保护机制
- 符合性审计日志记录

## 数据流 {#data-flow}

### Memory 添加流程 {#memory-addition-flow}
```
用户/Agent → API 接入层 → 记忆管理层
                              ↓
                    智能记忆处理器
                              ↓
                    重要性评估器（LLM）
                              ↓
                    艾宾浩斯算法处理
                              ↓
                    记忆类型判定
                              ↓
                    数据存储层（向量 + 标量）
                              ↓
                    返回 Memory ID
```
### 记忆查询流程 {#memory-query-flow}
```
用户/Agent → API 接入层 → 记忆管理层
                              ↓
                    查询处理
                              ↓
                    Embedding 生成
                              ↓
                    向量搜索（数据存储层）
                              ↓
                    应用艾宾浩斯衰减
                              ↓
                    相关性排序
                              ↓
                    基于 LLM 的重排序（可选）
                              ↓
                    返回排序结果
```
### 记忆优化流程 {#memory-optimization-flow}
```
定时任务 → 智能记忆管理器
                        ↓
            艾宾浩斯算法
                        ↓
            衰减计算
                        ↓
        ┌───────────────┴───────────────┐
        │                               │
        晋升检查                        遗忘检查
        │                               │
        移动到更高层                    自动清理
        │                               │
        更新保持分数                    从存储中移除
```
## 性能考量 {#performance-considerations}

### 可扩展性 {#scalability}

- **水平扩展**: 数据存储层支持分布式架构
- **缓存**: 智能缓存常访问的记忆
- **批处理**: 批量操作用于大规模记忆更新

### 优化 {#optimization}

- **记忆压缩**: 自动合并相似记忆
- **定期清理**: 定期移除被遗忘的记忆
- **索引优化**: 高效的向量索引以实现快速检索

### 监控 {#monitoring}

- **遥测**: 内置遥测用于性能监控
- **审计日志**: 全面的操作审计记录
- **记忆统计**: 实时记忆统计和健康指标

## 安全与隐私 {#security--privacy}

### 数据保护 {#data-protection}

- **加密**: 数据静态和传输中的加密
- **访问控制**: 细粒度的权限管理
- **隐私保护**: 内置隐私控制以保护敏感数据

### 合规性 {#compliance}

- **审计日志**: 完整的审计记录以满足合规要求
- **数据保留**: 可配置的数据保留策略
- **GDPR 支持**: 符合法规的隐私控制

## 未来增强 {#future-enhancements}

该架构设计支持未来的增强功能：

- **基于图的记忆关系**: 增强的关系建模
- **高级强化学习**: 更复杂的学习算法
- **分布式记忆**: 跨系统记忆同步
- **实时协作**: Agent 间的实时记忆更新

## 结论 {#conclusion}

PowerMem 的架构提供了一个强大、可扩展且智能的记忆管理系统，模拟了人类记忆过程，同时利用了现代 AI 的能力。分层设计确保了生产部署中的灵活性、可扩展性和性能。
