概述
codebase-memory v0.11.0（2026-09-15）是一個大版本：自 v0.10.8 起合併 171 個 PR（其中 76 個來自維護者以外的貢獻者）。它升上 minor 版號的原因有兩個：索引格式遷移與工具輸出契約改變。
官方給這版的存在理由很直白：安裝、解除安裝與 daemon 啟動的可靠性，以及記憶體——若 cbm 曾拒絕安裝、拒絕乾淨解除安裝、啟動死亡不告訴你原因，或在大 repo 上爆記憶體，這版就是為此而生。
檔案身分：副檔名成為身分的一部分
這是本次格式遷移的核心（#1104，@LA-10）。
問題
File 節點的 qualified name 過去不含副檔名。同一個目錄下的 auth.py 與 auth.ts 會碰撞成同一個節點名稱——兩個檔案的符號被靜默合併或丟失。
解法與代價
File 節點的 qualified name 現在保留副檔名。這移動了 on-disk 索引格式的邊界，所以：
- cbm 以
PRAGMA user_version在資料庫裡蓋格式戳記 - 舊格式（v0.10.8 及更早）的索引會走一次完整 reindex
- ADR 與索引 metadata 在重建過程中保留
你會看到什麼
升級後第一次 index_repository（或第一次 watcher / daemon 觸發的索引）會花像冷索引一樣久的時間，而不是平常增量的幾秒鐘。大 monorepo 會很有感。**這是預期行為，不是錯誤，沒有東西遺失。**那一次之後，戳記就是最新的，增量索引恢復正常。
第一次可能還會出現一行 orphan_removed——那是 #2111 的新清播機制在清舊版 worker 被殺掉時留下的 staging 檔。同樣是一次性、無害。
精簡但無損的輸出（#1597）
什麼改變了
CLI 與 MCP 回應預設精簡。官方對「這不是什麼」講得很明確：
- 沒有移除任何工具
- 沒有任何你以前查得到的欄位變得查不到
- 沒有任何答案變得更難找
變的是：營運細節移到明確的旗標與參數後面，預設回應只帶圖譜答案本身。
預設保留（永遠）
- graph rows 與 node identities
- 精確總數（不是「約 N」）
- 截斷狀態——你永遠知道自己在看子集
- 所有被省略內容的 continuation cursors
改為 opt-in
- diagnostics（診斷資訊）
- evidence columns（證據欄位）
- progress chatter（進度雜訊）
- JSON 輸出
配套：語意分頁（14c229b1）
max_output_tokens 現在是確定性、模型中立的 byte 上限——在完整語意單元邊界切分，不在 record 中間切位元組；每個省略項都可獨立分頁。Cursors 綁定查詢參數、結果狀態與索引世代——stale cursor 會 fail closed，而不是默默翻到另一個快照的分頁。
另外新增明確的 quiet CLI mode 供腳本使用（4a9fcd97）。
實測數字
同一個 MCP tools/list 序列化 fixture：23,075 → 15,071 bytes（−34.7%）；cl100k / o200k token 各降 −31.4% / −30.7%。
對既有使用者的影響
| 情境 | 影響 |
|---|---|
| 升級後第一次索引 | 會像冷索引一樣久（預期行為） |
| 腳本解析 CLI/MCP 的詳細欄位 | 需加上對應的 opt-in 旗標 |
| 其他 | 工具與欄位全數可達，只是預設輸出變精簡 |
學習重點
- 身分（identity）設計的省略成本：「檔名不含副檔名」看似精簡，卻讓同目錄同名異語言檔案互相碰撞、靜默丟失符號。身分欄位的每一個「隱含約定」都是未來的碰撞——而修身分就意味著格式遷移，所以身分要一次做對。
- 格式版本要蓋在資料裡，不是靠檔名猜：
PRAGMA user_version讓「舊資料庫需要重建」成為資料自己宣告的事實，而不是工具用啟發式猜測。 - 「省 34%」的正確姿勢：不是刪資訊，是把營運雜訊移到明確要求的後面——總數仍然精確、截斷仍然透明、每個省略仍然可分頁。token 經濟學的前提是無損。
來源：v0.11.0