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

But they don't share memory. (Until now).

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

| Feature | Other Solutions | Nucleus | |---------|-----------------|---------| | Cross-Platform Sync | Single platform only | ✅ Syncs ALL your AI tools | | Sovereignty | Cloud-dependent | ✅ 100% local, your data stays on your machine | | Protocol | Proprietary | ✅ MCP standard (Anthropic-backed) | | Security | Often misconfigured | ✅ Secure by default, audit logs included | | Lock-in | Platform-specific | ✅ MIT license, open standard |

⚡ Quick Start (2 Minutes)

1. Install

pip install nucleus-mcp

2. Initialize

nucleus-init --scan

This creates your .brain/ folder, auto-configures Claude Desktop, and automatically ingests your README.md to seed the brain with initial context.

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

ChatGPT (Web)

1. Go to Settings → Apps → Advanced → Developer Mode.
2. Run the Nucleus SSE Bridge: python scripts/sse_bridge.py.
3. Add http://localhost:8000/sse as your MCP endpoint.

See the Community FAQ for more details.

🛠 Core Tools

Memory

| Tool | Description | |------|-------------| | brain_write_engram | Store persistent knowledge | | brain_query_engrams | Retrieve knowledge | | brain_audit_log | View decision history |

Sync (Multi-Agent)

| Tool | Description | |------|-------------| | brain_sync_now | Manually trigger brain sync | | brain_sync_status | Check sync state and conflicts | | brain_sync_auto | Enable/disable auto-sync | | brain_identify_agent | Register agent identity |

State Management

| Tool | Description | |------|-------------| | brain_get_state | Get current project state | | brain_set_state | Update project state | | brain_list_artifacts | List all artifacts |

Hypervisor (Security)

| Tool | Description | |------|-------------| | lock_resource | Lock file/folder (immutable) | | unlock_resource | Unlock resource | | watch_resource | Monitor file changes | | hypervisor_status | View security state |

🔄 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 | Claude Code | Nucleus | |---|----------|-------------|---------| | What it syncs | OpenClaw → OpenClaw | Claude → Claude | Everything ↔ Everything | | Cross-platform | ❌ | ❌ | ✅ | | Local-first | ⚠️ Some cloud | ⚠️ Some cloud | ✅ 100% local | | MCP Native | ❌ Custom protocol | ⚠️ Limited | ✅ Full MCP | | Open Source | ✅ MIT | ❌ Closed | ✅ MIT |

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.