# NeuralMind

> Persistent, 100% local memory for AI coding agents. NeuralMind learns your codebase the way a senior engineer would — what files go together, what you usually edit next, what patterns matter — and compresses tool output before the model reads it. Side effect: 12-50× cheaper code questions, measured by a reproducible public benchmark on real pinned OSS repos. Works with Claude Code, Cursor, Cline, Continue, and any MCP-compatible agent. MIT-licensed, `pip install neuralmind`.

Key facts, each backed by a runnable eval (raw traces committed):

- Cheaper context: 100% gold-file recall at 38–85× fewer tokens than pasting files; beats ripgrep on both recall and cost (public benchmark on `requests` and `click`).
- Finds the right code: MRR 0.96 vs 0.23 for the incumbent codebase-memory-mcp at matched retrieval depth (pure retrieval ranking, reproducible).
- Learns how you work: a Hebbian synapse layer lifts top-k retrieval hit-rate +6.1 points, budget-neutral (reference fixture A/B).
- Better-grounded answers: faithfulness +0.143 at a matched token budget (reference fixture parity gate).
- 100% local: no code leaves the machine; 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.

## Docs

- [Homepage](https://docs.neuralmind.uk/): 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
- [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

## Comparisons

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

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