Common issues and solutions for NeuralMind.
Symptoms: Running neuralmind returns “command not found” or similar.
Causes:
Solutions:
# Check if neuralmind is installed
pip show neuralmind
# If installed, find the scripts location
python -c "import site; print(site.USER_BASE + '/bin')"
# Add to PATH (Linux/macOS)
export PATH="$HOME/.local/bin:$PATH"
# If using virtual environment, ensure it's activated
source venv/bin/activate # Linux/macOS
venv\Scripts\activate # Windows
Symptoms: Import errors when running NeuralMind.
Causes:
Solutions:
# Reinstall with dependencies
pip uninstall neuralmind
pip install neuralmind
# Or install dependencies manually
pip install chromadb>=0.4.0 pyyaml>=6.0
# Verify installation
python -c "import chromadb; print('ChromaDB OK')"
python -c "import neuralmind; print('NeuralMind OK')"
Symptoms: Installation fails when building ChromaDB.
Causes:
Solutions:
# Update pip and build tools
pip install --upgrade pip setuptools wheel
# On Linux, install build dependencies
sudo apt-get install python3-dev build-essential
# On macOS, ensure Xcode tools are installed
xcode-select --install
# Try installing again
pip install neuralmind
Symptoms: Package fails to install or import with Python version errors.
Causes: Python version < 3.10
Solutions:
# Check Python version
python --version
# If < 3.10, install newer Python
# Ubuntu/Debian
sudo apt install python3.11
# macOS with Homebrew
brew install python@3.11
# Use pyenv for version management
pyenv install 3.11.0
pyenv local 3.11.0
Symptoms: neuralmind build fails with “graph.json not found”.
Causes:
neuralmind build generates the graph itself)Solutions:
# Build with the correct path — the code graph is generated automatically
neuralmind build /path/to/project
# Verify graph exists
ls /path/to/project/graphify-out/graph.json
# Still failing? The doctor pinpoints the missing piece
neuralmind doctor
Symptoms: Build completes but reports 0 nodes processed.
Causes:
Solutions:
# Check graphify output
cat /path/to/project/graphify-out/GRAPH_REPORT.md
# Verify graph.json has content
python -c "import json; g=json.load(open('graphify-out/graph.json')); print(f'Nodes: {len(g.get(\"nodes\", []))}')"
# Using the optional graphify backend? Re-run it with verbose output
graphify update /path/to/project --verbose
Symptoms: Build fails with database lock errors.
Causes:
Solutions:
# Kill any hanging processes
pkill -f neuralmind
# Remove lock files
rm -rf /path/to/project/graphify-out/neuralmind_db/*.lock
# Or delete and rebuild database
rm -rf /path/to/project/graphify-out/neuralmind_db
neuralmind build /path/to/project
Symptoms: Build crashes with MemoryError or system becomes unresponsive.
Causes:
Solutions:
# Check codebase size
python -c "import json; g=json.load(open('graphify-out/graph.json')); print(f'Nodes: {len(g[\"nodes\"])}')"
# For large codebases (>10,000 nodes), consider:
# 1. Close other applications to free memory
# 2. Use a machine with more RAM
# 3. Exclude test/vendor directories from graphify
# Build incrementally after initial build
neuralmind build /path/to/project # Uses incremental updates
Symptoms: Query fails with “index not built” or “run build first”.
Causes:
build command never runSolutions:
# Check if index exists
ls /path/to/project/graphify-out/neuralmind_db/
# Build the index
neuralmind build /path/to/project
# Then query
neuralmind query /path/to/project "your question"
Symptoms: Queries return context that doesn’t seem relevant.
Causes:
Solutions:
# Try more specific queries
neuralmind query /path "How does JWT authentication work?" # Instead of "auth"
# Use search to understand what's indexed
neuralmind search /path "authentication" --n 20
# Check graph quality
cat /path/graphify-out/GRAPH_REPORT.md
# Rebuild with fresh graph (regenerated automatically)
neuralmind build /path --force
Symptoms: Query returns more tokens than expected (~2000+ instead of ~1000).
Causes:
Solutions:
# For minimal context, use wakeup
neuralmind wakeup /path # L0 + L1 only
# Review project structure
neuralmind stats /path
Symptoms: You know specific code exists but it’s not in the context.
Causes:
Solutions:
# Search directly for the code
neuralmind search /path "function_name" --n 20
# Check if it's in the graph
python -c "
import json
g = json.load(open('graphify-out/graph.json'))
for n in g['nodes']:
if 'function_name' in n.get('name', ''):
print(n)
"
# If not in graph, rebuild (use graphify update /path instead if
# you're on the optional graphify backend)
neuralmind build /path --force
Symptoms: After updating Claude Code itself (not NeuralMind), tool-output token counts feel higher than they used to, or the compression noted in neuralmind benchmark doesn’t match what you observe in Claude Code’s actual usage.
Cause: Claude Code’s hook matcher names and tool dispatch path can change between versions. The most notable change so far: v2.1.117 (April 2026) folded the standalone Grep/Glob tools into Bash on native macOS/Linux builds. Our installed-hooks still cover that case (the Bash matcher catches the rerouted searches), but it’s a useful health check after any Claude Code upgrade.
Diagnosis — run the benchmark:
neuralmind benchmark .
If the reduction ratio dropped sharply vs. your last run (and you didn’t change your project), the hook layer may have regressed. Then check both possible settings files — install-hooks defaults to project scope (<project>/.claude/settings.json), and --global writes to ~/.claude/settings.json. NeuralMind hook blocks are identified by the neuralmind _hook ... command embedded in each block (not by a metadata field). One-liner that scans both:
python - <<'PY'
import json, os
from pathlib import Path
paths = [Path(".claude/settings.json"), Path.home() / ".claude/settings.json"]
for p in paths:
if not p.exists():
print(f"{p}: not present")
continue
cfg = json.loads(p.read_text())
hits = []
for event, blocks in (cfg.get("hooks") or {}).items():
for b in blocks or []:
for h in b.get("hooks") or []:
if "neuralmind _hook" in (h.get("command") or ""):
hits.append(f"{event}/{b.get('matcher', '*')}")
print(f"{p}: {hits if hits else 'no neuralmind hooks'}")
PY
Fix: if neither path lists any blocks, reinstall — match the scope you originally used:
neuralmind install-hooks . # project scope (default)
neuralmind install-hooks . --global # ~/.claude/settings.json
If the block is present but the benchmark still looks off, open an issue with the Claude Code version (claude --version) and the neuralmind benchmark . output — the matcher list may need an update.
NeuralMind’s hooks compress the output of Claude Code’s built-in tools (Read, Bash, Grep, plus rerouted searches on v2.1.117+ native builds). They do not compress responses from third-party MCP servers — MCP tool calls match on mcp__<server>__<tool> patterns, which NeuralMind’s installed block deliberately doesn’t subscribe to (we don’t know what those MCP tools return or whether compression would be safe). If a third-party MCP server is dominating your token bill, that compression is a separate problem from what install-hooks solves.
Symptoms: Claude Desktop or Cursor can’t connect to NeuralMind MCP server.
Causes:
Solutions:
# Test the same operation via CLI first
neuralmind query /path/to/project "test question"
# Check for port conflicts
lsof -i :8080 # If using custom port
Symptoms: Server runs but Claude Desktop doesn’t show NeuralMind tools.
Causes:
Solutions:
~/Library/Application Support/Claude/claude_desktop_config.json%APPDATA%\Claude\claude_desktop_config.json~/.config/Claude/claude_desktop_config.jsoncat ~/Library/Application\ Support/Claude/claude_desktop_config.json | python -m json.tool
{
"mcpServers": {
"neuralmind": {
"command": "neuralmind-mcp"
}
}
}
Symptoms: Claude shows errors when calling NeuralMind tools.
Causes:
Solutions:
# Test the same operation via CLI first
neuralmind query /path/to/project "test question"
# Ensure index is built
neuralmind build /path/to/project
# Check MCP server logs (run manually to see output)
neuralmind-mcp 2>&1 | tee mcp.log
Symptoms: Running Register-ScheduledTask fails with permission error.
Causes:
Solutions:
# MUST run PowerShell as Administrator
# Right-click PowerShell → "Run as administrator"
# Then set execution policy
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
# Now register the task
$trigger = New-ScheduledTaskTrigger -Daily -At 2:00am
$action = New-ScheduledTaskAction -Execute "powershell.exe" -Argument "-NoProfile -ExecutionPolicy Bypass -File C:\scripts\run-neuralmind-all.ps1"
Register-ScheduledTask -TaskName "NeuralMind Suite" -Trigger $trigger -Action $action -RunLevel Highest
Symptoms: Task appears in Task Scheduler but never executes.
Causes:
Solutions:
# Verify task exists and is enabled
Get-ScheduledTask -TaskName "NeuralMind*" | Select-Object TaskName, State
# Check task history
Get-ScheduledTaskInfo -TaskName "NeuralMind Suite"
# Test running manually
Start-ScheduledTask -TaskName "NeuralMind Suite"
# Check results and logs
Get-ScheduledTaskInfo -TaskName "NeuralMind Suite" | Select-Object LastRunTime, LastTaskResult
If task runs but fails silently:
# Bad: powershell.exe -File script.ps1
# Good: C:\Users\username\AppData\Local\Programs\Python\Python311\python.exe script.py
$ErrorActionPreference = "Stop"
try {
cd C:\path\to\project
neuralmind wakeup . 2>&1 | Tee-Object -FilePath "C:\logs\neuralmind.log"
} catch {
Add-Content -Path "C:\logs\error.log" -Value "Error: $_"
exit 1
}
# Run in PowerShell (not scheduled) to see errors
C:\scripts\run-neuralmind-all.ps1
Symptoms: Scheduled task runs but finds “0 initialized projects”.
Causes:
neuralmind.db/ directorySolutions:
# Verify projects are initialized
Get-ChildItem -Path "C:\Users\dtfro\claudecode" -Directory | ForEach-Object {
$hasIndex = Test-Path (Join-Path $_.FullName "neuralmind.db")
Write-Host "$($_.Name): $($hasIndex ? 'Ready' : 'NOT INITIALIZED')"
}
# Initialize missing projects
cd "C:\path\to\project"
neuralmind build .
Symptoms: Cloud sync task runs but doesn’t update repos.
Causes:
Solutions:
# Verify git is accessible
git --version
# Test cloning manually
cd C:\temp
git clone https://github.com/yourname/your-repo.git
# If SSH required, ensure keys are set up
ssh -T git@github.com
# Check repo URLs in sync script
# Should be: https://github.com/owner/repo.git
# NOT: git@github.com:owner/repo.git (unless SSH configured)
Symptoms: Scheduled tasks run but no log files appear in expected directory.
Causes:
Solutions:
# Create log directory if missing
$logDir = "$env:USERPROFILE\Documents\neuralmind-logs"
if (!(Test-Path $logDir)) {
New-Item -ItemType Directory -Path $logDir | Out-Null
}
# Check directory permissions
Get-Acl $logDir
# Manually test logging
$logFile = "$logDir\test.log"
"Test message" | Tee-Object -FilePath $logFile
Get-Content $logFile
Symptoms: Initial build takes a very long time (>5 minutes for medium projects).
Causes:
Solutions:
# Check node count
neuralmind stats /path 2>/dev/null || \
python -c "import json; print(len(json.load(open('graphify-out/graph.json'))['nodes']))"
# For subsequent builds, incremental is automatic
neuralmind build /path # Only embeds changed nodes
# Force rebuild only when necessary
neuralmind build /path --force # Re-embeds everything
Symptoms: Queries take >1 second to return.
Causes:
Solutions:
# First query is slower (loading model), subsequent are faster
time neuralmind query /path "test"
time neuralmind query /path "another test" # Should be faster
# Move database to SSD if on HDD — rebuild after moving
mv graphify-out/neuralmind_db /ssd/path/
neuralmind build /path --force
Symptoms: NeuralMind consumes excessive RAM.
Causes:
Solutions:
# Memory is primarily from:
# - Embedding model: ~100-200MB (unavoidable)
# - ChromaDB: Scales with node count
# - Graph data: Loaded entirely
# For very large projects, consider:
# 1. Excluding test/vendor directories from graphify
# 2. Running on a machine with more RAM
# 3. Using a remote ChromaDB instance
| Code | Meaning | Common Causes |
|---|---|---|
| 0 | Success | Normal completion |
| 1 | General error | Various runtime errors |
| 2 | Invalid arguments | Wrong CLI arguments |
| 3 | Graph not found | graphify not run |
| 4 | Index not built | build command not run |
| 5 | Database error | ChromaDB issues |
| Exception | Meaning | Solution |
|---|---|---|
FileNotFoundError: graph.json |
Knowledge graph missing | Run neuralmind build (regenerates the graph) |
RuntimeError: Index not built |
Embeddings not generated | Run neuralmind build |
chromadb.errors.InvalidCollectionException |
Database corruption | Delete and rebuild database |
MemoryError |
Insufficient RAM | Reduce project size or increase RAM |
ValueError: Empty query |
Query string is blank | Provide a valid question |
#!/bin/bash
# neuralmind_health.sh - Check NeuralMind installation
echo "=== NeuralMind Health Check ==="
# Check installation
echo -n "NeuralMind installed: "
python -c "import neuralmind; print('✓')" 2>/dev/null || echo "✗"
# Check dependencies
echo -n "ChromaDB: "
python -c "import chromadb; print(f'✓ v{chromadb.__version__}')" 2>/dev/null || echo "✗"
echo -n "PyYAML: "
python -c "import yaml; print('✓')" 2>/dev/null || echo "✗"
# Check CLI
echo -n "CLI available: "
which neuralmind >/dev/null && echo "✓" || echo "✗"
# Check graphify
echo -n "Graphify installed: "
which graphify >/dev/null && echo "✓" || echo "✗"
# Check MCP server
echo -n "MCP server: "
which neuralmind-mcp >/dev/null && echo "✓" || echo "✗"
echo ""
echo "=== Version Info ==="
python -c "import neuralmind; print(f'NeuralMind: installed')" 2>/dev/null
python -c "import chromadb; print(f'ChromaDB: {chromadb.__version__}')" 2>/dev/null
python --version
#!/bin/bash
# project_diagnostic.sh - Check project setup
PROJECT="${1:-.}"
echo "=== Project: $PROJECT ==="
# Check graph
if [ -f "$PROJECT/graphify-out/graph.json" ]; then
echo "✓ Knowledge graph exists"
NODE_COUNT=$(python -c "import json; print(len(json.load(open('$PROJECT/graphify-out/graph.json'))['nodes']))")
echo " Nodes: $NODE_COUNT"
else
echo "✗ Knowledge graph missing (run: neuralmind build $PROJECT)"
fi
# Check index
if [ -d "$PROJECT/graphify-out/neuralmind_db" ]; then
echo "✓ NeuralMind index exists"
DB_SIZE=$(du -sh "$PROJECT/graphify-out/neuralmind_db" | cut -f1)
echo " Size: $DB_SIZE"
else
echo "✗ NeuralMind index missing (run: neuralmind build $PROJECT)"
fi
# Test query
if [ -d "$PROJECT/graphify-out/neuralmind_db" ]; then
echo ""
echo "=== Test Query ==="
time neuralmind wakeup "$PROJECT" | head -20
fi
When opening a GitHub issue, include:
**Environment**
- OS: [e.g., Ubuntu 22.04, macOS 14, Windows 11]
- Python version: [output of `python --version`]
- NeuralMind version: [output of `pip show neuralmind`]
- ChromaDB version: [output of `pip show chromadb`]
**Steps to Reproduce**
1. ...
2. ...
**Expected Behavior**
What should happen.
**Actual Behavior**
What actually happens.
**Error Output**
Paste full error message here
**Additional Context**
- Project size (number of nodes)
- First time or worked before?
- Any recent changes?