Nucleus

Nucleus MCP provides a local, cross-tool brain that synchronizes memory and decisions across your AI tools. With a single MCP server running on your machine, you can share decisions, plans, and context between tools like Claude Desktop, Cursor, Windsurf, and other MCP-compatible agents, eliminating constant re-explanation and maintaining continuity across sessions.

How to use

You run a local MCP server and connect your AI tools to it. Each tool stores decisions, plans, and memories in the shared brain, so when you switch tools you can pick up where you left off. Use the standard configuration to link each client to the local server, and let the server manage synchronization, audit trails, and access control.

How to install

pip install nucleus-mcp

nucleus-init --scan

This will create your .brain/ folder, auto-configure supported tools, and seed the brain with initial context by ingesting relevant project data. After installation, restart any connected tools to enable cross-tool memory sharing.

## Configuration and usage notes

Configure each MCP client to point at the local MCP server so they can share memory and decisions. You will typically specify the server command and environment path to your brain.

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

## Security and data locality

All brain data remains on your local machine. The server operates with 100% local data and includes audit logging to track decisions and synchronization actions.

## Notes on usage across clients

- Use the brain to seed initial context by providing core decisions and plans from your projects. - Enable auto-sync to keep all clients up to date in real time. - Review the audit trail to trace decisions and resolve conflicts when necessary.

## The .brain directory

Nucleus stores all data under a .brain/ folder in your project. This directory contains configuration, state, artifacts, and session data to support cross-tool memory.

## Troubleshooting

If a tool cannot connect to the local MCP server, verify that the server process is running and that the path to the brain directory is correct. Check for permission issues and ensure the environment variable NUCLEAR\_BRAIN\_PATH points to the right location.

## Available tools

### brain\_write\_engram

Store persistent knowledge in the brain for long-term memory.

### brain\_query\_engrams

Retrieve stored memories and insights from the brain.

### brain\_audit\_log

View the decision and synchronization history.

### brain\_sync\_now

Manually trigger brain synchronization across agents.

### brain\_sync\_status

Check current sync state and identify conflicts.

### brain\_sync\_auto

Enable or disable automatic real-time synchronization.

### brain\_identify\_agent

Register an agent identity with the brain.

### brain\_get\_state

Retrieve the current project state from the brain.

### brain\_set\_state

Update the project state in the brain.

### brain\_list\_artifacts

List all stored artifacts in the brain.

### lock\_resource

Lock a file or folder to prevent concurrent edits.

### unlock\_resource

Unlock a previously locked resource.

### watch\_resource

Monitor file changes for security and synchronization.

### hypervisor\_status

View the current security/hypervisor state.