llms.txt@docs git:20261021.61916d3A

Immutable. This exact content never changes and is served at /api/v1/blob/73f4862a1c3e0779.

# NeuralMind

> Persistent, local-first codebase memory for AI coding agents. NeuralMind indexes a repository into a code graph, learns which files go together from how you actually work (a Hebbian synapse layer), and serves compact, ranked context to Claude Code, Codex, Cursor, Cline, Continue and any MCP client — so the agent starts each session already knowing where things are. On a reproducible public benchmark it finds the gold file on 40 of 40 queries, against 32 of 40 for keyword ripgrep (query keywords, top five matching files opened whole), at 31–67× fewer tokens than that ripgrep baseline, and 51–242× fewer than pasting every source file; on a larger 150-question eval it puts a gold file in the top five for 93.3% of questions and misses 10, published. MIT core, every feature free at 1 seat, `pip install neuralmind`.

Key facts, each backed by a runnable eval with its data committed:

- Cheaper context: the gold file on 40 of 40 pre-registered queries, against 32 of 40 for keyword ripgrep opening its top five files whole, at 31–67× fewer tokens than that ripgrep baseline (an agent that reads only the matching lines pays less than this baseline; that is not measured), and 51–242× fewer tokens than pasting every source file; on recall NeuralMind beats ripgrep on 3 of 4 repos and ties exactly on the fourth (public benchmark on `requests`, `click`, `flask`, `rich`; measured at v4.12.0). Forty queries is a small sample: the 150-question retrieval eval puts the gold file in the top five for 93.3% of questions and misses 10, published. Caveat: the plain vector baseline — the top 8 entries of NeuralMind's own index, a symbol's name, module and docstring, not code — is cheaper on every repo and still ranks the gold file higher on `flask` and `rich` (MRR 0.74 vs 0.72, 0.94 vs 0.83), though its recall is at or below NeuralMind's — see "Where NeuralMind loses" in docs/benchmarks/public.md.
- Task outcomes: a pre-registered 20-task pilot (Claude Code with and without NeuralMind, 120 runs) found no cost difference — 18 of 20 bug-fix tasks solved in both arms, median per-task cost change +0.0% (95% CI −5.2% to +8.6%) — and in the 60 runs with NeuralMind the agent never called its MCP tools. A pilot, not a product claim; report: https://github.com/dfrostar/neuralmind/blob/main/bench/task_outcome/pilot/report.txt
- `neuralmind benchmark .` measures the reduction on your own repo: the token count of the code the index covers (prose excluded, at the same ~4 chars/token as the context) over the tokens each question costs, so it scales with the repo — 78.6× on psf/requests v2.32.3 at v4.5.0. Before v4.5.0 it divided a fixed 50K-token estimate instead; the 12–50× reported on private repos then (field reports — directional, not a promise) is on that scale, and `--naive-50k` reproduces it.
- Finds the right code: on the 150-question retrieval eval over five public repositories, a gold file in the top five for 93.3% of questions (MRR 0.750, ~830 context tokens per question) at v4.12.0; 10 questions are still missed, published (bench/retrieval/on-v4.12/report.md). A separate, off-by-default head-to-head against codebase-memory-mcp (MRR 0.96 vs 0.23 on `requests`, 0.60 vs 0.50 on `click`; pure retrieval ranking) was run in June 2026 (v0.33.0), on `requests` and `click` only, and has not been re-run since.
- Learns how you work: a Hebbian synapse layer learns which files you use together and re-ranks recall with those links, budget-neutral. CI gates the direction only — recall never lowers top-k hit rate at a neutral token budget, on a ~500-line reference fixture; earlier releases measured +3.5 to +14 points there, and at v4.12.0 recall adds nothing (+0) because the fixture reaches 97% without it. Its benefit on a real repo is not shown; `neuralmind eval . --synapse-ab` (v4.14.0+) measures it on yours. Reproduce the fixture A/B with `python -m tests.benchmark.run`.
- Answer grounding vs. naive truncation at a matched token budget, on the prose-heavy reference fixture: delta +0.265 at v4.12.0 (0.839 vs 0.574, measured with CI's command on one machine; v4.11.1 +0.027 there), after a published loss of -0.054 at v4.3.4; CI fails below -0.10.
- Team memory: `neuralmind memory publish` writes learned weights (no source code) to a file you commit; teammates' agents import it on their next session, with each association quality-scored and borderline ones held in a review queue. Once an admin sets up governance, publish enforces the publishing scope and weight threshold, `neuralmind team governance remove-edge` retracts an association for every teammate through the committed file, and publishes, imports, reviews and admin changes land in a hash-chained audit log.
- Decision memory: architecture decisions with rationale and affected files go STALE when a commit changes one of those files after the decision was recorded, and since v4.16.0 when a pull, merge or rebase does (git hooks from `neuralmind init-hook`, which since v4.13.0 also rebuild the index after merges, branch switches and rebases, not only commits), and a PreToolUse hook warns Claude Code before it edits a file governed by a stale decision.
- Read dedup (Claude Code): a repeat read of an unchanged file in the same session is replaced with a short stub; the next read is always full. Not benchmarked yet.
- Local-first: by default the engine transmits no repository content and sends no telemetry; its one default outbound request is a public embedding-model download on first build, pre-seedable via NEURALMIND_ONNX_MODEL_DIR (an opt-in, off-by-default feature sends README/architecture prose to Anthropic; the agent still sends its selected slice to its own model); ChromaDB-free default install on Linux, Apple Silicon (macOS arm64), and Windows x64 (ChromaDB is the automatic fallback on other platforms); NIST AI RMF mapped.
- Indexes ten languages out of the box via bundled tree-sitter (Python, TypeScript, Go, Rust, Java, C, C++, C#, Ruby, PHP), plus JavaScript (`.js` `.mjs` `.cjs` `.jsx`, parsed with the TypeScript grammars since v4.12.0), plus OpenAPI, SQL DDL, and Protocol Buffers schema artifacts.
- Pricing: MIT core plus source-available Team modules; every feature runs free at 1 seat with no signup and no expiry. NeuralMind Team is $29/user/mo (5–50 seats, annual) for more seats and priority support.

## Product

- [Homepage](https://neuralmind.uk/): what NeuralMind is, how it works, evidence, FAQ
- [Public benchmark](https://neuralmind.uk/benchmark/): per-repo results, baselines, and every miss
- [Measure your own repo](https://neuralmind.uk/measure-your-own/): three commands to get your own numbers
- [Team memory](https://neuralmind.uk/team/): sharing learned memory through git, governance, audit, seats
- [Pricing](https://neuralmind.uk/pricing/): free at 1 seat; Team $29/user/mo
- [Security](https://neuralmind.uk/security/): what goes over the network, SBOM, disclosure

## Docs

- [Docs home](https://docs.neuralmind.uk/wiki/Home): overview, benefits, what's new
- [About / how it works](https://docs.neuralmind.uk/about.html): architecture, synapse layer, release history
- [Installation](https://docs.neuralmind.uk/wiki/Installation.html): pip install, one-command MCP setup for Claude Code, Cursor, Cline, Claude Desktop
- [CLI reference](https://docs.neuralmind.uk/wiki/CLI-Reference.html): every command and environment variable
- [Architecture](https://docs.neuralmind.uk/wiki/Architecture.html): progressive L0–L3 context disclosure, graph + vector + BM25 hybrid retrieval
- [Memory layer](https://docs.neuralmind.uk/wiki/Memory-Layer.html): decision memory and the stale-decision guard
- [Multi-Project Scoping](https://docs.neuralmind.uk/wiki/Multi-Project-Scoping.html): isolation rules when running NeuralMind on multiple codebases
- [FAQ](https://docs.neuralmind.uk/wiki/FAQ.html)
- [Limits and failure modes](https://docs.neuralmind.uk/wiki/Limits-and-Failure-Modes.html): honest scope — where NeuralMind does not win

## Benchmarks

- [Public benchmark methodology and results](https://docs.neuralmind.uk/benchmarks/public.md): no-cherry-picking comparison vs full-file paste, ripgrep, vector RAG, and codebase-memory-mcp on pinned OSS repos; objective def-site oracle, no LLM judge
- [Live benchmark dashboard](https://docs.neuralmind.uk/benchmarks/): charts, per-query traces
- [Benchmarks & results](https://docs.neuralmind.uk/wiki/Benchmarks.html): CI-gated fixture evals, synapse A/B, faithfulness, and the multi-repo retrieval eval behind v4.6.0's one BM25 index over docs and code
- [Tool-output compression benchmark](https://docs.neuralmind.uk/benchmarks/compression.html): what the PostToolUse hooks did to tokens in Claude Code (they added them), why they inject nothing by default, and the opt-in that trims pip install and neuralmind build progress lines (NEURALMIND_BASH_REPLACE=1), with its retention gates

## Comparisons

- [vs Claude Code native memory](https://docs.neuralmind.uk/comparisons/vs-claude-code-native-memory.html)
- [vs Codex CLI memory](https://docs.neuralmind.uk/comparisons/vs-codex-cli-memory.html)
- [vs Mem0 and Zep](https://docs.neuralmind.uk/comparisons/vs-mem0-zep.html)
- [vs codebase-memory-mcp](https://docs.neuralmind.uk/comparisons/vs-codebase-memory-mcp.html)
- [vs long-context models](https://docs.neuralmind.uk/comparisons/vs-long-context.html)
- [vs prompt caching](https://docs.neuralmind.uk/comparisons/vs-prompt-caching.html)
- [vs vanilla RAG](https://docs.neuralmind.uk/comparisons/vs-rag.html)
- [vs Cursor codebase indexing](https://docs.neuralmind.uk/comparisons/vs-cursor-codebase.html)
- [vs GitHub Copilot](https://docs.neuralmind.uk/comparisons/vs-github-copilot.html)
- [vs Aider repo-map](https://docs.neuralmind.uk/comparisons/vs-aider-repomap.html)
- [Context-engineering stack guide](https://docs.neuralmind.uk/comparisons/context-engineering-stack.html): where NeuralMind sits next to Ponytail and Headroom

## Use cases

- [Claude Code daily driver](https://docs.neuralmind.uk/use-cases/claude-code.html): hooks, synapse memory on session start, prompt-time recall
- [Cost optimization](https://docs.neuralmind.uk/use-cases/cost-optimization.html)
- [Growing monorepo](https://docs.neuralmind.uk/use-cases/growing-monorepo.html)
- [Offline / regulated environments](https://docs.neuralmind.uk/use-cases/offline-regulated.html)
- [Run NeuralMind air-gapped](https://docs.neuralmind.uk/use-cases/air-gapped.html)
- [Team memory across a squad of agents](https://docs.neuralmind.uk/use-cases/multi-agent.html)
- [Benchmark your own repo](https://docs.neuralmind.uk/use-cases/benchmark-your-repo.html)
- [Measure memory across a refactor](https://docs.neuralmind.uk/use-cases/measure-memory-across-a-refactor.html)
- [Keep decision memory honest across commits](https://docs.neuralmind.uk/use-cases/decision-memory-across-commits.html)
- [Govern what your team's agents share](https://docs.neuralmind.uk/use-cases/govern-team-memory.html)
- [Pick up where you left off](https://docs.neuralmind.uk/use-cases/pick-up-where-you-left-off.html)
- [Hermes-Agent with code memory in every turn](https://docs.neuralmind.uk/use-cases/hermes-agent.html)

## Get it

- [PyPI package](https://pypi.org/project/neuralmind/)
- [GitHub repository](https://github.com/dfrostar/neuralmind)
- [Changelog](https://github.com/dfrostar/neuralmind/blob/main/CHANGELOG.md)