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 文件。