-
Notifications
You must be signed in to change notification settings - Fork 0
Usage Guide
Complete guide to features, use cases, and scheduling routines for NeuralMind
- What is NeuralMind?
- Key Features
- The 4-Layer Architecture
- Quick Start
- Use Cases
- CLI Command Reference
- Scheduling Routines
- ROI Calculator
- MCP Server Integration
- Troubleshooting
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, andGrepoutput 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.
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
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.
| Feature | Description | Benefit |
|---|---|---|
| 4-Layer Context | Progressive disclosure architecture | Only loads what's relevant |
| Semantic Search | Vector embeddings for meaning-based lookup | Finds related code by concept |
| Query-Aware | Different queries get different context | Maximizes relevance |
| CLI Tool | Simple command-line interface | Easy integration |
| MCP Server | Direct IDE integration | Works with Claude Desktop/Cursor |
| Auto-Updates | Scheduled maintenance | Always current knowledge |
┌─────────────────────────────────────────────────────────────┐
│ 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
- Graphify analyzes your codebase and creates a knowledge graph
- NeuralMind creates vector embeddings of all code entities
- When you query, it selects only relevant context using semantic similarity
- You get focused, accurate context that fits in any LLM's context window
pip install neuralmind graphifyycd your-project
graphify update .neuralmind build .# 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?"# 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/CursorWhen: 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 answerBenefit: 100 queries/day goes from $450/month → $7/month with Claude 3.5 Sonnet
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.mdBenefit: New devs get accurate answers without constantly asking senior devs
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
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.mdBenefit: AI-assisted documentation that's accurate to actual code
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 graphifyy
- name: Update knowledge graph
run: graphify update .
- 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 pushBenefit: Always up-to-date context file in your repo
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
watchdaemon 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:
- Open Claude Code (terminal A) and ask "how does authentication work in this codebase?"
- Switch to terminal B's browser tab — the auth-cluster nodes are
pulsing as the agent calls
neuralmind_query. - In your editor, open
src/auth/handlers.py, add a comment, save. - Switch back to the browser — the corresponding node pulses within ~1s.
- 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).
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
| Command | Purpose | Example |
|---|---|---|
neuralmind build . |
Build/rebuild neural index | First-time setup, after major changes |
neuralmind query . "..." |
Query with natural language | Daily usage |
neuralmind wakeup . |
Get project overview | Start new AI conversations |
neuralmind search . "..." |
Direct semantic search | Find specific code entities |
neuralmind learn . |
NEW Analyze query patterns → improve ranking | After collecting queries |
neuralmind benchmark . |
Measure token reduction | Verify cost savings |
neuralmind stats . |
Show index statistics | Check index health |
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
graphify update . && neuralmind build .When to use: After initial setup, after significant code changes, weekly maintenance.
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?" | pbcopyWhen to use: Every time you want to ask AI about your code.
Returns the project overview (L0 + L1 layers) for starting new conversations.
# Get wakeup context
neuralmind wakeup .
# Save as project overview
neuralmind wakeup . > PROJECT_OVERVIEW.mdWhen to use: Starting a new Claude/ChatGPT conversation about your project.
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.
Analyzes your query history to discover module relationships and improve ranking.
# After collecting queries, analyze patterns
neuralmind learn .
# Example output:
# Analyzing 8 query events...
# ✓ Learned 12 cooccurrence patterns
# ✓ Patterns saved to .neuralmind/learned_patterns.json
# ✓ Next query will apply learned patterns for improved retrieval
#
# Top cooccurrence patterns:
# community_0|community_1: 5 times
# community_1|community_2: 4 times
# community_0|community_2: 3 timesWhat it does:
- Reads query events from
.neuralmind/memory/query_events.jsonl - Finds which code modules appear together in successful queries
- Saves patterns to
.neuralmind/learned_patterns.json - On next query, automatically boosts related modules in search results
When to use: After 5-10 queries have been logged to build meaningful patterns. Run weekly for continuous improvement.
How it improves retrieval:
- Example: If you frequently query about "auth" + "validation" together
- System learns this pattern (cooccurrence score: high)
- Next time you ask about auth, validation automatically gets boosted in results
- Better relevance = smaller context needed = more token savings
Privacy: 100% local analysis. No data sent anywhere. Patterns file is just JSON in your project.
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.
Shows index statistics.
# View stats
neuralmind stats .
# Example output:
# Nodes: 241
# Edges: 203
# Communities: 93
# Index size: 12.4 MBWhen to use: Checking index health, monitoring project growth.
| Scenario | Recommended Action | Frequency |
|---|---|---|
| Active development | Git hook on commit | Every commit |
| Team project | Automated CI/CD | On merge to main |
| Stable codebase | Scheduled maintenance | Weekly |
| Before code review | Manual update | As needed |
| After major refactor | Full rebuild | Immediately |
Automatically update the index after every commit:
# Create post-commit hook
cat > .git/hooks/post-commit << 'EOF'
#!/bin/bash
echo "🧠 Updating NeuralMind index..."
graphify update . 2>/dev/null
neuralmind build . 2>/dev/null
echo "✓ NeuralMind index updated"
EOF
# Make it executable
chmod +x .git/hooks/post-commit# Edit crontab
crontab -e
# Daily update at 6 AM
0 6 * * * cd /path/to/project && graphify update . && neuralmind build . >> /var/log/neuralmind.log 2>&1
# Weekly update on Monday at 3 AM
0 3 * * 1 cd /path/to/project && graphify update . && neuralmind build . >> /var/log/neuralmind.log 2>&1# .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 graphifyy
- run: graphify update .
- run: neuralmind build .
- run: neuralmind stats .Weekly maintenance routine:
#!/bin/bash
# weekly_maintenance.sh
echo "🔧 NeuralMind Weekly Maintenance"
echo "================================"
# Update knowledge graph
echo "1. Updating knowledge graph..."
graphify update .
# Rebuild neural index
echo "2. Rebuilding neural index..."
neuralmind build .
# Show stats
echo "3. Current statistics:"
neuralmind stats .
# Run benchmark
echo "4. Benchmark results:"
neuralmind benchmark .
echo ""
echo "✅ Maintenance complete!"| Model | Input Price | Without NeuralMind | With NeuralMind | Per-Query Savings |
|---|---|---|---|---|
| Claude 3.5 Sonnet | $3/1M tokens | $0.15/query | $0.0023/query | $0.1477 (98.5%) |
| GPT-4o | $5/1M tokens | $0.25/query | $0.0038/query | $0.2462 (98.5%) |
| GPT-4.5 | $75/1M tokens | $3.75/query | $0.0574/query | $3.6926 (98.5%) |
| Claude Opus | $15/1M tokens | $0.75/query | $0.0115/query | $0.7385 (98.5%) |
| Gemini 2.5 Pro | $2.50/1M tokens | $0.125/query | $0.0019/query | $0.1231 (98.5%) |
| Daily Queries | Claude 3.5 Sonnet | GPT-4o | GPT-4.5 | Claude Opus |
|---|---|---|---|---|
| 10 queries/day | $44/month | $74/month | $1,107/month | $221/month |
| 50 queries/day | $221/month | $369/month | $5,539/month | $1,108/month |
| 100 queries/day | $443/month | $738/month | $11,078/month | $2,216/month |
| 500 queries/day | $2,216/month | $3,693/month | $55,389/month | $11,078/month |
| Usage Level | Annual Savings (Claude 3.5) | Annual Savings (GPT-4.5) |
|---|---|---|
| Light (10/day) | $531 | $13,284 |
| Medium (50/day) | $2,658 | $66,468 |
| Heavy (100/day) | $5,316 | $132,936 |
| Enterprise (500/day) | $26,580 | $664,668 |
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.
- Install NeuralMind (the MCP server is included by default since v0.5.0):
pip install neuralmind- 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"]
}
}
}- Restart Claude Desktop
| Tool | Description |
|---|---|
neuralmind_wakeup |
Get project overview |
neuralmind_query |
Query with natural language |
neuralmind_search |
Direct semantic search |
neuralmind_build |
Rebuild index |
neuralmind_stats |
Show index statistics |
neuralmind_benchmark |
Run token benchmark |
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.
# Solution: Run graphify first
graphify update .
neuralmind build .# Solution: Rebuild the index
graphify update .
neuralmind build .# Solution: Clear and rebuild
rm -rf graphify-out/neuralmind_db
neuralmind build .# Solution: Reinstall
pip uninstall neuralmind
pip install neuralmind- GitHub Issues: https://github.com/dfrostar/neuralmind/issues
- Wiki: https://github.com/dfrostar/neuralmind/wiki
- Discussions: https://github.com/dfrostar/neuralmind/discussions
See CONTRIBUTING.md for guidelines.
MIT License - see LICENSE for details.