NeuralMind v4.21.0 — an agent that can see NeuralMind: MCP server instructions, a six-tool default list, and the leading file’s code in the prompt block; and Intel macOS and Windows ARM work again out of the box

The task-outcome pilot ran the same agent on 20 real bug fixes with and without NeuralMind: 120 runs. NeuralMind made no difference: median cost per task +0.0% (95% CI −5.2% to +8.6%), 18 of 20 tasks solved either way. Replaying what NeuralMind gave the agent in those runs, with no agent and no API cost, showed why:

• The agent never saw what the tools were for. Claude Code defers MCP tools: the model sees their names and has to look a tool up before it can call it. It saw 28 names, no descriptions and no word on when to use any of them, and called none in 60 runs.
• The prompt block named the right file and the agent searched anyway. The UserPromptSubmit hook named the file the fix changed in 17 of 20 tasks. The agent made a median of 4 search or read calls before its first edit, with NeuralMind or without it.

This release changes both, and the agent’s behaviour on those 20 tasks didn’t change: an exploratory rerun with this release found the agent still called no NeuralMind tool, and searched as much before its first edit as without NeuralMind (measured after). What the release does change, and what it doesn’t, is below.

What changed

The MCP server says what it’s for

The server now sends instructions in its initialize reply. Claude Code shows a server’s instructions to the model even while that server’s tools are deferred. They say: to find where something is implemented, or the code behind a bug from its symptom, call neuralmind_search before Grep or Glob; neuralmind_query to understand how a part works; neuralmind_skeleton, neuralmind_impact and neuralmind_query_decisions for structure, dependents and recorded decisions; and to start from a prompt’s NeuralMind block when it has one.

Asked, before calling anything, which tool it would use to find the code behind a bug, Claude Code 2.1.287 on Sonnet 5.5 answered “NONE” with v4.15.1’s server, and “neuralmind_search”, quoting the instructions, with this one.

tools/list offers six tools by default

neuralmind_search, neuralmind_query, neuralmind_skeleton, neuralmind_impact, neuralmind_wakeup and neuralmind_query_decisions. The other 22 (build, stats, benchmark, savings, the synapse tools, health, review, compliance report, document ingestion, and the rest of the decision tools) are still served: a client that calls one by name gets the same answer as before. They’re just not in the list an agent chooses from.

The prompt block shows the leading file’s code

When one file clearly leads the prompt’s matches (their summed score is at least twice the next file’s), the block the UserPromptSubmit hook adds (and the Hermes plugin’s pre_llm_call hook) now quotes that file’s best-matching function or class:

Code matching this prompt:
- neuralmind/secret_scan.py: redact_text() L479, scan_text() L402, …
- neuralmind/output_cache.py: …
Most matches are in neuralmind/secret_scan.py. Its best match, L348-L377 (read the file before you edit it):
```
def _scan_line(…):
    …
```

• From the working tree, so it is what the agent would read; from the symbol’s first line to the line before the next symbol the graph records in that file, at most 40 lines.
• Secrets are redacted with the same scanner neuralmind last uses.
• No lead, no code: with no file 2:1 ahead, the block is the file list as before. NEURALMIND_RECALL_EXCERPT=0 turns the excerpt off.

evals/task_outcome/replay.py: the hook, scored offline, in CI

It exports each of the pilot’s 20 tasks at the fix’s parent commit, builds the index, sends the task’s prompt through neuralmind _hook prompt-submit, and scores the block against the fix’s own diff. A new workflow, Prompt-recall replay, runs it on every pull request that touches the recall path and fails below its floors. Measured on this release:

The last row is the honest limit of the excerpt. The best-matching symbol is usually in the right file, and usually not the function the fix touched: a symptom reads like what the code is about, not where it breaks. The excerpt’s gate was set on these same 20 prompts, so 7 of 9 is a ceiling, not an estimate.

Measured after: the agent’s behaviour didn’t change

An exploratory rerun (not pre-registered) ran the pilot’s 20 tasks again, 3 times each, with this release in the NeuralMind arm. Same model, Claude Code version, prompts and budget, against the pilot’s baseline runs:

• The instructions reached the model and didn’t change its choice. Asked, it names neuralmind_search; given a real bug, it used Grep and Read in all 60 runs and never called ToolSearch, which a deferred tool needs first.
• The excerpt didn’t replace the agent’s own search. On the 9 tasks where the block quoted code, the agent made a median of 4.0 search or read calls before its first edit, against 3.0 without NeuralMind.
• Cost: median −2.1% per task against the baseline (95% CI −6.9% to +6.5%, p = 0.34), 18 of 20 tasks solved in each arm. No difference shown.

On these tasks an agent finds the file to fix in about four searches with or without help, which leaves little to save. Whether NeuralMind changes the outcome on a larger, unfamiliar repository with harder fixes is not measured yet.

Intel macOS and Windows ARM work again out of the box

turbovec publishes wheels for Linux, Apple Silicon macOS and 64-bit Windows. On every other platform, notably Intel macOS and Windows ARM, pip install neuralmind installs ChromaDB in its place. That has been the design since the default install went ChromaDB-free (#251): the default backend was auto, which used turbovec where it was installed and ChromaDB where it wasn’t.

v0.46.0 made the default a fixed turbovec and dropped that fallback, but left the install markers as they were. From v0.46.0 to v4.20.0, on those platforms, a default install selected a backend it didn’t have: neuralmind build, and everything that builds, failed with No module named 'turbovec' unless the project set backend: graph. neuralmind demo failed the same way. Some of our docs described setting backend: chroma there as required.

v4.21.0 restores the fallback. Nothing changes where turbovec is installed.

The default backend falls back to ChromaDB where turbovec isn’t installed

With no backend configured, or with backend: auto or backend: turbovec, NeuralMind uses turbovec when its stack (turbovec, onnxruntime, tokenizers) imports, and ChromaDB when it doesn’t and ChromaDB does. That is the install you get on Intel macOS and Windows ARM.

• No deprecation warning for it. Choosing backend: graph or chroma yourself still warns that ChromaDB is deprecated; the fallback doesn’t, since you didn’t choose it.
• neuralmind doctor shows it. Its Backend line reports the backend in use, graph (auto-selected; turbovec stack not installed) on those platforms. It also stops calling a project with no neuralmind-backend.yaml “pinned via neuralmind-backend.yaml”, which it had done since v0.46.0, and says so when a file names turbovec but ChromaDB serves it.
• An existing backend: chroma keeps working and can stay or go: the default now selects the same backend there.

A missing backend says what to install

If neither turbovec nor ChromaDB is installed (say, both were uninstalled), NeuralMind used to fail deep inside a build with a bare ModuleNotFoundError. It now stops when it creates the backend, with what to install:

the turbovec backend needs turbovec, which isn't installed. Install it with
`pip install turbovec onnxruntime tokenizers`; where turbovec has no wheel
(Intel macOS, Windows ARM), install ChromaDB instead with
`pip install "neuralmind[chromadb]"`.

neuralmind demo on ChromaDB

The demo’s bundled index and question vectors (v4.19.0) are turbovec’s. On a ChromaDB install the demo now builds the sample’s index with the embedding model instead, which downloads it once, and says so:

[demo] this install uses the ChromaDB backend (turbovec has no wheel for this
platform), so the demo builds the sample's index with the embedding model,
which downloads it once.

Offline, it exits 1 with one line saying the model couldn’t be downloaded, not a traceback. With no vector backend at all it exits 1 with the install hint above. The demo runs offline, with nothing downloaded, where turbovec is installed: Linux, Apple Silicon macOS and 64-bit Windows.

What the agent sees on Intel macOS and Windows ARM

On Linux, Apple Silicon macOS and 64-bit Windows, this part changes nothing.

On Intel macOS and Windows ARM, every integration works without a neuralmind-backend.yaml:

The first build on those platforms downloads ChromaDB’s embedding model once. For an air-gapped install, stage ChromaDB’s model cache as the air-gapped walkthrough describes.

Tests

• tests/test_backend_manager.py: the default and turbovec resolve to ChromaDB when only ChromaDB is installed, with no deprecation warning; stay turbovec when its stack is installed or when nothing is; explicit backends are never rerouted; a missing turbovec names what to install.
• tests/test_doctor.py: no config file reads as auto-selected, on either backend; a turbovec pin served by ChromaDB says so.
• tests/test_cli.py::TestCLIDemoWithoutTurbovec: on ChromaDB the demo says it is building with the model and exits 1 with one line when offline; with no backend it exits 1 with the install hint.

What the agent actually sees post-install

Upgrading

• If an agent or script relies on a tool outside the six, by name, it keeps working. If an agent needs to see it to choose it (Cursor’s tool picker, say), set NEURALMIND_MCP_TOOLS=all, or name the tools, in the MCP server’s environment.
• Nothing to rebuild: the excerpt reads the index you have.
• On Intel macOS and Windows ARM you can delete a backend: chroma line you added only to make NeuralMind run; it is harmless to keep.

New environment variables

Use cases

• Existing: NeuralMind in Claude Code. The agent gets the tool it should reach for named in the server’s instructions and, on prompts where NeuralMind is confident, the code itself.
• New: check what your agent is handed before paying for agent runs. python -m evals.task_outcome.replay scores what the hook shows for a set of bug-fix tasks against their real fixes, offline. The harness that measures the outcome (evals/task_outcome/run.py) can then measure whether it mattered.