nucleus-mcp 1.8.8

Sovereign Agent OS — Persistent Memory, Governance & Compliance for AI Agents

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 14 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

	Free	Pro
114 MCP tools	Yes	Yes
Persistent memory	Yes	Yes
Governance & HITL	Yes	Yes
Audit trails (DSoR)	Yes	Yes
Signed audit reports	-	Ed25519
Compliance exports	Score only	Full PDF/HTML
Priority issues	-	Yes

---

Install

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"]
    }
  }
}

Alternative: use pip install directly

{
  "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

Jurisdiction	Retention	HITL Ops	Kill Switch
eu-dora	7 years	5 types	Required
sg-mas-trm	5 years	5 types	Required
us-soc2	1 year	3 types	Optional
global-default	90 days	2 types	Optional

---

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 | [e-mail]