Integration Guide

Guide to integrating NeuralMind with MCP tools, graphify, and other development workflows.

Table of Contents

• How Agents Share Memory (v0.6.0+)
• Graphify Integration
• MCP Integration
  • Claude Desktop
  • Cursor
  • Custom MCP Clients
• CI/CD Integration
• IDE Integration
• Scripting Integration

How Agents Share Memory (v0.6.0+)

NeuralMind is the shared associative memory layer underneath whatever AI coding tools you use. If you run Claude Code for the day-to-day, Cursor for inline completions, OpenClaw for one-offs, and Hermes-Agent for planning — they all reinforce the same brain, and v0.6.0 makes the union of their activity visible.

The shared substrate

Three pieces of local state belong to the project, not to any one agent:

There’s no per-agent partition. Claude Code’s neuralmind_query and Hermes-Agent’s neuralmind_query reinforce the exact same synapse edges. The brain is one brain.

Verifying the shared-brain setup

# In each agent's host (Claude Desktop, Hermes, OpenClaw, etc.),
# the MCP server is registered with the SAME args:

neuralmind-mcp /absolute/path/to/project

# Verify the agent connected:
hermes mcp test neuralmind          # if using Hermes
openclaw mcp show neuralmind        # if using OpenClaw

# Verify the synapse store is at the expected path:
neuralmind stats .

# Pop the live canvas:
neuralmind serve .

Then trigger a tool call from each agent. The corresponding nodes should pulse on the v0.6.0 canvas regardless of which agent originated the call. If only some agents pulse, check that they’re pointing at the same project root (most common bug: relative paths that resolve differently in different processes — always use absolute paths in MCP host configs).

Why this didn’t work pre-v0.6.0

The synapse store was already shared, but the experience wasn’t. Each agent talked to the same SQLite file but you had no way to see the union of their activity — three tools talking to a black box. The v0.6.0 JSONL bridge (event_log.py) solved this by routing every event_bus.publish() through a shared file that serve can tail. Same SQLite, plus a visible heartbeat.

See docs/use-cases/multi-agent.md for a two-week walkthrough.

Opt-out

NEURALMIND_EVENT_LOG=0 disables the JSONL writer in the process where it’s set. The in-process bus is unaffected — serve still pulses for its own activity, just not for activity from other processes.

Graphify Integration

NeuralMind requires a knowledge graph generated by graphify to function. Graphify analyzes your codebase and creates a structured representation of code entities and their relationships.

Installing Graphify

Optional since v0.15.0 — neuralmind build generates the code graph itself via the built-in tree-sitter backend (Python, TypeScript, Go). Install graphify only if you want its richer graph or broader language coverage; it takes priority automatically.

pip install graphifyy

Generating Knowledge Graph

# Navigate to your project
cd /path/to/your/project

# Generate knowledge graph
graphify update .

# This creates:
# - graphify-out/graph.json (knowledge graph)
# - graphify-out/GRAPH_REPORT.md (analysis report)
# - graphify-out/cache/ (processing cache)

Understanding graph.json

The knowledge graph contains:

{
  "nodes": [
    {
      "id": "unique_id",
      "name": "authenticate_user",
      "type": "function",
      "file_path": "auth/handlers.py",
      "description": "Validates user credentials",
      "community": 5
    }
  ],
  "edges": [
    {
      "source": "node_id_1",
      "target": "node_id_2",
      "type": "calls"
    }
  ],
  "communities": [
    {
      "id": 5,
      "name": "Authentication",
      "description": "User authentication and authorization"
    }
  ]
}

Keeping Graph Updated

Update the graph when code changes:

# Rebuild the NeuralMind index (the code graph is regenerated
# automatically; on the graphify backend, run graphify update first)
neuralmind build /path/to/project

Git Hook for Automatic Updates

Add to .git/hooks/post-commit:

#!/bin/bash
# Automatically update knowledge graph after commits

PROJECT_ROOT=$(git rev-parse --show-toplevel)

# Rebuild NeuralMind index (regenerates the code graph)
neuralmind build "$PROJECT_ROOT" 2>/dev/null

Make it executable:

chmod +x .git/hooks/post-commit

MCP Integration

NeuralMind includes a Model Context Protocol (MCP) server for seamless integration with AI coding assistants.

MCP Server Overview

The MCP server exposes NeuralMind’s functionality as tools that AI assistants can call:

Starting the MCP Server

# Using the CLI entry point
neuralmind-mcp

# Or as a Python module
python -m neuralmind.mcp_server

# With custom port (if supported)
neuralmind-mcp --port 8080

Claude Desktop

Claude Desktop supports MCP servers natively.

Configuration

1. Find your Claude Desktop config file:
   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json
   • Linux: ~/.config/Claude/claude_desktop_config.json
2. Add NeuralMind server:

{
  "mcpServers": {
    "neuralmind": {
      "command": "neuralmind-mcp",
      "args": [],
      "env": {}
    }
  }
}

1. Restart Claude Desktop

Using with Claude

Once configured, Claude can:

User: What does the authentication module do in /projects/myapp?

Claude: [Calls neuralmind_query with project_path and question]
        Based on the codebase analysis, the authentication module...

Virtual Environment Configuration

If NeuralMind is installed in a virtual environment:

{
  "mcpServers": {
    "neuralmind": {
      "command": "/path/to/venv/bin/neuralmind-mcp",
      "args": [],
      "env": {
        "VIRTUAL_ENV": "/path/to/venv"
      }
    }
  }
}

Cursor

Cursor IDE supports MCP through its AI features.

Configuration

1. Open Cursor Settings
2. Navigate to AI → MCP Servers
3. Add server configuration:

{
  "neuralmind": {
    "command": "neuralmind-mcp"
  }
}

Workspace-Specific Setup

Create .cursor/mcp.json in your project:

{
  "servers": {
    "neuralmind": {
      "command": "neuralmind-mcp",
      "env": {
        "NEURALMIND_PROJECT": "${workspaceFolder}"
      }
    }
  }
}

Custom MCP Clients

For building your own MCP client integration:

Python Client Example

import asyncio
import json
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

async def query_neuralmind(project_path: str, question: str):
    server_params = StdioServerParameters(
        command="neuralmind-mcp",
        args=[]
    )
    
    async with stdio_client(server_params) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()
            
            # Call the query tool
            result = await session.call_tool(
                "neuralmind_query",
                {
                    "project_path": project_path,
                    "question": question
                }
            )
            
            return result

# Usage
result = asyncio.run(query_neuralmind(
    "/path/to/project",
    "How does authentication work?"
))
print(result)

Tool Schemas

NeuralMind MCP tools follow these schemas:

{
  "neuralmind_wakeup": {
    "input": {
      "project_path": "string (required)"
    },
    "output": {
      "context": "string",
      "tokens": "integer",
      "layers": "array"
    }
  },
  "neuralmind_query": {
    "input": {
      "project_path": "string (required)",
      "question": "string (required)"
    },
    "output": {
      "context": "string",
      "tokens": "integer",
      "reduction_ratio": "number",
      "layers": "array",
      "communities": "array"
    }
  },
  "neuralmind_search": {
    "input": {
      "project_path": "string (required)",
      "query": "string (required)",
      "limit": "integer (optional, default 10)"
    },
    "output": {
      "results": "array of search results"
    }
  },
  "neuralmind_build": {
    "input": {
      "project_path": "string (required)",
      "force": "boolean (optional, default false)"
    },
    "output": {
      "nodes_processed": "integer",
      "nodes_embedded": "integer",
      "communities": "integer",
      "time_elapsed": "number"
    }
  },
  "neuralmind_stats": {
    "input": {
      "project_path": "string (required)"
    },
    "output": {
      "node_count": "integer",
      "community_count": "integer",
      "last_build": "string"
    }
  },
  "neuralmind_benchmark": {
    "input": {
      "project_path": "string (required)"
    },
    "output": {
      "results": "array",
      "averages": "object"
    }
  }
}

Optional: NVIDIA NIM for LLM-Enhanced Queries

NeuralMind can use NVIDIA NIM (free, 80+ models) for LLM-based question decomposition in recursive queries:

# Get free API key at https://build.nvidia.com
export NVIDIA_API_KEY="nvapi-..."

# Recursive queries will use NVIDIA for decomposition when available
neuralmind_recursive_query(project_path=".", question="How does auth work?")

Base URL: https://integrate.api.nvidia.com/v1 (OpenAI-compatible) Recommended models:

• Decomposition: google/gemma-3-4b-it (fast)
• Synthesis: meta/llama-3.3-70b-instruct (reliable)
• Code: qwen/qwen3-coder-480b-a35b-instruct (specialist)

CI/CD Integration

GitHub Actions

Add NeuralMind to your CI pipeline:

# .github/workflows/neuralmind.yml
name: Update NeuralMind Index

on:
  push:
    branches: [main]
    paths:
      - '**.py'
      - '**.js'
      - '**.ts'

jobs:
  update-index:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.11'
      
      - name: Install dependencies
        run: |
          pip install neuralmind
      
      - name: Build NeuralMind index
        run: neuralmind build .
      
      - name: Run benchmark
        run: neuralmind benchmark . --json > benchmark.json
      
      - name: Upload artifacts
        uses: actions/upload-artifact@v4
        with:
          name: neuralmind-index
          path: |
            graphify-out/graph.json
            graphify-out/neuralmind_db/
            benchmark.json

Pre-commit Hook

Validate NeuralMind setup before commits:

# .pre-commit-config.yaml
repos:
  - repo: local
    hooks:
      - id: neuralmind-check
        name: Check NeuralMind Index
        entry: bash -c 'neuralmind stats . || echo "Warning: NeuralMind index not built"'
        language: system
        pass_filenames: false
        always_run: true

IDE Integration

VS Code

Native Extension (recommended)

Install the NeuralMind VS Code extension for a first-class editor experience — no task configuration needed.

# From the editors/vscode directory in the repo:
cd editors/vscode && npm install && npm run compile

Then load the extension in VS Code via Extensions: Install from VSIX or open editors/vscode/ as a workspace and press F5 to launch a debug session.

What you get:

• Status bar ($(check) NeuralMind · 2.1k nodes) — green/yellow/red shows index freshness; click to open graph view
• Command palette — NeuralMind: Query, Wakeup, Skeleton, Build Index, Probe, Open Graph View
• Graph panel — embedded force-directed graph (the same neuralmind serve UI) in a WebviewPanel
• Auto-build prompt — notifies when the index is stale (configurable threshold)
• Hover cards — opt-in (neuralmind.enableHover: true) skeleton view on hover

Settings (Ctrl+, → search “NeuralMind”):

Task Configuration (fallback, no extension required)

Create .vscode/tasks.json:

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "NeuralMind: Build Index",
      "type": "shell",
      "command": "neuralmind build ${workspaceFolder}",
      "problemMatcher": [],
      "group": "build"
    },
    {
      "label": "NeuralMind: Wake-up Context",
      "type": "shell",
      "command": "neuralmind wakeup ${workspaceFolder}",
      "problemMatcher": [],
      "presentation": {
        "reveal": "always",
        "panel": "new"
      }
    },
    {
      "label": "NeuralMind: Query",
      "type": "shell",
      "command": "neuralmind query ${workspaceFolder} \"${input:question}\"",
      "problemMatcher": [],
      "presentation": {
        "reveal": "always",
        "panel": "new"
      }
    },
    {
      "label": "NeuralMind: Benchmark",
      "type": "shell",
      "command": "neuralmind benchmark ${workspaceFolder}",
      "problemMatcher": [],
      "presentation": {
        "reveal": "always",
        "panel": "new"
      }
    }
  ],
  "inputs": [
    {
      "id": "question",
      "type": "promptString",
      "description": "Enter your question about the codebase"
    }
  ]
}

Keyboard Shortcuts

Add to keybindings.json:

[
  {
    "key": "ctrl+shift+n w",
    "command": "workbench.action.tasks.runTask",
    "args": "NeuralMind: Wake-up Context"
  },
  {
    "key": "ctrl+shift+n q",
    "command": "workbench.action.tasks.runTask",
    "args": "NeuralMind: Query"
  }
]

JetBrains IDEs

External Tools Configuration

1. Go to Settings → Tools → External Tools
2. Add new tool:

Name: NeuralMind Query
Program: neuralmind
Arguments: query $ProjectFileDir$ "$Prompt$"
Working directory: $ProjectFileDir$

1. Assign keyboard shortcut in Settings → Keymap

Scripting Integration

Shell Scripts

Complete Update Script

#!/bin/bash
# update_knowledge.sh - Update graphify and NeuralMind

set -e

PROJECT_PATH="${1:-.}"
FORCE_REBUILD="${2:-false}"

echo "Updating knowledge system for: $PROJECT_PATH"

# Build NeuralMind (the code graph is regenerated automatically)
echo "Building NeuralMind index..."
if [ "$FORCE_REBUILD" = "true" ]; then
    neuralmind build "$PROJECT_PATH" --force
else
    neuralmind build "$PROJECT_PATH"
fi

# Show stats
echo ""
echo "=== Index Statistics ==="
neuralmind stats "$PROJECT_PATH"

echo ""
echo "Done!"

Query Script with Clipboard

#!/bin/bash
# query_and_copy.sh - Query and copy result to clipboard

PROJECT_PATH="$1"
QUESTION="$2"

if [ -z "$PROJECT_PATH" ] || [ -z "$QUESTION" ]; then
    echo "Usage: $0 <project_path> <question>"
    exit 1
fi

RESULT=$(neuralmind query "$PROJECT_PATH" "$QUESTION")

echo "$RESULT"

# Copy to clipboard
if command -v pbcopy &> /dev/null; then
    echo "$RESULT" | pbcopy
    echo "\n[Copied to clipboard]"
elif command -v xclip &> /dev/null; then
    echo "$RESULT" | xclip -selection clipboard
    echo "\n[Copied to clipboard]"
fi

Python Scripts

Batch Processing

#!/usr/bin/env python3
"""Process multiple projects with NeuralMind."""

import sys
from pathlib import Path
from neuralmind import NeuralMind

def process_projects(project_paths: list, questions: list):
    """Process multiple projects with common questions."""
    
    results = []
    
    for project_path in project_paths:
        path = Path(project_path)
        if not path.exists():
            print(f"Skipping {project_path}: not found")
            continue
        
        print(f"\nProcessing: {project_path}")
        
        try:
            mind = NeuralMind(str(path))
            mind.build()
            
            project_results = {
                'project': project_path,
                'stats': mind.get_stats(),
                'queries': []
            }
            
            for question in questions:
                result = mind.query(question)
                project_results['queries'].append({
                    'question': question,
                    'tokens': result.budget.total,
                    'reduction': result.reduction_ratio
                })
            
            results.append(project_results)
            
        except Exception as e:
            print(f"Error processing {project_path}: {e}")
    
    return results

if __name__ == '__main__':
    projects = [
        '/path/to/project1',
        '/path/to/project2',
    ]
    
    questions = [
        "How does authentication work?",
        "What are the main API endpoints?",
    ]
    
    results = process_projects(projects, questions)
    
    # Print summary
    for r in results:
        print(f"\n{r['project']}: {r['stats']['node_count']} nodes")
        for q in r['queries']:
            print(f"  - {q['question'][:40]}... ({q['tokens']} tokens, {q['reduction']:.1f}x)")

Watch Mode

#!/usr/bin/env python3
"""Watch for changes and auto-rebuild NeuralMind index."""

import time
import subprocess
from pathlib import Path
from watchdog.observers import Observer
from watchdog.events import FileSystemEventHandler

class CodeChangeHandler(FileSystemEventHandler):
    def __init__(self, project_path: str):
        self.project_path = project_path
        self.last_rebuild = 0
        self.debounce_seconds = 5
    
    def on_modified(self, event):
        if event.is_directory:
            return
        
        # Only watch code files
        extensions = {'.py', '.js', '.ts', '.java', '.go', '.rs'}
        if Path(event.src_path).suffix not in extensions:
            return
        
        # Debounce
        current_time = time.time()
        if current_time - self.last_rebuild < self.debounce_seconds:
            return
        
        self.last_rebuild = current_time
        print(f"Change detected: {event.src_path}")
        self.rebuild()
    
    def rebuild(self):
        print("Rebuilding knowledge graph...")
        subprocess.run(['graphify', 'update', self.project_path], check=True)
        
        print("Rebuilding NeuralMind index...")
        subprocess.run(['neuralmind', 'build', self.project_path], check=True)
        
        print("Done!\n")

if __name__ == '__main__':
    import sys
    project_path = sys.argv[1] if len(sys.argv) > 1 else '.'
    
    event_handler = CodeChangeHandler(project_path)
    observer = Observer()
    observer.schedule(event_handler, project_path, recursive=True)
    observer.start()
    
    print(f"Watching {project_path} for changes...")
    print("Press Ctrl+C to stop\n")
    
    try:
        while True:
            time.sleep(1)
    except KeyboardInterrupt:
        observer.stop()
    observer.join()

See Also

• Installation - Setup instructions
• CLI Reference - Command-line interface
• API Reference - Python API documentation
• Architecture - System design details