agentmemory

agentmemory 是什麼？

agentmemory 是 AI 程式代理的本地「記憶層」，用來擷取代理的會話活動，並提供後續步驟的快速回憶。它以單一 Node 程序在您的機器上執行，並將狀態以 JSON 格式儲存在磁碟上，無需外部資料庫。

系統透過自動擷取鉤子捕捉工具呼叫與提示，將原始觀察結果整合為語義記憶，並透過混合管道（BM25 + 向量 + 知識圖譜）提供檢索服務，搭配裝置端重新排序。

主要功能

• 本地執行環境與 JSON 磁碟狀態（零外部資料庫）： 以單一 Node 程序執行，並將資料以 JSON 格式持久化至磁碟；無需 Redis、Kafka、Postgres、Qdrant 或 Neo4j。
• 代理活動自動擷取鉤子： PreToolUse、PostToolUse、SessionStart、Stop 及其他事件會直接進入記憶管道，安裝後無需額外整合程式碼。
• 混合檢索與裝置端重新排序： 三重串流回憶結合 BM25、向量與知識圖譜訊號，並在裝置端重新排序結果（頁面描述為「筆記型電腦上 P50 低於 20ms」）。
• 自動整合與保留行為： 每小時掃描將原始觀察結果整合為語義記憶、合併重複項目、依保留評分讓過時資料衰減，並在刪除項目時輸出批次稽核記錄。
• MCP 伺服器與定義的工具介面： 提供 MCP 工具如 memory_save、memory_recall、memory_smart_search、memory_sessions、governance、audit 與 export，同時為每個 MCP 工具提供 REST 對應端點 /agentmemory/*。
• 透過 JSONL 匯入進行會話重播： 從 Claude Code JSONL 轉錄檔重新建立會話，包括觀察結果、工具使用與時間軸，存入儲存庫。
• 知識圖譜壓縮與查詢： 壓縮過程中提取實體與關係；支援透過 /agentmemory/graph 進行圖譜查詢，並可在檢視器中進行視覺化。
• 節點間聯邦同步（已驗證 HTTPS）： 使用持有者權杖驗證在 agentmemory 節點之間推送/拉取記憶；頁面明確註明「無靜默同步」。
• 本地檢視器與可觀測性輸出： 提供即時觀察串流檢視器（連接埠 3113）與記錄/追蹤功能，透過「OTEL 可觀測性工作程式」輸出 OTLP（支援 Jaeger、Honeycomb、Tempo 等追蹤後端）。

如何使用 agentmemory

1. 安裝一次： 執行 npm install -g @agentmemory/agentmemory 將 agentmemory 加入 PATH。
2. 啟動伺服器： 執行 agentmemory（伺服器執行於 :3111，檢視器執行於 :3113）。
3. 本地驗證： 開啟 http://localhost:3113 查看即時觀察串流與儀表板。
4. 透過 MCP 連接代理： 設定您的代理使用 agentmemory MCP JSON 設定（網站說明「一個 MCP JSON 適用於大部分情境」）。
5. 選擇性匯入過去會話： 使用提供的 JSONL 會話匯入功能，將先前代理執行結果重播至儲存庫。

使用情境

• 建立跨多個程式碼會話的延續性： 擷取每個會話的提示與工具使用，讓後續代理動作能快速檢索相關過去觀察結果。
• 支援「代理為何這麼做？」的稽核： 使用刪除時輸出的稽核記錄與可觀測性/追蹤輸出，檢視記憶體操作與會話處理期間發生的事情。
• 提升混合查詢的檢索品質： 當查詢包含詞彙、語義或依賴提取的關係時，使用混合搜尋（BM25 + 向量 + 知識圖譜）與裝置端重新排序。
• 將轉錄檔轉為可重複使用的記憶： 匯入 Claude Code JSONL 轉錄檔重建完整會話時間軸，適用於需要後續查詢的過去執行結果。
• 協調多個代理機器： 使用已驗證 HTTPS 在 agentmemory 節點之間設定點對點同步，進行記憶推送/拉取交換。

常見問題

• agentmemory 是否需要外部資料庫（如 Postgres 或 Qdrant）？ 不需要。本頁面標明「ZERO EXTERNAL DATABASES」，並說明系統以單一程序執行，狀態以 JSON 格式儲存在磁碟上。

• 如何存取用於儲存與回憶記憶的工具？ agentmemory 提供 MCP 伺服器，包含 memory_save 與 memory_recall 等工具。本頁面也說明每個工具皆有 REST 端點，位於 /agentmemory/*。

• 我可以在哪裡查看伺服器正在擷取的內容？ 系統會自動啟動檢視器，監聽埠號 3113，顯示即時觀測串流、工作階段探索器、記憶瀏覽器、知識圖譜視覺化，以及健康儀表板。

• 我可以匯入現有的程式碼對話記錄？ 可以。本頁面說明支援 JSONL 工作階段匯入流程，可將 Claude Code JSONL 記錄檔重新轉換為觀測資料、工具使用記錄與時間軸。

• agentmemory 是否支援在不同機器之間移動記憶資料？ 本頁面說明支援透過已驗證的 HTTPS 進行點對點同步，並需使用 bearer-token（不會進行無提示同步）。

替代方案

• 通用向量資料庫 + 自訂代理記憶層： 你可以儲存嵌入向量並實作檢索，但需自行負責協調、整合、掛鉤，以及工作階段／時間軸處理，與 agentmemory 所述的自動擷取 + MCP/REST 介面不同。
• 用於程式碼歷史的本地知識庫工具（註記／圖形風格系統）： 此類工具可索引文件並提供搜尋／圖形檢視，有助於回憶，但可能無法透過本頁面所述的掛鉤流程直接擷取代理工具呼叫與工作階段事件。
• 不具代理專屬自動擷取功能的 RAG 框架： 許多 RAG 堆疊可提供檢索與生成時的內容組裝，但可能需要更多自訂整合，才能將 SessionStart/Stop 與工具使用事件擷取到可檢索的記憶模型。
• 僅限代理遙測／可觀測性設定： 追蹤工具可協助檢視行為，但通常無法提供 agentmemory 所述的記憶整合、檢索端點與重播匯入流程。