liurenchaxin/modules/documentation-suite/docs/VERTEX_MEMORY_BANK_SETUP.md

# Vertex AI Memory Bank 配置指南

## 🏛️ 稷下学宫记忆银行集成

本文档介绍如何为稷下学宫AI辩论系统配置和使用Vertex AI Memory Bank功能。

## 📋 前置要求

### 1. Google Cloud 项目设置
- 有效的 Google Cloud 项目
- 启用 Vertex AI API
- 配置适当的 IAM 权限

### 2. 必需的依赖
```bash
pip install google-cloud-aiplatform>=1.38.0
pip install google-adk  # 或开发版本
```

### 3. 环境变量配置
在 Doppler 或本地环境中设置以下变量：

```bash
# 必需配置
GOOGLE_API_KEY=your_gemini_api_key
GOOGLE_CLOUD_PROJECT_ID=your-project-id

# 可选配置
GOOGLE_CLOUD_LOCATION=us-central1  # 默认区域
VERTEX_MEMORY_BANK_ENABLED=TRUE    # 启用记忆银行
GOOGLE_SERVICE_ACCOUNT_KEY=path/to/service-account.json  # 服务账号密钥
```

## 🚀 快速开始

### 1. 验证配置
```bash
# 验证 Google ADK 配置
python config/settings.py

# 测试 Memory Bank 连接
python tests/test_vertex_memory_bank.py
```

### 2. 初始化八仙记忆银行
```python
from src.jixia.memory.vertex_memory_bank import initialize_baxian_memory_banks

# 初始化所有八仙的记忆银行
memory_bank = await initialize_baxian_memory_banks(
    project_id="your-project-id",
    location="us-central1"
)
```

### 3. 创建记忆增强智能体
```python
from src.jixia.agents.memory_enhanced_agent import create_memory_enhanced_council

# 创建记忆增强的八仙议会
council = await create_memory_enhanced_council()

# 进行记忆增强辩论
result = await council.conduct_memory_debate(
    topic="NVIDIA股票投资分析",
    participants=["tieguaili", "lvdongbin", "hexiangu"],
    rounds=3
)
```

## 🎭 八仙记忆特性

每位仙人都有独特的记忆重点和学习模式：

### 铁拐李 (逆向投资大师)
- **记忆重点**: 市场异常、逆向案例、风险警示、反向策略
- **学习模式**: 关注市场共识的反面，记住历史上的逆向成功案例

### 吕洞宾 (理性分析者)
- **记忆重点**: 技术分析、数据洞察、逻辑推理、理性决策
- **学习模式**: 基于数据和逻辑的严密分析，记住成功的分析框架

### 何仙姑 (直觉洞察者)
- **记忆重点**: 市场情绪、直觉判断、情感因素、人性洞察
- **学习模式**: 关注市场情绪变化，记住情感驱动的市场事件

### 张果老 (历史智慧者)
- **记忆重点**: 历史案例、长期趋势、周期规律、经验教训
- **学习模式**: 从历史中学习，记住重要的历史模式和教训

### 汉钟离 (平衡协调者)
- **记忆重点**: 平衡策略、综合分析、协调方案、稳健建议
- **学习模式**: 寻求各方观点的平衡，记住成功的协调案例

### 蓝采和 (创新思维者)
- **记忆重点**: 创新机会、新兴趋势、潜力发现、灵活策略
- **学习模式**: 发现新兴机会，记住创新投资的成功案例

### 韩湘子 (艺术感知者)
- **记忆重点**: 美学趋势、创意洞察、感性分析、艺术视角
- **学习模式**: 从美学角度分析市场，记住艺术和创意相关的投资

### 曹国舅 (实务执行者)
- **记忆重点**: 执行策略、机构动向、实务操作、专业分析
- **学习模式**: 关注实际执行，记住机构操作和专业分析

## 🔧 高级配置

### 1. 自定义记忆类型
```python
# 支持的记忆类型
MEMORY_TYPES = [
    "conversation",  # 对话记忆
    "preference",    # 偏好记忆
    "knowledge",     # 知识记忆
    "strategy"       # 策略记忆
]

# 添加自定义记忆
await memory_bank.add_memory(
    agent_name="tieguaili",
    content="在熊市中，逆向投资策略往往更有效",
    memory_type="strategy",
    debate_topic="市场策略",
    metadata={
        "market_condition": "bear_market",
        "confidence": 0.8,
        "source": "historical_analysis"
    }
)
```

### 2. 记忆搜索和过滤
```python
# 搜索特定类型的记忆
strategy_memories = await memory_bank.search_memories(
    agent_name="tieguaili",
    query="逆向投资",
    memory_type="strategy",
    limit=10
)

# 获取智能体的完整上下文
context = await memory_bank.get_agent_context(
    agent_name="tieguaili",
    debate_topic="NVIDIA投资分析"
)
```

### 3. 辩论会话保存
```python
# 自动保存辩论会话
await memory_bank.save_debate_session(
    debate_topic="比特币投资价值",
    participants=["tieguaili", "lvdongbin", "hexiangu"],
    conversation_history=conversation_history,
    outcomes={
        "winner": "tieguaili",
        "key_insights": ["逆向思维在加密货币投资中的重要性"],
        "consensus": "需要更谨慎的风险管理"
    }
)
```

## 📊 监控和管理

### 1. 记忆银行状态检查
```python
# 检查记忆银行状态
for agent_name, bank_name in memory_bank.memory_banks.items():
    chinese_name = memory_bank.baxian_agents[agent_name]
    print(f"{chinese_name}: {bank_name}")
```

### 2. 记忆使用统计
```python
# 获取记忆统计信息
stats = await memory_bank.get_memory_stats(agent_name="tieguaili")
print(f"总记忆数: {stats['total_memories']}")
print(f"对话记忆: {stats['conversation_count']}")
print(f"策略记忆: {stats['strategy_count']}")
```

### 3. 记忆清理和维护
```python
# 清理过期记忆（如果需要）
await memory_bank.cleanup_old_memories(
    agent_name="tieguaili",
    days_old=30,
    memory_type="conversation"
)
```

## 🔒 安全和隐私

### 1. 数据加密
- 所有记忆数据在传输和存储时都会加密
- 使用 Google Cloud 的企业级安全措施

### 2. 访问控制
- 每个智能体只能访问自己的记忆银行
- 通过 IAM 控制项目级别的访问权限

### 3. 数据保留
- 可以配置记忆数据的保留期限
- 支持手动删除敏感记忆

## 🚨 故障排除

### 常见问题

#### 1. 项目ID未配置
```
❌ Google Cloud Project ID 未配置
```
**解决方案**: 设置 `GOOGLE_CLOUD_PROJECT_ID` 环境变量

#### 2. API权限不足
```
❌ 403 Forbidden: Vertex AI API access denied
```
**解决方案**: 
- 在 Google Cloud Console 中启用 Vertex AI API
- 确保服务账号有适当的权限

#### 3. 记忆银行创建失败
```
❌ 创建记忆银行失败: Region not supported
```
**解决方案**: 
- 检查 `GOOGLE_CLOUD_LOCATION` 设置
- 使用支持 Memory Bank 的区域（如 us-central1）

#### 4. 依赖包缺失
```
❌ Google Cloud AI Platform 未安装
```
**解决方案**: 
```bash
pip install google-cloud-aiplatform>=1.38.0
```

### 调试模式
```python
# 启用详细日志
import logging
logging.basicConfig(level=logging.DEBUG)

# 测试连接
python tests/test_vertex_memory_bank.py
```

## 📚 参考资源

- [Vertex AI Memory Bank 官方文档](https://cloud.google.com/blog/products/ai-machine-learning/vertex-ai-memory-bank-in-public-preview)
- [Google ADK 文档](https://github.com/google/adk-python)
- [稷下学宫项目文档](../README.md)

## 🤝 贡献指南

如果你想为 Memory Bank 功能贡献代码：

1. 确保所有新功能都有对应的测试
2. 遵循现有的代码风格和注释规范
3. 更新相关文档
4. 提交 Pull Request 前运行完整的测试套件

---

**让AI辩论照亮投资智慧，记忆银行让智慧永续传承** 🏛️✨