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 的可靠性來自成功邊界設計。門控減少無效呼叫，最佳努力鎖降低併發，冪等承擔少量重複風險，回滾與延遲清理保證失敗後仍能再次嘗試。