# Nucleus

> Nucleus is an open-source MCP server for knowledge and memory. Shared local decision log and persistent memory for Claude Code, Cursor and Codex. It can run locally on your machine or as a hosted remote server.

- **Kind:** MCP server
- **Pricing:** Open source
- **Platforms:** CLI, self-hosted, Linux, macOS, Windows
- **Website:** https://nucleusos.dev
- **Repository:** https://github.com/eidetic-works/nucleus-mcp
- **MCP Registry name:** io.github.eidetic-works/nucleus
- **Categories:** knowledge and memory, developer tools
- **Listing updated:** 2026-11-14

## About

Everything lives in a .brain folder inside your repo, as plain JSON and markdown with no embeddings, so each AI tool starts a session already knowing past decisions, policies and plans. It is MIT licensed and installs from PyPI with nucleus init, which seeds the folder, writes a project .mcp.json and offers to configure the clients it finds. The README says hosted access is currently unavailable, so use the local install.

The README organises it around three loops. GROUND verifies AI-written code in five tiers: diff, syntax, imports, tests and runtime. ALIGN records your correction as a verdict against a prior decision, which becomes a training pair and an event. COMPOUND measures the gap between intent and reality so recurring patterns can become strategy. Tool responses carry a frontier health line.

The README counts 30 tools across 16 facades exposing 210 actions, plus 19 brain:// resources and 8 prompts. A second tool, nucleus-rabbithole, tracks depth and context-switching for developers who lose focus, backed by local SQLite.

## Features

- **Portable .brain folder:** Keeps decisions, policies and plans in plain files in your repo.
- **Cross-tool memory:** One MCP server serves Claude Code, Cursor and Codex.
- **Execution verification:** Checks AI output through diff, syntax, imports, tests and runtime.
- **One-call corrections:** Records a verdict, delta, training pair and event together.
- **Rabbit-hole tracker:** Includes a depth stack and context-switch detector in local SQLite.
- **Guided setup:** nucleus init configures installed AI clients.

## Good for

- Stop re-explaining project decisions at each session start
- Share the same context across Cursor and Claude Code
- Verify that AI-written code actually imports and passes tests
- Record corrections as training pairs
- Track context switches during deep work

## Install

### Claude Code (Terminal)

```sh
claude mcp add --transport http nucleus https://relay.nucleusos.dev/mcp
```

### Claude Desktop (Settings → Connectors → Add custom connector)

```sh
https://relay.nucleusos.dev/mcp
```

### Cursor (~/.cursor/mcp.json)

```json
{
  "mcpServers": {
    "nucleus": {
      "url": "https://relay.nucleusos.dev/mcp"
    }
  }
}
```

### VS Code (.vscode/mcp.json)

```json
{
  "servers": {
    "nucleus": {
      "type": "http",
      "url": "https://relay.nucleusos.dev/mcp"
    }
  }
}
```

### Windsurf (~/.codeium/windsurf/mcp_config.json)

```json
{
  "mcpServers": {
    "nucleus": {
      "serverUrl": "https://relay.nucleusos.dev/mcp"
    }
  }
}
```

### Other clients (your client's MCP settings (most use this shape))

```json
{
  "mcpServers": {
    "nucleus": {
      "type": "http",
      "url": "https://relay.nucleusos.dev/mcp"
    }
  }
}
```

## FAQ

### Where is data stored?

In a .brain folder in your repo as JSON and markdown files.

### Is there a hosted version?

The README says hosted access is not currently available.

### What licence is it?

MIT.

### How do I install it?

pip install nucleus-mcp, then nucleus init.

### Is Nucleus free?

Yes. Nucleus is open source, so you can use and self-host it for free.

### How do I add Nucleus to Claude Code?

Run this command in your terminal: claude mcp add --transport http nucleus https://relay.nucleusos.dev/mcp

### What are the best alternatives to Nucleus?

The closest alternatives to Nucleus are REA, Codebase Memory, GitHub, Serena MCP: the IDE for your agent and XERJ.

## Alternatives

- [REA](https://ai-powered.com/mcp/rea): REA is an open-source MCP server for developer tools.
- [Codebase Memory](https://ai-powered.com/mcp/codebase-memory): Codebase Memory is an open-source MCP server for knowledge and memory.
- [GitHub](https://ai-powered.com/mcp/github-2): GitHub is an open-source MCP server for developer tools.
- [Serena MCP: the IDE for your agent](https://ai-powered.com/mcp/serena-mcp-the-ide-for-your-agent): Serena MCP: the IDE for your agent is an open-source MCP server for developer tools.
- [XERJ](https://ai-powered.com/mcp/xerj): XERJ is an open-source MCP server for knowledge and memory.
- [Ouroboros](https://ai-powered.com/mcp/ouroboros): Ouroboros is an open-source MCP server for developer tools.
- [Claude Code Ultimate Guide](https://ai-powered.com/mcp/claude-code-ultimate-guide): Claude Code Ultimate Guide is an open-source MCP server for ai models and llm tooling.
- [Nautilus Compass Memory](https://ai-powered.com/mcp/nautilus-compass-memory): Nautilus Compass Memory is an open-source MCP server for knowledge and memory.

---
Source: https://ai-powered.com/mcp/nucleus
