neuralmind

Setup Guide

First-time setup for NeuralMind on any platform in under 5 minutes.

NeuralMind is persistent memory for AI coding agents: a 4-layer semantic index that answers code questions in ~800 tokens instead of 50,000+, a brain-like synapse layer that learns your codebase from how you actually use it, and PostToolUse hooks that compress Read/Bash/Grep output before your agent sees it. Token reduction is 40–70× per query on real repos, measured in CI on every commit.

See Use Cases if you’re unsure whether NeuralMind fits your workflow, or Comparisons for how it differs from Cursor @codebase, Copilot, Claude Projects, long context, and others.

Table of Contents

Install — pick your path

NeuralMind installs five ways. They all deliver the same package; pick the one that fits your existing tooling. Since v0.15.0 the code graph is generated by a built-in tree-sitter backend (Python, TypeScript, Go) — no external graph tool is required.

Method Command When to pick
pip pip install neuralmind Default. Drops it in your active env.
pipx pipx install neuralmind Global CLI, no env pollution.
uv uv pip install neuralmind Modern, fast Python tooling.
Docker docker pull ghcr.io/dfrostar/neuralmind:latest && docker run --rm -v "$PWD:/project:ro" ghcr.io/dfrostar/neuralmind:latest neuralmind --help Containerized — no Python on the host. Multi-platform (linux/amd64 + linux/arm64); auto-published to GHCR on every release since v0.9.0. To build locally instead: docker build -t neuralmind:dev . and substitute that tag.
From source git clone https://github.com/dfrostar/neuralmind && pip install -e . Contributing or hacking.

Pros and cons of each path, including persistence and PATH behavior: Install paths walkthrough.

Verify any install:

python -c "import neuralmind; print(neuralmind.__version__)"
neuralmind --help

30-Second Setup

Once installed (any path above):

# 1. Go to your project
cd /path/to/your-project

# 2. Build the neural index (generates the code graph automatically)
neuralmind build .

# 3. Test it
neuralmind wakeup .

You should see a compact project overview. If you do, NeuralMind is ready.

Note: the first neuralmind build downloads the local embedding model (~80 MB, one time, cached in ~/.cache). Everything after that is fully offline. On an air-gapped or proxied machine, see the air-gapped walkthrough.

Choose Your Workflow

Your tool What to set up Guide
Claude Code MCP + PostToolUse hooks Claude Code
Claude Desktop MCP server Claude Desktop
Cursor / Cline / Continue MCP server Cursor / Cline / Continue
ChatGPT / Gemini / any LLM CLI (copy-paste output) Any LLM

Shortcut for all MCP agents at once (v0.19.0+):

neuralmind install-mcp --all

This auto-detects your installed agents — Claude Code, Cursor, Cline, Claude Desktop — and registers NeuralMind’s MCP server with each (non-destructive merge, idempotent; add --print to preview the config without writing files). The per-platform sections below show the manual config if you prefer to edit it yourself.

Platform Setup

Claude Code

Claude Code gets the full stack: smart retrieval, learned synapse memory on session start, and compressed tool outputs.

pip install neuralmind

cd your-project
neuralmind build .

# Register the MCP server (or use: neuralmind install-mcp --all)
neuralmind install-mcp --client claude-code

# Install PostToolUse compression hooks (compresses Read/Bash/Grep output)
neuralmind install-hooks .

# Optional: auto-rebuild index on every git commit
neuralmind init-hook .

Use it:

Inside a Claude Code session, call NeuralMind tools directly:

neuralmind_wakeup(".")          # project overview at session start
neuralmind_query(".", "How does auth work?")   # focused context
neuralmind_skeleton("src/auth.py")             # compact file view

Or add a .mcp.json at your project root so Claude Code loads NeuralMind automatically:

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

Claude Desktop

pip install neuralmind

cd your-project
neuralmind build .

# Register the MCP server automatically:
neuralmind install-mcp --client claude-desktop

Or add NeuralMind to your Claude Desktop config manually:

{
  "mcpServers": {
    "neuralmind": {
      "command": "neuralmind-mcp",
      "args": ["/absolute/path/to/your-project"]
    }
  }
}

Restart Claude Desktop. NeuralMind tools (neuralmind_wakeup, neuralmind_query, etc.) will appear automatically.

Tip: If NeuralMind is installed in a virtual environment, use the full path: "/path/to/venv/bin/neuralmind-mcp"

Cursor / Cline / Continue

pip install neuralmind

cd your-project
neuralmind build .

# Register the MCP server automatically (Cursor and Cline are auto-detected):
neuralmind install-mcp --all

Or add to your MCP config manually (location varies by tool — check your tool’s docs):

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

When using MCP tools, always pass the project_path parameter pointing to your project root.

Any LLM (copy-paste)

No special integration needed. Just pipe CLI output into your chat interface.

# Copy project overview (macOS)
neuralmind wakeup . | pbcopy

# Copy project overview (Linux)
neuralmind wakeup . | xclip -selection clipboard

# Copy project overview (Windows PowerShell)
neuralmind wakeup . | Set-Clipboard

# Ask a specific question and copy the answer
neuralmind query . "How does the payment system work?" | pbcopy

Paste the output at the start of any Claude/ChatGPT/Gemini conversation.

Keeping the Index Fresh

Option A — Watch mode (recommended for active projects, v0.18.0+)

neuralmind watch --reindex

Re-parses each changed file as you save it and re-embeds only its nodes — unchanged files are skipped, so the index stays fresh as you type. Run it as a service with the committed systemd/launchd templates (Scheduling Guide).

Option B — Git hook

# Install managed hook (idempotent, coexists with other hooks)
neuralmind init-hook .

The index rebuilds automatically after every commit.

Option C — Manual

# After code changes
neuralmind build .

Option D — Scheduled (CI/CD or cron)

# .github/workflows/update-neuralmind.yml
- run: pip install neuralmind
- run: neuralmind build .

Verify Everything Works

# One command checks the whole setup (v0.12.0+): code graph, semantic
# index, synapse memory, MCP registration, hooks — each with the exact
# fix command if something's missing
neuralmind doctor

# Check index stats
neuralmind stats .

# Run token-reduction benchmark
neuralmind benchmark .

Expected output from stats:

Project: your-project
Built: True
Nodes: <number>

If Built: False, run neuralmind build . again — and if it still fails, neuralmind doctor will tell you which piece is missing.

Optional: the graphify backend

NeuralMind’s built-in tree-sitter backend covers Python, TypeScript, and Go standalone, proven at parity with graphify by a CI gate. If you prefer graphify’s richer graph, install it and it takes priority automatically:

pip install graphifyy   # PyPI name for graphify
graphify update .
neuralmind build .

For compiler-accurate call/inheritance edges there’s also the optional SCIP precision pass (NEURALMIND_PRECISION=1, v0.17.0+).

Requirements

Requirement Version
Python 3.10 or higher
NeuralMind pip install neuralmind (includes the MCP server and the tree-sitter graph backend)
graphify (optional) pip install graphifyy — richer graph, auto-prioritized when present

Supported OS: Linux, macOS, Windows 10+

Next Steps

This site is open source. Improve this page.