Skip to content
MCP server

Nucleus

Shared local decision log and persistent memory for Claude Code, Cursor and Codex

Install
Pricing
Open source
Platforms
CLI, self-hosted, Linux
Runs
Locally or Remotely
Version
1.17.1
Listing updated
3 days ago

About Nucleus

Nucleus is an open-source MCP server for knowledge and memory. It can run locally on your machine or as a hosted remote server.

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.

Install

Run in a terminal

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

Add to Settings → Connectors → Add custom connector

https://relay.nucleusos.dev/mcp
Install in CursorOpens Cursor, which asks you to confirm. Or add it by hand:

Add to ~/.cursor/mcp.json

{
  "mcpServers": {
    "nucleus": {
      "url": "https://relay.nucleusos.dev/mcp"
    }
  }
}
Install in VS CodeOpens VS Code, which asks you to confirm. Or add it by hand:

Add to .vscode/mcp.json

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

Add to ~/.codeium/windsurf/mcp_config.json

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

Add to your client's MCP settings (most use this shape)

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

Configuration

  • NUCLEUS_BRAIN_PATHPath to .brain/ directory (defaults to .brain in current directory)

What it does

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

Pricing

Open source

MIT licensed; free local install

Prices change. Check nucleusos.dev before you buy.

Nucleus 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 to Nucleus

  1. REA

    MCP server

    CLI and MCP server that lets coding agents reverse engineer apps and binaries

    Runs locally
    • Open source
    • 464K GitHub stars
    • Developer tools
  2. Codebase Memory

    MCP server

    Local MCP server that builds a code knowledge graph for AI coding agents

    Runs locally
    • Open source
    • 48.7K GitHub stars
    • Knowledge and memory
  3. GitHub

    MCP server

    Official MCP server connecting AI assistants to GitHub repos, issues and workflows

    Not checked yet
    • Remote
    • Open source
    • 34.5K GitHub stars
    • Developer tools
  4. MCP toolkit giving coding agents symbol-level code retrieval and editing

    Runs locally
    • Open source
    • 31.5K GitHub stars
    • Developer tools
  5. XERJ

    MCP server

    Local search engine for AI agents with cited answers over your code and docs

    Runs locally
    • Open source
    • 19.2K GitHub stars
    • Knowledge and memory
  6. Ouroboros

    MCP server

    Spec-first layer that pins requirements and verifies results of AI coding agent work

    Runs locally
    • Open source
    • 6.4K GitHub stars
    • Developer tools