CLI Reference

Complete command-line interface documentation for NeuralMind.

Table of Contents

• Overview
• Global Options
• Commands
  • build
  • scan-for-secrets
  • query
  • wakeup
  • search
  • benchmark
  • probe
  • stats
  • validate
  • doctor
  • eval
  • ingest-content
  • learn — document ingestion
  • learn (deprecated, pre-v1.11.0)
  • self-improve status
  • next
  • memory
  • skeleton
  • structural
  • last
  • install-hooks
  • init-hook
  • drift
  • compliance
  • ci-check
  • export
  • watch
  • serve
  • daemon
  • savings
  • review
  • onboarding
  • optimize-docs
• Exit Codes
• Environment Variables
• Examples

Overview

NeuralMind provides a command-line interface for building neural indexes, querying codebases with natural language, and managing knowledge graphs.

neuralmind [OPTIONS] COMMAND [ARGS]

Getting Help

# General help
neuralmind --help

# Command-specific help
neuralmind build --help
neuralmind query --help

Global Options

Commands

audit recent (v3.1.4+)

Query recent audit trail events.

Arguments

Output

Recent audit events in tabular format.

Examples

# Show last 10 audit events
neuralmind audit recent

# Show last 20 events since a specific date
neuralmind audit recent -n 20 --since "2026-08-01"

# Show only backend builds
neuralmind audit recent --category backend --action build

Prerequisites

Requires an initialized project with audit trail.

build

Build or rebuild the neural index from a knowledge graph.

neuralmind build <project_path> [OPTIONS]

Arguments

Options

Output

Displays build statistics including:

• Number of nodes processed
• Number of nodes embedded (new/changed)
• Number of nodes skipped (unchanged)
• Number of communities indexed
• Build time elapsed

Examples

# Basic build
neuralmind build /path/to/project

# Force complete rebuild
neuralmind build /path/to/project --force

# Estimate token savings without building (Gap 1: 1-click setup)
neuralmind build /path/to/project --dry-run
# → NeuralMind dry run — my-project
# →   Files scanned : 142
# →   Lines of code : 18,342
# →   Languages     : 89 Python, 53 TypeScript
# →   Est. token reduction  : ~42x per query
# →   No index was built. Run `neuralmind build .` to activate these savings.

Prerequisites

As of v0.15.0, none beyond pip install neuralmind. When no graphify-out/graph.json exists, build auto-generates one with the bundled tree-sitter backend (neuralmind/graphgen.py) and prints:

[neuralmind] generated code graph via the built-in tree-sitter backend → graphify-out/graph.json

Backend precedence:

1. A real graphify graph always takes priority where present (graphify update /path/to/project).
2. Otherwise the built-in tree-sitter backend generates the graph. It indexes Python, TypeScript, Go, Rust, Java, C, C++, C#, Ruby, and PHP (.py, .ts/.tsx, .go, .rs, .java, .c/.h, .cpp/.cc/.cxx/.hpp/.hh/.hxx, .cs, .rb, .php) out of the box (Java added in v0.28.0; C and C++ in v0.32.0; C# in v0.35.0; Ruby in v0.36.0; PHP in v0.37.0); more grammars register behind the SUPPORTED_SUFFIXES seam. A mixed-language repo is indexed in one pass. Schema artifacts (v0.40.0+) are indexed alongside code as document nodes: OpenAPI/AsyncAPI specs (.yaml/.yml with an openapi/asyncapi/swagger key) emit nodes per path+method, schema component, and channel; SQL DDL (.sql) emits one node per CREATE object; Protocol Buffers (.proto) emit nodes per message, service, rpc, and enum. Plain YAML config files are silently skipped.
3. --force only regenerates graphs we wrote — it never clobbers a graphify build.
4. An empty/non-code project writes no graph, so you still get the “no graph” guidance rather than a silent 0-node success.
5. Optional precision (v0.17.0+): set NEURALMIND_PRECISION=1 and place a *.scip index (from scip-python/scip-typescript/scip-go) in the project root to replace the built-in backend’s heuristic calls/inherits edges with compiler-accurate ones for the files the index covers. Off by default.

6. Secret redaction (opt-in): --redact-secrets (or NEURALMIND_REDACT_SECRETS=1) replaces detected credentials with [REDACTED:<kind>] in embedded text — document chunks and node descriptions — on all three backends. Off by default, because redacting costs recall on legitimately secret-shaped identifiers.

   What it does not cover. Node labels, graphify-out/graph.json and .neuralmind/index_ir.json are written before the embedding step, so a credential inside a symbol name or docstring still reaches those files verbatim (on every backend — this is not backend-specific). Verify with grep -r '<the-secret>' graphify-out/ .neuralmind/ after a build if it matters to you.

   The flag is a backstop for text that reaches the vector store, not a guarantee that no artifact under the project holds the credential. Run neuralmind scan-for-secrets . first — removing and rotating is the actual fix. The build also warns if git is already tracking files under .neuralmind/.

scan-for-secrets

Report credentials present in a project’s files, so they can be removed and rotated before they reach the index, a commit, or an agent’s context.

neuralmind scan-for-secrets [PROJECT_PATH] [--high-confidence-only] [--strict]
                            [--use-neuralmindignore] [--json]

NeuralMind secret scan — /home/dev/myproject

  [HIGH ] .env:1  anthropic-api-key  (sk-a…(43 chars))
  [HIGH ] src/config.py:8  aws-access-key-id  (AKIA…(20 chars))
  [maybe] src/db.py:34  generic-secret-assignment  (9f8K…(28 chars))

  2 high-confidence, 1 heuristic.

Two confidence tiers. HIGH matches a vendor-specific shape and effectively never fires on prose: Anthropic and OpenAI keys, AWS access key IDs and secret keys, GitHub tokens and fine-grained PATs, Slack tokens, Google API keys, Stripe keys, PyPI and npm tokens, PEM private-key blocks, JWTs, Authorization: Bearer/Basic headers, and passwords embedded in database connection strings. maybe matches a generic SECRET=value assignment that cleared a Shannon-entropy threshold and a placeholder denylist — so password = "changeme", api_key = os.environ["X"], and KEY=${VAR} are not reported.

Previews never include the tail of a secret — only a short prefix and a length — so scan output is safe to paste into an issue or a CI log.

Exit codes, so this works as a CI gate:

The scanner reads files directly rather than going through the indexer, so it sees .env and other files build never parses. It skips the usual vendored/build directories (node_modules, .venv, dist, target, .git, .neuralmind), binary files, and anything over 5 MB.

.neuralmindignore is not applied by default. That file is tuned for retrieval quality, not security — NeuralMind’s own copy excludes docs/, *.md and tests/ because markdown dilutes code retrieval. A scanner that inherited it would skip exactly where credentials tend to sit and report a false all-clear. Pass --use-neuralmindignore if you want those globs applied anyway.

Related: neuralmind build . --redact-secrets scrubs detected credentials out of indexed text as a backstop — it does not remove the credential from your working tree, and it is not a substitute for rotating a key that has already been exposed.

query

Query the codebase with natural language and get optimized context.

neuralmind query <project_path> "<question>" [OPTIONS]

Type Filter (v3.1.4+)

Filter results by node type:

Cross-Project Search (v3.1.4+)

Query across multiple indexed projects:

neuralmind query --projects /repo/a,/repo/b "authentication logic"

Results are tagged with source project and deduplicated by ID.

Arguments

Options

Output

Returns:

• Optimized context text for AI consumption
• Token count and breakdown by layer
• Reduction ratio compared to full codebase
• Communities/modules loaded

Retrieval traces (v0.23.0+)

--trace explains why a result came back (PRD 3) — useful when retrieval surprises you. It records, layer by layer:

• candidates — the raw vector-search pool (ids + scores);
• cluster_scores — per-cluster score with vector-vs-synapse attribution (how much of each cluster’s score came from learned co-activation);
• synapse_boost — individual co-activation boosts;
• hits — the final ranked hits, flagging which were synapse-recalled;
• budget — tokens per layer + reduction ratio.

Plain --trace prints a compact per-layer summary; --json includes the full trace object (bounded, and path-redactable via the RetrievalTrace API for sharing in bug reports). Tracing is off by default and zero-overhead. The daemon’s /query honors trace too, so daemon and direct mode return the same attribution.

Relevance sidecar (v0.41.0+)

--relevance (with --json) attaches a structured relevance block so a downstream compressor can tell which spans are load-bearing and must survive compression. NeuralMind already computes a vector score, a learned synapse boost, and a recall flag per retrieved node; the sidecar exposes them as machine-readable metadata keyed by source file (plus best-effort line spans from the graph), built from the post-boost L3 hits so it reflects the same signals the rendered context used:

{
  "relevance": {
    "version": 1,
    "files": {
      "auth/handlers.py": {
        "max_score": 1.02,
        "nodes": [
          {"node_id": "…", "label": "authenticate", "score": 0.87,
           "synapse_boost": 0.15, "recalled": true, "lines": [42, 68]}
        ]
      }
    }
  }
}

The version field guards the wire shape; the stable files{} / node_id keys let a tool running after NeuralMind re-associate the signal regardless of pipeline order. The same block is available over MCP via neuralmind_query(include_relevance=true). Off by default — query output is unchanged unless requested. --relevance and --explain both run in direct mode (they need the full result the daemon’s thin response omits).

Examples

# Basic query
neuralmind query /path/to/project "How does authentication work?"

# JSON output
neuralmind query /path/to/project "What are the main API endpoints?" --json

# Explain the retrieval path (raw trace)
neuralmind query /path/to/project "How does billing work?" --trace
neuralmind query /path/to/project "How does billing work?" --trace --json

# Human-friendly explanation of why this context was chosen (v0.39.0+)
neuralmind query /path/to/project "auth flow" --explain
# → Why this context?
# →   Token budget breakdown:
# →     L0 identity   :    142 tokens
# →     L1 summary    :    513 tokens
# →     L2 communities:    800 tokens
# →     L3 search     :    980 tokens
# →     Total used    :  2,435 tokens
# →     Est. saved    : 47,565 tokens  (20.5x reduction)
# →   Top search hits (L3, 4 nodes):
# →     0.912  authenticate  (auth/handlers.py)
# →     0.887  JWTMiddleware  (auth/middleware.py)

Sample Output

=== Query: How does authentication work? ===

[Context]
# Project: MyApp
MyApp is a web application with JWT-based authentication...

[Authentication Module]
The auth module handles user login, token generation, and validation...

[Relevant Code]
- auth/jwt_handler.py: JWT token generation and validation
- auth/middleware.py: Authentication middleware for routes
- models/user.py: User model with password hashing

---
Tokens: 847 | Reduction: 59.0x | Layers: L0, L1, L2, L3 | Communities: [5, 12]

wakeup

Get minimal wake-up context for starting a new conversation.

neuralmind wakeup <project_path> [OPTIONS]

Arguments

Options

Output

Returns L0 (Identity) + L1 (Summary) context, typically ~600 tokens, suitable for:

• Starting new AI conversations
• Providing project context to coding assistants
• Initial system prompts

Examples

# Get wake-up context
neuralmind wakeup /path/to/project

# Redirect to file
neuralmind wakeup /path/to/project > context.md

# JSON format
neuralmind wakeup /path/to/project --json

Sample Output

=== Wake-up Context ===

# Project: MyApp

MyApp is a full-stack web application for task management built with React and Node.js.

## Architecture Overview

### Core Components
- **Frontend**: React 18 with TypeScript, Tailwind CSS
- **Backend**: Node.js/Express REST API
- **Database**: PostgreSQL with Prisma ORM
- **Auth**: JWT-based authentication

### Main Modules
1. User Management (users/) - Registration, profiles, settings
2. Task Engine (tasks/) - CRUD operations, scheduling, notifications
3. API Layer (api/) - REST endpoints, middleware, validation

---
Tokens: 412 | Layers: L0, L1

search

Perform direct semantic search across codebase entities.

neuralmind search <project_path> "<query>" [OPTIONS]

Arguments

Options

Output

Returns matching code entities with:

• Entity name and type
• Similarity score (0-1)
• File path
• Community membership

Examples

# Basic search
neuralmind search /path/to/project "authentication"

# Limit results
neuralmind search /path/to/project "database connection" --n 5

# JSON output
neuralmind search /path/to/project "API endpoint" --json

Sample Output

=== Search: authentication ===

1. authenticate_user (function) - Score: 0.92
   File: auth/handlers.py
   Validates user credentials and returns JWT token
   Community: 5 (Authentication)

2. AuthMiddleware (class) - Score: 0.87
   File: auth/middleware.py
   Express middleware for JWT validation
   Community: 5 (Authentication)

3. hash_password (function) - Score: 0.81
   File: utils/crypto.py
   Securely hashes passwords using bcrypt
   Community: 5 (Authentication)

---
Results: 3 | Query time: 45ms

benchmark

Run performance benchmark with sample queries.

neuralmind benchmark <project_path> [OPTIONS]

Arguments

Options

Output

Comprehensive benchmark report including:

• Token counts for each query type
• Reduction ratios
• Query latencies
• Comparison with full codebase size

Examples

# Run default benchmark
neuralmind benchmark /path/to/project

# JSON output
neuralmind benchmark /path/to/project --json

Quality-eval mode (v0.23.0+)

--quality switches the command from token-reduction benchmarking to retrieval-quality measurement: does NeuralMind surface the right code, not just less of it? It scores precision@k, recall@k, MRR, and answerability over golden query suites (Python / TypeScript / Go — 30 queries with expected-module labels) and exits non-zero if a suite regresses past its floor, so CI can gate retrieval-affecting changes.

Like neuralmind eval, this is a contributor/CI self-test that runs against the golden suites shipping with the source repo (the evals/quality/ package), not the installed wheel. The pure metrics live in neuralmind.quality (from neuralmind import quality).

# Score all golden suites
neuralmind benchmark --quality

# One language, machine-readable
neuralmind benchmark --quality --suite go --json

# Compare against the committed measured baseline (reports metric deltas)
neuralmind benchmark --quality --baseline evals/quality/baseline.json

# Dependency-free validation of the suites + metric math (no embeddings)
python -m evals.quality.runner --selfcheck

Sample (markdown) output — measured on the committed fixtures:

## NeuralMind retrieval-quality eval

| Suite | Queries | MRR | Answerability | Recall@5 | Precision@5 | Gate |
|-------|--------:|----:|--------------:|---------:|------------:|:----:|
| `go`         | 10 | 0.950 | 100% | 0.833 | 0.603 | PASS |
| `python`     | 10 | 0.900 | 100% | 0.833 | 0.612 | PASS |
| `typescript` | 10 | 0.900 | 100% | 0.800 | 0.562 | PASS |

**Overall: PASS**

The exit code is non-zero if any suite drops below the floors in evals/quality/harness.py (DEFAULT_THRESHOLDS), so CI can gate on it. The measured baseline lives at evals/quality/baseline.json; the self-benchmark workflow runs this on every PR (where real embeddings are available) and posts the table + baseline deltas as a PR comment.

Public-benchmark mode (v0.31.0+)

--public runs the honest public benchmark: a reproducible, no-cherry-picking comparison of how much context different approaches put in an agent’s window to answer a real code question, and whether the objectively-correct file actually makes it in. It clones real, pinned OSS repos at fixed commit SHAs (requests @0e322af877, click @874ca2bc1c) and scores cost and correctness together against strong baselines: full-file paste, ripgrep, a same-encoder embedding-rag, and neuralmind’s progressive disclosure.

Gold-file recall is an objective def-site oracle — each query’s gold file is the definition site of a named symbol, verifiable with one rg; there is no LLM judge. Scoring reuses neuralmind/quality.py verbatim — the same metric code the CI quality gate runs. Pre-registered queries live in evals/public/manifest.json; every one is reported, losses included.

# Clone the pinned repos and print the full table
neuralmind benchmark --public

# Scope to one repo
neuralmind benchmark --public --repo click

# Machine-readable output (for CI / further analysis)
neuralmind benchmark --public --json

# Equivalent module entrypoint (from a clone)
python -m evals.public.run

The run is deterministic — synapse injection is OFF (session-dependent learning can’t be a fixed, reproducible public number; its lift is measured separately by the synapse A/B eval, tests/benchmark/run.py Phase 2). This reuses the same NEURALMIND_SYNAPSE_INJECT=0 toggle documented in the Environment Variables table. Re-running matches the published table to the token.

Honest headline: against what agents actually do today — paste files or grep — NeuralMind reaches 79–100% gold-file recall (93.75% mean) at 45–257× fewer tokens than pasting files, and beats ripgrep on cost on every repo; on recall it’s ahead on 2 of 4 repos and ties exactly on the other 2. The benchmark also reports, without hiding it, that a well-tuned vector RAG ties or beats it at findability too (and cheaper on raw tokens), and that click is NeuralMind’s weakest repo in the corpus. Full methodology, results, honest caveats, and “where NeuralMind loses” are published at docs/benchmarks/public.md; raw per-query data is committed at bench/public/results.json, and the forkable runner is .github/workflows/bench-public.yml.

Competitor head-to-head (v0.33.0+)

The benchmark also ships a live, reproducible row vs. codebase-memory-mcp 0.8.1 (the obvious incumbent), on the same pinned repos, questions, def-site gold, and quality.py scorer, at retrieval depth matched to embedding-rag (top-8). It lives in a separate module and is off the default run because it downloads an external binary — invoke it explicitly from a clone:

pip install codebase-memory-mcp==0.8.1     # pins 0.8.1 — on-device embeddings, no API key
python -m evals.public.competitor   # prints the competitor row; fails closed without the binary

On reproducible retrieval ranking NeuralMind reaches 100% gold-file recall and ranks the right file far higher (MRR 0.96 vs 0.23 on requests, 0.60 vs 0.50 on click), while the competitor surfaces the gold file in its top-8 only ~half the time, at an order of magnitude more read cost. Honest framing: this measures pure retrieval — no LLM agent loop on either side, exactly how we test NeuralMind’s own search; we used the competitor’s most-favorable reproducible keyword mapping; and we cite its published LLM-agent numbers (~90% of an “Explorer” agent; C at 0.58) as-is rather than reproduce them. Per-query traces and pinned REPRODUCE.md are committed under bench/public/competitor/; full caveats are in the “Competitor head-to-head” section of docs/benchmarks/public.md.

Answerability arm — --judge (v0.34.0+)

Gold-file recall measures locating the right file, not answering the question. The opt-in answerability arm adds the answering signal — a clearly-labeled secondary to the recall headline:

ANTHROPIC_API_KEY=…  python -m evals.public.run --judge   # off by default

For each query it answers from the real context each backend would put in the window (whole files / retrieved chunks / compact L0–L3 context) using a pinned model (claude-opus-4-8), constrained to that context only, then a separate judge call grades the answer against the same def-site gold anchor on a 0–2 scale plus a grounded flag. It needs ANTHROPIC_API_KEY (and the anthropic package), never runs in CI, and the recall table is byte-identical with or without --judge — absent a key it skips cleanly and the recall benchmark still runs. The answerer prompt, judge rubric, pinned model id, and every raw transcript are committed under bench/public/judge/ (transcripts written to --judge-out, default bench/public/judge). Full framing + caveats: the “Answerability arm” section of docs/benchmarks/public.md.

Sample Output

=== NeuralMind Benchmark ===

Project: MyApp
Total Nodes: 241
Communities: 93
Estimated Full Codebase: 50,000 tokens

| Query Type | Tokens | Reduction | Latency |
|------------|--------|-----------|----------|
| Wake-up context | 341 | 146.6x | 45ms |
| How does authentication work? | 739 | 67.7x | 187ms |
| What are the main API endpoints? | 748 | 66.8x | 192ms |
| Explain the database models | 812 | 61.6x | 201ms |
|------------|--------|-----------|----------|
| **Average** | **660** | **85.7x** | **156ms** |

---
Benchmark completed in 625ms

probe (v0.27.0+)

Run a retrieval self-probe on your own codebase: does the index actually find the right file when the agent asks about a symbol? Unlike benchmark (which measures token reduction) and benchmark --quality (which scores ranking against committed golden fixtures), probe runs label-free — no hand annotation — so it works on any built project.

neuralmind probe [project_path] [OPTIONS]

For a deterministic sample of indexed symbols, it queries each one by its intent — the symbol’s rationale (the docstring text NeuralMind stores as rationale nodes, e.g. "Raised when the exp claim is in the past"), which doesn’t contain the symbol name, so it’s a real natural-language → code test rather than a string match. It asks the backend for code hits directly, then scores whether the symbol’s source file came back: recall@1/3/5, MRR, and answerability@k (reusing the neuralmind.quality metrics). Undocumented symbols fall back to a humanized label, and the report discloses the rationale-vs-name split so a mostly-fallback run reads as a sanity check, not a quality score. The most actionable output is the blind-spot list: the sampled symbols the index couldn’t retrieve from their description — i.e. where an agent would come up empty. --k must be ≥ 1 and --sample-size ≥ 0 (0 = all).

The idea is borrowed from long-context “needle-in-a-haystack” evals (e.g. S-NIAH in the Recursive Language Models paper): rather than measuring cost, it measures whether the right node still surfaces as the index grows. It is read-only — it never mutates the index or the synapse store.

Arguments

Options

Examples

# Probe the current project
neuralmind probe .

# Tighter: the right file must be the #1 hit
neuralmind probe . --k 1

# Save a baseline, then check whether a refactor moved retrieval
neuralmind probe . --sample-size 100 --json > probe-baseline.json
neuralmind probe . --sample-size 100 --baseline probe-baseline.json

Sample Output

Retrieval self-probe — sample_project
Sampled 63 of 64 indexed symbols, retrieval depth k=10
Query source: 51 rationale, 12 label
============================================================
  answerability  : 98%  (file found in top-10)
  MRR            : 0.789
  recall@1/3/5   : 0.667 / 0.905 / 0.968
  blind spots    : 1
------------------------------------------------------------
Symbols the index couldn't retrieve from their own description (1 total):
  - get_me_endpoint()  (api/routes.py)   query: "GET /api/users/me — requires Authorization: Bearer header"

The Query source line discloses how strong the run was: rationale probes are real NL→code tests; label probes are a weaker name-based fallback for undocumented symbols. Because the probe is deterministic per --seed and emits --json (with a query_sources tally), you can gate CI on a per-repo recall/MRR floor, or diff two runs with --baseline to catch a retrieval regression before it ships.

stats

Show statistics about the neural index.

neuralmind stats <project_path> [OPTIONS]

Arguments

Options

Output

Displays:

• Node counts by type
• Community statistics
• Synapse edge count and total weight
• Embedding model and backend info

Examples

neuralmind stats .
neuralmind stats /path/to/project --json

synapse prune (v3.1.4+)

Remove stale synapses older than N days.

Arguments

Options

Output

Number of synapses pruned.

Notes

LTP-protected edges (≥5 activations) are preserved to maintain learned associations.

Examples

# Prune synapses older than 30 days
neuralmind synapse prune . --days 30

# Preview what would be pruned (use stats first)
neuralmind synapse stats .

synapse stats (v3.1.4+)

Detailed synapse diagnostics.

Arguments

Output

• Total edges
• LTP-protected count
• Stale (30+ days inactive)
• Dormant (≤1 activation)
• Total weight

Examples

neuralmind synapse stats .

• Embedding information
• Index storage size
• Last build timestamp

Examples

# Basic stats
neuralmind stats /path/to/project

# JSON format
neuralmind stats /path/to/project --json

Sample Output

=== NeuralMind Statistics ===

Project: MyApp
Graph Path: /path/to/project/graphify-out/graph.json
DB Path: /path/to/project/graphify-out/neuralmind_db

## Index Summary
- Total Nodes: 241
- Total Edges: 203
- Communities: 93
- Embedding Dimensions: 384

## Node Types
- Functions: 142 (58.9%)
- Classes: 45 (18.7%)
- Files: 38 (15.8%)
- Database Models: 16 (6.6%)

## Storage
- Index Size: 12.4 MB
- Cache Size: 2.1 MB

## Build Info
- Last Build: 2024-01-15 14:30:22
- Build Duration: 8.3s
- Embedding Model: all-MiniLM-L6-v2

validate (v0.23.0+)

Validate the project’s canonical intermediate representation (IR) — the versioned, producer-agnostic contract NeuralMind builds from graph.json. Runs a static schema check; no vector backend required (it never touches ChromaDB/turbovec).

neuralmind validate [project_path] [OPTIONS]

Arguments

Options

What it checks

• errors (exit code 1): dangling edge endpoints, missing endpoints, duplicate node ids, malformed synapse endpoints, unsupported (too-new) ir_version.
• warnings: orphaned (edgeless) nodes, unknown node kinds, unknown edge relations, and stale synapses (learned memory pointing at nodes a rebuild removed) — forward-compatibility / hygiene signals.

It also reports the IR contract version, source backend + producer schema version, coverage (coarse/precise), per-kind / per-language counts, and the learned-synapse count (folded in backend-free from the SQLite store).

Examples

# Validate the IR for the current project
neuralmind validate .

# Machine-readable summary
neuralmind validate . --json

# Migrate a legacy project's state to the IR in place (no rebuild)
neuralmind validate . --write

Sample Output

IR version:      1
Source backend:  neuralmind.graphgen (tree-sitter)
Source schema:   v1
Coverage:        coarse
Entities:        135 nodes, 185 edges, 18 clusters
Node kinds:      document=56, file=13, function=41, symbol=25
Languages:       python=135
------------------------------------------------------------
VALID — 0 errors, 0 warning(s).

function is inferred from the built-in backend’s call-form labels (name()); a producer that doesn’t follow that convention maps those to the generic symbol. Learned synapses, when a .neuralmind/synapses.db exists, are folded in and shown in the --json synapses count.

The IR is also exposed as a public Python API: from neuralmind import IndexIR, from_graph_json, validate_ir, validate_project.

doctor (v0.12.0+)

Diagnose a project’s NeuralMind setup and print an actionable fix for anything that isn’t wired up. Read-only — it never builds or mutates state.

neuralmind doctor [project_path] [--json]

Arguments:

Checks: code graph, semantic index, backend (v0.22.0+), synapse memory, MCP server, Claude Code hooks, and query-memory consent. Each reports ok, warn (optional/learned-over-time), or fail (setup incomplete). The Backend check reports the configured value (e.g. auto), what it resolves to (turbovec or chroma), and whether the turbovec stack is installed — so the per-environment default is never a silent mystery.

Exit codes: 0 when no check failed (warnings allowed), 1 when any check failed — so you can gate a CI step or an agent’s provisioning on neuralmind doctor.

Example:

neuralmind doctor .

NeuralMind doctor — /path/to/project
============================================================
  [ ok ] Code graph: 1240 nodes at /path/to/project/graphify-out/graph.json
  [ ok ] Semantic index: 1240 nodes embedded (turbovec backend)
  [ ok ] Backend: turbovec (auto-selected; turbovec stack available)
  [warn] Synapse memory: no synapses.db yet (nothing learned)
         -> It populates automatically as you query and edit the codebase.
  [ ok ] MCP server: MCP SDK importable (neuralmind-mcp ready)
  [warn] Claude Code hooks: not installed
         -> Install them: neuralmind install-hooks
  [ ok ] Query memory: enabled (logging queries for learning)
============================================================

JSON output (--json) is stable for scripting and agent consumption:

{
  "status": "fail",
  "checks": [
    {"name": "Code graph", "status": "fail",
     "detail": "not found at /repo/graphify-out/graph.json",
     "fix": "Generate it: neuralmind build /repo"}
  ]
}

eval (v0.14.0+)

Run the faithfulness eval: does NeuralMind’s selected context contain more gold facts than a matched-budget naive baseline? It self-evaluates against the committed reference fixture + gold-fact set (which ship with the source repository), so — like neuralmind benchmark — it’s a quality self-test, not a per-repo command.

neuralmind eval [project_path] [--json] [--selfcheck] [--onboarding]

Arguments:

What it reports: the faithfulness delta — mean expected-fact recall of NeuralMind’s context minus the naive baseline’s, at a matched per-query token budget — plus grounding rate, contradiction rate, and a per-query breakdown. A positive delta means smart selection beats dumb truncation at equal token cost. The default judge is 100% offline; an opt-in LLM-as-judge sits behind NEURALMIND_EVAL_LLM_JUDGE=1 and is never the default or the CI gate.

What --onboarding reports: the onboarding lift — onboarded − cold top-k module hit-rate (the share of a query’s expected modules that land in the ranked top-k retrieval the agent sees), the slice associative recall re-ranks within. Fact-recall and full-context grounding print as honest secondaries: at a fixed budget fact-recall is budget-traded (slightly negative on the tiny fixture) and grounding saturates, so neither is the gated headline. It’s the same top-k hit-rate signal as the self-benchmark’s Phase-3 A/B.

Requirements: the A/B needs the retrieval stack (chromadb) and a built index; without them it degrades with an actionable message. --selfcheck needs neither. From an installed wheel (where the evals/ package isn’t bundled), run it from a source checkout instead: python -m evals.faithfulness.runner --run.

ingest-content (v3.4.0+)

Index a corpus of prose — a book’s chapters/, a docs tree, a research folder — into its own content index. Unlike learn, which mixes documents into a code project’s graph, ingest-content is built for corpora that are only content, and for re-running as that corpus grows.

neuralmind ingest-content chapters                       # index a folder of .md/.txt
neuralmind ingest-content chapters --content-only        # skip the code-graph build
neuralmind ingest-content chapters --dry-run             # preview files + chunk counts
neuralmind ingest-content chapters --project-path book   # pin the index location
neuralmind ingest-content chapters --json                # machine-readable result

Where the index goes. The project root is resolved from the nearest .neuralmind/ or .git marker above the content path, then the cwd. Point it at book/chapters inside a git repo with no NeuralMind index and it resolves to the repo root — which is rarely what you want for a book — so it says so and names the flag:

Note: indexing into /repo — the nearest project marker above /repo/book/chapters
      (a git root, with no NeuralMind index of its own).
      To keep this corpus self-contained, re-run with --project-path /repo/book/chapters

--project-path pins it explicitly. After the first run the directory carries its own .neuralmind/index_ir.json, so later runs resolve there on their own.

Skipping the code graph. By default the ingest builds the project’s code graph first, which for a folder of Markdown is pure cost — and used to require writing a throwaway _content_seed.py to give the build something to parse. --content-only skips generating a graph entirely (an existing graph is still loaded, so code nodes stay in the keyword index) and writes a valid empty IR to mark the directory as a project. No seed file.

Incremental by default. Every embedded file’s SHA-256 and chunk parameters are recorded in <project>/.neuralmind/content_manifest.json. A re-run re-embeds only what changed:

Ingested 1 file(s) → 9 chunks → 9 nodes (33 unchanged, skipped)
Corpus: 34 file(s), 306 chunks
Wall time: 0.6s | Embed time: 0.46s

Chunk ids are positional, so a chapter that shrinks would otherwise leave orphaned chunks behind. The manifest records each file’s node ids, so shortened and deleted files have their stale chunks evicted from the index. --force re-embeds everything; changing --chunk-size/--overlap invalidates the manifest on its own, since new parameters mean new chunk boundaries.

Progress. On a terminal you get an in-place bar with an ETA. Off one — CI logs, an agent shell, a redirect — you get plain milestone lines instead, so a long embed shows movement rather than looking hung. Progress goes to stderr, so --json on stdout stays parseable. --no-progress (or NEURALMIND_NO_PROGRESS=1) turns it off.

Timeouts. --timeout N stops cleanly after N seconds: the manifest is written for what did land, so the next run resumes instead of starting the corpus over. A timed-out run exits 1 and reports "timed_out": true in JSON. Files it never reached are not treated as deleted.

JSON output:

{
  "success": true,
  "project_path": "/repo/book",
  "content_only": true,
  "incremental": true,
  "files_processed": 1,
  "files_skipped": 33,
  "files_total": 34,
  "total_chunks": 306,
  "chunks_embedded": 9,
  "total_nodes": 9,
  "orphans_removed": 0,
  "chunk_size": 500,
  "overlap": 50,
  "wall_time_seconds": 0.6,
  "embed_time_seconds": 0.46,
  "timed_out": false,
  "errors": []
}

--dry-run --json returns a different shape: dry_run: true, a files array of {file, path, bytes, chunks, status}, and chunks_would_embed.

Exit codes: 0 success · 1 one or more files failed, or the run timed out · 2 invalid chunk parameters.

Check the result any time with neuralmind status <path>.

learn — document ingestion (v1.11.0+)

Ingest PDFs, Markdown, and plain text into the knowledge graph alongside code. The deprecated no-op has been repurposed as a first-class ingestion command.

neuralmind learn <file>                # ingest single file
neuralmind learn <directory>           # ingest all supported files
neuralmind learn --type pdf guide.pdf  # type hint (auto/pdf/markdown/text)
neuralmind learn --json report.md      # output stats as JSON

What it does:

• Parses PDF/Markdown/text into ContentNode objects with chunking
• Embeds chunks into the same vector space as code
• Deduplicates on re-ingestion (identical content → 0 new nodes)
• Guards against path traversal, binary files, size bombs (>10MB)

Notes:

• Ingested documents appear in neuralmind query results alongside code
• Learning from usage (synapses) still happens automatically via the synapse layer
• For compliance/tagged ingestion, use neuralmind learn --type cmmc

learn (deprecated, v0.25.0 — pre-v1.11.0)

This section describes the pre-v1.11.0 behavior, replaced by the command above. cooccurrence reranker this command used to populate was removed. The command now prints a deprecation notice and exits 0, so existing scripts and CI that call it keep working unchanged.

neuralmind learn <project_path>   # 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. A 2×2 A/B on the benchmark fixture showed the old reranker added 0.0 points to top-k hit rate while the synapse layer alone moves it (+3.5 to +14 points across runs; CI gates the direction, not the magnitude).

To see what’s been learned, use neuralmind stats or neuralmind memory inspect. For the full rationale and migration notes, see the v0.25.0 release notes.

self-improve status (v0.26.0+)

Show the self-improvement engine’s current selector-tuning state. Read-only — it never writes and never runs the tuner; it only reports what the tuner has done.

neuralmind self-improve status [project_path] [--json]

Arguments

Options

What it reports

• l2_recall_k — the current (possibly tuned) L2 recall depth, i.e. how many community summaries a query surfaces. Default 3, clamped to [2, 6].
• l2_recall_k_tuned_at — ISO timestamp of the last change, or never.
• query-event count + warm-up state (the tuner holds until 50 query events accumulate).
• the windowed re_query_rate the tuner reads.
• whether autotune is enabled (the NEURALMIND_SELECTOR_AUTOTUNE flag).

$ neuralmind self-improve status .
Project: my-project
Autotune enabled: True (NEURALMIND_SELECTOR_AUTOTUNE)
l2_recall_k: 4
Last tuned at: 2026-06-12T17:58:10+00:00
Query events logged: 132 (warmed up: True)
Query events in tuning window: 41
re_query_rate: 0.512

The tuner itself runs only when NEURALMIND_SELECTOR_AUTOTUNE=1 — under Claude Code it ticks once per session from the SessionStart hook (after the synapse decay tick); the tuned value is then threaded into the selector at build time so ordinary queries (CLI or MCP) use the adapted recall depth. With the flag unset the hot path does zero extra I/O and the selector keeps its hard-coded default. The tuner is single-step, windowed, hysteretic, clamped, and fail-open; see the v0.26.0 release notes and evals/self_improvement/PLAN.md for the full design.

next (v0.11.0+)

Predict what typically follows a node (file path or node id) in the learned directional transition graph. Pairs with the record_sequence calls the file watcher runs automatically on every batched flush.

neuralmind next <project_path> <from_node> [--n 5] [--namespace NAME] [--json]

Arguments

Options

Examples

# What do I usually edit after the auth handlers?
neuralmind next . src/auth/handlers.py

# JSON for scripting
neuralmind next . src/auth/handlers.py --n 10 --json

Sample output:

After src/auth/handlers.py:
   45.2%  tests/test_auth.py
   28.4%  src/auth/middleware.py
   12.1%  docs/auth.md
    8.3%  src/auth/__init__.py
    6.0%  src/main.py

The same capability is exposed via MCP as neuralmind_next_likely and via Python as SynapseStore.next_likely(from_node, top_k=5). The file watcher must have been running at some point for this to return results — fresh installs need a few sessions before the transition graph accumulates signal.

memory (v0.24.0+)

Namespace-level controls over the learned synapse memory (PRD 4). Every learned association carries a namespace — personal (default; all pre-v0.24 memory migrates here losslessly), shared (imported team baseline), branch:<name> (per-git-branch, detected automatically), and ephemeral (session scratch, cleared at session boundaries). All four subcommands work without a built index — the store is stdlib SQLite.

neuralmind memory inspect [project_path] [--namespace NAME] [--json]
neuralmind memory reset   [project_path] --namespace NAME [--json]
neuralmind memory export  [project_path] [--namespace NAME] [-o FILE]
neuralmind memory import  <file> [--project-path PATH] [--namespace NAME] [--json]
neuralmind memory publish [project_path] [--json]

Subcommands

Examples

# What has the agent learned, and where does it live?
neuralmind memory inspect .

# A feature branch merged — drop exactly its memory
neuralmind memory reset . --namespace branch:feature-x

# Ship a team baseline to a new teammate (ad-hoc bundle)
neuralmind memory export . --namespace personal -o team-baseline.json
neuralmind memory import team-baseline.json --namespace shared

# Team memory (v0.30.0): commit once, teammates inherit automatically
neuralmind memory publish .
git add .neuralmind-team-memory.json && git commit -m "publish team memory"
# teammates: their next `neuralmind build` / Claude Code session inherits it

How the active namespace is resolved

NEURALMIND_NAMESPACE env var → memory_namespace: in neuralmind-backend.yaml → branch:<name> when the repo is on a non-default git branch (best-effort git rev-parse, 3s timeout) → personal. A non-repo, detached HEAD, or missing git all degrade safely to personal. Long-lived processes (the daemon, the MCP server) detect a git checkout between writes via a cheap .git/HEAD fingerprint and re-resolve automatically — no restart needed.

Merged-read weighting

Recall, next, and stats default to a merged view with explicit, published constants (neuralmind/synapses.py):

merged_weight = 1.0 × active  +  0.8 × personal  +  0.5 × shared
                (W_BRANCH)       (W_PERSONAL)        (W_SHARED)

On the default branch the active namespace is personal (read at 1.0×), so behavior is identical to pre-namespace releases. Per-namespace decay: shared is sticky, personal/branch:* decay at the standard rates, ephemeral fades fast with no LTP floor. Traced queries (query --trace) attribute each synapse boost to its namespace via namespace_contribution.

skeleton

Print a compact graph-backed view of a file — functions, rationales, and call graph — without loading the full source.

neuralmind skeleton <file_path> [--project-path .] [--json]

Arguments

Options

Examples

# Skeleton for a file in the current project
neuralmind skeleton src/auth/handlers.py

# Skeleton with explicit project root
neuralmind skeleton src/auth/handlers.py --project-path /path/to/project

# JSON output
neuralmind skeleton src/auth/handlers.py --json

structural (v0.42.0+)

Show how a symbol is wired into the codebase from the static code graph — its callers, callees, base/sub classes, and importers. These are the precise structural edges (calls, inherits, imports_from) that graphify extracts, distinct from the learned synapse graph. Use it before editing a function’s signature (find every caller) or a class (find overrides), or pass --blast-radius for the transitive set of code a change would affect.

neuralmind structural <symbol> [--relation calls|inherits|imports|contains|all] \
                               [--blast-radius] [--depth N] [--project-path .] [--json]

Arguments

Options

Examples

# Who calls / what does this call / what does it inherit?
neuralmind structural "create user"

# Just the callers, via the calls relation
neuralmind structural authenticate_user --relation calls

# Blast radius before a risky refactor
neuralmind structural "charge customer" --blast-radius --depth 2

# Machine-readable output for scripting
neuralmind structural UserService --json

Example output:

## Structural neighbors of users_crud_create_user

### Callers (1)
- create_user_endpoint() — routes.py

### Callees (2)
- get_connection() — connection.py
- User — crud.py

The equivalent MCP tool is neuralmind_structural_neighbors (with a blast_radius boolean). Both return real graph node ids, so they compose with neuralmind_synaptic_neighbors.

impact (v0.52.0+, originally v0.47.0)

A friendlier-named, richer-output sibling of structural --blast-radius — same underlying structural index, same traversal, but each dependent row carries which hop and which relation (calls/inherits/ imports_from/implements) connects it, not just its id. Use before renaming, re-signing, or deleting a symbol to see everything a change would touch, in one command instead of a boolean flag on a differently-named one.

neuralmind impact <symbol> [--depth N] [--project-path .] [--json]

Arguments

Options

Examples

neuralmind impact hash_password
neuralmind impact "the login handler" --depth 2
neuralmind impact UserService --json

Example output:

Impact of auth_handlers_authenticate_user (semantic match) — depth 2:
  h1  calls          login_endpoint() — routes.py

1 dependent(s).

--json returns {symbol, depth, relations, resolution, resolved_node, dependents, count}, where resolution is "exact" (symbol was a literal node id), "semantic" (resolved via the closest embedding match), or "none". The equivalent MCP tool is neuralmind_impact.

last (v0.10.0+)

Print the most recent Bash output the PostToolUse hook cached, so an agent can recover the dropped middle without re-running the command.

Every time the compress-bash hook fires, it stashes the raw pre-compression stdout/stderr to <project>/.neuralmind/last_output.json (single-slot, 2 MB cap, atomic temp-file + rename writes). neuralmind last surfaces it.

neuralmind last [project_path] [--json]

Arguments

Examples

# Human-readable: what the agent would have seen pre-compression.
neuralmind last

# Full JSON payload — useful for scripted recovery flows.
neuralmind last --json

# When no cache exists yet (no Bash call has fired the hook).
neuralmind last
# → "No cached output found at <path>. Run a Bash tool call through Claude Code first…"
# → exits with status 1

Exit codes

When to use

Credential redaction (v3.5.0+). Secrets are stripped before the cache is written, so a value shown as [REDACTED:<kind>] was never stored on disk. The header lists which kinds were removed:

# cached: 2026-08-24T13:47:44   exit=0
# command: printenv
# redacted: anthropic-api-key (re-run the command to see real values)

ANTHROPIC_API_KEY=[REDACTED:anthropic-api-key]

Re-run the command yourself if you need the real value. Disable with NEURALMIND_OUTPUT_REDACT=0 (not recommended — the cache lives in a plaintext file inside your project).

install-hooks

Install or uninstall Claude Code lifecycle hooks. As of v0.4.0 this registers four event blocks (idempotent — re-running only updates the NeuralMind block, leaving any user hooks untouched):

neuralmind install-hooks [project_path] [--global] [--uninstall]

Arguments

Options

Examples

# Install hooks for current project
neuralmind install-hooks .

# Install hooks globally
neuralmind install-hooks --global

# Uninstall project hooks
neuralmind install-hooks --uninstall

# Uninstall global hooks
neuralmind install-hooks --uninstall --global

Bypass temporarily:

NEURALMIND_BYPASS=1 claude-code ...

install-mcp (v0.19.0+)

Register the NeuralMind MCP server (neuralmind-mcp) with one or more AI coding agents. Auto-detects installed clients and merges a neuralmind entry into each client’s mcpServers config without clobbering your other servers (idempotent — re-running is a no-op).

neuralmind install-mcp [project_path] [--client NAME] [--all] [--print]

Clients & config locations

Options

Examples

# Register with Claude Code for this project (writes .mcp.json)
neuralmind install-mcp

# Register with every agent installed on this machine/project
neuralmind install-mcp --all

# A specific client
neuralmind install-mcp --client cursor

# Just show me the snippet
neuralmind install-mcp --print

Restart the client after registering so it picks up the new server. The agent then exposes NeuralMind’s MCP tools (wakeup, query, search, skeleton, build, stats, …).

init-hook

Install (or update) two Git hooks, both idempotent and both appended to any existing hook script rather than overwriting it:

• post-commit rebuilds the neural index automatically after every commit.
• pre-commit (v3.2.0+) runs neuralmind drift . --staged over the staged diff — the commit-time drift guard described under drift below.

neuralmind init-hook [project_path] [--no-drift] [--strict]

Arguments

Examples

# Install both hooks (drift guard warns, never blocks)
neuralmind init-hook .

# Install both hooks, with drift blocking the commit
neuralmind init-hook . --strict

# Install only the post-commit rebuild, no drift guard
neuralmind init-hook . --no-drift

drift (v3.2.0+)

Flag changed symbols that skip a pattern their peers share — the commit-time half of the cohesion outlier check (NEURALMIND_SYNAPSE_OUTLIERS, see Environment Variables), which runs the same consensus math at query time instead of diff time. Reads a git diff, maps the changed lines onto graph symbols, groups each changed symbol with its siblings in the same file or class, and asks whether the symbol you just touched omits an association a strong majority of that group makes (e.g. nine of ten *_endpoint handlers call verify_session() and the tenth doesn’t).

Only symbols in the diff are ever reported — pre-existing outliers elsewhere in the graph are silently ignored, so the check never blames a commit for drift it didn’t introduce. Warn-only and exit-0 by default so it is safe to wire into pre-commit; --strict makes it exit non-zero.

neuralmind drift [project_path] [--staged] [--diff BASE] [--strict]
                  [--cohesion N] [--min-peers N] [--max-findings N]
                  [--no-refresh] [--json]

Arguments

Examples

# What a pre-commit hook runs
neuralmind drift . --staged

# Check everything since a branch diverged from main
neuralmind drift . --diff main

# Be stricter about what counts as consensus, and block on it
neuralmind drift . --staged --cohesion 0.75 --strict

## NeuralMind drift check (warning) — 1 finding(s)

- api/routes.py:67 — `delete_me_endpoint()` skips `verify_session()`, which 3 of its 9 peers (33%) use. Confirm this is deliberate.

Warning only — the commit proceeds. Use --strict to block on drift.

Requires a built graph (neuralmind build .) — without one, drift reports “No code graph found” and exits 0 rather than failing the commit. When tree-sitter is installed (the graphgen optional extra), the graph is transparently refreshed for just the changed files before judging, so a brand-new function in the diff is visible even though the persisted index predates it; pass --no-refresh to skip that and judge against the index exactly as it was last built. Stdlib-only otherwise, same as neuralmind/cohesion.py — no ChromaDB or embedder work.

compliance (v3.1.4+)

Scan a project for compliance annotations written in comments or prose, and reinforce a synapse between the annotated code node and the control it names — so neuralmind query "what implements CC6.1" can find it later.

neuralmind compliance [project_path] [--watch] [--json]

$ neuralmind compliance .

Found 27 compliance annotations across neuralmind:

  [      SOC2] CC6.1
             Logical access controls.
             docs/compliance/ACCESS_CONTROL.md

  [      NIST] AC-1
             Access control policy
             neuralmind/compliance_matcher.py

Annotation syntax — each framework needs its own marker

This is the part that bites people. A control id alone never matches. Every framework requires a marker, on the same line as the id:

Two consequences worth stating plainly:

• Compliance: is a SOC 2 / ISO 27001 marker, not a universal one. # Compliance: AC-1: Access control policy matches nothing — NIST needs its own prefix.
• A bare CC6.1 in a prose table does not match. The marker may sit up to 32 characters before the id on the same line, which is what makes **SOC 2 Control:** CC6.1 work, but a control id on its own is indistinguishable from a version string and is ignored. This tightening landed in v3.3.0 after the looser pattern matched v0.13, M13.5 (an SVG path command) and python3.10 as Trust Services Criteria.

What gets scanned

Code and prose: .py .js .jsx .ts .tsx .go .java .rb .php .cs .c .cpp .h .rs .md .mdx .rst .txt. Skipped: .git, node_modules, .venv, venv, __pycache__, .next, out, htmlcov, .neuralmind.

(Before v3.3.1 the CLI read only source files, so annotations kept in markdown — the usual place for a policy document — were invisible to this command even though the matcher supported them.)

Showing an annotation without becoming evidence

Documentation, tests and marketing copy have to show what an annotation looks like. Before v3.4.1 every one of those examples was counted as a real annotation — on this repository the scan reported 37 controls, 25 of which were syntax samples in the very pages that document the syntax, and all 37 flowed into neuralmind export --controls, which users submit as audit evidence.

Two opt-out markers fix that. Neither is a comment syntax of its own — put the text anywhere a given file lets you put text (an HTML comment in markdown, a # or // comment in code, prose in a docstring):

<!-- neuralmind:example-file — annotations here are syntax examples, not evidence. -->
# CLI Reference

help="e.g. # NIST AC-1: Access control policy",  # neuralmind:example

The file-level marker is checked before any pattern runs, so an opted-out file costs nothing to scan. The line-level marker is tested against the whole line the control id sits on, not the start of the match.

Both markers are inert everywhere else — nothing else in NeuralMind reads them, and a file carrying one still indexes, embeds and queries normally.

ci-check (v3.1.4+)

Run the same detection against a git diff instead of the whole tree, so a pipeline can report which compliance-annotated code a change touches.

neuralmind ci-check [project_path] [--framework NAME] [--diff REF] [--fail-on-warning] [--json]

$ neuralmind ci-check . --framework soc2 --diff HEAD~1

NeuralMind CI Compliance Check
Framework: SOC2
Base ref: HEAD~1
Changed files: 3

No compliance annotations affected by this diff.

--framework accepts the friendly spellings (sox → SOX ITGC, iso → ISO 27001, soc/soc 2 → SOC2). (Before v3.3.1 the flag was echoed in the header but never applied — findings from every framework were reported regardless of what you passed.)

export (v3.1.4+)

Write NeuralMind state out as an auditor-ready artifact.

neuralmind export [project_path] [--format csv|pdf] [--controls] [--nodes] [--output FILE]

--controls is the flag people submit as evidence, so it inherits the annotation rules above exactly: what neuralmind compliance finds is what lands in the CSV, including its label column.

watch (v0.4.0+)

Run the file activity → synapse co-activation daemon in the foreground. Edits to project files are debounced into batches and fed into the synapse store, so the v0.4.0 brain-like layer keeps learning even when no query runs. Periodic decay ticks age unused weights without manual intervention. Stops cleanly on Ctrl-C.

neuralmind watch [project_path] [--debounce SECONDS] [--decay-interval SECONDS] [--quiet] [--reindex]

Arguments

Flags

Examples

# Always-on learning for the current project
neuralmind watch &

# Background it and only log the final summary
neuralmind watch /path/to/repo --quiet &

# Disable periodic decay (decay only runs from SessionStart hook)
neuralmind watch . --decay-interval 0

# Keep the index live as you edit (incremental re-index, v0.18.0+)
neuralmind watch . --reindex

Notes

• Backed by watchdog when present, with a polling fallback when not. No mandatory new dependency.
• Pairs with neuralmind install-hooks — the watcher learns from edits, the lifecycle hooks learn from queries and tool calls, and the same <project>/.neuralmind/synapses.db store is the single source of truth.
• For “always on” across reboots, wrap in systemd, launchd, or tmux. NeuralMind deliberately doesn’t self-daemonize.

serve (v0.5.4; live feed v0.6.0+)

Start the graph-view UI — a local, dependency-free, Obsidian-style force-directed graph over the same index and synapse store your AI agent queries. v0.6.0 made the canvas live: synapse + file events stream to the browser over SSE, affected nodes pulse, a sidebar log shows recent events. Stops cleanly on Ctrl-C.

The server binds to 127.0.0.1 by default and prints a per-session auth-token URL on startup; pass that URL to the browser so untrusted local processes can’t read your graph.

neuralmind serve [project_path] [--port PORT] [--no-browser] [--editor EDITOR] [--no-auth]

Arguments

Flags

Examples

# Run against the current project
neuralmind serve .

# Custom editor for the "open in editor" button
neuralmind serve . --editor "code -n"

# Pick a different port and skip the browser
neuralmind serve . --port 9000 --no-browser

# Skip auth for a kiosk / trusted local host
neuralmind serve . --no-auth

Live activity feed (v0.6.0+)

The canvas updates in real time as the brain works:

• Synapse events — every SynapseStore.reinforce() call publishes a synapse event over the in-process event bus; the affected pair of nodes pulse on the canvas.
• File activity events — every coalesced edit batch from the neuralmind watch daemon (or from Claude Code’s PostToolUse hooks) publishes a file_activity event; affected nodes pulse.
• Sidebar log — the most recent ~80 events render as a scrolling feed with timestamps. Click an entry to focus the corresponding node on the canvas.

Cross-process activity bridge (v0.6.0+)

When serve and the activity source live in different processes — a separate neuralmind watch daemon, a Claude Code session — each event_bus.publish() call also appends a JSON line to <project>/.neuralmind/events.jsonl. The serve process tails that file in a background thread and re-emits anything it didn’t originate. Net result: one canvas, all processes, no IPC complexity.

Behaviour:

• NEURALMIND_EVENT_LOG=0 disables the writer (in-process feed still works).
• The tailer is best-effort. If the file disappears or rolls, the next event re-creates it.
• The bus stays the primary path. The JSONL is a fallback, not a queue.

Notes

• Read-only over HTTP. Edits to nodes/synapses still go through the regular CLI and MCP tools; the UI only inspects.
• The /api/open endpoint launches $EDITOR against an allowlist pre-computed from the graph’s source_file set, so a tampered client can’t trick the server into opening arbitrary paths.
• All assets in neuralmind/web/ (HTML, JS, CSS) are read-only at runtime; the server doesn’t generate any of them.
• Graph payload is cached per-session in _Handler._graph_cache; any endpoint touching graph state respects _graph_lock.
• Vanilla-JS frontend, stdlib-only HTTP server, no CDN. Safe to run behind a firewall.

daemon (v0.23.0+)

Manage the local NeuralMind daemon (experimental — PRD 5). The daemon holds each project’s state warm so repeated queries skip cold backend init. CLI read commands (query, stats) prefer it automatically when it’s running and fall back to direct mode otherwise.

neuralmind daemon {start|stop|restart|status} [OPTIONS]

Actions

Options

Behavior

• One per-user daemon, many projects. A project registry initializes each NeuralMind once and reuses it; a per-project lock serializes build/query/watch so they can’t corrupt the index or synapse store; slow builds run as background jobs.
• Auto-preference + fallback. neuralmind query / stats use the daemon when reachable (output marked via: daemon in --json), else run directly. Force direct mode with NEURALMIND_NO_DAEMON=1.
• Crash-safe discovery. A stale discovery file (dead pid / unreachable) is cleaned up automatically, so a crashed daemon never wedges the CLI.
• Shared API. The daemon speaks one transport-agnostic contract (health / status / query / search / stats / build / validate / jobs); the neuralmind-daemon console script runs it directly. Token-guarded even on loopback.

# Warm daemon, then fast repeat queries
neuralmind daemon start
neuralmind query . "how does auth work?"   # served warm (via: daemon)
neuralmind daemon status --json
neuralmind daemon stop

savings (v0.39.0+)

Show cumulative token savings from the local query event log. Verifies the 12-50× claim against your own real usage rather than trusting the demo.

neuralmind savings [project_path] [OPTIONS]

Options

Examples

# Show project-level savings
neuralmind savings .
# → NeuralMind token savings — my-project
# →   Queries logged    : 47
# →   Avg reduction     : 38.2x
# →   Tokens actually used :     83,140
# →   Est. cost without NM : 2,350,000
# →   Tokens saved         : 2,266,860

# Global savings across all projects
neuralmind savings --global

# JSON for dashboards or scripting
neuralmind savings . --json

# Dollar savings at claude-opus-4-8 input pricing (v0.45.0+)
neuralmind savings . --cost
# →   Dollar savings — claude-opus-4-8 @ $5.0/MTok input
# →     Cost without NM : $     11.75
# →     Cost with NM    : $      0.42
# →     Saved           : $     11.33
# →     Projected       : $24.12/day · $723.47/month  (at 100 queries/day)

# Price against a different model and daily volume
neuralmind savings --global --cost --model gemini-2.5-pro --queries-per-day 250

# JSON gains a "dollar_savings" block when --cost is set
neuralmind savings . --cost --json

The dollar figures are estimates anchored to the same 50,000-tokens-per-query baseline as the token report, priced on input tokens only — retrieval decides which input tokens ship, so output pricing never enters the math. Prices are a 2026-07 snapshot (MODEL_PRICING_PER_MTOK in neuralmind/memory.py).

Only the with-NeuralMind cost is measured from logged tokens; without-NM (and therefore saved / projected) is estimated from the fixed baseline, so those figures are marked (est) in the human output. The JSON dollar_savings block makes this machine-readable too: estimated: true, a basis string, and baseline_tokens_per_query.

Memory logging must be enabled (answer yes when first prompted, or set NEURALMIND_MEMORY=1).

why (v0.43.0+)

Recall the recorded rationale behind code — the decision provenance a human authored, not something inferred.

Harvests Decision: git trailers from history and surfaces the ones whose subjects the query mentions. The trailer is the store: no database, nothing to build, and it works retroactively on commits already in history.

neuralmind why "<symbol or question>" [--project-path PATH]

Capture a decision by adding a trailer to a commit message (backticked symbols in the rationale become subjects automatically; an explicit Subjects: line is also honored):

cli: resolve org id per handler

Decision: resolveOrgId is per-handler, not middleware — avoids Prisma on
          /health, /metrics, /token; keeps tests simple.
Subjects: `resolveOrgId`, `authMiddleware`

Arguments

Options

Sample Output

## NeuralMind decision provenance

- `resolveOrgId`, `authMiddleware`: resolveOrgId is per-handler, not middleware —
  avoids Prisma on /health, /metrics, /token; keeps tests simple. (see commit ba25fed)
### doctor *(v0.12.0+)*

Run diagnostic checks on the index.

### eval *(v0.14.0+)*

Evaluate retrieval quality.

### feedback good/bad *(v3.1.4+)*

Provide explicit feedback on the last query's results.

#### Arguments

| Argument | Required | Default | Description |
|----------|----------|---------|-------------|
| `--json` | No | `false` | Output as JSON |

#### Output

Confirmation of edges boosted or penalized.

#### Examples

```bash
# Boost edges from last query (good feedback)
neuralmind feedback good .

# Penalize edges from last query (bad feedback)
neuralmind feedback bad .

Prerequisites

Requires a synapse store with edges from a previous query.

health (v3.1.4+)

Check NeuralMind health status.

Arguments

Output

Health status: healthy, stale (index ≥24h old), or no index.

Exit Codes

Examples

# Check health
neuralmind health .

# Use in CI/CD
neuralmind health . || echo "Index needs rebuild"

status (v3.1.4+; index reporting v3.4.0+)

Two independent halves of a project’s state in one glance: what is indexed (code nodes, ingested content, when it was last built) and what has been learned (synapse edges, and an “is it learning?” diagnostic). Both are reported even when only one exists — a freshly ingested corpus has no synapses yet, and a long-lived project can carry months of learned edges over an index nobody has rebuilt.

neuralmind status .          # human-readable dashboard
neuralmind status . --json   # machine-readable

═══ NeuralMind Status — book ═══
  Code nodes:   0 (0 edges) — content-only project
  Last build:   0.4h ago
  Disk:         2.1 MB
  Content:      34 file(s), 306 chunks, 306 nodes
  Last ingest:  2026-08-23T13:19:14+00:00

  Status:       🟢 active
  Namespace:    personal
  Edges:        318 (12 LTP-protected)
  ...

“Code nodes” is named that way so it doesn’t read as a total: a content-only project legitimately has zero of them and thousands of chunks.

The JSON adds an index object (exists, path, nodes, edges, built_at, age_hours, disk_mb) and a content object (files, chunks, nodes, last_indexed_at, tracked) alongside the existing synapse keys.

Reads the IR and the content manifest straight off disk and never constructs a vector backend, so it answers in milliseconds. An IR above 64 MB is summarized rather than parsed — nodes comes back null and the build timestamp still reports.

learn — document ingestion (v1.11.0+)

neuralmind gaps [project_path]

Phase 1 heuristics cover Express + Jest (JS/TS). Route paths are normalized across :id / {id} / ${...} / * styles so a registration and a test reference match; a test “hits the real DB” when its file imports a real-DB fixture (e.g. @/db, testDb) and the case isn’t skip-guarded (SKIP_PG, .skip).

Arguments

Sample Output

## neuralmind gaps — live-Postgres coverage

Routes tested in-memory only (no live-DB coverage):
  POST /api/sessions            — 3 tests — all SKIP_PG  ❌
  GET  /.well-known/jwks.json   — 1 test — all SKIP_PG   ❌
Endpoints with no tests:
  POST /api/auth/jwk/rotate     ⚠️
Live-covered:
  GET  /health                  ✅

gaps –structural (v1.9.0+)

Identify structural gaps in your codebase — missing bridges between communities that should be connected but aren’t. Built on Brandes’ betweenness centrality algorithm over the structural graph.

neuralmind gaps --structural [OPTIONS]

Options

Examples

# Find top 20 structural gaps
neuralmind gaps --structural

# Find gaps with score > 0.5, JSON output
neuralmind gaps --structural --threshold 0.5 --json

# Gaps in a specific community
neuralmind gaps --structural --community 3

Sample Output

## NeuralMind — Structural Gaps (G5)

Rank  Score    Node                                   Communities
────  ──────   ─────────────────────────────────────  ────────────
1     0.87     src/auth/token.py                      2, 5
2     0.72     src/models/user.py                     1, 3
3     0.65     src/utils/validation.py                2, 4

The equivalent MCP tool is neuralmind_structural_gaps.

review (v0.39.0+)

Warn about likely co-breakage before a commit or when reviewing a diff.

Reads the current git diff (or a specified base ref), finds changed files, and runs spreading activation through the learned synapse graph to surface files that are strongly associated but NOT in your diff — files that have historically been edited together with the ones you’re changing.

neuralmind review [project_path] [OPTIONS]

Options

Examples

# Review uncommitted changes (diff against HEAD)
neuralmind review .

# Review the last commit
neuralmind review . --base HEAD~1

# Review changes on a feature branch vs main
neuralmind review . --base main

# JSON output for CI integration
neuralmind review . --json

Sample Output

NeuralMind review — my-project  (diff against: HEAD)

Changed files (3):
  • auth/middleware.py
  • auth/handlers.py
  • tests/test_auth.py

Co-break candidates — files NOT in diff but strongly associated (4):
  0.782 ████████  auth/tokens.py
  0.654 ██████    auth/models.py
  0.431 ████      config/settings.py
  0.198 ██        docs/auth.md

These files have historically been edited together with the ones above.
Consider whether your change also needs to touch them.

Requires the synapse graph to have accumulated edges. Cold graphs (first few sessions) return empty results. Also available as the neuralmind_review MCP tool.

Wiki reference: Tier2-Operator-Guide · Upgrade-Guide

onboarding (v1.7.0+)

Walk a new operator through license activation, governance defaults, admin email setup, and verification. The entry point for strangers who just ran neuralmind wakeup . and want to configure their project.

neuralmind onboarding              # interactive mode — walks all 5 steps
neuralmind onboarding --quick      # skip all prompts, defaults only

Options

What it walks through

1. License activation — checks for license.json. If missing, auto-issues free tier (or activates Team license if provided).
2. Governance defaults — sets publishing_scope (personal/shared/both) and weight_threshold (0.0–1.0).
3. Admin email setup — adds admin emails for governance notifications.
4. Team seat audit — lists current seats (neuralmind team seats list).
5. Verification — prints license status + governance state.

Sample Output

$ neuralmind onboarding --quick

✓ Free tier activated (1 seat, never expires)
✓ Governance: scope=both, threshold=0.1
✓ Admin: (none — free tier)
✓ Seats: 1/1 (free)

Run `neuralmind team license status` to view.

Honest scope

• Free tier: onboarding --quick configures governance but doesn’t issue paid license
• Team tier: requires neuralmind team license activate <file> before seat management works
• Onboarding doesn’t install hooks or build the index — see neuralmind install-hooks and neuralmind build

optimize-docs (v1.7.2+)

Run the DocEvolver — an evolutionary JSDoc optimizer that finds undocumented methods, generates JSDoc variants using mutation strategies, and evolves them against a retrieval fitness function (Recall@1).

neuralmind optimize-docs <project_path> [OPTIONS]

Arguments

Options

Examples

# Run full audit + evolution on a project
neuralmind optimize-docs .

# Dry-run (report only, no file changes)
neuralmind optimize-docs . --dry-run

# With pre-computed blind spots from probe
neuralmind probe . --json > spots.json
neuralmind optimize-docs . --blind-spots spots.json

# Custom evolution parameters
neuralmind optimize-docs . --population 10 --generations 8 --hysteresis 0.03

# Machine-readable output
neuralmind optimize-docs . --json

How it works

1. Sample — generates N JSDoc variants per undocumented method via four mutation strategies: LENGTH (1/3/5-line), STRUCTURE (Args/Returns vs prose-only vs mixed), KEYWORD_DENSITY (method-name synonyms vs generic description), POSITION (above vs inline for arrow functions).
2. Evaluate — patches each variant into the source, runs a natural-language query, and scores Recall@1 = 1/rank of the correct file.
3. Promote — the best variant beats the incumbent by the hysteresis margin, then mutates around it for the next generation.
4. Patch — after G generations, the winning JSDoc is written back to the source file.

Sample Output

$ neuralmind optimize-docs . --dry-run

DocEvolver — my-project
============================================================
Blind spots found: 12 undocumented methods
  - handle_csv_export()  (utils/csv.py)
  - parse_headers()      (utils/csv.py)
  - validate_schema()    (models/base.py)
  ...

Run without --dry-run to evolve JSDoc for these methods.

Files

• neuralmind/doc_evolver.py — main module (1181 lines)
• tests/test_doc_evolver.py — 44 tests

Exit Codes

Environment Variables

Vector backend selection (v0.21.0+)

NeuralMind’s vector store is pluggable. The default is auto (an unset config behaves the same): it resolves to the ChromaDB-free turbovec backend when its stack (turbovec + onnxruntime + tokenizers) is importable, and otherwise falls back to chroma. As of v0.29.0 the turbovec stack is a platform-gated base dependency, so a plain pip install neuralmind resolves to turbovec (ChromaDB-free) out of the box on platforms with turbovec wheels (Linux, macOS arm64, Windows x86_64). On platforms without a turbovec wheel (Intel macOS, Windows ARM) ChromaDB is auto-installed as the fallback backend, so the install always works. Install pip install "neuralmind[chromadb]" (and pin backend: graph) to force ChromaDB anywhere. (Alpine/musl Linux: use a python:slim glibc image or the [chromadb] extra — markers can’t gate musl.)

To pin a backend explicitly (an explicit value always wins over auto), drop a neuralmind-backend.yaml at the project root:

backend: turbovec   # the default path: TurboVec ANN + bundled OnnxMiniLMEmbedder
# backend: graph    # force ChromaDB (alias: chroma) — needs `pip install "neuralmind[chromadb]"`
# backend: auto     # the default — turbovec when its deps are installed, else chroma

The turbovec/ONNX stack ships by default; pip install "neuralmind[chromadb]" adds the opt-in ChromaDB backend. Vectors are byte-identical between backends, so retrieval quality is at/above parity; the turbovec index is 8–16× smaller. Selecting graph/chroma without the [chromadb] extra raises an actionable error pointing at the install command. Accepted values: auto (default), graph / chroma, turbovec, in_memory (offline tests).

One-time auto-reindex. When auto resolves to turbovec for a project that still has a legacy ChromaDB index and no turbovec index yet, the next build reindexes from graph.json and prints a one-line notice. The old ChromaDB index is left in place as a fallback — nothing is deleted.

Run neuralmind doctor to see which backend the current environment resolves to (see the Backend line).

Examples

Complete Workflow

# 1. Build neural index (the code graph is generated automatically)
neuralmind build ~/projects/myapp

# 3. View statistics
neuralmind stats ~/projects/myapp

# 4. Get wake-up context for new conversation
neuralmind wakeup ~/projects/myapp > context.md

# 5. Query specific functionality
neuralmind query ~/projects/myapp "How does the payment system work?"

# 6. Search for specific entities
neuralmind search ~/projects/myapp "PaymentController" --n 5

# 7. Run benchmark
neuralmind benchmark ~/projects/myapp

Scripting Integration

#!/bin/bash
# update_and_query.sh - Update index and run queries

PROJECT="$1"
QUERY="$2"

# Rebuild if graph changed
if [ graphify-out/graph.json -nt graphify-out/neuralmind_db ]; then
    echo "Graph updated, rebuilding index..."
    neuralmind build "$PROJECT"
fi

# Run query
neuralmind query "$PROJECT" "$QUERY" --json

Piping to AI Tools

# Get context and pipe to clipboard (macOS)
neuralmind wakeup ~/projects/myapp | pbcopy

# Get context and pipe to clipboard (Linux)
neuralmind wakeup ~/projects/myapp | xclip -selection clipboard

# Save context to file for AI assistant
neuralmind query ~/projects/myapp "Explain the auth system" > auth_context.md

See Also

• API Reference - Python API documentation
• Architecture - System design details
• Integration Guide - MCP and tool integrations