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

<!-- Demo video: https://github.com/eidetic-works/nucleus-mcp/releases - see demo_video.mp4 -->

---

🚀 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
Security	❌ Sleeper agents, key leaks	⚠️ Cloud-managed	✅ Hypervisor + audit trail
Cross-platform	❌	❌	✅
Local-first	⚠️ Some cloud	⚠️ Some cloud	✅ 100% local

OpenClaw trades security for capability. Nucleus gives you both. 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.