git:20260928.f69202c to git:20261004.bcad5b9

3 added, 2 removed. Audit A to A.

# 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 93.75% mean gold-file recall at 45–261× 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–100% gold-file recall per repo (93.75% mean, 90% found-rate across 40 pre-registered queries) at 45–261× fewer tokens than pasting every source file; beats ripgrep on cost on every repo, and on recall beats it on 2 of 4 repos and ties exactly on the other 2 (public benchmark on `requests`, `click`, `flask`, `rich`; `flask` is NeuralMind's weakest repo at 0.85 recall; 4 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.

- - On private repos, `neuralmind benchmark .` has reported 12–50× fewer tokens per code question, measured against a fixed 50K-token estimate of naive context (field reports — directional, not a guarantee).

+ - `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. Admin actions land in a hash-chained audit log; publish-time scope/threshold enforcement is on the roadmap.

- 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

+ - [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, tool-output compression, synapse memory on session start

+ - [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)

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