npm install -g neuronai && cd your-project && neuron init

The problem

Every new chat starts from zero. You re-explain the architecture, the conventions, the thing you tried last quarter that broke production. Then the agent confidently proposes it again.

Without a project brain

You: Add rate limiting to the API. Agent: I'll add an in-memory counter to each route handler. You: No. We decided rate limiting goes in middleware, once, for everything.

With one

You: Add rate limiting to the API. Agent: (reads project memory) This project decided rate limiting belongs in the middleware layer so every handler inherits it, rather than per-handler throttling. I'll add it there.

That knowledge lives in .neuron/ in your repo, in plain JSON, versioned in Git alongside the code it describes.

See it in Cursor

Neuron does not replace the coding assistant. It removes repetitive project rediscovery. Cursor is told (via the generated rule) to call neuron_context before broad repository exploration, then open the returned paths.

Why it helps

How it works

codebase ──scan──▶ .neuron/brain/ ──retrieve──▶ compile ──MCP──▶ Cursor
                        ▲                                          │
                        └────────── ask before remembering ◀───────┘

Scan builds the brain

neuron init / neuron scan walks the repo, detects stack and modules, and writes durable brain files. Structural code intelligence (symbols, verified imports/calls/routes) lives in the same knowledge.json plane — not a second index, not embeddings.

Compact context on every task

Retrieval is deterministic BM25-style lexical ranking over memories, map locations, and code symbols. Relevance is a gate — importance never promotes an unrelated memory. When evidence exists, expansion follows high-confidence edges (start → related → dependency).

Brain Compression packs one markdown document against a hard token budget (500 / 1200 / 3500 for minimal / standard / deep).

neuron context "Where should I add a payment endpoint?"

Project Brain
────────────────────────

Recommended:
  src/billing/service.ts

Rules:
  Never call the payment provider directly from route handlers

Context: 182 / 2143 tokens · 8 ms · MODIFICATION

estimatedTokensSaved compares compiled context to pasting the whole brain — not a claim about the model's full session bill.

Install & quick start

npm install -g neuronai
cd your-project
neuron init

Node.js 22+. Or: npx neuronai init. One package, one dependency (@modelcontextprotocol/sdk).

Init detects the project, writes the brain, and wires Cursor. Real output sketch:

[5/8] Initial scan…
✓ Mapped 5 modules across 15 files
✓ Learned 21 things about this project
[7/8] Cursor integration…
✓ Created Cursor rules + MCP (.cursor/)

Connect Cursor

neuron init writes .cursor/mcp.json and agent rules. Then Settings → Tools & MCP → enable "neuron". After upgrading NeuronAI, toggle the server off/on (or Reload Window) so the tool list refreshes to the current 7 tools. If chat still shows neuron_prepare_task or CallMcpTool returns -32602, that is a stale Cursor catalog — reload MCP; do not rewrite config.

neuron cursor     # connection status
neuron doctor     # stdio catalog + IDE reload guidance

What lives on disk

.neuron/
├── prefs.json            # your init answers                 (commit)
├── brain/
│   ├── dna.json          # stack, modules, structure         (commit)
│   ├── knowledge.json    # memories, decisions, rules, code  (commit)
│   └── health.json       # derived health score              (commit)
├── runtime/store.json    # regenerable engine store          (ignored)
└── cache/                # scan cache                        (ignored)

Commit .neuron/brain/ and your team shares one project memory.

Ask before remembering

Neuron never writes a memory you did not approve. After a change the agent proposes a draft and asks Yes · Edit · No. From the terminal:

neuron remember "Rate limiting belongs in middleware, not individual handlers"

MCP tools

Seven tools, one job each. Full reference: docs/mcp.md.

| Tool | Purpose | | --- | --- | | neuron_context | Ranked, compressed project knowledge for a task — call first | | neuron_search | Keyword search over memories | | neuron_remember | Store a decision, pattern, warning or fact | | neuron_update | Change a memory (versioned) | | neuron_after_task | Propose what to remember after coding | | neuron_resolve_suggestion | Apply Yes / Edit / No | | neuron_scan | Rebuild the brain from the codebase |

Local-first (tested)

| | | | --- | --- | | Cloud services | none | | API keys | none | | Database | none — plain JSON files | | Telemetry | none | | Network at runtime | none (pnpm verify:offline) |

Honest metrics

neuron brain

Keep these labels separate:

| Label | Meaning | | --- | --- | | Brain compression | Whole brain → compiled neuron_context (measured) | | Exploration policy | Scripted baseline vs Neuron ops (simulated) | | Live agent proof | Real Cursor tool traces — measured on hard MCP A/B for this release; not token/latency savings |

Never call Brain compression “agent token savings.” Never call the scripted exploration harness a live-agent result. Details: docs/FINAL_RELEASE_AUDIT.md, docs/LIVE_AGENT_MCP_VALIDATION.md.

Commands

| Command | What it does | | --- | --- | | neuron init | Detect the project, build the brain, wire Cursor | | neuron scan | Re-learn from the codebase (--deep, --update) | | neuron search <query> | Search what the project knows | | neuron context <task> | Show compact context for a task | | neuron remember <text> | Add something yourself | | neuron brain | Metrics: measured, derived, estimated | | neuron status | Project and memory overview | | neuron cursor | Cursor connection status | | neuron doctor | Diagnose brain, storage and Cursor setup | | neuron mcp | MCP server (Cursor calls this) |

Roadmap

Local OSS stays free. Cloud is optional convenience — not required for the core product.

Architecture (monorepo)

apps/cli          the neuron binary (bundled, self-contained)
apps/mcp-server   MCP server over stdio
packages/brain    ProjectBrain, retrieval, compiler, dedupe
packages/storage  the one runtime construction path
packages/*        scanner, config, types, Cursor integration

More: How it works · .neuron/ folder · FAQ · Privacy · Production readiness.

Contributing

pnpm install
pnpm verify   # lint, typecheck, test, build, package + offline checks

See CONTRIBUTING. Issues: open an issue.

License

AGPL-3.0. Name and logo: TRADEMARK. Security: SECURITY.