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

引言

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

pip install memory-hub
memory-hub setup

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

一、環境準備

1.1 系統要求

⚠️ 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 區域說明

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 配置未生效或路徑錯誤。

解決：

1. 確認 MCP 配置文件中 command 路徑正確
2. 重啟 AI 平台
3. 在 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 環境下的實際安裝經驗撰寫。