企业级多Agent角色协同记忆系统

# Memory Service - 设计背景与初衷

> **🔒 文档状态:** ✅ 已锁定（v1.0.0）| 锁定日期: 2025-10-01
>
> **变更控制:** 本文档已进入锁定状态，核心设计理念变更需经团队评审。提交变更请使用 [变更请求模板](../../.github/ISSUE_TEMPLATE/memory-service-change-request.md)。

**文档版本:** v1.0.0
**最后更新:** 2025-10-01
**状态:** 🔒 已锁定

---

## 🎯 设计初衷

### 核心问题
在使用 Claude Code CLI 进行多角色协作开发时，我们面临以下关键挑战：

#### 1. **上下文断裂问题**
```
场景：后端开发 Agent 完成 API 开发后，前端开发 Agent 接手
问题：前端 Agent 不知道后端做了什么决策、为什么这样设计
结果：❌ 重复沟通、理解偏差、返工
```

#### 2. **决策追溯困难**
```
场景：一周后发现系统架构有问题
问题：当时为什么选择 PostgreSQL 而不是 MongoDB？谁批准的？
结果：❌ 无法追溯决策链，责任不清，难以复盘
```

#### 3. **监督盲区**
```
场景：监督 Agent 检测到可疑代码变更
问题：这个变更是谁做的？基于什么背景？经过审批了吗？
结果：❌ 无法有效监督，质量风险高
```

#### 4. **协作混乱**
```
场景：5 个不同角色的 Agent 同时工作
问题：谁在做什么？谁等待谁？有没有冲突？
结果：❌ 协作效率低，容易产生冲突
```

#### 5. **知识丢失**
```
场景：项目开发 3 个月后，新 Agent 加入
问题：如何快速了解项目历史、技术选型、已踩过的坑？
结果：❌ 学习成本高，重复犯错
```

#### 6. **多租户隔离挑战**
```
场景：SaaS 平台需要为多个企业客户提供服务
问题：如何确保企业 A 的记忆不会泄露给企业 B？
结果：❌ 数据安全风险，合规问题
```

---

## 🧠 设计理念

### **"一切皆记忆"原则**

受人类大脑工作机制启发，我们认为：

> **有效的协作需要共享的、可追溯的、分层的记忆系统**

### 三层记忆架构

```
┌─────────────────────────────────────┐
│  工作记忆 (Working Memory)          │  ← 最近 10-20 条消息
│  - 即时上下文                       │     实时访问
│  - 当前任务状态                     │     低延迟
└─────────────────────────────────────┘
              ↓ 定期归档
┌─────────────────────────────────────┐
│  短期记忆 (Short-term Memory)       │  ← 最近 7-30 天
│  - 项目活动历史                     │     快速检索
│  - 关键决策记录                     │     结构化存储
└─────────────────────────────────────┘
              ↓ 压缩提炼
┌─────────────────────────────────────┐
│  长期记忆 (Long-term Memory)        │  ← 全生命周期
│  - 项目知识库                       │     语义搜索
│  - 最佳实践                         │     向量化存储
│  - 经验教训                         │
└─────────────────────────────────────┘
```

### 企业级数据隔离

在多租户环境中，数据隔离是核心要求：

```
┌─────────────────────────────────────────────────┐
│  Enterprise A (企业 A)                          │
│  ├── Solution 1 (解决方案 1)                     │
│  │   ├── Project X                             │
│  │   └── Project Y                             │
│  └── Solution 2 (解决方案 2)                     │
│      └── Project Z                             │
│                                                 │
│  ✅ 所有记忆都带有 enterprise_id 标识            │
│  ✅ 数据库层级强制隔离                           │
│  ✅ 跨企业访问完全禁止                           │
└─────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────┐
│  Enterprise B (企业 B)                          │
│  ├── Solution 3                                │
│  └── Solution 4                                │
│                                                 │
│  🔒 与企业 A 的数据完全隔离                      │
│  🔒 独立的归档策略和权限管理                     │
└─────────────────────────────────────────────────┘
```

**设计原则：**
- 所有数据表都包含 enterprise_id 字段（强制非空）
- 数据库索引优先使用 enterprise_id 分区
- API 层面自动注入企业上下文，防止跨企业访问
- 审计日志记录所有跨边界访问尝试

---

## 🌟 核心价值

### 1. **可追溯性 (Traceability)**

**问题：** 代码是谁写的？为什么这样写？

**解决：** 每条消息、每个决策、每次代码变更都有明确的角色标识和时间戳

```sql
-- 追溯任意代码行的完整历史
SELECT
    cc.file_path,
    cc.operation,
    r.name as author,
    cc.reason,
    d.context as decision_context,
    cc.committed_at
FROM code_changes cc
JOIN roles r ON cc.author_role_id = r.id
LEFT JOIN decisions d ON cc.decision_id = d.id
WHERE cc.file_path LIKE '%auth.ts%'
ORDER BY cc.committed_at DESC;
```

### 2. **可恢复性 (Recoverability)**

**问题：** Agent 重启后忘记了之前的对话

**解决：** 任意时间点恢复完整上下文

```typescript
// 恢复后端开发 Agent 的工作状态
const context = await memoryService.recoverContext({
  roleId: 'backend-uuid',
  depth: 'full', // minimal/standard/full
  timeRange: '7d'
});

// context 包含：
// - 最近的对话历史
// - 未完成的任务
// - 待处理的决策
// - 协作请求
// - 代码变更记录
```

### 3. **可审计性 (Auditability)**

**问题：** 监督 Agent 如何验证工作质量？

**解决：** 完整的审计日志和决策链

```typescript
// 审计报告：某个决策的完整生命周期
{
  "decision_id": "uuid",
  "initiated_by": "backend-dev",
  "initiated_at": "2025-10-01T10:30:00Z",
  "context": "修改用户认证逻辑，从 Session 改为 JWT",
  "votes": [
    {
      "voter": "supervisor-security",
      "vote": "approve",
      "reason": "JWT 更安全，支持分布式",
      "voted_at": "2025-10-01T10:35:00Z"
    },
    {
      "voter": "supervisor-performance",
      "vote": "approve",
      "reason": "减少数据库查询，性能更好",
      "voted_at": "2025-10-01T10:36:00Z"
    }
  ],
  "final_result": "approved",
  "implemented_at": "2025-10-01T10:40:00Z",
  "code_changes": [
    "src/auth/session.ts -> deleted",
    "src/auth/jwt.ts -> created"
  ]
}
```

### 4. **可协作性 (Collaborability)**

**问题：** 多角色 Agent 如何高效协作？

**解决：** 共享记忆池 + 角色隔离

```
┌──────────────────────────────────────────────┐
│           共享项目记忆池                      │
├──────────────────────────────────────────────┤
│  ✅ 所有人可见：                             │
│    - 项目需求文档                            │
│    - API 接口定义                            │
│    - 架构决策记录                            │
│    - 代码规范                                │
├──────────────────────────────────────────────┤
│  🔒 角色隔离：                               │
│    - 后端 Agent 只看后端相关消息              │
│    - 前端 Agent 只看前端相关消息              │
│    - 监督 Agent 可以看所有角色               │
└──────────────────────────────────────────────┘
```

### 5. **可学习性 (Learnability)**

**问题：** Agent 如何避免重复犯错？

**解决：** 从历史中学习

```typescript
// 查询类似场景的历史决策
const similarDecisions = await memoryService.searchSimilar({
  query: "如何实现用户认证",
  context: "需要支持 OAuth2 和手机验证码",
  projectId: "uuid",
  limit: 5
});

// 返回：
// - 3 个月前类似问题的解决方案
// - 当时的决策过程
// - 实施后的反馈
// - 遇到的问题和解决方法
```

### 6. **企业级管理 (Enterprise Management)**

**问题：** SaaS 平台如何管理多个企业客户的数据？

**解决：** 企业维度的完整隔离和管理

```typescript
// 企业管理员查看企业整体数据
const enterpriseStats = await memoryService.getEnterpriseStatistics({
  enterpriseId: 'enterprise-abc',
  timeRange: '30d'
});

// 返回：
// - 所有解决方案的活跃度
// - 企业级决策记录
// - 数据存储使用量
// - 合规性检查报告
// - 跨解决方案协作情况

// 企业级数据隔离保证
const searchResults = await memoryService.search({
  query: "用户认证",
  enterpriseId: "enterprise-abc"  // 自动限制搜索范围
});
// ✅ 只返回本企业的记忆
// ❌ 绝不会返回其他企业的数据
```

### 7. **多租户隔离 (Multi-Tenancy Isolation)**

**问题：** 如何确保企业间数据完全隔离？

**解决：** 数据库级别的强制隔离

```sql
-- 所有查询自动添加企业过滤
-- Row-Level Security (RLS) 策略
CREATE POLICY enterprise_isolation ON messages
    USING (enterprise_id = current_setting('app.current_enterprise_id')::UUID);

-- 防止跨企业数据泄露
SELECT * FROM messages WHERE id = 'xxx';
-- 自动转换为：
-- SELECT * FROM messages
-- WHERE id = 'xxx'
--   AND enterprise_id = current_setting('app.current_enterprise_id')::UUID;
```

**安全保障：**
- 应用层：每个请求必须携带企业标识
- 数据库层：RLS 策略强制隔离
- 审计层：记录所有跨边界访问尝试
- 归档层：企业级独立归档策略

---

## 🏗️ 架构设计原则

### 1. **角色为中心 (Role-Centric)**

**传统方式：** 以会话(Session)为中心
```
问题：会话结束后，角色的工作历史碎片化
```

**我们的方式：** 以角色(Role)为中心
```
优势：
- 角色的完整工作历史
- 跨会话的连续性
- 角色间的协作关系可视化
```

### 2. **时间轴可回溯 (Timeline Reversible)**

**设计：** 任意时间点的状态快照
```sql
-- 回到 3 天前的项目状态
SELECT * FROM timeline_snapshot
WHERE project_id = :id
  AND created_at <= NOW() - INTERVAL '3 days'
ORDER BY created_at DESC LIMIT 1;
```

**应用场景：**
- 🔄 回退到某个稳定版本
- 🔍 复现历史问题
- 📊 分析开发进度

### 3. **分层存储 (Layered Storage)**

```
┌─────────────────────────────────────┐
│  Redis (工作记忆)                   │  ← 毫秒级
│  - 当前会话状态                     │
│  - 最近 20 条消息                   │
└─────────────────────────────────────┘
              ↓
┌─────────────────────────────────────┐
│  PostgreSQL (短期记忆)              │  ← 秒级
│  - 完整对话历史                     │
│  - 决策和代码变更                   │
└─────────────────────────────────────┘
              ↓
┌─────────────────────────────────────┐
│  Vector DB (长期记忆)               │  ← 语义搜索
│  - Embedding 后的知识                │
│  - 项目文档和最佳实践               │
└─────────────────────────────────────┘
```

### 4. **渐进式遗忘 (Progressive Forgetting)**

**灵感：** 人类大脑会遗忘不重要的细节

**实现：**
```typescript
// 记忆重要性评分
interface MemoryImportance {
  immediate: number;    // 即时重要性 (1-10)
  strategic: number;    // 战略重要性 (1-10)
  referenceCount: number; // 被引用次数
  decayRate: number;    // 衰减速率
}

// 根据重要性决定保留策略
if (importance.strategic > 8) {
  // 永久保留（如架构决策）
  retention = 'permanent';
} else if (importance.immediate > 5) {
  // 保留 30 天（如日常对话）
  retention = '30d';
} else {
  // 压缩后归档（如调试日志）
  retention = 'archived';
}
```

---

## 🔄 与 Claude CLI 的集成理念

### **无侵入式记录**

通过 Hooks 机制，在不修改 Claude CLI 代码的前提下实现记录：

```json
{
  "hooks": {
    "UserPromptSubmit": [{
      "hooks": [{
        "type": "command",
        "command": "node memory-service/record.js user"
      }]
    }],
    "Stop": [{
      "hooks": [{
        "type": "command",
        "command": "node memory-service/record.js assistant"
      }]
    }],
    "PreToolUse": [{
      "matcher": "Write|Edit",
      "hooks": [{
        "type": "command",
        "command": "node memory-service/record-change.js"
      }]
    }]
  }
}
```

### **最小化性能影响**

```typescript
// 异步写入，不阻塞 Claude CLI
async function recordMessage(message: Message) {
  // 立即返回，后台处理
  setImmediate(async () => {
    await messageQueue.add('record', message);
  });
}

// 批量写入，减少数据库压力
messageQueue.process('record', async (job) => {
  const batch = await messageQueue.getJobs(['waiting'], 0, 100);
  await db.batchInsert('messages', batch.map(j => j.data));
});
```

---

## 📊 成功指标

记忆模块的价值通过以下指标衡量：

### 1. **上下文恢复准确率**
```
目标：Agent 恢复后能正确理解 95% 的历史上下文
测量：人工评估恢复的上下文是否完整
```

### 2. **决策追溯完整性**
```
目标：100% 的决策可追溯到原始背景和投票记录
测量：随机抽查决策记录的完整性
```

### 3. **协作效率提升**
```
目标：多角色协作时，重复沟通减少 60%
测量：统计"这是为什么"、"之前做了什么"类问题的频率
```

### 4. **知识复用率**
```
目标：类似问题能在 3 秒内找到历史解决方案
测量：语义搜索的召回率和响应时间
```

### 5. **存储成本**
```
目标：每个项目每月存储成本 < $5
测量：数据库大小 × 单位成本
```

---

## 🚀 演进路线

### Phase 1: 基础记忆 (当前)
- ✅ 消息和决策的完整记录
- ✅ 角色标识体系
- ✅ 基础查询和恢复
- ✅ 五级层级体系（Enterprise → Solution → Project → Role → Session）

### Phase 2: 智能记忆 (3 个月)
- 🔄 语义搜索（Vector DB）
- 🔄 自动摘要生成
- 🔄 记忆重要性评分
- 🔄 企业级数据分析和报表

### Phase 3: 主动记忆 (6 个月)
- 🔮 预测性推荐（"你可能需要查看..."）
- 🔮 异常模式检测（"这次决策与历史不一致"）
- 🔮 知识图谱构建
- 🔮 跨解决方案的知识关联发现

### Phase 4: 分布式记忆 (12 个月)
- 🌐 跨项目知识迁移
- 🌐 企业级知识库（跨解决方案共享）
- 🌐 行业最佳实践库
- 🌐 联邦学习（企业间知识共享，保护隐私）

### Phase 5: 企业智能 (18 个月)
- 🚀 企业级 AI 助手（基于全企业记忆）
- 🚀 自动化合规检查和报告
- 🚀 智能归档和成本优化
- 🚀 跨企业对标分析（匿名化）

---

## 💡 设计哲学

### **"记忆是协作的基石"**

没有记忆的 Agent 就像失忆症患者，每次对话都是从零开始。

**我们相信：**

1. **透明化** - 所有决策可见、可追溯
2. **连续性** - Agent 的工作有连贯的上下文
3. **可问责** - 每个行为都有明确的责任主体
4. **可学习** - 从历史中吸取经验，避免重复犯错
5. **可协作** - 共享记忆让多角色协作成为可能

---

## 🎯 总结

Memory Service 不仅仅是数据库，而是：

- 🧠 **多 Agent 的共享大脑**
- 📚 **项目的知识中枢**
- 🔍 **决策的审计系统**
- 🤝 **协作的基础设施**
- 📈 **组织的学习平台**
- 🏢 **企业的记忆资产**（新增）
- 🔒 **多租户的安全隔离**（新增）

**核心目标：** 让每个 Agent 都能在正确的上下文中，做出高质量的决策，并与其他 Agent 高效协作。同时，在多租户环境下，确保企业数据的完全隔离和安全。

---

## ✅ 已决策问题（设计确定）

### 1. 数据保留策略

**决策：** 采用**四级存储策略**，平衡性能和成本

| 存储级别 | 保留时长 | 存储位置 | 访问性能 | 说明 |
|---------|---------|---------|---------|------|
| **Hot** | 30 天 | PostgreSQL 主库 + Redis | < 100ms | 频繁访问的活跃数据 |
| **Warm** | 90 天 | PostgreSQL 主库（分区） | < 500ms | 偶尔访问的历史数据 |
| **Cold** | 365 天 | PostgreSQL 归档分区 | < 2s | 很少访问的长期数据 |
| **Archive** | 永久（可选） | 对象存储（S3/OSS）| < 10s | 合规和审计需要的历史存档 |

**特殊规则：**
- ✅ 决策记录：永久保留（不删除）
- ✅ 高质量消息（quality_score > 0.8）：永久保留
- ✅ 关键标签（`critical`, `milestone`）：永久保留
- ✅ 已提交的代码变更：永久保留
- ⏰ 自动归档：每日凌晨 2:00 执行

### 2. 隐私和安全

**决策：** 采用**自动脱敏 + 加密存储**双重保护

#### 2.1 自动脱敏规则

```typescript
// 敏感信息正则匹配和脱敏
const SENSITIVE_PATTERNS = {
  apiKey: /sk-[a-zA-Z0-9]{32,}/g,           // API Key
  password: /password[=:]\s*['"]?([^'"\s]+)/gi,  // 密码
  token: /token[=:]\s*['"]?([^'"\s]+)/gi,   // Token
  email: /[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}/g,  // 邮箱（保留域名）
  phone: /1[3-9]\d{9}/g,                    // 手机号
  idCard: /\d{17}[\dXx]/g,                  // 身份证
  creditCard: /\d{4}[\s-]?\d{4}[\s-]?\d{4}[\s-]?\d{4}/g  // 银行卡
};

// 脱敏策略
apiKey: 'sk-***********cdef'      // 保留前缀和后4位
password: 'password=***'           // 完全隐藏
email: 'user***@example.com'       // 保留部分用户名和域名
phone: '138****5678'               // 保留前3后4位
```

#### 2.2 加密存储

- **敏感字段加密：** 使用 AES-256-GCM 加密（密钥通过 KMS 管理）
- **数据传输加密：** PostgreSQL SSL/TLS 连接
- **日志脱敏：** 所有日志输出自动脱敏

### 3. 存储预算

**决策：** 采用**梯度定价**，根据企业规模设定配额

| 订阅级别 | 存储配额 | 月度 Token | 项目数 | 预估成本/月 |
|---------|---------|-----------|-------|-----------|
| **Free** | 1 GB | 100K | 3 | $0 |
| **Starter** | 10 GB | 1M | 10 | $9 |
| **Professional** | 100 GB | 10M | 50 | $49 |
| **Enterprise** | 1 TB | 100M | 无限 | $199 |

**成本控制：**
- ✅ 自动归档到对象存储（成本降低 80%）
- ✅ 数据压缩（JSONB、TEXT 字段 gzip 压缩）
- ✅ 定期清理零散会话（30 天无活动自动归档）
- ✅ 配额预警（达到 80% 自动通知）

**目标：** 单企业平均存储成本 < $10/月

### 4. 备份策略

**决策：** 采用**增量备份 + 定期全量**策略

#### 4.1 备份频率

| 备份类型 | 频率 | 保留时长 | 说明 |
|---------|------|---------|------|
| **全量备份** | 每周日 02:00 | 4 周 | 完整数据库快照 |
| **增量备份** | 每日 02:00 | 7 天 | WAL 日志增量 |
| **实时归档** | 持续 | 永久 | WAL 归档到对象存储 |

#### 4.2 备份存储

- **主备份：** 对象存储（S3/OSS）- 跨区域复制
- **灾备：** 异地机房（每周全量同步）
- **加密：** AES-256 加密存储

#### 4.3 恢复目标

- **RPO（恢复点目标）：** < 1 小时（最多丢失 1 小时数据）
- **RTO（恢复时间目标）：** < 4 小时（4 小时内恢复服务）

### 5. 企业隔离

**决策：** 采用**逻辑隔离（Row-Level Security）+ 索引分区**，不采用物理分库

#### 5.1 逻辑隔离优势

✅ **成本更低：** 单数据库实例，运维成本低
✅ **扩展性好：** 新增企业无需创建数据库
✅ **备份简单：** 统一备份策略
✅ **跨企业分析：** 管理员可进行整体数据分析（脱敏后）

#### 5.2 安全保障

```sql
-- Row-Level Security 策略
CREATE POLICY enterprise_isolation ON messages
  FOR ALL
  USING (enterprise_id = current_setting('app.current_enterprise_id')::UUID);

-- 索引分区（提升查询性能）
CREATE INDEX idx_messages_enterprise_partition
  ON messages (enterprise_id, created_at DESC)
  PARTITION BY LIST (enterprise_id);
```

#### 5.3 未来升级路径

如需物理隔离（高安全要求客户）：
- 提供**独立部署版本**（单租户模式）
- 或采用**PostgreSQL Schema 隔离**（一个 DB，多个 Schema）

### 6. 合规要求

**决策：** 支持 **GDPR、CCPA、等保 2.0** 三大合规框架

#### 6.1 GDPR（欧盟数据保护条例）

| 要求 | 实现方式 |
|------|---------|
| **数据可携带权** | 提供数据导出 API（JSON/CSV 格式）|
| **被遗忘权** | 支持完全删除企业和用户数据（硬删除选项）|
| **数据最小化** | 仅收集必要字段，敏感信息自动脱敏 |
| **数据处理透明** | 记录所有数据访问和修改日志（audit_log）|
| **数据驻留** | 支持指定数据存储区域（欧盟、美国、中国）|

#### 6.2 CCPA（加州消费者隐私法）

| 要求 | 实现方式 |
|------|---------|
| **知情权** | 数据访问日志可查询 |
| **删除权** | 用户可请求删除个人数据 |
| **选择退出** | 支持禁用数据分析和自动标签 |

#### 6.3 等保 2.0（中国信息安全等级保护）

| 要求 | 实现方式 |
|------|---------|
| **访问控制** | 基于角色的权限管理（RBAC）|
| **审计日志** | 所有操作记录审计日志，保留 6 个月 |
| **数据加密** | 传输加密（TLS）+ 存储加密（AES-256）|
| **备份恢复** | 每日备份，异地灾备 |

#### 6.4 合规功能开关

```typescript
// 企业级合规配置
{
  compliance: {
    gdpr: true,         // 启用 GDPR 合规模式
    ccpa: true,         // 启用 CCPA 合规模式
    dataResidency: 'EU', // 数据驻留区域
    retentionYears: 7,  // 数据保留年限（法律要求）
    auditLogRetention: 180  // 审计日志保留天数
  }
}
```

### 7. 跨企业协作

**决策：** **默认禁止**跨企业数据共享，提供**受控的知识共享机制**（未来功能）

#### 7.1 当前版本（v1.x）

🚫 **完全隔离：** 企业间数据完全隔离，禁止任何形式的跨企业访问

#### 7.2 未来规划（v2.x+）

提供可选的**知识共享市场**（需企业明确授权）：

```typescript
// 企业 A 分享最佳实践（脱敏后）
await memory.knowledge.share({
  scope: 'public',  // 公开到知识市场
  content: {
    title: 'React 性能优化最佳实践',
    summary: '...',
    tags: ['react', 'performance'],
    sensitivity: 'public'  // 必须标记为公开
  },
  consent: {
    dataResidency: true,  // 数据仍存储在本企业
    analytics: false      // 不允许统计分析
  }
});

// 企业 B 订阅知识
await memory.knowledge.subscribe({
  tags: ['react', 'performance'],
  source: 'marketplace'
});
```

**安全保障：**
- ✅ 所有分享内容自动脱敏
- ✅ 需要企业管理员明确授权
- ✅ 审计日志记录所有跨企业访问
- ✅ 可随时撤回分享

---

## 🎯 设计原则总结

基于以上决策，Memory Service 遵循以下核心原则：

1. **安全优先** - 数据隔离、加密、脱敏三重保护
2. **合规导向** - 满足 GDPR/CCPA/等保要求
3. **存储模式** - 智能归档
4. **性能优化** - 四级存储，热数据 < 100ms 响应
5. **可恢复性** - RPO < 1h，RTO < 4h
6. **灵活扩展** - 支持从逻辑隔离到物理隔离的升级路径

---