Nucleus Sovereign OS

🧠 Nucleus Sovereign OS

The Operating System for AI Agents — Persistent Operational Memory, Swarm Orchestration, and Local-First Sovereignty.

Nucleus is the Recursive Aggregator that gives your AI agents a persistent brain (.brain/) and a file system. It turns stateless chatbots into stateful Sovereign Agents.

Context vs. Control

Claude's CLAUDE.md provides static context. Nucleus provides active control.

✨ Governance Features (The Moat)

• Default Deny Security — All mounted servers start with NO network/filesystem access.
• Explicit Consent — You approve every command. No silent execution.
• Isolation Boundaries — Tools cannot see each other or the full chat history.
• Auth Firewall — Tokens are stored in Nucleus (Host), never passed to agents.
• Event Ledger — Immutable audit trail of every agent decision (DecisionMade).
• Decision Provenance — v0.6.0 DSoR: Full audit trail with context hashing.
• IPC Security — Per-request auth tokens prevent socket impersonation (CVE-2026-001).
• 135 Native Tools — For orchestration, swarms, memory, and DSoR inspection.

🚀 Quick Start (2 Minutes)

1. Install

pip install mcp-server-nucleus

2. Initialize (Smart Config)

The nucleus-init command automatically detects your system and configures Claude Desktop for you.

# Create your .brain/ and auto-configure Claude Desktop
nucleus-init

3. Ask Claude

Restart Claude Desktop and try:

"Use the cold_start prompt from nucleus to see our current sprint focus."

v0.2.2+: Smart Init automatically detects Claude Desktop and adds the config for you!

Configuration (Claude Desktop)

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

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

Restart Claude Desktop and try: "What's my current sprint focus?"

Configuration (Windsurf)

Add to ~/.codeium/windsurf/mcp_config.json:

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

Configuration (Cursor)

Add to ~/.cursor/mcp.json:

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

❓ Troubleshooting

"Show me all tasks" returns nothing? Check your config pointer! You might be pointing to an old or temp brain.

1. Check config: Open ~/Library/Application Support/Claude/claude_desktop_config.json
2. Verify path: Ensure NUCLEAR_BRAIN_PATH points to your active project (e.g., /Users/me/my-project/.brain)
3. Restart: You MUST restart Claude Desktop after any config change.

🛠 Tool Categories (110+ Total)

🎯 Core Orchestration

📋 Task Management

🐝 Swarm Coordination

💾 Session & Memory

📊 Monitoring & Audit

V2 Task Schema (11 fields):

{
  "id": "task-abc123",
  "description": "Build landing page",
  "status": "PENDING | READY | IN_PROGRESS | BLOCKED | DONE | FAILED | ESCALATED",
  "priority": 1,
  "blocked_by": ["task-prerequisite"],
  "required_skills": ["python", "frontend"],
  "claimed_by": "agent-thread-id",
  "source": "user | synthesizer",
  "escalation_reason": null,
  "created_at": "2026-01-03T12:00:00",
  "updated_at": "2026-01-03T12:00:00"
}

📡 MCP Resources

💬 MCP Prompts

🎯 Common Use Cases

1. Run a Sprint

> "What's my current sprint focus?"
> "Add a task: Build landing page with priority 1"
> "Show me all priority 1 tasks"

2. Coordinate Multiple Agents

> "Claim the next Python task for me"
> "Mark task-abc123 as DONE"
> "List all tasks claimed by agent-1"

3. Escalate When Stuck

> "Escalate task-xyz with reason: Need human approval on pricing"

The task is released and flagged for human intervention.

4. Check Agent Context

> "Use the cold_start prompt from nucleus"

Instantly loads sprint, events, and artifacts.

🚀 Cold Start (New in v0.2.4)

Start every new session with full context:

> Use the cold_start prompt from nucleus

Or click brain://context in Claude Desktop's sidebar.

What you get:

• Current sprint name, focus, and status
• Recent events and artifacts
• Workflow detection (e.g., lead_agent_model.md)
• Lead Agent role assignment

📁 Expected .brain/ Structure

.brain/
├── ledger/
│   ├── events.jsonl
│   ├── state.json
│   └── triggers.json
├── artifacts/
│   ├── research/
│   ├── strategy/
│   └── ...
└── memory/      # Engram storage (Memory)
    └── *.md

⚠️ Known Limitations

• IDE context is separate: Each MCP client (Claude Desktop, Cursor, Windsurf) connects to the same .brain/ directory and shares project state. However, IDE-specific context (Cursor's codebase memory, Antigravity's conversation artifacts, etc.) remains separate per editor.
• No cross-editor sync: Artifacts created in one IDE's conversation don't automatically sync to another. Manual copy is required for important documents.
• Python 3.10+ required: Won't work with older Python versions.

🚀 What's New in v0.5.1

• 130 MCP Tools (up from 110 in v0.5.0)
• Engram Ledger — Persistent cognitive memory (brain_write_engram, brain_query_engrams)
• Governance Dashboard — brain_governance_status() for security monitoring
• Cryptographic Audit — SHA-256 hashed interaction log (brain_audit_log)
• V3.1 Task Engine with slot pooling and tier routing
• Swarm Orchestration for recursive multi-agent missions
• Session Persistence across conversations
• Health Monitoring endpoints for production use
• E2E Test Suite — 18/18 critical path tests passing

The Governance Moat (v0.5.1)

📜 License

MIT © Nucleus Team

Built for the AI-native developer. Star us on GitHub if Nucleus saves you from context amnesia! ⭐