🧠 NeuralMind Wiki

Persistent, local-first codebase memory for AI coding agents. A semantic code graph + a synapse layer that learns how you work + an MCP server, Claude Code hooks and a Hermes-Agent plugin — for Claude Code, Hermes-Agent, Codex, Cursor, Cline, Continue, and any MCP client. On the public benchmark: the gold file on 40 of 40 queries at 51–242× fewer tokens than pasting every source file.

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

Why NeuralMind — what the data shows, losses included

NeuralMind is more than token reduction. Every claim below ships with a committed eval. The first two run on real, pinned OSS repos and are fully reproducible — python -m evals.public.run for the four-repo benchmark, python -m evals.public.competitor for the requests/click competitor head-to-head. The last two are measured A/Bs on the bundled reference fixture, so they’re real but smaller-scope — and the last one is currently a loss, published as such.

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 — the plain vector baseline (the top 8 entries of NeuralMind’s own index: names and docstrings, not code) costs fewer tokens and still ranks the gold file higher on flask and rich, though its recall is at or below NeuralMind’s, 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 plain vector index ranks the gold file higher on two of the four repos 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

v4.12.1 — doctor exits 1 on a failed check; examples rank below code (October 2026)

neuralmind doctor exits 1 again when a check fails, as documented (v0.55.0 through v4.12.0 always exited 0), and a leftover index.tvim.stale backup no longer fails it once the index is rebuilt. Example scripts (examples/, demos/, samples/) now rank below the code they demonstrate, as test files have since v4.12.0, unless the question asks for an example (NEURALMIND_EXAMPLE_FILE_FACTOR=1 turns it off). See the release notes.

v4.12.0 — Retrieval that keeps what vector search finds (October 2026)

On the public benchmark, NeuralMind’s own vector index alone — top 8, nothing added — matched or beat the full query pipeline on gold-file recall on all four repositories: the layers on top were taking accuracy away. L3 now holds 8 hits instead of 4, chosen from a pool of the 20 best fused candidates after every re-ranking pass has run over the whole pool, and L2 lists that query’s other candidates (pool ranks 9–20) instead of each cluster’s first seven nodes. Code-or-docs re-weighting applies only when you ask for a type (--type, MCP query_type); the code-signal boost is off; keyword search ignores question words; a node is embedded as its qualified name, module and docstring. The eight hits spread across files, and test files rank below the code they test. JavaScript files (.js, .mjs, .cjs, .jsx) get code nodes. Retrieval eval hit@5 80.0% → 93.3% over 150 questions (21 won, 1 lost, exact McNemar p < 0.0001) at 11% fewer context tokens; on the public benchmark the gold file is found on 40 of 40 queries (v4.11.1 missed 3) at 51–242× fewer tokens. Losses: the retrieval eval still misses 10 of 150, and on flask and rich NeuralMind’s MRR (0.72, 0.83) is still below the plain vector baseline’s (0.74, 0.94). Query p50 was 13–14 ms on the library repos and 21 ms on this repository, on one 4-core machine (266–348 ms before). NEURALMIND_L3_K, NEURALMIND_L3_POOL, NEURALMIND_QUERY_LAYERS, NEURALMIND_AUTO_INTENT_BOOST and NEURALMIND_CODE_SIGNAL_CAP tune or restore it. Run neuralmind build once after upgrading. Release notes.

Also in v4.12.0 — No turbovec store on a ChromaDB project (October 2026)

neuralmind build and neuralmind doctor check whether the turbovec index was quarantined, and both opened the turbovec store to do it, whatever the backend. So on a project with ChromaDB pinned (backend: graph or chroma), every build left an empty .neuralmind/neuralmind_turbovec/store.sqlite behind, and doctor called it “Index version compatible”. Both checks now run only on turbovec projects; elsewhere doctor reports the check as not applicable. Release notes.

v4.11.0 — Prompt recall that names the files a prompt is about and stays quiet when the prompt isn’t about the code, and a session’s own record back after compaction (October 2026)

Prompt-time recall used to add up to eight code nodes to almost any prompt, “thanks!” included, while missing most prompts that were about the code: their best match was often a docstring (rationale) node, which has no synapse edges. Recall now starts from the code node behind that match, and the UserPromptSubmit hook adds nothing when the prompt’s best match scores below NEURALMIND_RECALL_MIN_SIMILARITY (default 0.35). On this repository’s own index, 15 prompts about the code and 15 off-topic ones went from 5/15 and 10/15 getting recall to 15/15 and 1/15; that’s one repository and 30 prompts, and python -m tests.benchmark.recall_gate, run from a source checkout, reproduces the 15/15 and 1/15 or calibrates your own. neuralmind metrics counts how often recall injected or abstained. When it fires, the block names files, symbols and lines: the code the prompt matches, other files, mostly code, that the synapse graph links directly to it, and matching docs. On a freshly built project it used to list doc headings’ neighbours as node ids instead; on fresh indexes it now names a file that answers the prompt for 14 of 14 Click prompts and 14 of 15 held-out prompts about this repository (v4.9.2: 3 and 4), and tests.benchmark.prompt_recall, from a source checkout, reproduces that (commands). After Claude Code compacts a session, the session also gets its own first prompt, latest prompts (as written, up to 200 characters each) and edited files back, alongside the compaction summary. Whether these changes improve answers isn’t measured. Pick up where you left off · NEURALMIND_RECALL_MIN_SIMILARITY · release notes.

v4.10.0 — Hermes can install the NeuralMind plugin itself, and the plugin says why when it can’t work (October 2026)

The Hermes plugin’s directory now carries its own plugin.yaml (declaring requires_hermes: ">=0.21.5") and a README that lists what it reads, writes and sends. So Hermes can install it from a clone of this repository, hermes plugins install dfrostar/neuralmind#neuralmind/hermes_plugin --enable, and Hermes’s catalog check, hermes plugins validate, passes. Installed that way, the plugin runs the neuralmind command on Hermes’s PATH (absolute PATH entries only); neuralmind install-hermes-plugin on a plugin Hermes installed writes only the interpreter and the project. When the plugin can’t start NeuralMind, finds one older than 4.9 (which answers without the session recap), or a call times out, it logs one warning per Hermes process naming the fix: hermes logs --level WARNING | grep -i neuralmind. Fixed: install-hermes-plugin --uninstall disabled the plugin before removing it, which left it on Hermes’s disabled list, so installing it again left it off; it now runs hermes plugins remove neuralmind, which drops its entries from config.yaml. Tested against Hermes v0.21.5 in live hermes chat sessions. install-hermes-plugin.

Also in v4.10.0, opt-in for Claude Code: NeuralMind’s PostToolUse hooks inject nothing by default, because Claude Code adds additionalContext next to a tool result instead of replacing it. With NEURALMIND_BASH_REPLACE=1, the Bash hook replaces one kind of output through updatedToolOutput: pip install and neuralmind build run on their own reach Claude with their progress lines elided and every other line verbatim, and a line mentioning an error, warning, failure or deprecation is never removed. The full output, credentials redacted, is kept under .neuralmind/bash_outputs/, and the replaced result ends with its path. Every other command, failed commands, and Read and Grep results are never replaced. The compression benchmark gates it in CI on keeping the pre-registered must-keep lines. Walkthrough: Trim noisy install logs · release notes.

Also in v4.10.0: neuralmind validate stops reporting the chapter files the prose path records, such as ch01.md, as stale synapses while the index still holds chapters/ch01.md, and the neuralmind.sleep API’s long-term promotion no longer boosts ephemeral edges, which decay never protects.

v4.9.2 — -- works again in the decisions and memory subcommands (October 2026)

v4.9.1 let six decisions and memory subcommands take the project path after their options, but on Python 3.10, 3.11, 3.12 before 3.12.8 and 3.13.0 -- could stop ending their options: decisions query -- -q . failed. -- works again, the path can still follow the options, and every supported Python parses these lines the same way. A path after a list option such as --evidence needs -- before it, which record --help and amend --help now say. Release notes.

v4.9.1 — The last four fixes from the v4.8.2 bug hunt (October 2026)

neuralmind feedback good|bad with query memory off no longer adjusts an older query recorded before memory went off; it exits 1, names that query and says how to turn memory back on. The “LTP-protected” edge count in status, synapse stats and the dashboard uses decay’s own rule, so expect a lower number. neuralmind validate stops reporting the prose path’s query nodes, now written query:<term>, as stale. And the decisions and memory subcommands accept the project path after their options (`decisions restore