agentmemory 完整教學 2026：讓 Claude Code 記住你的程式架構，跨 Session 持久記憶

開發者的痛點：AI Coding Agent 的健忘症

你一定有過這種經驗：

• 昨天告訴 Claude Code「這個專案用 TypeScript strict mode，不要用 any」
• 今天重開 session，它又開始用 any
• 你必須再次貼上 CLAUDE.md，重新說明架構決策
• 做了三個月的專案，每次都要「喚醒」AI 的記憶

這就是 AI coding agent 的「工作記憶限制」問題。每個 session 都是白板，context window 有限，你的架構知識、偏好設定、過往決策全部消失。

agentmemory 的出現，正是為了解決這個問題。

agentmemory 是什麼？

agentmemory（GitHub: rohitg00/agentmemory）是目前 GitHub 上 最熱門的 AI coding agent 持久記憶框架，自稱「#1 Persistent Memory for AI Coding Agents」。

2026 年 5 月，agentmemory 在 ProductHunt 也出現在 Trending 欄，顯示受到廣泛關注。目前 GitHub stars 超過 11,487，本週單週新增 7,103 stars，爆發力驚人。

運作原理：記憶壓縮與 MCP 整合

記憶分層架構

agentmemory 把記憶分為三層：

記憶壓縮機制

當記憶量累積到設定閾值，agentmemory 會自動觸發「記憶壓縮」：

1. 分析重複或類似的記憶片段
2. 用 LLM 合併成更精簡的摘要
3. 保留關鍵資訊，刪除冗餘
4. 向量化儲存，支援語義搜尋

這讓長期使用不會因為記憶量爆炸而佔用過多 token。

MCP 整合

agentmemory 提供 MCP（Model Context Protocol）伺服器，AI coding agent 可以透過 MCP 工具呼叫：

• store_memory：存入新記憶
• recall_memory：根據查詢召回相關記憶
• list_memories：列出所有記憶
• delete_memory：刪除特定記憶

安裝設定：5 步驟快速上手

系統需求

• Python 3.10+
• pip（或 uv）
• 支援的 AI coding agent（Claude Code, Codex, Cursor 等）

步驟一：安裝 agentmemory

# 用 pip 安裝
pip install agentmemory

# 或用 uv（更快）
uv pip install agentmemory

步驟二：初始化記憶庫

# 初始化（預設儲存在 ~/.agentmemory/）
agentmemory init

# 指定儲存路徑
agentmemory init --path ~/my-project/.memory

步驟三：設定環境變數

# 在 .env 或 shell config 中加入
export AGENTMEMORY_PATH=~/.agentmemory
export OPENAI_API_KEY=sk-...  # 或 ANTHROPIC_API_KEY

# 若使用 Ollama（本地模型）
export AGENTMEMORY_LLM_PROVIDER=ollama
export AGENTMEMORY_EMBEDDING_MODEL=nomic-embed-text

步驟四：啟動 MCP 伺服器

# 啟動 MCP 伺服器（後台）
agentmemory server start

# 確認運行狀態
agentmemory server status
# → MCP server running on localhost:7878

步驟五：驗證安裝

# 存入第一個記憶
agentmemory store "我偏好用 PostgreSQL，不用 SQLite。原因：需要 JSON 操作與複雜 query。"

# 召回記憶
agentmemory recall "資料庫選擇"
# → 找到記憶：PostgreSQL 偏好，日期：2026-05-18

Claude Code 整合教學

這是最多台灣開發者的使用場景。

方法一：透過 CLAUDE.md 自動注入

在專案根目錄的 CLAUDE.md 中加入：

# 記憶工具

使用 agentmemory MCP 工具：
- 每次 session 開始時，呼叫 recall_memory 查詢「架構決策」、「程式偏好」
- 當用戶說「記住這個」時，呼叫 store_memory 存入
- 當 session 結束前，自動摘要本次決策並 store_memory

方法二：透過 Claude Code 指令

直接告訴 Claude Code：

# 在 Claude Code session 中輸入：
請查詢 agentmemory，召回這個專案的架構決策和程式偏好。

方法三：開機自動載入記憶

# 在 ~/.claude/settings.json 中加入 MCP 設定
{
  "mcpServers": {
    "agentmemory": {
      "command": "agentmemory",
      "args": ["server", "mcp"],
      "env": {
        "AGENTMEMORY_PATH": "/root/.agentmemory"
      }
    }
  }
}

設定後，Claude Code 啟動時會自動連接 agentmemory MCP，可直接呼叫記憶工具。

你：這個專案用 Next.js 15 + TypeScript strict + Tailwind v4
agentmemory: store_memory("技術棧：Next.js 15, TypeScript strict, Tailwind v4. 日期：2026-05-18")

Claude Code: [自動召回] 技術棧：Next.js 15, TypeScript strict, Tailwind v4
→ Claude Code 不再建議使用 any 或舊版 API

MCP 伺服器進階設定

支援的 AI Coding 平台

Cursor 整合設定

# ~/.cursor/mcp.json
{
  "servers": {
    "agentmemory": {
      "url": "http://localhost:7878",
      "enabled": true
    }
  }
}

記憶 namespace 管理（多專案）

# 為不同專案設定獨立記憶空間
agentmemory store --namespace "project-alpha" "使用 Django REST framework"
agentmemory store --namespace "project-beta" "使用 FastAPI + SQLModel"

# 查詢特定專案記憶
agentmemory recall --namespace "project-alpha" "框架選擇"

實戰使用情境

情境一：前端工程師 — 元件規範記憶

# 存入元件規範
agentmemory store "元件規範：
- 所有元件用 React functional component + TypeScript
- Props interface 命名：${ComponentName}Props
- 用 styled-components，不用 CSS modules
- 所有 async 操作用 React Query v5 的 useQuery/useMutation"

此後 Claude Code 生成元件時，自動遵循這些規範，不需每次重述。

情境二：後端工程師 — 資料庫決策記憶

agentmemory store "資料庫架構決策：
- 主資料庫：PostgreSQL 16（Supabase 託管）
- 快取層：Redis（session, rate limit）
- 搜尋：pg_vector（不引入 Elasticsearch，降低維運複雜度）
- ORM：Prisma（不用 TypeORM，因 migration 支援更好）"

情境三：全端工程師 — 錯誤教訓記憶

agentmemory store "踩坑記錄 2026-05-10：
Next.js 15 App Router 中使用 server action 時，
form data 的 file 上傳需要特別處理 FormData，
不能直接用 JSON.stringify。
參考解法：/app/actions/upload.ts 第 23 行。"

兩個月後遇到同樣問題，agentmemory 自動召回這段記憶，Claude Code 直接給出正確解法。

情境四：AI Agent 開發者 — Workflow 記憶

agentmemory store "Agent 系統架構（AutoDev AI 專案）：
- 使用 OpenClaw 管理 agent session
- 工作目錄：/root/ai-services-site
- 每輪先讀 agent-state.json 確認狀態
- 文章提交格式：git add . && git commit -m 'content: ...' && git push origin main"

agentmemory vs 其他解法比較

agentmemory 的優勢在於：開源免費、MCP 標準整合、支援多平台、記憶壓縮節省 token。

雲端部署：多台機器共享記憶庫

如果你有多台機器（本機 + 工作筆電 + 雲端 VPS），可以把 agentmemory 部署到 VPS 上，讓所有機器共用同一個記憶庫。

在 VPS 上部署 agentmemory 伺服器

# 在 DigitalOcean Droplet 上（Ubuntu 22.04）
pip install agentmemory
agentmemory init --path /opt/agentmemory-data

# 啟動為系統服務
agentmemory server start --host 0.0.0.0 --port 7878 --daemon

# 設定 systemd 開機自啟
agentmemory server install-service

本機連接遠端記憶庫

# 設定環境變數指向遠端
export AGENTMEMORY_REMOTE_URL=http://your-vps-ip:7878
export AGENTMEMORY_API_KEY=your-secret-key

# 測試連接
agentmemory recall "測試" --remote
# → 連接成功，遠端記憶庫正常

進階技巧

自動記憶觸發器（Hooks）

# 在 agentmemory.config.yaml 設定自動觸發
hooks:
  on_session_start:
    - recall: ["架構偏好", "程式規範", "重要決策"]
  on_session_end:
    - store_summary: true  # 自動摘要本次決策
  on_keyword:
    triggers:
      - "記住這個"
      - "別忘了"
    action: store_current_message

記憶健康報告

# 檢查記憶庫狀態
agentmemory stats
# → Total memories: 247
# → Compressed: 89 (36%)
# → Last accessed: 2026-05-18 04:15
# → Storage size: 2.3 MB

記憶備份與匯出

# 匯出所有記憶（JSON 格式）
agentmemory export --output my-memories-backup.json

# 匯入記憶（換機或共享）
agentmemory import --input my-memories-backup.json

常見問題

總結：agentmemory 值得裝嗎？

答案是肯定的，尤其如果你：

• ✅ 每天使用 Claude Code、Codex 或 Cursor 開發
• ✅ 有長期維護的專案（超過一個月）
• ✅ 厭倦每次重開 session 都要重述架構
• ✅ 想讓 AI coding agent 真正了解你的偏好

agentmemory 解決了 AI coding agent 最根本的痛點：工作記憶限制。安裝簡單，開源免費，MCP 標準整合讓它與各主流平台無縫配合。

本週 GitHub Trending #2（+7,103 stars/週），代表它正在快速成為業界標準。現在正是最佳進場時機——你可以在它變成每個工程師標配之前，搶先掌握這個工具。