Nucleus MCP Server

🧠 Nucleus — Sovereign Agent OS

⚠️ official repository → nucleus-mcp

The sovereign, local-first Agent Operating System — persistent memory, governance, compliance, and audit trails for any AI agent.

🌐 **Website** • 🏦 **Live KYC Demo** • 🛠 **170+ Tool Catalog** • 💬 **Discord**

[!CAUTION] Agent security is no longer optional. Recent incidents across the ecosystem — leaked API keys, supply-chain attacks, unaudited tool execution — prove that ungoverned agents are a liability. Nucleus is built security-first: hypervisor controls, resource locking, compliance governance, and full audit trails — all 100% local.

🎯 The Problem

AI agents are powerful, but ungoverned:

• No memory — every session starts from zero
• No audit trail — no one knows why the agent did what it did
• No compliance — regulators can't approve what they can't trace
• No sovereignty — your data flows through someone else's cloud

For regulated industries (banking, healthcare, legal), this is a dealbreaker.

✨ The Solution: Sovereign Agent OS

Nucleus gives every AI agent a persistent brain with built-in governance:

┌─────────────────────────────────────────────────┐
│  🧠 Nucleus — Sovereign Agent OS                │
│                                                 │
│  ┌─ Memory ──┐  ┌─ Governance ┐  ┌─ DSoR ────┐ │
│  │ Engrams   │  │ HITL        │  │ Decision  │ │
│  │ Sessions  │  │ Kill Switch │  │ Trail     │ │
│  │ Context   │  │ Compliance  │  │ Audit     │ │
│  └───────────┘  └─────────────┘  └───────────┘ │
│                                                 │
│  100% Local  •  Zero Cloud  •  Full Audit Trail │
└─────────────────────────────────────────────────┘

🚀 Quick Start (2 Minutes)

Install

pip install nucleus-mcp
nucleus self-setup

Adaptive Path Discovery

Nucleus automatically locates your .brain by following this hierarchy:

1. NUCLEUS_BRAIN_PATH environment variable.
2. Climbing parent directories from CWD to find an existing .brain.
3. Defaulting to $HOME/.nucleus/brain.

Try It

# One-command security hardening + posture report
nucleus secure

# Interactive AI chat (Gemini, Anthropic, Groq — hot-switchable)
nucleus chat

# See your sovereignty posture
nucleus sovereign

# Run a KYC compliance demo
nucleus kyc demo

# Apply EU DORA compliance
nucleus comply --jurisdiction eu-dora

# Generate audit-ready report
nucleus audit-report --format html -o report.html

# Browse decision trails
nucleus trace list

# System Health & Lock Recovery
nucleus status --health
nucleus status --cleanup-lock

🆘 Session Recovery (Universal)

If your IDE session freezes due to bloated conversation files:

# One-shot automatic recovery
nucleus recover auto <conversation-id>

# Or step-by-step:
nucleus recover detect                      # Find bloated conversations
nucleus recover extract <conversation-id>   # Extract context
nucleus recover bootstrap <conversation-id> # Create fresh session
nucleus recover rewrite <old-id> <new-id>   # Update test paths

Works across any IDE (Windsurf, Cursor, Antigravity) and CLI. Zero configuration required.

Configure (Claude Desktop / Cursor / Windsurf)

Add to your MCP config:

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

🗝️ Agent CLI — v1.6.2

Nucleus speaks MCP + CLI + SDK. Every command auto-detects TTY (table) vs pipe (JSON).

# Memory
nucleus engram search "compliance"                    # Table in terminal, JSONL when piped
nucleus engram write my_key "important insight" --context Strategy --intensity 8
nucleus engram query --context Decision --limit 10

# Tasks
nucleus task list --status READY --format json        # Force JSON output
nucleus task add "Ship v1.4.0 CLI" --priority 1
nucleus task update task-abc123 --status DONE

# Sessions
nucleus session save "Working on CLI implementation"
nucleus session resume                                # Most recent session

# Growth
nucleus growth pulse                                  # GitHub stars +