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 <site-packages>/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

	Free	Pro
30 tools, 19 resources, 8 prompts	Yes	Yes
Persistent memory	Yes	Yes
Governance & HITL	Yes	Yes
Audit trails (DSoR)	Yes	Yes
Signed audit reports	-	not yet shipped
Compliance exports	Score only	Full PDF/HTML
Priority issues	-	Yes

---

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 <config>.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 <site-packages>/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

Jurisdiction	Retention	HITL Ops	Kill Switch
eu-dora	7 years	5 types	Required
sg-mas-trm	5 years	5 types	Required
us-soc2	1 year	3 types	Optional
global-default	90 days	2 types	Optional

---

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.

Privacy

Where your memories live depends on which Quick Start option you chose.

Option B — local install. Nucleus is local-first. Engrams, memories and project state are written to .brain/ on your machine. Nothing is sent anywhere unless you configure a relay yourself.

Option A — no install (relay.nucleusos.dev). This is a hosted service we operate. Your engrams are stored on our servers, not on your machine, and what is stored is the full content of each memory — the value field, not just a key or a timestamp — along with its context label, intensity, version and timestamps. There is no local .brain/ in this mode; the relay is the brain.

We keep tenants separated and reachable only with your own bearer token. But "local-first" does not describe Option A, and it would be wrong to let the word cover it: if you would not put something on a server we run, do not put it in a memory while connected this way. Use Option B for that.

An earlier version of this section described only the local case, and understated what a relay receives. It has been corrected.

Telemetry: Anonymous, aggregate usage statistics only (command name, duration, error type, versions, OS). No engram content, no file paths, no prompts, no API keys, no PII — ever. Disable with nucleus config --no-telemetry or NUCLEUS_ANON_TELEMETRY=false. This is separate from, and unaffected by, which option above you chose.

Self-hosted relay (optional, Option B): If you point Nucleus at a relay endpoint you run, full engram content is synced there — same record shape as above. That server is yours.

Contact: Privacy questions → hello@nucleusos.dev