🧠 NeuralMind Wiki

Reduce Claude, GPT, and Gemini token costs 12–50× on code questions. Local semantic codebase index + MCP server + PostToolUse compression hooks for Claude Code, Cursor, Cline, Continue, and any LLM.

Welcome — this wiki is the in-depth reference. For the fastest orientation, use the two pages at the top of Quick Links.

Why NeuralMind — four data-backed benefits

NeuralMind is more than token reduction. Every claim below ships with a committed eval. The first two run on real, pinned OSS repos (requests, click) and are fully reproducible — python -m evals.public.run. The last two are measured A/Bs on the bundled reference fixture, so they’re real but smaller-scope.

Honest scope: the cost and accuracy rows run on real, pinned OSS repos (fully reproducible — see methodology); the “beats ripgrep” claim is specifically against ripgrep — a bare vector-RAG baseline ties NeuralMind’s recall at fewer tokens, see “Where NeuralMind loses”; the learning and grounding rows are committed A/Bs on the bundled reference fixture, so they’re real but smaller-scope. We report where NeuralMind doesn’t win too — a well-tuned vector RAG ties it on pure findability and is cheaper on raw tokens; that’s in the benchmark table. The competitor comparison is pure retrieval ranking, not their LLM-agent loop. Full numbers and reproduction commands on the Benchmarks page.

What’s New

N-16 — Content QA System: Book/Markdown Retrieval (August 2026)

Extends NeuralMind from code-only to long-form content retrieval. Indexes 150K-word books via neuralmind ingest-content CLI. 30-query Underground manifest with graded relevance (0-3) per ~150-word chunk. N-15 IR metrics (recall@k, MRR, nDCG@5) + RAGAS faithfulness on compressed context. 7 CI regression gates with per-shape breakdowns (precise/thematic/entity/temporal/causal). Spec: CONTENT-BENCHMARK-SPEC.md.

N-15 — SOTA Retrieval Quality Benchmarks (August 2026)

Graded relevance (0-3) + standard IR metrics (nDCG@5, MRR, recall@k, precision@k) + RAGAS faithfulness scoring on compressed retrieval output. 8 CI regression gates with per-shape breakdowns (focused/cross-file/identity). Zero-tolerance gate catches complete retrieval failures that averaged metrics hide. Consumes existing ragas.py stdlib-only judge — no embedding stack required. Spec: RETRIEVAL-BENCHMARK-SPEC.md.

N-13 — Business-Context Synapse Seeding (August 2026)

seed_from_documents() builds deterministic, LLM-free associations between business documents (decisions, SOPs, meeting notes, policies) and your code graph. Compound matches require adjacency in text (not just presence), title-reference cross-linking connects related business docs, and frequency-capped tags prevent common terms from dominating. 56 tests. This is the backbone of the “second brain” expansion (N-06 scope decision).

v3.1.4 — Dogfood Fixes + Code/Document Scoring (August 2026)

v3.1.4 resolves all 12 dogfood issues from v3.1.2 and introduces code/document scoring for better retrieval precision.

What’s fixed:

• P0: Role-gated tools, auto-rebuild hint, incremental build
• P1: .neuralmindignore, markdown bloat
• P2: Unknown edge relations, audit queries, SOC2, type filter, cross-project
• P3: Synapse pruning, health check endpoint

What’s new:

• Intent detection — auto-detects code vs doc queries, boosts relevant nodes 2-3×
• Health check — neuralmind health with exit codes (0/1/2) for CI/CD
• Synapse pruning — neuralmind synapse prune/stats with LTP protection
• Cross-project search — neuralmind query --projects a,b "question"

Full details: RELEASE_NOTES_v3.1.4.md

v3.0.2 — Post-Extraction Cleanup (August 2026)

The self-improving loop (signal→insight→experiment→promote) was extracted to a private repo (dfrostar/agencyOS). NeuralMind is now pure code intelligence — the public package ships only what your agent needs.

• Agent OS extracted. 12 modules moved to dfrostar/agencyOS. The public repo is leaner.
• Dashboard rebranded. Agent/Agency OS references removed from ROADMAP and tests.
• v3.0.0, v3.0.1 — SBOM publishing, license cleanup, extraction follow-through.

v2.0.0 — Compliance Engine + neuralmind init (August 2026)

12–50× typical savings — updated from the 12-50× estimate with founder-benchmarked results on local production repos. The original number was real vs a naive “dump all files” baseline (~30K tokens); 12–50× is the realistic range against a 10K-token human baseline. Up to 50×+ for targeted queries.

New compliance capabilities for regulated teams, plus a one-command project init.

Claim tiering:

• 44× avg vs 30K naive baseline — Tier C (self-measured, reproducible via neuralmind benchmark .)
• 12–25× vs realistic 10K human baseline — Tier C (self-measured, same pipeline)
• “Up to 50×+” for targeted queries — Tier D (hypothesized, depends on query shape)

v1.7.1 — Schema hotfix + autopilot integration (July 2026)

Synapse schema fix adds half_life_days + learned_at columns before CREATE TABLE to fix sqlite3.OperationalError on existing databases. Autopilot v0.10.1 ships with self-improving loop (15-min systemd tick). Path migration from /home/dtfrost/ to /home/dtfrost5/.

v1.7.0 — Free tier auto-provision + upgrade funnel (July 2026)

Free tier now auto-provisions on first wakeup. pip install neuralmind && neuralmind wakeup . writes the license on first run — zero signup wall, zero “team” default breaking free onboarding.

• Free tier auto-provision: cmd_wakeup checks for ~/.config/neuralmind/license.json; if missing, calls issue_free_license() and prints activation message
• Default tier changed: Tier2Config.tier default flipped from "team" to "free" — fresh tier2.yaml no longer triggers downgrade guard
• Upgrade CTA: Counter fires one-liner Team CTA at call 10 (NeuralMind Team: $29/user/mo — shared memory, governance, seat management)
• Tests: 21/21 tier2 tests pass, 191/191 total across tier2 + config + license-validator suites

Acceptance: free license created on first wakeup, idempotent on repeat calls, CTA fires exactly once at call 10.

v1.4.0 — Louvain modularity clustering

build_graph now assigns communities via Louvain modularity over structural code-dependency edges. Previous versions assigned one community per file — every file in src/auth/ was its own community even if it imported heavily from src/users/. v1.4.0 groups them: files with many inter-edges collapse into one community, isolated files (docs, configs) stay separate.

Stdlib-only pure-Python Louvain, O(n·k), deterministic output.

Acceptance: 1582+ tests pass, bench/ repos verify expected community counts.

v1.0.0 — Team tier ships

NeuralMind Team is the paid tier for engineering teams of 5-50 seats: $29/user/mo, annual contract. Adds team memory governance, immutable audit log (SHA-256 hash-chained append-only), self-hosted deployment (docker-compose, one-command install), and seat management on top of the MIT core. Ed25519-signed license validation with 30-day offline grace. Acceptance: 46 unit + integration tests.

Full details: RELEASE_NOTES_v1.0.0.md

v0.52.0 — Impact: blast radius under a name you’d actually reach for

A Reddit comparison against GitNexus flagged “no impact tool” as a gap. Not quite right — neuralmind structural --blast-radius has answered “what depends on this?” since v0.42.0 — but the naming critique landed. v0.52.0 gives the same capability a name an agent (or a human) would actually reach for, plus richer output. Each dependent row now carries its hop and its relation (calls/inherits/imports_from/implements). The MCP tool is neuralmind_impact(). structural --blast-radius stays byte-identical — now a one-line wrapper over the same blast_radius_detail(). Honest scope: naming + discoverability, no new capability.

Full details: v0.52.0 release notes · docs/use-cases/blast-radius-before-a-rename.md

v0.51.3 — Shipped

CI green, GitHub Release published, GHCR published, PyPI verified at 0.51.3.

Full details: v0.51.3 release notes

v0.50.0 — Metrics Dashboard + Team Memory Integration

neuralmind metrics --summary, --days, --json, plus /api/metrics HTTP endpoint. Full team memory integration test (E1→E2→E3→E4 chain). Autopilot engine orchestrator + bug fixes (signals Page-Hinkley, self_play IDs, experiment_runner docstring).

Full details: v0.50.0 release notes

v0.49.5 — DeepSeek Patches

Applied DeepSeek QA patches: prune dangling edges, remove dead code, fix axis independence in tuner faithfulness.

v0.49.4 — DeepSeek QA

DeepSeek code review of incremental wiring, tuner, and autopilot modules. One CRITICAL finding (concurrent build locking — needs fcntl.flock()), two WARNING findings patched.

v0.49.3 — Incremental Extraction Wiring

Wired IncrementalExtractor into build_graph() — scope re-extraction to changed files + importers. Acceptance: 10K-line repo, 1 file changed → <10% of full-build wall-clock.

v0.49.2 — DeepSeek Wave 5 QA

DeepSeek review of tuner v0.49.0 and graphgen incremental wiring. CRITICAL: NaN/Inf guard, _clamp() does NOT defend against NaN. WARNING: inverted time filter in _get_param_changes. Patched.

v0.49.0 — Tuner Faithfulness Gap

Live A/B eval: configure the embedder per candidate, run ~20 fixture queries, measure real retrieval_quality (nDCG@5) and session_health (re-query-rate).

v0.48.0 — v2.0 Complete

All four waves of the v2.0 future-proofing plan complete (26 workstreams, 7 buckets).

v0.47.0 — Impact Tool (original)

Original impact tool release. Superseded by v0.52.0.

v0.21.0 — ChromaDB-free retrieval

The opt-in turbovec backend can now embed and search with zero ChromaDB: Google Research’s TurboQuant compressed index (8–16× smaller vectors) plus a bundled OnnxMiniLMEmbedder that produces vectors byte-identical to ChromaDB’s (all-MiniLM-L6-v2; verified cosine 1.0). Retrieval stays at/above parity (fact recall 0.744 → 0.800). Enable with backend: turbovec in neuralmind-backend.yaml — see the ChromaDB-free local walkthrough. This retires the dependency behind the recurring CVE-2026-45829 advisory; flipping the default is the staged next step. Full details: v0.21.0 release notes.

v0.20.0 — Measure the onboarding lift

neuralmind eval --onboarding turns NeuralMind’s differentiator into a number: does an agent that inherits a committed team memory retrieve better on its first queries than a cold agent? The headline is the top-k module hit-rate lift (run-dependent: +0.9 to +11.6 points observed across runs on the reference fixture, and trending toward the low end of that band as the cold-path baseline itself improves, leaving less headroom for the memory layer to add), with fact-recall + grounding as honest secondaries; budget-neutral, gated in CI at lift ≥ 0. Full details: v0.20.0 release notes.

📊 New: a single Benchmarks & Results page collects every measured, CI-gated number (token reduction, faithfulness delta, synapse and onboarding lift, pts, ChromaDB-free parity) with reproduction commands.

v0.14.0 — Measure faithfulness

neuralmind eval turns “does the memory make answers better, not just shorter?” into a number: it scores whether NeuralMind’s selected context contains more of the facts a correct answer needs than a matched-budget naive baseline (a faithfulness delta), plus grounding and contradiction checks. 100% local by default (--json and --selfcheck too); the LLM-as-judge is opt-in. It’s a contributor/CI quality gate — run it from a source checkout (the evals/ gold set isn’t bundled in the pip wheel; from an installed wheel the command points you at the repo). The first release where you can measure answer quality, not just token reduction. Full details: v0.14.0 release notes.

v0.13.0 — Measurement foundation

The scaffolding to prove the memory helps, not just claim it: a 100%-local faithfulness eval (a versioned query + gold-fact dataset and an offline expected-fact-recall scorer), polyglot retrieval fixtures (TypeScript + Go) so quality is measured beyond Python, and a written documentation process. No runtime change to your install — this is the fitness function the eval-first roadmap (v0.13→v0.16) builds on. The full neuralmind eval report is the next increment. Full details: v0.13.0 release notes.

v0.12.0 — Install Doctor

neuralmind doctor inspects an install (code graph, semantic index, synapse memory, MCP server, Claude Code hooks, query memory) and reports each piece with a status and the exact fix; --json for agents, non-zero exit to gate CI. Full details: v0.12.0 release notes.

v0.11.0 — Directional Synapses

The synapse layer now learns what comes next, not just what goes together: a synapse_transitions table, a next_likely() API, the neuralmind next CLI, and the neuralmind_next_likely MCP tool. Full details: v0.11.0 release notes.

v0.10.0 — Agent Ergonomics

A content-aware PostToolUse compression footer (categorized line counts + repeated-line detection) and neuralmind last to recover dropped middle output without re-running the command. Full details: v0.10.0 release notes.

v0.9.0 — Enterprise-Ready

Phase 3 of the release arc. Every tagged release now auto-publishes a multi-platform container image to GHCR (ghcr.io/dfrostar/neuralmind:vX.Y.Z and :latest, linux/amd64 + linux/arm64) and attaches a CycloneDX JSON SBOM to the GitHub Release. New docs/use-cases/air-gapped.md walkthrough covers the strictest deployment posture — no outbound network at install, build, runtime, or query. New docs/COMPLIANCE-SUMMARY.md consolidates NIST AI RMF + SOC 2 + GDPR claims previously scattered across SECURITY-GUIDE.md and the now-extracted enterprise docs, with a “how to verify yourself” command for every claim.

No production code changes — pure CI + docs. Full details: v0.9.0 release notes.

v0.8.0 — Always-On

neuralmind watch and neuralmind serve are first-class production processes now. Committed systemd and launchd templates, plus a Windows Task Scheduler walkthrough in the Scheduling Guide, keep both running across reboots and crashes. neuralmind serve exposes a /healthz endpoint (unauthenticated, returns {"status":"ok","version":"…"}) for Docker HEALTHCHECK and systemd ExecStartPost probes. Cross-platform walkthrough at docs/use-cases/always-on.md.

Distribution (v0.7.0) made NeuralMind reachable. Always-on (v0.8.0) makes it persistent — the synapse store accumulates 24/7 whether you’re at the keyboard or not. Full details: v0.8.0 release notes.

v0.7.0 — Install anywhere

NeuralMind now installs five ways: pip, pipx, uv, Docker, and source. Same package, same CLI, same MCP server, same graph view — every path. The Quick Start matrix lives at the top of the Installation page and the README; the repo’s root Dockerfile is multi-stage, non-root, and pre-wheels every transitive dep so the runtime image doesn’t need a C toolchain. PyPI keywords got a long-overdue refresh too, so search ranking for graph-view, hebbian-learning, and friends finally matches the v0.6.0 product copy.

Also in v0.7.0: a P2 fix in the JSONL bridge (rotation race that could drop events under logrotate/copytruncate) and a test-coverage gap on /api/queries. Full details: v0.7.0 release notes · Install paths walkthrough.

v0.6.0 — Graph view + live activity feed

neuralmind serve now streams synapse + file events to the canvas in real time over SSE. Affected nodes pulse as the brain works; a sidebar log keeps the most recent ~80 events. A cross-process JSONL bridge means a separate neuralmind watch daemon, a Claude Code session, or any other process feeds the same live feed via <project>/.neuralmind/events.jsonl. Pin UX (visible glyph, Pin/Unpin button, Unpin-all), Cmd/Ctrl-K quick-switch, a 1–3-hop depth slider, replay-last-query overlay, edge tooltips, and a min-weight synapse slider round out the release.

The pitch flipped: v0.5.4 made the brain inspectable; v0.6.0 makes it legible. You can sit there and watch the hippocampus learn your codebase, live.

Multi-tool unlock: every agent (Claude Code, Cursor, OpenClaw, Hermes-Agent) talking to the same project reinforces the same synapse store, and the v0.6.0 canvas now shows the union of their activity. See docs/use-cases/multi-agent.md.

Full details: v0.6.0 release notes · Architecture: event bus + JSONL bridge · CLI Reference: neuralmind serve

v0.5.4 — Graph view foundation

The Obsidian-style force-directed graph that v0.6.0 made live first shipped in v0.5.4. Code nodes coloured by community; structural edges and Hebbian synapses drawn together; backlinks, synaptic neighbours, semantic quick-switch, and one-click open-in-editor. Per-session access token bound to 127.0.0.1 by default. Builds on v0.5.0’s bundled MCP server.

v0.4.0 — Brain-like synapse layer

NeuralMind runs as a second brain alongside the LLM: a persistent SQLite-backed weighted graph that learns associations between code nodes from co-activation, decays unused edges, and answers via spreading activation. Includes the neuralmind watch daemon, three Claude Code lifecycle hooks (SessionStart, UserPromptSubmit, PreCompact), and a memory exporter that surfaces learned associations to Claude Code’s auto-memory system. See the release notes or the Architecture and Learning Guide sections.

Quick Links

Start here

Enterprise & Deployment

Reference

What is NeuralMind?

A two-phase token optimizer for AI coding agents.

• Phase 1 — Retrieval. A 4-layer progressive-disclosure index surfaces ~800 tokens of structured context for any code question, instead of loading 50,000+ tokens of raw source.
• Phase 2 — Consumption. PostToolUse hooks (Claude Code) compress Read, Bash, and Grep output before the agent sees it — typically 88–91% smaller.

Combined effect: 12–50× retrieval token reduction (6.2× measured in CI on the fixture), offline and model-agnostic.

The core problem

You: "How does authentication work in my codebase?"

❌ Traditional: Load entire codebase → 50,000 tokens → $0.15-$3.75/query
✅ NeuralMind: Smart context → ~800 tokens → $0.002-$0.06/query

When do I reach for it?

Short answer: if any of these describe you, start with the Use Cases page.

• My Claude Code session hits context limits mid-task
• My monthly LLM bill is climbing
• I start every session re-pasting project structure
• The agent reads a 2,000-line file to answer one question
• I want to query my codebase from ChatGPT / Gemini / a local model
• I need AI coding help but code can’t leave my machine

Full symptom-and-goal matrix in the main README.

Quick Start

# Install
pip install neuralmind

# Setup
cd your-project
neuralmind build .

# Use
neuralmind wakeup .
neuralmind query . "How does authentication work?"
neuralmind skeleton src/auth/handlers.py

Claude Code users, install the lifecycle hooks (PostToolUse compression plus the v0.4.0 brain-like synapse hooks: SessionStart, UserPromptSubmit, PreCompact):

neuralmind install-hooks .
neuralmind init-hook .        # auto-rebuild on every git commit (optional)
neuralmind watch &            # always-on synapse learning from file edits (optional)

Compare to alternatives

Full list: Comparisons.

Prove it on your code

Don’t trust fixture numbers — measure it on your own repo:

pip install neuralmind
neuralmind build .
neuralmind benchmark . --contribute

This outputs your reduction ratio, tokens per query, and an estimated monthly savings figure at Claude 3.5 Sonnet pricing. The --contribute flag produces a ready-to-share JSON blob you can paste into a PR (or a benchmark submission issue) to add to the public leaderboard.

Full walkthrough: Does NeuralMind work on your codebase?

Support

• GitHub Issues — bug reports, feature requests
• GitHub Discussions — questions and ideas
• Main README — always the most current overview