引言：為什麼需要 MemoryHub？
AI Agent 最大的痛點是什麼？不是模型能力不夠強，不是工具不夠多，而是——每次醒來都是空白。
無論是 OpenClaw、Claude Code、Hermes 還是 DeepSeek TUI，每個 AI 平台都面臨同一個根本問題：Session 結束後，所有對話上下文隨之消失。即便有檔案系統的 Session Log（JSONL），那也是原始數據，無法進行語義搜索、無法跨 Session 關聯、無法跨平台整合。
MemoryHub 正是為了解決這個問題而設計的——一個跨平台的持久化記憶增強系統。
一、系統全景：雙模式捕獲引擎
MemoryHub 的核心架構圍繞一個統一的 Capture Daemon 構建，支援兩種互補的捕獲模式：
AI Platforms (OpenClaw / Hermes / DeepSeek / Claude Code)
│ │
│ MODE B: File scan │ MODE A: MCP real-time
│ (每 5 分鐘增量掃描) │ (即時 via /hook)
▼ ▼
Capture Daemon (:3872) ──── Qdrant Vector DB (:6333)
│ │
Dashboard (:3872) MCP Server (stdio)
• Live feed • mem_save / mem_search
• 24h/7d charts • mem_stats / capture_send
• Global search • 4 per-platform collections
• Collection stats
Mode A — MCP 即時捕獲
當 AI Agent 調用 MCP 工具（如 mem_save）時，Capture Daemon 通過 /hook 端點即時接收捕獲數據。這是零延遲的捕獲路徑，適合需要立即保存的重要對話片段。
Mode B — 檔案系統增量掃描
Daemon 每 5 分鐘掃描四個平台的 Session 目錄，通過 offset 機制只讀取新增內容，避免重複處理。這是被動但完整的捕獲路徑，確保沒有任何對話被遺漏。
兩者互補
- Mode A 快但不完整（依賴 Agent 主動調用 MCP）
- Mode B 慢但完整（被動掃描所有 Session 文件）
- 兩者疊加 = 完整且即時的記憶捕獲系統
二、核心組件詳解
2.1 Capture Daemon（捕獲守護進程）
統一守護進程，整合四大功能：
| 功能 | 說明 | 技術細節 |
|---|---|---|
| Mode A 接收 | POST /hook 即時捕獲 |
HTTP stdlib server, DAEMON_HOOK_URL |
| Mode B 掃描 | 每 5 分鐘增量掃描 | 檔案 offset 追蹤, capture_offsets.json |
| Dashboard | Web UI 實時監控 | 6 API endpoints, 24h/7d 圖表 |
| 狀態管理 | 內存狀態 + 持久化 | capture_daemon_state.json |
2.2 四平台 Parser
每個 AI 平台使用不同的對話格式，MemoryHub 內建對應的 Parser：
| 平台 | Parser | 格式 | 特殊處理 |
|---|---|---|---|
| OpenClaw | _scan_file |
JSONL | type="message" + content blocks 提取 |
| Hermes | _scan_file |
JSONL | 逐行 role/content 解析 |
| DeepSeek TUI | _scan_deepseek_checkpoint |
JSON | messages array, tool_result/tool_use 提取 |
| Claude Code | _scan_file |
JSONL | 6 個目錄掃描, 42 個追蹤檔案 |
關鍵設計決策：DeepSeek TUI 的 tool_result 和 tool_use 區塊包含在 messages array 中，需要特殊處理才能正確提取內容——這是 v2.0 修復的核心 Bug 之一。
2.3 MCP Server
基於 JSON-RPC stdio 協議的 MCP Server，對外暴露 6 個工具：
| 工具 | 功能 | 使用場景 |
|---|---|---|
mem_save |
保存記憶到 Qdrant + 通知 daemon | 「記住這個客戶偏好」 |
mem_search |
語義相似度搜索 | 「上個月的 DD 報告在哪」 |
mem_stats |
Collection 統計資訊 | 「我們有多少條記憶」 |
mem_list_collections |
列出所有 Collection | 瀏覽記憶分類 |
mem_delete |
刪除記憶條目 | 清理過時資訊 |
capture_send |
顯式對話捕獲 | 手動觸發捕獲 |
2.4 Dashboard Web UI
內建 HTTP Server（port 3872），無需額外前端框架：
| 區域 | 顯示內容 |
|---|---|
| Stats Bar | 今日捕獲數、MCP vs 掃描比例、掃描週期、Qdrant 點數、運行時間 |
| Platform Cards | 每個平台的捕獲數量、追蹤檔案數、進度條 |
| Charts | 24 小時每小時趨勢圖 或 7 天每日趨勢圖 |
| Live Feed | 實時捕獲內容流 |
| Search | 全文搜索所有已捕獲記憶 |
三、數據流：從對話到向量記憶
完整的數據管道包含 7 個步驟：
1. 用戶與 AI Agent 對話
2. Agent Session 文件更新 (JSONL/JSON)
3. Daemon Mode B 掃描器捕獲新行 (≤5 分鐘延遲)
或 Agent 調用 MCP 工具 → Mode A 即時捕獲
4. 內容解析，提取角色 (user/assistant)
5. 保存到 ~/.memory-hub/captured/<platform>/YYYY/MM/DD.jsonl
6. 通過 BGE-m3 模型生成向量嵌入（本地推理）
7. 存入 Qdrant Collection 供語義搜索
存儲佈局
~/.memory-hub/
├── capture_daemon_state.json # 守護進程即時狀態
├── capture_offsets.json # 每個檔案的讀取偏移量
├── captured/ # 所有捕獲內容（數據源）
│ ├── openclaw/YYYY/MM/DD.jsonl
│ ├── hermes/YYYY/MM/DD.jsonl
│ ├── deepseek/YYYY/MM/DD.jsonl
│ └── claude/YYYY/MM/DD.jsonl
├── memories/ # MCP 保存的記憶
│ └── <uuid>.json
└── hooks/ # Hook 日誌
四、三層去重機制
重複捕獲是記憶系統的常見問題。MemoryHub 設計了三層去重防護：
| 層級 | 機制 | 說明 |
|---|---|---|
| Layer A | UUID5 內容哈希 | 基於內容生成確定性 UUID，相同內容 = 相同 ID |
| Layer B | Offset 增量掃描 | 只讀取上次掃描位置之後的新內容 |
| Layer C | 跨 Session 語義相似度 | 相似度 >85% 的記憶被標記為重複 |
五、十年生命週期設計
MemoryHub 不僅是「今天的記憶」，而是設計了完整的時間衰減與壓縮策略：
每日原始日誌 → 每週摘要 → 每月總結 → 年度回顧 → 十年歸檔
↓ ↓ ↓ ↓ ↓
永不刪除 關鍵事件 里程碑 年度審視 長期趨勢
核心原則：從不刪除，只壓縮。原始數據永久保留，高層級只是更精煉的視圖。
三層備份
| 層級 | 頻率 | 儲存位置 |
|---|---|---|
| hourly | 每小時 | ~/.memory-hub/backups/hourly/ |
| daily | 每日 | ~/.memory-hub/backups/daily/ |
| weekly | 每週 | ~/.memory-hub/backups/weekly/ |
六、技術棧
| 組件 | 技術選擇 | 理由 |
|---|---|---|
| 語言 | Python 3.9+ | 生態豐富，跨平台 |
| 向量數據庫 | Qdrant (Docker) | 高性能，Rust 實現，REST API |
| 嵌入模型 | BGE-m3 (本地) | 多語言支援，sentence-transformers 生態 |
| 全文索引 | SQLite | 零配置，內建 Python 支援 |
| API | HTTP (stdlib) | 零依賴，輕量級 |
| MCP | JSON-RPC stdio | 標準協議，多平台兼容 |
| 自動啟動 | launchd (macOS) / systemd (Linux) | 系統原生 |
七、與現有記憶系統的關係
MemoryHub 不是要取代 OpenClaw 的 agentmemory 或 Auto-Dream，而是作為第四層增強：
第 1 層：Session Log (JSONL) ← 系統自動保存
第 2 層：Daily Log (Markdown) ← 結構化日誌
第 3 層：MEMORY.md (長期記憶) ← Auto-Dream 整合
第 4 層：MemoryHub (向量語義) ← 跨平台搜索與關聯 🆕
第 4 層提供前三層無法實現的能力：
- 語義搜索：不是 grep 關鍵字，而是理解意圖
- 跨平台關聯：OpenClaw 的對話可以與 Claude Code 的對話關聯
- 時間旅行：快速定位「三個月前關於某個項目的討論」
結語
MemoryHub v2.0 從一個內部腳本進化為完整的 Python 套件，經歷了 v1.2（Hook 升級）→ v2.0（CLI + 套件化）的迭代。它解決了 AI Agent 最根本的記憶問題：從每次醒來的空白，到跨時間、跨平台的持久化語義記憶。
下一步的演進方向包括：多用戶支援、雲端同步、以及與 agentmemory 的更深層整合。
本文基於 MemoryHub v2.0.0（2026-05-20 發布）的實際架構撰寫。GitHub: Bryan-cmf/memory-hub