Memory 系统与元思考机制

状态：已实现（2026-04）。本文档同时承担设计理由和使用规范。入口、工具、API 清单见文末"十、实现与入口"。一~九节解释"为什么这么做"，改动前请先读懂论证。

概述

本文档设计两个紧密关联的能力：

Memory：为需要跨任务维持身份的 Agent 提供持久化记忆（Markdown 文件）
统一元思考机制：整合现有的知识提取（reflection）、知识评估（knowledge_eval）和新增的记忆反思（dream），形成完整的"Agent 自我认知"能力

一、现有元思考机制梳理

当前框架已实现两种元思考能力，都基于侧分支（side branch）机制：

1.1 知识提取（reflection 侧分支）

目的：从执行过程中提取客观知识，保存到 KnowHub（全局共享知识库）。

触发时机：

压缩前（_manage_context_usage，runner.py:825-829）
任务完成后（runner.py:1834-1838，enable_completion_extraction）

输出：调用 upload_knowledge 工具，保存 experience/tool/strategy/case 到 KnowHub。

Prompt：REFLECT_PROMPT（压缩时）和 COMPLETION_REFLECT_PROMPT（任务完成后），定义在 agent/core/prompts/knowledge.py。

已知问题：任务完成时触发的 reflection 使用 config.knowledge.get_reflect_prompt()（runner.py:1249），没有区分压缩场景和完成场景。应该在完成场景使用 get_completion_reflect_prompt()。

1.2 知识评估（knowledge_eval 侧分支）

目的：评估被注入的知识是否有用，记录到本地 knowledge_log.json。

触发时机（详见 knowhub/docs/cognition-log-plan.md）：

Goal 完成时（store.py:update_goal，设置 pending_knowledge_eval 标志）
压缩前（必须在压缩前完成评估，否则执行上下文丢失）
任务结束时（兜底）

输出：每条被注入的知识获得评估（irrelevant / unused / helpful / harmful / neutral），写入 knowledge_log.json。

当前局限：评估结果只存本地，不自动回传 KnowHub。只有用户通过 API 手动反馈才同步。

1.3 侧分支队列机制

两种元思考通过 force_side_branch 队列协调执行顺序（runner.py:1198-1207）：

压缩触发时的典型队列：
  ["reflection", "knowledge_eval", "compression"]
  
任务完成时：
  ["knowledge_eval"]（先评估）→ ["reflection"]（再提取）

每个侧分支执行完后 pop 队首，继续下一个，直到队列清空回到主路径。

二、缺失的能力：个人记忆

问题

现有的两种元思考都面向全局共享知识（KnowHub）。但有一类 Agent 需要维护主观的、属于自己的长期记忆：

品味偏好、策略判断、风格积累、用户反馈
属于特定 Agent 身份，不是公共知识
需要人类能直接阅读和修改
跨多次 trace 持续积累和演化
可能被同一身份下的多个 Agent run 共享读写

KnowHub 不适合承担这个职责——它是"大众点评"，不是"个人日记"。

记忆文件

记忆以 Markdown 文件存储在指定目录下。每个文件覆盖一个语义维度。

{base_path}/
├── taste.md        # 偏好判断
├── strategy.md     # 当前策略
├── skills.md       # 积累的技巧
└── ...

为什么是 Markdown 文件：

人类可直接阅读和修改（vim/VS Code 打开就能改）
Git 版本控制
Agent 用 read_file/write_file 工具即可操作，无需新增工具
文件数量少（几个到十几个），不需要检索能力

共享读写：同一身份下的多个 Agent run 可以读写同一组记忆文件。哪个 Agent 该关注哪些文件、怎么更新，由 dream prompt 来定义。

三、统一元思考模型

三种元思考及其定位

	知识提取（已有）	知识评估（已有）	记忆反思（新增）
回答的问题	我学到了什么客观知识？	给我的知识有没有用？	这些经历对我的偏好/策略意味着什么？
输出目的地	KnowHub（全局共享）	knowledge_log.json（本地）	记忆文件（Agent 身份私有）
触发时机	压缩前、任务完成后	Goal 完成、压缩前、任务结束	Dream 时（见下文）
时效性要求	高（压缩会丢上下文）	高（压缩会丢上下文）	低（可以延迟处理）
实现机制	reflection 侧分支	knowledge_eval 侧分支	dream 操作（新增）

关键区分：知识提取和知识评估必须在上下文丢失前完成（压缩前/任务结束时），所以是侧分支、即时触发。记忆反思可以延迟——甚至应该延迟，因为用户可能还有反馈、Agent 可能继续执行。

为什么记忆反思不在 trace 结束时做

trace 结束只意味着 Agent 行动完一个轮次。后续可能发生：

用户在飞书里说"这个方向不对"
Agent 被唤醒在同一任务下继续执行
新的 trace 产生了推翻前一个 trace 结论的信息

如果 trace 一结束就做记忆反思，这些后续信息会被忽略。记忆反思的价值在于综合一段时间的经历，不是记录每次行动的即时感受。

但知识提取仍然在压缩/完成时做（采用"提取-审核-提交"两阶段）

知识提取必须在压缩/完成时做，因为压缩会删除历史，不在压缩前提取，知识就永久丢失。

但"立即 upload 到 KnowHub"这一步并不需要立即做。所谓"客观知识"也可能被后续推翻：

工具用法可能被后续 trace 发现是错的（例如某个参数其实有副作用）
调研结论可能被用户反馈推翻
一次 trace 的"成功经验"在更长窗口看可能是反模式

如果 reflection 直接 upload 到 KnowHub，错误知识会立刻污染全局检索，影响所有 Agent。

两阶段方案：

Step 1: extract（自动，压缩前/任务结束）
  Reflection 侧分支提取知识 → 写 cognition_log: type="extraction_pending"
  不调用 upload_knowledge（信息保全已完成）

Step 2: review（人工，CLI 里逐条决策）
  approve / edit / discard → 写 cognition_log: type="extraction_reviewed"

Step 3: commit（人工触发，批量上传）
  把 reviewed=approved 的批量 upload_knowledge
  写 cognition_log: type="extraction_committed"

review 和 commit 分开的理由：review 是逐条语义判断（要不要、内容对不对），commit 是机械批量动作。两者分离允许用户分批 review、最后一次 commit；也允许撤回 review 决策。

默认行为：所有 Agent（包括默认 Agent 和 memory-bearing Agent）reflect_auto_commit 默认关闭，pending 提取必须人工 review + commit 才会进 KnowHub。如需自动直通（保留旧行为），手动在 KnowledgeConfig 里打开 reflect_auto_commit=True。

这与"信息保全 vs 全局发布解耦"的原则一致 —— 压缩前必须做的是保全（写本地 cognition_log），发布到 KnowHub 可以延迟到有人确认时。

四、Dream：记忆反思的触发与流程

什么是 Dream

Dream 是 memory-bearing Agent 的记忆整理操作。它不是一个侧分支（不在某个 trace 的执行过程中插入），而是一个独立的顶层操作，回顾多个 trace 的执行历史，更新记忆文件。

触发方式

Agent 主动调用 dream 工具（"我觉得该整理一下了"）
外部调度触发（定时、或人工 CLI 触发）
框架可以在 run 启动时检测距上次 dream 的时间/trace 数量，建议 Agent dream

反思状态追踪

Trace 模型新增字段：
- reflected_at_sequence: Optional[int]    # 上次记忆反思时的最新 message sequence
                                           # None = 从未被记忆反思处理

反思摘要不存在 Trace 模型中，而是作为 reflection 事件写入 cognition_log.json（详见 knowhub/docs/cognition-log-plan.md）。

Agent run 产生新 message → reflected_at_sequence 自然落后于实际 sequence
记忆反思完成 → 更新 reflected_at_sequence 为当前最新 sequence
Dream 扫描 reflected_at_sequence < latest_sequence 的 trace

Dream 流程

Dream 触发
  │
  ├─ Step 1: 扫描该 Agent 身份下所有 trace
  │   找到 reflected_at_sequence < latest_sequence 的 trace
  │
  ├─ Step 2: Per-trace 记忆反思（逐个 trace）
  │   对每个需要反思的 trace：
  │   a. 加载 reflected_at_sequence 之后的消息（增量）
  │   b. 同时加载该 trace 的 cognition_log.json（查询、评估、提取事件）
  │   c. 用 reflect_prompt 生成反思摘要
  │   d. 摘要作为 reflection 事件写入 cognition_log.json
  │   e. 更新 reflected_at_sequence
  │
  ├─ Step 3: 跨 trace 整合
  │   a. 收集各 trace 的 reflection 事件（cognition_log 中 type="reflection"）
  │   b. 读取当前记忆文件
  │   c. 汇总 cognition_log 中的评估趋势（多次 harmful/unused 的 source 模式）
  │   d. 用 dream_prompt 指导 LLM 更新记忆文件
  │   e. 标记 reflection 事件为已消化
  │
  └─ 完成

Per-trace 反思的输入

反思 prompt 看到的不只是"发生了什么"，还包括知识评估结果：

## 执行过程
[该 trace 中 reflected_at_sequence 之后的消息]

## 知识使用情况（来自 cognition_log.json）
查询 1（sequence 42）："ControlNet 相关工具知识"
  → source knowledge-a1b2: helpful — "准确定位了问题"
  → source knowledge-c3d4: irrelevant — "与当前任务无关"
  → source knowledge-e5f6: harmful — "建议的方法已过时"

## 请反思
1. 这次执行中有什么值得记住的经验？
2. 哪些知识的评估结果反映了我的判断需要调整？
3. 用户的反馈（如果有）说明了什么？

这样，已有的 knowledge_eval 结果直接成为记忆反思的输入，不需要重复评估。

Dream 整合的输入

Dream prompt 看到的是：

## 最近的反思摘要
[各 trace 的 reflect_summary，每份几百 token]

## 知识评估趋势（汇总自各 trace 的 cognition_log）
- 最近 N 个 trace 中，被评为 harmful 的 source：[列表]
- 被评为 unused 的高频 source 类型：[统计]
- 被评为 helpful 的查询模式：[统计]

## 当前记忆文件
[各文件内容]

## 请更新记忆
[dream_prompt 的具体指导]

五、与现有实现的集成

不改动的部分

现有机制	保持不变	原因
reflection 侧分支	✅	知识提取到 KnowHub，时效性要求高，必须在压缩前做
knowledge_eval 侧分支	✅	知识评估，时效性要求高，必须在压缩前做
force_side_branch 队列	✅	侧分支排序机制，成熟可靠
cognition_log.json	✅	统一事件流存储（原 knowledge_log.json 扩展），dream 直接读取
三个评估触发点	✅	Goal 完成/压缩前/任务结束

需要修改的部分

1. 任务完成时的 reflection prompt 选择

当前 runner.py:1249 始终使用 get_reflect_prompt()。应区分场景：

# runner.py:1248-1249 修改
if branch_type == "reflection":
    if break_after_side_branch:  # 任务完成后的反思
        prompt = config.knowledge.get_completion_reflect_prompt()
    else:  # 压缩前的反思
        prompt = config.knowledge.get_reflect_prompt()

这是一个独立的 bug fix，不依赖 Memory 系统。

2. Trace 模型扩展

agent/trace/models.py:Trace 新增字段：

reflected_at_sequence: Optional[int] = None    # 上次记忆反思的 sequence
# 反思摘要存在 cognition_log.json 中（type="reflection" 事件），不在 Trace 模型中

3. RunConfig 扩展

agent/core/runner.py:RunConfig 新增可选字段：

memory: Optional[MemoryConfig] = None

4. KnowledgeConfig 扩展

agent/core/runner.py:KnowledgeConfig（或对应类）新增字段：

reflect_auto_commit: bool = False
# False（默认，所有 Agent）: reflection 只写 cognition_log: type="extraction_pending"
#                          人工通过 CLI review + commit 才进 KnowHub
# True（手动开启）         : reflection 直接 upload_knowledge，保留旧的"提取即上传"行为

5. Reflection 侧分支行为变更

当前 reflection 的 prompt 直接指导 LLM 调用 upload_knowledge。需要改为：

reflect_auto_commit=False 时：prompt 指导 LLM 调用新的 record_pending_extraction 工具（仅写 cognition_log）
reflect_auto_commit=True 时：保持当前行为

或者更简洁的实现：reflection 始终调用 record_pending_extraction，由侧分支结束后的 hook 根据 reflect_auto_commit 决定是否立即调用 commit_approved（视为全部 approved）。这避免了 prompt 分叉。

新增的部分

1. MemoryConfig

@dataclass
class MemoryConfig:
    """持久化记忆配置"""

    base_path: str = ""                          # 记忆文件目录
    files: Optional[Dict[str, str]] = None       # {路径: 用途说明}
    # key 是相对 base_path 的路径，支持嵌套（如 "core/identity.md"）或 glob
    # （如 "relationships/*.md"）。框架只负责按 key 读文件内容注入上下文，
    # 组织结构由配置者决定。
    dream_prompt: str = ""                       # Dream 整合 prompt（空用默认）
    reflect_prompt: str = ""                     # Per-trace 反思 prompt（空用默认）

2. Run 启动时记忆加载

Memory-bearing Agent 的 run 启动时，框架按 files 的 key 依次解析（直接路径或 glob 匹配），读取命中的文件内容以字符串形式注入上下文。Agent 可用 write_file 新增文件；只要新文件的路径匹配某条 key（直接路径或 glob），下次 run 启动时自动加载。

3. Dream 操作

以 dream 工具形式提供，Agent 可主动调用：

@tool
async def dream() -> ToolResult:
    """整理长期记忆。回顾最近的执行历史，更新记忆文件。"""
    # 1. 扫描需要反思的 trace
    # 2. 逐个 per-trace 反思
    # 3. 跨 trace 整合，更新记忆文件

也可以作为 AgentRunner 的方法暴露，供外部调度直接调用。

4. 提取审核 CLI 流程

为支持"提取-审核-提交"两阶段（见第三节），新增 agent/cli/extraction_review.py 模块。不是 Agent 工具（Agent 不应自我审核），是 CLI 内部模块 + 独立可执行脚本：

# agent/cli/extraction_review.py

async def list_pending(trace_id: str) -> list[PendingExtraction]:
    """读 cognition_log，返回 type=extraction_pending 且未 reviewed 的条目"""

async def review_one(
    trace_id: str,
    extraction_id: str,
    decision: Literal["approve", "edit", "discard"],
    edited_content: Optional[str] = None,
) -> None:
    """写 reviewed 事件到 cognition_log"""

async def commit_approved(trace_id: str) -> CommitReport:
    """批量上传 approved 条目到 KnowHub，写 committed 事件"""

可独立调用：

python -m agent.cli.extraction_review --trace XXX --list
python -m agent.cli.extraction_review --trace XXX --commit

集成到现有交互式 CLI（agent/cli/interactive.py:174 的菜单）扩展两项：

  1. 插入干预消息并继续
  2. 触发经验总结（reflect）         ← 现有
  ...
  8. 审核待提交知识（review）        ← 新增
  9. 提交已审核知识到 KnowHub        ← 新增

8 进入交互式 review 循环：

[1/3] tool 经验
─────────────────────
nanobanana 工具的 strength 参数 < 0.3 时会丢失原图轮廓...
─────────────────────
[a]pprove / [e]dit / [d]iscard / [s]kip / [q]uit:

9 显示 approved 列表 + 用户最终确认 → 调 commit_approved，输出 commit 报告（成功/失败条数、KnowHub 返回的 ID）。

实现注意：

现有 perform_reflection（interactive.py:269）走 HTTP API（/api/traces/{trace_id}/reflect）。新流程同样应该走 API 端点（如 POST /api/traces/{trace_id}/extractions/{id}/review、POST /api/traces/{trace_id}/extractions/commit），让未来 Web UI 能复用同一套审核流，而不是 CLI 直接读写 cognition_log 文件。
"edit" 分支允许用户直接修改 LLM 生成的 markdown 内容；初版只支持改正文文本，后续可扩展到改类型/metadata。

六、完整的元思考数据流

Agent 执行任务（Trace）
  │
  ├─ 知识查询（ask）→ cognition_log: type="query"（含整合回答 + source_ids）
  │
  ├─ Goal 完成 → 触发 knowledge_eval 侧分支 → cognition_log: type="evaluation"
  │
  ├─ 压缩触发 →
  │   队列: [reflection, knowledge_eval, compression]
  │   reflection: 提取客观知识 → cognition_log: type="extraction_pending"
  │                            （默认不直接 upload，等人工 review）
  │   knowledge_eval: 评估各 source → cognition_log: type="evaluation"
  │   compression: 压缩上下文
  │
  ├─ 任务完成 →
  │   knowledge_eval（如有 pending）→ cognition_log: type="evaluation"
  │   reflection → cognition_log: type="extraction_pending"
  │
  ├─ 人工审核（CLI 触发，可发生在任意时刻）→
  │   逐条 approve/edit/discard → cognition_log: type="extraction_reviewed"
  │   批量 commit → upload_knowledge → KnowHub
  │                + cognition_log: type="extraction_committed"
  │
  └─ Trace 状态更新（新消息使 reflected_at_sequence 落后）

         ···时间流逝，可能有多个 trace···

Dream 触发（Agent 主动调用 / 外部调度）
  │
  ├─ Per-trace 记忆反思
  │   输入: 未反思的消息 + cognition_log 中的 query/evaluation/extraction 事件
  │   输出: cognition_log: type="reflection"
  │
  ├─ 跨 trace 整合
  │   输入: 各 trace 的 reflection 事件 + evaluation 趋势 + 当前记忆文件
  │   输出: 更新后的记忆文件（taste.md, strategy.md, ...）
  │
  └─ 记忆文件被下次 run 加载 → 影响 Agent 行为 → 新的 Trace → ...

三种元思考的时间线

Trace 执行中:
  ──[Goal完成]──knowledge_eval──[压缩]──reflection→knowledge_eval→compression──

Trace 结束后:
  ──knowledge_eval──reflection(completion)──

之后某个时刻:
  ──dream──per-trace记忆反思──跨trace整合──更新记忆文件──

即时的元思考（knowledge_eval、reflection）保护信息不被压缩丢失。延迟的元思考（dream）在全局视角下更新个人记忆。两者互补。

七、记忆模型全景

Memory 和 Knowledge 是两条平行的线，而不是抽象层级。区分维度是"主观 vs 客观"和"私有 vs 共享"。Memory 不会"升级"成 Knowledge，反过来也不会。

                    ┌─────────────────────────────┐
                    │ Trace（任务状态 / 工作记忆）  │
                    │ Messages + Goals             │
                    │ + cognition_log              │
                    └──────────┬──────────────────┘
                               │
              dream 反思       │      reflection 提取（→ pending）
              （延迟、可选）    │      knowledge_eval 评估
                               │      （即时、必做）
                  ┌────────────┴───────────┐
                  ▼                        ▼
        ┌──────────────────┐     ┌──────────────────────┐
        │ Memory           │     │ Knowledge            │
        │ Agent 身份私有    │     │ KnowHub 全局共享      │
        ├──────────────────┤     ├──────────────────────┤
        │ 主观 / 偏好 / 策略 │     │ 客观 / 工具 / 调研    │
        │ Markdown 文件     │     │ DB + 向量索引         │
        │ 人类可直接编辑     │     │ 经 review 才入库      │
        │ 来源: dream       │     │ 来源: reflection      │
        └────────┬─────────┘     └──────────┬───────────┘
                 │                          │
                 └────注入下次 run──────────┘

两条线的交互（不是层级关系，是同源 + 互相参考）：

都源自同一个 Trace（cognition_log 是共同的事件流）
dream 在生成记忆摘要时可以参考 cognition_log 中的 evaluation 趋势（来自 Knowledge 这条线）
reflection 也可以参考 Memory 来判断"这条经验我已经记过了"
但二者的读者不同：Memory 只服务于同一身份的未来 run；Knowledge 服务于所有 Agent

八、两类 Agent

	默认 Agent	Memory-bearing Agent
知识提取（reflection）	✅ 配置 KnowledgeConfig	✅ 配置 KnowledgeConfig
知识评估（knowledge_eval）	✅ 自动	✅ 自动
个人记忆	❌	✅ 配置 MemoryConfig
Dream	❌	✅ 可调用 dream 工具
Run 启动加载记忆	❌	✅ 自动注入

Memory 是 opt-in 的增量能力。但知识提取的提交行为变了：默认 Agent 也不再自动 upload 到 KnowHub，必须通过 CLI 人工 review + commit；如需保留旧的"提取即上传"行为，手动设置 KnowledgeConfig.reflect_auto_commit=True。

九、开放与已决问题

[DECIDED] 已有落地结论；[OPEN] 尚未决定，等真实运行数据再定。

[DECIDED] 记忆注入方式 → system prompt 末尾追加。见 runner.py:_build_system_prompt 里调 format_memory_injection。代价：若记忆文件很大，每轮 LLM 调用都带 —— 暂时接受，等实际观察到膨胀再换方案。
[OPEN] 并发写冲突：多个 Agent run 同时写同一个记忆文件怎么办？文件锁？还是 dream 统一写、其他 run 只读？当前没做并发保护，假设 dream 是单一写入方。
[OPEN] 记忆膨胀：记忆文件越来越长怎么办？DEFAULT_DREAM_PROMPT 已写"在原有基础上演进不要重写"，但是否真能控制住要看实际使用。
[OPEN] Per-trace 反思的成本控制：很短的 trace 不值得反思。当前 per_trace_reflect 无下限阈值，所有 reflected_at_sequence < last_sequence 的 trace 都会反思。
[OPEN] Knowledge eval 结果回传 KnowHub：仍然只存本地 cognition_log。
[DECIDED] Dream 中评估趋势的呈现方式 → LLM 直接读 cognition_log 原始事件。见 dream.py:_build_reflect_input，把 query / evaluation / extraction_pending / extraction_committed 事件摘要化后一并塞给 LLM，不做预计算统计。
[DECIDED] Dream 操作的实现形式 → 两者都提供。Agent 主动调用走 dream 工具（agent/tools/builtin/memory.py，memory 组），外部调度走 AgentRunner.dream() 方法。
[OPEN] 未 review 的 pending 提取何时清理：目前没有 TTL，pending 无限期累积。等观察积压速度再定（例如 30 天未 review 自动 discard / 归档）。
[OPEN] review 的"edit"分支允许多深：初版只支持改 markdown 字段（task/content/score/tags）。改 type 或 metadata 目前需 discard 重写。
[OPEN] 批量 review 的辅助能力：当前逐条看。未做批量 approve / 相似条目去重 / LLM 预筛。
[OPEN] Dream 的 JSON 解析脆弱性：cross_trace_integrate 依赖 LLM 严格输出 {updates:[...]} JSON（见 dream.py:_parse_dream_output）。真实 LLM 可能偶尔加前言、用不同键名。首次线上运行需监控 parse 失败率，必要时加重试 + 更严格 prompt。

十、实现与入口

2026-04 落地清单，供看代码时快速定位。

10.1 数据层

改动	位置
Trace 新字段 `reflected_at_sequence`	`agent/trace/models.py:Trace`
cognition_log 事件 schema（含新增的 extraction_pending/reviewed/committed + reflection）	`agent/trace/store.py:append_cognition_event` docstring

10.2 提取-审核-提交两阶段

职责	位置
LLM 暂存用工具（core 组默认可见）	`agent/tools/builtin/knowledge.py:knowledge_save_pending`
反思 prompts（已改为调 `knowledge_save_pending`）	`agent/core/prompts/knowledge.py`
Auto-commit 开关（默认 False）	`KnowledgeConfig.reflect_auto_commit`
反思侧分支退出时的 auto-commit hook	`agent/core/runner.py` 反射分支退出分支内
核心逻辑（list_pending / review_one / commit_approved / auto_commit_branch）	`agent/trace/extraction_review.py`
独立 CLI 入口	`python -m agent.cli.extraction_review --trace <ID> [--list/--list-all/--review/--commit]`
交互式菜单入口	`agent/cli/interactive.py` 菜单项 8（review）/ 9（commit）
HTTP API 入口	`GET /api/traces/{tid}/extractions`、`POST .../extractions/{eid}/review`、`POST .../extractions/commit`（见 `agent/trace/run_api.py`）

三种入口共享同一个核心模块 agent/trace/extraction_review.py。

10.3 Memory + Dream

职责	位置
MemoryConfig 定义	`agent/core/memory.py:MemoryConfig`
记忆文件加载（支持 glob + 去重）	`agent/core/memory.py:load_memory_files`
记忆注入格式	`agent/core/memory.py:format_memory_injection`
注入到 system prompt	`agent/core/runner.py:_build_system_prompt`（memory 段落在 skills 段之后）
Dream per-trace 反思	`agent/core/dream.py:per_trace_reflect`
Dream 跨 trace 整合	`agent/core/dream.py:cross_trace_integrate`
Dream 顶层入口	`agent/core/dream.py:run_dream`
Agent 工具入口（memory 组）	`agent/tools/builtin/memory.py:dream`
外部调度入口	`AgentRunner.dream(memory_config, trace_filter=..., reflect_model=..., dream_model=...)`
默认 prompts	`dream.py:DEFAULT_REFLECT_PROMPT` / `DEFAULT_DREAM_PROMPT`（可通过 `MemoryConfig.reflect_prompt`/`dream_prompt` 覆盖）

10.4 启用方式

默认 Agent 不启用 memory，但提取审核仍然生效（pending 不自动上传 KnowHub）。

要让某个 example 直接上传（恢复旧行为）：

RunConfig(knowledge=KnowledgeConfig(reflect_auto_commit=True))

要让一个 Agent 变成 memory-bearing：

from agent.core.memory import MemoryConfig

RunConfig(
    memory=MemoryConfig(
        base_path="/path/to/agent_memory",
        files={
            "taste.md": "品味偏好",
            "strategy.md": "当前策略",
            "journals/*.md": "执行日记",
        },
    ),
    tool_groups=["core", "memory"],   # memory 组暴露 dream 工具
)

然后周期性（或 Agent 主动调用 dream 工具）触发：

await runner.dream(memory_config=rc.memory)

10.5 已知 rough edges

实施过程发现旧的 upload_knowledge 引用是悬空的（仓内无实现），未清理 examples/*/prompt 里的残留引用
Dream 两次 LLM 调用（reflect + integrate）默认模型写死 gpt-4o-mini / gpt-4o，未接入 RunConfig 的 utility_llm_call
trace_filter 没提供按 agent_type / owner 过滤的便捷函数，调用方传 lambda

memory.md 28 KB Historique Raw