llms.txt@docs git:20261009.3ab7ab2A

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

# 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 at 51–242× fewer tokens than pasting every source file, and on 93.3% of a larger 150-question eval (top five). 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 at 51–242× fewer tokens than pasting every source file; beats ripgrep on cost on every repo, and on recall beats it 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.
- `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 guarantee) is on that scale, and `--naive-50k` reproduces it.
- Finds the right code: MRR 0.96 vs 0.23 for the incumbent codebase-memory-mcp at matched retrieval depth (a separate, off-by-default eval on `requests`/`click` only; pure retrieval ranking, reproducible).
- Learns how you work: a Hebbian synapse layer lifts top-k retrieval hit-rate, budget-neutral (reference fixture A/B). CI gates the direction (recall-on >= recall-off), not a magnitude; +3.5 to +14 points observed across runs. Reproduce with `python -m tests.benchmark.run`.
- Answer grounding vs. naive truncation at a matched token budget, on the prose-heavy reference fixture: delta +0.251 at v4.12.0 (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 (post-commit hook from `neuralmind init-hook`), 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 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)