-
Notifications
You must be signed in to change notification settings - Fork 0
FAQ
Quick answers to common NeuralMind questions.
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 ChromaDBAnswer: 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 filesAnswer: Yes — since v0.38.0, NeuralMind uses hybrid search (BM25 + vector) by
default. BM25 uses code-aware tokenisation, so queries like "UserService" or
"get_auth_token" score exact name matches above semantically similar but
textually different nodes.
neuralmind search . "UserService" # BM25 exact-name match + semantic, merged via RRF
neuralmind query . "UserService" # Full 4-layer context, hybrid L3 searchSet NEURALMIND_BM25=0 to revert to pure vector search if needed.
For raw string grep across files (not structured retrieval):
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 directoryReasons:
-
Index changed — Code was updated, rebuild with
neuralmind build . - Learning kicked in — NeuralMind learns from your queries (improvement!)
- Randomness — Small variations in embedding similarity
Solution: Results should be consistent. If they vary significantly, rebuild:
neuralmind build . --forceNo!
- Initial build is 1-2 min per 10K nodes
- Queries are <100ms
- Works for 1M+ LOC codebases
For large projects:
# Use PostgreSQL backend (scales to 10M+ nodes)
neuralmind build . --backend postgres --db-url postgresql://...Rough estimates:
- 100K LOC → 50-100 MB
- 500K LOC → 200-500 MB
- 1M LOC → 500MB-2GB
- 10M LOC → 5-20GB
Full size / index-time / memory envelope — with the honest "not yet measured at scale" caveats — is on the Limits & Failure Modes page.
Compress if needed:
# Delete old indexes
rm -rf neuralmind.db
# Rebuild with optimization
neuralmind build . --optimizeOne codebase is the unit — and where NeuralMind is strongest. Everything
is anchored to a single project root: the index in graphify-out/, and the
embeddings plus the learned synapse memory in .neuralmind/. One root = one
index + one namespaced memory.
-
A monorepo counts as one codebase and is fully supported. Retrieval is
community/cluster-aware, and builds are incremental —
neuralmind build .re-embeds only changed nodes, so build time scales with churn, not repo size. (See the Growing Monorepo use case.) -
Several separate repos → run one NeuralMind per repo. There's no
cross-repo "workspace" store today; each repo is its own independent brain
with its own
.neuralmind/. Nothing stops you running it on ten repos — they're just ten separate stores, not one unified one. - The memory compounds per codebase. The synapse layer learns associations from how you actually work in that repo, so sustained use on one codebase sharpens recall over time. Splitting attention across many repos means each accumulates less learning signal.
Within a single codebase it's still flexible: memory namespaces isolate
branch:<name> / personal / shared, multiple agents (Claude Code,
Cursor, Cline) share the one store, and even multiple git worktrees can share
it with per-branch isolation.
Supported (built-in tree-sitter, no graphify needed):
- Python, TypeScript/JavaScript, Go, Rust, Java, C, C++, C#, Ruby, PHP
- Plus schema/doc artifacts: Markdown, OpenAPI/AsyncAPI (YAML), SQL DDL, Protocol Buffers
Partial support:
- Other languages can be indexed as plaintext (less precise)
The per-language support matrix spells out exactly what's indexed and what's explicitly not modeled per language (C/C++ macros & templates, dynamic-dispatch call resolution, SQL
ALTER/SELECT, proto imports, OpenAPI$ref, …).
If not supported:
# Use `--format any` to treat as plaintext
neuralmind build . --format any
# Still works, just less preciseYes, 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)
# NeuralMind indexes only local code and makes no calls of its ownOption 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.comNo.
- ✅ 100% local processing
- ✅ No cloud APIs
- ✅ No telemetry
- ✅ No network calls of its own
# 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 resultsYes! NeuralMind is built for compliance:
- ✅ NIST AI RMF audit trail
- ✅ SOC 2 compliance mapping
- ✅ GDPR-compliant (local processing)
- ✅ HIPAA-friendly (local processing, no calls home)
pip install --upgrade neuralmind
# Or install with dev extras (testing/linting tools)
pip install "neuralmind[dev]"Solutions:
-
Rebuild index — Code changed, index is stale
neuralmind build . --force -
Ask better questions — Be more specific
# Bad: "How does it work?" # Good: "How does user authentication work?"
-
Let learning warm up — NeuralMind improves with use, automatically via the synapse layer (no manual step). Install the hooks and optionally the watcher, then check what's been learned:
neuralmind install-hooks . neuralmind watch & # optional: learn from file edits neuralmind memory inspect . # see what the synapse layer has learned
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 andserveboth 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_LOGis not set to0. This env var disables the JSONL writer. If it's set in your shell config or the parent process of eitherserveorwatch, 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 servewas started from~/projects/fooandneuralmind watchfrom~/projects/foo/src/. They write to different.neuralmind/events.jsonlfiles and never see each other. Run both from the project root, or pass an explicitproject_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
PostToolUsehooks for file events, those only fire on tool calls — they won't see your manual editor saves. For editor-driven pulses, startneuralmind watchseparately: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 URLserveprinted). -
The synapse store is being reinforced. If no agent is calling
neuralmind_queryor 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 30Yes!
- ✅ MIT License (fully open source)
- ✅ No subscription
- ✅ No usage limits
- ✅ Self-hosted (no cloud costs)
Yes! MIT License allows commercial use:
- ✅ Use in products
- ✅ Use in services
- ✅ Use in enterprises
- ✅ Modify for your needs
Just include the license text.
Coming in v1.0 (Q1 2027):
- Priority bug fixes
- Deployment consulting
- Custom integrations
- SLA guarantees
| 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:
- Copilot — Code completions, inline suggestions
- NeuralMind — Code understanding, context retrieval
Use both together for maximum productivity.
- 📖 GitHub Discussions
- 🐛 Report Issues
- 📧 Email: contact@company.com
# 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 outputYes! See CONTRIBUTING.md