ai-agent-deep-dive/docs/04-memory-and-session.md

# 04. 记忆与会话系统需求文档

## 1. 为什么需要记忆系统

如果产品只靠当前窗口上下文工作，会出现几个问题：

- 用户长期偏好无法沉淀
- 项目背景每次都要重新解释
- 复杂任务容易因上下文压缩而丢失关键事实
- 系统无法逐步形成“协作连续性”

因此，这个产品需要一个多层级记忆系统。

## 2. 记忆系统的产品目标

1. 保存长期有效的用户偏好和协作约束
2. 保存项目级背景信息
3. 在上下文压缩后仍能恢复关键事实
4. 支持会话恢复与后续继续执行
5. 为子任务和后台任务提供必要的上下文继承

## 3. 记忆层级反推

从目录结构与调用链可以推断，产品至少需要以下记忆层级：

### 3.1 用户级记忆
保存：
- 用户语言偏好
- 输出风格偏好
- 常见工作习惯
- 可长期生效的协作规则

### 3.2 项目级记忆
保存：
- 项目目录背景
- 常用命令
- 测试 / 构建约定
- 项目规范文件中的持续性要求

### 3.3 会话级记忆
保存：
- 当前任务目标
- 当前已知上下文
- 本轮执行中的中间状态
- 当前阶段的局部决策

### 3.4 子任务级记忆
保存：
- 子 agent 的任务目标
- 子 agent 的局部上下文
- fork 继承的父上下文
- 验证 / 探索 / 规划等专职子任务的专属状态

## 4. 记忆系统的核心需求

### 4.1 持久化需求
系统需要能保存以下内容：
- 用户长期偏好
- 项目常识
- 会话摘要
- 可恢复的任务元数据

### 4.2 注入需求
系统需要在合适的时机把记忆重新注入到模型上下文中，而不是永久塞在一次请求里。

### 4.3 压缩需求
当上下文接近限制时，系统必须支持：
- 自动压缩历史
- 保留关键事实
- 降低 token 成本

### 4.4 恢复需求
用户中断后再次回来时，系统要支持：
- 恢复当前任务状态
- 恢复关键上下文
- 继续之前的执行链

## 5. Session 管理需求

### 5.1 会话身份
每个会话都需要唯一标识，便于：
- 恢复
- 归档
- 分析
- 分享
- 跟踪任务生命周期

### 5.2 会话摘要
系统需要能够自动生成摘要，用于：
- 历史压缩
- 后续恢复
- 快速理解上下文

### 5.3 会话转录
系统需要持久记录关键消息流，至少包括：
- 用户输入
- 模型输出
- 工具调用摘要
- 子任务结果
- 失败信息

## 6. 为什么记忆不能等于“把所有历史都塞进去”

产品层面必须避免一种错误思路：把完整历史无脑拼进上下文。

这样会导致：
- 成本上升
- 注意力稀释
- 有效信息被噪声淹没
- 子任务污染主线程

更合理的需求是：

> 记忆应该是可选择地提取、压缩、恢复和注入，而不是无节制堆积。

## 7. fork 与记忆的需求关系

从多 agent 设计看，fork 子任务有两个特殊需求：

1. 继承足够的上下文来完成任务
2. 又不能把中间噪声带回主线程

因此系统需要：
- 支持父子上下文有边界地继承
- 支持子任务输出被总结，而不是原样回灌
- 支持 prompt cache 友好的上下文复用

## 8. 记忆系统的伪代码表达

```python
class MemorySystem:
    def load_user_memory(self, user_id):
        ...

    def load_project_memory(self, project_root):
        ...

    def load_session_summary(self, session_id):
        ...

    def build_runtime_context(self, user_memory, project_memory, session_summary):
        return merge_relevant_context(user_memory, project_memory, session_summary)

    def compact_if_needed(self, messages):
        if context_budget_low(messages):
            return summarize(messages)
        return messages
```

## 9. 产品经理视角下的总需求句

> 这套产品必须拥有一个分层记忆系统：它既能保存长期偏好与项目背景，又能在上下文预算受限时压缩历史，并在任务恢复、子任务继承和长期协作中重新注入关键事实。