🧠 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

🎯 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 (BFSI, 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 (15-minute BFSI 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 + PyPI + compound
nucleus growth status                                 # Metrics without side effects

# Outbound I/O
nucleus outbound check reddit r/ClaudeAI              # Idempotency gate
nucleus outbound record reddit r/ClaudeAI --permalink https://reddit.com/abc
nucleus outbound plan                                 # What's ready vs posted

# Pipe-friendly (Unix composable)
nucleus engram search "test" | jq '.key'
nucleus task list --format tsv | cut -f1,3

Global flags: --format json|table|tsv • --brain-path /path/to/.brain • --version

�🥞 The Layered Open-Core Model

Nucleus is designed for progressive adoption. You can start local and scale up to full institutional compliance seamlessly.

1. Layer 1: Sovereign Core (OSS): 100% local, persistent engrams, session state, and essential file governance.

2. Layer 2: CLI-First Tooling: morning-brief, end-of-day, and the dogfood tracker for compounding intelligence.

3. Layer 3: Deployment Kit: 1-command jurisdiction deployments (nucleus deploy --jurisdiction eu-dora).

4. Layer 4: Institutional Compliance: DSoR Trace Viewer, Audit Report HTML exports (DORA/MAS TRM), and strict HITL gates.

🏛️ Why Nucleus for Regulated Industries

Jurisdiction-Aware Compliance

One command to configure for any regulatory framework:

nucleus comply --jurisdiction eu-dora       # EU DORA (7yr retention, kill switch)
nucleus comply --jurisdiction sg-mas-trm    # Singapore MAS TRM (5yr, strictest HITL)
nucleus comply --jurisdiction us-soc2       # US SOC2 (1yr retention)
nucleus comply --report                     # Check compliance status

KYC Compliance Demo

Built-in demo workflow showing how Nucleus governs a KYC document review:

nucleus kyc review APP-001  # Low risk → ✅ APPROVE
nucleus kyc review APP-002  # Medium risk → ⚠️ ESCALATE (PEP match)
nucleus kyc review APP-003  # High risk → ❌ REJECT (sanctions)
nucleus kyc demo            # Run all 3 in sequence

Each review generates:

• 5 automated checks (sanctions, PEP, document validity, risk factors, source of funds)

• Full decision trail stored as DSoR (Decision System of Record) trace

• HITL approval request for risky applications

• Sovereignty guarantee: all processing is local

Audit Reports

Generate audit-ready reports for regulators:

nucleus audit-report                              # Terminal text
nucleus audit-report --format json                # JSON for APIs
nucleus audit-report --format html -o report.html # HTML for compliance officers

Sovereignty Status

See your full sovereignty posture:

nucleus sovereign

Shows: sovereignty score (0-100), memory health, governance posture, DSoR integrity, data residency guarantee.

🛠 Full Feature Set

Core — Persistent Agent Memory

Governance — Agent Controls

Interactive — AI Chat

Orchestration — Multi-Agent Coordination

⚡ Comparison

🐳 Deployment

Docker (per jurisdiction)

# EU DORA deployment
docker compose -f deploy/docker-compose.eu-dora.yml up -d

# Or use the one-command deployment script
./deploy/deploy.sh eu-dora

Local

pip install nucleus-mcp
nucleus init
nucleus comply --jurisdiction eu-dora
nucleus sovereign  # Verify

🔭 Anonymous Telemetry

Nucleus collects anonymous, aggregate usage statistics to improve the product. No personal data, no engram content, no org docs — ever.

⚠️ Note: Anonymous telemetry powers the autonomous incident brain engine (telemetry.nucleusos.dev). Disabling it may degrade or disable autonomy features like policy adaptation, crash-loop detection, and rollout health scoring. Only opt out if you have a fully local telemetry stack.

Opt out in 1 command:

nucleus config --no-telemetry
# or via env:    NUCLEUS_ANON_TELEMETRY=false
# or in config:  telemetry.anonymous.enabled: false

What's collected: command name, duration, error type, Nucleus/Python version, OS platform.
What's NEVER collected: engram content, file paths, prompts, API keys, any PII.

See TELEMETRY.md for full details.

📦 v1.6.2 — Interactive Intelligence

• Multi-Provider Chat — nucleus chat with Gemini, Anthropic, Groq (hot-switchable via /provider)

• Native Tool Calling — Anthropic tool_use API + Groq OpenAI function calling

• Model-Aware Gating — 70b+ models use native tools; 8b models use <execute> tags

• Groq Auto-Rotation — Cascades across models on rate limit (70b → scout → qwen → 8b)

• Session Resume — Chat history auto-loads from disk on startup

• nucleus secure — One-command security hardening + posture report with certificate

• 263 tests passing — Routing fuzzer, session resume, tool pattern detection

📦 v1.6.0 — The Autonomous Incident Brain

• Automated Incident Response, Adaptive Policy Engine, Reliability Policy Surface

• Full-Stack Health Monitoring with crash-loop defense

• Safe Rollouts & Auto-Rollback with health-gated releases

📦 v1.5.0 — The Sovereign Kernel

• Adaptive Path Discovery — Zero-conf brain location (Env > CWD > Home)

• Universal Shell Integration — Integrated bash/zsh completions via self-setup

• Federation Level 1 — Automated local peer discovery via IPC

• DSoR Self-Healing — Automated reconciliation of orphaned decisions in audit logs

• CLI Sovereignty — Unified routing, Python-native bootstrap, and health monitoring

• 80+ tests — All passing (including stale lock recovery and recursion guards)

See CHANGELOG.md for full details.

🤝 Community & Contributing

• 🐛 Found a bug? Open an Issue

• 💡 Feature idea? Start a Discussion

• 🔧 Want to contribute? See CONTRIBUTING.md

• 💬 Join Discord — Join the Nucleus Development Server

📜 License

MIT © 2026 Nucleus Team | hello@nucleusos.dev

Built for the AI-native enterprise. Star us if Nucleus gives your agents a brain — and a conscience. ⭐