Nucleus

The MCP server that makes AI outputs more reliable every week.

AI agents hallucinate, break code, and repeat mistakes. Nucleus catches this. Every AI output is verified, every correction is recorded, and every mistake trains the system to not repeat it. Locally, on your machine.

Three Frontiers

The core loop that makes AI reliability compound over time:

  GROUND              ALIGN               COMPOUND
  ──────              ─────               ────────
  Machine verifies    Human corrects      System learns

  AI writes code  →  You fix a mistake →  Delta recorded
  GROUND checks   →  Verdict stored    →  DPO pair created
  Receipt logged  →  Event emitted     →  Training data grows
       │                   │                    │
       └───────────────────┴────────────────────┘
                    Reliability improves

GROUND — 5-tier execution verification. Syntax, imports, tests, runtime. Goes outside the formal system to check the AI's work.

ALIGN — One-call corrections. nucleus_align(action="correct", params={context, correction}). Each correction automatically records a verdict, creates a training pair, and emits an event.

COMPOUND — Deltas measure the gap between intent and reality. Recurring patterns become strategy. Negative deltas become training signal.

Every tool response shows frontier health:

[frontiers: GROUND 42 | ALIGN 12 | COMPOUND 28]

Quick Start

pip install nucleus-mcp
nucleus init --recipe founder

Two commands. Nucleus is running. AI outputs are now verified.

What It Does

114 MCP tools across 13 facades:

• GROUND — Execution verification (5 tiers: diff, syntax, imports, tests, runtime)
• ALIGN — Human corrections (verdict + delta + DPO + event in one call)
• Memory — Engrams that persist across sessions. Write once, recall forever.
• Sessions — Save context, resume later. Session arc shows your last 3 sessions.
• Tasks — Priority queue with escalation, HITL gates, and heartbeat monitoring.
• Governance — Kill switch, compliance configs (EU DORA, MAS TRM, SOC2), audit trails.
• Orchestration — Agent slots, multi-brain sync, task dispatch.
• Archive — Training pipeline (SFT + DPO), delta tracking, frontier health dashboard.

Nucleus Pro

Everything above is free (MIT). Nucleus Pro adds verifiable governance:

nucleus trial                              # 14-day free trial
nucleus compliance-check                   # Score your AI governance
nucleus audit-report --signed -o report.html  # Cryptographically signed report

$19/month or $149/year — nucleusos.dev/pricing

Install

One-Click

pip / npx

pip install nucleus-mcp

Or use npx (zero Python setup required):

npx -y nucleus-mcp

Configure Your MCP Client

Claude Desktop / Cursor / Windsurf

Add to your MCP config (claude_desktop_config.json or equivalent):

{
  "mcpServers": {
    "nucleus": {
      "command": "npx",
      "args": ["-y", "nucleus-mcp"]
    }
  }
}

{
  "mcpServers": {
    "nucleus": {
      "command": "python3",
      "args": ["-m", "mcp_server_nucleus"],
      "env": {
        "NUCLEAR_BRAIN_PATH": "/path/to/your/project/.brain"
      }
    }
  }
}

Claude Code

Add to .mcp.json in your project root:

{
  "mcpServers": {
    "nucleus": {
      "command": "npx",
      "args": ["-y", "nucleus-mcp"]
    }
  }
}

Path Discovery

Nucleus finds your .brain automatically:

1. NUCLEAR_BRAIN_PATH environment variable (explicit)
2. Walk up from CWD looking for .brain/ directory
3. Fall back to $HOME/.nucleus/brain

CLI

Nucleus has a full CLI alongside the MCP tools. Auto-detects TTY (table output) vs pipe (JSON).

# Memory
nucleus engram write my_key "insight here" --context Decision --intensity 7
nucleus engram search "compliance"
nucleus engram query --context Strategy --limit 10

# Tasks
nucleus task list --status READY
nucleus task add "Ship the feature" --priority 1

# Sessions
nucleus session save "Working on auth refactor"
nucleus session resume

# Health
nucleus status --health
nucleus sovereign

# Compliance
nucleus comply --jurisdiction eu-dora
nucleus audit-report --format html -o report.html

# Chat (multi-provider: Gemini, Anthropic, Groq)
nucleus chat

Pipe-friendly:

nucleus engram search "test" | jq '.key'
nucleus task list --format tsv | cut -f1,3

Compliance

One-command configuration for regulatory frameworks:

nucleus comply --jurisdiction eu-dora       # EU DORA
nucleus comply --jurisdiction sg-mas-trm    # Singapore MAS TRM
nucleus comply --jurisdiction us-soc2       # US SOC2

Telemetry

Nucleus collects anonymous, aggregate usage statistics (command name, duration, error type, versions, OS). No engram content, no file paths, no prompts, no API keys, no PII — ever.

nucleus config --no-telemetry
# or: NUCLEUS_ANON_TELEMETRY=false

See TELEMETRY.md for details.

Contributing

• Bug? Open an Issue
• Feature idea? Start a Discussion
• Code? See CONTRIBUTING.md
• Chat? Discord

License

MIT © 2026 | hello@nucleusos.dev