NeuralMind

Persistent codebase memory for AI coding agents — Claude Code, Codex, Cursor, Cline, Continue, and any MCP client.

Your agent gets a memory of your codebase — what goes together, what you usually touch next — that carries across sessions. Local-first, no telemetry by default. On a public benchmark that publishes every miss, NeuralMind finds the gold file on 40 of 40 queries, where keyword ripgrep (top five files opened whole) finds 32 of 40 — at 31–67× fewer tokens than ripgrep, and 51–242× fewer than pasting every source file. On a larger 150-question eval it puts the gold file in the top five for 93.3% of questions; its 10 misses are published too.

After install, your agent:

• Boots with SYNAPSE_MEMORY.md (learned associations, strongest hub files)
• Recalls related files for each prompt you send (Claude Code UserPromptSubmit hook; on Hermes-Agent, the plugin's pre_llm_call hook, v4.9.0+): from the first prompt on a fresh index, the files and symbols the prompt matches, with line numbers, and code the synapse graph links to them; and adds nothing when the prompt's best match in the code scores below a cutoff, which most replies like "yes" and off-topic questions do (v4.11.0+); and when one file clearly leads the matches, that file's best match as code, secrets redacted (v4.21.0+); test files after the code they test unless the prompt names a test (v4.23.0+)
• Gets its own first prompt, latest prompts and edited files back after Claude Code compacts the session, prompts as written up to 200 characters (v4.11.0+)
• Gets a few hundred tokens of ranked context per code question instead of whole files: 670–961 tokens a question on the public benchmark, where pasting every source file costs 41,729–232,483 (v4.12.0)
• Is told when the index is behind: one line on its query, search and prompt context when commits since the last build changed the project, the background rebuild failed, or the index is in the legacy layout (v4.17.0+)
• Gets health checks, synapse pruning, audit queries, and code/doc type filtering (v3.1.4+)
• Gets a pre-commit warning when a change skips a pattern its own peers share — the eleventh handler that forgot the auth check the other ten have (v3.2.0+)
• Gets compliance annotations it can actually trust — a version string or an SVG path is no longer reported as a SOC 2 control (v3.3.0+)
• Searches your prose too: ingest-content indexes a book or docs tree into its own project, re-embeds only what changed, and shows a progress bar with an ETA while it works (v3.4.0+)
• Six synaptic learning rules adapted from published memory research (STC, SAMPL, resource STDP, FOK, lateral inhibition, replay) plus intent-aware ranking that reads "how does X implement Y" as a question about code, and ranks implementation above docstrings for it (v3.9.0+; since v4.12.0 an intent detected from the wording no longer re-weights hits, only a type you ask for does, and NEURALMIND_AUTO_INTENT_BOOST=1 restores the old behaviour)
• New in v4.23.1: a Hermes session's first turn gets its recap on a large repository. The plugin runs neuralmind _hook session-start for the previous session's recap and stops it after 8 s, and on a 1.27M-edge synapse store the hook's decay tick and SYNAPSE_MEMORY.md export took 6.3–7.7 s on one loaded Linux machine, so the recap it had already written was dropped (NEURALMIND_SYNAPSE_EXPORT=0 was the workaround). From a 64 MB synapses.db up, that work now runs in a detached process after the hook returns, with the same result: the hook took 0.20 s against 4.34 s on such a store on an M3, and 0.33 s against 7.00 s under CPU load, where v4.23.0 overran 8 s once in 5 (tests/benchmark/session_start_latency.py, release notes)
• Also in v4.23.1: the Hermes plugin serves each session's own project on Hermes 0.22.2 and later. Every CLI, TUI and Desktop session's hooks run in one Hermes gateway process there, and the plugin read the gateway's own TERMINAL_CWD and working directory, so unpinned it served nothing: on Hermes 0.22.5 a hermes chat turn in a built checkout started no NeuralMind hook, and NEURALMIND_PROJECT set on the hermes command never left the client. It now asks Hermes for the session's working directory (ctx.session_cwd()), and, checked live with a local model, the block reached it after a plugin reload. Re-run neuralmind install-hermes-plugin after upgrading, then reload a running gateway with hermes plugins disable neuralmind && hermes plugins enable neuralmind (release notes)
• v4.23.0: the per-prompt block lists the code before its tests when the prompt only says how to run them. Any test word ("run the existing tests with pytest") ranked test files with the code, so on NousResearch/hermes-agent 18 of the 32 files the block listed over 5 bug fixes were tests, and 2 of its 3 code excerpts quoted one. Test files now come after the code unless the prompt names a test (test_parse, tests/test_parser.py), a prompt that mentions tests keeps one slot for its best test file, and the excerpt is from a source file whenever one is listed. Replayed offline on those 5 tasks, the ones that motivated it, tests fell to 6 of 35 files listed and no excerpt quotes one; the fixed file is still named on 2 of 5. On the pilot's 20 tasks the block still names it on 17 (release notes)
• Also in v4.23.0: a test file that matches the prompt brings the code it tests into the list, found by name (tests/agent/test_x.py → agent/x.py), so that file is listed even when only its test matched. The change was also replayed offline on 12 held-out hermes-agent bug fixes, the new tasks the screen's 5 couldn't stand in for; no agent ran (held-out record)
• Also in v4.23.0: the per-prompt hook answers within the Hermes plugin's 8 s timeout on a large index. Each hook is a new process that reloaded the whole graph; on hermes-agent that took 9–15 s a call on one Linux machine, so the block arrived only with NEURALMIND_HERMES_TIMEOUT=30. The loaded graph is now kept in .neuralmind/graph_cache.marshal (written by build, or in the background the first time a hook finds it missing; NEURALMIND_GRAPH_CACHE=0 turns it off), and the hook skips the structural index recall doesn't read: 1.3 s a call against 6.5 s on hermes-agent's index on an M3, the same block byte for byte (tests/benchmark/hook_latency.py, release notes)
• v4.22.0: neuralmind doctor says whether anything calls NeuralMind. A Wiring section, before the other checks, reports the daemon, the Git hooks (a hook git can't run doesn't count), the Hermes plugin (enabled, pinned, or older than the installed NeuralMind) and the MCP entry in each client, each warning with the command that fixes it; with no agent host wired it ends with Installed but not wired, not Up and running, and the exit code is unchanged. neuralmind install-mcp --client hermes (or install-hermes-plugin --mcp) adds the MCP server to Hermes's config.yaml, keeping its comments. A build ends with the commands for whatever isn't wired yet, in at most three lines (release notes)
• Also in v4.22.0: a feature branch's calls and memory stay on the branch. Every build seeds the call and import edges it finds, and they went into the shared baseline every branch reads, so a call added on a feature branch was still recalled on main until it decayed (60-day half-life). They now go into a structural namespace each build replaces with the checked-out code's graph, read at the same 0.5 weight, never decayed and left out of the team bundle. And SYNAPSE_MEMORY.md, the memory file Claude Code loads at session start, listed associations learned on every branch; it now holds only what recall reads on the checkout (release notes)
• v4.21.0: your agent can see what NeuralMind is for. Claude Code hides MCP tools behind tool search, so in the task-outcome pilot the agent saw 28 bare tool names and called none in 60 runs, and NeuralMind made no difference to its cost per task (+0.0%, 95% CI −5.2% to +8.6%). Now the MCP server sends instructions saying when to call neuralmind_search (before Grep, to find the code behind a symptom) and the other core tools, and tools/list offers six tools instead of 28 (NEURALMIND_MCP_TOOLS=all restores the full list; every tool still answers by name). And when one file clearly leads a prompt's matches, the per-prompt block quotes that file's best match as code, secrets redacted (NEURALMIND_RECALL_EXCERPT=0 to turn it off). A new CI gate replays the hook on the pilot's 20 tasks with no agent: the block names a file the fix changed in 17, first in 10; its code is from a changed file in 7 of the 9 tasks where it's shown, and covers the changed lines in 2. Measured after, on the same 20 tasks: it didn't change what the agent did. The agent still called no NeuralMind tool in 60 runs and searched as much before its first edit (median 4.0 calls, as without NeuralMind); cost per task −2.1% (95% CI −6.9% to +6.5%), no difference shown (exploratory rerun, release notes)
• Also in v4.21.0: the default backend works again on Intel macOS and Windows ARM. turbovec has no wheel there, so pip install neuralmind installs ChromaDB instead, and from v0.46.0 the default backend ignored it: every build failed with No module named 'turbovec' unless you set backend: graph. The default now falls back to ChromaDB where turbovec isn't installed (no change where it is), neuralmind demo builds its sample with the model there instead of failing, a missing backend says what to install, and neuralmind doctor no longer calls a project with no config file "pinned". Installing on Intel macOS compiles cryptography, which has no wheel there, so it needs a Rust toolchain; on Windows ARM a native install fails to build cryptography, chromadb and grpcio, so use WSL 2 or the container image (what it needs)
• Also in v4.21.0: an idle learned association's decay rate relaxes back to the 30-day default, as designed. The blend was computed only at reinforcement, where it changes nothing, so an association used three times a month apart kept its short learned half-life and was pruned after two idle months; it is now kept after two and pruned within five, and a heavily used one slides toward the default instead of keeping its long half-life (release notes)
• v4.20.0: no change to what your agent does. The site is rebuilt around its evidence: neuralmind.uk/benchmark is the one proof page, with every number the site quotes rendered from site/claims.json and the committed runs (the build fails if one drifts), where NeuralMind loses, and the task-outcome pilot that found no cost difference; neuralmind.uk/security opens with verifying a release (cosign, gh attestation verify, SBOM, VEX, SSDF), now also a walkthrough: Verify a NeuralMind release before installing it (release notes)
• v4.19.0: the audit log reaches your SIEM as it is written. Set security.audit_syslog: /dev/log (or udp:// / tcp://) and every audit record goes to syslog right after it is written, from the CLI, the MCP server, the hooks and the daemon, with its hash so the SIEM can check the chain. Records a dead target missed are sent when it is back (neuralmind audit forward sends them on demand), and a record that can't be written raises an alert-severity syslog message at once (CMMC AU.L2-3.3.4, 3.3.5). Under security.profile: cui the target must be on this machine, since NeuralMind doesn't encrypt the connection; the host's syslog daemon forwards over TLS. neuralmind doctor gets an Audit forwarding line. Also new: an OSCAL component definition of the 21 SP 800-53 Rev. 5 controls NeuralMind touches, with what stays yours (readable version), for an agency's System Security Plan, and an SP 800-53 hardening guide: 17 rules, each mapped to its controls, that neuralmind hardening checks on a project and its host, exiting 1 when any fails. And pip install neuralmind && neuralmind demo now runs offline: the sample project's index and its questions' embeddings ship in the package, so the demo downloads nothing (release notes)
• v4.18.1: no change to what your agent does. Every Python file in the package names its license in an SPDX tag (MIT, or LicenseRef-NeuralMind-Commercial under neuralmind/tier2/), so a dependency scanner reading the installed files can tell which license each is under (release notes)
• v4.18.0: neuralmind data-locations lists every place a project's data lives, in the project, under the home directory and in the integrations that write it, so a deletion can be checked before and after. A failed audit write is noted and reported by doctor (Audit log writes) instead of vanishing, and neuralmind audit record-gap records the gap in the hash-chained log. Under security.require_encrypted_storage, Claude Code's synapse export and the global query log are written only to a verified volume, and NEURALMIND_SYNAPSE_EXPORT=0 now stops the MCP export tool too (release notes)
• v4.17.2: a machine policy whose require_encrypted_storage is neither true nor false (flase, blank) holds every project to the strictest settings, as v4.17.1 said any invalid value did. It used to switch the encryption check on and leave the CUI profile and OS identity off (release notes)
• v4.17.1: three security fixes from an audit of the compliance claims. An administrator's machine policy (/etc/neuralmind/policy.yaml) keeps security.profile: cui on when a developer deletes the project's neuralmind-backend.yaml, which used to switch every CUI control off; it only tightens and can't grant roles. Under identity: os, a reader can no longer build through the daemon or neuralmind build, which MCP already refused. And processes writing the audit log at once keep its hash chain valid, where audit verify used to report an untouched log as tampered (release notes)
• v4.17.0: an answer from a stale index says so. query, search, the MCP query, search and wakeup tools, and the related-files block each prompt gets (Claude Code and Hermes) carry one line when commits since the last build changed the project, when the git hook's background rebuild failed, or when the index is only in the legacy graphify-out/ layout that nothing reads. MCP payloads gain a freshness field, and neuralmind doctor a Query freshness line. Before, query, search and the prompt block said nothing, so the agent took old context for current. Re-run neuralmind init-hook . so the hook records a failed rebuild (release notes)
• Also in v4.17.0: an edit to a package's __init__.py reaches the graph. Incremental builds never saw __init__.py files, so code added to one stayed invisible to search, and one whose nodes had gone missing (doctor: "files on disk not in graph") stayed missing through build --force --regenerate-graph. The next build restores them (release notes)
• v4.16.0: security.profile: cui switches on the CUI-enclave posture as one setting: OS-account identity, a refusal to run on an unencrypted disk, serve refused beyond loopback or without its token (a daemon started that way refuses the project), and LLM documentation seeding refused even when switched on. Each refusal lands in the audit log, a contradictory or misspelled profile fails closed, and neuralmind doctor checks it as a unit, failing when the OS FIPS mode is off (release notes, CUI enclave walkthrough)
• Also in v4.16.0: an audit log whose newest records can't be removed unnoticed. neuralmind audit checkpoint signs the log's record count and last hash with an ECDSA P-256 key the developer can't read, pinned in neuralmind-backend.yaml, and anchors a copy where only the administrator can write. neuralmind audit verify then fails when records a checkpoint covers were removed from the end, when the chain was recomputed, or when a checkpoint is forged or missing (CMMC AU.L2-3.3.8; release notes)
• Also in v4.16.0: neuralmind team … and neuralmind onboarding exit 1 when they fail, so a provisioning script under set -e stops on a refused license: team license activate on an expired or altered file, a seat limit, a non-admin, a broken audit chain, a declined license agreement. They printed the failure and exited 0 before; team seats sync now exits 2 when the seat limit refused some of a manifest's seats (release notes)
• Also in v4.16.0: a reversed decision stops reaching your agent. The Decision: git trailers each prompt gets (Claude Code and Hermes) couldn't be retracted, since a commit message can't change; now neuralmind decisions scan (the post-commit hook; re-run neuralmind init-hook . to update it) imports them into the decision store, decisions invalidate <id> takes one out of every later prompt and neuralmind why in your clone, and a lat