角色記憶

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