🧠 NeuralMind

Persistent codebase memory for AI coding agents — Claude Code, Codex, Cursor, Cline, Continue, and any MCP client.

Your agent learns your codebase the way a senior engineer would — what goes together, what you usually touch next — and remembers it across sessions. Local-first, no telemetry. Side effect: much cheaper code questions — 45–261× fewer tokens than pasting every source file, at 93.75% mean gold-file recall, on a public 40-query benchmark that publishes every miss.

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+)
• Gets compliance annotations it can actually trust — a version string or an SVG path is no longer reported as a SOC 2 control (v3.3.0+)
• Searches your prose too: ingest-content indexes a book or docs tree into its own project, re-embeds only what changed, and shows a progress bar with an ETA while it works (v3.4.0+)
• Thinks with your brain, not just your code: 6 SOTA synaptic learning techniques (STC, SAMPL, resource STDP, FOK, lateral inhibition, replay) plus intent-aware ranking that reads "how does X implement Y" as a question about code, and ranks implementation above docstrings for it (v3.9.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 sends no telemetry and transmits no repository content off your machine. It processes locally and hands only the relevant code slice to your AI tool on the same machine — what that tool then sends to its own model provider is between you and it. Its one outbound request is a one-time download of a public embedding model on first build — pre-seedable, see Run NeuralMind air-gapped.

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. Hermes-Agent, OpenClaw, and Agent Zero are covered by host-specific notes in skills/neuralmind/SKILL.md and a CI check (tests/test_skill_manifest.py) that keeps the portable skill's identity in sync with each registry's rules, but none has been physically driven end-to-end yet either.

Benefits

1. Cheaper context

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. Context budget management (v3.13.0+)

Every query gets a fixed token budget (default 8,000 tokens, matching lean-ctx). If the assembled context would exceed it, lower-priority layers are trimmed first — L3 search results, then L2 on-demand modules, then L1 summary. L0 identity is never trimmed. Budget warnings log at 80% usage.

result = mind.query("How does auth work?", context_budget=6000)
# Context trimmed to fit 6000 tokens, L3 removed first

4. Session summaries (v3.13.0+)

Periodic session digests (every 25 tool calls) capture what was done, key decisions, files touched, and commands run. Stored as markdown under .neuralmind/summaries/, semantically recallable via the vector index. Auto-pruned (max 100 per project).

neuralmind status .  # shows recent summaries

5. Code graph traversal edges and read dedup (v3.13.0+, not yet wired in)

The graph_traversal (co-access edges between files read together) and read_dedup (content-hash stubs for re-reads of unchanged files, plus preloading of related files) modules ship in the source tree, but nothing in the query path or the hooks calls them yet — so they do not affect what your agent sees today. They are listed here so the v3.13.0 release notes don't read as a promise the running product keeps.

6. Cognition loop (v3.13.0+)

neuralmind cognition-loop runs a knowledge-consolidation pass on demand:

1. Reinforces co-access edges from recent queries
2. Decays unused edges
3. Consolidates knowledge (promotes frequently co-activated clusters to LTP)
4. Prunes stale data (old summaries, dormant synapses)

neuralmind cognition-loop .  # run a pass now
# Nothing schedules it for you — add a cron entry if you want it periodic

7. Decision memory + stale-decision guard (v4.1.0+)

Store architecture decisions with rationale, evidence, affected files and the commit they came from (neuralmind decisions record), search them (neuralmind decisions query), and retire one when the code moves on (neuralmind decisions invalidate). Before your agent edits a file, a PreToolUse hook surfaces any decision governing it that has been marked stale or invalidated. Invalidation is manual today: the engine that would retire decisions automatically on commit exists but is not yet wired into the hooks.

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

93.75% mean gold-file recall (85–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.

9. Answer grounding vs. naive truncation (currently a loss)

At a matched token budget, the faithfulness eval asks whether NeuralMind's selected context carries more of the gold facts than naive truncation. On the ~500-line reference fixture, which mixes code with prose chapter summaries, truncation currently wins slightly: 0.451 vs 0.505 expected-fact recall, a −0.054 delta at v4.3.4. CI fails the build if the mean delta drops below −0.10; earlier releases measured +0.013 to +0.143. We publish it as a loss rather than drop the eval.

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 transmits no repository content, 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

Index prose, not just code (v3.4.0+)

A book, a docs tree, a research folder — ingest-content indexes a corpus of Markdown/text into its own project, so it never gets folded into the enclosing repo:

neuralmind ingest-content chapters --dry-run       # preview: files, sizes, chunk counts
neuralmind ingest-content chapters --content-only  # index the prose, skip the code graph
neuralmind status book                             # nodes indexed, chunks, last ingest

Re-runs are incremental — only files whose content changed are re-embedded, and chunks from shortened or deleted files are evicted. Long embeds show a progress bar with an ETA on a terminal, and plain milestone lines off one (CI, an agent shell), so a slow run is never mistaken for a hung one.

Wire up your agent

# Claude Code, Cursor, Cline, VS Code, Claude Desktop — registers with every detected client
neuralmind install-mcp --all
# Codex, Continue, or any other MCP client: point it at the stdio server
codex mcp add neuralmind -- neuralmind-mcp

# Claude Code: install lifecycle hooks (SessionStart, UserPromptSubmit, PreCompact, PostToolUse, PreToolUse, Stop, SessionEnd)
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 .

# Reproduce the public benchmark (requests, click, flask, rich) — needs a source checkout
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. On real repos, neuralmind benchmark reports 12–50× against its fixed 50K-token naive estimate, and the public benchmark measures 45–261× against every source file (benchmarks · production field report).

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 neuralmind last recovers the full output the compressor trimmed from a cache written before compression.
• Team memory. neuralmind memory publish writes a learned-weights bundle (no source code); commit it and teammates' agents inherit it 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 fixture 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; the public benchmark reproduces on demand with python -m evals.public.run, raw per-query data committed:

• 85–100% gold-file recall (93.75% mean) at 45–261× fewer tokens than pasting every source file on the public benchmark — 4 of 40 queries missed, every one published, and a bare vector-RAG baseline matches or beats it on recall at fewer tokens (where NeuralMind loses).
• 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, against the CLI's 50K-token naive estimate (full field report).
• 5.1× token reduction on the CI fixture at v4.3.4 (500-line, deliberately tiny — the floor of a floor; the build fails below 4.0×).
• 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 and results.

3 submission(s). See the JSON data for notes and verification commands, or the interactive dashboard for scatter + by-language charts.

🔒 Security & Compliance

• Local engine, no telemetry by default. NeuralMind transmits no repository content and ships no telemetry in its default configuration. Only the minimal relevant slice of code ever reaches your AI tool. The only outbound requests it makes by default are a one-time fetch of a public embedding model on first build (carrying nothing about your code; pre-seed it and the install never reaches the network at all) and, only if you explicitly opt in with NEURALMIND_LLM_SEED=1 + ANTHROPIC_API_KEY, a call that sends README/architecture-doc prose (never code, never other files) to Anthropic to seed synapse edges. No code path ingests video, image, or audio files at all. Full disclosure: docs/compliance/THIRD_PARTY_LLM_DISCLOSURE.md.
• CycloneDX SBOM per release, hash-chained audit logs (the query trail in the core; the governance trail in the Team modules, free at 1 seat), signed licenses (Ed25519), tarball integrity instructions on every release.
• Live posture page: neuralmind.uk/security · Policy: SECURITY.md · Compliance summary · Third-party LLM & media disclosure · 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), NEURALMIND_STALE_GUARD=0 (skip the PreToolUse stale-decision guard). 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? NeuralMind itself sends no telemetry and transmits no repository content off your machine; its only default outbound request is a one-time public embedding-model download on first build (pre-seedable). Your agent still sends its selected slice to its own model — NeuralMind just makes that slice 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, and the auto-issued free license runs every feature — governance and audit included — at 1 seat. The Team tier ($29/user/mo, 5–50 seats) adds seats beyond one, priority support, and an annual invoice.

What about SOC 2? Our architecture supports SOC 2 deployment patterns (no repository content transmitted, 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.