Nucleus

.brain — the portable decision log

The portable decision log your AI tools all read. One MCP server. Any AI tool. Plain files.

Every AI coding session starts by re-explaining context the last session already knew. .brain is a folder in your repo that Claude Code, Cursor, and Codex all read via one MCP server. Decisions, policies, plans — written once, remembered across every session and every tool.

MIT licensed. File-based (plain JSON + markdown). No embeddings. No vendor lock-in.

---

Also included: nucleus-rabbithole

nucleus-mcp ships a second, fully independent tool: nucleus-rabbithole, a rabbit-hole depth tracker for focus-prone developers.

It gives your AI a push/pop depth stack, a context-switch thrash detector, an open-loop externaliser, and a weekly review — all backed by local SQLite, no network, no daemon.

# Already installed with nucleus-mcp — just run:

nucleus-rabbithole

Claude Code .mcp.json snippet:

{

"mcpServers": { "nucleus-rabbithole": { "command": "nucleus-rabbithole", "args": [] } } }

Full documentation: docs/RABBITHOLE.md — also installed with the package, at /mcp_server_nucleus/docs/RABBITHOLE.md.

---

Three Frontiers

The core loop that makes AI reliability compound over time:

  GROUND              ALIGN               COMPOUND

────── ───── ──────── Machine verifies Human corrects System learns

AI writes code → You fix a mistake → Delta recorded GROUND checks → Verdict stored → DPO pair created Receipt logged → Event emitted → Training data grows │ │ │ └───────────────────┴────────────────────┘ Reliability improves

GROUND — 5-tier execution verification. Syntax, imports, tests, runtime. Goes outside the formal system to check the AI's work.

ALIGN — One-call corrections. nucleus review records a verdict against a prior decision, which becomes a training pair and an event.

COMPOUND — Deltas measure the gap between intent and reality. Recurring patterns become strategy. Negative deltas become training signal.

Every tool response shows frontier health:

[frontiers: GROUND 42 | ALIGN 12 | COMPOUND 28]

---

Quick Start

Hosted access is not currently available. The remote MCP endpoint is withdrawn pending an access-control review. Use the local install below.

Local install (Cursor, Windsurf, Claude Desktop):

pip install nucleus-mcp

nucleus init --recipe founder

Two commands. Nucleus is running. nucleus init seeds .brain/, writes a project-local .mcp.json, and offers to configure every AI client you have installed. Say yes, then restart the client.

nucleus build additionally needs a coding-agent CLI on PATH — any one of claude (npm i -g @anthropic-ai/claude-code), devin, or agy, already authenticated (claude/devin/agy login once, separately). Without one, build stops at the plan stage. If build reports status='error' without a clear cause, the vendor CLI's own error (e.g. an expired login) lands in .brain/relay/cross_vendor/*.json — check the newest file there.

---

What It Does

30 MCP tools across 16 facades, exposing 210 actions, plus 19 brain:// resources and 8 prompts. Regenerate these with python3 tools_audit/count_surface.py rather than editing them by hand — three hand-maintained copies of this number had drifted apart before that script existed.

• GROUND — Execution verification (5 tiers: diff, syntax, imports, tests, runtime)
• ALIGN — Human corrections (verdict + delta + DPO + event in one call)
• Memory — Engrams that persist across sessions. Write once, recall forever.
• Sessions — Save context, resume later. Session arc shows your last 3 sessions.
• Tasks — Priority queue with escalation, HITL gates, and heartbeat monitoring.
• Governance — Kill switch, compliance configs (EU DORA, MAS TRM, SOC2), audit trails.
• Orchestration — Agent slots, multi-brain sync, task dispatch.
• Archive — Training pipeline (SFT + DPO), delta tracking, frontier health dashboard.

Benchmark: decision-retention-evals — does your AI agent remember why the code is the way it is? (ask on Discord for the current mirror)

---

Nucleus Pro

Everything above is free (MIT). Nucleus Pro adds verifiable governance:

nucleus trial                              # 14-day free trial

nucleus compliance-check # Score your AI governance nucleus audit-report --format html -o report.html # Audit report

$19/month or $149/year — nucleusos.dev/pricing

---

Install

pip install nucleus-mcp      # or:  uvx nucleus-mcp  ·  pipx install nucleus-mcp

nucleus init # seeds .brain/, then offers to configure your AI clients

Requires Python ≥3.10; on 3.14 some dependencies (e.g. watchdog) build from source — 3.11–3.13 install wheels cleanly. init writes whichever nucleus binary it resolves first on PATH into the config it generates — with a stale global install alongside a venv, pipx/uvx or which nucleus keeps the right one.

nucleus init always does three things: seeds .brain/, writes a project-local .mcp.json that Claude Code reads in that folder, and runs a memory write-and-recall self-test so you can see it working before you trust it.

In an interactive terminal it then asks whether to configure your other AI clients. Answer yes and it writes the nucleus entry into every one it finds installed — Claude Desktop, Claude Code, Cursor, Windsurf, Antigravity, Devin — backing up each file it touches. It tells you how many it configured, and says so plainly when that number is zero rather than leaving you to wonder.

Run with --no-wizard, or in a script where there is no terminal to ask, and it seeds the brain and the project-local config only. Use nucleus setup for the client configuration in that case.

Then restart your AI client. To verify: your client's tool list now shows nucleus_* tools, or run nucleus doctor.

An existing nucleus entry is never touched unless you pass --force. For most clients a .json.bak copy is written before the edit. Claude Code's ~/.claude.json is handled differently and deliberately: nucleus writes a temp file and swaps it in atomically, so a failed write leaves the original exactly as it was, and no .bak is left lying beside it. A client that is installed but has never had an MCP config gets one created; a client you do not have is left alone entirely, and ~/.claude.json is never invented if it is missing. Already have a .brain? Run nucleus setup to configure clients without re-seeding it, with --dry-run to preview the exact changes first.

Claude Desktop — one-click bundle

A one-click `nucleus.mcpb` bundle for Claude Desktop is built via bash scripts/build_mcpb.sh (it will be attached to releases once the release workflow ships it). Opening the bundle with Claude Desktop uses Claude's built-in uv runtime to fetch and run nucleus-mcp — no Python setup required.

Hosted / no-install access

Currently unavailable. The remote MCP endpoint is withdrawn pending an access-control review; use a local install.

Manual config (fallback)

If a client isn't auto-detected, run nucleus setup --dry-run to print every location nucleus looks in and the exact mcpServers block it would write, then paste that block into your client's config yourself. nucleus setup --create writes a Claude Code config even when nothing is detected. The full manual walkthrough lives in docs/QUICK_START.md, which ships with the package at /mcp_server_nucleus/docs/QUICK_START.md.

Path Discovery

Nucleus finds your .brain automatically:

1. NUCLEUS_BRAIN_PATH environment variable (explicit)
2. Walk up from CWD looking for .brain/ directory
3. Fall back to $HOME/.nucleus/brain

This lookup order applies to the running server. nucleus init instead seeds .brain/ in the directory you run it in (or the path argument) — set NUCLEUS_BRAIN_PATH afterwards if you want the server to find a brain placed somewhere else.

---

CLI

Nucleus has a full CLI alongside the MCP tools. Auto-detects TTY (table output) vs pipe (JSON).

# Memory

nucleus engram write my_key "insight here" --context Decision --intensity 7 nucleus engram search "compliance" nucleus engram query --context Strategy --limit 10

Tasks

nucleus task list --status READY nucleus task add "Ship the feature" --priority 1

Sessions

nucleus session save "Working on auth refactor" nucleus session resume

Health

nucleus status --health nucleus sovereign

Compliance

nucleus comply --jurisdiction eu-dora nucleus audit-report --format html -o report.html

Chat (multi-provider: Gemini, Anthropic, Groq)

nucleus chat

Pipe-friendly:

nucleus engram search "test" | jq '.key'

nucleus task list --format tsv | cut -f1,3

---

Compliance

One-command configuration for regulatory frameworks:

nucleus comply --jurisdiction eu-dora       # EU DORA

nucleus comply --jurisdiction sg-mas-trm # Singapore MAS TRM nucleus comply --jurisdiction us-soc2 # US SOC2

---

Telemetry

Nucleus collects anonymous, aggregate usage statistics (command name, duration, error type, versions, OS). No engram content, no file paths, no prompts, no API keys, no PII — ever.

nucleus config --no-telemetry

or: NUCLEUS_ANON_TELEMETRY=false

See TELEMETRY.md for details.

---

Contributing

• Bug? Email hello@nucleusos.dev or report it on Discord
• Feature idea? Bring it to Discord
• Code? See CONTRIBUTING.md
• Chat? Discord

License

MIT © 2026 | hello@nucleusos.dev

Companion repositories (optional)

Some deployments keep companion scripts in a repo next to this one. Point nucleus at them with either:

export NUCLEUS_SIBLING_REPOS="$HOME/repo-a:$HOME/repo-b"     # os.pathsep-separated

or, one path per line:

printf '%s\n' "$HOME/repo-a" "$HOME/repo-b" > ~/.config/nucleus/siblings

With neither set, nucleus searches only its own repo — no assumptions are made about the host. A job whose script cannot be found fails with an error naming every location tried.

Pri