NeuralMind Usage Guide

Complete guide to features, use cases, and scheduling routines for NeuralMind

Table of Contents

• What is NeuralMind?
• Key Features
• The 4-Layer Architecture
• Quick Start
• Use Cases
• CLI Command Reference
• Scheduling Routines
• ROI Calculator
• MCP Server Integration
• Troubleshooting

What is NeuralMind?

NeuralMind is a two-phase token optimizer for AI coding agents.

• Phase 1 — Retrieval. A 4-layer progressive-disclosure index surfaces ~800 tokens of structured context per code question, instead of loading 50,000+ tokens of raw source. Works with Claude, GPT-4, Gemini, and local models.
• Phase 2 — Consumption. PostToolUse hooks (Claude Code) compress Read, Bash, and Grep output before the agent sees it — typically 88–91% smaller.

Combined effect: 5–10× total reduction vs baseline agent usage. 100% local, offline, model-agnostic. See Use Cases for persona-matched walkthroughs.

The Core Problem

You: "How does authentication work in my codebase?"

❌ Traditional approach: Load entire codebase → 50,000 tokens → $0.15-$3.75/query
✅ NeuralMind approach:  Smart context         → ~800 tokens   → $0.002-$0.06/query

The Solution

NeuralMind turns a code repository into a queryable knowledge graph + vector index, and exposes it via CLI, MCP server, and (for Claude Code) PostToolUse compression hooks. When you ask a question, only the context relevant to that question is surfaced.

Key Features

The 4-Layer Architecture

┌─────────────────────────────────────────────────────────────┐
│ Layer 0: Project Identity (~100 tokens) - ALWAYS LOADED     │
│ • Project name, type, tech stack                            │
│ • Entry points, main patterns                               │
├─────────────────────────────────────────────────────────────┤
│ Layer 1: Architecture Summary (~300 tokens) - ALWAYS LOADED │
│ • Module overview, key components                           │
│ • Dependencies, data flow                                   │
├─────────────────────────────────────────────────────────────┤
│ Layer 2: Relevant Modules (~300 tokens) - QUERY-SPECIFIC    │
│ • Code clusters related to your question                    │
│ • Community detection based on code relationships           │
├─────────────────────────────────────────────────────────────┤
│ Layer 3: Semantic Search (~300 tokens) - QUERY-SPECIFIC     │
│ • Direct keyword and concept matches                        │
│ • Vector similarity search results                          │
└─────────────────────────────────────────────────────────────┘

Total: ~800-1,100 tokens vs 50,000+ for full codebase

How It Works

1. The built-in tree-sitter backend (or graphify, if installed) analyzes your codebase and creates a knowledge graph
2. NeuralMind creates vector embeddings of all code entities
3. When you query, it selects only relevant context using semantic similarity
4. You get focused, accurate context that fits in any LLM’s context window

Quick Start

Step 1: Install

pip install neuralmind

Step 2: Build Neural Index

cd your-project
neuralmind build .   # the code graph is generated automatically (v0.15.0+)

Step 3: Query Your Codebase

# Get project overview
neuralmind wakeup .

# Ask specific questions
neuralmind query . "How does authentication work?"
neuralmind query . "What are the main components?"
neuralmind query . "How is data validated?"

Step 4: Use with AI

# Copy output to clipboard (macOS)
neuralmind query . "How does X work?" | pbcopy

# Copy output to clipboard (Linux)
neuralmind query . "How does X work?" | xclip -selection clipboard

# Copy output to clipboard (Windows PowerShell)
neuralmind query . "How does X work?" | Set-Clipboard

# Then paste into Claude/ChatGPT/Cursor

Use Cases

Use Case 1: Daily Development Questions

When: You need to ask AI about your codebase multiple times per day

How:

# Get context for your question
neuralmind query . "How does the payment processing work?"

# Copy output → Paste into Claude/ChatGPT → Get accurate answer

Benefit: 100 queries/day goes from $450/month → $7/month with Claude 3.5 Sonnet

Use Case 2: New Developer Onboarding

When: New team member needs to understand the codebase

How:

# Generate project overview
neuralmind wakeup . > project_overview.md

# Answer common onboarding questions
neuralmind query . "What are the main API endpoints?" > docs/api_overview.md
neuralmind query . "How is the database structured?" > docs/database.md
neuralmind query . "What authentication method is used?" > docs/auth.md
neuralmind query . "How do I set up my local development environment?" > docs/setup.md

Benefit: New devs get accurate answers without constantly asking senior devs

Use Case 3: Code Review Context

When: Reviewing a PR and need to understand related code

How:

# Understand the feature being changed
neuralmind query . "How does the user registration flow work?"

# Find related code that might be affected
neuralmind search . "validation middleware"

# Understand the test coverage
neuralmind query . "What tests exist for user registration?"

Benefit: Better code reviews with full context awareness

Use Case 4: Documentation Generation

When: Creating or updating documentation

How:

# Export structured understanding
neuralmind wakeup . > docs/ARCHITECTURE.md

# Generate API documentation
neuralmind query . "List all API endpoints with their purposes" >> docs/API.md

# Generate component documentation
neuralmind query . "Describe each React component and its purpose" >> docs/COMPONENTS.md

Benefit: AI-assisted documentation that’s accurate to actual code

Use Case 5: Team Memory via CI Auto-Index (v0.38.0+)

When: You want every developer on a team to have an up-to-date NeuralMind index without running neuralmind build manually.

How: Drop the bundled GitHub Action into your repo — it runs on every push to main, rebuilds the index incrementally (source-hash cache skips unchanged files), exports the synapse memory as .neuralmind-team-memory.json, and commits it back so the next developer’s git pull picks it up:

# .github/workflows/neuralmind-autoindex.yml
name: NeuralMind Auto-Index
on:
  push:
    branches: [main, master]
  workflow_dispatch:
    inputs:
      force:
        description: Force full re-embed
        type: boolean
        default: false

permissions:
  contents: write

jobs:
  autoindex:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: actions/setup-python@v5
        with:
          python-version: "3.11"
      - name: Restore cache
        uses: actions/cache@v4
        with:
          path: .neuralmind/
          key: neuralmind-$
      - run: pip install "neuralmind>=0.38.0"
      - run: neuralmind build .
      - run: neuralmind memory export
      - uses: stefanzweifel/git-auto-commit-action@v5
        with:
          commit_message: "chore: update team memory [skip ci]"
          file_pattern: ".neuralmind-team-memory.json"

Benefit: The synapse layer’s learned associations are shared across the whole team — no one starts cold. Agent sessions inherit the team’s collective knowledge of which files go together.

Use Case 6: CI/CD Integration

When: Automated context generation in pipelines

How:

# .github/workflows/update-context.yml
name: Update AI Context
on:
  push:
    branches: [main]

jobs:
  update-context:
    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 NeuralMind
        run: pip install neuralmind
      
      - name: Build neural index
        run: neuralmind build .
      
      - name: Generate AI context file
        run: neuralmind wakeup . > AI_CONTEXT.md
      
      - name: Commit updated context
        run: |
          git config user.name "github-actions[bot]"
          git config user.email "github-actions[bot]@users.noreply.github.com"
          git add AI_CONTEXT.md
          git diff --staged --quiet || git commit -m "docs: update AI context"
          git push

Benefit: Always up-to-date context file in your repo

Use Case 7: Watch the brain learn (v0.6.0+)

When: You want a “second screen” for your AI coding session — a live view of which parts of your codebase the agent is using, in real time, as it works.

How:

# Terminal A — your normal Claude Code (or Cursor, OpenClaw, etc.) session
claude-code   # work as usual

# Terminal B — the live graph view
neuralmind serve .

# Terminal C — always-on synapse learning from file edits
neuralmind watch . --quiet &

Open the URL neuralmind serve prints in your browser. The graph view is now alive:

• Every time your agent calls neuralmind_query (or any other NeuralMind MCP tool), the affected nodes pulse on the canvas with short animated radial rings.
• Every time you save a file in your editor, the corresponding node pulses (because the watch daemon coalesces edits into co-activation events).
• The sidebar log shows the most recent ~80 events with timestamps. Click an entry to focus the corresponding node.

The three-terminal walkthrough:

1. Open Claude Code (terminal A) and ask “how does authentication work in this codebase?”
2. Switch to terminal B’s browser tab — the auth-cluster nodes are pulsing as the agent calls neuralmind_query.
3. In your editor, open src/auth/handlers.py, add a comment, save.
4. Switch back to the browser — the corresponding node pulses within ~1s.
5. The synapse store has now reinforced the edges between auth handlers and whatever else the agent looked at. Next session, asking about auth will surface this file faster.

Benefit: trust-gap closure. “Is the agent looking at the right code?” becomes a 2-second visual answer. When retrieval feels wrong, the Replay last query action in the detail panel re-highlights the L3 hits the agent actually received — usually the diagnosis is obvious from the pulse pattern.

Multi-agent unlock: the v0.6.0 cross-process JSONL bridge (<project>/.neuralmind/events.jsonl) means every agent talking to the same project (Claude Code, Cursor, OpenClaw, Hermes-Agent) feeds the same canvas. See multi-agent use-case page.

Opt out: set NEURALMIND_EVENT_LOG=0 to disable the JSONL writer (you still get the in-process feed for the agent running serve itself).

Use Case 8: IDE Integration (MCP Server)

When: Direct AI integration in Claude Desktop or Cursor

How:

// ~/.config/claude/claude_desktop_config.json (macOS/Linux)
// %APPDATA%\Claude\claude_desktop_config.json (Windows)
{
  "mcpServers": {
    "neuralmind": {
      "command": "neuralmind-mcp",
      "args": ["/path/to/your/project"]
    }
  }
}

Benefit: Claude Desktop automatically gets relevant context for every question

CLI Command Reference

Detailed Command Usage

neuralmind build

Builds or rebuilds the neural index from your knowledge graph.

# Build index for current directory
neuralmind build .

# Build index for specific project
neuralmind build /path/to/project

# Rebuild after code changes
neuralmind build .

When to use: After initial setup, after significant code changes, weekly maintenance.

neuralmind query

Asks a natural language question and returns relevant context.

# Basic query
neuralmind query . "How does authentication work?"

# Query and save to file
neuralmind query . "What are all the API endpoints?" > api_context.md

# Query and copy to clipboard (macOS)
neuralmind query . "How is data validated?" | pbcopy

When to use: Every time you want to ask AI about your code.

neuralmind wakeup

Returns the project overview (L0 + L1 layers) for starting new conversations.

# Get wakeup context
neuralmind wakeup .

# Save as project overview
neuralmind wakeup . > PROJECT_OVERVIEW.md

When to use: Starting a new Claude/ChatGPT conversation about your project.

neuralmind search

Direct semantic search without the full context layers.

# Search for related code
neuralmind search . "payment processing"
neuralmind search . "error handling middleware"
neuralmind search . "database models"

When to use: When you want to find specific code entities quickly.

neuralmind learn (deprecated, v0.25.0)

Deprecated and a no-op since v0.25.0. The learned_patterns cooccurrence reranker this command populated was removed; the command now prints a deprecation notice and exits 0, so old scripts and CI keep working unchanged.

neuralmind learn .   # prints a deprecation notice, exits 0

Learning is now handled entirely by the synapse layer, which learns continuously and automatically from queries, edits, and tool calls — no manual step, and edges decay instead of going stale. The reranker was removed after a 2×2 A/B on the benchmark fixture showed it added 0.0 points to top-k hit rate while the synapse layer alone adds +11.6 points.

What to do instead: install the lifecycle hooks (neuralmind install-hooks .) and optionally run neuralmind watch . so the synapse layer learns from your usage. Inspect what’s been learned with neuralmind stats . or neuralmind memory inspect .. See the Learning Guide for details.

• Better relevance = smaller context needed = more token savings

Privacy: 100% local analysis. No data sent anywhere. Patterns file is just JSON in your project.

neuralmind benchmark

Measures token reduction for sample queries.

# Run benchmark
neuralmind benchmark .

# Example output:
# Query: "How does authentication work?" - 739 tokens (67.7x reduction)
# Query: "What are the API endpoints?" - 748 tokens (66.8x reduction)
# Average: 766 tokens (65.3x reduction)

When to use: Verifying your cost savings, demonstrating value to team.

neuralmind stats

Shows index statistics.

# View stats
neuralmind stats .

# Example output:
# Nodes: 241
# Edges: 203
# Communities: 93
# Index size: 12.4 MB

When to use: Checking index health, monitoring project growth.

Scheduling Routines

When to Update Your Index

Git Hook Setup (Recommended for Active Development)

Automatically update the index after every commit:

# Create post-commit hook
cat > .git/hooks/post-commit << 'EOF'
#!/bin/bash
echo "🧠 Updating NeuralMind index..."
neuralmind build . 2>/dev/null
echo "✓ NeuralMind index updated"
EOF

# Make it executable
chmod +x .git/hooks/post-commit

Cron Job Setup (Recommended for Servers)

# Edit crontab
crontab -e

# Daily update at 6 AM
0 6 * * * cd /path/to/project && neuralmind build . >> /var/log/neuralmind.log 2>&1

# Weekly update on Monday at 3 AM
0 3 * * 1 cd /path/to/project && neuralmind build . >> /var/log/neuralmind.log 2>&1

CI/CD Integration (Recommended for Teams)

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

on:
  push:
    branches: [main]
  schedule:
    - cron: '0 6 * * *'  # Daily at 6 AM UTC

jobs:
  update:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.11'
      - run: pip install neuralmind
      - run: neuralmind build .
      - run: neuralmind stats .

Maintenance Checklist

Weekly maintenance routine:

#!/bin/bash
# weekly_maintenance.sh

echo "🔧 NeuralMind Weekly Maintenance"
echo "================================"

# Rebuild neural index (the code graph is regenerated automatically)
echo "1. Rebuilding neural index..."
neuralmind build .

# Show stats
echo "2. Current statistics:"
neuralmind stats .

# Run benchmark
echo "3. Benchmark results:"
neuralmind benchmark .

echo ""
echo "✅ Maintenance complete!"

ROI Calculator

Cost Comparison by Model

Monthly Savings Calculator

Annual Savings

MCP Server Integration

What is MCP?

Model Context Protocol (MCP) allows AI assistants to directly query external tools. NeuralMind’s MCP server lets Claude Desktop and Cursor automatically get relevant code context.

Setup for Claude Desktop

1. Install NeuralMind (the MCP server is included by default since v0.5.0):

   pip install neuralmind
   

2. Add to Claude Desktop config:

macOS/Linux: ~/.config/claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

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

1. Restart Claude Desktop

Available MCP Tools

Usage in Claude Desktop

Once configured, Claude will automatically have access to your codebase context. Just ask questions like:

• “How does authentication work in this project?”
• “What are all the API endpoints?”
• “Explain the database schema”

Claude will use NeuralMind to get relevant context before answering.

Troubleshooting

Common Issues

“No graph.json found”

# Solution: Run graphify first
neuralmind build .

“Index out of date”

# Solution: Rebuild the index
neuralmind build .

“ChromaDB error”

# Solution: Clear and rebuild
rm -rf graphify-out/neuralmind_db
neuralmind build .

“Module not found”

# Solution: Reinstall
pip uninstall neuralmind
pip install neuralmind

Getting Help

• GitHub Issues: https://github.com/dfrostar/neuralmind/issues
• Wiki: https://github.com/dfrostar/neuralmind/wiki
• Discussions: https://github.com/dfrostar/neuralmind/discussions

Contributing

See CONTRIBUTING.md for guidelines.

License

MIT License - see LICENSE for details.