教學

部署計畫 · DEVOPS RUNBOOK

agentmemory 全公司 共享記憶層 · 部署計畫

NETEON // OPS agentmemory · DEPLOYMENT RUNBOOK READY TO BUILD 部署計畫 · DEVOPS RUNBOOK agentmemory 全公司共享記憶層 · 部署計畫 從一台中央 hub、網路怎麼接、知識怎麼進來、到全公司每個人的 agent 怎麼上線——這份 runbook 把落地 agentmemory 需要的每一步 DevOps 都寫成可照做的動作。設備、指令、設定檔、治理...

從一台中央 hub、網路怎麼接、知識怎麼進來、到全公司每個人的 agent 怎麼上線——這份 runbook 把落地 agentmemory 需要的每一步 DevOps 都寫成可照做的動作。設備、指令、設定檔、治理、上線節奏，一次到位。

rohitg00/agentmemory
星標
20.1K
分支
1.7K
授權
—
資料截至
閱讀時間
11 分
更新日期
開啟原始報告
拓撲
中央 hub ＋ 各端 spoke
Phase 1 設備
現有 Mac mini
Phase 2 設備
自控 VPS（Coolify）
連線
Tailscale 私網
本頁章節

01TL;DR原稿 §00

一眼看懂這份計畫

Deployment Decision

  • 設備 → 先用你的 Mac mini，量產再遷小型 VPS

  • 拓撲 → 一台中央 hub 存共享記憶，各人 agent 連上來

  • 連線 → Tailscale 私網，不曝露公網

  • 知識入庫 → Hermes 擷取 ＋ 治理閘門 ＋ REST 寫入

agentmemory 原本是「每個開發者本機一台」的設計。要變成全公司共用的知識庫，我們把它架成 hub-and-spoke：一台中央 hub 持有共享命名空間（business knowledge 進這裡、所有人的 agent 查這裡），每個人的 Claude Code / OpenClaw / Hermes 當 spoke 連上來。這用的是它的 team 模式 ＋ bearer 驗證，能跑，但屬於「非預設用法」，所以計畫刻意採先試點、再全公司的節奏。

02TARGET TOPOLOGY原稿 §01

目標架構：hub-and-spoke

單一「真相來源」比全網狀（mesh）更適合公司知識庫。中央 hub 是那個真相來源；個人端可自行選擇要不要另跑本機記憶。

目標拓撲

  1. CENTRAL HUB · 共享記憶

    agentmemory Hub

    • TEAM 共享命名空間 · SQLite＋本地向量 · 稽核／來源／快照 · 綁 0.0.0.0（僅限 Tailscale 私網）· :3111

  2. ▲ 讀取共享知識 │ 寫入（經治理閘門）▼

  3. SPOKE · 擷取

    Hermes 擷取代理

    • 從 Email／簡報／會議記錄擷取 → 治理閘門 → 寫入 hub

  4. SPOKE · 消費

    各人 Claude Code

    • MCP 指向 hub；查共享＋帶自己的 USER_ID 私有

  5. SPOKE · 消費

    OpenClaw／其他 agent

    • 同一段 MCP 設定，全公司共用一份記憶

03HARDWARE DECISION原稿 §02

設備選擇：Mac mini vs VPS

agentmemory 極輕——零外部資料庫（SQLite ＋ 記憶體向量索引），本地 embedding 跑 CPU 就好。所以「要多強的機器」不是重點，**「always-on、網路穩、能備份、資料在你手上」**才是。

考量Mac mini（你現有）小型 VPS（自控）
上線速度最快——機器已在跑（pmset 關睡眠＋tmux）需開機／設定，約半天
資料主權100% 在你辦公室你租的機器，root 在你手上
成本零額外成本約 US$12–24/月（2 vCPU / 4–8GB）
可靠度綁辦公室電力／網路；停電即停資料中心級 uptime、獨立於辦公室
對外端點需 Tailscale 才穩定可達固定 IP／DNS，Tailscale 亦可
備份需自建（Time Machine／rsync）快照＋磁碟備份易自動化
維運介面tmux／launchd 手動Coolify＝自架 PaaS UI，重啟／log／備份一鍵
建議Phase 1 試點：就用它，最快驗證價值Phase 2 量產：遷過去當公司正式服務

Phase 1 · Mac mini

  • 沿用你現有設定：pmset 關睡眠、tmux 常駐 session。

  • Node.js ≥ 20；裝 iii-engine v0.11.2（macOS arm64 二進位）。

  • 用 launchd 讓 hub 開機自啟、掛掉自動重拉。

  • Tailscale 讓團隊在私網內連到它，不動防火牆、不曝露公網。

Phase 2 · VPS 規格

  • 2 vCPU / 4 GB RAM / 60–80 GB SSD 已足（零外部 DB）。

  • 要本地 embedding ＋ LLM 壓縮較從容 → 升到 8 GB。

  • Ubuntu 22.04/24.04；裝 Docker → 用 Coolify 跑同一套 compose stack。

  • 供應商挑你偏好的（Hetzner／DO／Vultr…），重點是你能拿到 root。

04STAND UP THE HUB原稿 §03

建置中央 hub（逐步）

3.1 安裝 runtime 與 agentmemory。需要 Node ≥ 20，以及 iii-engine（原生二進位，agentmemory 目前鎖定 v0.11.2——別自行升級，它還沒為新版 sandbox 模型重構）。

hub · install（macOS arm64 範例）

bash
# 1) iii-engine v0.11.2（Mac mini arm64）
mkdir -p ~/.local/bin
curl -fsSL https://github.com/iii-hq/iii/releases/download/iii/v0.11.2/iii-aarch64-apple-darwin.tar.gz \
  | tar -xz -C ~/.local/bin && chmod +x ~/.local/bin/iii
iii --version   # 應印出 0.11.2

# 2) agentmemory（全域安裝，之後 bare 指令到處可用）
npm install -g @agentmemory/agentmemory

# 3) 本地 embedding（免費、離線、資料不外流）＋ 繁中斷詞（必裝）
npm install -g @xenova/transformers
npm install -g @node-rs/jieba tiny-segmenter   # 中日韓斷詞，繁中檢索品質關鍵

**3.2 設定檔 ~/.agentmemory/.env。**這是 hub 的核心設定。共享 hub 一定要開驗證（AGENTMEMORY_SECRET），並用你的 OpenRouter 把壓縮 LLM 路由到便宜模型（呼應你 OpenClaw 的分層路由思路）。

~/.agentmemory/.env

dotenv
# ── 驗證（共享 hub 必填）──
AGENTMEMORY_SECRET=<openssl rand -hex 32 產生的長字串>

# ── Port（預設即可）──
III_REST_PORT=3111

# ── Embedding：本地、免費、離線 ──
EMBEDDING_PROVIDER=local

# ── LLM 壓縮／摘要：走你的 OpenRouter，路由便宜模型 ──
OPENROUTER_API_KEY=<你的 key>
AGENTMEMORY_AUTO_COMPRESS=true    # 要壓縮才開；活躍寫入會有 token 花費

# ── Team：共享 ＋ 私有命名空間 ──
TEAM_ID=neteon
# USER_ID 由各使用者「端」帶入（見 §06），hub 端不寫死
# TEAM_MODE 可用值以你安裝版本的 `agentmemory doctor` / 文件為準

# ── 治理／運維 ──
GRAPH_EXTRACTION_ENABLED=true    # 開知識圖譜抽取
CONSOLIDATION_ENABLED=true
LESSON_DECAY_ENABLED=true
SNAPSHOT_ENABLED=true       # git 版本化快照，可回溯／diff
AGENTMEMORY_TOOLS=all        # 開滿 51 個 MCP 工具（含治理類）

3.3 啟動與冒煙測試。

hub · smoke test

bash
agentmemory            # 啟動 hub（REST :3111 / viewer :3113）
agentmemory doctor     # 互動式診斷，確認 engine／embedding／team 設定
agentmemory demo       # 灌入樣本資料，驗證語意檢索真的會動

curl http://localhost:3111/agentmemory/health   # 應回 ok（此端點永遠公開）
open http://localhost:3113                       # viewer：看記憶即時長出來

**3.4 常駐化。**hub 是公司服務，要開機自啟、掛掉自動重起。

Mac mini · launchd

  • 寫一個 ~/Library/LaunchAgents/net.neteon.agentmemory.plist，KeepAlive=true、RunAtLoad=true。

  • launchctl load 後即背景常駐；比 tmux 更適合正式服務。

  • log 導到 ~/.agentmemory/hub.log 方便排錯。

VPS · Coolify / compose

  • Coolify 內新增 Resource → 指到 repo 的 deploy/coolify 藍圖。

  • 同一套 Docker Compose（拉 iiidev/iii:0.11.2），持久卷掛 /data。

  • 容器內只發布 3111；重啟／log／備份都在 Coolify UI。

05NETWORKING & HARDENING原稿 §04

連線與資安

預設 agentmemory 只綁 127.0.0.1。要讓全公司連到，首選不是開防火牆，而是拉一張私網。

首選：Tailscale 私網

  • hub 與每位同事都加入同一個 tailnet；hub 只在私網內可達，公網零曝露。

  • 大家連的是 http://memory-hub.<tailnet>.ts.net:3111，跨 Mac／Win／Linux 一致。

  • 用 Tailscale ACL 限定只有特定裝置能碰 :3111——網路層就先擋一道。

  • 最適合小公司：免憑證申請、免反向代理，最快落地。

替代：反向代理 ＋ TLS

  • VPS 上用 Caddy／nginx 前擋，自動 Let's Encrypt 憑證。

  • 只把 :3111 經 TLS 對外；務必疊 AGENTMEMORY_SECRET bearer 驗證。

  • 適合已有網域／要對外正式端點時；比 Tailscale 多一層維運。

資安硬化清單（上線前逐條打勾）：

  • 未完成：

    設定強 AGENTMEMORY_SECRET：openssl rand -hex 32；所有受保護端點都要 bearer。

  • 未完成：

    API 綁定範圍：只在 Tailscale／VPN 或 TLS 反代之後綁 0.0.0.0；絕不裸奔公網。

  • 未完成：

    viewer / console loopback-only：:3113、:3114 不對外。

  • 未完成：

    隱私過濾已內建：寫入前自動剝除密鑰／API key／<private> 標籤——但仍要疊你自己的「可入庫政策」（見 §05）。

  • 未完成：

    備份 /data：SQLite ＋ 索引都在這；每日快照＋異地備份。

  • 未完成：

    鎖版本：iii-engine 維持 v0.11.2，別跟著上游盲升；升級走 §07 的流程。

  • 未完成：

    定期輪替 secret：搭配 deploy 範本產生的 HMAC，一季輪替一次。

06INGESTION PIPELINE原稿 §05

知識怎麼進來：擷取 ＋ 治理閘門

這是把你原始構想落地的關鍵。agentmemory 的自動 hook 是為「coding session」設計的；你要的**商業知識（Email／簡報／會議）**走的是它的 REST／MCP 寫入路徑。用你既有的 Hermes 排程當擷取代理，最順。

  1. SRC · 來源

    Email、簡報、會議記錄——知識交換的現場。

  2. EXT · Hermes 擷取代理

    排程跑 claude -p 讀原文，抽出候選事實（誰、什麼、何時、來源）。

  3. GATE · 治理閘門（你定政策）

    去識別（內建）＋ 來源／信心標記 ＋ 存取分級 ＋ 寫入審核。機制 agentmemory 給，政策你定。

  4. HUB · 寫入 hub 共享命名空間

    經 /agentmemory/remember 落地，帶上 facet 標籤供日後分級檢索。

寫入範例（示意——實際欄位以 src/triggers/api.ts 的 schema 為準；用 memory_facet_tag 打 dept／confidentiality 維度標籤）：

ingest · POST /agentmemory/remember

bash
curl -X POST http://memory-hub.<tailnet>.ts.net:3111/agentmemory/remember \
  -H "Authorization: Bearer $AGENTMEMORY_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "project": "neteon-shared",
    "content": "Moxa 於 2026 Q2 將 Neteon 升為 Gold Partner，適用北美區。",
    "source": "2026-04 業務週會記錄",
    "facets": { "dept": "sales", "confidentiality": "internal" }
  }'

07PER-EMPLOYEE ONBOARDING原稿 §06

全公司上線：每個人怎麼接

對使用者來說，接上 hub 就是在他們 agent 的 MCP 設定裡貼一段，把 AGENTMEMORY_URL 指向 hub、帶上自己的 USER_ID。同一段設定，跨所有 agent 通用。

各 agent 通用 · mcpServers 區塊

json
{
  "mcpServers": {
    "agentmemory": {
      "command": "npx",
      "args": ["-y", "@agentmemory/mcp"],
      "env": {
        "AGENTMEMORY_URL": "http://memory-hub.<tailnet>.ts.net:3111",
        "AGENTMEMORY_SECRET": "<hub 的 secret>",
        "USER_ID": "hubert"
      }
    }
  }
}

Claude Code

  • /plugin marketplace add rohitg00/agentmemory → /plugin install agentmemory。

  • 自動註冊 12 hooks ＋ 4 skills ＋ MCP，並把 AGENTMEMORY_URL 指向 hub。

  • 驗證：curl .../agentmemory/health。

OpenClaw

  • 把上面 mcpServers 區塊併進 OpenClaw MCP 設定。

  • 要更深整合：複製 integrations/openclaw 到 ~/.openclaw/extensions/agentmemory，設 plugins.slots.memory = "agentmemory"。

Hermes

  • ~/.hermes/config.yaml 加 mcp_servers.agentmemory ＋ memory.provider: agentmemory。

  • 要 6-hook 深整合：複製 integrations/hermes 到 ~/.hermes/plugins/agentmemory。

08GOVERNANCE & OPERATIONS原稿 §07

治理與日常運維

治理工具（開箱）

  • memory_audit / /agentmemory/audit：所有操作的稽核軌跡。

  • memory_verify：任一記憶回溯到來源觀察，追 provenance。

  • memory_governance_delete：帶稽核的刪除（符合遺忘權）。

  • memory_snapshot_create：git 版本化快照，可回滾／diff。

排程與監控

  • iii worker add iii-cron：夜間固化、每週快照、衰減掃描。

  • 用你既有的 Hermes cron 跑每日擷取 ＋ 記憶健檢。

  • iii console（:3114，走 tunnel）：OTEL trace 看每次檢索的 BM25→向量→RRF 瀑布。

  • memory_diagnose / memory_heal：健檢與自動修復卡住狀態。

備份與升級

  • 未完成：

    每日備份 /data（Mac mini：rsync 到 NAS／雲；VPS：Coolify 快照＋磁碟備份）。

  • 未完成：

    升級走 staging：agentmemory upgrade 會變動 runtime，先在測試機驗證再上正式。

  • 未完成：

    engine 版本鎖定：維持 iii-engine v0.11.2，直到 agentmemory 官方解除 pin。

  • 未完成：

    還原演練：每季用快照做一次還原演練，確認備份真的能救。

09PHASED ROLLOUT原稿 §08

分階段上線節奏

  1. P0 · 第 1 週 · 你自己 · hub 起來

    Mac mini 上把 §03 走完：安裝、.env、繁中斷詞、secret、Tailscale、常駐化、冒煙測試。一台能通的 hub。

  2. P1 · 第 2–3 週 · 擷取 · 接一個知識源

    先接會議記錄一種來源，用 Hermes 擷取＋治理閘門＋寫入 neteon-shared。驗證「進得去、查得到、來源可追」。

  3. P2 · 第 3–5 週 · 試點團隊 · 3–5 人接上 hub

    把試點同仁的 Claude Code／OpenClaw／Hermes 指向 hub。重點觀察多人同時寫入時的命名空間隔離與矛盾處理。

  4. P3 · 第 5–7 週 · 治理定案 · 政策成文

    訂共享 vs 私有、寫入審核、依部門／機密級的存取分級；用 audit＋verify 落實 provenance；開快照。

  5. P4 · 第 7 週後 · 全公司 · 自助上線 ＋ 遷 VPS

    發一頁 onboarding（就是 §06 那段設定），同仁自助接入；同時把 hub 遷到自控 VPS 當正式服務。

10RISKS & GUARDRAILS原稿 §09

風險與護欄

pre-1.0 成熟度

  • agentmemory 仍在 v0.9.x、單一主維護者。護欄：鎖版本、開快照、每日備份、升級走 staging。

  • 試點階段就把「備份能還原」演練過，別等出事。

hub 模式屬非預設用法

  • 它本是本機單人設計；多人中央共享靠 team＋auth 撐。護欄：P2 專門壓測多人寫入的隔離與矛盾。

  • 先小規模驗證再放大，別一次全公司。

iii 引擎依賴

  • 綁較新的 iii（鎖 v0.11.2）。護欄：不盲升；關注上游；必要時 Docker 版隔離。

單點故障

  • 單 hub 掛了全公司無記憶。護欄：常駐自啟＋監控；量產後評估 iii-pubsub 雙 hub。

**資料來源：**rohitg00/agentmemory 官方 README 與 deploy/、src/triggers/api.ts（查證於 2026/07，對應 v0.9.18 / iii-engine v0.11.2）；iii-hq/iii releases。

**注意：**agentmemory 為 pre-1.0，指令、環境變數與端點 schema 可能隨版本變動；上線前以你安裝版本的 agentmemory doctor 與 repo 內文件為準。部分寫入 payload 欄位為示意，實際以 api.ts 為準。