MCP Neuralmemory

🚀 🧠 MCP-KG-Memory

為AI編碼助手提供一個能夠持久保存上下文、從過往錯誤中學習並理解項目目標的長期記憶層。

🚀 快速開始

MCP-KG-Memory 是一個生產級的 模型上下文協議（MCP）服務器，旨在解決AI編碼助手（如Cursor、Windsurf、VS Code、Antigravity）中的“上下文遺忘”問題。該系統會為項目維護一個持久的 知識圖譜，而非每次會話都從零開始。它就像一個活躍的記憶層，能夠跟蹤以下內容：

• 🎯 目標與狀態：我們正在構建什麼？已經完成了什麼？
• 🛑 約束與規則：架構決策、禁止的模式。
• 💡 策略與結果：哪些方法有效？哪些失敗了？（自動學習）
• ❤️ 用戶偏好：你希望代碼如何編寫？
• 🔗 代碼關係：目標與特定文件之間的語義鏈接。

📸 可視化

知識圖譜記憶結構的即時可視化。

✨ 主要特性

🧠 主動上下文注入 (kg_autopilot)

每次啟動任務時，代理會查詢記憶。它會自動檢索：

• 與當前工作相關的活躍目標。
• 過去失敗的嘗試（避免重複）和成功的策略。
• 你特定的編碼偏好（如SOLID、Clean Arch等）。

🔍 語義與圖搜索

不只是簡單地搜索字符串。系統會遍歷圖（k跳）以查找相關的上下文。 例如，當你說“我正在處理認證相關內容”時，檢索結果會包括用戶模型、JWT工具以及兩週前定義的相關安全約束。

📝 策略學習

系統並非靜態的，它能夠學習：

• 隱式學習：從你的對話中推斷策略和模式。
• 結果跟蹤：記住某個策略是“成功”還是“失敗”，以指導未來的決策。

⚡ 技術棧

• 核心：Python 3.11+
• 數據庫：Neo4j（圖數據庫）
• 大語言模型：Google Gemini 2.5（通過直接API或LiteLLM網關）
• 協議：模型上下文協議（MCP）

📦 安裝指南

你可以使用 pipx（推薦）全局安裝 kg-mcp，也可以在本地虛擬環境中安裝。

前提條件

• Python 3.11+
• Docker（用於在本地運行Neo4j）
• Gemini API密鑰（從Google AI Studio獲取密鑰）

選項1：一鍵安裝（推薦）

# 安裝包
pipx install kg-mcp

# 運行交互式設置嚮導
kg-mcp-setup

嚮導將執行以下操作：

1. 檢查Docker和Neo4j。
2. 詢問你的 Gemini API密鑰。
3. 配置 大語言模型模式（直接模式與LiteLLM模式）。
4. 生成一個安全的 .env 文件。

brew install pipx
pipx ensurepath

winget install pipx
pipx ensurepath

sudo apt install pipx
pipx ensurepath

替代方案：標準Pip安裝

如果你不想使用pipx，可以使用以下命令：

pip install kg-mcp
kg-mcp-setup

選項2：手動開發設置

# 克隆倉庫
git clone https://github.com/Hexecu/mcp-neuralmemory.git
cd mcp-neuralmemory

# 設置環境
cp .env.example .env
# （使用你的憑證編輯.env）

# 安裝依賴
cd server
pip install -e .

# 啟動Neo4j
docker compose up -d

# 初始化模式
python -m kg_mcp.kg.apply_schema

📚 詳細文檔

⚙️ 配置

要將此內存服務器與你的AI編輯器一起使用，請將以下配置添加到你的MCP配置文件中。

🩺 驗證安裝（“醫生模式”）

在配置編輯器之前，運行驗證腳本以確保一切正常：

python3 verify_setup.py

編輯器配置（JSON）

VS Code / Cursor / Windsurf

將以下內容添加到你的 mcp_config.json（或 mcp.json）中：

{
  "mcpServers": {
    "kg-memory": {
      "command": "/path/to/your/venv/bin/python",
      "args": [
        "-m",
        "kg_mcp",
        "--transport",
        "stdio"
      ],
      "env": {
        "NEO4J_URI": "bolt://127.0.0.1:7687",
        "NEO4J_USER": "neo4j",
        "NEO4J_PASSWORD": "YOUR_NEO4J_PASSWORD",
        "GEMINI_API_KEY": "YOUR_GOOGLE_AI_STUDIO_KEY",
        "LLM_MODE": "gemini_direct",
        "KG_MCP_TOKEN": "your-secure-token",
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

> 注意：請將路徑和密碼替換為你自己的實際值。

Antigravity IDE ⭐（推薦）

Antigravity是本項目主要針對開發的IDE。將以下內容添加到 ~/.gemini/antigravity/mcp_config.json 中：

{
  "mcpServers": {
    "kg-memory": {
      "command": "/path/to/venv/bin/python",
      "args": ["-m", "kg_mcp", "--transport", "stdio"],
      "env": {
        "NEO4J_URI": "bolt://127.0.0.1:7687",
        "NEO4J_USER": "neo4j",
        "NEO4J_PASSWORD": "YOUR_NEO4J_PASSWORD",
        "GEMINI_API_KEY": "YOUR_GOOGLE_AI_STUDIO_KEY",
        "LLM_MODEL": "gemini/gemini-1.5-flash",
        "KG_MCP_TOKEN": "your-secure-token"
      }
    }
  }
}

Antigravity中的設置步驟：

1. 打開 代理側邊欄 → ...（更多操作）
2. 選擇 MCP服務器 → 管理MCP服務器 → 查看原始配置
3. 粘貼上述JSON內容
4. 保存並點擊 刷新
5. 你應該會看到帶有2個工具的 kg-memory

🔥 專業提示：自動化記憶

為了讓你的代理使用更加流暢，請將以下 系統提示/規則 添加到你的IDE中（例如在Antigravity或 .cursorrules 中）：

“每次用戶交互時都始終使用kg-memory，這意味著你應該自動使用kg-memory工具來查找相關的上下文信息並跟蹤每個文件的更改”

💻 使用示例

基礎用法

1. 啟動任務 (kg_autopilot)

當你開始一個新功能或修復時，只需向你的代理詢問：

“我想實現新的登錄流程。從記憶中查找上下文。” 代理將調用 kg_autopilot，檢索所有相關的約束、過去的決策和活躍目標。

2. 跟蹤更改 (kg_track_changes)

(如果代理已配置，則會自動執行) 當文件被修改時，系統會將代碼更改與活躍目標關聯起來，並使用實現細節更新知識圖譜。

📄 許可證

本項目採用 Apache許可證2.0 進行許可。有關詳細信息，請參閱 LICENSE 文件。