# Memory Bank 设计与实现文档

## 概述

Memory Bank 是 稷下学宫AI辩论系统 的核心组件之一，旨在为每个AI智能体（八仙）提供持久化的记忆能力。通过集成不同的后端实现（如 Google Vertex AI Memory Bank 和 Cloudflare AutoRAG），系统能够灵活地存储、检索和利用智能体在辩论过程中积累的知识和经验。

## 架构设计

### 核心抽象

系统通过 `MemoryBankProtocol` 定义了记忆银行的通用接口，确保了不同后端实现的可替换性。

```python
@runtime_checkable
class MemoryBankProtocol(Protocol):
    async def create_memory_bank(self, agent_name: str, display_name: Optional[str] = None) -> str: ...

    async def add_memory(
        self,
        agent_name: str,
        content: str,
        memory_type: str = "conversation",
        debate_topic: str = "",
        metadata: Optional[Dict[str, Any]] = None,
    ) -> str: ...

    async def search_memories(
        self,
        agent_name: str,
        query: str,
        memory_type: Optional[str] = None,
        limit: int = 10,
    ) -> List[Dict[str, Any]]: ...

    async def get_agent_context(self, agent_name: str, debate_topic: str) -> str: ...

    async def save_debate_session(
        self,
        debate_topic: str,
        participants: List[str],
        conversation_history: List[Dict[str, str]],
        outcomes: Optional[Dict[str, Any]] = None,
    ) -> None: ...
```

### 工厂模式

通过 `get_memory_backend` 工厂函数，系统可以根据配置动态选择合适的记忆后端实现。

```python
def get_memory_backend(prefer: Optional[str] = None) -> MemoryBankProtocol:
    # 根据环境变量 JIXIA_MEMORY_BACKEND 选择后端
    # 支持 "vertex" 和 "cloudflare"
    ...
```

## 后端实现

### Vertex AI Memory Bank

基于 Google Vertex AI 的 Memory Bank 服务实现。

**特点**:
- 与 Google Cloud 生态系统深度集成
- 提供企业级的安全性和可靠性
- 支持复杂的元数据过滤和查询

**配置**:
- `GOOGLE_API_KEY`: Google API 密钥
- `GOOGLE_CLOUD_PROJECT_ID`: Google Cloud 项目ID
- `GOOGLE_CLOUD_LOCATION`: 部署区域 (默认 us-central1)

### Cloudflare AutoRAG

基于 Cloudflare Vectorize 和 Workers AI 实现的向量检索增强生成方案。

**特点**:
- 全球分布的边缘计算网络
- 成本效益高，适合中小型项目
- 易于部署和扩展

**配置**:
- `CLOUDFLARE_ACCOUNT_ID`: Cloudflare 账户ID
- `CLOUDFLARE_API_TOKEN`: 具有 Vectorize 和 Workers AI 权限的 API 令牌

## 使用指南

### 初始化记忆银行

```python
from src.jixia.memory.factory import get_memory_backend

# 根据环境变量自动选择后端
memory_bank = get_memory_backend()

# 或者显式指定后端
memory_bank = get_memory_backend(prefer="cloudflare")
```

### 为智能体创建记忆空间

```python
# 为吕洞宾创建记忆银行/空间
await memory_bank.create_memory_bank("lvdongbin")
```

### 添加记忆

```python
await memory_bank.add_memory(
    agent_name="lvdongbin",
    content="倾向于使用DCF模型评估科技股的内在价值",
    memory_type="preference",
    debate_topic="TSLA投资分析"
)
```

### 搜索记忆

```python
memories = await memory_bank.search_memories(
    agent_name="lvdongbin",
    query="TSLA",
    memory_type="preference"
)
```

### 获取上下文

```python
context = await memory_bank.get_agent_context("lvdongbin", "TSLA投资分析")
```

## 最佳实践

1. **合理分类记忆类型**:
   - `conversation`: 记录对话历史，用于上下文理解和连贯性。
   - `preference`: 存储智能体的偏好和倾向，指导决策过程。
   - `knowledge`: 积累专业知识和数据，提升分析深度。
   - `strategy`: 总结辩论策略和战术，优化表现。

2. **定期维护记忆**:
   - 实施记忆的定期清理和归档策略，避免信息过载。
   - 通过 `save_debate_session` 方法系统性地保存重要辩论会话。

3. **优化搜索查询**:
   - 使用具体、明确的查询词以提高搜索相关性。
   - 结合 `memory_type` 过滤器缩小搜索范围。

4. **错误处理**:
   - 在生产环境中，务必对所有异步操作进行适当的错误处理和重试机制。

## 未来扩展

1. **混合后端支持**: 允许同时使用多个后端，根据数据类型或访问模式进行路由。
2. **记忆压缩与摘要**: 自动对长篇记忆进行摘要，提高检索效率。
3. **情感分析**: 为记忆添加情感标签，丰富检索维度。

---
*此文档旨在为开发者提供 Memory Bank 模块的全面技术参考*