MemoryHub 實戰安裝與使用完全指南：從零到四平台自動記憶捕獲 | Agentic Research

引言

MemoryHub 的安裝過程只需兩條指令：

pip install memory-hub
memory-hub setup

但在實際部署中，你會遇到各種環境差異：Docker 配置、Python 版本、MCP 設定、自動啟動配置等。本文基於在 Mac Studio (M3 Ultra) 上的真實安裝經驗，記錄從零到完整運行的每一個步驟。

一、環境準備

1.1 系統要求

項目	最低要求	推薦配置
操作系統	macOS 12+ / Linux (kernel 5.x+)	macOS 14+ / Ubuntu 22.04+
Python	3.9+	3.12
記憶體	8GB	16GB+（BGE-m3 嵌入需要 ~2GB）
磁盤	2GB 可用空間	10GB+（含 Qdrant 數據）
Docker	Docker Desktop / Docker Engine	最新穩定版

⚠️ Python 版本注意：Chroma 在 Python 3.14 上存在兼容性問題。如果你使用 Python 3.14，建議選擇 LanceDB 或僅使用 Qdrant。

1.2 Docker 安裝（Qdrant 所需）

macOS：

brew install --cask docker
# 啟動 Docker Desktop，等待引擎就緒

Linux (Ubuntu)：

curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER
# 重新登錄使權限生效

1.3 驗證 Qdrant 容器

# 啟動 Qdrant
docker run -d -p 6333:6333 -p 6334:6334 \
  -v qdrant_storage:/qdrant/storage \
  --name mh-qdrant \
  qdrant/qdrant

# 驗證健康狀態
curl http://localhost:6333/health
# 預期輸出: {"title":"healthz","version":"..."}

二、安裝 MemoryHub

2.1 一鍵安裝

pip install memory-hub

如果 pip install memory-hub 在 PyPI 找不到（新套件），使用 GitHub 直裝：
pip install git+https://github.com/Bryan-cmf/memory-hub.git

2.2 互動式設定嚮導

memory-hub setup

安裝器會引導你完成六個階段：

Phase 1: Environment Check
  → 檢測 Python, pip, Docker, git
  → 檢測已安裝的 AI 平台

Phase 2: Core Components (自動安裝)
  → Qdrant (Docker) — 向量搜索
  → SQLite — 全文索引
  → MemoryHub daemon + Dashboard

Phase 3: Optional Backends (互動選擇)
  → [x] Qdrant (推薦，已選)
  → [ ] Chroma (pip, 無 Docker)
  → [ ] LanceDB (pip, 嵌入式)
  → [ ] SQLite-vec (輕量向量)
  → [ ] FAISS (GPU 加速)
  → [ ] Redis Stack (高並發)
  → [ ] PostgreSQL+pgvector (全功能)
  → [ ] Elasticsearch (混合搜索)
  → [ ] MongoDB Atlas (雲端)
  → [ ] Neo4j (圖數據庫)
  → Press Enter to skip

Phase 4: MCP Configuration
  → 為已檢測平台自動寫入 MCP 配置

Phase 5: Verification
  → 檢查所有組件狀態

Phase 6: Start daemon
  → 是否立即啟動守護進程？

2.3 手動啟動

# 啟動（默認端口 3872）
memory-hub start

# 自定義端口
memory-hub start --port 3880

# 查看狀態
memory-hub status

# 停止
memory-hub stop

三、MCP 四平台配置

MCP (Model Context Protocol) 是 MemoryHub 與 AI 平台之間的橋樑。配置完成後，AI Agent 將擁有記憶工具。

3.1 OpenClaw

在 OpenClaw 的 MCP 配置中添加：

{
  "mcpServers": {
    "memory-hub": {
      "command": "python3",
      "args": ["-m", "memory_hub.server.mcp_server"],
      "env": {
        "DAEMON_HOOK_URL": "http://localhost:3872/hook",
        "QDRANT_URL": "http://localhost:6333"
      }
    }
  }
}

AI Agent 重啟後可用工具：mem_save、mem_search、mem_stats、capture_send

3.2 Hermes

{
  "mcpServers": {
    "memory-hub": {
      "command": "python3",
      "args": ["-m", "memory_hub.server.mcp_server"],
      "env": {
        "DAEMON_HOOK_URL": "http://localhost:3872/hook",
        "QDRANT_URL": "http://localhost:6333"
      }
    }
  }
}

3.3 DeepSeek TUI

{
  "mcpServers": {
    "memory-hub": {
      "command": "python3",
      "args": ["-m", "memory_hub.server.mcp_server"],
      "env": {
        "DAEMON_HOOK_URL": "http://localhost:3872/hook",
        "QDRANT_URL": "http://localhost:6333"
      }
    }
  }
}

3.4 Claude Code

Claude Code 的 MCP 配置需要額外的路徑設定：

{
  "mcpServers": {
    "memory-hub": {
      "command": "python3",
      "args": ["-m", "memory_hub.server.mcp_server"],
      "env": {
        "DAEMON_HOOK_URL": "http://localhost:3872/hook",
        "QDRANT_URL": "http://localhost:6333"
      }
    }
  }
}

💡 配置技巧：安裝器的 Phase 4 會自動檢測你已安裝的平台，並生成對應的 MCP 配置片段。你只需要複製粘貼到對應的配置文件中。

四、Dashboard 使用指南

4.1 打開 Dashboard

open http://localhost:3872

4.2 Dashboard 區域說明

區域	顯示內容	如何使用
Stats Bar	今日捕獲數、MCP vs Scan、Qdrant 點數、運行時間	快速健康檢查
Platform Cards	每平台捕獲數、追蹤檔案數	確認各平台是否正常捕獲
24h Chart	每小時捕獲趨勢	了解對話活躍時段
7d Chart	每日捕獲趨勢	了解長期使用模式
Live Feed	實時捕獲流	確認捕獲內容是否正確
Search	全文搜索	查找特定對話或記憶

4.3 讀懂數據

今日 Stats:
  Captures: 247  ← 今日捕獲總數
  MCP: 12       ← 通過 MCP 工具即時捕獲
  Scan: 235     ← 通過檔案掃描捕獲
  Cycles: 58    ← 掃描週期數（每 5 分鐘一次）
  Points: 1247  ← Qdrant 中向量總數
  Uptime: 3h    ← 守護進程運行時間

MCP 數量少是正常的：大多數捕獲來自 Mode B 被動掃描
Scan 數量在重啟後歸零：offset 機制會從上次位置繼續，不會重複計數
平台卡片顯示 0：可能在重啟後尚未有新的對話——等待幾分鐘後會有新的掃描

4.4 搜索技巧

# 精確短語
"客戶偏好"

# 按專案過濾（如果標記了）
project:cellfie

# 按日期過濾
2026-05

# 組合搜索
2026-05 project:cellfie "盡職調查"

五、命令行工具完整參考

5.1 核心命令

# 互動式安裝
memory-hub setup

# 啟動守護進程
memory-hub start              # 默認端口 3872
memory-hub start --port 3880  # 自定義端口

# 狀態檢查
memory-hub status

# 停止守護進程
memory-hub stop

# 健康驗證
memory-hub verify
# 檢查項目: Qdrant / Daemon / Dashboard / MCP / Files / 4 platform configs

# 備份記憶
memory-hub backup --tier hourly    # 每小時備份
memory-hub backup --tier daily     # 每日快照
memory-hub backup --tier weekly    # 每週存檔

5.2 常用場景

場景 1：首次安裝

pip install memory-hub
memory-hub setup      # 跟隨嚮導
memory-hub start      # 啟動
memory-hub verify     # 驗證

場景 2：日常檢查

memory-hub status     # 快速檢查
open http://localhost:3872  # 打開 Dashboard

場景 3：故障排查

memory-hub stop       # 停止
memory-hub verify     # 診斷問題
memory-hub start      # 重啟

場景 4：數據遷移

memory-hub backup --tier weekly  # 備份數據
# 在新機器上
memory-hub setup
# 恢復備份文件到 ~/.memory-hub/

六、自動啟動配置

6.1 macOS (launchd)

# 複製 LaunchAgent 配置
cp ~/.memory-hub/scripts/com.memoryhub.capture-daemon.plist \
   ~/Library/LaunchAgents/

# 載入並啟動
launchctl load ~/Library/LaunchAgents/com.memoryhub.capture-daemon.plist

# 驗證
launchctl list | grep memoryhub

守護進程會在系統啟動時自動運行，crash 後自動重啟。

6.2 Linux (systemd)

sudo cp ~/.memory-hub/scripts/systemd/memoryhub-capture-daemon.service \
        /etc/systemd/system/
sudo systemctl enable --now memoryhub-capture-daemon

# 驗證
sudo systemctl status memoryhub-capture-daemon

七、常見問題排查

Q1: Dashboard 打開後一片空白

原因：可能端口衝突或守護進程未啟動。

# 檢查進程
pgrep -f capture_daemon

# 檢查端口
lsof -i :3872

# 重啟
memory-hub stop && memory-hub start

Q2: 平台卡片一直顯示 0

原因：Mode B 掃描需要實際發送對話才會增加計數。

解決：發送幾條測試消息，等待 5 分鐘（掃描週期），查看 Dashboard 更新。

Q3: Qdrant 連接失敗

# 檢查 Docker
docker ps | grep qdrant

# 重啟 Qdrant
docker restart mh-qdrant

# 檢查健康
curl http://localhost:6333/health

Q4: MCP 工具在 AI Agent 中不可用

原因：MCP 配置未生效或路徑錯誤。

解決：

確認 MCP 配置文件中 command 路徑正確
重啟 AI 平台
在 AI 對話中測試：mem_stats 是否可用

Q5: Python 3.14 安裝 Chroma 失敗

解決：

# 方案 A：降級 Python
# 方案 B：改用 LanceDB
pip install lancedb
# 安裝器中選擇 LanceDB 而非 Chroma

Q6: Docker 未運行

# macOS
open -a Docker
# 等待 Docker Desktop 完全啟動

# Linux
sudo systemctl start docker

八、性能優化建議

8.1 嵌入模型選擇

MemoryHub 默認使用 BGE-m3，這是一個多語言模型，在中文場景表現優秀。如果你的場景完全是英文，可以考慮切換到更輕量的模型：

# 在 ~/.memory-hub/config.json 中修改
{
  "embedding_model": "BAAI/bge-small-en-v1.5"
}

8.2 Qdrant 調優

# 為 Qdrant 分配更多記憶體
docker run -d -p 6333:6333 \
  --memory 4g \
  -v qdrant_storage:/qdrant/storage \
  qdrant/qdrant

8.3 掃描頻率調整

# 在 ~/.memory-hub/config.json 中修改
{
  "scan_interval_seconds": 300  # 默認 5 分鐘，最低 60 秒
}

九、卸載

# 停止守護進程
memory-hub stop

# 移除 Qdrant
docker rm -f mh-qdrant

# 移除數據（可選）
rm -rf ~/.memory-hub

# 卸載套件
pip uninstall memory-hub -y

# 移除 LaunchAgent (macOS)
launchctl unload ~/Library/LaunchAgents/com.memoryhub.capture-daemon.plist
rm ~/Library/LaunchAgents/com.memoryhub.capture-daemon.plist

結語

MemoryHub 的設計理念是「兩條指令，五分鐘運行」。從 pip install 到 Dashboard 看到第一條捕獲，整個過程不應超過十分鐘。

如果你在安裝過程中遇到任何問題，可以查閱官方文檔：

GitHub: Bryan-cmf/memory-hub
問題回報：GitHub Issues
完整文檔：memory-hub/docs/

讓你的 AI Agent 不再遺忘，從 MemoryHub 開始。🧠

本文基於 MemoryHub v2.0.0（2026-05-20）在 Mac Studio M3 Ultra / macOS 15 / Python 3.12 環境下的實際安裝經驗撰寫。

引言