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 & Antigravity IDE

Neuron does not replace the coding assistant. It removes repetitive project rediscovery. Your IDE is told (via generated rules for Cursor or Antigravity) 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 your selected IDE. Real output sketch:

[5/8] Initial scan…
✓ Mapped 5 modules across 15 files
✓ Learned 21 things about this project
[7/8] IDE integration…
✓ Created Cursor rules + MCP (.cursor/)
✓ Created Antigravity rules + MCP (.agents/ + ~/.gemini/config/mcp_config.json)

Connect your IDE

During neuron init you can select which IDE to configure:

• Cursor: Writes .cursor/mcp.json and agent rules. Then Settings → Tools & MCP → enable "neuron".
• Antigravity IDE: Writes workspace .agents/mcp_config.json (with NEURON_CWD), always-on rules under .agents/rules/ (trigger: always_on), skill .agents/skills/neuron-memory/, an AGENTS.md Neuron block, and a global MCP fallback at ~/.gemini/config/mcp_config.json. Then Customizations → Installed MCP Servers → Refresh, and Allow mcp(neuron/*) so tools are not stuck in Ask mode. Antigravity init runs a deep scan (no manual neuron scan --deep).

After upgrading NeuronAI, reload your IDE's MCP tool list so it refreshes to the current tool set (includes neuron_context, neuron_resolve_clarify, neuron_workflow).

neuron cursor              # Cursor connection status
neuron antigravity setup   # (re)write Antigravity wiring
neuron antigravity doctor  # diagnose Antigravity MCP + rules
neuron doctor              # stdio catalog + IDE reload guidance

Workflow skills (prime & deliver)

neuron cursor setup also installs Neuron Workflow skills so the agent knows how to work — not only where to look. Full guide: docs/workflow.md.

| Command | Meaning | Use when | | --- | --- | --- | | neuron init | Brain + scan + prime (prefs + PROJECT_MAP.md) + IDE | First setup | | neuron prime | Refresh conventions + map | Stack / scripts changed after init | | /neuron-deliver | Brain-gated plan → build → verify → remember (beats Absolute prompt boards) | Multi-file features, tickets |

neuron_context can return present.clarify / present.gate / codingAllowed: false — the agent must AskQuestion and must not write application code until you answer. Cursor also gets a best-effort neuron-gate hook (blocks Write while gate.json is open); always honor codingAllowed — Shell and other hosts may bypass the hook.

neuron prime
/neuron-deliver Add rate limiting to the public API

What lives on disk

.neuron/
├── prefs.json                 # init answers + workflow prefs     (commit)
├── PROJECT_MAP.md             # living map from init / prime      (commit)
├── memory/*.md                # per-memory markdown mirrors       (commit)
├── workflow/
│   ├── board.json             # deliver board (neuron_workflow)   (commit)
│   ├── board.md               # human-readable board              (commit)
│   ├── LAST_DELIVER.md        # last completed deliver receipt    (commit)
│   ├── gate.json              # open clarify gate                 (ignored)
│   └── history.jsonl          # deliver history                   (ignored)
├── 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/, prefs.json, and (optionally) workflow/board* + LAST_DELIVER.md so the team shares one project memory and deliver trail.

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

Nine 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_resolve_clarify | Persist clarify answers; clears gate.json | | neuron_workflow | Deliver board: get/set/clear / propose_waves / complete_checklist | | 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 / Antigravity IDE | | 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 antigravity setup | Write Antigravity .agents/ MCP, rules, skill, AGENTS.md | | neuron antigravity doctor | Diagnose Antigravity wiring | | neuron doctor | Diagnose brain, storage and IDE setup | | neuron mcp | MCP server (Your IDE 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.