Add teaching Python agent CLI with Poetry and CI

docs/04-memory-and-session.md

@@ -0,0 +1,152 @@
+# 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. 产品经理视角下的总需求句
+
+> 这套产品必须拥有一个分层记忆系统：它既能保存长期偏好与项目背景，又能在上下文预算受限时压缩历史，并在任务恢复、子任务继承和长期协作中重新注入关键事实。