GitHub - eidetic-works/nucleus-mcp: The Sovereign Agent Control Plane — One brain for Cursor, Claude, and Windsurf.

🧠 nucleus-mcp

⚠️ official repository → nucleus-mcp

the sovereign agent control plane — one brain that syncs cursor, claude, windsurf, and any mcp-compatible tool.

🚀 live on product hunt: nucleus is the local-first agentic identity & security layer. join the strike →

🚨 v1.0.8 monolith: the "infrastructure" update

immediate value. zero friction.

New in v1.0.8: Monolith Decomposition completed. Core logic migrated to the runtime/ module for modular growth. New in v1.0.7: Nucleus now welcomes you with a Sovereign Brain Card and pre-seeded memories.

• Brain Card: cold_start now returns a rich summary of your memory, active tasks, and connected tools.
• Welcome Engrams: Your brain connects with pre-loaded context, so you never start from zero.
• Smart Config: nucleus-init gives you OS-specific paths (macOS/Windows/Linux) for 1-second setup.

📦 Installation

The clean, open source version of Nucleus is now available at:

→ github.com/eidetic-works/nucleus-mcp

pip install nucleus-mcp
nucleus-init

This repository (mcp-server-nucleus) is the internal development monorepo. For production use, please use the official open source package above.

🎯 the problem

you use multiple ai tools daily:

• cursor for coding
• claude desktop for thinking
• windsurf for exploration
• chatgpt for quick answers

but they don't share memory.

every time you switch tools, you lose context. you re-explain decisions. you repeat yourself.

✨ the solution

nucleus syncs them with one brain.

Tell Claude about a decision → Cursor knows it
Make a plan in Windsurf → Claude remembers it
One brain. All your tools.

🚀 What Makes Nucleus Different? (The Fractal Architecture)

🚀 What Makes Nucleus Different

🛠 140+ MCP Tools Included

• Engrams — Persistent knowledge that survives sessions
• Tasks — Track work across agents
• Sessions — Save and resume context
• Sync — Multi-agent brain synchronization
• Hypervisor — File locking, security, audit trails
• Orchestration — Coordinate multiple agents

⚡ Comparison: Nucleus vs Alternatives

openclaw trades security for capability. nucleus gives you both. nucleus connects ALL your platforms with one shared brain.

🚀 Quick Start (2 Minutes)

1. Install

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

You will see the Sovereign Brain Card: a live dashboard of your engrams, tasks, and connected tools.

v1.0.7+: Smart Init automatically detects your OS and provides the exact config block for your editor.

Configuration (Claude Desktop)

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

{
  "mcpServers": {
    "nucleus": {
      "command": "python3",
      "args": ["-m", "nucleus_mcp"],
      "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", "nucleus_mcp"],
      "env": {
        "NUCLEAR_BRAIN_PATH": "/path/to/your/.brain"
      }
    }
  }
}

Configuration (Cursor)

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "nucleus": {
      "command": "python3",
      "args": ["-m", "nucleus_mcp"],
      "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 Engrams — 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.

🔄 Multi-Agent Sync (New in v0.7.0)

The killer feature: Multiple agents, one brain.

# Agent A (Claude Desktop) makes a decision
brain_sync_now()  # Syncs to shared .brain/

# Agent B (Cursor) automatically sees it
brain_sync_status()  # Shows last sync, active agents

Features:

• Intent-Aware Locking — Files locked with WHO/WHEN/WHY metadata
• Conflict Detection — Last-write-wins with manual resolution option
• Auto-Sync — Optional file watcher for real-time sync
• Audit Trail — Every sync logged to events.jsonl

🛠 Tool Categories

🧠 Core (Public)

🔄 Sync Tools

🔒 Enterprise Features

❓ How is Nucleus Different?

See the full comparison: Nucleus vs ContextStream vs mem0 vs OpenClaw →

🤝 Community & Contributing

We're building the universal brain for AI agents. Join us!

• 🐛 Found a bug? Open an Issue
• 💡 Feature idea? Start a Discussion
• 🔧 Want to contribute? See CONTRIBUTING.md
• 💬 Join Discord — discord.gg/nucleus (coming soon)

�📜 License

MIT © Nucleus Team

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