Grok Build · Memory Engineering

Dream 的真實機制

Dream 會把近期 session 日誌與現有 MEMORY.md 合併成長期記憶。它由會話結束、可選週期檢查或手動命令進入，並受門控與最佳努力鎖共同約束。

課程目標

讀懂 Dream 從觸發到重建索引的完整鏈路，能解釋 DreamGate、冪等要求、鎖競爭和寫入失敗回滾各自解決什麼問題。

TEACHING DIAGRAM

一次 Dream 的狀態機

下圖是教學化圖示。節點名稱來自源碼，佈局與文字説明經過課程化整理。

入口與門控

1. 配置門

MemoryDreamConfig.enabled 預設為 true。子 Agent 會話直接跳過 Dream。

2. 時間門

min_hours 預設為 4。鎖檔案 mtime 記錄上次成功 consolidation 的時間。

3. 會話門

min_sessions 預設為 3。統計上次 consolidation 後修改的 session Markdown，並排除當前會話。

觸發事實：預設 check_interval_secs = None，代表不啓用週期檢查。源碼明確支持 session end 和 /dream；只有配置檢查間隔後，session actor 才會按週期檢查門控。因此不能概括為「所有空閒時必然自動運行」。

crates/codegen/xai-grok-memory/src/dream.rs crates/codegen/xai-grok-memory/src/dream_lock.rs crates/codegen/xai-grok-memory/src/storage.rs crates/codegen/xai-grok-memory/src/index.rs crates/codegen/xai-grok-config-types/src/memory.rs crates/codegen/xai-grok-shell/src/session/acp_session_impl/memory_dream.rs check_dream_gates maybe_run_dream

鎖、冪等與失敗恢復

DreamLock 是最佳努力協調

.dream-lock 保存 PID，並用 mtime 兼作上次成功時間。活進程持有且未過期時返回 Ok(None)。死進程或超時鎖可被回收。

源碼註釋明確説明它並非嚴格互斥。寫後復讀能降低競爭概率，仍可能有兩個進程都認為自己獲勝，所以 Dream 必須容忍重複 consolidation。

成功邊界決定清理邊界

模型返回空、NO_REPLY 或無 Markdown 標題時，不寫入也不刪 session。
寫 MEMORY.md 失敗時調用 rollback(prior) 恢復舊鎖狀態。
寫入成功後才清理已讀取的 session；5 分鐘內仍活躍的檔案會跳過。
搜索索引只移除實際刪掉的路徑，再為新 MEMORY.md 重建索引與 embedding。

真實源碼快照

crates/codegen/xai-grok-memory/src/dream.rsREAL SOURCE · abridged

pub fn check_dream_gates(
    config: &MemoryDreamConfig,
    lock: &DreamLock,
    sessions_dir: &Path,
    current_session_sid8: Option<&str>,
) -> DreamGate {
    if !config.enabled { return DreamGate::Disabled; }
    // Time gate, then session gate
    ...
    DreamGate::Open { sessions }
}

快照説明：程式碼保留真實函式簽名與返回類型，中間實現以省略號壓縮。頁面中的狀態機 SVG 屬於教學化表達，不對應倉庫生成的架構圖。

課堂練習：定位失敗後的系統狀態

情境：Dream 已完成模型調用，但寫入 MEMORY.md 失敗。請回答：鎖檔案應該恢復返去咩狀態？邊啲 session 檔案可以刪？索引要唔要更新？再從 execute_dream 的分支給出依據。

Takeaway：Dream 的可靠性來自成功邊界設計。門控減少無效調用，最佳努力鎖降低併發，冪等承擔少量重複風險，回滾與延遲清理保證失敗後仍能再次嘗試。