agentmemory：AI 代理的跨 session 記憶伺服器
AI 編碼代理沒有跨 session 的記憶。關掉視窗，前一輪累積的脈絡就清空了，下一次必須重新說明架構、重新發現同一個 bug、重新告知偏好設定。多數人的對策是手寫一份 CLAUDE.md 或 .cursorrules，但依 README 說明：這種內建記憶約 200 行即達上限，且隨時間過時。
agentmemory 是一個在背景執行的記憶伺服器，搭配 12 個 hooks 自動側錄代理的每一次工具呼叫。觀察會被去重（SHA-256）、過濾隱私、用 LLM 壓縮、嵌入向量，再寫進索引。下一個 session 開場時，相關脈絡會自動注入回去，代理不需要再次提問即可取得上下文。
設計上它延伸自 Karpathy 的 LLM Wiki 模式，加入信心評分、生命週期管理與知識圖譜。記憶分四層整併：原始觀察為 Working，壓縮後的 session 摘要為 Episodic，萃取出的事實與模式為 Semantic，沉澱下來的工作流程為 Procedural。記憶依 Ebbinghaus 遺忘曲線衰減，常被取用的強度增加，陳舊的自動淘汰，矛盾的由系統偵測並化解。
側錄 Capture
壓縮 Compress
索引 Index
注入 Inject
回想 Recall
「You explain the same architecture every session. You re-discover the same bugs. You re-teach the same preferences.」每個 session 重複解釋相同的架構決定、重新發現相同的 bug，是 agentmemory 要解決的核心問題。
一行 npx 啟動記憶伺服器，連線由 hooks 自動完成
最快的路徑是 npx，不需要全域安裝即可啟動記憶伺服器，運行於本機 :3111。第二行的 demo 會灌入幾段範例 session，當場示範回想能力，方便在接上正式專案前先確認效果。
# 30 秒體驗:啟動伺服器並看一次回想示範
npx @agentmemory/agentmemory
npx @agentmemory/agentmemory demo正式安裝:全域安裝並接上代理
長期使用建議全域安裝，再用 connect 把記憶層接到指定代理。connect 會自動寫好設定：Claude Code 取得 12 個自動側錄 hooks，Cursor、Gemini CLI、Cline 等則接上 MCP 伺服器。
npm install -g @agentmemory/agentmemory
agentmemory # 啟動記憶伺服器於 :3111
agentmemory connect claude-code # 接上代理(也支援 cursor / codex / gemini-cli …)CLI 指令、51 個 MCP 工具與斜線指令分類說明
agentmemory 的能力分三類：命令列工具（安裝、連接、診斷）、51 個 MCP 工具（8 個核心、43 個延伸，負責讀寫與治理記憶），以及斜線指令（在對話中直接呼叫記憶）。以下卡片列出最常用的一組。熟悉 memory_recall、memory_smart_search、memory_save 這三個工具並搭配自動側錄 hooks，可覆蓋日常九成用法。
CLI · 01
agentmemory
記憶伺服器
啟動本機記憶伺服器於 :3111。一台伺服器服務所有代理,零外部資料庫。
CLI · 02
agentmemory connect
代理接線員
把記憶層接到指定代理。自動寫好 Claude Code 的 hooks,或 Cursor、Gemini CLI 的 MCP 設定。
CLI · 03
agentmemory demo
回想示範
灌入範例 session 並當場證明回想能力。先看到效果,再決定是否信任。
CLI · 04
agentmemory doctor
互動診斷
逐項檢查環境與連線,遇到問題給出修復提示。安裝卡住時第一個跑它。
Capture · 05
12 hooks
自動側錄
從 SessionStart 到 PostToolUse 到 Stop,在生命週期各點側錄,完全不需手動。
Capture · 06
agentmemory import-jsonl
歷史回填
匯入舊的 Claude Code JSONL 對話記錄,讓記憶從第一天就不是空的。
Recall · 07
memory_recall
過往觀察查詢
搜尋過去側錄的觀察。代理要回想「上次怎麼做」時的第一道入口。
Recall · 08
memory_smart_search
混合檢索引擎
BM25 關鍵字加向量嵌入加知識圖譜,以 RRF 融合排序。LongMemEval-S 上 R@5 達 95.2%。
Recall · 09
memory_save · /remember
主動寫入
把一個決定、洞察或模式手動存進長期記憶。自動側錄之外,你也能親手標記重點。
Govern · 10
memory_consolidate
四層整併
把 Working 觀察逐層提煉成 Episodic、Semantic、Procedural。記憶從雜訊變知識。
Govern · 11
memory_graph_query
知識圖譜遍歷
沿著概念、檔案、決策之間的關係走查,而不只是比對關鍵字。
Coordinate · 12
memory_lease · memory_signal_send
多代理協作
用 leases 鎖定獨佔動作、用 signals 在代理間傳訊。多個代理共用同一層記憶不打架。
四層記憶,一張表看懂
記憶分層整併：越上層越接近可直接行動的知識。memory_consolidate 負責把下層提煉成上層。
| 層級 | 內容 | 對應的人類記憶 |
|---|---|---|
Working | 來自工具呼叫的原始觀察 | 短期記憶 |
Episodic | 壓縮後的 session 摘要 | 「發生過什麼」 |
Semantic | 萃取出的事實與模式 | 「我知道什麼」 |
Procedural | 沉澱下來的工作流程與決策模式 | 「該怎麼做」 |
六項官方文件建議的進階配置
以下六項設定來自 README 與官方設定文件，對 token 成本、context 壓縮存活率與隱私三方面有明顯影響。所有旗標均來自官方文件，未加入未經查證的參數。
先跑 demo,再決定信不信
安裝後執行 npx @agentmemory/agentmemory demo。它會灌入範例 session 並示範回想結果。確認回想到正確脈絡後，再把它接到正式專案。
來源 · 官方 README · Quick Start
用環境變數控制工具數量
51 個 MCP 工具不一定都要曝露給代理。設 AGENTMEMORY_TOOLS=core 只保留 8 個核心工具,省下 context;要完整治理能力時再切 AGENTMEMORY_TOOLS=all 解鎖全部。
來源 · 官方 README · MCP 設定
用 import-jsonl 回填歷史
不想從空白記憶開始?agentmemory import-jsonl 會匯入你過去的 Claude Code JSONL 對話記錄。裝好的第一天,代理就帶著你先前的決策與架構脈絡。
來源 · 官方 README · CLI 指令
接本機嵌入,token 成本歸零
README 的成本表寫得很清楚:agentmemory 一年約 17 萬 token($10 等級);若改用本機嵌入模型,檢索的嵌入成本直接降到 $0。長期專案值得切過去。
來源 · 官方 README · 成本對照表
用 <private> 標籤擋住敏感內容
agentmemory 會在寫入前自動剝除 API key 與密鑰。如需更精確地控制，把不想被記住的段落包進 <private> 標籤，標籤內的內容不會進入記憶儲存。
來源 · 官方 README · 隱私說明
PreCompact hook 讓記憶撐過壓縮
Claude Code 的 context 壓縮後，原有脈絡會稀釋。agentmemory 的 PreCompact hook 會在壓縮前把記憶重新注入，使長對話中途也能保留完整上下文。
來源 · 官方 README · Hooks 清單
跨 session 記憶保留的實際操作流程
以下情境直接取自 README:Session 1 你請代理接好 JWT 驗證;Session 2 隔天回來,你只說「加上 rate limiting」。看 agentmemory 怎麼讓代理在你開口前就已經知道你的 auth 用了什麼、測試蓋了哪些、為什麼這樣選。
$ You ›
幫我在這個 API 接上 JWT 驗證,要能在 Edge runtime 跑。
claude: Claude ›
我會用 jose 做 middleware，它沒有 Node 內建模組依賴,
在 Edge runtime 比 jsonwebtoken 安全。寫進 auth.ts。
$ You › /remember 選 jose 是因為 Edge runtime 相容性
$ You ›
幫這個 API 加上 rate limiting。
claude: Claude ›
先回想一下這個專案的脈絡，
> → memory_smart_search("auth rate limiting api")
hl: 命中 3 則記憶:
· auth 用 jose middleware,位於 src/middleware/auth.ts
· 測試 tests/auth.test.ts 已覆蓋 token 驗證
· 決策:選 jose 而非 jsonwebtoken(Edge 相容性)
claude: Claude ›
我已經知道你的 auth 結構。rate limiting 我會接在
同一條 auth.ts middleware 鏈上,維持 Edge 相容,
並沿用你既有的測試風格補 regression test。
不需要你再解釋一次架構。
ok: 實作完成 · 沿用 jose 鏈 · 測試 +6 · 與既有風格一致
Session 2 你問 rate limiting，代理已知道 auth 用 jose middleware、測試覆蓋範圍，以及選 jose 的原因，不需要再次說明架構。
這段流程為什麼關鍵
整段流程中，memory_* 指令全由系統自動呼叫。hooks 在背景側錄，代理在 Session 2 開場時自行呼叫 memory_smart_search。唯一一次主動介入是用 /remember 標記「為什麼選 jose」的決策理由，將其釘進 Semantic 層。
記憶保留的不只是檔案內容，而是決策理由。代理知道 jose 是刻意的取捨，下一輪不會建議替換。這種連續性使跨 session 的工作品質保持一致。
安裝與使用前需確認的已知限制
多代理協作與治理工具的擴展路徑
把基本回想跑順之後,agentmemory 真正的縱深在多代理協作與治理。同一台記憶伺服器服務所有代理,意味著你可以讓多個 AI 共用一份脈絡,而不是各記各的。
進階玩法地圖
**1. 解鎖完整工具面。**設 AGENTMEMORY_TOOLS=all 把 MCP 工具從 8 個核心擴到 51 個,拿到 memory_consolidate、memory_audit、memory_graph_query 等治理與稽核能力。
**2. 讓多個代理協作。**用 memory_lease 鎖定獨佔動作、memory_signal_send 與 memory_signal_read 在代理間傳訊、memory_mesh_sync 在多個 agentmemory 實例間做 P2P 同步。
3. 與團隊共享記憶。memory_team_share 讓專案知識不再鎖在個人機器上;新進同事接上同一台伺服器,就承接整個專案的決策史。
**4. 把 token 成本壓到零。**改用本機嵌入模型,檢索的嵌入成本歸零,記憶系統的長期持有成本接近免費。
**5. 用 iii 原語擴充。**底層 iii-engine 支援 iii worker add，可加入 pubsub、cron、佇列、可觀測性、沙箱與 SQL 後端，將記憶層擴展為更完整的代理基礎設施。
最該讀的三份延伸閱讀
① github.com/rohitg00/agentmemory：主 README，包含完整 CLI、MCP 工具、hooks 與成本對照。 ② agentmemory / releases：版本紀錄，確認安裝版本與已修復的問題。 ③ github.com/iii-hq/iii：底層 iii-engine，說明記憶伺服器的執行模型與擴充點。
內建記憶（CLAUDE.md、.cursorrules）約 200 行即達上限，且隨時間過時。agentmemory 以自動側錄與分層整併解決這項限制。