# nucleus

Maintains agent decisions and project context inside a local .brain folder. It links memory across coding editors without vector databases.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 5
- Author: eidetic-works
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/eidetic-works/nucleus-mcp
- Updated: 2026-10-02
- HTML: https://affpapa.org/en/nevibecode/mcp/nucleus

## What it does

Nucleus stores project policies and architecture decisions inside plain markdown and JSON files within a repository directory named `.brain`. Agents read this directory through MCP tools. This avoids re-explaining previous technical trade-offs at the start of every session.

The package bundles 30 tools and a local utility called `nucleus-rabbithole` that tracks task focus using SQLite without background daemons. Its verification loops handle syntax, tests, and human feedback to capture deltas between intent and actual output.

You need Python 3.10 or newer. Python versions 3.11 through 3.13 install clean binary wheels, whereas 3.14 compiles dependencies like `watchdog` from source. The remote endpoint remains offline pending review. When running `nucleus build`, an authenticated `claude`, `devin`, or `agy` CLI binary must exist on `PATH`, or the process stops at the planning step.

## Requirements
- Needs: Python and uv (commands run via uvx)
- Remote server: `https://relay.nucleusos.dev/mcp`
- Environment variables: `NUCLEUS_BRAIN_PATH` — keys and tokens: ask the human for the values, never commit them or put them in shared files.

## Install

### Claude Code (native platform)

1. **Platform CLI: remote server**
```bash
claude mcp add --transport http nucleus https://relay.nucleusos.dev/mcp
```

2. **Platform CLI**
```bash
claude mcp add --env NUCLEUS_BRAIN_PATH=<NUCLEUS_BRAIN_PATH> --transport stdio nucleus -- uvx nucleus-mcp
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from nucleus-mcp <command>

### Codex

1. **Platform CLI: remote server**
```bash
codex mcp add nucleus --url https://relay.nucleusos.dev/mcp
```

2. **Platform CLI**
```bash
codex mcp add nucleus --env NUCLEUS_BRAIN_PATH=<NUCLEUS_BRAIN_PATH> -- uvx nucleus-mcp
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from nucleus-mcp <command>

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "nucleus": {
            "url": "https://relay.nucleusos.dev/mcp"
        }
    }
}
```
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "nucleus": {
            "command": "uvx",
            "args": [
                "nucleus-mcp"
            ],
            "env": {
                "NUCLEUS_BRAIN_PATH": "<NUCLEUS_BRAIN_PATH>"
            }
        }
    }
}
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from nucleus-mcp <command>

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "nucleus": {
            "type": "http",
            "url": "https://relay.nucleusos.dev/mcp"
        }
    }
}
```
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "nucleus": {
            "type": "stdio",
            "command": "uvx",
            "args": [
                "nucleus-mcp"
            ],
            "env": {
                "NUCLEUS_BRAIN_PATH": "<NUCLEUS_BRAIN_PATH>"
            }
        }
    }
}
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from nucleus-mcp <command>

### Gemini CLI

1. **Platform CLI: remote server**
```bash
gemini mcp add -t http nucleus https://relay.nucleusos.dev/mcp
```

2. **Platform CLI**
```bash
gemini mcp add -e NUCLEUS_BRAIN_PATH=<NUCLEUS_BRAIN_PATH> nucleus uvx nucleus-mcp
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from nucleus-mcp <command>

## When to use it
- retain architectural decisions across multiple coding sessions
- verify AI code output against syntax and runtime checks
- prevent context loss when switching between different IDEs
- track subtask rabbit holes with a local push-down stack

## Example prompts
- Record the new database migration policy into the `.brain` log
- Run `nucleus review` on the latest changes to capture our verdict
- Check subtask depth using `nucleus-rabbithole`

## Similar
- [REA](https://affpapa.org/en/nevibecode/mcp/rea.md) — MCP server · ★ 392262
- [GitHub](https://affpapa.org/en/nevibecode/mcp/github.md) — MCP server · ★ 33989
- [Netdata](https://affpapa.org/en/nevibecode/mcp/netdata.md) — MCP server · ★ 81163
- [browser-use](https://affpapa.org/en/nevibecode/mcp/browser-use.md) — MCP server · ★ 119231
- [Codebase Memory](https://affpapa.org/en/nevibecode/mcp/codebase-memory.md) — MCP server · ★ 47577
- [mcp-server](https://affpapa.org/en/nevibecode/mcp/mcp-server.md) — MCP server · ★ 43902

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md