Buildautomata Memory MCP

🚀 BuildAutomata Memory MCP 服務器

BuildAutomata Memory MCP 服務器藉助模型上下文協議（MCP）為 AI 代理提供持久、可搜索的記憶系統。它能讓 AI 代理（如 Claude）擁有跨對話的持久記憶，就像給 AI 配備了一個長期記憶系統，具備語義搜索、時間版本控制、智能組織等功能。

🚀 快速開始

前提條件

• Python 3.10 及以上版本
• Claude Desktop（用於 MCP 集成）或任何兼容 MCP 的客戶端
• 可選：Qdrant 用於增強語義搜索

安裝步驟

1. 克隆此倉庫

git clone https://github.com/brucepro/buildautomata_memory_mcp.git
cd buildautomata_memory_mcp-main

2. 安裝依賴項

pip install mcp qdrant-client sentence-transformers

3. 配置 Claude Desktop 編輯 Claude Desktop 配置文件（Windows 系統路徑為 AppData/Roaming/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "buildautomata-memory": {
      "command": "python",
      "args": ["C:/path/to/buildautomata_memory_mcp_dev/buildautomata_memory_mcp.py"]
    }
  }
}

4. 重啟 Claude Desktop 完成上述步驟後，內存系統將在首次運行時自動創建其數據庫。

✨ 主要特性

核心功能

• 🧠 混合搜索：結合向量相似度（Qdrant）和全文搜索（SQLite FTS5）
• 📚 時間版本控制：每次記憶更新都會創建一個新版本，提供完整的審計跟蹤
• 🏷️ 智能衰減：重要性分數根據訪問模式隨時間衰減
• 🔄 豐富的元數據：支持類別、標籤、重要性和自定義元數據
• 💾 LRU 緩存：通過自動緩存管理實現快速重複訪問
• ⚙️ 線程安全：通過適當的鎖定實現併發操作

MCP 工具暴露

作為 MCP 服務器運行時，為 Claude 提供以下工具：

1. store_memory - 創建新記憶
2. update_memory - 修改現有記憶（創建新版本）
3. search_memories - 帶過濾器的語義 + 全文搜索
4. get_memory_timeline - 查看完整的版本歷史
5. get_memory_stats - 系統統計信息
6. prune_old_memories - 清理舊的/低重要性的記憶
7. run_maintenance - 數據庫優化

架構

┌─────────────────┐
│  Claude Desktop │
│   (MCP Client)  │
└────────┬────────┘
         │
    ┌────▼─────────────────────┐
    │  MCP Server              │
    │  buildautomata_memory    │
    └────┬─────────────────────┘
         │
    ┌────▼──────────┐
    │  MemoryStore  │
    └────┬──────────┘
         │
    ┌────┴────┬─────────────┬──────────────┐
    ▼         ▼             ▼              ▼
┌───────┐ ┌────────┐ ┌──────────┐ ┌─────────────┐
│SQLite │ │Qdrant  │ │Sentence  │ │ LRU Cache   │
│  FTS5 │ │Vector  │ │Transform │ │ (in-memory) │
└───────┘ └────────┘ └──────────┘ └─────────────┘

💻 使用示例

基礎用法

# 搜索記憶
python interactive_memory.py search "consciousness research" --limit 5

# 存儲新記憶
python interactive_memory.py store "Important discovery..." --category research --importance 0.9 --tags "ai,insight"

# 查看記憶演變
python interactive_memory.py timeline --query "project updates" --limit 10

# 獲取統計信息
python interactive_memory.py stats

高級用法

快速訪問腳本

Windows 系統：

memory.bat search "query"
memory.bat store "content" --importance 0.8

Linux/Mac 系統：

./memory.sh search "query"
./memory.sh store "content" --importance 0.8

📚 詳細文檔

使用場景

1. 持久的 AI 上下文

用戶：“記住我更喜歡詳細的技術解釋”
[記憶以類別：用戶偏好存儲]

下一次會話...
Claude：*自動回憶起偏好並提供詳細響應*

2. 項目連續性

會話 1：處理項目 A，存儲進度
會話 2：Claude 回憶起項目狀態，從上次中斷的地方繼續
會話 3：查看所有項目決策的時間線

3. 研究與學習

- 發現研究結果時進行存儲
- 按主題、重要性、來源進行標記
- 語義搜索：“我對神經網絡有哪些瞭解？”
- 查看理解隨時間的演變

4. 多工具工作流

Claude Desktop → 通過 MCP 存儲洞察
Claude Code → 通過 CLI 檢索
Cursor AI → 訪問相同的內存數據庫
= 所有工具上的統一 AI 角色

想要完整套餐？

🎁 獲取 Gumroad 套餐

Gumroad 版本包括：

• ✅ 預編譯的 Qdrant 服務器（Windows .exe，無需 Docker）
• ✅ 一鍵啟動腳本（start_qdrant.bat）
• ✅ 分步設置指南（instructions.txt）
• ✅ 商業許可證，用於商業用途
• ✅ 通過電子郵件提供優先支持

適合人群：

• 希望輕鬆設置的非技術用戶
• 想要完整堆棧套餐的 Windows 用戶
• 需要明確許可證的商業/企業用戶
• 任何重視時間而非自行設置的人

此開源版本：

• ✅ 免費用於個人/教育/小企業用途（年收入 < 10 萬美元）
• ✅ 可訪問完整源代碼
• ✅ 自行設置 Qdrant（從 qdrant.io 安裝）
• ✅ 通過 GitHub 問題獲得社區支持

兩個版本使用完全相同的核心代碼 - 您只是在便利性（Gumroad）和自行設置（GitHub）之間進行選擇。

配置

環境變量

# 用戶/代理身份
BA_USERNAME=buildautomata_ai_v012      # 默認用戶 ID
BA_AGENT_NAME=claude_assistant         # 默認代理 ID

# Qdrant（向量搜索）
QDRANT_HOST=localhost                  # Qdrant 服務器主機
QDRANT_PORT=6333                       # Qdrant 服務器端口

# 系統限制
MAX_MEMORIES=10000                     # 修剪前的最大記憶數
CACHE_MAXSIZE=1000                     # LRU 緩存大小
QDRANT_MAX_RETRIES=3                   # 重試次數
MAINTENANCE_INTERVAL_HOURS=24          # 自動維護間隔

數據庫位置

記憶存儲在以下路徑：

<script_dir>/memory_repos/<username>_<agent_name>/memoryv012.db

可選：Qdrant 設置

為了增強語義搜索（強烈推薦）：

選項 1：使用 Docker

docker run -p 6333:6333 qdrant/qdrant

選項 2：手動安裝

從 Qdrant 發佈頁面 下載。

選項 3：Gumroad 套餐

包括預編譯的 Windows 可執行文件 + 啟動腳本

不使用 Qdrant 時：系統仍可使用 SQLite FTS5 全文搜索（語義理解能力較弱）。

開發

運行測試

# 搜索測試
python interactive_memory.py search "test" --limit 5

# 存儲測試
python interactive_memory.py store "Test memory" --category test

# 統計信息
python interactive_memory.py stats

文件結構

buildautomata_memory_mcp_dev/
├── buildautomata_memory_mcp.py      # MCP 服務器
├── interactive_memory.py             # CLI 界面
├── memory.bat / memory.sh            # 輔助腳本
├── CLAUDE.md                         # 架構文檔
├── README_CLI.md                     # CLI 文檔
├── CLAUDE_CODE_INTEGRATION.md        # 集成指南
└── README.md                         # 本文件

故障排除

“Qdrant 不可用”

• 如果在不使用 Qdrant 的情況下運行，這是正常現象 - 會回退到 SQLite FTS5
• 要啟用：啟動 Qdrant 服務器並重啟 MCP 服務器

數據庫“權限被拒絕”

• 檢查 memory_repos/ 目錄的權限
• 在 Windows 上：如有需要，以管理員身份運行

Claude Desktop 未顯示工具

1. 檢查 claude_desktop_config.json 路徑是否正確
2. 驗證 Python 是否在系統路徑中
3. 完全重啟 Claude Desktop
4. 檢查 Claude Desktop → 幫助 → 查看日誌中的日誌

導入錯誤

pip install --upgrade mcp qdrant-client sentence-transformers

📄 許可證

開源（此 GitHub 版本）：

• 免費用於個人、教育和小企業用途（年收入 < 10 萬美元）
• 必須註明原作者（Jurden Bruce）
• 完整條款請參閱 LICENSE 文件

商業許可證：

• 年收入超過 10 萬美元的公司：每位用戶 200 美元或每家公司 2 萬美元（取較低者）
• 聯繫方式：sales@brucepro.net

支持

社區支持（免費）

• GitHub 問題：報告錯誤或請求功能
• 討論區：提問、分享技巧

優先支持（Gumroad 客戶）

• 電子郵件：sales@brucepro.net
• 更快的響應時間
• 設置協助
• 自定義配置幫助

路線圖

• [ ] 記憶關係圖
• [ ] 批量導入/導出
• [ ] 用於記憶管理的 Web UI
• [ ] 多模態記憶（圖像、音頻）
• [ ] 協作記憶（多用戶）
• [ ] 記憶整合/總結
• [ ] 智能自動標記

貢獻

歡迎貢獻代碼！請按以下步驟操作：

1. 分叉倉庫
2. 創建功能分支
3. 進行更改
4. 提交拉取請求

致謝

作者：Jurden Bruce 項目：BuildAutomata 年份：2025

構建工具：

• MCP - 模型上下文協議
• Qdrant - 向量數據庫
• Sentence Transformers - 嵌入
• SQLite - 持久存儲

相關鏈接

• 模型上下文協議文檔
• Qdrant 文檔
• Gumroad 套餐 - 輕鬆設置版本

如果您覺得這個倉庫有用，請給它點個 ⭐！如果您想支持開發並獲得易於安裝的版本，請考慮 Gumroad 套餐。

• 請我喝咖啡
• Ko-fi