# Integration Guide

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

## Table of Contents

- [How Agents Share Memory (v0.6.0+)](#how-agents-share-memory-v060)
- [Graphify Integration](#graphify-integration)
- [MCP Integration](#mcp-integration)
  - [Claude Desktop](#claude-desktop)
  - [Cursor](#cursor)
  - [Custom MCP Clients](#custom-mcp-clients)
- [CI/CD Integration](#cicd-integration)
- [IDE Integration](#ide-integration)
- [Scripting 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:

| Path | What it is | Who reads/writes |
|------|------------|------------------|
| `graphify-out/graph.json` | Call graph (created by `graphify`) | Read-only at NeuralMind runtime |
| `graphify-out/neuralmind_db/` | ChromaDB vector index | `neuralmind build` writes; agents read |
| `<project>/.neuralmind/synapses.db` | Learned synapse weights | Every MCP tool call, every `watch` event, every Claude Code hook |
| `<project>/.neuralmind/events.jsonl` *(v0.6.0+)* | Cross-process activity stream | Every `event_bus.publish()` writes; `serve` tails |

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

```bash
# 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`](../../neuralmind/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](../../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](https://github.com/safishamsi/graphify) to function. Graphify analyzes your codebase and creates a structured representation of code entities and their relationships.

### Installing Graphify

```bash
pip install graphifyy
```

### Generating Knowledge Graph

```bash
# 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:

```json
{
  "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:

```bash
# Manual update
graphify update /path/to/project

# Then rebuild NeuralMind index
neuralmind build /path/to/project
```

### Git Hook for Automatic Updates

Add to `.git/hooks/post-commit`:

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

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

# Update graph
graphify update "$PROJECT_ROOT" 2>/dev/null

# Rebuild NeuralMind index
neuralmind build "$PROJECT_ROOT" 2>/dev/null
```

Make it executable:

```bash
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:

| Tool | Description |
|------|-------------|
| `neuralmind_wakeup` | Get wake-up context for a project |
| `neuralmind_query` | Query project with natural language |
| `neuralmind_search` | Semantic search across codebase |
| `neuralmind_skeleton` | Graph-backed file view |
| `neuralmind_recursive_query` | Decompose and explore complex questions |
| `neuralmind_query_docs` | Search reference documents (PDFs, DOCX) |
| `neuralmind_build` | Build/rebuild neural index |
| `neuralmind_stats` | Get project statistics |
| `neuralmind_benchmark` | Run performance benchmark |
| `neuralmind_synaptic_neighbors` *(v0.4.0)* | Spreading-activation recall over the learned synapse graph; complements vector search with usage-based recall |
| `neuralmind_synapse_stats` *(v0.4.0)* | Inspect the synapse graph: edges, LTP edges, top hubs, total weight |
| `neuralmind_synapse_decay` *(v0.4.0)* | Manually run a decay tick (normally fired automatically by the SessionStart hook) |
| `neuralmind_export_synapse_memory` *(v0.4.0)* | Render the synapse graph as markdown and write it to project-local memory + Claude Code's auto-memory directory when present |

### Starting the MCP Server

```bash
# 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:

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

3. 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:

```json
{
  "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:

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

#### Workspace-Specific Setup

Create `.cursor/mcp.json` in your project:

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

### Custom MCP Clients

For building your own MCP client integration:

#### Python Client Example

```python
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:

```json
{
  "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:

```bash
# 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:

```yaml
# .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 graphifyy neuralmind
      
      - name: Update knowledge graph
        run: graphify update .
      
      - 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:

```yaml
# .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

#### Task Configuration

Create `.vscode/tasks.json`:

```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`:

```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$
```

3. Assign keyboard shortcut in Settings → Keymap

---

## Scripting Integration

### Shell Scripts

#### Complete Update Script

```bash
#!/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"

# Update graphify
echo "Running graphify update..."
graphify update "$PROJECT_PATH"

# Build NeuralMind
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

```bash
#!/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

```python
#!/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

```python
#!/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](Installation.md) - Setup instructions
- [CLI Reference](CLI-Reference.md) - Command-line interface
- [API Reference](API-Reference.md) - Python API documentation
- [Architecture](Architecture.md) - System design details