ai-memory 怎麼用？2026 讓 Claude Code、Codex 接力寫程式：安裝、長期記憶與 5 個安全檢查

重點先講：ai-memory 能讓 Claude Code、Codex 共用專案記憶，減少換工具時重講背景的麻煩。它透過三個環節運作：

• Hooks 自動收集工作過程與會話事件。
• Markdown Wiki 保存可閱讀、可編輯的專案知識。
• Handoff 把未完成工作交給下一個 Coding Agent。

最後更新：2026 年 10 月 23 日

資料截點：2026-10-23 12:00（台北時間）

Claude Code 幫你修改 API，做到一半發現另一項工作更適合交給 Codex。你開啟 Codex，卻得重新解釋專案架構、已經試過的修復方法、哪些測試還沒通過。

這種情況很常見。AI Coding Agent 可以協助修改數十個檔案，但換一個工具，就可能失去前一段工作的上下文。

GitHub 上的 akitaonrails/ai-memory 正在處理這件事。它把 Coding Agent 的工作紀錄整理成可保存、可搜尋的專案記憶，再利用交接機制提供給下一個 Agent。

我認為這個專案最值得注意的地方，是它把「工作到哪裡」從單一 AI 工具的聊天紀錄中抽離，交給一套可以自己檢查的記憶系統。

但先說明：本文是依官方 README、安裝文件、使用文件與安全說明整理的操作指南。本站尚未完成跨 Agent 的端到端安裝實測，因此不會把官方功能描述寫成已驗證的成效。

ai-memory 是什麼？跟 Claude Code 內建記憶有什麼不同？

一句話結論：ai-memory 是開源的 Coding Agent 長期記憶與交接工具，讓不同 AI 編程工具存取同一套專案知識，並延續未完成工作的上下文。

一般 Coding Agent 已經有不同程度的記憶或專案說明功能。最簡單的方法，是在專案中放一個 Markdown 文件，告訴 AI 程式架構、習慣與限制。

這很實用，但有幾個問題：誰來更新文件？哪些重要決策值得保存？切換工具之後，下一個 Agent 怎麼知道上一個 Agent 曾經嘗試哪些失敗方案？

ai-memory 的方向，是透過生命週期 Hooks 觀察工作過程，在會話結束時整理記憶，並在新會話開始時提供交接資訊。

因此，已經習慣只用 Claude Code、專案也不大的開發者，可能不需要額外安裝一個記憶服務。經常切換 Claude Code、Codex、Cursor 或其他 Coding Agent 的團隊，才更有理由評估。

ai-memory 會記住哪些東西？是把聊天紀錄全部存起來嗎？

官方 README 把運作流程整理成四個階段：capture、consolidate、recall、handoff。

1. Capture：Hooks 在工作期間收集提示詞、工具呼叫、會話邊界等觀察事件，並依設定進行資料過濾。
2. Consolidate：會話結束時，把觀察紀錄整理成專案 Wiki 頁面。
3. Recall：下一個 Agent 可以搜尋先前的決策、問題與工作資訊。
4. Handoff：提供下一段工作需要的摘要，包括目前進度、未解決的事情與交接資訊。

其中有個重要差別：可閱讀的 Wiki 頁面、用來搜尋的資料庫，以及部分模式下保存的觀察紀錄，不是同一種東西。

按照官方架構，一個 ai-memory 資料目錄可能包含：

<data_dir>/
├── wiki/
├── raw/
├── db/
├── models/
└── logs/

wiki/ 保存 Markdown 頁面，是專案知識的主要來源；raw/ 保存經過清理的工作觀察片段；db/ 包含 SQLite 與搜尋索引；logs/ 保存服務日誌。這是目錄結構示意，不代表每次安裝都會立即產生所有檔案。

使用者可以直接閱讀 Markdown Wiki，而資料庫索引可以依內容重新建立。這是它與完全依賴封閉式聊天歷史服務的一個重要差異。

不過，長期記憶不代表永久正確。Agent 可能誤解測試失敗原因、把暫時決策當成固定規則，或在程式碼已經修改後繼續引用舊文件。

因此，架構、部署方式、測試結果這類容易變動的資訊，仍須和現在的程式碼、Git Commit 與 CI 結果對照。

ai-memory 怎麼安裝？新手需要先準備什麼？

官方提供 Linux、macOS、Windows、Docker 及其他安裝路線。開始之前，先確認電腦系統、預計整合的 Agent 工具，以及自己是否具備管理本機服務的權限。

不必先學會自行寫一套記憶資料庫才能使用 ai-memory，但至少要能操作終端機、閱讀安裝輸出，以及檢查 AI 工具的設定變更。完全沒有終端機經驗的使用者，最好先在不含敏感資料的測試專案練習。

第一步：下載官方版本

Linux 與 macOS 的官方快速入門提供以下安裝方式：

curl -fsSL https://github.com/akitaonrails/ai-memory/releases/latest/download/install.sh | sh

這是官方文件提供的命令，不是本站已執行的測試紀錄。由於它會下載並執行遠端腳本，安全上更謹慎的做法，是先開啟 GitHub Releases，檢查發行版本、安裝腳本內容、支援平台與 SHA-256 校驗流程，再於隔離環境執行。

Windows 使用者的官方 PowerShell 路線為：

irm https://github.com/akitaonrails/ai-memory/releases/latest/download/install.ps1 | iex

同樣建議先檢視腳本再執行。官方支援矩陣把 WSL2 列為支援環境，原生 Windows 則標示為 Experimental；若公司電腦限制 PowerShell 腳本、背景服務或防火牆設定，應先請管理員確認。

第二步：執行初始化設定

ai-memory setup

依官方 README，setup 會規劃資料目錄、服務啟動與支援工具的整合。互動式流程會顯示偵測到的 Agent 及預計修改的設定，讓使用者選擇要接入的工具。

如果希望先看設定計畫、不立即修改，可以使用：

ai-memory setup --plan

這一步尤其重要。Coding Agent 的設定可能包含 Hooks、MCP 與 Skills。新增整合之後，工具能存取哪些資料、什麼時候會將事件送給記憶服務，都應事先理解。

第三步：檢查服務狀態

ai-memory status

確認服務已啟動、必要整合是否設定完成、是否啟用認證，再重新啟動已接入的 Coding Agent。

請注意，服務啟動成功只代表基本環境可運作，不代表整條記憶保存與跨工具交接流程已通過測試。

如何從 Claude Code 交接給 Codex？

最直觀的驗收方法，是準備一個小型測試專案，讓 Claude Code 留下一項尚未完成的工作，再檢查 Codex 能否找回必要背景。

官方文件提供兩條值得區分的路線：一般 Hooks/MCP 整合，以及透過 ai-memory run 管理的工作流程。

路線一：透過 Hooks 自動交接

1. 在測試專案確認 Claude Code 已完成 ai-memory 整合。
2. 請 Claude Code 閱讀一個小型程式模組，分析問題並說明下一步，但先不要修改所有程式。
3. 正常結束會話，讓 SessionEnd 相關機制有機會建立工作摘要。
4. 在同一專案目錄啟動已整合的 Codex。
5. 詢問：「上一段工作做到哪裡？還有哪些問題沒有解決？」
6. 核對回覆是否符合前一段工作紀錄。

官方使用文件指出，安裝生命週期 Hooks 後，可以在會話結束時建立交接資訊，並於後續會話開始時提供給接手的 Agent。

但交接內容有範圍、優先序及生命週期設定，例如人工建立的 handoff 與自動產生的 handoff 可能具有不同優先權。不能假設每次啟動都會取得所有歷史內容。

路線二：使用 Managed Workstreams

官方 README 也介紹 ai-memory run，供需要跨 Agent 延續工作流程的使用者採用。

例如：

ai-memory run codex

這種模式除了共用記憶，也會依官方設計管理 workstream，並可在符合條件時提供上一個工具的可見歷史內容給新工具使用。

不過，這條路線的實際行為取決於 Agent 支援程度、版本與設定。官方將 Managed Workstreams 標示為可選功能，不能直接等同於所有 Agent 都具備完整的原生會話續接能力。

該怎麼確認交接真的成功？

我會使用一份簡單的驗收表，而不是只問 Agent「你記得嗎」。

若新 Agent 能說出正確的專案架構，卻漏掉一項失敗測試，就只能說部分交接成功。若它自行補上從未發生的決策，更需要追查記憶來源。

這份表格是本文提出的驗收方法，並非 ai-memory 官方的效能測試結果。

ai-memory 會保存 API Key 或私密程式碼嗎？

這是部署前最應該確認的問題。

官方設計包含在資料進入儲存流程前的清理機制，並允許使用者設定路徑排除規則。對開發者來說，這比完全不提供任何過濾功能更容易管理，但仍然不能視為機密資料不會被記錄的保證。

尤其要注意：路徑排除規則不是完整的資料外洩防護系統。如果敏感字串出現在普通的提示詞、工具輸出或非排除路徑中，就不能只依賴檔案路徑規則保護資料。

安裝前至少檢查這五件事

1. 確認擷取範圍：先閱讀官方 Capture 設定，檢查哪些路徑及工具事件會進入記憶系統。
2. 設定機密資料排除：針對憑證、金鑰、私人設定及客戶資料建立合適的路徑規則，必要時使用 allowlist。
3. 確認認證狀態：官方原生初始化流程會建立 bearer token，但舊安裝或 Docker 快速入門可能存在未啟用認證的情況。
4. 檢查網路暴露面：確認服務是否僅綁定本機回環介面；如需跨電腦連線，必須重新評估 TLS、身份驗證與存取權限。
5. 驗證刪除及備份：Markdown Wiki 可能具有 Git 歷史，不能只刪除目前頁面就認定所有先前版本與其他資料副本都已清除。

其中第三點很容易被忽略。官方文件指出，一般服務預設綁定 loopback，而 Docker 快速入門的部分配置並未自動建立認證資訊。若後續調整成區域網路可存取，必須先處理身份驗證，不能把本機範例直接搬到公開網路。

另外，開啟選用的 LLM 整理或向量服務後，資料流向可能和不使用外部模型的預設模式不同。採用任何第三方模型之前，應查閱 官方 DATA_HANDLING.md，確認傳輸範圍、保存方式與供應商條件。

不接 LLM API，也能使用 ai-memory 嗎？

可以。依官方說明，基本的捕捉、儲存、搜尋及交接流程可以在不呼叫外部 LLM 的情況下運作。

它的 Markdown Wiki 會作為主要知識來源，SQLite 提供搜尋索引，包含全文搜尋、實體與關聯資訊。選用的 LLM 可以協助改善摘要整理，部分向量檢索功能也需要額外的模型或服務。

這裡要分清三件事情：

• ai-memory 本身不必依賴雲端 LLM 才能保存基本記憶。
• 如果使用 Claude Code 或 Codex，這些 Coding Agent 本身的模型服務仍可能產生費用。
• 若自行啟用外部 LLM 或 Embedding Provider，則可能增加 API 使用成本與資料處理要求。

因此，不能把「記憶服務可零 LLM 呼叫」宣傳成「整套 AI 編程工作流程完全免費」。

專案在 GitHub 標示 MIT 授權；商業或企業部署前仍應查看完整 LICENSE、第三方相依套件授權，以及自己接入的模型服務條款。

ai-memory 跟 Hindsight、Mem0 或普通 Markdown 筆記怎麼選？

這些工具有相似的記憶需求，但設計重點不同。沒有一個工具能在所有工作情境下直接取代其他方案。

這張表是依工具定位整理的選型參考，並非同環境的速度、準確率或費用比較。

對只使用一種 Agent、而且任務通常當天就能完成的人，我傾向先把專案說明文件和測試紀錄整理好，再決定要不要增加一套服務。

對每天都在 Claude Code、Codex 與其他開發工具之間切換的工程師，ai-memory 提供一條更具體的實驗路線：先用小專案驗證交接是否可靠，再逐步擴展到正式環境。

如果重點是 Agent 從過往任務中學習、建立更複雜的記憶或推理流程，可以延伸閱讀本站的 Hindsight 長期記憶介紹，不必強行把兩者當成完全相同的產品。

哪些人適合使用 ai-memory？哪些人可以先不用？

我的判斷標準是：工作上下文是否真的跨工具、跨會話流失，而且這種流失是否已經造成可觀的重複工作。

適合先試用的情況：同一個專案經常由 Claude Code 與 Codex 輪流處理；大型程式庫需要持續累積架構決策；多人協作時，已經有明確的權限與資料治理流程。

可以先維持現狀的情況：只有單一 Agent、工作範圍很小、專案文件已經完整，或團隊目前沒有能力管理額外的本機服務。

需要特別謹慎的情況：開發環境含客戶個資、正式環境憑證、未公開商業程式碼，或者公司規範禁止對工作事件進行自動蒐集。

對接案工程師來說，真正有價值的結果不是裝了多少 AI 工具，而是換人、換工具時能否快速找回可核實的工作資訊。若交接成本確實降低，就能把時間留給測試、文件與交付品質；但改善幅度必須依實際專案量測。

實際導入前，怎樣設計一個可信的測試？

我會先設計有對照組的小型實驗，避免只憑一次成功的交接就判定工具可靠。

1. 選一個沒有機密資料的小型 Git 專案。
2. 準備固定任務，例如修正兩個函式、更新一份測試文件，並留下明確的未完成工作。
3. 先在沒有 ai-memory 的情況下，從 Claude Code 交接到 Codex，記錄重新說明背景所需的步驟。
4. 在另一份同條件的測試副本中啟用 ai-memory，完成相同交接。
5. 比較是否能找回必要決策、是否引用過時資訊、是否需要人工補充，以及是否有敏感資料進入儲存區。
6. 讓人工審查者核對 Git Diff、測試結果與 handoff，並記錄失敗案例。

測試結果至少分成完整、部分、不正確、無法交接四類。不要只看 Agent 是否回答得流暢，更要看它的敘述有沒有對應到實際證據。

建議同時記錄 Agent 版本、ai-memory 版本、作業系統、接入方式及模型設定。若前後測試條件不同，交接品質的差距就未必由 ai-memory 造成。

這套方法不必一開始就做大型 benchmark，但至少能回答一個實際問題：裝上 ai-memory 之後，你的工作流程究竟少了哪些重複說明，又多了哪些維護負擔？

ai-memory 常見問題 FAQ

ai-memory 可以讓 Claude Code 與 Codex 共用記憶嗎？

依官方整合說明可以，但需要正確設定 Hooks、MCP 或相應的管理工作流程。跨工具支援不代表不同工具的全部會話能力完全一致，仍須逐一驗證。

ai-memory 會自動記住所有事情嗎？

不會保證完整或永遠正確。系統存在擷取範圍、摘要整理、記憶搜尋及交接資訊量的限制。重要決策應定期與程式碼及原始記錄核對。

沒有付費 LLM API 可以使用嗎？

官方說明基本記憶流程可以零外部 LLM 呼叫運作；但 Coding Agent 本身、額外的 LLM 整理或 Embedding Provider 仍可能涉及費用。

ai-memory 的記憶放在哪裡？

官方架構使用由服務管理的資料目錄，包含 Markdown Wiki、原始觀察紀錄、SQLite 索引等。實際位置依安裝平台及設定而異，應以當前環境的設定為準。

Windows 可以安裝 ai-memory 嗎？

官方提供 Windows PowerShell 安裝方式，也支援 WSL2。但支援矩陣將原生 Windows 標示為實驗性，因此正式導入前應確認版本與相容性。

ai-memory 能保證不儲存密碼或 API Key 嗎？

不能這樣保證。官方提供資料清理、擷取排除與認證設定，但不應將它視為完整 DLP 防護機制。敏感環境必須先確認資料流向與權限。

結論：ai-memory 值得花時間研究嗎？

如果每天只使用一個 Coding Agent，而且專案文件清楚，手動 Markdown 記憶可能已經足夠。

如果工作經常從 Claude Code 移到 Codex，第二個工具又得花時間重新理解架構、決策和失敗嘗試，那麼 ai-memory 的設計就很符合這種需求。

我最在意的優點是它保留了人類可閱讀、可修改的 Markdown Wiki，也讓交接不必完全依賴單一聊天介面的歷史紀錄。

但要把它放進正式開發流程，我會先確認兩件事：新的 Agent 是否真的拿到正確且最新的工作內容，以及記憶服務是否保存了不該留下的資料。

這兩關通過，才有足夠理由擴大部署。工具能保存資訊，不代表它已經理解資訊；能延續工作，也不代表已經完成驗收。

延伸閱讀

• Hindsight 開源教學：AI Agent 長期記憶
• context-mode：AI 寫程式一直忘記上下文怎麼辦？
• OpenRig：Claude Code、Codex 多 Agent 分工與驗收
• AgentOps：AI Agent 工作成果驗收指南

資料來源

• akitaonrails/ai-memory 官方 GitHub 倉庫與 README
• 官方安裝說明
• 官方日常使用與 Handoff 說明
• 官方系統架構
• 官方安全性文件
• 官方資料處理說明
• 官方版本發行頁

資料截點：2026-10-23 12:00（台北時間）。本文依當時可取得的官方文件與附件素材整理；實際安裝流程、支援矩陣、服務功能及版本資訊可能隨後續更新而改變。本站未執行上述安裝命令，亦未對跨工具交接成功率、記憶準確率或效能改善幅度進行實測。

利益揭露：本文未包含返佣連結、邀請連結或付費合作推薦。

免責聲明：本文僅供開源工具研究與軟體工程教育參考，不構成資安稽核、法務或投資建議。執行第三方安裝腳本、啟用 Coding Agent Hooks、設定 MCP 或部署記憶服務之前，應自行檢查原始碼、權限、憑證、資料處理政策、相依套件與授權條款。AI 自動產生的摘要及交接內容可能遺漏或誤述資訊，正式修改與部署仍須人工審查。