Open-source semantic code intelligence for AI agents. Built for cost efficiency, security, and compliance.
NeuralMind is not just "fewer tokens." 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.
ripgrep on both recall and cost. (Public benchmark, real OSS repos.)codebase-memory-mcp on retrieval ranking (0.96 vs 0.23). (Same public benchmark, real repos.)Honest scope: the cost and accuracy rows run on real, pinned OSS repos (fully reproducible — see the methodology); 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.
Every figure below is produced by code in the repo and gated in CI, so it can't silently regress. Where a number is a real-repo extrapolation or an estimate, it says so. Reproduce them all with python -m tests.benchmark.run and the evals/ harnesses — details on the Benchmarks page.
import neuralmind no longer requires ChromaDB, and the default backend is now auto — it prefers the ChromaDB-free turbovec path when its deps are installed, else falls back to chroma. Plain installs are unchanged; neuralmind doctor shows the resolved backend.What we don't claim: the CI numbers come from a tiny fixture (they prove the mechanism and catch regressions, not a real-repo ceiling); TurboQuant is an approximate index whose compression win matters at scale; 40–70× is a range, not a fixed guarantee. Point it at your own repo to see your ratio.
Reach for NeuralMind if you drive an AI coding agent (Claude Code, Cursor, Cline, Continue, or your own MCP/OpenRouter stack) over a non-trivial codebase, you want one shared memory across those agents, you're watching LLM spend on repo-level questions, or you work in a regulated/air-gapped setting that rules out SaaS code search.
You probably don't need it if your repo is under ~5K tokens (just paste it in), you don't use an agent, or you only want inline completions (use Copilot/Cursor directly).
Set expectations honestly: the 40–70× token reduction is a real-repo range — CI measures a conservative 6.2× on a tiny fixture, so prove it on your own code. ChromaDB is still the default (the slim, ChromaDB-free backend is opt-in while it bakes). It's a fast-moving, single-maintainer beta with a lot of surface area — pin a version for CI. The compressed backend is approximate, with parity gated on the reference fixture rather than measured at large-repo scale. If those trade-offs are fine, the upside is real and the receipts are in the repo.
A staged plan — the first increment (v0.13.0) has shipped. After the v0.10→v0.12 ergonomics + diagnostics work, the current arc is about proving and future-proofing the core. The spine is simple: measure, then change, then measure again.
neuralmind eval now reports a faithfulness delta (expected-fact recall vs a matched-budget naive baseline), grounding, and contradiction checks over the gold dataset + polyglot TypeScript + Go fixtures. The onboarding-lift eval is the remaining increment; the LLM-as-judge stays strictly opt-in.Committable, opt-in team/shared memory is approved in principle: a reviewed team baseline that travels in your git repo (no SaaS, no exfiltration), overlaid by each developer's private personal layer. Its day-one onboarding lift will be measured by the v0.13 harness before the design is locked — we sign off on data, not assertion.
NeuralMind is one piece of a broader context engineering ecosystem. Three tools address token waste at different points in the LLM pipeline — and they compose without conflict:
ponytail: and harvested into a technical debt ledger via /ponytail-debt.| Tool | Locus | Primary Mechanism | Verified Savings |
|---|---|---|---|
| NeuralMind | Retrieval | Hebbian synapse networks | 40–70× fewer query tokens |
| Ponytail | Generation | Sequential decision ladder | 80–94% output token savings |
| Headroom | Transport | Reversible CCR loops | 60–95% payload reduction |
For enterprise-scale agentic fleets, the full stack delivers maximum token efficiency, 100% local privacy, and a traceable technical debt ledger. Read the full comparative guide →
NeuralMind's recall has always run on two soft signals — semantic similarity and the learned synapse graph. v0.42.0 adds the hard one the graph carried all along: how the code is actually wired. graphify already extracts typed structural edges — calls, inherits, imports_from, contains — into every graph.json, and the embedder already loads them. Until now they were dead weight, used only by the graph-view UI. This release turns them into a first-class, queryable capability an agent can call. No new extraction, no schema bump, and default retrieval stays byte-identical to v0.41.0.
neuralmind structural <symbol>Ask how any symbol is wired and get its callers, callees, base classes, subclasses, and importers straight from the static graph. The neuralmind_structural_neighbors MCP tool returns the same, shaped for agent consumption; the query may be a symbol name or a natural-language description, resolved to the closest code node (rationale/doc nodes are skipped, since they carry no structural edges). This is the precise, day-one answer to "what calls foo?" — the kind of correctness question an editing agent gets wrong when it changes a function but misses two callers.
neuralmind structural <symbol> --blast-radiusPass --blast-radius (CLI) or blast_radius=true (MCP) to get the transitive reverse-dependency set — everything that (transitively) calls, imports, subclasses, or implements the symbol. It's depth-bounded, cycle-safe, and hub-capped so one over-connected utility can't explode the result. Run it before a rename or a risky change and edit with every affected caller, importer, and subclass in view instead of discovering them from a red CI run.
With NEURALMIND_STRUCTURAL_RECALL=1, a query that lands on a called function also pulls its callers/callees into L3 context — budget-neutral: a pulled-in neighbor displaces the weakest vector hit rather than adding to the count, and recalled nodes are tagged [wired] in the rendered context. This is opt-in, not default: on graphs where the call/inherit signal is strong it can saturate top-k recall and crowd out the tuned synapse signal, so default retrieval is left byte-identical and the always-on structural tools carry the headline value with zero effect on the retrieval stack. The whole layer is killable with NEURALMIND_STRUCTURAL=0.
Full v0.42.0 release notes → | Blast-radius-before-a-rename walkthrough →
Two features that make NeuralMind's half of a modular agent stack real: the retrieval layer now learns from what the agent did, and emits the relevance signal it already computes as structured data a downstream tool can consume. The standard critique of a modular split is that the layers can't see each other — a compressor downstream shrinks spans without knowing why they were retrieved, and nothing feeds what the agent reused vs. rewrote back into memory. v0.41.0 closes NeuralMind's half of both seams. Both are opt-in / off-by-default on the wire, so nothing about default retrieval changes.
A new Edit/Write PostToolUse hook (edit-activity) fires on every edit: it resolves the edited file to its graph nodes, then scans the new code for identifiers that name a symbol defined elsewhere in the graph. Those references are a reuse signal — the edited file and the reused definitions fired together in one thought — so their synapse edges are reinforced, and the existing L2/L3 synapse boost surfaces the reused nodes more readily on future queries. It's the implicit complement to v0.38.0's explicit neuralmind_feedback MCP tool: the agent doesn't have to say anything; NeuralMind observes what it reused from the edit it already made and learns from that. Language-agnostic by construction (it operates on graph nodes and identifier tokens, never on source syntax), a pure side effect that never triggers a build and fails open, and surfaces possible duplication (not yet penalized) when new code redefines a name that already exists. Off-switch: NEURALMIND_REUSE_FEEDBACK=0.
Every retrieved node already carries three relevance signals — a vector similarity score, a learned synapse boost, and a recall flag. The ranked context string renders these as prose, which is fine for the model but opaque to a tool. v0.41.0 exposes them as a structured, parseable relevance block keyed by source file — per-file max_score plus per-node score / synapse_boost / recalled / line spans — built from the post-boost L3 hits, so it reports the same signals the visible context used. Request it with neuralmind_query(include_relevance=true) (MCP) or neuralmind query --relevance (CLI). A downstream compression proxy can read this and protect the load-bearing spans instead of compressing them away. Because the signal travels alongside the payload as versioned, stably-keyed metadata, a tool running after NeuralMind can re-associate it regardless of pipeline order — the sidecar is order-independent by design.
NeuralMind now indexes non-code schema artifacts alongside your source, closing the most-requested documentation gap from the v0.38 audit. Three new extractors join the document layer: OpenAPI/AsyncAPI YAML specs, SQL DDL files, and Protocol Buffer definitions. All three reuse the existing document node type — no new MCP tools, no config changes, no new retrieval concepts. The synapse layer learns cross-artifact associations automatically, so POST /payments/charge co-activated with process_payment() strengthens the synapse edge without any manual wiring.
.yaml, .yml)Parses files that carry an openapi, asyncapi, or swagger key using PyYAML (falls back to JSON). Emits one file-level node labelled by info.title, one node per path+method labelled by summary or operationId (e.g. Charge a card), one node per schema component (e.g. schema:Payment), and one node per AsyncAPI channel. Plain YAML config files (no API key) are silently skipped — NeuralMind never indexes infrastructure config as API documentation. Honest scope: $ref resolution and inline response body schemas are not modelled.
.sql)Regex-matches CREATE TABLE, CREATE VIEW, CREATE PROCEDURE, CREATE FUNCTION, CREATE TRIGGER, CREATE INDEX, and CREATE TYPE statements (case-insensitive; handles OR REPLACE and IF NOT EXISTS variants). Emits one node per database object (e.g. TABLE:accounts, VIEW:active_users). ALTER TABLE, INSERT, and SELECT are not indexed — only DDL CREATE is the object layer agents actually query.
.proto)Regex-extracts message, service, rpc, and enum block headers (proto2 + proto3). Emits one node per definition (e.g. service:UserService, rpc:GetUser, message:GetUserRequest, enum:Status). Proto import edges (cross-file message references) are not modelled as graph edges; GraphQL support is planned for v0.42.0.
Schema files participate in neuralmind watch --reindex. A changed .yaml, .sql, or .proto re-extracts only that file's nodes on the next incremental build pass — same as .py/.ts files. The synapse layer applies the same Hebbian co-activation to schema nodes: if an agent retrieves schema:Payment and then process_payment(), that association strengthens automatically over queries.
Five developer-experience improvements shipped together: dry-run indexing, instant synapse decay on file deletion, retrieval explainability, diff-aware co-break detection, and a cumulative token savings dashboard. None change the retrieval path — progressive disclosure, Hebbian synapses, and team memory are unchanged. Each improvement closes a specific gap in how transparent and trustworthy NeuralMind is to work with daily.
neuralmind build --dry-runScans the project, counts files and lines by language, and prints an estimated token savings table — without touching the vector store or synapses. Safe to run in CI as a pre-build gate. Pass --json for machine-readable output. Typical output: Estimated savings: 6.2× (89,400 tokens → 14,400 tokens) across 247 files.
The file watcher (neuralmind watch) now detects when source files are removed and immediately calls decay_node() on every graph node belonging to that file — using the watchdog on_deleted event (event-driven) or set-difference detection in the poll loop. Deletion callbacks fire without the normal debounce delay, so deleted-code associations are pruned in real time rather than gradually fading over many sessions. Existing watch callers without a deletion_callback are unaffected (the parameter is optional, defaults to None).
neuralmind query --explainAppends a structured trace to query output showing exactly how the context budget was allocated: which layers (L0/L1/L2/L3) fired and how many tokens each consumed, which community clusters loaded, the top search hits with their scores, and which synapse associations influenced recall. This is the primary tool for debugging a retrieval that felt wrong — the trace makes the L0–L3 progressive-disclosure decision auditable.
neuralmind review — diff-aware co-break detectionReads git diff --name-only <base>, maps each changed file to its graph nodes, runs spreading activation (depth 2, top-k configurable) from those seed nodes, and surfaces the most likely co-break candidates — the nodes most strongly associated with the changed code but not themselves in the diff. Prints a ranked table of candidates with their edge weights. Also available as the neuralmind_review MCP tool, so agents can call it automatically before a commit or push. Handles cold (unbuilt) graphs gracefully.
neuralmind savings — cumulative token savings dashboardReads the JSONL event log (NEURALMIND_MEMORY=1), groups events by session, and prints a dashboard: total sessions tracked, total tokens saved, average reduction ratio, and a table of the most recent queries with their individual ratios. Run it after a week of use to get a concrete, cumulative number for the token cost you've avoided.
VS Code users now get first-class NeuralMind integration without Cline or a hand-wired tasks.json. The extension (editors/vscode/) is a thin TypeScript shell over the existing Python CLI and HTTP server — no new retrieval logic, no new Python dependencies.
A persistent status bar item shows index state at a glance: ✓ NeuralMind · 2.1k nodes (green, fresh), ⚠ NeuralMind · 2.1k nodes (yellow, stale), or ⊘ NeuralMind (red, not built). Staleness is measured against graphify-out/graph.json mtime vs. the neuralmind.autoBuildThresholdHours setting. Clicking opens the graph panel.
Ctrl+Shift+P → NeuralMind exposes eight commands: Query (retrieved context to the Output panel), Wakeup, Skeleton (structural outline of the active file), Build Index (with a progress notification), Probe Retrieval (answerability / MRR / recall@k), Open Graph View, Setup Cline MCP, and Setup VS Code MCP.
The neuralmind serve UI is embedded in a VS Code WebView via <iframe> — all existing frontend JS and CSS reused untouched. The panel retains its graph layout when hidden (retainContextWhenHidden: true).
Set "neuralmind.enableHover": true in VS Code settings to get structural skeleton cards on symbol hover, LRU-cached (50 entries, 60 s TTL).
neuralmind install-mcp --client vscode writes the server entry to Code/User/settings.json under "mcp.servers" (VS Code 1.99+ native MCP format). If settings.json is JSONC, the command prints the entry to paste manually rather than clobbering the file.
VS Code extension walkthrough → | Full v0.38.0 release notes →
Three retrieval-quality improvements that directly address the gaps between NeuralMind and LlamaIndex/mem0 on code-specific retrieval. None touch the existing token-reduction machinery — progressive disclosure, Hebbian synapses, and team memory are unchanged.
A code-aware BM25 keyword index is built alongside the vector store and merged via Reciprocal Rank Fusion at query time. The tokeniser splits camelCase (UserService → ["user", "service"]), snake_case (get_auth_token → ["get", "auth", "token"]), dots, and hyphens so identifier fragments score exact-name matches instead of relying entirely on semantic similarity. Queries like "UserService authentication" now rank the exact UserService node first, not just semantically similar nodes. The merge is budget-neutral — same result count as pure vector search, just reordered. Disable with NEURALMIND_BM25=0. The BM25 index is persisted at <project>/.neuralmind/bm25_index.json and rebuilt on every neuralmind build.
The new neuralmind_feedback MCP tool exposes explicit positive/negative signal on a retrieved node — closing the feedback loop gap that mem0 delivers. Positive signal (signal="positive" with context_node_ids) fires an immediate Hebbian reinforcement between the target node and the other nodes from the same retrieval round, identical to what happens during natural co-editing but instant rather than end-of-session. Negative signal (signal="negative") applies a targeted single-tick decay to all synapse edges for that node — LTP-protected edges (activation_count ≥ 5, weight ≥ 0.20) are never fully removed by a single negative signal, so a mis-click can't erase long-established associations.
A drop-in GitHub Action (.github/workflows/neuralmind-autoindex.yml) auto-builds the index on every push to main/master, caches .neuralmind/ under a source-hash key (so only real source changes trigger a re-embed), and auto-commits the updated .neuralmind-team-memory.json team memory snapshot. No secrets needed — NeuralMind is 100% local. Copy it into any repo to get automated indexing and fresh team memory on every push.
The bundled tree-sitter backend now indexes PHP out of the box, taking it to ten languages — Python, TypeScript, Go, Rust, Java, C, C++, C#, Ruby, and PHP — with no external tooling, completing the C#/Ruby/PHP breadth tier. PHP (.php) is registered behind the same _SUFFIX_LANG → _EXTRACTORS seam every other language uses, emitting the same graphify-compatible graph.json the whole retrieval stack already consumes. neuralmind build . now just works on a PHP project, no graphify. The tree-sitter-php grammar is bundled as a runtime dep.
class/interface/trait/enum declarations become type nodes (nested types recurse, contained by the outer type); method declarations and top-level function definitions become function nodes; property declarations (the leading $ is stripped from the label), class const declarations, and enum cases become symbol nodes.use namespace imports resolve to imports_from file→file edges (the imported Acme\Db\Connection matches the file that declares it — resolved by class name, exactly like Java imports — emitted only to existing file ids, so dangling-free by construction); extends/implements produce inherits edges (external bases synthesized so the edge never dangles, mirroring Java/TS); calls (Class::method, $obj->method, bare) are matched by method name, best-effort (the opt-in SCIP precision pass remains the path to compiler-accurate edges)./** */ PHPDoc block comments attach to the symbol they document, feeding the rationale layer (markers stripped) exactly like Javadoc and Rust ///.PHP maps almost 1:1 onto the existing Java extractor plus a namespace layer — class/interface/trait/enum → type nodes; extends/implements → inherits; use → imports_from (resolved by class name, like Java imports) — so it rides a proven shape at the smallest risk, one language per PR, each clearing the parity gate in isolation. This release completes the C#/Ruby/PHP breadth tier. Honestly out of scope: compiler-accurate call resolution (no $obj->method receiver-type resolution; SCIP remains the exact path), require/include path imports (use is the edge source), and trait-use-inside-a-class-body as inheritance (only extends/implements emit inherits).
graphify can't parse PHP standalone, so the gold is a hand-authored expected symbol set — what a correct parser should recover, enumerated from the fixture independently of our implementation. PHP passes the same gate as Rust/Java/C/C++/C#/Ruby — 54/54 symbols (100% structural coverage), zero dangling edges — on a dedicated sample_project_php fixture.
The bundled tree-sitter backend now indexes Ruby out of the box, taking it to nine languages — Python, TypeScript, Go, Rust, Java, C, C++, C#, and Ruby — with no external tooling. Ruby (.rb) is registered behind the same _SUFFIX_LANG → _EXTRACTORS seam every other language uses, emitting the same graphify-compatible graph.json the whole retrieval stack already consumes. neuralmind build . now just works on a Ruby project, no graphify. The tree-sitter-ruby grammar is bundled as a runtime dep.
class and module declarations become type nodes (Acme::Foo scope-resolution → simple name; nested types recurse, contained by the outer type); def foo and def self.foo become function nodes.assignment whose left side is a constant (ATTEMPTS = 3, module constant groups like GET = "GET") becomes a symbol node — Ruby has no static field declarations, so attr_accessor accessors and instance variables aren't emitted as fields.require_relative resolves to imports_from file→file edges (the string arg resolved against the requiring file's directory, emitted only to existing file ids, so dangling-free by construction; a require of a gem/stdlib is external and skipped); class Foo < Bar produces an inherits edge (external bases synthesized so the edge never dangles, mirroring Java/TS); calls are bare-name best-effort (the opt-in SCIP precision pass remains the path to compiler-accurate edges).# doc comments feed the rationale layer (the leading # marker is stripped so it doesn't leak into rationale text), exactly like Javadoc and Rust ///.Ruby is dynamic (no static receiver types), so compiler-accurate call resolution isn't done — calls stays bare-name best-effort and dynamic dispatch / metaprogramming (define_method, method_missing) isn't resolved (SCIP remains the exact path). Mixins aren't modelled as inheritance — include/extend/prepend are not emitted as inherits edges (only class Foo < Bar is). The structural layer — class/module/method structure — is clean and recovers well, which is what the parity gate proves.
graphify can't parse Ruby standalone, so the gold is a hand-authored expected symbol set — what a correct parser should recover, enumerated from the fixture independently of our implementation. Ruby passes the same gate as Rust/Java/C/C++/C# — 46/46 symbols (100% structural coverage), zero dangling edges — on a dedicated sample_project_ruby fixture.
The bundled tree-sitter backend now indexes C# out of the box, taking it to eight languages — Python, TypeScript, Go, Rust, Java, C, C++, and C# — with no external tooling. C# (.cs) is registered behind the same _SUFFIX_LANG → _EXTRACTORS seam every other language uses, emitting the same graphify-compatible graph.json the whole retrieval stack already consumes. neuralmind build . now just works on a C# project, no graphify. The tree-sitter-c-sharp grammar is bundled as a runtime dep.
class/interface/struct/record/enum declarations become type nodes (nested types recurse, contained by the outer type); methods and constructors become function nodes; fields, properties, enum members, and a positional record's parameters become symbol nodes.using directives resolve to imports_from file→file edges (emitted only to existing file ids, so dangling-free by construction); base_list entries produce inherits edges (external bases synthesized so the edge never dangles, mirroring Java/TS); calls are bare-name best-effort (the opt-in SCIP precision pass remains the path to compiler-accurate edges)./// XML doc comments attach to the symbol they document, feeding the rationale layer exactly like Javadoc and Rust ///.C# maps almost 1:1 onto the existing Java extractor — namespaces ≈ packages; class/interface/struct/record/enum → type nodes; base_list → inherits; using → imports_from — so it rides a proven shape at the smallest risk, one language per PR, each clearing the parity gate in isolation. Honestly out of scope: compiler-accurate call/inherit resolution (SCIP remains the exact path), generics/partial-class merging and using aliases, and top-level-statement implicit Main.
graphify can't parse C# standalone, so the gold is a hand-authored expected symbol set — what a correct parser should recover, enumerated from the fixture independently of our implementation. C# passes the same gate as Rust/Java/C/C++ — 52/52 symbols (100% structural coverage), zero dangling edges — on a dedicated sample_project_csharp fixture.
Gold-file recall measures whether the right file lands in the window — locating, not answering. The new opt-in answerability arm (python -m evals.public.run --judge) closes that gap honestly, without ever displacing the deterministic recall headline.
For each query it takes the real context each backend would put in the window — whole files for full-file/ripgrep, retrieved chunks for embedding-rag, the compact L0–L3 assembly for neuralmind — and asks a pinned model (claude-opus-4-8) to answer using only that context (it must say "insufficient context" when the window can't support an answer). A separate judge call grades each answer against the same def-site gold anchor (the query's oracle_symbol) on a 0–2 scale, plus a grounded flag.
bench/public/judge/. Re-score it, or swap the model, yourself.ANTHROPIC_API_KEY, never runs in CI, and the recall table is byte-identical with or without --judge.The public benchmark's competitor row is no longer a scaffold — it's a live, reproducible head-to-head vs. codebase-memory-mcp 0.8.1 (the obvious incumbent: DeusData, single-binary, on-device embeddings, no LLM API key). It runs on the same pinned repos, same questions, same objective def-site gold, scored by the same quality.py as every other backend, at retrieval depth matched to embedding-rag (top-8).
At matched retrieval depth, NeuralMind finds the objectively-correct file every time and ranks it far higher: 100% gold-file recall with MRR 0.96 on requests and 0.60 on click, against the competitor's 0.50 recall / 0.23 MRR (requests) and 0.64 recall / 0.50 MRR (click) — i.e. it surfaces the gold file in its top-8 only ~half the time, and the files it does surface cost an order of magnitude more tokens to read (25K–38K vs ~1K). The win is on reproducible retrieval ranking, not a claim about end-to-end agent behavior.
search. The competitor's published numbers (~90% of an "Explorer" agent across 31 scored languages; C at 0.58) come from an LLM-driven loop that isn't reproducible without paying for an LLM — we cite those as-is and do not claim to reproduce them. Its "158 languages" is vendored grammars, not all benchmarked.ripgrep).The competitor adapter is off the default run (it needs an external binary download). From a clone: pip install codebase-memory-mcp==0.8.1 (pins 0.8.1) and python -m evals.public.competitor. Raw per-query traces, results.json, and pinned REPRODUCE.md are committed under bench/public/competitor/; full caveats live in the "Competitor head-to-head" section of docs/benchmarks/public.md.
The bundled tree-sitter backend now indexes C and C++ out of the box, taking it to seven languages — Python, TypeScript, Go, Rust, Java, C, and C++ — with no external tooling. C (.c/.h) and C++ (.cpp/.cc/.cxx + .hpp/.hh/.hxx) are registered behind the same _SUFFIX_LANG → _EXTRACTORS seam every other language uses, emitting the same graphify-compatible graph.json the whole retrieval stack already consumes. neuralmind build . now just works on a C/C++ project, no graphify.
static helpers, and C++ member functions/methods (including out-of-line Foo::bar definitions) become function nodes; C struct/union/enum (+ fields and enum constants), typedefs, and C++ class/struct with member fields become type/symbol nodes. Namespace-qualified ids keep app::auth::JwtCodec distinct from a global of the same name.#include "local.h" (quoted local includes) resolve to imports_from file→file edges — the C/C++ analogue of module imports; <system> headers are treated as external (no dangling edge). C++ base classes produce inherits edges; calls are bare-name best-effort (the opt-in SCIP precision pass remains the path to compiler-accurate edges).foo.h and foo.c/foo.cpp resolve to a shared module key, so a declaration and its definition land in the same neighborhood — the one C/C++-specific wrinkle Python/Java don't have.C/C++ is where naive multi-language indexers fall over: a widely-cited competitor advertises 158 languages yet scored 0.58 on C because preprocessor density wrecks a shallow parse. NeuralMind takes the opposite tack — index the parseable code at full parity and be honest about what's out. So: preprocessor macros are not indexed as symbols (#defines, including function-like macros, are skipped), templates are not specialized (a template<...> is emitted as one symbol), and #ifdef is not evaluated (conditionally-compiled code is indexed as visible). These are deliberate MVP boundaries, tracked as follow-ups.
graphify can't parse these standalone, so the parity gate proves parity structurally: both C and C++ pass the same gate as Rust/Java — 100% symbol coverage, zero dangling edges — on dedicated fixtures, with hand-listed expected symbols/edges in tests/test_graphgen.py as the independent oracle.
NeuralMind's headline has always been "40–70× fewer tokens on code questions." v0.31 backs it with evidence built to survive hostile expert scrutiny. neuralmind benchmark --public runs a reproducible, no-cherry-picking comparison on real, pinned OSS repos (requests @0e322af877, click @874ca2bc1c), against strong baselines (full-file paste, ripgrep, a same-encoder vector RAG), reporting cost and correctness together — and it ships the forkable runner plus raw data so anyone reproduces it without trusting us. Run it from a source checkout (the evals/public harness ships in the repo, not the pip wheel).
Gold-file recall — an objective def-site oracle, no LLM judge — vs. context tokens (tiktoken o200k_base, deterministic):
requests: NeuralMind reaches 1.00 recall at 1,095 tokens/query — 38× fewer than pasting files (41,729). ripgrep manages only 0.79 recall at 26,543 tokens.click: NeuralMind reaches 1.00 recall at 924 tokens/query — 85× fewer than pasting files (78,514). ripgrep again lands 0.79 recall at 45,059 tokens.Honest headline: against what agents actually do today — paste files or grep — NeuralMind hits 100% gold-file recall at 38–85× fewer tokens, and beats ripgrep on both recall and cost. We also show, without hiding it, that a well-tuned vector RAG is excellent at findability too (and cheaper on raw tokens) — credibility comes from reporting the losses, not just the wins.
git checkout <sha> and audit.rg; scoring reuses the same neuralmind/quality.py the CI gate runs..github/workflows/bench-public.yml regenerates the table on demand; raw per-query data at bench/public/results.json.Full methodology, caveats, and where NeuralMind loses → · v0.31.0 release notes →
NeuralMind's synapse layer learns what code goes with what from how you work. v0.30 makes that learned signal a team artifact. A team commits one file and every teammate's agent inherits the team's learned associations automatically — a fresh git clone starts with the team's earned intuition instead of relearning it from scratch. This is the differentiator a static code-index can't copy: there's no learned signal to share.
neuralmind memory publish exports your personal + shared learned memory to a committed file at the repo root, .neuralmind-team-memory.json (beside .gitignore, not inside the per-machine .neuralmind/ dir, so it travels with git clone).SessionStart (Claude Code) or neuralmind build (Cursor/Cline/generic MCP), the bundle is imported once into the shared namespace, gated by its content hash so it never re-imports.shared namespace already blends into retrieval at 0.5× via merged-read weighting — inherited associations surface co-edited modules a cold textual search ranks lower, with no new tool call.Off-switch NEURALMIND_TEAM_MEMORY=0; writes the shared namespace only (never a teammate's personal/branch memory); MAX-merge + decay mean a stale bundle can't permanently distort recall (neuralmind memory reset --namespace shared clears it); fail-open on a missing/corrupt bundle; and the bundle is association pairs + weights — no source code, no prose — traveling via git, 100% local. Measure the day-one lift with neuralmind eval --onboarding.
On mainstream platforms, pip install neuralmind no longer pulls ChromaDB. The default install uses the ChromaDB-free turbovec/ONNX backend (vectors byte-identical to ChromaDB's), removing ChromaDB's large transitive dependency tree — and the recurring ChromaDB CVE surface — from the default. The vector backend is platform-gated by wheel availability, so the install never breaks: on platforms turbovec has no wheel for (Intel macOS, Windows ARM) ChromaDB is auto-installed as a transparent fallback. ChromaDB is also a one-line opt-in anywhere: pip install "neuralmind[chromadb]" (then backend: graph).
"ChromaDB-free" is not a claim of "smaller install": the turbovec path pulls onnxruntime, a heavy native wheel. The precise win is removing ChromaDB's sprawl (FastAPI / grpcio / OpenTelemetry / kubernetes client / …) and its CVE surface from the default, in exchange for one focused native dependency.
graph.json into turbovec; the old ChromaDB index is kept as a selectable fallback (nothing deleted).pip install "neuralmind[chromadb]".This was low-risk because the migration was staged across v0.21 (the turbovec/ONNX backend) and v0.22 (ChromaDB-free import neuralmind + auto-preferring turbovec); v0.29.0 simply flips which dependency set is installed by default.
The bundled tree-sitter backend now indexes Java out of the box, taking it to five languages — Python, TypeScript, Go, Rust, and Java — indexed in one pass. Java (.java) is registered behind the same _SUFFIX_LANG → _EXTRACTORS seam every other language uses, emitting the same graphify-compatible graph.json the whole retrieval stack already consumes. neuralmind build . now just works on a Maven/Gradle/plain Java project, no graphify.
class, interface, enum, and record declarations become code type nodes; methods and constructors become function nodes contained by their type; fields and enum constants become symbol nodes. Nested types are contained by their outer type.extends/implements become inherits edges (external bases like Runnable synthesized so the edge never dangles); import statements resolve by fully-qualified name into imports_from edges; method invocations become best-effort calls edges./** … */) becomes the rationale layer the selector surfaces in L0–L2. Node provenance is anchored on the identifier's line, so @Override and modifiers never misplace a symbol.graphify can't parse Java, so the parity gate proves parity structurally: the built-in backend must recover ≥90% of the gold graph's symbols with a valid, dangling-free graph. On the reference fixture it recovers 100% (54/54 symbols, zero dangling edges). The independent correctness oracle is a hand-listed set of expected symbols/edges/rationale in tests/test_graphgen.py. Next per the PRD: C/C++ and Ruby.
The bundled tree-sitter backend now indexes Rust out of the box, taking it to four languages — Python, TypeScript, Go, and Rust — indexed in one pass. Rust (.rs) is registered behind the same _SUFFIX_LANG → _EXTRACTORS seam every other language uses, so it emits the same graphify-compatible graph.json the whole retrieval stack already consumes. Nothing downstream of graph.json changed — only the set of languages the producer understands. pip install neuralmind && neuralmind build . now just works on a Rust crate, no graphify.
struct, enum, union, trait, and type items become code type nodes; free functions, impl methods, and trait signatures become function nodes. impl methods are contained by their type, so Connection::get_connection hangs off Connection.impl Trait for Type becomes an inherits edge (Type → Trait); use paths resolve against a module-key table into imports_from edges; call_expressions become best-effort calls edges by name; struct fields and enum variants become symbol nodes.///, //!, /** */) — which are distinct node types from ordinary comments — become the rationale layer the selector surfaces in L0–L2.target/ build directory is skipped automatically, like node_modules / dist / build.graphify can't parse Rust, so the parity gate proves parity structurally: the built-in backend must recover ≥90% of the symbols in the committed gold graph with a valid, dangling-free graph. On the reference fixture it recovers 100% (49/49 symbols, zero dangling edges). The independent correctness oracle is a hand-listed set of expected symbols, edges, and rationale in tests/test_graphgen.py; the parity gate then guards against regressions. This release executes Phase 1 of the language-extractor expansion PRD — Java, C/C++, and Ruby follow the same gated recipe, one language per PR.
NeuralMind's progressive-disclosure selector can now adjust its own L2 recall depth from how an agent actually uses it. This is phases 1–2 of the self-improvement engine (issue #156): a logging substrate that records query and wakeup events with a session_id, and an opt-in tuner that reads that signal back to widen or narrow how many community summaries L2 surfaces per query. The whole thing is off by default behind NEURALMIND_SELECTOR_AUTOTUNE=1, and with the flag unset behavior is byte-identical to v0.25 — zero extra I/O on the hot path.
The signal is the re-query rate: when an agent issues two consecutive same-session queries whose recalled communities heavily overlap, the first query under-disclosed and the agent had to come back. Persistent overlap means L2 is too narrow, so the tuner raises the recall depth one step (up to 6); a consistently low overlap means it can narrow (down to 2). The tuned value is persisted in the synapse store's meta table, so it carries across sessions per project. A transition-margin dampener (v0.11+) suppresses an otherwise-warranted raise when the agent's directional-transition graph already predicts the next hop decisively (top-1 probability ≥ 0.70) — if the agent already knows where it's going, widening L2 wouldn't reduce the re-query, it would just spend tokens.
SessionStart hook runs the tuner once per session (after the decay tick); under Cursor, Cline, and generic MCP clients the tuned value is threaded into the selector at build time, so ordinary queries get the adapted depth with no new tool to call.neuralmind self-improve status . (with --json) reports the current recall depth, when it was last tuned, event counts, warm-up state, the windowed re-query rate, and whether autotune is enabled. It never writes.The tuner only moves the cheapest, most reversible knob — the L2 community budget — and every guard keeps it from acting on thin or self-referential data: a 50-event warm-up gate, a hysteretic dead band so it doesn't oscillate, single-step moves clamped to [2, 6] (enforced both before persisting and on read), a window keyed to since the last tune so it doesn't chase a distribution it just perturbed, the transition-margin dampener, and fail-open everywhere — the tuner never raises and the SessionStart hook always returns 0. Phase 3 (eval-driven closed-loop tuning) is future work, surveyed in evals/self_improvement/PLAN.md.
NeuralMind now has a single learning signal. The old learned_patterns cooccurrence reranker is removed, and neuralmind learn becomes an exit-0 deprecation no-op. The Hebbian synapse layer — which already learns continuously from your queries, edits, and tool calls, and lets unused edges decay — is now the only thing that adapts retrieval to how you actually use the codebase. One system instead of two means automatic learning instead of a manual step, and decay instead of staleness. This is a removal, not a regression: warm-path recall is synapse-driven exactly as it was in v0.24.
A 2×2 on the benchmark fixture measured top-k hit rate with the reranker on vs. off, crossed with synapses on vs. off. The reranker moved the number by 0.0 points in both rows (71.7% → 71.7% cold, 83.3% → 83.3% warm), while the synapse layer alone moved it by +11.6 points. The reranker was also runtime-inert on the warm path — the synapse boost re-sort discarded its ordering anyway — required the manual neuralmind learn step to populate, and went stale between runs. The learning that matters is the synapse layer's, and that is the signal NeuralMind keeps.
(+X.XX boost) labels from the reranker. Synapse-recall labels are unchanged and still appear..neuralmind/learned_patterns.json is no longer read or written. An existing one is simply ignored and can be deleted.neuralmind learn prints a deprecation notice and exits 0, so any script or CI step that calls it keeps working. NeuralMind(enable_reranking=...) is accepted and ignored for backward compatibility.Two learning mechanisms that nominally do the same job is two places for behavior to drift, two things to document, and two things to keep honest. The A/B settled which one earns its keep. Automatic beats manual: the reranker only improved with a neuralmind learn step you had to remember to run, while the synapse layer learns as you work. And decay beats staleness: the reranker's JSON captured a snapshot that aged between runs, whereas the synapse layer continuously reinforces what's used and decays what isn't, so recall tracks current usage instead of a stale batch. To see what's been learned, use neuralmind stats or neuralmind memory inspect.
The learned synapse layer is now namespace-aware (PRD 4). Branch experiments, your personal long-term memory, an imported team baseline, and throwaway session scratch live in separate namespaces inside the same store — branch:<name>, personal, shared, ephemeral — so a weekend spike on a feature branch can't pollute what the agent learned about main. Reads stay smart by default: a transparent merged view prioritizes recent branch-local context while retaining long-term priors, with the weighting published as three constants. Existing learned memory migrates in place, losslessly — everything you've taught NeuralMind becomes the personal namespace, and on the default branch behavior is byte-identical to v0.23.
NEURALMIND_NAMESPACE env var → memory_namespace: pinned in neuralmind-backend.yaml → branch:<name> on a non-default git branch (best-effort stdlib git rev-parse, 3s timeout) → personal. Detached HEAD, missing git, or a non-repo all degrade safely — a weird git state never fails a memory write.namespace joins the primary keys of all three tables, so the store rebuilds each table inside a single IMMEDIATE transaction that rolls back wholesale on any failure. A mandatory stdlib-only test opens a real pre-namespace database and proves every edge, transition, and activation survives with identical weights under personal.neighbors, next_likely, edges, and transitions merge the active namespace at 1.0× (W_BRANCH), personal at 0.8× (W_PERSONAL), and shared at 0.5× (W_SHARED) — explicit module-level constants with the formula documented beside them. Explicit namespaces=[...] (or --namespace) reads one namespace at raw weights.neuralmind memory {inspect,reset,export,import}. Inspect contribution by namespace (also folded into stats); clear one namespace without touching the index or any other namespace; export a namespace as a portable, versioned JSON bundle reusing the IR's IRSynapse shape; import validates format + version and merges idempotently (weights merge by MAX). This is the PRD 8 team-memory on-ramp.shared is sticky (a team baseline shouldn't evaporate because one developer changed focus); personal / branch:* keep the existing rates with long-term potentiation intact; ephemeral fades fast with no LTP floor and is cleared outright at session boundaries (SessionStart hook, daemon shutdown).namespace_contribution map showing how much boost energy arrived through each namespace's edges — computed only on traced queries, so the untraced hot path pays nothing.A learned usage memory is only trustworthy if the wrong lessons can be contained and removed. Namespaces give branch experiments a place to live and die, give a team a clean channel to ship baseline knowledge to a new teammate (shared at 0.5× — informative, never louder than your own experience), and give throwaway exploration a memory that forgets itself. And because the migration is the riskiest part of touching a memory store, it's a single transaction with rollback-on-error and a no-data-loss test — the pattern future schema bumps follow.
Full v0.24.0 release notes → · Branch-isolated memory walkthrough →
Four future-proofing foundations land together. PRD 1: NeuralMind now builds a canonical, versioned intermediate representation (IR) of your code graph and validates it on every build — a new neuralmind validate command checks that contract and reports schema problems, decoupling retrieval/memory/UI/MCP from any one graph producer's field names. It's a Phase-1, hidden-adapter rollout: the embedder still reads graph.json exactly as before, so nothing about retrieval changes. PRD 2: a new neuralmind benchmark --quality mode proves retrieval finds the right code — precision@k / recall@k / MRR / answerability over golden suites — and fails CI on a regression. PRD 3: neuralmind query --trace shows why a result came back — per-layer candidates, cluster scoring with vector-vs-synapse attribution, synapse boosts, and final hits. PRD 5: an experimental neuralmind daemon holds project state warm so repeat queries skip cold backend init, with the CLI auto-preferring it and falling back to direct mode.
neuralmind/ir.py). Every build adapts the loaded graph.json into an IndexIR — canonical IRNode / IREdge / IRCluster / IRSynapse entities stamped with an ir_version, the source backend, the producer's schema version, language inference, and a per-build coverage signal (coarse for tree-sitter/graphify; a future SCIP/LSP backend reports precise). Written to .neuralmind/index_ir.json.neuralmind validate [path] [--write] [--json]. Validates the IR with no vector backend (no ChromaDB/turbovec needed). It reports errors (dangling/missing edge endpoints, duplicate ids, unsupported IR version) and warnings (orphaned nodes, unknown node kinds, unknown edge relations). --write (re)materializes the IR — the in-place migration path for a project that predates it, no rebuild required; --json emits a machine-readable summary for CI.from_graph_json / to_graph_json round-trip any graph.json back to a dict equal on every field the stack consumes; non-standard producer fields are preserved verbatim so upgrades don't silently drop information.build and stats. build prints an IR: v1 (valid) line; stats (and build_stats) carry an ir block with the contract version, counts, coverage, and last validation result. Public API: from neuralmind import IndexIR, from_graph_json, validate_ir, validate_project.neuralmind/quality.py) — PRD 2. Pure, stdlib-only precision@k / recall@k / MRR / answerability, with a regression-threshold gate and baseline-delta comparison.neuralmind benchmark --quality. Scores those metrics over golden query suites spanning three repos (Python / TypeScript / Go — 30 labelled queries), reports per-suite MRR / answerability / recall@k / precision@k, and exits non-zero on a regression. --suite scopes to one language; --baseline reports deltas vs a saved run; --json for dashboards. A contributor/CI self-test like neuralmind eval.neuralmind query --trace) — PRD 3. A per-layer trace of the retrieval path: vector candidate pool, cluster scoring with vector-vs-synapse attribution, individual synapse boosts, final ranked hits (flagging synapse-recalled ones), and the token budget. Pure/stdlib neuralmind/trace.py; bounded so it can ride along in a CLI/MCP payload, and redact-able to basenames for bug reports. Zero-overhead off by default; the daemon's /query honors it too.neuralmind daemon) — PRD 5, experimental. A per-user localhost service with a project registry (each project's index initialized once, reused warm), per-project locks + background build jobs (no index/synapse corruption), and a transport-agnostic dispatch() API the CLI client speaks. neuralmind query/stats auto-prefer it and fall back to direct mode (NEURALMIND_NO_DAEMON=1 to force direct); a stale discovery file is cleaned up so a crashed daemon never wedges the CLI.Retrieval no longer has to assume one producer's exact JSON shape — the IR is the single contract, and the graphify/tree-sitter reader is just the first adapter behind it. validate turns "why is retrieval weird?" debugging into a one-line schema check, surfacing dangling edges and orphaned nodes before they cost a query. And the quality harness closes the loop the token-reduction benchmark left open: it proves the context NeuralMind selects is relevant, not just cheap, so a ranking or synapse-recall change that quietly drops the right files fails CI instead of shipping. The embedder still consumes graph.json today; future phases dual-write, then make the IR the read path.
import neuralmind no longer requires ChromaDB, and the default backend is now auto. v0.21.0 made a complete ChromaDB-free retrieval path (the turbovec backend). v0.22.0 starts switching everyone onto it — safely: the package imports without ChromaDB, and auto prefers turbovec when its deps are installed, else falls back to chroma. Nothing breaks for a plain install, and the old ChromaDB index is never deleted.
import neuralmind is ChromaDB-free. GraphEmbedder is now exposed lazily via PEP 562 module-level __getattr__ (so from neuralmind import GraphEmbedder still works), and the chromadb telemetry patch moved next to the only import chromadb — so import neuralmind succeeds with ChromaDB entirely absent.auto. An unset config (or backend: auto) resolves to turbovec when its stack (turbovec + onnxruntime + tokenizers) is importable, else chroma. An explicit backend: in neuralmind-backend.yaml always wins, so pinning chroma (backend: graph) is a one-liner.auto lands on turbovec for a project that still has a legacy ChromaDB index and no turbovec index yet, the build path reindexes from graph.json and prints a one-line notice. The old ChromaDB index is left untouched as a fallback — nothing is deleted.neuralmind doctor shows the resolved backend. A new Backend check reports the configured value, what it resolves to, and whether the turbovec stack is installed.A plain pip install neuralmind (no [turbovec] extra) resolves auto → chroma, so existing installs and CI are unchanged; users who added the extra get the ChromaDB-free path by default, letting it bake before v0.23 makes it universal. The flip is deliberately soft — turbovec is still an optional extra and chromadb is still a core dependency. This release removes only the import-time requirement and makes turbovec the preferred default; folding the turbovec deps into core and dropping chromadb are the staged next steps (v0.23).
NeuralMind can now embed and search with zero ChromaDB. v0.20.0 moved vector search to TurboVec (Google Research's TurboQuant compressed index); v0.21.0 moves the last ChromaDB-only job — embedding — into a bundled module, so the opt-in turbovec backend is fully self-contained.
OnnxMiniLMEmbedder. A ChromaDB-free all-MiniLM-L6-v2 embedder on just onnxruntime + tokenizers + numpy, producing vectors byte-identical to ChromaDB's DefaultEmbeddingFunction (verified: cosine 1.0, max diff 0.0).turbovec backend is ChromaDB-free end to end. Vectors → TurboVec IdMapIndex (8–16× smaller); text + metadata → local SQLite; embeddings → the bundled embedder. Enable with backend: turbovec in neuralmind-backend.yaml.turbovec never constructs the Chroma stack.ChromaDB drags in a large dependency tree and the recurring CVE-2026-45829 advisory surface. This release is the foundation for retiring it entirely — making the package import ChromaDB-free, flipping the default to turbovec with a migration, and dropping the dependency are the staged next steps (v0.22–v0.23).
The static code graph is commoditizing; the learned synapse layer is the moat. v0.20.0 turns that moat into a number: neuralmind eval --onboarding measures whether an agent that inherits a committed team memory retrieves better on its first queries than a cold agent with none.
neuralmind eval --onboarding. A cold-vs-onboarded A/B over the gold queries, sharing one built index and differing only in synapse recall (off vs on over a committed team baseline). Scored by the same offline judge as the faithfulness eval; the headline is the top-k module hit-rate lift — the slice associative recall re-ranks within — with fact-recall and grounding reported as honest secondaries (at a fixed budget fact-recall is budget-traded and full-context grounding saturates).evals/onboarding/seed_history.json is a regenerable record of co-edit sessions replayed through the real reinforcement path — no binary synapses.db committed.AST-derived code graphs are table stakes now. NeuralMind's durable edge is usage memory — the synapse layer that learns what your team edits together. This release makes that edge measurable and regression-gated, formalising the self-benchmark's Phase-3 synapse A/B into a committed-baseline eval.
Distribution is half the moat. The static code graph is commoditizing; what NeuralMind has that a static graph can't copy is usage memory (the learned synapse layer) plus being the memory an agent actually reaches for. v0.19.0 makes the latter frictionless: one command registers NeuralMind's MCP server with every agent you have installed.
neuralmind install-mcp. Auto-detects installed MCP clients — Claude Code, Cursor, Cline, Claude Desktop — and merges a NeuralMind entry into each client's config. --all does every detected client; --client targets one; --print emits the snippet to paste by hand.{"mcpServers": {…}} shape (just in different files); the command preserves your other servers, re-running is a no-op, and a changed entry is updated in place. Pure standard library (neuralmind/mcp_install.py), 11 tests.{"command": "neuralmind-mcp"} — the MCP tools take a project_path per call, so there's nothing to bake in.AST-derived code graphs are becoming table stakes. NeuralMind's durable edge is usage memory + distribution. The self-benchmark already measures the learned uplift directly (Phase 3 — synapse-recall A/B: top-k hit rate 71.7% → 83.3%, +11.7 points with recall on, at a neutral token budget). v0.19.0 invests in the other half — making NeuralMind trivial to plug into every agent, so it sees more usage and learns more.
Stay fresh without rebuilding. Picking up a code change used to mean re-running neuralmind build — a whole-repo re-parse. v0.18.0 re-parses just the file you edited and re-embeds only its nodes, leaving everything else byte-for-byte untouched.
graphgen.update_files(). Splices a re-parse of the changed files back into an existing graph.json. Unchanged files keep their nodes, edges, and community numbers byte-for-byte — the latter is the trick, since renumbering communities would change every node's content hash and force a full re-embed. The edited file's outgoing edges are re-resolved; edges into a removed/renamed symbol are pruned (no dangling edges).NeuralMind.update_files(paths). Writes the graph, deletes embeddings for removed symbols, and re-embeds — which, thanks to content hashing, only touches the edited file's nodes. On the reference fixture, editing one file re-embeds 2 nodes and skips 135.neuralmind watch --reindex. Wires it to the watcher: every debounced batch of edits is re-indexed automatically, so a query right after a save already reflects the new code. Opt-in, since re-embedding needs the retrieval stack in the watch process.The built-in backend was already file-by-file and the embedder already content-hashed; v0.18.0 closes the loop so the parse is incremental too and it happens automatically as you work. The graph contract is unchanged — retrieval, synapses, the graph view, and MCP tools just see a fresher graph.
Compiler-accurate edges, where you have them. The built-in backend resolves calls/inherits edges heuristically — by name — which is wrong when two classes both define, say, handle(). If your repo has been indexed by a SCIP tool (scip-python, scip-typescript, scip-go), v0.17.0 can fold that compiler-accurate resolution in.
neuralmind/precision.py). With NEURALMIND_PRECISION=1 and a *.scip index present, neuralmind build replaces the heuristic calls/inherits edges for the files the index covers with SCIP-resolved ones. Off by default — a no-op otherwise.contains, imports_from, rationale, communities — is untouched, behind the same graph.json seam.run() → B.handle (wrong), SCIP links run() → A.handle (right) and drops the wrong edge, and the pass is a strict no-op when disabled.Tree-sitter gives breadth (66+ languages, no build); SCIP/LSP give compiler-grade precision per language. v0.17.0 is the proven hybrid: tree-sitter by default, exact edges where a SCIP index exists — both behind the same seam, so the retrieval stack is untouched. No runtime change unless you opt in.
The built-in backend is no longer Python-only. v0.16.0 takes the bundled tree-sitter backend multi-language: neuralmind build . now indexes Python, TypeScript, and Go out of the box, with no graphify install — and a mixed-language repo is indexed in one pass.
neuralmind/graphgen.py dispatches each file by suffix (_SUFFIX_LANG → _EXTRACTORS) to a language extractor. TypeScript (.ts/.tsx) and Go (.go) join Python, each mapping its grammar's node types onto the same code/rationale/document nodes and contains/imports_from/inherits/calls edges./** … */ JSDoc, and Go // … doc comments all become the same rationale layer; struct fields and module constants become queryable code symbols.tree-sitter-typescript and tree-sitter-go are now core dependencies, so the languages work with no extra install; a missing optional grammar is skipped per-file rather than failing the build.The seam — not the parser — is the durable asset. Adding a language is now registering a pair of functions, with the parity gate guaranteeing each new grammar holds up before it ships. The retrieval stack downstream of graph.json is untouched; it simply sees more of the world. No runtime change for existing Python or graphify installs.
The biggest barrier to trying NeuralMind on your own repo is gone. Until now you had to install a second, external tool (graphify) and run it before neuralmind build would do anything. v0.15.0 ships a built-in tree-sitter graph backend, so pip install neuralmind && neuralmind build . just works.
neuralmind/graphgen.py). A pure-Python parser that produces a graphify-compatible graph.json — symbol-level code nodes (incl. module constants & class fields), contains/imports_from/inherits/calls edges, a full-body rationale layer, document nodes from markdown, and balanced per-file communities. tree-sitter + tree-sitter-python are now bundled core deps.--force never clobbers a real graphify build, and an empty/non-code project still gets the honest "no graph" guidance instead of a silent 0-node "success."evals/parity/run.py) builds the reference fixture with both backends, runs the faithfulness eval and derives the self-benchmark reduction on each, and fails the build if the built-in backend drifts outside tolerance of graphify (within 25% reduction, within 10 points faithfulness). An early cut failed this gate — it retrieved worse than naive truncation — and the backend was improved until it cleared the bar on the merits. On the reference fixture the built-in now beats graphify on fact recall (0.717 vs 0.555), grounding (1.000 vs 0.917), and token reduction (6.66× vs 6.08×). It's the safety net every future backend change must clear.graph.json — embedder, context selector, communities, synapses, graph view, MCP tools — is unchanged. Only the graph producer changed, behind a generated_by / schema_version stamp. That's what lets multi-language extractors and an optional LSP/SCIP precision pass slot in next.Removing the external-tool dependency cuts the #1 onboarding drop-off and a single-maintainer bus-factor risk, and unblocks a cleaner fresh-install on more platforms. The static code graph is commoditizing across the industry; making the producer pluggable — and gating every swap on measured retrieval quality — is how NeuralMind keeps the part that's actually unique (the learned synapse layer) honest. No runtime change for existing graphify-based installs.
The measurement foundation became a command. neuralmind eval turns "does NeuralMind's memory make an agent's answers better, not just shorter?" into a reproducible number — and, like everything here, the default judge is 100% local.
neuralmind eval. Runs a with-NeuralMind vs naive A/B on the reference fixture and reports a faithfulness delta, grounding rate, contradiction rate, and a per-query breakdown. --json for machines; --selfcheck validates the gold set + offline scorer with no heavy deps. A contributor/CI quality gate — run it from a source checkout (the evals/ gold set isn't bundled in the pip wheel).NEURALMIND_EVAL_LLM_JUDGE and is never the default or the gate.NeuralMind has always led with a token-reduction number. v0.14.0 adds the harder, more honest one: quality. It's a self-test against the bundled reference fixture today (like neuralmind benchmark), and the fitness function the rest of the roadmap — graph-backend decoupling, team memory — is validated against. No runtime change to your install.
A foundation release: the scaffolding to prove the memory helps, not just claim it. v0.13.0 doesn't change what your install does at runtime — it builds the machinery to measure whether NeuralMind makes an agent's answers better (faithfulness), and to measure retrieval quality beyond Python. Plus a documentation process so the docs stop drifting.
NEURALMIND_EVAL_LLM_JUDGE mode is clearly labelled as leaving the machine and is never the default or the gate.DOCUMENTATION-PROCESS.md, a PR-template checklist, and a CONTRIBUTING link, so every user-facing change ships its docs in the same PR and the landing-page version stops going stale.NeuralMind's headline claims — cheaper, and the memory makes answers better — deserve to be measured, not asserted. v0.13.0 is the first brick: an honest, offline, reproducible way to score answer faithfulness, and fixtures that extend quality coverage past Python. Nothing here is a runtime feature; all of it is the fitness function the rest of the eval-first roadmap builds on. No migration, no new dependencies, no behavior change for existing installs.
One command tells you exactly what's wired up and what isn't. NeuralMind has accumulated moving parts — a code graph, a semantic index, a synapse memory db, Claude Code hooks, an MCP server, a query-memory consent flag. When one isn't in place, the old symptom was a stack trace or a silent no-op. v0.12.0 makes the setup legible.
neuralmind doctor. Inspects the install and reports each piece with a status (ok / warn / fail) and the exact command to fix it. Read-only — it never builds or mutates state. Exits non-zero when a check fails (graph/index missing) so you can gate a CI step or an agent's provisioning on it.--json output. A stable, machine-readable snapshot of every check, for scripting and agent consumption. An agent provisioning its own environment can run neuralmind doctor --json as a pre-flight check before issuing queries.AttributeError. It now raises a clear, actionable message naming the two commands to run (graphify update, then neuralmind build) and points you at neuralmind doctor.Most NeuralMind support friction is setup friction: a piece isn't installed, and the failure doesn't say which one. doctor turns "it doesn't work" into a checklist with fixes — for the human dropped into a fresh clone, and for the agent that has to verify its own environment before relying on the tool. No new dependencies, no behavior change for working installs.
The brain-like layer now learns what comes next, not just what goes together. The Hebbian co-activation signal that's powered NeuralMind since v0.4.0 has always been symmetric: nodes that fire together wire together, no ordering. v0.11.0 adds a parallel directional signal — after touching file A, you typically touch file B with probability p.
synapse_transitions(from_node, to_node, weight, count) table tracks ordered observations. Same Hebbian + decay machinery as the undirected synapses, but with directionality preserved. The file watcher records transitions automatically every time it flushes a batch — sorted by edit timestamp so re-touched files appear at their latest position, not their first.next_likely(node) API. Returns the probability distribution over what typically follows a given file or node. Probabilities normalize to 1.0 across all outgoing transitions. Callable from Python (mind.synapses.next_likely(path)), the CLI (neuralmind next . path/to/file.py), or via the new neuralmind_next_likely MCP tool from Cursor / Cline / Continue / any MCP client.TRANSITION_DECAY_RATE = 0.01 vs DECAY_RATE = 0.02 for the undirected edges) because sequential signals are rarer per session — you might edit ten files together but only get nine ordered pairs between them, so they need to accumulate for longer before being trusted.The existing undirected synapse graph answers association: "given this file, what other files belong to the same thought?" Directional transitions split that signal into before (prefetch this file's skeleton when the implementation file is loaded) and after (remind the agent to update this when the implementation changes). Same source data — every activate_files call writes to both the undirected and directional tables — two views.
No migration. The new table is created on first connection. Existing co-activation edges in synapses.db are untouched. Disable by ignoring the new API — the watcher still records transitions in the background, but if nothing reads them, they just sit there decaying like any other edge.
Three friction-removing changes to the PostToolUse Bash compressor — the surface AI coding agents see on every shell call. Built from real session feedback where the previous footer forced a second query round-trip just to recover dropped middle content.
[Full output: 4298 bytes...] message with a categorized breakdown: dropped 23 lines (12 info, 8 debug, 3 other); repeated: 5× 'Gamma API error 503'. Agents can judge whether the dropped middle was log noise or a buried error without re-running the command.neuralmind last — new CLI that prints the raw pre-compression output. The PostToolUse hook stashes every Bash result to <project>/.neuralmind/last_output.json (single-slot, 2 MB cap, atomic temp-file + rename writes). Turns NEURALMIND_BYPASS=1 from a re-run-from-scratch escape hatch into a free lookup — meaningful on npm test (~28s) and non-deterministic network calls.NEURALMIND_BASH_SMALL (default 500 chars) pass through verbatim with just exit-code framing, even on non-zero exit.The PostToolUse compressor is the most-visible surface NeuralMind exposes — the agent sees it on every Bash call. v0.10.0 converts the common "I need to see the dropped middle" friction from a re-run loop into a single cache lookup, and turns the footer text itself into actionable messaging: concrete benefit visible, concrete affordance, clear escape hatch.
No migration. Same graph.json, same synapses.db, same hooks. The new cache file is additive; disable via NEURALMIND_OUTPUT_CACHE=0.
Phase 3 of the release arc. Turn the v0.6.0 → v0.7.0 → v0.8.0 foundation into something a CTO, security team, or regulated-industry operator can actually adopt.
ghcr.io/dfrostar/neuralmind:vX.Y.Z and :latest, multi-platform (linux/amd64 + linux/arm64), non-root runtime, transitive deps pre-wheeled. :latest only moves for stable tags — pre-release tags like v1.0.0-rc1 are excluded from the floating tag.neuralmind-vX.Y.Z.sbom.json — ingestible by Grype, Trivy, Dependency-Track, and most enterprise SCA scanners.No production code changes — pure CI + docs. No migration. Same graph.json, same synapses.db, same hooks.
neuralmind watch and neuralmind serve are first-class production processes now. The synapse store accumulates 24/7 whether you're at the keyboard or not, and the graph view is always listening on 127.0.0.1:8765.
scripts/systemd/neuralmind-{watch,serve}.service (user-scope units, hardened), scripts/launchd/com.neuralmind.{watch,serve}.plist (macOS user agents with RunAtLoad + KeepAlive), Windows Task Scheduler section in the Scheduling Guide./healthz endpoint on neuralmind serve — unauthenticated, returns {"status":"ok","version":"..."}. Designed for Docker HEALTHCHECK and systemd ExecStartPost probes so a fresh container can be checked without threading a session token.HEALTHCHECK) with install + verify + uninstall + troubleshooting.The canvas still requires the per-session auth token by default; pass --no-auth in the templates or read the tokenized URL from the service logs.
Distribution release, not a features release. The brain is the same brain. What changed is how many ways you can install it.
pip install neuralmind graphifyy — the default. Works in any venv.pipx install neuralmind — global CLI, isolated env. neuralmind on PATH everywhere without activation.uv pip install neuralmind graphifyy — ~10× faster than pip, same wheel.docker build -t neuralmind:dev . — multi-stage Dockerfile in the repo root, non-root runtime, transitive deps pre-wheeled in the builder. GHCR auto-publish lands in a later release; build locally for now.All five paths deliver the same package: the neuralmind CLI, the neuralmind-mcp server (for Claude Code, Cursor, Cline, Continue, and any MCP client), and the live graph view from v0.6.0. Smoke test is identical: neuralmind --help works everywhere; python -c "import neuralmind" works for pip / uv / source paths.
graph-view, hebbian-learning, force-directed-graph, …) so PyPI search ranking finally matches what we ship.logrotate/copytruncate is fixed./api/queries test coverage (#116) — the replay-last-query route is now in the automated regression suite.No migration. Same graph.json, same synapses.db, same hooks. Upgrade is whatever your install path's --upgrade equivalent is.
The pitch flipped. v0.5.4 made the brain inspectable. v0.6.0 makes it legible. neuralmind serve now streams a live activity feed: synapse + file events pulse across the canvas in real time as the agent and the codebase interact. The graph stops being a static map and becomes a window into the hippocampus learning your codebase.
/api/events SSE stream subscribed to the in-process event bus. Affected nodes pulse on the canvas; sidebar log shows the most recent ~80 events.neuralmind watch daemon, or a hook-driven Claude Code session in another process, feeds the same live feed via <project>/.neuralmind/events.jsonl. The in-process bus stays the primary path; the JSONL is a deliberately boring side channel. Opt out with NEURALMIND_EVENT_LOG=0.Cmd/Ctrl-K and / jump-to-search from anywhere; Esc clears and blurs.The cross-process JSONL bridge means that if you run Claude Code, Cursor, OpenClaw, and Hermes-Agent against the same project — they reinforce the same synapse store, and the v0.6.0 graph view shows the union of their activity. Pre-v0.6.0, the synapse store was shared but the experience wasn't — three tools talking to a black box. Now the brain is visibly one brain. See the multi-agent walkthrough.
No migration: same graph.json, same synapses.db, same hooks. Upgrade is pip install --upgrade neuralmind. Then neuralmind serve and save a file — that's the demo and the verification in one motion.
NeuralMind exists to solve a fundamental problem: AI agents waste tokens loading raw source code when they only need small, semantic context.
Our mission is to make semantic code intelligence accessible, affordable, and trustworthy—without data exfiltration, vendor lock-in, or compliance headaches.
Phase 1 — Smart Retrieval: Instead of loading entire files, NeuralMind uses a 4-layer semantic index to surface only the ~800 tokens of code your question actually needs.
Phase 2 — Output Compression: PostToolUse hooks compress Read, Bash, and Grep output 88–91% smaller before agents see it.
Phase 3 — Brain-like Memory (v0.4.0): A second brain runs alongside the LLM — a persistent weighted graph that learns associations between code nodes from how the agent and the codebase actually interact. Stronger connections form between code that gets used together, weaker ones decay, and the agent's prompts trigger spreading-activation recall over the learned graph.
Phase 4 — Graph View (v0.5.4, made live in v0.6.0): neuralmind serve renders the whole system as an Obsidian-style force-directed graph in the browser. Structural edges, the learned synapse overlay, backlinks, a semantic quick-switcher, and one-click open-in-editor. v0.6.0 adds a live activity feed — synapse and file events pulse on the canvas in real time, with a cross-process JSONL bridge that lets Claude Code, Cursor, OpenClaw, and Hermes-Agent all feed the same canvas. The brain stops being a black box — you can finally watch what it's learning, live.
Result: 40–70× per-query token reduction (50K+ tokens of raw source compressed into ~800 tokens of structured context) and 40–70% bill drops on real codebases. Retrieval that gets sharper the longer the system runs on a codebase.
NeuralMind doesn't load code randomly. It uses a 4-layer index that progressively surfaces context:
The agent gets exactly what it needs, in order, without bloat.
NeuralMind learns from how you actually use the codebase. Over time, the brain-like synapse layer (described below) improves retrieval quality based on which code you query, edit, and run tools over together — automatically and continuously, with no external training and no manual step.
The newest layer is an associative memory inspired by how brains actually learn. NeuralMind tracks weighted "synapses" between code nodes, and applies three classic neuroscience principles:
The synapse store is local SQLite, project-scoped, and inspectable. It exports a markdown summary that Claude Code's auto-memory system loads natively, so the learned associations show up in every session — no MCP tool call required.
neuralmind serve (v0.5.4, made live in v0.6.0)The agent-facing brain is now also a human-facing tool. A stdlib HTTP server renders a force-directed graph of the entire codebase in the browser — structural edges (calls and imports) drawn together with the learned synapse overlay, where edge thickness encodes weight. Each node has Obsidian-style backlinks and outgoing-links panels, a "synaptic neighbours" list with weights and activation counts, and a one-click "open in editor" button (smart support for VS Code, Cursor, vim, sublime, JetBrains). A semantic quick-switcher lets you type a phrase and jump straight to the matching node. Zero CDN dependencies; per-session access token bound to 127.0.0.1.
v0.6.0 adds a live activity feed. The server now exposes a long-lived /api/events SSE stream subscribed to an in-process event bus. Every SynapseStore.reinforce() call and every coalesced file-edit batch publishes an event; affected nodes pulse on the canvas with short animated radial rings, and a sidebar log shows the most recent ~80 events. A cross-process JSONL bridge (<project>/.neuralmind/events.jsonl) lets a separate neuralmind watch daemon, a Claude Code session, an OpenClaw call, or any other process feed the same canvas. One canvas, every agent. Opt out with NEURALMIND_EVENT_LOG=0.
Why it matters: pre-v0.6.0 the graph view was inspectable but static — you had to refresh to see new state. With the live feed, you can sit there in real time and watch the hippocampus learn your codebase. "The agent has a learning memory" stops being a claim and becomes a visual.
Every query is logged with full provenance: which code was retrieved, why, which embeddings were used, code state (git commit). Export for NIST AI RMF, SOC 2, GDPR, HIPAA.
NeuralMind is MIT licensed and fully open source. No hidden business model, no vendor lock-in, no surprise rate limits.
The latest release leans into the distribution moat: neuralmind install-mcp --all auto-detects your installed agents (Claude Code, Cursor, Cline, Claude Desktop) and registers NeuralMind's MCP server with each — a non-destructive, idempotent merge. The learned synapse layer's uplift is already measured by the self-benchmark's Phase-3 A/B (top-k hit rate 71.7% → 83.3% with recall on). See the v0.19.0 release notes or the summary above.
This is an independent, open-source project. No relationship to NeuralMind.ai (a different company). We chose the name because it reflects our philosophy: a "neural" index that learns your codebase.
Your code stays local. Zero cloud calls, zero telemetry, zero data exfiltration.
Open source, MIT licensed. Every decision is auditable, every result is explainable.
Built for regulated industries. NIST AI RMF, SOC 2, GDPR, HIPAA friendly.
Works with your tools. Claude Code, Cursor, ChatGPT, local LLMs—not locked in.
Smart context reduces per-query tokens 40–70×. Lower costs, better answers.
Built in public. Issues, discussions, and contributions welcome.
Ready to reduce your per-query token costs by 40–70×?