-
Notifications
You must be signed in to change notification settings - Fork 0
Home
Reduce Claude, GPT, and Gemini token costs 40–70× on code questions. Local semantic codebase index + MCP server + PostToolUse compression hooks for Claude Code, Cursor, Cline, Continue, and any LLM.
Welcome — this wiki is the in-depth reference. For the fastest orientation, use the two pages at the top of Quick Links.
Phase 3 of the release arc. Every tagged release now auto-publishes a multi-platform container image to GHCR (ghcr.io/dfrostar/neuralmind:vX.Y.Z and :latest, linux/amd64 + linux/arm64) and attaches a CycloneDX JSON SBOM to the GitHub Release. New docs/use-cases/air-gapped.md walkthrough covers the strictest deployment posture — no outbound network at install, build, runtime, or query. New docs/COMPLIANCE-SUMMARY.md consolidates NIST AI RMF + SOC 2 + GDPR claims previously scattered across SECURITY-GUIDE.md and ENTERPRISE.md, with a "how to verify yourself" command for every claim.
No production code changes — pure CI + docs. Full details: v0.9.0 release notes.
neuralmind watch and neuralmind serve are first-class production processes now. Committed systemd and launchd templates, plus a Windows Task Scheduler walkthrough in the Scheduling Guide, keep both running across reboots and crashes. neuralmind serve exposes a /healthz endpoint (unauthenticated, returns {"status":"ok","version":"…"}) for Docker HEALTHCHECK and systemd ExecStartPost probes. Cross-platform walkthrough at docs/use-cases/always-on.md.
Distribution (v0.7.0) made NeuralMind reachable. Always-on (v0.8.0) makes it persistent — the synapse store accumulates 24/7 whether you're at the keyboard or not. Full details: v0.8.0 release notes.
NeuralMind now installs five ways: pip, pipx, uv, Docker, and source. Same package, same CLI, same MCP server, same graph view — every path. The Quick Start matrix lives at the top of the Installation page and the README; the repo's root Dockerfile is multi-stage, non-root, and pre-wheels every transitive dep so the runtime image doesn't need a C toolchain. PyPI keywords got a long-overdue refresh too, so search ranking for graph-view, hebbian-learning, and friends finally matches the v0.6.0 product copy.
Also in v0.7.0: a P2 fix in the JSONL bridge (rotation race that could drop events under logrotate/copytruncate) and a test-coverage gap on /api/queries. Full details: v0.7.0 release notes · Install paths walkthrough.
neuralmind serve now streams synapse + file events to the canvas in
real time over SSE. Affected nodes pulse as the brain works; a
sidebar log keeps the most recent ~80 events. A cross-process JSONL
bridge means a separate neuralmind watch daemon, a Claude Code
session, or any other process feeds the same live feed via
<project>/.neuralmind/events.jsonl. Pin UX (visible glyph,
Pin/Unpin button, Unpin-all), Cmd/Ctrl-K quick-switch, a 1–3-hop
depth slider, replay-last-query overlay, edge tooltips, and a
min-weight synapse slider round out the release.
The pitch flipped: v0.5.4 made the brain inspectable; v0.6.0 makes it legible. You can sit there and watch the hippocampus learn your codebase, live.
Multi-tool unlock: every agent (Claude Code, Cursor, OpenClaw, Hermes-Agent) talking to the same project reinforces the same synapse store, and the v0.6.0 canvas now shows the union of their activity. See docs/use-cases/multi-agent.md.
Full details: v0.6.0 release notes ·
Architecture: event bus + JSONL bridge ·
CLI Reference: neuralmind serve
The Obsidian-style force-directed graph that v0.6.0 made live first shipped in v0.5.4. Code nodes coloured by community; structural edges and Hebbian synapses drawn together; backlinks, synaptic neighbours, semantic quick-switch, and one-click open-in-editor. Per-session access token bound to 127.0.0.1 by default. Builds on v0.5.0's bundled MCP server.
NeuralMind runs as a second brain alongside the LLM: a persistent
SQLite-backed weighted graph that learns associations between code
nodes from co-activation, decays unused edges, and answers via
spreading activation. Includes the neuralmind watch daemon, three
Claude Code lifecycle hooks (SessionStart, UserPromptSubmit,
PreCompact), and a memory exporter that surfaces learned
associations to Claude Code's auto-memory system. See the
release notes or the
Architecture and Learning Guide
sections.
| Page | When to read it |
|---|---|
| Setup Guide | First-time setup for Claude Code, Cursor, Claude Desktop, or any MCP client |
| Use Cases | Step-by-step walkthroughs by persona: Claude Code user, cost optimization, any-LLM, offline/regulated, growing monorepo |
| Comparisons | Honest "NeuralMind vs X" pages: Cursor, Copilot, Cody, Aider, Claude Projects, LangChain, long context, prompt caching, RAG, tree-sitter |
| Version Strategy | Versioning policy, breaking changes, release schedule, deprecation timeline |
| Compatibility Matrix | Version compatibility, Python support, known issues, upgrade paths |
| Benchmarks | CI-measured reduction ratios, per-model breakdown, community submissions, and how to run it on your own code |
| Page | For... |
|---|---|
| Deployment Guide | DevOps/Infrastructure: Architecture patterns, Docker, Kubernetes, PostgreSQL backend, scaling, monitoring |
| Security Guide | Security teams: RBAC, encryption, secrets management, NIST AI RMF, SOC 2, threat models |
| Upgrading Guide | Everyone: How to upgrade between versions, breaking changes, rollback procedures |
| Page | Contents |
|---|---|
| Installation |
pip / pipx / uv / Docker / source — pick your path (v0.7.0) |
| Usage Guide | End-to-end examples for every command |
| CLI Reference | All CLI commands, flags, and output shapes |
| API Reference | Python API (NeuralMind, ContextResult, TokenBudget) |
| Architecture | How the 4-layer progressive disclosure system works |
| Integration Guide | MCP, CI/CD, VS Code, JetBrains, any-LLM piping |
| Scheduling Guide | Automate audits with Windows Task Scheduler, GitHub Actions, or cron |
| Learning Guide | Opt-in memory + cooccurrence reranking (v0.3.2) and brain-like synapses (v0.4.0) |
| Brain-Like Learning | Design rationale for the v0.3.x learning system |
| v0.4.0 Release Notes | Brain-like synapse layer: continuous co-activation, spreading activation, lifecycle hooks |
| Troubleshooting | Common issues and fixes |
| FAQ | 30+ frequently asked questions answered |
A two-phase token optimizer for AI coding agents.
- Phase 1 — Retrieval. A 4-layer progressive-disclosure index surfaces ~800 tokens of structured context for any code question, instead of loading 50,000+ tokens of raw source.
-
Phase 2 — Consumption. PostToolUse hooks (Claude Code) compress
Read,Bash, andGrepoutput before the agent sees it — typically 88–91% smaller.
Combined effect: 5–10× total reduction vs baseline agent usage, offline and model-agnostic.
You: "How does authentication work in my codebase?"
❌ Traditional: Load entire codebase → 50,000 tokens → $0.15-$3.75/query
✅ NeuralMind: Smart context → ~800 tokens → $0.002-$0.06/query
Short answer: if any of these describe you, start with the Use Cases page.
- My Claude Code session hits context limits mid-task
- My monthly LLM bill is climbing
- I start every session re-pasting project structure
- The agent reads a 2,000-line file to answer one question
- I want to query my codebase from ChatGPT / Gemini / a local model
- I need AI coding help but code can't leave my machine
Full symptom-and-goal matrix in the main README.
# Install
pip install neuralmind graphifyy
# Setup
cd your-project
graphify update .
neuralmind build .
# Use
neuralmind wakeup .
neuralmind query . "How does authentication work?"
neuralmind skeleton src/auth/handlers.pyClaude Code users, install the lifecycle hooks (PostToolUse compression plus the v0.4.0 brain-like synapse hooks: SessionStart, UserPromptSubmit, PreCompact):
neuralmind install-hooks .
neuralmind init-hook . # auto-rebuild on every git commit (optional)
neuralmind watch & # always-on synapse learning from file edits (optional)| Compared against | Short verdict |
|---|---|
Cursor @codebase |
Works only in Cursor; NeuralMind works anywhere |
| GitHub Copilot | Copilot is hosted completions; NeuralMind is local context |
| Claude Projects | Projects reload all files every turn; NeuralMind retrieves only what the query needs |
| Long context windows | Possible ≠ cheap — NeuralMind drops per-query cost ~60× |
| Prompt caching | Caching amortizes big prompts; NeuralMind makes them small |
Full list: Comparisons.
Don't trust fixture numbers — measure it on your own repo:
pip install neuralmind graphifyy
graphify update . && neuralmind build .
neuralmind benchmark . --contributeThis outputs your reduction ratio, tokens per query, and an estimated monthly savings figure at Claude 3.5 Sonnet pricing. The --contribute flag produces a ready-to-share JSON blob you can paste into a PR (or a benchmark submission issue) to add to the public leaderboard.
Full walkthrough: Does NeuralMind work on your codebase?
- GitHub Issues — bug reports, feature requests
- GitHub Discussions — questions and ideas
- Main README — always the most current overview