ai-memory：把專案記憶搬出工具，Codex 接手不必從頭解釋

用 AI 摘要這篇文章：

ChatGPT Claude Perplexity Google Grok

先用實測結果開場：一個 Docker 容器、完全不填任何 API 金鑰，ai-memory 2.0.3 就在本機的 127.0.0.1:49374 連接埠起來了。接著我把一條工作紀錄餵進去、手寫了一頁決策筆記、用帶中文的關鍵字把它搜出來，最後走完一輪交接：一端留下任務摘要與未解問題，另一端把這份交接領走，領取紀錄裡連誰領的、幾點領的都有欄位。整段過程沒有向任何模型服務申請過金鑰。這是這類自稱 AI 記憶的工具裡少見的姿態：先把不用錢、不用帳號的部分做完整，模型能力當成選配。

它解決的場景台灣開發者應該都不陌生。Claude Code 用到額度見底，或者一個難纏的 bug 查到一半思路卡死，直覺的動作就是開 Codex 或 Cursor 換個模型續攤。問題在新工作階段什麼都不知道：專案長什麼結構、這個錯誤訊息前面查到哪裡、哪幾個方法已經試過而且確定行不通、接下來打算做什麼。這些脈絡重講一次是十幾分鐘起跳，而它其實前一天才剛講過。ai-memory 想把這段「換手」從口頭重述變成有格式、有版本、可接續的東西。

不填金鑰跑一輪：從餵一條紀錄到領回交接單

測試環境是 Docker 拉官方映像檔、綁本機回環位址、資料落在容器卷冊，命令列只有連接埠跟資料目錄兩個參數。啟動日誌把性格攤得很明白：因為沒有設定任何模型提供者，工作階段整理功能停用、壓縮前快照退回規則式、檢查也只跑規則式；同時它在背景下載一個約 87MB 的本地嵌入模型，並註明混合檢索要等下次重啟才生效。啟動完成時列出的東西也很具體：MCP 端點掛在 POST /mcp 與 POST /hook，請求上限 10MB，Host 標頭只允許 localhost 系列，另外跳出一則警告，提醒這個容器若發布到對外網路介面、又沒設存取權杖，同網段任何人都能呼叫它提供的破壞性工具。一個剛裝好的服務主動唸出自己最危險的設定，這個細節我給高分。

接著我用 MCP 協定直接操作，等於手動扮演掛上記憶服務的兩端 agent。服務列出 18 個工具，涵蓋寫頁、讀頁、搜尋、探索、交接、回饋、刪除與整理。實測走了一整條鏈：先模擬生命週期掛鉤送出一條使用者提示（就是我假裝在修登入 API 的錯誤處理），服務回覆已排隊，翻開資料目錄，這條觀察已經落成 git 版控 wiki 裡的一行 markdown；再手寫一頁決策筆記，回傳的是頁面 id 加一個 git checkpoint 雜湊；然後用「OPTIONS preflight 統一錯誤格式」當關鍵字搜尋，全文檢索直接命中，摘要裡關鍵字帶高亮標記；最後建立交接、再從另一端領取，領到的 JSON 連開放問題清單、建立時間、認領人欄位都是齊的。服務自帶一個唯讀的網頁瀏覽器，麵包屑從工作區、專案一路指到單一頁面檔案，把「記憶就是一堆 markdown」這件事可視化得相當誠實。

Pin

兩個沒走通的地方：手動呼叫工作階段整理工具時，它直接報錯說沒有設定模型提供者、不給跑；而命令列的 finalize-session 對我手動餵進去的工作階段找不到符合對象，最可能是因為真實掛鉤送出的欄位比我拼的完整、代理類型對不上。前者是設計上的邊界（規則式路徑負責基本款，LLM 摘要是選配），後者是我這次測試的邊界：我沒有把它真的掛進 Claude Code 或 Codex 的設定檔去跑一個完整的工作日，掛鉤在真實工具裡的採集完整度，目前只有官方文件的說法，我沒有實測到那一步。

它真正在賣的是交接協定，不是又一個筆記庫

市面上把 AI 記憶做成產品的專案不少，多數的共同點是記憶跟著工具走：Claude Code 有自己的筆記與自動記憶，Cursor 有專案規則，每家都在加，而且每家的東西都關在自己的牆裡。ai-memory 的判斷剛好相反：記憶不該是 agent 的功能，而該是 agent 外面的基礎設施，像資料庫或檔案伺服器一樣自己活著，誰來接都能讀寫。所以它是一個自己跑的服務，Claude Code、Codex、Cursor 都只是它的客戶端。

這個視角解釋了它的幾個設計選擇。資料的原始真相是一個 git 版控的 markdown wiki，你可以 grep、可以拿 Obsidian 開、可以手改、可以 rsync 備份；SQLite 資料庫只是從這些檔案長出來的檢索索引，原檔還在就能整個重建。這個架構等於向使用者保證：記憶不會被鎖在某種專有格式裡，服務哪天不玩了，你的檔案還是你的。實測時我翻進容器裡看，開頭那條假裝的使用者提示，就原封不動躺在專案資料夾當月的 log 頁裡，一行標題加時間戳加原文，誰寫的、什麼時候寫的，開檔案就看到。

而跨工具的交接在它這裡是有型別的協定。以我實測領回的那份交接單為例：它有自己的編號，帶任務摘要（我把 middleware 攔截失敗、改走 per-route handler 的來龍去脈寫進去）、開放問題清單（OPTIONS 誤攔要不要改在路由層處理、三個既有 e2e 測試要不要重寫）、建立時間，以及一整組認領欄位，領取人、領取時間、領取的工作階段各一欄。設計上交接單只能被領一次，領過就結案，不會出現兩個 agent 拿到同一張單各自埋頭做的狀況。這些欄位一個不缺，而且全部出自本機的實跑。

Pin

日常使用的樣貌，這部分出自官方使用文件。掛好之後平常不太需要理它：掛鉤默默收提示與工具呼叫，工作階段結束收斂成 wiki 頁，下個工作階段開場自動收到交接。你對著 agent 說上次做到哪裡、我們有沒有討論過某件事、給我一份最近進度摘要，這些話都會落到記憶服務的查詢上；接手一個有幾個月歷史的既有專案時，有一條 bootstrap 命令可以先把現況掃一輪。另外還有一套可選的 managed workstreams，用 ai-memory run 代替直接啟動工具，跨工具的工作階段連續性再往上一層，這套是明確標成選配的，不開也不影響基本運作。

還有一個容易錯過的分界：它搬的是脈絡，不是工作區。跨機器續作時，ai-memory 只負責讓你在另一台電腦領得到上一台留下的記錄；程式碼、依賴、環境變數本來怎麼同步，現在還是怎麼同步。官方文件把這條線畫得很清楚，期待它連開發環境一起搬的人會失望，但換個角度看，這也是它敢把資料層做成純文字檔案的原因之一，它不需要碰你的程式碼。

零模型預設：先給你不需要金鑰就能跑的功能

一個名字裡有 AI 的工具，預設路徑卻是不呼叫任何模型，這是我在整份文件裡最欣賞的決定。不設金鑰時，擷取、全文檢索、交接照常運作，壓縮前快照與檢查走規則式，工作階段整理與自動改善沒有模型就不啟動；想要工作階段摘要或語意搜尋，再自己接提供者，Anthropic、OpenAI、Gemini、GitHub Copilot 都在支援列，也能對接 Ollama、LM Studio 這類本機端點。v2.0 起更進一步，全新安裝會自動啟用行程內的本地嵌入模型，就是啟動日誌裡那個 87MB 的背景下載，語意檢索不必辦任何雲端帳號；抓不下來的環境就退回純全文檢索，不會因此罷工。

成本帳要算在正確的地方。zero-key 指的是 ai-memory 這個服務本身不花模型錢，你的 Claude Code 或 Codex 訂閱、它們背後把程式碼送上雲端的行為，一毛都不會少。反過來說，隱私邊界也因此清楚：ai-memory 在無提供者模式下不外送記憶內容，掛了雲端 embedding 或摘要之後，相關內容就會交給對應的模型商處理，部署前該看的是對方的資料政策。

擷取側的防護有兩道。第一道在入口：掛鉤送進來的觀察會先過一道分型別的清理邊界才寫入，什麼該遮、什麼該留是按型別走的規則，比一句「會處理」具體得多；第二道在儲存庫層：以 repo 為單位的擷取規則可以把指定路徑整個排除，或反轉成白名單模式，只收你明列的目錄。對會碰到客戶資料或金鑰檔的專案，這兩道加起來等於可以把記憶服務的採集範圍釘死在自己劃的圈子裡，不用賭它剛好沒看到。

記憶放久了會腐化，這件事它也正面處理了。工具清單裡有一整套維護面：lint 會檢查 wiki 頁面之間的一致性，工作階段結束後的自動改善流程會提出頁面修改建議，預設自動核准生效，想逐條人工把關要自行切到手動審核，回饋工具讓你對單一頁面標記對或錯，遺忘掃描可以清掉失效內容。這裡也有個明白的細節：我在無提供者模式下看到啟動日誌明白寫著自動改善排程沒有模型就不啟動，維護面的全速運轉跟摘要一樣，是接了 LLM 之後的事。

官方公布的兩個數字，僅供參考：寫入上限約每秒 700 次，標明是實測值；v2.0 的檢索品質在 LongMemEval-S 上 hit@5 從 0.617 提到 0.823。這兩個都是專案方自己量給自己背的數字，我沒有重現，採用的時候當方向感就好。

支援矩陣裡最值錢的部分，是它承認做不到的事

接線本身不複雜：一條命令裝 MCP、一條命令裝生命週期掛鉤，兩條跑完該工具就會開始把提示與工具呼叫送進記憶服務，反著跑一遍解除安裝，且只移除它自己裝的東西。差異在客戶端這側。Claude Code 是機能最全的一等公民，掛鉤、交接、自動採集到助手最終回覆都有開關；Codex 支援掛鉤擷取，但沒有真正的自動工作階段結束事件，要最終摘要或交接得手動跑一次 finalize-session，而且它明講不給 Codex 裝助手回覆採集；VS Code Copilot 與 Zed 只有 MCP 接入，沒有生命週期掛鉤，等於記憶要靠 agent 主動發問，不會自動長出來。Gemini CLI、Cursor、OpenCode、Grok、Kimi、Kiro 這一長串都各有各的接法與眉角，官方把每個客戶端能做什麼、不能做什麼、哪個事件會被忽略，逐條寫在一張官方自稱用 CI 測試釘住的支援矩陣裡。

我特別把這張矩陣挑出來講，是因為它是判斷這類專案可信度的好工具。多數專案的相容性清單只寫支援什麼，它連某個工具會忽略工作階段啟動注入、某個工具的回覆採集裝不了、某個 CLI 沒有穩定的 session id 這種自曝其短都寫進去。會把限制寫進文件並用測試釘住的專案，通常也會把同一套標準用在資料安全上，這個推論在它身上成立：刪除命令會講清楚刪掉的定義、每次變更進審計日誌、單一實例鎖防止兩個服務寫壞同一個資料目錄。

要讓別的機器連上來，安全是你自己的作業

預設部署綁 127.0.0.1、不開認證，單人筆電使用是合理的預設。一旦想把服務放到家裡伺服器、區網主機或 VPS 上給多台機器、多個同事連，安全就是自己的作業：存取權杖驗證身分、TLS 保護傳輸，官方文件明講認證不等於加密：掛了存取權杖，遠端存取仍要另外上 TLS，並附了反向代理與 Cloudflare Tunnel 的設定範例。多使用者有帳號密碼、API 金鑰、每位成員的寫入歸屬與審計，但資料架構是單租戶，沒有逐頁的權限控制，團隊內共用沒問題，直接當對外知識庫開放給互不信任的對象就超出它的設計了。

平台與安裝方面，Linux 與 macOS 是主要支援對象，Windows 官方路線是 WSL2，原生 Windows 標為實驗性。Docker 之外還有幾條路：Arch Linux 有 AUR 套件含 systemd 服務單元，macOS 有官方建議的原生執行檔，映像檔同時出 amd64 與 arm64 版，我在 Apple Silicon 的 Mac 上直接拉起來沒有任何模擬警告，這點對拿 Mac 開發的人是加分。部署位置按需求分三層：單機就跑本機；桌上機與筆電兩邊要共享，把服務放到常開的家用主機或區網機器，所有設備指向同一個位址；團隊共學則指向同一套服務，每個人的寫入各自歸屬。跨機器場景要記得前面講過的那條線：記憶會跟著服務走，程式碼不會。

天天換工具搬專案的人該裝，長期只用一套的先觀望

判斷標準其實只有一條：你多常在工具之間、機器之間搬同一個專案。天天在 Claude Code 與 Codex 之間換手、公司筆電與桌機兩邊跑、或是團隊想讓每個人的 agent 都查得到同一份專案歷史，這些情境它的價值最直接，尤其你的工作裡有大量那種檔案看不出來的知識，為什麼當初選這個方案、哪條路試過行不通、bug 查到哪一步。相對地，長期只用一套工具的人，原生記憶加專案規則通常已經夠用；不想多養一個服務、多背一份備份與升級責任的人，也沒有必要為了長期記憶多一個照顧對象。它增加的是一套需要設定、更新、備份的基礎設施，這個成本是真實的，換到的東西也是真實的。

跟我們先前介紹過的讓 Claude Code 與 Codex 接上自有模型的作法擺在一起看會更清楚：那類工具解決的是模型從哪裡來，ai-memory 解決的是做一半的脈絡去哪裡放，兩者可以同時用。如果你的煩惱偏向在幾套 AI 編程方案之間選邊站，AI 編程方案比較仍是先讀的那篇；已經在 Claude Code 生態系裡的人，像把書變成工作卡的 Skill或自動畫架構圖的 Skill講的是單一工具內的知識整理，跟跨工具的記憶搬移是互補關係。

授權與專案狀態

MIT 授權，單一 Rust 執行檔，儲存庫 2026 年 5 月底建立，到 2026 年 9 月初已有五千八百多顆星與四百多個 fork。活躍度直接看發布節奏最準：9 月 1 日到 4 日之間連發五版，從 1.39 一路到 2.0.3，2.0 是大改版（wiki 換成可攜的開放格式、混合檢索變預設、本地嵌入上線），之後幾個小版接連處理升級卡點與資料安全，也順手整頓了檢查報告氾濫的問題，這種修法對一個管你記憶的服務來說是好事。維護者是 Ruby 圈資深的巴西開發者 Fabio Akita（akitaonrails），README 也坦言這個程式碼庫是他與 Claude Code 協作出來的，設計文件裡引用了 Karpathy 的 LLM Wiki 筆記與 agentmemory、basic-memory、cognee 等前作的研究脈絡。想動手的人，從 GitHub 專案頁的快速開始照抄兩段命令就能重現我這次的測試環境，玩完一行 docker 指令拆除，不留下任何設定。

Pin