AgentMemory AI 工作流接入教學

01章節

接入指南

原始安裝 runbook

agentmemory banner

這份文件是「接入指南」，不是完整 API reference。需要細節時可從下方文件地圖跳到 repo 內的原始文件。

02Mental Model

把 AgentMemory 想成 5 個卡扣

最少只需要第一個卡扣。要讓 AI 自動記錄與自動回想，就逐步加上 MCP、hooks 與 skills。

卡扣 1 · Memory Server

本機 daemon，REST 在 :3111，Viewer 預設在 :3113。

卡扣 2 · MCP Tools

讓 AI agent 直接呼叫 memory_save、memory_smart_search 等工具。

卡扣 3 · Lifecycle Hooks

在 session start、prompt、tool use、compact、stop 等事件自動捕捉上下文。

卡扣 4 · Native Skills

教 agent 何時該回想、何時該記住、何時該交接或清除記憶。

卡扣 5 · Viewer + REST

人類檢查記憶、session、replay、graph，也能用 REST 接任何自製流程。

03Tutorial

從零到可用: 先讓記憶伺服器跑起來

這段走完，你會有一個可用的 AgentMemory server、Viewer，以及一筆可以搜尋回來的測試記憶。

安裝或直接用 npx 啟動

建議全域安裝一次，之後任何 repo 都能直接執行 agentmemory。

npm install -g @agentmemory/agentmemory
agentmemory

如果你不想全域安裝，用最新版 npx 也可以:

npx -y @agentmemory/agentmemory@latest

確認 server 活著

livez 是最小健康檢查。首次啟動會下載並啟動 pinned iii engine，可能要等幾秒。

curl -fsS http://localhost:3111/agentmemory/livez

預期結果是 HTTP 200。完整健康資訊用:

curl -fsS http://localhost:3111/agentmemory/health

用 demo 看到第一個結果

Demo 會建立 3 個真實感的 coding sessions，然後用語意搜尋證明可召回。

agentmemory demo --serve

打開 Viewer。預設是 http://localhost:3113；如果你用 --port 3112，Viewer 會是 http://localhost:3114。

04Attach

把你的 AI agent 卡上去

選你正在用的 host。Codex 與 Claude Code 可以走 plugin + hooks；Cursor、Gemini CLI、Cline、Windsurf 等通常走 MCP config。

Codex CLI / Codex Desktop

若你使用 Codex plugin platform，先裝 plugin，再在 Desktop 目前的 workaround 下補上 global hooks。

# Terminal 1: 先讓 memory server 跑著
agentmemory

# Terminal 2: 安裝 Codex plugin
codex plugin marketplace add rohitg00/agentmemory
codex plugin add agentmemory@agentmemory

# Codex Desktop 目前建議補這個 hooks workaround
agentmemory connect codex --with-hooks

Codex plugin 會提供 MCP、6 個 lifecycle hooks，以及 AgentMemory skills。若只需要 MCP，也可用 codex mcp add agentmemory -- npx -y @agentmemory/mcp。

Claude Code

推薦用 Claude Code plugin 安裝，因為它會一次註冊 hooks、skills 與 MCP。

# Terminal 1
agentmemory

# Claude Code session 內
/plugin marketplace add rohitg00/agentmemory
/plugin install agentmemory

# 若不用 plugin，而是直接寫 MCP config，補 hooks:
agentmemory connect claude-code --with-hooks

Cursor、Cline、Windsurf、Gemini CLI 等 MCP host

這類 host 通常只需要把同一個 MCP block 合併進設定檔。不要覆蓋原本整個 config。

{
  "mcpServers": {
    "agentmemory": {
      "command": "npx",
      "args": ["-y", "@agentmemory/mcp"],
      "env": {
        "AGENTMEMORY_URL": "http://localhost:3111"
      }
    }
  }
}

若 host 在 sandbox 內連不到你的 host localhost，設定 AGENTMEMORY_FORCE_PROXY=1 並把 AGENTMEMORY_URL 指到可連的 LAN 或 remote URL。

OpenCode、Hermes、OpenClaw、pi

這些 host 有更深的 plugin 或 memory provider 接法。先用 MCP 跑起來，再依需求安裝對應 integration。

# OpenCode MCP-only
agentmemory connect opencode

# Hermes MCP-only
agentmemory connect hermes

# OpenClaw MCP-only
agentmemory connect openclaw

更完整的 OpenCode hooks、Hermes memory provider、OpenClaw memory slot 可看 repo 內 plugin/opencode/ 與 integrations/。

05Automation

加上 skills 與 hooks，讓它自動工作

MCP tools 是「手可以拿工具」。Skills 是「知道什麼時候拿」。Hooks 是「每次工作時自動留下觀察」。

安裝 native skills

這會安裝 15 個 Claude-Code-style skills，包括 remember、recall、handoff、forget、recap、session-history。

npx skills add rohitg00/agentmemory -y

確認 hooks 實際有接上

Claude Code plugin 有 12 個 lifecycle hooks。Codex plugin 有 6 個，Desktop 目前要補 --with-hooks workaround。

agentmemory connect codex --with-hooks
agentmemory connect claude-code --with-hooks

開啟自動注入上下文

預設 hooks 會捕捉，但不一定把記憶注入 prompt。要讓過去記憶自動進入 agent context，明確打開這個 flag。

# ~/.agentmemory/.env
AGENTMEMORY_INJECT_CONTEXT=true

06Verification

驗證你真的接好了

不要只看 config 有沒有寫入。要確認 server、MCP、save/recall、Viewer 四個面向都通。

1. Server health

curl -fsS http://localhost:3111/agentmemory/livez
curl -fsS http://localhost:3111/agentmemory/health

有設定 AGENTMEMORY_SECRET 時，請加上 Authorization: Bearer $AGENTMEMORY_SECRET。

2. REST save/recall round trip

curl -X POST http://localhost:3111/agentmemory/remember \
  -H "Content-Type: application/json" \
  -d '{"content":"AgentMemory workflow snap-in verification","concepts":["workflow","snap-in"]}'

curl -X POST http://localhost:3111/agentmemory/smart-search \
  -H "Content-Type: application/json" \
  -d '{"query":"workflow snap-in verification","limit":5}'

3. MCP tool round trip

在已接入的 agent 中要求它呼叫:

memory_save {
  "content": "AgentMemory MCP wiring works in this agent",
  "concepts": "mcp,wiring,verification"
}

memory_smart_search {
  "query": "MCP wiring works",
  "limit": 5
}

4. Viewer

預設 Viewer:

open http://localhost:3113

如果你用 --port 3112 或目前本機頁面已在 3114，則打開:

open http://localhost:3114/#dashboard

07Daily Use

日常怎麼用它

接好以後，不需要每次手動寫記憶。讓 hooks 捕捉例行工作；在重要決策、專案偏好、bug 復盤時用 explicit memory。

你想做的事	建議用法	實際工具或指令
保存一個重要決策	明確叫 agent 記住，避免只靠 session transcript。	`memory_save` 或 `/remember`
查以前為什麼這樣做	用語意查詢，不必記得精確關鍵字。	`memory_smart_search` 或 `/recall`
接續昨天的工作	列出近期 sessions，再讓 agent 做 recap。	`memory_sessions`、`/recap`
把工作交給另一個 agent	產出可接手摘要與相關記憶。	`/handoff`
刪除不該保留的記憶	先搜尋確認，再用治理刪除，保留 audit trail。	`memory_governance_delete`、`/forget`
讓自製工具讀寫記憶	直接呼叫 REST API，不必走 MCP。	`POST /agentmemory/remember`、`POST /agentmemory/smart-search`

什麼值得存

架構決策、命名規則、部署坑、測試策略、使用者偏好、事故復盤、反覆出現的錯誤。

什麼不該存

API key、密碼、一次性 OTP、私人資料、臨時無價值的 terminal noise。敏感資料應先遮蔽。

何時開自動注入

當你已經確認 recall 品質不錯，且願意用一些 token 換 session 開頭的上下文連續性時再開。

08Config

常用設定

大部分使用者不需要 API key 就能開始。預設會跑本機記憶、BM25 搜尋與可用的本地 embedding path。

最小安全設定

如果只在本機 loopback 使用，不設 secret 也能跑。若要暴露到 LAN、reverse proxy 或雲端，請設定 bearer token。

# ~/.agentmemory/.env
AGENTMEMORY_SECRET=replace-with-your-own-secret

遠端或 sandbox MCP

當 agent 的 MCP process 不在同一個 localhost namespace，明確指定 URL。

AGENTMEMORY_URL=http://localhost:3111
AGENTMEMORY_FORCE_PROXY=1
AGENTMEMORY_PROBE_TIMEOUT_MS=3000

工具面縮小

有些 host 工具列表太長會干擾模型，可切到 core。一般情況維持預設 full server tools。

AGENTMEMORY_TOOLS=core

多 agent 分工

同一個 server 給 architect、developer、reviewer 共用時，用 AGENT_ID 標記來源。

TEAM_ID=company
USER_ID=engineering
AGENT_ID=architect
AGENTMEMORY_AGENT_SCOPE=shared

09Troubleshooting

常見卡住點

先看症狀，再檢查 server 是否在跑、MCP 是否連到 server、hooks 是否真的被 host dispatch。

Agent 只看到 7 個 tools

@agentmemory/mcp 沒連到 full server，進了 local fallback。啟動 agentmemory，確認 curl http://localhost:3111/agentmemory/livez 成功，然後重啟 agent 或重載 MCP。

Viewer 打不開

先跑 agentmemory status 看實際 Viewer URL。預設 REST 是 3111，Viewer 是 3113。若你用 --port 3112，Viewer 會變 3114。

Codex Desktop 有 MCP 但沒有自動記錄

這通常是 plugin-local hooks 沒被 Desktop dispatch。先跑 agentmemory connect codex --with-hooks，它會把 hooks mirror 到 global ~/.codex/hooks.json。

REST 回 401 或 Viewer 要 token

你設定了 AGENTMEMORY_SECRET。REST 呼叫要加 Authorization: Bearer $AGENTMEMORY_SECRET。MCP env 也要帶同一個 secret。

Port already in use

檢查 3111、3112、3113、49134。也可以用 agentmemory --instance 1 開另一組 port block。

10Reference Map

你之後會用到的文件

這些是本教學整理時實際對照的 repo 文件。若要查完整細節，從這裡跳。

完整 README

安裝、agent 支援表、MCP、Viewer、部署與 API 總覽。

開啟 README.md

Agent 安裝 runbook

給 coding agent 逐步執行的端到端安裝與驗證流程。

開啟 INSTALL_FOR_AGENTS.md

繁體中文 README

官方繁中導覽，適合先快速了解產品定位。

開啟 README.zh-TW.md

MCP tools reference

53 個 MCP tools 的參數與用途，從 source 產生。

開啟 MCP reference

REST API reference

REST endpoints 清單，包含 health、remember、smart-search、sessions。

開啟 REST reference

Config reference

環境變數、secret、URL、tools、proxy、agent scope 等設定。

開啟 config reference

Hooks reference

Claude Code plugin 的 lifecycle hook 事件表。

開啟 hooks reference

Agents reference

agentmemory connect <agent> 支援的 host 清單與協定。

開啟 agents reference

Pairings recipe

AgentMemory 如何和 codegraph、Understand Anything、Graphify 分工。

開啟 pairings.md

11Starter Prompt

給你的 AI agent 的第一段指令

當你接好 MCP 與 skills 後，可以直接把這段貼給 agent，確認它會用 AgentMemory。

請使用 AgentMemory 接續這個專案:
1. 先用 memory_smart_search 查詢這個 repo 最近的架構決策、踩坑與待辦。
2. 如果找不到，請說明目前沒有足夠記憶，不要假裝知道。
3. 做任何重要決策後，用 memory_save 保存「決策、原因、影響檔案、驗證方式」。
4. 完成一段工作後，用 memory_sessions 或 recap 整理可交接摘要。

文件產出位置: docs/agentmemory-ai-workflow-tutorial.zh-TW.html。本文件專注於如何接入工作流；完整 API 與所有工具細節以 repo 內 reference 文件為準。

卡扣 1 · Memory Server

卡扣 2 · MCP Tools

卡扣 3 · Lifecycle Hooks

卡扣 4 · Native Skills

卡扣 5 · Viewer + REST

安裝或直接用 npx 啟動

確認 server 活著

用 demo 看到第一個結果

Codex CLI / Codex Desktop

Claude Code

Cursor、Cline、Windsurf、Gemini CLI 等 MCP host

OpenCode、Hermes、OpenClaw、pi

安裝 native skills

確認 hooks 實際有接上

開啟自動注入上下文

1. Server health

2. REST save/recall round trip

3. MCP tool round trip

4. Viewer

什麼值得存

什麼不該存

何時開自動注入

最小安全設定

遠端或 sandbox MCP

工具面縮小

多 agent 分工

Agent 只看到 7 個 tools

Viewer 打不開

Codex Desktop 有 MCP 但沒有自動記錄

REST 回 401 或 Viewer 要 token

Port already in use

完整 README

Agent 安裝 runbook

繁體中文 README

MCP tools reference

REST API reference

Config reference

Hooks reference

Agents reference

Pairings recipe

參考資料

相關文件

agentmemory 全公司部署 Runbook · Neteon 共享記憶層

Auto Company 使用手冊｜在本機運行自主 AI 公司

Claude Code Dynamic Workflows｜多代理編排腳本指南 — Tenten