🧠 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.

✨ Core Features (Included)

• Persistent Memory — brain_write_engram / brain_query_engrams (Vector-lite).
• Audit Ledger — Immutable SHA-256 logs of every action (brain_audit_log).
• Recursive Mounting — brain_mount_server (Basic).
• Local Sovereignty — Zero cloud. All data in ~/.nucleus/brain.

🔐 Sovereign Edition (Closed Beta)

The "Dark Wheel" is reserved for active builders.

Early Access Program The Sovereign Edition (Task Engine, Swarm, Federation) is currently invite-only to ensure stability. To join the cohort:

1. Install Core (PyPI).
2. DM u/NucleusOS on Reddit for an invite code.

Unlockable Features:

• Task Engine — brain_add_task, brain_claim_task.
• Swarm Orchestration — brain_orchestrate_swarm.
• Session Persistence — brain_save_session.
• Federation — Peer-to-Peer Agent Mesh.

🚀 Quick Start (Core)

1. Install

pip install mcp-server-nucleus

2. Initialize

nucleus-init

3. Use the Memory

Restart Claude and try:

"Write an engram: 'The project goal is World Domination'. Then audit the ledger."

🛠 Tool Categories

🧠 Core (Public)

🔒 Sovereign (Beta Key Required)

�️ Community & Feedback

We represent the Sovereign Web. We build in the open, but we protect the signal.

• 🐛 Found a bug? Open an Issue on GitHub.
• 💡 Have an idea? Discuss it on GitHub Discussions.
• 🗝️ Want to join the Inner Circle? Check the Early Access Program above.

�📜 License

MIT © Nucleus Team

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