🧠 NeuralMind

Persistent memory and context compression for AI coding agents.

Your agent learns your codebase the way a senior engineer would — what goes together, what you usually touch next — and remembers it across sessions. 100% local, no telemetry. Side effect: 12–50× cheaper code questions on real repos, measured in CI on every commit.

After install, your agent:

• Boots with SYNAPSE_MEMORY.md (learned associations, strongest hub files)
• Receives PostToolUse compression automatically (Bash output → errors + signals)
• Queries your codebase in ~800 tokens instead of ~50,000
• Gets health checks, synapse pruning, audit queries, and code/doc type filtering (v3.1.4+)
• Gets a pre-commit warning when a change skips a pattern its own peers share — the eleventh handler that forgot the auth check the other ten have (v3.2.0+)

Works with every IDE your team already uses.

Website: neuralmind.uk · Docs: docs.neuralmind.uk · Changelog: CHANGELOG.md · Release notes: docs/releases/

The Problem

Every large engineering organization has the same AI spend problem: token costs compound as the codebase grows, context is re-discovered from scratch on every query, and nobody can explain the ROI.

You: "How does authentication work in my codebase?"

❌ Naive:  Load entire codebase → 50,000 tokens → $0.15-$3.75/query
✅ NeuralMind: Smart context → ~800 tokens → $0.002-$0.06/query

Engineering leads are stuck between two bad options: let agents burn tokens loading whole files, or hand-curate context windows. Neither scales.

The Solution

NeuralMind is a code intelligence layer that deploys in your infrastructure — not a SaaS wrapper, not a model swap. It sits between your agent and your code, learning how your team actually works.

Two cooperating brains:

The agent asks a question. NeuralMind retrieves only the relevant slice (~800 tokens). The more you use it, the smarter the retrieval gets — Hebbian co-activation strengthens edges between code that's used together; unused edges decay.

NeuralMind makes no network calls of its own. It processes locally and feeds only the relevant code slice to your AI tool.

Who This Is For

If your team uses Claude Code, Cursor, Cline, or any MCP agent — NeuralMind makes every agent remember your codebase.

Theoretical = MCP is standard protocol. All MCP-compatible agents should work. We haven't physically tested display-server-dependent IDEs (Cursor, Cline, Continue) — Xvfb is not available in our CI.

Benefits

1. Cheaper context (measured in CI on every commit)

The fixture number is the floor of a floor: small repo, conservative gate. The mechanism is what scales — the bigger the codebase, the more whole-file context you avoid.

2. Learns how you work (the differentiator)

NeuralMind's moat is usage memory: a Hebbian synapse layer that learns what your team edits together and surfaces it on future queries.

Both are budget-neutral by design: recalled nodes displace the weakest hits rather than adding tokens.

Why a range, not a number. Both A/Bs run against a ~500-line fixture through a ChromaDB HNSW index, so the deltas are small and jitter between runs — CI averages the onboarding lift over three runs for exactly that reason. What CI guarantees is the direction; the magnitude is whatever your own repo produces. Run python -m tests.benchmark.run for yours.

3. Finds the right code (not just less of it)

93.75% mean gold-file recall (79–100% per repo) across 40 pre-registered queries on four pinned OSS repos (requests, click, flask, rich) — every miss published, not rounded away. Reproducible — python -m evals.public.run. A separate, off-by-default eval on requests/click only put retrieval ranking at MRR 0.96 against the incumbent codebase-memory-mcp's 0.23; that one has not been re-verified against the current four-repo corpus.

4. Better-grounded answers (not just shorter)

At a matched token budget, NeuralMind's selected context carries more of the gold facts than naive truncation. CI gates the delta at ≥ 0; the measured delta has ranged +0.013 to +0.143 across runs on the reference fixture, with grounding at 1.00. Same caveat as above — the gate is the guarantee, the magnitude moves.

Use Cases

Limitations (Read Before Installing)

What NeuralMind is NOT:

• NOT a SaaS wrapper. It's a code intelligence layer that runs in your infrastructure. We never see your code.
• NOT a model swap. It works with whatever agent you already use — Claude, GPT, Gemini, or any MCP-compatible agent.
• NOT a replacement for Copilot/Cursor. It composes with them. It's the memory layer that makes every agent smarter.
• SOC 2-ready posture, certification on the roadmap. Our architecture supports SOC 2 deployment patterns (an engine that makes no network calls of its own, hash-chained audit log, RBAC). See commercial-terms.json.
• NOT SSO/SAML today. This is a roadmap feature. See commercial-terms.json do_not_market list.

Technical limits:

• Per-language answer quality is Python-first. Structural coverage (symbol extraction) is 100% across all 10 bundled languages. Answer quality (faithfulness, grounding) is only measured on Python fixtures.
• Synapse learning needs sessions. The Hebbian layer learns from co-activation over time. A fresh install has no learned associations — they accumulate over days/weeks of real use.
• No real-time cross-machine sync today. Team memory uses a commit-and-pull model (neuralmind memory publish). Real-time sync is roadmap-only.

How to Use

Install (pick your path)

Quick start

cd your-project
neuralmind build .          # index the codebase (tree-sitter, ~seconds to minutes)

neuralmind wakeup .         # what the agent sees at session start
neuralmind query . "How does authentication work?"  # ~800 tokens, not 50,000

neuralmind install-hooks .  # Claude Code: automatic PostToolUse compression
neuralmind serve .          # Obsidian-style graph view in your browser
neuralmind savings . --cost # measured token savings, priced for your model
neuralmind doctor           # verify the install end to end

Wire up your agent

# Any MCP-compatible agent (Claude Code, Cursor, Cline, Continue, Codex)
neuralmind install-mcp --all

# Claude Code: install lifecycle hooks (SessionStart, UserPromptSubmit, PreCompact, PostToolUse)
neuralmind install-hooks .

# Team memory: commit learned weights (no source code) for teammates
neuralmind memory publish

Run the benchmark

# Measure YOUR repo — not a fixture, not a demo
neuralmind benchmark .

# Measure against the public benchmark (requests, click)
neuralmind benchmark . --public

# Retrieval self-probe: does the index find YOUR symbols?
neuralmind probe .

⚡ 30-Second Proof

The clearest evidence the memory is working is the measurable side effect: the agent stops re-loading context it already understood. Reproduce it on a fresh clone:

git clone https://github.com/dfrostar/neuralmind && cd neuralmind
bash scripts/demo.sh

Output looks like:

  Q: How does authentication work in this codebase?
     naive = 4,736 tok   neuralmind =  829 tok   reduction =   5.7×

  Average reduction:   5.5×  across 3 queries
  Avg context size:    859 tokens  (vs 4,736 naive)

The fixture is intentionally tiny (~500 lines) — it runs in CI as a regression gate. Real repos measure 12–50× on the same pipeline (benchmarks · measured production results).

Then get your own number:

pip install neuralmind
cd /path/to/your-repo
neuralmind build .
neuralmind benchmark .

🧠 What You Get

• Progressive context disclosure (L0–L3). A question costs ~800 tokens, not your whole repo. The agent asks for more depth only where it needs it.
• A synapse layer that learns. Hebbian co-activation strengthens edges between code that's used together; unused edges decay. Recall is spreading activation over that graph — your agent's context gets better the more you work.
• Session memory. SYNAPSE_MEMORY.md is exported for Claude Code so every session boots already knowing the hub files and learned associations.
• Tool-output compression + recovery. PostToolUse hooks compress noisy Bash output to errors + signals, and a recovery cache brings back tool output the context window dropped.
• Team memory. neuralmind memory publish commits a learned-weights bundle (no source code) that teammates' agents inherit on their next session — a fresh clone starts with the team's earned intuition.
• Commit-time drift guard. neuralmind drift reads your staged diff, maps changed lines to graph symbols, and flags one that skips a pattern a strong majority of its siblings share — before it ships, not after a query happens to surface the cluster. neuralmind init-hook wires it into pre-commit automatically (warn by default; --strict to block).
• MCP server for any agent. Claude Code, Codex, Cursor, Cline, Continue, or anything MCP-compatible: neuralmind install-mcp --all.
• Graph view. neuralmind serve renders the index as a force-directed, community-coloured graph with the synapse overlay — backlinks, semantic quick-switcher, clickable neighbours. There's also a VS Code extension.
• Ten-language code graph. tree-sitter indexes Python, TypeScript, Go, Rust, Java, C, C++, C#, Ruby, and PHP out of the box.
• Business-context synapse seeding. seed_from_documents() builds deterministic, LLM-free associations between business documents (decisions, SOPs, meeting notes, policies) and your code graph — adjacency-matched compounds, title-reference cross-links, frequency-capped tags. 56 tests.
• Team tier ($29/user/mo). The license buys seats and support: a multi-seat license (5-50), priority support, and an annual invoice. The features themselves — shared-memory governance, append-only hash-chained audit log, self-hosted deployment — run under the auto-issued free license at 1 seat, so you can evaluate everything before paying. MIT core stays MIT; tier2 is source-available, not MIT — see LICENSING.md and pricing.

How it works under the hood: Architecture · brain-like learning.

📊 Benchmarks

Measured, not marketed — the numbers are produced by CI on every commit (every merged PR carries a sticky benchmark comment) and reproduce locally with python -m tests.benchmark.run:

• 79–100% gold-file recall (93.75% mean) at 45–257× fewer tokens on the public benchmark.
• Synapse recall A/B: lifts top-k hit rate at ±0 token cost — +3.5 to +14 points across runs; CI gates the direction, not the magnitude.
• Onboarding lift: lifts top-k module hit-rate from a committed team baseline — +0.9 to +11.6 points across runs (a distinct eval from the synapse recall A/B above — see evals/onboarding/).
• Real production rebuild: 48.8× average reduction, 1,033 tokens/query (full field report).
• 6.1× token reduction on the CI fixture (500-line, deliberately tiny — the floor of a floor).
• Retrieval quality (N-15): graded relevance (0-3), nDCG@5, MRR, recall@k, precision@k + RAGAS faithfulness scoring — 8 CI regression gates, per-shape breakdowns.
• Content QA (N-16): book/markdown content retrieval — 30 queries, 11 chapters, 150K-word corpus. N-15 IR metrics + RAGAS on long-form content. ingest-content CLI + benchmark --content end-to-end command.
• Backend parity gate: the built-in tree-sitter backend is held within tolerance of the legacy graphify backend on every PR.

Methodology, gold sets, and community submissions: benchmarks/ · public methodology.

🔒 Security & Compliance

• 100% local engine. NeuralMind makes zero network calls of its own and ships no telemetry. Only the minimal relevant slice of code ever reaches your AI tool.
• CycloneDX SBOM per release, hash-chained audit log (Team tier), signed licenses (Ed25519), tarball integrity instructions on every release.
• Live posture page: neuralmind.uk/security · Policy: SECURITY.md · Compliance summary · SDLC policy

Behavior toggles: NEURALMIND_BYPASS=1 (skip compression), NEURALMIND_SYNAPSE_INJECT=0 (skip prompt-time recall), NEURALMIND_SYNAPSE_EXPORT=0 (skip memory export), NEURALMIND_TEAM_MEMORY=0 (skip team-bundle import). All fail-open.

📚 Documentation

❓ FAQ

How is this different from RAG? RAG retrieves similar text. NeuralMind maintains a weighted graph of your code and learns from use — retrieval is spreading activation over structural edges plus Hebbian synapses, disclosed progressively so the agent pays only for the depth it needs.

Does my code leave my machine? No. The engine is fully local. Your agent still talks to its own model — NeuralMind just makes what it sends smaller.

What if it doesn't help on my repo? Run neuralmind benchmark . and read the number. If it's not worth it, uninstall — and see the use cases for guidance on when NeuralMind is the right fit.

Is the paid tier required? No. The core is MIT and complete. The Team tier adds governance, audit, and seat management for organizations.

What about SOC 2? Our architecture supports SOC 2 deployment patterns (no network calls of its own, audit log, RBAC). Certification is on the roadmap. See commercial-terms.json.

What about SSO/SAML? Roadmap-only. Not available today. See commercial-terms.json do_not_market list.

🤝 Contributing

Contributions welcome — see CONTRIBUTING.md, CODE_OF_CONDUCT.md, and SUPPORT.md. Tests live in tests/; pytest tests/ must pass (the synapse layer's tests are stdlib-only). Security reports: see SECURITY.md.

📄 License

MIT for the core — see LICENSE. The optional Team tier is licensed separately — see LICENSE-COMMERCIAL.md.