角色记忆

Role Memory 为已声明的分析角色保存成功模式和失败模式。在统一 Trading Memory 架构中，只有案例精确关联到已消费的人工交易 preview，且对应执行已有结算结果后，才具备学习资格。

它不是通用预测日志，也不是账户历史镜像。Autopilot、Strategy Studio、XStrategy、workflow 执行以及来源未知的 perps 都不能生成可召回的 role case。

用户侧审计页面参见 Trading Memory。

准入边界

Role case 只有同时满足以下条件才具备评分资格：

1. role ID 由 reasoning skill 声明，并存在于 role registry。
2. 人工 preview 恰好被消费一次。
3. 案例与执行的 decision ID、资产、方向、账户和市场完全一致。
4. 执行来源是 manual_agent 或经过验证的 manual_external。
5. 结果已结算，并有足够的评价数据。

自动标记的优先级高于表面的人工证据。未知 role 或交易来源会被隔离，而不是 fallback 到通用角色。该 fail-closed 边界避免把自动策略行为重新解释为人工偏好或分析角色经验。

数据模型

role_cases 保存角色、关联的决策和 evaluation run、情境、决策文本、结果状态、反思、provenance、评分资格及时间戳。FTS 与可选向量索引用于检索，但关系型的决策/评价关联才是事实来源。

统一主链如下：

trading_decisions
  → trade_executions / trade_fills
  → position_lifecycles
  → evaluation_runs / evaluation_components
  → methodology_observations and role_cases

案例不能独立声称某笔交易发生过；这一事实必须继承自已关联的执行链。

角色声明

分析型 skill 声明稳定 role ID 和 reflection policy。Role registry 在启动时验证它们；重复或未知 ID 不会静默映射到通用 role。角色定义控制失败模式、成熟窗口、outcome probe 与反思提示词。

区分 skill 和 role 是有意设计：skill 是能力集合，role 则命名其中一种决策情境。因此 valuation、momentum 和 cycle analysis 的经验不会混在一起。

反思

符合条件的案例成熟后，reflector 首先分类结果：

• logic_error：推理与当时可用证据冲突，可训练。
• missing_data：本应获取必要证据，可训练。
• exogenous：结果依赖无法预见的事件；保留审计，但不形成指导。
• variance：结果与噪声无法区分；不生成指导。

只有可训练类别会得到简短、角色特定的 lesson。反思按 role 串行执行以避免重复 LLM 调用，受预算限制，且不能调用资金操作工具。

运行模式

ROLE_MEMORY_MODE 在启动时读取，并在该进程内固定：

非法值会记录警告并回退到 shadow。Active 不会向 execution tool 注入案例文本。SOUL、静态安全规则、权限门和用户显式约束始终高于召回案例。

Recall 和手动 reflect 工具只在 active 模式注册；shadow 仅开放生成候选案例所需的 store 路径。也就是说，shadow 不是“模型可以忽略案例”，而是模型完全无法从正式决策提示词中检索或接收案例。

检索约束

Active 检索按精确 role 过滤，并在提供时按 symbol 和 scenario 过滤。只有已反思、未隔离、具备评分资格的人工案例可被召回。排序可以使用 FTS 或 embedding，但语义相似度永远不会放宽来源、角色或决策关联约束。

与评价体系的关系

Role Memory 消费版本化 evaluation run。同一决策可由多个 benchmark profile 评价，重放会追加新 run。只有明确 promoted 的 primary run 才能更新下游统计。因子详情和缺失数据质量保留在 evaluation_components；Role Memory 不会把它们压缩成一种写死的评分。

迁移

旧 role_memory 行迁移到 role_cases。已知角色保留原文与 provenance，未知角色进入隔离区。旧评分仅供审计，不能更新新方法论或角色统计。迁移与 Trading Memory 其他部分共用带校验和的备份和守恒报告。

运营检查

• 正式注入前，使用 ROLE_MEMORY_MODE=shadow 验证生成与评价行为。
• 修改模式后必须重启，不支持热切换。
• 通过 doctor/audit 输出检查长期 pending、failed 或隔离案例。
• 案例缺失时，先验证人工 preview 已消费并精确关联执行，再排查反思调度。
• 不要通过手工修改评分资格来“修复”自动或未知交易。

相关实现：

• apps/agent/src/memory/role-memory-mode.ts
• apps/agent/src/memory/role-reflector.ts
• apps/agent/src/memory/prompt-injection.ts
• apps/agent/src/tools/role-memory.ts
• apps/agent/src/memory/trading-memory-migration.ts