你請 Claude Code 記住「這個函式最多重試三次」，隔天程式改成五次，它卻繼續照舊說。這篇 Graphicle 教學 要教你把這種不安變成能驗收的問題：哪一筆記憶依賴哪段程式？程式改了，舊說法是否被擋下？
專為第一次接觸 Agent 記憶工具的讀者寫。你會先看懂原理，再在可丟棄的小型 Repo（程式資料夾）設計三組變更，最後把 Graphicle 與只用 rg 搜尋的流程放到同一份考卷。需要能開終端機，並已有 Git、Python 3；整合階段另需 Graphicle 與 Claude Code。
查核截至 2026 年 10 月 15 日，文件與程式碼固定在 6850164，官方發布頁列出 0.1.0。本篇是來源導向的上手與驗收方法；此次環境未安裝 Graphicle，因此不提供 AlphaLab 的記憶失效、修補成功率或 token 實測成績。
先說結論：Graphicle 教學先記住「便條＋定位釘」
可信的專案記憶＝已審核的說法＋目前仍有效的程式依據。 像在維修手冊貼便條，還要把便條釘到對應零件；零件換了，便條先撤下重看。Graphicle 的重點之一，就是把記憶連到函式等程式符號，再用版本判斷是否仍適用。
- 先驗「記憶是不是過期」，再驗「Agent 是否修對」。這是兩張成績單。
- 同檔其他函式改動與目標函式改動，要分開做；全檔綁定與符號綁定也分開記。
- 保留 rg 基線、全新對話、相同模型與測試，不把記憶問答分數當成開發效率。
- 從假資料 Repo 開始；先記設定差異，最後實際驗收
disconnect。
原理：Graphicle 把五個零件接在一起
Graphicle 是把程式關係圖與專案記憶放在一起的工具。Code Graph（程式關係圖）像零件目錄：知道檔案、函式、呼叫和匯入之間的關係。記憶像維修註記：保存決策與做法。要先補上整體分工，可讀 AI Agent Harness 白話原理。
- ①「原稿」：來源。 程式、文件與選擇擷取的對話，是可回查的材料。
- ②「門牌」：符號。 函式、類別與方法有識別資料，不只是一串行號。
- ③「核准便條」：reviewed memory。 Agent 提出的草稿先等審核，再進入正常記憶檢索。
- ④「版本貼紙」：revision。 綁定的符號改變時，舊記憶可被判為過期並暫不供應。
- ⑤「取件窗口」：MCP。 這是 Agent 呼叫外部工具的協定，讓它取得來源片段與記憶，而非每次把整本歷史塞回對話。
這裡最容易誤會的是「有效」。官方精確規則 寫的是：引文落在單一符號內時，記下 stable_id 與 revision；判定範圍由該定義起點到下一個定義或檔案結尾。這是程式片段的依賴檢查，不能直接等同理解了所有商業語意。
例如函式原文沒變，但它讀取的外部設定改了，你仍應另外測試決策是否正確。反過來，單純在函式上方加幾行，行號雖變，原符號內容可能仍相同。行號是找到證據的入口，版本與依賴才是判斷有效性的條件。
Graphicle 教學上手：六步做出可判分的驗收
①「固定考卷」：先建只有假資料的小 Repo
怕工具碰到真專案？先開一個全新資料夾。以下兩個函式分別代表重試上限與無關標籤；所有變更都只在這份練習中做。
mkdir graphicle-memory-lab
cd graphicle-memory-lab
git init
python3 - <<'PY'
from pathlib import Path
Path("retry.py").write_text(
'def retry_limit(attempt):\n return min(attempt, 3)\n\ndef label():\n return "lab"\n'
)
PY
git add retry.py
git -c user.name="Memory Lab" -c user.email="lab@example.invalid" commit -m "baseline fixture"
git rev-parse HEAD
rg -n "retry_limit|return|label" retry.py先讀輸出，確認兩個定義與行號，再記下 Git SHA（這一版程式的指紋）。rg -n 是用關鍵字找文字並顯示行號的基線；它的結果要由你或 Agent 讀懂。這份小考不是在測大型專案搜尋覆蓋率。
②「先看再接線」：code-only 索引與設定盤點
首次安裝依 官方安裝文件，macOS／Linux 的 Homebrew 路線是 brew install graphicle-ai/tap/graphicle。記下 graphicle --version、claude --version，並從 Claude Code 的 /model 記錄實際模型；對照期間固定它。
graphicle graph extract . --code-only
graphicle graph affected "retry_limit()"
git status --short
graphicle setup --clients claude-code --no-capture --no-instructions --no-hooks
graphicle status
graphicle doctor第一行先走不呼叫模型的程式索引路線。獨立 graph extract 與後面的專案設定是不同工作：前者看圖，後者建立專案與 Agent 整合。上列設定限定 Claude Code、略過對話擷取、指令文件與 Git hooks；--no-hooks 指 Git hooks，Claude Code 的 graph guard 仍要另外檢查。
依 Graphicle 用戶端文件，重點檔案是專案 .mcp.json 與 .claude/settings.local.json。完整 setup 預設還可能處理 AGENTS.md、既有 CLAUDE.md、Git hooks 與偵測到的其他用戶端。記下摘要逐項核對，也查看被 Git 忽略的本機設定；只看 git diff 不完整。
Graphicle 會先留 .graphicle-bak 備份。保留安裝前副本與 setup 摘要，接著重啟 Claude Code，以 /mcp 確認連線。Anthropic 的 MCP 文件 與 Hooks 文件 說明了專案伺服器及工具事件；本機 shell hook 是會執行的程式，先讀它的命令再啟用。
③「釘到零件」：建立一則已審核記憶
在這份練習的 Claude Code 中貼上以下任務。這是給 Agent 的操作要求；實際參數由已連線工具的 schema 決定，不把自然語言當成 CLI。
請只針對目前 graphicle-memory-lab：
1. 用 Graphicle 查 retry.py 的 retry_limit，列出路徑、行號、stable_id 與 revision。
2. 讀回原始來源，逐字核對 return min(attempt, 3)。
3. 用 propose_memory 提出「這版 retry_limit 把 attempt 上限限制為 3」的草稿，
引用該行並綁到 retry_limit；不要額外加入整個 retry.py 的 files 依賴。
4. 顯示工具原始結果與草稿 ID，停在等待審核。再執行 graphicle open，在 Memory 查看草稿與來源，確認說法只是描述目前實作，才核准。用 project_memory 查看審核與 freshness（新鮮度），以 recall_project 詢問上限。兩者都保留原始回傳，不能只抄 Agent 的摘要。工具行為見 官方 MCP 工具清單。
如果引文跨兩個符號、位於模組標頭，或額外指定整份檔案，官方規則會保留全檔依賴。這類記憶不能拿來驗證「改其他函式仍有效」；先查記憶中的連結與理由，確認綁定正確再繼續。
④「一次只改一處」：三組變更驗記憶失效
每組都從第一步的原始內容與同一份已審核記憶開始；勿把三種變更疊在一起。修改前先確認工作資料夾是練習 Repo，原檔內容可用第一步 Python 片段重建。
- A／目標函式改了： 把
return min(attempt, 3)改成return min(attempt, 5)。同步及圖更新完成後，檢查舊記憶是否為 stale，理由是否含symbol_changed:。 - B／無關函式改了： 還原原始內容，只把
return "lab"改成return "lab-v2"。在此單一符號綁定設計下，預期目標記憶仍 current；若失效，回查是否誤綁整檔。 - C／來源消失： 還原後，把練習檔移到 Repo 外，例如
mv retry.py ../retry.py.graphicle-lab-backup；先確認外面沒有同名備份。同步後應把舊記憶擋下，保存實際 missing／source unavailable 類理由；不要預填成功。
每組修改後執行 graphicle sync、graphicle status，再要求 Agent 依序呼叫 project_memory 與 recall_project，列出原始狀態、理由、來源及版本。若圖還在排隊，projection_pending 表示暫時扣住記憶；等圖更新再判分，不能把等待直接算作錯誤失效。
以上是依文件與 官方符號記憶測試 設計的預期，不是本篇執行結果。「沒搜到」也不等於「已失效」：可能只是排名沒選中。要用記憶本身的狀態與回傳來源交叉確認。完成 C 後，把備份移回原位再同步。
⑤「換同一份考卷」：與只用 rg 的修補流程對照
機制過關後，再問工具是否幫到開發。準備兩份相同程式狀態：基線組不接 Graphicle，讓 Claude Code 使用 rg 與讀檔；工具組接 Graphicle，保留上述已審核記憶。兩組使用全新對話，固定模型、權限、任務文字、時間與 token 預算。不要把剛才測試的答案貼進新對話。
- 任務一／改上限： 從上限三次版本改成五次，驗收
retry_limit(9) == 5與retry_limit(2) == 2。 - 任務二／不擴大修改： 只將
label()的字串改成lab-v2，驗收retry_limit(9) == 3，並檢查 diff 只包含標籤變更。 - 任務三／面對已改來源： 先在兩組都把上限改成五，再要求 Agent 寫一個超出上限輸入的測試。預先指定通過條件是輸入九得到五，工具組另查是否仍把「三」當現況。
把預先寫好的驗收條件留在評分端，勿讓其中一組多看答案。每次記錄是否通過原有與新增測試、是否引用過期說法、牆鐘時間、輸入／輸出 tokens、工具呼叫與重試。用量取自實際用戶端紀錄；拿不到填 N/A，不用字數估造。先交替跑組別，再增加重複次數，避免暖快取或題目順序決定輸贏。
總成本還要另列首次索引、日後同步與人工審核時間；一次性設定成本和每次任務成本分開。小題全部過關，只表示這份考卷過關。要採用到真專案，另加跨檔呼叫、外部設定改動與真實回歸測試。關於關係圖檢索的另一種驗收，可對照 GitNexus 的 Blast Radius 測例。
⑥「收線驗收」：disconnect 後確認恢復
graphicle disconnect claude-code
graphicle status
graphicle doctor
git status --short上列撤除這個用戶端；如果要撤除本練習專案由 setup 加入的全部整合，執行 graphicle disconnect。依官方設計，它按名稱與標記移除自己的設定；檔案與備份完全相同時才放回備份。
最後重啟 Claude Code，核對 /mcp，比對原本的 MCP 條目與 hooks 是否仍在，並確認不再出現 Graphicle 的 graph guard。disconnect 的驗收範圍是整合設定；本機保存的專案資料要另行處理。 不要為了測試復原而整份覆蓋自己的其他設定。
怎麼決定要不要用？先看瓶頸在哪裡
如果 rg 加讀檔已能穩定修對小專案，先保留簡單流程；如果常跨對話重講決策，又難確認舊便條是否仍有依據，Graphicle 的符號綁定值得放進小考。需要自己維護決策狀態的人，也可先讀 Decision Ledger 的決策保存方法；需要明確規則推導與撤回的人，可接著看 Lemmalog 的依賴與撤回教學。
官方 記憶評估說明 註明使用開發資料集、代理評估模型與未隨發布檔提供的 renderer，發布版無法原樣執行那套配置。這些是作者記憶問答評估的邊界；本文不引用其分數作為修補成功率或節省 tokens 的證明。
隱私也要分開看：--code-only 是程式解析路線；完整 graph extract 會走文件／圖片的模型處理，Claude Code 自己使用的模型又是另一層。就算 Graphicle 在本機保存資料，Agent 取得片段後仍可能交給它所連接的模型。從假資料起步，能讓資料流與權限較容易查清楚。
FAQ：Graphicle 新手最容易混淆的八件事
1. 程式改了，所有記憶都會失效嗎？
不一定。單一符號綁定主要看該符號版本；全檔依賴則看整檔。先看記憶實際連到哪裡。
2. 同一檔案其他函式改了，可以當成無影響嗎？
先通過 B 組。本文這份簡單測例預期仍有效，但跨符號引文、額外檔案依賴與同步排隊都會改變判讀。
3. stale 表示記憶的文字一定錯了嗎？
不是。它表示依據變動，需要重新審視；內容可能仍對，也可能已不適用。
4. 引用有行號，就表示答案正確嗎？
還不夠。行號幫你找到原文，還要核對目前版本、適用條件與推論是否成立。
5. code-only 一定要另付模型 API 費嗎？
該索引路線不呼叫模型。Agent 回答與你另行啟用的模型功能，分別按實際用量計算。
6. 核准過一次，未來就能永遠使用嗎？
要持續檢查。審核是當下接受這則說法，程式變更後仍需重新驗證依賴與結論。
7. 官方跑分高，就能略過 rg 對照嗎？
不能由此推出。記憶問答與完成修補的評分單位不同，應用同一組開發任務驗收。
8. 完全不會寫程式，今天能做哪一步？
先做第一步並讀懂兩個函式的差別，再用紙筆寫 A、B、C 的預期。能分清應失效與應保留，才往設定與整合走。
給新手的三個重點
- 記憶不是越多越好；每則重要說法都要能回到依據。
- 把同步完成、狀態正確與任務修對拆開記，失敗才知道卡在哪一層。
- 先保留 rg 基線與撤除出口，測完一輪再決定是否擴大。
接著閱讀
左右滑動查看更多推薦
下一步：先讓一張舊便條學會暫停
回到全文的定位釘：可信的專案記憶＝已審核的說法＋目前仍有效的程式依據。 今天先建立這份小 Repo，留下一筆指向 retry_limit 的記憶；先做 A 組，再做 B 組，拿原始工具回傳確認一個該停、一個該留。完成這一輪，再用同題修補結果決定工具是否值得加入工作流。想系統化練習 Agent、工具整合與驗收，可從 AlphaLab 課程 選擇下一個實作，也可回 AI 專區 延伸學習。