Nucleus MCP
Nucleus MCP is a portable, file-based AI decision log and agent operating system providing 35+ tools across 13 facades for persistent memory, task orchestration, governance, and multi-agent coordination.
š§ Memory (Engrams) ā Persistent key-value store with full-text search, context graphs, relationship traversal, and daily briefs.
ā Task Management ā Priority queue with escalation, human-in-the-loop gates, cognitive depth tracking, and bulk JSONL import.
š Session Lifecycle ā Start/save/resume sessions, emit structured events, manage key-value state, create checkpoints for rollback, and generate handoff summaries.
š Governance & Security ā File locking, red/blue security modes, automated verify-diagnose-fix-retry loops, egress-controlled HTTP proxying, package installs with audit logging, and compliance frameworks (EU DORA, SOC2, MAS TRM) with signed audit reports.
š¤ Multi-Agent Sync ā Cross-agent artifact sharing, shared key-value store, trigger-based automation, and deployment polling/smoke testing.
š Sprint & Slot Execution ā Time-boxed work slots with fifo/priority/balanced strategies, 25-minute autopilot sprints, and multi-sprint missions with automatic sequencing.
š Federation ā Connect and sync multiple brain instances across distributed environments, route requests to peers, and monitor connectivity/latency.
š¤ Agent Management ā Spawn sub-agents (reviewer, implementer, researcher, planner), run automated code review/repair, orchestrate swarms for parallel tasks, and import tasks from GitHub/CSV/JSONL.
š Orchestration & Strategy ā Satellite bird's-eye view of all active work, commitment tracking, pattern detection, and data export in JSON/CSV/Markdown.
š Telemetry & Safety ā LLM tier configuration, interaction logging for DPO training pairs, human feedback capture, kill switches, notification pausing, and per-agent cost dashboards.
šļø Infrastructure ā File change monitoring, GCP service status, local service detection, and strategic planning report generation.
š Features & Proofs ā Feature lifecycle tracking, cryptographic Ed25519-signed execution proofs for audit compliance, and mounting external MCP servers as composable sub-tools.
āļø Execution Verification (Align/Ground) ā One-call alignment corrections that record verdicts and create DPO training pairs, plus 5-tier code verification (syntax, imports, tests, runtime) with auto-fix loops.
Integrates with Codeium's Windsurf editor to synchronize project state, session memory, and decision history with other AI-powered development environments.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Nucleus MCPWhat decisions have we made about the architecture?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
.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.
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 improvesGROUND ā 5-tier execution verification. Syntax, imports, tests, runtime. Goes outside the formal system to check the AI's work.
ALIGN ā One-call corrections. nucleus_align(action="correct", params={context, correction}). Each correction automatically records a verdict, creates a training pair, and emits 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
pip install nucleus-mcp
nucleus init --recipe founderTwo commands. Nucleus is running. AI outputs are now verified.
What It Does
114 MCP tools across 13 facades:
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?
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 --signed -o report.html # Cryptographically signed report$19/month or $149/year ā nucleusos.dev/pricing
Free | Pro | |
13 tools, 10 resources, 3 prompts | Yes | Yes |
Persistent memory | Yes | Yes |
Governance & HITL | Yes | Yes |
Audit trails (DSoR) | Yes | Yes |
Signed audit reports | - | Ed25519 |
Compliance exports | Score only | Full PDF/HTML |
Priority issues | - | Yes |
Install
One-Click
IDE | Install |
Cursor | |
Claude Code |
|
Any IDE |
|
pip / npx
pip install nucleus-mcpOr use npx (zero Python setup required):
npx -y nucleus-mcpConfigure Your MCP Client
Claude Desktop / Cursor / Windsurf
Add to your MCP config (claude_desktop_config.json or equivalent):
{
"mcpServers": {
"nucleus": {
"command": "npx",
"args": ["-y", "nucleus-mcp"]
}
}
}{
"mcpServers": {
"nucleus": {
"command": "python3",
"args": ["-m", "mcp_server_nucleus"],
"env": {
"NUCLEUS_BRAIN_PATH": "/path/to/your/project/.brain"
}
}
}
}Claude Code
Add to .mcp.json in your project root:
{
"mcpServers": {
"nucleus": {
"command": "npx",
"args": ["-y", "nucleus-mcp"]
}
}
}Path Discovery
Nucleus finds your .brain automatically:
NUCLEUS_BRAIN_PATHenvironment variable (explicit)Walk up from CWD looking for
.brain/directoryFall back to
$HOME/.nucleus/brain
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 chatPipe-friendly:
nucleus engram search "test" | jq '.key'
nucleus task list --format tsv | cut -f1,3Compliance
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 SOC2Jurisdiction | Retention | HITL Ops | Kill Switch |
| 7 years | 5 types | Required |
| 5 years | 5 types | Required |
| 1 year | 3 types | Optional |
| 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=falseSee TELEMETRY.md for details.
Contributing
Bug? Open an Issue
Feature idea? Start a Discussion
Code? See CONTRIBUTING.md
Chat? Discord
License
MIT Ā© 2026 | hello@nucleusos.dev
Maintenance
Latest Blog Posts
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/eidetic-works/nucleus-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server