🧠 Nucleus MCP

🧠 Nucleus MCP

The Universal Brain for AI Agents — One brain that syncs Cursor, Claude Desktop, Windsurf, and any MCP-compatible tool.

🎯 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 constantly.

✨ 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

⚡ Quick Start (2 Minutes)

1. Install

pip install nucleus-mcp

2. Initialize

nucleus-init

This creates your .brain/ folder and auto-configures Claude Desktop.

3. Restart Claude Desktop

Then try:

"What decisions have we made about the architecture?"

Claude will now remember across sessions!

🔧 Manual Configuration

Claude Desktop

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

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

Cursor

Add to ~/.cursor/mcp.json:

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

Windsurf

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

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

🛠 Core Tools

Memory

Sync (Multi-Agent)

State Management

Hypervisor (Security)

🔄 Multi-Agent Sync (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

⚔️ Comparison: Nucleus vs Alternatives

OpenClaw is great for multi-agent teams on their platform.Nucleus connects ALL your platforms with one brain.

📁 The .brain/ Folder

Nucleus stores everything in a .brain/ folder in your project:

.brain/
├── config/
│   └── nucleus.yaml      # Configuration
├── ledger/
│   ├── state.json        # Current state
│   ├── events.jsonl      # Audit log
│   └── decisions.md      # Decision history
├── artifacts/
│   └── ...               # Your stored knowledge
└── sessions/
    └── ...               # Saved sessions

Your data. Your machine. Your control.

🤝 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

✨ Contributors

A huge thank you to the pioneers helping build the universal brain:

• @aryasadawrate19 — Added Linux XDG support for nucleus-init.

Development Setup

git clone https://github.com/eidetic-works/nucleus-mcp.git
cd nucleus-mcp
python3 -m venv venv
source venv/bin/activate
pip install -e ".[dev]"
pytest tests/

📜 License

MIT © Nucleus Team

⭐ Support

Star us on GitHub if Nucleus saves you from context amnesia!

One brain. All your AI tools. No more repeating yourself.

Built for the AI-native developer.