Quick answers to common NeuralMind questions.
neuralmind command not found”Solution:
# Check if installed
pip show neuralmind
# If installed, find where
python -c "import site; print(site.USER_BASE + '/bin')"
# Add to PATH (Linux/macOS)
export PATH="$HOME/.local/bin:$PATH"
# Add to PATH (Windows PowerShell)
$env:Path += ";$env:APPDATA\Python\Python311\Scripts"
(Only relevant if you installed the optional graphify backend — since v0.15.0 NeuralMind builds the code graph itself.)
Solution: The command changed in newer versions. Use:
graphify update . # New (v1.2+)
# NOT: graphify build .
Solutions:
# 1. First build is slow (one-time)
# Subsequent builds are incremental and fast
# 2. Exclude unnecessary files
# Add to neuralmind.toml:
# [build]
# exclude_patterns = ["*.test.js", "node_modules/", "dist/"]
# 3. Use faster backend
neuralmind build . --backend lancedb # Faster than ChromaDB
Answer: NeuralMind searches semantically across your entire codebase automatically.
# Just ask a question about the whole project
neuralmind query . "How is data validation handled throughout the codebase?"
# It will find relevant validation code in multiple files
Answer: Use neuralmind search for semantic search:
neuralmind search . "authentication" # Semantic: finds related code
For exact string matching, use your editor or grep:
grep -r "authenticate" src/
Solutions:
# 1. Ask more specific questions
neuralmind query . "How does password validation work?" # Better than "How does auth work?"
# 2. Use JSON output and parse it
neuralmind query . "What endpoints are available?" --json | jq '.results | length'
# 3. Narrow scope
neuralmind query src/auth/ "How does login work?" # Limits to one directory
Reasons:
neuralmind build .Solution: Results should be consistent. If they vary significantly, rebuild:
neuralmind build . --force
No!
For large projects:
# Use PostgreSQL backend (scales to 10M+ nodes)
neuralmind build . --backend postgres --db-url postgresql://...
Rough estimates:
Compress if needed:
# Delete old indexes
rm -rf neuralmind.db
# Rebuild with optimization
neuralmind build . --optimize
Supported:
Partial support:
If not supported:
# Use `--format any` to treat as plaintext
neuralmind build . --format any
# Still works, just less precise
Yes, but consider excluding them:
# neuralmind.toml
[build]
exclude_patterns = [
"*.test.js",
"*.spec.py",
"test/",
"tests/"
]
Why? Test code clutters the index without adding understanding.
Yes!
# If your project uses private packages, NeuralMind indexes:
# 1. Your code (always)
# 2. Local node_modules / site-packages (yes)
# 3. External PyPI/npm packages (no, stays private)
# Nothing leaves your machine
Option 1: Local per-developer (simplest)
# Each developer on their machine
neuralmind build .
neuralmind install-hooks .
Pros: Simple, fully private
Cons: Index duplication
Option 2: Shared PostgreSQL backend (enterprise)
# Setup: Central PostgreSQL database
# Each developer points to it:
neuralmind build . --backend postgres --db-url postgresql://...
Pros: Single source of truth, auditable
Cons: Requires infrastructure
Yes, with MCP server + RBAC:
# Launch MCP with access control
neuralmind-mcp . --rbac-enabled \
--admin-users alice@company.com \
--developer-users bob@company.com,charlie@company.com \
--viewer-users intern@company.com
No.
# 1. Scan for secrets before building
neuralmind scan-for-secrets .
# 2. Fix exposed secrets
# (Remove from code, regenerate tokens)
# 3. Build with redaction enabled
neuralmind build . --redact-secrets
# 4. Verify
neuralmind search . "password" # Should return no results
Yes! NeuralMind is built for compliance:
pip install --upgrade neuralmind
# Or install with dev extras (testing/linting tools)
pip install "neuralmind[dev]"
Solutions:
neuralmind build . --force
# Bad: "How does it work?"
# Good: "How does user authentication work?"
neuralmind install-hooks .
neuralmind watch & # optional: learn from file edits
neuralmind memory inspect . # see what the synapse layer has learned
serve canvas stay quiet when I edit files?” (v0.6.0+)You ran neuralmind serve, opened the graph view, edited a file in
your editor — and no node pulsed. The live feed (v0.6.0) depends on
two paths working: the in-process event bus, and the cross-process
JSONL bridge. When the canvas is silent, one of these is the
culprit. Check in this order:
.neuralmind/ directory exists in the project root. The
JSONL bridge writes to <project>/.neuralmind/events.jsonl,
which the watcher and serve both need to find. If the directory
doesn’t exist (fresh clone, or you blew it away):
neuralmind build . # creates .neuralmind/ alongside graphify-out/
NEURALMIND_EVENT_LOG is not set to 0. This env var
disables the JSONL writer. If it’s set in your shell config or
the parent process of either serve or watch, the in-process
feed still works for the same process but cross-process events
never reach the canvas.
env | grep NEURALMIND_EVENT_LOG # should be empty or =1
unset NEURALMIND_EVENT_LOG # clear it if set
Both processes target the same project root. A common gotcha:
neuralmind serve was started from ~/projects/foo and
neuralmind watch from ~/projects/foo/src/. They write to
different .neuralmind/events.jsonl files and never see each
other. Run both from the project root, or pass an explicit
project_path:
neuralmind serve /abs/path/to/project &
neuralmind watch /abs/path/to/project &
The file watcher is actually running. If you’re relying on
Claude Code’s PostToolUse hooks for file events, those only
fire on tool calls — they won’t see your manual editor saves.
For editor-driven pulses, start neuralmind watch separately:
neuralmind watch . --quiet &
The browser tab actually has the SSE stream open. Open the
browser devtools network tab and look for a long-lived request
to /api/events. If it’s missing or 404, refresh the page; if it
401s, your token expired (re-open the URL serve printed).
The synapse store is being reinforced. If no agent is
calling neuralmind_query or any other NeuralMind MCP tool, the
synapse store has nothing to publish — the canvas pulses only
when something actually happens. Trigger one manually:
neuralmind query . "test query"
You should see a pulse within ~1s.
If the canvas still stays quiet after all six, that’s a bug — open
an issue with the output of neuralmind stats . and a
description of what you tried.
# Check port is free
lsof -i :8000
# Run with debug output
NEURALMIND_DEBUG=1 neuralmind-mcp . --port 8000
# Check configuration
neuralmind backend-check
# Test connection
psql -h db.company.com -U neuralmind -d neuralmind -c "SELECT 1;"
# Check URL format
# postgresql://username:password@hostname:port/database
# Set connection timeout
neuralmind build . --backend postgres --db-timeout 30
Yes!
Yes! MIT License allows commercial use:
Just include the license text.
Coming in v1.0 (Q1 2027):
| Feature | NeuralMind | Cursor |
|---|---|---|
| Works everywhere | ✅ Yes | ❌ Cursor only |
| 100% offline | ✅ Yes | ❌ Cloud |
| Token reduction | 5-10× | 2-3× |
| Cost | Free | Paid (Cursor) |
| Open source | ✅ Yes | ❌ No |
Claude 3.5 Sonnet:
- Input: $3/1M tokens
- Output: $15/1M tokens
Traditional (50K tokens):
- Cost: $0.15 per query
With NeuralMind (800 tokens):
- Cost: $0.0024 per query
- Savings: 60× cheaper
Even with 200K token context limit available,
NeuralMind is 10× cheaper because the prompt is small.
No, they’re complementary:
Use both together for maximum productivity.
# 1. Reproduce the issue
# 2. Collect debug info
neuralmind --version
python --version
uname -a
# 3. Open GitHub issue with:
# - Clear title
# - Reproduction steps
# - Expected vs actual behavior
# - Debug output
Yes! See CONTRIBUTING.md