跳到主要內容

【2026 最新】MIRIX-2.0 教學:Graph Memory 怎麼開?六步搞懂 AutoDream 與來源追溯

最後更新: ·
MIRIX-2.0 教學 教學首圖

你照著 Quick Start 裝好記憶系統,問它「誰把預算改了」,卻不知道答案來自原始對話、整理後的記憶,還是一張關係圖。這篇 MIRIX-2.0 教學,就從這個容易漏掉的設定問題開始:Graph Memory 預設關閉,AutoDream 又是在整理哪一層?

本文專為第一次接觸 Agent 記憶的新手寫。先用「卷宗、索引、整理員」理解分工,再帶已具備 Docker 基礎與模型服務權限的讀者核對設定、準備假對話、做三組驗收。完全不寫程式,也能先完成題目與證據清單;操作段則需要能編輯設定檔和閱讀 JSON。

以下依 2026 年 11 月 17 日查閱的官方 README、評測設定、API schema 與程式碼整理,固定到 commit 9077e4b。這是一份設定與驗收指南;文中的預期答案是人工訂定的考卷,並非 AlphaLab 跑出的模型成績。

先說結論:記憶可追溯=保存紀錄+角色索引+逐筆回查

  • 裝好 MIRIX,不等於開啟 Graph Memory。圖模式要另開開關並接上 Neo4j。
  • 一般非 procedural 模式下,圖模式預設走 graph_only。它整理圖中的實體錨點,保留平面記憶列;明確傳入 graph_only:false 則可走改寫記憶的分支。
  • dry_run 是這次呼叫的預覽。它不是整套系統的寫入鎖,也不是完整合併結果的預演。

想像辦公室裡有三件東西:對話紀錄像會議錄音,記憶列像按主題歸檔的卷宗,圖索引像「誰、在哪件事、扮演什麼角色」的目錄。目錄變整齊,不能直接推論錄音被修改;錄音仍在,也不能直接推論回答一定找得到。要把三層分開驗收。

一、MIRIX-2.0 教學先分三層:對話、記憶列、圖索引

MIRIX 是可以接到 Agent 的記憶系統。Agent 指會呼叫工具完成任務的 AI 助手;MIRIX 替它保存與取用跨對話資訊。官方列出 Core、Episodic、Semantic、Procedural、Resource、Knowledge Vault 六類記憶。本篇聚焦其中的 Episodic「發生過的事」與 Semantic「可描述的知識」,它們是圖記憶主要索引的對象。

Graph Memory 使用 provenance hypergraph,可理解成「附來源的多人關係卡」。普通關係常寫成「甲認識乙」;一張多元關係卡則能同時記下提案人、核准人、專案和時間,不必把同一件事拆成互不相干的短句。圖中的 Anchor 是實體錨點,像通訊錄中的同一個人;Frame 則是一次帶角色的事實。

依 官方圖寫入實作,V7Fact 保存 memory_ids,並用帶 role 的 V7_FACT_ARG 邊連到 V7Anchor。這條來源連結讓你回查記憶列,但還要確認列內內容是否忠於對話、時間是否適用。來源編號是查核入口,不是正確保證。

同樣地,保存完整對話與保留記憶列是不同承諾。正式驗收時,請分別備份送入的訊息、系統保存的對話,以及抽出的記憶內容。若想先補整體分工,可讀 Agent Harness 的模型與執行層;這次只處理 MIRIX 的接線。

MIRIX-2.0 教學:對話、PostgreSQL 記憶與 Neo4j 圖索引三層驗收
三層要各自保存證據;graph_only 整理圖索引,來源列仍需逐筆回查。AlphaLab 製圖。

二、MIRIX-2.0 教學六步:先確認跑了哪條路

第 1 步:「文件跟我裝的一樣嗎?」先留下版本收據

先固定程式,再閱讀設定。在全新教學目錄取得官方原始碼;以下只下載並切換版本,尚未啟動模型。已有正式安裝的人另開目錄,避免覆蓋現有資料。

git clone https://github.com/Mirix-AI/MIRIX.git mirix-memory-lab
cd mirix-memory-lab
git checkout 9077e4b229dd8f61c5703b431a97788c6b61acfb
git rev-parse HEAD

把輸出的完整 SHA 存進自己的實驗筆記。另記錄 Python client 版本與每個容器的 image digest。官方 Compose 的 API 使用 :latest,所以固定 Git SHA 仍不等於固定容器裡的程式;升級前保存 docker compose images 輸出,再核對映像來源版本。若無法對齊,先標成「依此原始碼設計的驗收」,不要宣稱重現此 commit。

第 2 步:「Neo4j 有起來就算開圖?」核對兩個開關

服務存在與功能啟用要一起檢查。官方 Compose 把 Neo4j 放在 graph profile,API 另有 MIRIX_ENABLE_GRAPH_MEMORY,預設值為 false。只啟動 Neo4j,並未替 API 打開圖模式。

在全新目錄複製 docker/env.example 成 .env,替 PostgreSQL、Redis、JWT 和 Neo4j 分別產生秘密值;可用 openssl rand -hex 32 一次產生一個。將結果填入對應欄位,不要貼進聊天或公開收據。Neo4j 密碼依官方要求至少八字元。

cp docker/env.example .env
# 編輯 .env,填妥必要密碼、JWT 秘密與你已有的模型服務設定
# 圖模式另外設定:
# MIRIX_ENABLE_GRAPH_MEMORY=true
# MIRIX_NEO4J_PASSWORD=你另行產生的秘密值
docker compose --profile graph up -d
docker compose ps

這組啟動指令來自 Graph Memory 官方說明。先確認電腦已具備 Docker Compose,並避開既有 MIRIX 容器與連接埠;這份檔案含固定 container_name,換 project name 不能單獨保證隔離。全新測試環境宜使用另一台測試主機或獨立虛擬機。

容器裡的 API 用 bolt://neo4j:7687 連 Neo4j;主機直接跑伺服器的文件預設是 bolt://localhost:7687。兩個 localhost 指向不同地方。官方評測文件還要求 Neo4j 5.23 以上,Compose 指定 5.26,錨點向量維度要和 embedding 模型一致;不要把所有 embedding 設定原封不動混用。

驗收時只輸出非秘密設定,例如 docker compose exec mirix_api printenv MIRIX_ENABLE_GRAPH_MEMORY MIRIX_NEO4J_URI,再查服務健康狀態和錯誤日誌。避免直接公開完整 docker compose config,因為它會展開環境變數。舊資料庫另有 migration 要求,本篇採新庫;不要對正式庫盲跑遷移。

第 3 步:「它記得的是誰?」準備三段假對話與答案本

先寫答案,再餵資料。建立三段合成對話,每段附自己的來源標籤。S1:「小林提出青鳥計畫,阿晴核准預算 300。」S2:「林同學就是前面的小林;他仍是提案人,阿晴是核准人。」S3:「阿晴更正青鳥預算為 350;小林只是轉達,沒有核准。」每段讓 assistant 回「已收到」,保持訊息結構一致。

題目至少三題:最新預算多少?誰有核准角色?最早版本說多少?人工答案分別是 350、阿晴、300。每題另訂可接受的來源組合,最新預算要能接回 S3;核准角色要同時避免把「轉達」誤判成「核准」。這些是人造教具,不是研究資料集或模型輸出。

透過 Dashboard 建立測試 API key,再依 官方 Python client Quick Start 初始化記憶代理;只使用你已有權限的模型與 embedding 服務。可先執行 pip install mirix-client,並用 python -m pip show mirix-client 留下版本。對照該版本的同步/非同步範例後,使用 add 傳入三段訊息,指定各組不同的 user_id 與 session_id。

入庫後確認處理完成再問。來源碼的 async_add=False 可要求同步處理,但 client 版本與介面仍須對齊;不要把排隊成功當成記憶已抽出。先用列舉記憶的結果,對照三段資料是否都進入,並保留服務回覆中的實際內部使用者 ID。

第 4 步:「預覽會告訴我合併哪些人嗎?」直接看請求邊界

對非 procedural 模式,把 graph_only 寫明。以下 REST 範例使用已初始化、只有假資料的測試使用者;先在 shell 設妥 MIRIX_API_KEY 與其實際 MIRIX_TEST_USER_ID。使用 X-API-Key 是目前 client 的驗證方式。

curl --fail-with-body -sS \
  -H "X-API-Key: $MIRIX_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"mode":"experience","graph_only":true,"dry_run":true}' \
  "http://localhost:8531/memory/auto_dream?user_id=$MIRIX_TEST_USER_ID"

依 AutoDream 的實際分支,圖專用 dry run 會在建立 dream agent 與圖整理之前返回,processed 是空物件;它沒有先跑候選配對,所以不要把這份回覆稱為「已看到全部合併清單」。相對地,非圖分支的 dry run 會取資料並回報數量,兩者輸出不同。

這個邊界限於 AutoDream 管理器的該次流程。它不會暫停背景入庫,也不會撤銷之前的寫入;Python client 便利函式還可能先執行建立或取得使用者的前置動作。若想核對唯讀性,固定已存在的測試身分,停止其他寫入,再比較資料快照,別只看 dry_run:true 四個字。

第 5 步:「做夢到底動了什麼?」分開三組,再查來源

三組使用相同輸入,但各有獨立資料庫或可還原快照。A 組關閉圖模式且不觸發 AutoDream;B 組開圖模式但不做夢;C 組從 B 的同一份入庫完成快照複製,再做圖專用 AutoDream。評測腳本的 MIRIX_DREAM_EVERY_N_CHUNKS 是評測端排程設定,不能當成全站通用開關。

C 組先保存對話與 PostgreSQL 記憶列,再在小型測試庫送出 {"mode":"experience","graph_only":true,"dry_run":false,"final_full_graph":true}。它會真的整理圖並可能呼叫模型;final_full_graph 會納入尚未處理的安全類型語意錨點,但仍是有上限的 frontier,不是「每個節點都已檢查」。

這個額外欄位很重要:目前 請求 schema 與 圖整理實作 會區分增量來源與最後一輪。未提供增量 ID,且 final_full_graph 維持預設 false 時,不能只因 HTTP 成功就認定做過有效合併。看回傳的 graph_stats.bounded_frontier、候選數、提交數與 anchors_merged,零合併也可能是正確結果。

用 Neo4j Browser 的唯讀 Cypher 檢查一小批關係卡。將 $uid 設為實際內部使用者 ID;以下欄位依固定版本的圖寫入程式,不需要猜一個不存在的來源欄位。

MATCH (f:V7Fact {user_id: $uid})-[r:V7_FACT_ARG]->(a:V7Anchor)
RETURN f.id, f.memory_ids, r.role, a.name
ORDER BY f.id
LIMIT 30

沿 memory_ids 回到 PostgreSQL 記憶列,再對照 S1–S3。三組各問相同題目,固定回答模型、提示與檢索上限;逐題記答案、引用記憶 ID、能否回查,以及把提案人當核准人的角色錯誤。圖看起來更小,和答案變好,是兩張不同收據。

第 6 步:「內容沒變嗎?」用欄位指紋驗收,再算完整成本

先比內容,再比數量。將做夢前後同一批記憶的 ID、內容與 embedding 另存 JSON,依 ID 排序並固定 JSON 序列化方式,對每筆計算 SHA-256。SHA-256 是內容指紋;同一份匯出規則下雜湊不同,就回查差異。不要只對「原文摘要」取雜湊,摘要相同仍可能漏掉一個關鍵詞的修改。

另存圖快照或匯出,以免只備份 PostgreSQL 卻無法回復 Neo4j。排除時間戳等允許改變的欄位要事前約定;這項檢查只證明被比較欄位的狀態,不能自動證明所有儲存表都未改動。非 dry run 的任務紀錄或代理狀態,也應與「平面記憶列沒改」分開看。

完整成本至少分成入庫抽取、embedding、圖整理、檢索與回答五段;留下服務回覆的用量、模型 ID、耗時與錯誤。資料庫放在本機,模型端點仍可能在雲端。先畫出每段內容送到哪個服務,再決定能否輸入真實資料;第一輪只用本篇三段假對話。

三、AutoDream 會改原始記憶嗎?先問是哪一條分支

答案要附條件。對本篇的非 procedural 圖專用路徑,程式設計是保留平面 PostgreSQL 記憶 ID、內容與向量,對圖錨點做合併與邊重接。明確使用 graph_only:false,則會把選定類型的記憶交給 LLM 記憶工具整理;這條路徑可能改寫或刪除記憶列。因此「AutoDream 永遠不改記憶」太寬。

還有一個例外要單獨記:mode:"procedural" 在主入口先分流到技能學習,不讀 graph_only。技能學習處理任務經驗與技能演化,和本篇人物、預算的事實記憶驗收不同。想保護來源,不能靠把這個旗標套在所有 mode 上。

官方測試檔可提供分支意圖與 mock 條件的證據;它們不能替你的資料庫證明已保存所有來源。要採用這套設計,先完成 B→C 的內容指紋與逐題回查,再擴大資料。泛用的進步/退步分母,可接著讀 WikiTrace 四組記憶評估;本篇不重寫那套考卷。

四、怎麼讀論文成績:先核對設定,不把關閉當缺陷

官方 README 說明,LoCoMo 使用圖記憶加 AutoDream,LongMemEval-S 與文件問答使用圖記憶本身。這表示不同題目採不同配置;文件問答沒有開 AutoDream,既不能證明它必定有幫助,也不能證明它必定有害。你的三題只驗設定與回查,不能換成整份 benchmark 的準確率。

2026 年 11 月 16 日開出的 issue #156 詢問評分分母與 judge 計分;截至本次查閱仍為 open。這是一項待釐清問題,不足以判定論文數據錯誤。本篇不拿宣傳分數替任何設定保證效果,也不把不同版本、題目與評分方式排成同一個名次。

常見問題:八個先講答案的判斷

1. Quick Start 成功,就開了 Graph Memory 嗎?

不一定。固定版本的設定預設 false;核對 API 的實際環境與 Neo4j 連線,再查圖中是否有本次使用者的來源。

2. 開啟 graph profile,就會自動替我做夢嗎?

不能這樣推論。Profile 啟動服務,功能開關決定記憶路徑,觸發 AutoDream 則是另外的呼叫或排程。

3. graph_only 就是完全不寫 PostgreSQL 嗎?

要縮小範圍。它保護的是本篇非 procedural 流程的平面記憶列;任務紀錄與代理狀態要另外核對。

4. dry_run 會列出所有即將合併的錨點嗎?

目前圖專用分支不會。它在圖整理前返回;完整候選與合併計畫不是這份回覆承諾的內容。

5. anchors_merged 等於零,是否代表壞了?

不一定。可能沒有合適候選、模型拒絕合併,或本輪沒有增量來源;先看 frontier 和候選統計。

6. 原始對話還在,答案就一定可追溯嗎?

不一定。還要讓回答引用接回記憶 ID,再讀到適用的來源與時間;每段交接都可能失敗。

7. 本機 Docker 代表資料完全離線嗎?

不代表。儲存與推論是兩段資料流;核對實際模型、embedding 端點和請求內容。

8. 完全新手今天先做到哪裡?

先寫好 S1–S3 與三題答案本,理解三層與兩個旗標。有現成測試環境後,再做一輪 B→C;保留沒有結果的空白欄位,比預填成功更有用。

給新手的三個重點

  • 先問改哪層:對話、記憶列、圖索引分開命名與備份。
  • 先看實際分支:圖開關、graph_only、dry_run、mode 和增量範圍一起記。
  • 先逐題回查:角色、更正時間與來源內容通過,才談擴大和省成本。

下一步:先找回「誰核准了 350」的那一筆

今天先把三段假對話與答案本存好。若已有環境,確認圖開關後完成一輪預覽,再從獨立快照做圖整理,沿來源 ID 回到阿晴的更正。記憶可追溯=保存紀錄+角色索引+逐筆回查:能指出哪個人、哪個時間、哪一列,才算這次練到的能力。下一個練習可從 AI 教學專區 選題,或到 AlphaLab 課程 安排完整的 Agent 工作流學習。

ALPHALAB 社群

有問題?來 Telegram 聊

和 Terry、編輯、其他網友一起討論這篇文章。提問、分享觀點,回覆更即時。

加入 Telegram 討論

📩 訂閱 AlphaLab 電子報

週日 Weekly 週報+週二、週四 Alpha Signal,每週最多三封。

我們不會 spam,隨時可退訂。已訂閱?管理訂閱偏好(會寄登入連結到你的信箱)

主題篩選與退訂說明

寄送日期以台灣時間為準。主題偏好會篩選每期精選,並非每篇新文章的即時通知;當期符合主題的文章不足時會略過寄送。

未勾選任何主題會收到所有主題的精選,並不會停止寄信。

取消勾選 Alpha Signal 可停止週二、週四短報,仍保留週日週報。若要停止所有電子報,請使用信件底部的「取消訂閱」。