llms.txt@docs git:20261006.347c963A

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

# 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 reaches 95% mean gold-file recall at 46–263× fewer tokens than pasting every source file. 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: 85.71–100% gold-file recall per repo (95% mean, 92.5% found-rate across 40 pre-registered queries) at 46–263× 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`; `click` is NeuralMind's weakest repo at 0.86 recall; 3 of 40 queries missed, every one published). Caveat: a bare vector-RAG baseline matches or beats NeuralMind's recall at fewer tokens on every repo — 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 (a published loss): at a matched token budget, naive truncation currently keeps slightly more gold facts than NeuralMind's context on the prose-heavy reference fixture — delta -0.054 at v4.3.4; CI fails below -0.10; earlier releases measured +0.013 to +0.143.
- 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), and why they no longer inject anything

## 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)