🧠 Vector Memory — AI Agent 向量記憶系統

讓你的 AI Agent 永遠不會失憶。獨立安裝，一行指令。

基於 Qdrant + BGE-m3 + MCP 協議的本地向量記憶系統。 支援 OpenClaw、Claude Code、Hermes Agent 及任何支援 MCP 的 AI Agent。

---

📐 架構

┌──────────────────────────────────────────────────────┐
│                 向量記憶系統 v2.0                       │
├──────────────────────────────────────────────────────┤
│                                                      │
│  AI Agents                          Qdrant           │
│  ┌──────────┐    MCP (stdio)    ┌──────────────┐    │
│  │ OpenClaw │───────→ ←────────│ localhost:6333│    │
│  ├──────────┤                   │              │    │
│  │ Hermes   │                   │ openclaw_mem  │    │
│  ├──────────┤                   │ hermes_mem    │    │
│  │ Claude   │                   │ shared_mem    │    │
│  │  Code    │                   │ deepseek_mem  │    │
│  └──────────┘                   │ claude_mem    │    │
│       │                         └──────────────┘    │
│       │ BGE-m3 (1024-dim)              ↑             │
│       │ Apple MPS 加速                  │             │
│       └────────────────────────────────┘             │
│                                                      │
│  自動化層                                              │
│  ┌──────────────────────────────────────────────┐    │
│  │ auto_sync.py      每小時增量同步               │    │
│  │ guard.sh          每分鐘存活監控               │    │
│  │ consistency_check  每天 04:00 雙系統一致性     │    │
│  │ morning_brief.py   每天 08:00 記憶摘要         │    │
│  │ qdrant_backup.py   每週備份 + 每月緊湊化       │    │
│  │ sync_watcher.py    事件驅動同步守護             │    │
│  └──────────────────────────────────────────────┘    │
└──────────────────────────────────────────────────────┘

---

🚀 一行安裝

curl -sSL https://raw.githubusercontent.com/Bryan-cmf/vector-memory/main/setup.sh | bash

或手動：

git clone https://github.com/Bryan-cmf/vector-memory.git
cd vector-memory
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

前置條件

• Python 3.11+
• Docker (Qdrant)
• Apple Silicon 推薦（MPS 加速），Intel 也支援（CPU）

---

⚡ 快速啟動

# 1. 啟動 Qdrant
docker run -d -p 6333:6333 \
  -v ~/qdrant_storage:/qdrant/storage \
  qdrant/qdrant

# 2. 啟動 MCP Server
cd ~/Desktop/Projects/vector-memory
source .venv/bin/activate
python mcp_server.py

---

🔌 Agent 配置

OpenClaw

// openclaw.json → mcp.servers
{
  "vector-memory": {
    "command": "/path/to/vector-memory/.venv/bin/python",
    "args": ["/path/to/vector-memory/mcp_server.py"],
    "env": {
      "EMBEDDING_MODEL": "BAAI/bge-m3",
      "QDRANT_URL": "http://localhost:6333"
    }
  }
}

Claude Code

// .claude.json → mcpServers
{
  "vector-memory": {
    "command": "python",
    "args": ["path/to/mcp_server.py"]
  }
}

Hermes Agent

# ~/.hermes/config.yaml
mcp:
  servers:
    vector-memory:
      command: python
      args: ["~/Desktop/Projects/vector-memory/mcp_server.py"]

---

🛠️ MCP 工具

工具	功能	範例
mem_save	保存記憶	mem_save(content="今日會議...", tags=["會議","估值"])
mem_search	語義搜索	mem_search(query="上週的盡調報告", limit=5)
mem_list_collections	列出集合	mem_list_collections()
mem_delete	刪除記憶	mem_delete(collection="openclaw_mem", point_id="...")
mem_stats	統計信息	mem_stats(collection="openclaw_mem")
mem_health	健康報告	mem_health()
mem_decay	記憶衰減	mem_decay(collection="openclaw_mem", dry_run=true)
mem_dedup	語義去重	mem_dedup(threshold=0.92, dry_run=true)
mem_graph	知識圖譜	mem_graph(collection="openclaw_mem")
mem_contradict	矛盾檢測	mem_contradict(content="新記憶...")
mem_time_travel	時光回溯	mem_time_travel(date="2026-05-01", query="...")
mem_federated	跨集合搜索	mem_federated(query="...", limit=10)

---

📊 Collections（多租戶隔離）

Collection	用途	條目數
openclaw_mem	OpenClaw/UltraClaw 記憶	10,131
hermes_mem	Hermes Agent 記憶	35+
deepseek_mem	DeepSeek TUI 記憶	394
claude_mem	Claude Code 記憶	290
shared_mem	跨 Agent 共享知識	—

---

🔧 自動化 Cron 設定

# 增量同步（每小時）
0 * * * * /path/to/.venv/bin/python auto_sync.py >> /tmp/auto_sync.log 2>&1

# 存活監控（每分鐘）
* * * * * /bin/bash guard.sh

# 一致性檢查（每天 04:00）
0 4 * * * /path/to/.venv/bin/python consistency_check.py >> /tmp/consistency.log 2>&1

# 每日摘要（每天 08:00）
0 8 * * * /path/to/.venv/bin/python morning_brief.py >> /tmp/morning_brief.log 2>&1

# 每週備份（週日 03:00）
0 3 * * 0 /path/to/.venv/bin/python qdrant_backup.py >> /tmp/qdrant_backup.log 2>&1

# 每月緊湊化（1 日 03:30）
30 3 1 * * /path/to/.venv/bin/python qdrant_backup.py --optimize >> /tmp/qdrant_backup.log 2>&1

---

📈 當前統計（Production · 2026-06-15）

指標	數值
總向量數	10,131
向量維度	1024 (BGE-m3)
距離函數	Cosine
嵌入模型	BAAI/bge-m3
硬體加速	Apple MPS
記憶體使用	~2 GB（含模型）
平均搜尋延遲	~0.5 秒
集合數	5

---

🗂️ 文件結構

vector-memory/
├── mcp_server.py          ← MCP 服務器主程式 (42KB)
├── memory_utils.py        ← 記憶核心工具 (Qdrant CRUD)
├── auto_sync.py           ← 增量同步引擎
├── batch_import.py        ← 批量導入工具
├── consistency_check.py   ← 雙系統一致性檢查
├── sync_watcher.py        ← 事件驅動同步守護
├── memory_preload.py      ← 記憶預載入
├── morning_brief.py       ← 每日記憶摘要
├── qdrant_backup.py       ← 備份 + 緊湊化
├── dashboard.py           ← CLI Dashboard
├── guard.sh               ← 存活監控
├── memory_check.sh        ← 系統檢查
├── setup.sh               ← 一鍵安裝
├── start.sh               ← 快速啟動
├── docker-compose.yml     ← Qdrant 部署
├── requirements.txt       ← Python 依賴
├── tests/
│   └── test_basic.py
└── README.md

---

📄 相關資源

• Agentic Infrastructure 十件套 — 完整 AI Agent 基礎設施
• MemoryHub Dashboard — 記憶可視化 Dashboard
• MCP 協議 — Model Context Protocol

---

📜 License

MIT © 2026 Bryan Chan · 君澤智庫

---

讓 AI Agent 記住一切，永遠不會失憶。