# https://github.com/eidetic-works/nucleus-mcp Project Manual Generated at: 2026-06-27 10:29:04 UTC ## Table of Contents - [Overview, Installation & Configuration](#page-1) - [The Three Frontiers (GROUND / ALIGN / COMPOUND)](#page-2) - [MCP Tools, CLI, Memory & Data Flow](#page-3) - [Compliance, Governance, Telemetry & Security](#page-4) ## Overview, Installation & Configuration ### Related Pages Related topics: [The Three Frontiers (GROUND / ALIGN / COMPOUND)](#page-2), [MCP Tools, CLI, Memory & Data Flow](#page-3)
Related Source Files The following source files were used to generate this page: - [README.md](https://github.com/eidetic-works/nucleus-mcp/blob/main/README.md) - [examples/README.md](https://github.com/eidetic-works/nucleus-mcp/blob/main/examples/README.md) - [src/mcp_server_nucleus/flywheel/__init__.py](https://github.com/eidetic-works/nucleus-mcp/blob/main/src/mcp_server_nucleus/flywheel/__init__.py) - [src/mcp_server_nucleus/flywheel/core.py](https://github.com/eidetic-works/nucleus-mcp/blob/main/src/mcp_server_nucleus/flywheel/core.py) - [src/mcp_server_nucleus/sessions/autonomous_wake.py](https://github.com/eidetic-works/nucleus-mcp/blob/main/src/mcp_server_nucleus/sessions/autonomous_wake.py) - [src/mcp_server_nucleus/runtime/agents/oracle/manifest.json](https://github.com/eidetic-works/nucleus-mcp/blob/main/src/mcp_server_nucleus/runtime/agents/oracle/manifest.json) - [src/mcp_server_nucleus/runtime/capabilities/code_ops.py](https://github.com/eidetic-works/nucleus-mcp/blob/main/src/mcp_server_nucleus/runtime/capabilities/code_ops.py) - [src/mcp_server_nucleus/runtime/capabilities/feature_map.py](https://github.com/eidetic-works/nucleus-mcp/blob/main/src/mcp_server_nucleus/runtime/capabilities/feature_map.py) - [src/mcp_server_nucleus/runtime/capabilities/proof_system.py](https://github.com/eidetic-works/nucleus-mcp/blob/main/src/mcp_server_nucleus/runtime/capabilities/proof_system.py)
# Overview, Installation & Configuration ## Purpose and Scope `nucleus-mcp` is a file-based persistent memory MCP (Model Context Protocol) server designed to give AI assistants a single, durable "brain" that survives across sessions and tools. The README frames the project as a way to ensure that "Decisions, policies, plans — written once, remembered across every session and every tool." It is MIT licensed, uses plain JSON and markdown on disk, requires no embeddings, and has no vendor lock-in. Source: [README.md](https://github.com/eidetic-works/nucleus-mcp/blob/main/README.md). Beyond the memory core, the repository ships a second, fully independent companion tool called **nucleus-rabbithole**, a rabbit-hole depth tracker for focus-prone developers. Both share the same install and are invoked through the same MCP client configuration block. Source: [README.md](https://github.com/eidetic-works/nucleus-mcp/blob/main/README.md). The project's design philosophy is captured in the **Three Frontiers** loop: - **GROUND** — machine-verifies AI output (diff, syntax, imports, tests, runtime). Receipts are logged to `.brain/verification_log.jsonl`. - **ALIGN** — captures human corrections as one-call events. - **COMPOUND** — every verified output and every correction feeds back into training data so reliability compounds over time. Source: [README.md](https://github.com/eidetic-works/nucleus-mcp/blob/main/README.md). ## Architecture at a Glance The server is structured as a capability-based runtime: each capability exposes a stable MCP tool surface, and a `Capability` base class supplies the contract. For example, `code_ops` registers tools like `code_write_file`, `code_read_file`, `code_run_command`, and `code_list_files`. Source: [src/mcp_server_nucleus/runtime/capabilities/code_ops.py](https://github.com/eidetic-works/nucleus-mcp/blob/main/src/mcp_server_nucleus/runtime/capabilities/code_ops.py). Other capability modules follow the same pattern, including `feature_map` (product feature catalog), `proof_system` (per-feature proof documents), `web_ops`, `budget_ops`, `agent_dashboard`, and `synthesizer`. Sources: [src/mcp_server_nucleus/runtime/capabilities/feature_map.py](https://github.com/eidetic-works/nucleus-mcp/blob/main/src/mcp_server_nucleus/runtime/capabilities/feature_map.py), [src/mcp_server_nucleus/runtime/capabilities/proof_system.py](https://github.com/eidetic-works/nucleus-mcp/blob/main/src/mcp_server_nucleus/runtime/capabilities/proof_system.py). Below the capability layer lives the **Flywheel** subpackage, which implements the 6-action accountability helper plus CSR (Claims Survival Rate) bookkeeping. Its public API is exposed via `src/mcp_server_nucleus/flywheel/__init__.py` and includes `Flywheel`, `file_ticket`, `record_survived`, `bump_survived`, `bump_unsurvived`, `read_csr`, `render_dashboard_json`, `render_dashboard_html`, `generate_week_report`, and `curriculum_refresh`. Source: [src/mcp_server_nucleus/flywheel/__init__.py](https://github.com/eidetic-works/nucleus-mcp/blob/main/src/mcp_server_nucleus/flywheel/__init__.py). The Flywheel's `file_ticket` action runs up to six side effects (memory note, CSR bump, training pair seed, weekly report append, GitHub issue fallback, task registration fallback) and is idempotent so the loop keeps turning even when offline. Source: [src/mcp_server_nucleus/flywheel/core.py](https://github.com/eidetic-works/nucleus-mcp/blob/main/src/mcp_server_nucleus/flywheel/core.py). ```mermaid flowchart LR Client[MCP Client
Claude Code / Cursor / Windsurf] -->|JSON-RPC| Server[nucleus-mcp server] Server --> Caps[Capability Layer
code_ops / feature_map / proof_system / ...] Caps --> Brain[".brain/ on disk
plain JSON + markdown"] Server --> Flywheel[Flywheel
CSR + tickets + reports] Flywheel --> Brain Caps --> Agents["Agents
oracle / dashboard / runtime"] Agents --> Brain ``` ## Installation The recommended path is installation from PyPI, which exposes the `nucleus-mcp` console script plus the `nucleus-rabbithole` companion. Source: [README.md](https://github.com/eidetic-works/nucleus-mcp/blob/main/README.md). ```bash pip install nucleus-mcp ``` For local development against the source tree, set `PYTHONPATH` to `src/` and invoke examples directly: ```bash cd mcp-server-nucleus export PYTHONPATH=src python examples/basic_usage.py ``` Source: [examples/README.md](https://github.com/eidetic-works/nucleus-mcp/blob/main/examples/README.md). The first run prompts for telemetry consent and bootstraps a `.brain/` directory at the current working path. Fresh installs default telemetry to **disabled**; existing installs honor an explicit `telemetry.anonymous.enabled` key in `nucleus.yaml` rather than re-prompting. ## Configuration The MCP client integration uses a `.mcp.json` entry pointing at the `nucleus-mcp` console script. The companion tool uses an identical shape: ```json { "mcpServers": { "nucleus-mcp": { "command": "nucleus-mcp", "args": [] }, "nucleus-rabbithole": { "command": "nucleus-rabbithole", "args": [] } } } ``` Source: [README.md](https://github.com/eidetic-works/nucleus-mcp/blob/main/README.md). The brain directory location is resolved through `NUCLEUS_BRAIN_PATH`, with a fallback to `cwd/.brain`. The brain path is the on-disk root for verification logs, flywheel tickets, CSR state, training pair seeds, and agent manifests. Source: [src/mcp_server_nucleus/flywheel/core.py](https://github.com/eidetic-works/nucleus-mcp/blob/main/src/mcp_server_nucleus/flywheel/core.py). Key configuration levers: | Setting | Location | Effect | |---|---|---| | `telemetry.anonymous.enabled` | `nucleus.yaml` | Opt-in flag. Default `false` on fresh installs. | | `NUCLEUS_BRAIN_PATH` | environment | Overrides `cwd/.brain` for the storage root. | | `GEMINI_API_KEY` | environment | Enables `brain_synthesize_status_report` via `synthesizer`. | | Agent capabilities | `.brain/runtime/agents//manifest.json` | Declares read/write scopes, e.g. `nucleus.core.oracle`. | Sources: [src/mcp_server_nucleus/runtime/capabilities/synthesizer.py](https://github.com/eidetic-works/nucleus-mcp/blob/main/src/mcp_server_nucleus/runtime/capabilities/synthesizer.py), [src/mcp_server_nucleus/runtime/agents/oracle/manifest.json](https://github.com/eidetic-works/nucleus-mcp/blob/main/src/mcp_server_nucleus/runtime/agents/oracle/manifest.json). ## Common Failure Modes Several issues observed by the community surface recurring setup pitfalls worth flagging during onboarding: - **Silent skip paths** — callbacks like `_PostPrecomputeGuard` can swallow a save step. When integrating verification or caching hooks, ensure every branch logs whether the action ran or was skipped (BUG-002). - **Callback ordering** — operations placed **before** a training call can be useless because internal precomputation happens later (e.g., TRL's ref logprob precompute runs inside `.train()`, not in `DPOTrainer.__init__()`). For verification pipelines, instrument timing so GROUND/ALIGN receive reliable execution-order signals (BUG-001). - **Telemetry expectation** — telemetry is opt-in since v1.13.1. Existing installs are not re-prompted; if a feature seems missing, check `telemetry.anonymous.enabled` in `nucleus.yaml` before assuming a regression. Source: community context for BUG-001, BUG-002, and v1.13.1. ## See Also - Three Frontiers (GROUND / ALIGN / COMPOUND) - Flywheel accountability loop and CSR dashboard - Capability layer: `code_ops`, `feature_map`, `proof_system`, `budget_ops`, `agent_dashboard` - `nucleus-rabbithole` companion tool --- ## The Three Frontiers (GROUND / ALIGN / COMPOUND) ### Related Pages Related topics: [MCP Tools, CLI, Memory & Data Flow](#page-3), [Compliance, Governance, Telemetry & Security](#page-4)
Related Source Files The following source files were used to generate this page: - [src/mcp_server_nucleus/flywheel/__init__.py](https://github.com/eidetic-works/nucleus-mcp/blob/main/src/mcp_server_nucleus/flywheel/__init__.py) - [src/mcp_server_nucleus/flywheel/core.py](https://github.com/eidetic-works/nucleus-mcp/blob/main/src/mcp_server_nucleus/flywheel/core.py) - [src/mcp_server_nucleus/flywheel/dashboard.py](https://github.com/eidetic-works/nucleus-mcp/blob/main/src/mcp_server_nucleus/flywheel/dashboard.py) - [src/mcp_server_nucleus/flywheel/report.py](https://github.com/eidetic-works/nucleus-mcp/blob/main/src/mcp_server_nucleus/flywheel/report.py) - [src/mcp_server_nucleus/runtime/capabilities/proof_system.py](https://github.com/eidetic-works/nucleus-mcp/blob/main/src/mcp_server_nucleus/runtime/capabilities/proof_system.py) - [src/mcp_server_nucleus/runtime/capabilities/feature_map.py](https://github.com/eidetic-works/nucleus-mcp/blob/main/src/mcp_server_nucleus/runtime/capabilities/feature_map.py) - [README.md](https://github.com/eidetic-works/nucleus-mcp/blob/main/README.md)
# The Three Frontiers (GROUND / ALIGN / COMPOUND) ## Overview and Purpose The Three Frontiers is the core reliability loop that makes nucleus-mcp's AI accountability compound over time. Introduced in v1.8.0 as "Three Frontiers: AI reliability that compounds", the loop pairs machine verification with human correction and turns every delta into supervised training data. As stated in the README: "Every AI output verified. Every correction recorded. Every mistake trains the system." `Source: [README.md]()` The loop is implemented primarily in the `mcp_server_nucleus.flywheel` subpackage, which the module's docstring describes as "the compounding loop engine" where "every failure → ticket → curriculum pair → next training run" and "every success → CSR claim bump → dashboard delta." `Source: [src/mcp_server_nucleus/flywheel/__init__.py]()` The public API surface — `Flywheel`, `file_ticket`, `record_survived`, `bump_survived`, `bump_unsurvived`, `read_csr`, `render_dashboard_*`, `generate_week_report`, and `curriculum_refresh` — exposes the loop to MCP clients. `Source: [src/mcp_server_nucleus/flywheel/__init__.py]()` The current flywheel package version is 0.1.0. `Source: [src/mcp_server_nucleus/flywheel/__init__.py]()` ## GROUND — Machine Verification GROUND is the verification frontier. When the AI produces a change, a 5-tier execution verification runs against it: diff, syntax, imports, tests, and runtime. A successful verification yields a receipt that is appended to `.brain/verification_log.jsonl`, providing an auditable, append-only ledger of what the system claimed and what the system actually demonstrated. `Source: [README.md]()` Adjacent to GROUND is the Proof System capability, which lets MCP clients generate, fetch, and list proof documents describing how a feature was built and how it can be rolled back. Three MCP tools implement this: `brain_generate_proof(feature_id, …)`, `brain_get_proof(feature_id)`, and `brain_list_proofs()`. `Source: [src/mcp_server_nucleus/runtime/capabilities/proof_system.py]()` Each proof captures metadata such as feature_id, version, status, deployed_url, files_changed, risk_level, and rollback_time, and is persisted as a markdown file at `proofs_dir / f"{feature_id}.md"`. `Source: [src/mcp_server_nucleus/runtime/capabilities/proof_system.py]()` The `FeatureMap` capability complements proofs by tracking what a feature does, where it lives, how to test it, and its current development status. `Source: [src/mcp_server_nucleus/runtime/capabilities/feature_map.py]()` ## ALIGN — Human Correction ALIGN is the human-in-the-loop frontier. When the user disagrees with a GROUND verdict or spots a mistake, the correction is captured with a single call, the verdict is stored as a structured event, and the delta is emitted to downstream consumers. `Source: [README.md]()` The `Flywheel.file_ticket()` helper is the mechanical implementation of this stage: it wraps the "feedback nucleus accountability" markdown document into six idempotent actions so that a correction never gets lost even if downstream sinks fail. The six actions, per the module docstring, are: (1) memory note in `.brain/flywheel/pending_issues.jsonl`, (2) CSR unsurvived bump, (3) training-pair seed appended to `training/exports/unified_dpo_pending.jsonl`, (4) weekly report append, (5) GitHub issue attempt via the `gh` CLI (best-effort, queued on failure), and (6) task registration in `.brain/flywheel/pending_tasks.jsonl`. `Source: [src/mcp_server_nucleus/flywheel/core.py]()` Each ticket generation step is best-effort and idempotent: a ticket that cannot reach GitHub still writes the other five actions so the loop keeps turning when the network returns. `Source: [src/mcp_server_nucleus/flywheel/core.py]()` Complementing the ticket flow, `record_survived()` and `bump_survived()` / `bump_unsurvived()` are the public shortcuts used by tools that need to record whether a claim passed or failed ALIGN review. `Source: [src/mcp_server_nucleus/flywheel/core.py]()` ## COMPOUND — System Learning COMPOUND is where the corrections become training data. The training-pair seed written by `file_ticket()` flows into `.brain/training/exports/unified_dpo_pending.jsonl` and is later consumed by `curriculum_refresh()`, which closes the training loop and prepares the next DPO run. `Source: [src/mcp_server_nucleus/flywheel/__init__.py]()` The Claim Survival Rate (CSR) is the headline metric that quantifies how well COMPOUND is working. The dashboard projects CSR state — `claims_total`, `claims_survived`, `claims_unsurvived`, and the survival `ratio` — alongside counts of open tickets, open tasks, and pending curriculum pairs. `Source: [src/mcp_server_nucleus/flywheel/dashboard.py]()` Weekly markdown reports (`week-N.md`) are produced by `generate_week_report(brain_path, week=None)`, scoped to the current ISO week and built from the pending issues log plus CSR state. `Source: [src/mcp_server_nucleus/flywheel/report.py]()` Both renderers are safe to run repeatedly — the HTML/JSON dashboard regenerates state on each call, and the weekly report overwrites the summary block while preserving the append-only ticket log below it. `Source: [src/mcp_server_nucleus/flywheel/report.py]()` ## The Compounding Loop ```mermaid flowchart LR A[AI writes code] --> B[GROUND
5-tier verify] B -->|receipt| L[.brain/verification_log.jsonl] B --> C{Verdict} C -->|pass| D[CSR survived++] C -->|fail| E[ALIGN
file_ticket] E --> F[6 actions:
pending_issues
CSR unsurvived
unified_dpo_pending
week-N.md
gh issue
pending_tasks] F --> G[COMPOUND
curriculum_refresh] G --> H[Next DPO run] H --> A D --> I[Dashboard JSON/HTML
Weekly report] ``` The flywheel is observable end-to-end: GROUND writes receipts, ALIGN writes tickets, COMPOUND writes curriculum pairs, and the dashboard / weekly report close the feedback loop for the operator. `Source: [src/mcp_server_nucleus/flywheel/dashboard.py]()` and `Source: [src/mcp_server_nucleus/flywheel/report.py]()` ## Community Context and Known Issues Two community-reported bugs highlight timing and observability pitfalls when integrating the Three Frontiers with downstream TRL training: - **BUG-001 (Issue #8)** — GROUND/ALIGN missed execution-order verification: `gc.collect()` and the ref-logprob cache save were placed *before* `.train()` in a DPO notebook, but TRL's ref-logprob precomputation happens *inside* `.train()`, not during `DPOTrainer.__init__()`. The fix is to register pre-training hooks against the trainer's lifecycle, not the constructor. `Source: community context, issue #8` - **BUG-002 (Issue #9)** — The `_PostPrecomputeGuard` callback has a silent skip path: when the cache is already loaded (`_loaded_from_cache == True`), the save is skipped with no log line. Operators see cleanup output but cannot tell whether the cache was written or skipped. The recommended fix is to emit an explicit `[cache] skipped — already loaded` log on the skip branch. `Source: community context, issue #9` Both issues reinforce a general rule when wiring the Three Frontiers: hooks must attach to the right lifecycle stage (after `.train()` begins, not before), and every branch — including no-ops — must leave an observable trace in `.brain/`. ## See Also - Flywheel public API reference (`src/mcp_server_nucleus/flywheel/__init__.py`) - Claim Survival Rate dashboard (`src/mcp_server_nucleus/flywheel/dashboard.py`) - Weekly accountability reports (`src/mcp_server_nucleus/flywheel/report.py`) - Proof System MCP capability (`src/mcp_server_nucleus/runtime/capabilities/proof_system.py`) - Feature Map MCP capability (`src/mcp_server_nucleus/runtime/capabilities/feature_map.py`) - v1.8.0 release notes — Three Frontiers introduction - v1.13.1 release notes — Opt-in telemetry audit --- ## MCP Tools, CLI, Memory & Data Flow ### Related Pages Related topics: [Overview, Installation & Configuration](#page-1), [The Three Frontiers (GROUND / ALIGN / COMPOUND)](#page-2), [Compliance, Governance, Telemetry & Security](#page-4)
Related Source Files The following source files were used to generate this page: - [README.md](https://github.com/eidetic-works/nucleus-mcp/blob/main/README.md) - [examples/README.md](https://github.com/eidetic-works/nucleus-mcp/blob/main/examples/README.md) - [src/mcp_server_nucleus/runtime/capabilities/proof_system.py](https://github.com/eidetic-works/nucleus-mcp/blob/main/src/mcp_server_nucleus/runtime/capabilities/proof_system.py) - [src/mcp_server_nucleus/runtime/capabilities/budget_ops.py](https://github.com/eidetic-works/nucleus-mcp/blob/main/src/mcp_server_nucleus/runtime/capabilities/budget_ops.py) - [src/mcp_server_nucleus/runtime/capabilities/agent_dashboard.py](https://github.com/eidetic-works/nucleus-mcp/blob/main/src/mcp_server_nucleus/runtime/capabilities/agent_dashboard.py) - [src/mcp_server_nucleus/runtime/capabilities/enforcement_ops.py](https://github.com/eidetic-works/nucleus-mcp/blob/main/src/mcp_server_nucleus/runtime/capabilities/enforcement_ops.py) - [src/mcp_server_nucleus/runtime/capabilities/feature_map.py](https://github.com/eidetic-works/nucleus-mcp/blob/main/src/mcp_server_nucleus/runtime/capabilities/feature_map.py) - [src/mcp_server_nucleus/runtime/capabilities/web_ops.py](https://github.com/eidetic-works/nucleus-mcp/blob/main/src/mcp_server_nucleus/runtime/capabilities/web_ops.py) - [src/mcp_server_nucleus/runtime/capabilities/synthesizer.py](https://github.com/eidetic-works/nucleus-mcp/blob/main/src/mcp_server_nucleus/runtime/capabilities/synthesizer.py) - [src/mcp_server_nucleus/flywheel/__init__.py](https://github.com/eidetic-works/nucleus-mcp/blob/main/src/mcp_server_nucleus/flywheel/__init__.py) - [src/mcp_server_nucleus/flywheel/core.py](https://github.com/eidetic-works/nucleus-mcp/blob/main/src/mcp_server_nucleus/flywheel/core.py) - [src/mcp_server_nucleus/flywheel/dashboard.py](https://github.com/eidetic-works/nucleus-mcp/blob/main/src/mcp_server_nucleus/flywheel/dashboard.py) - [src/mcp_server_nucleus/sessions/autonomous_wake.py](https://github.com/eidetic-works/nucleus-mcp/blob/main/src/mcp_server_nucleus/sessions/autonomous_wake.py) - [src/mcp_server_nucleus/http_transport/readonly_app.py](https://github.com/eidetic-works/nucleus-mcp/blob/main/src/mcp_server_nucleus/http_transport/readonly_app.py)
# MCP Tools, CLI, Memory & Data Flow ## Purpose & Scope `nucleus-mcp` exposes a `.brain` decision log to any MCP-compatible client (Claude Code, Cursor, Codex) via a single MCP server. The product is MIT licensed, file-based (plain JSON + markdown), and avoids embeddings or vendor lock-in (Source: [README.md:1-3]()). Alongside the main MCP server, the package ships `nucleus-rabbithole`, an independent focus-tracking tool (Source: [README.md:9-19]()). The repository went through a public history reset on March 2, 2026; the code, packages, and documentation were preserved, but anyone who starred before will need to re-star (Source: [v1.2.0-announce release]()). The runtime is organized around three "Frontiers" introduced in v1.8.0 — `GROUND` (5-tier machine verification), `ALIGN` (one-call human corrections), and `COMPOUND` (delta recorded as DPO training pairs) (Source: [v1.8.0 release]()). The most recent release, v1.13.1 (2026-06-14), switches anonymous telemetry to opt-in (Source: [v1.13.1 release]()). Community-reported bugs in the training loop (BUG-001, BUG-002) reinforce the importance of execution-order verification and explicit logging on every cached-write decision (Source: [issue #8](), [issue #9]()). ## MCP Tool Surface The MCP tool surface is implemented as a set of capability classes under `src/mcp_server_nucleus/runtime/capabilities/`. Each capability extends a common base class and returns a JSON-schema `tools` array consumable by the host MCP client. Capabilities and their principal tools: - **Proof System** — `brain_generate_proof`, `brain_get_proof`, `brain_list_proofs` (Source: [proof_system.py:24-72]()) - **Budget Ops** — `brain_budget_status`, `brain_budget_set_daily`, `brain_budget_set_hourly`, `brain_budget_reset` (Source: [budget_ops.py:36-86]()) - **Agent Dashboard** — `brain_agent_dashboard`, `brain_agent_spawn_stats`, `brain_agent_costs`, `brain_agent_list_active`, `brain_agent_cancel`, `brain_agent_cleanup` (Source: [agent_dashboard.py:43-117]()) - **Enforcement Ops** — `brain_enforcement_stats`, `brain_enforcement_patterns`, `brain_enforcement_analyze`, `brain_enforcement_test` (Source: [enforcement_ops.py:33-79]()) - **Feature Map** — `brain_list_features`, `brain_get_feature`, plus CRUD variants (Source: [feature_map.py:21-50]()) - **Web Ops** — `web_search`, `web_read_page` (DuckDuckGo-backed) (Source: [web_ops.py:14-44]()) - **Synthesizer** — `brain_synthesize_status_report` (Gemini 2.0 Flash) (Source: [synthesizer.py:58-103]()) Each capability follows the same shape: a `name`, a `description`, and a `get_tools()` returning JSON-schema parameter objects. `execute_tool()` dispatches by `tool_name` and returns either structured data or an error string (Source: [proof_system.py:74-82]()). Dispatchers are defensive — `Capability` instances catch all exceptions so a single failing tool does not bring the whole MCP server down. ### Read-Only Transport Variant For environments that restrict MCP tools to read-only operations (Microsoft 365 Copilot federated connectors, enterprise sandboxes), a separate FastMCP instance is mounted at `/mcp-readonly` (Source: [readonly_app.py:1-19]()). It exposes only four tools (`nucleus_search`, `nucleus_audit`, `nucleus_route`, `nucleus_relay_subscribe`), each tagged `readOnlyHint=True`. The full server remains mounted at `/mcp` with all 17 tools. Both share `NUCLEUS_BRAIN_PATH` and the `PORT` env var (Source: [readonly_app.py:21-31]()). ## CLI & Path Discovery A CLI is shipped alongside the MCP tools and auto-detects TTY (table output) versus pipe (JSON) output (Source: [README.md:81-83]()). The CLI mirrors the underlying memory primitives: ```bash # Memory (engrams) nucleus engram write my_key "insight here" --context Decision --intensity 7 nucleus engram search "compliance" nucleus engram query --context Strategy --limit 10 # Tasks & sessions nucleus task list --status READY nucleus session save "Working on auth refactor" nucleus session resume # Health & compliance nucleus status --health nucleus sovereign nucleus comply --jurisdiction eu-dora nucleus audit-report --format html -o report.html # Multi-provider chat nucleus chat ``` When piped, output is JSON, making the CLI composable with `jq` and similar tools (Source: [README.md:96-97]()). Path discovery is deterministic and explicit (Source: [README.md:60-69]()): the resolver checks `NUCLEUS_BRAIN_PATH` first, then walks up from CWD looking for `.brain/`, and finally falls back to `$HOME/.nucleus/brain`. The same resolution logic is used inside Python modules — `_default_brain_path()` reads `NUCLEUS_BRAIN_PATH` first and otherwise returns `Path.cwd() / ".brain"` (Source: [flywheel/core.py:21-25]()). This guarantees that the MCP server, the CLI, and embedded Python callers all agree on the same `.brain` root. ## Memory, Flywheel & Data Flow Persistent state lives under `.brain/` as plain JSON and markdown files — no database required. The Flywheel subpackage is the central accountability engine: every failure becomes a ticket, every ticket becomes a curriculum pair, and every success bumps the Central Survival Rate (CSR) (Source: [flywheel/__init__.py:1-25]()). The Flywheel exposes a stable public API: ```python from mcp_server_nucleus.flywheel import ( Flywheel, file_ticket, record_survived, bump_survived, bump_unsurvived, read_csr, render_dashboard_html, render_dashboard_json, generate_week_report, curriculum_refresh, ) ``` The `file_ticket()` helper triggers six best-effort, idempotent actions per failure (Source: [flywheel/core.py:13-25]()): ```mermaid flowchart TD F[Failure detected] --> T[file_ticket step, error, logs] T --> A1[1. Append pending_issues.jsonl] T --> A2[2. Bump CSR unsurvived] T --> A3[3. Seed DPO pair in unified_dpo_pending.jsonl] T --> A4[4. Append week-N.md] T --> A5[5. gh issue create nucleus-bug,flywheel-auto] T --> A6[6. Register pending_tasks.jsonl fallback] A1 -.success.-> R[Flywheel state in .brain/flywheel/] A2 -.success.-> R A3 -.success.-> R A4 -.success.-> R A5 -.offline-tolerant.-> R A6 -.success.-> R R --> D[render_dashboard_json / render_dashboard_html] D --> O[MCP resource query or browser view] ``` All six actions are best-effort; if `gh` is unavailable the other five still run, so the loop keeps turning when network returns (Source: [flywheel/core.py:13-25]()). The dashboard renderer reads CSR state plus recent tickets and emits either JSON (for MCP resource queries) or a self-contained HTML page (Source: [flywheel/dashboard.py:18-33]()). Counts for open tickets, open tasks, and pending training pairs come from line-counting the respective JSONL files (Source: [flywheel/dashboard.py:9-16]()). For long-running autonomous sessions, `autonomous_wake.py` POSTs to the Anthropic `/v1/messages?beta=true` endpoint with a flattened `tools[]` array (deduped against `nucleus_relay`); the bearer token and payload body are never logged (Source: [autonomous_wake.py:14-26](), [autonomous_wake.py:53-71]()). The full request body is built by combining caller-supplied tools with flattened MCP-server tools — passing `mcp_servers` as a top-level field would produce an Anthropic 400, which is why the loader flattens rather than forwards the field (Source: [autonomous_wake.py:78-92]()). Tool flattening is defensive against malformed entries: non-dict servers, non-dict tools, and missing names are skipped silently rather than spamming logs (Source: [autonomous_wake.py:14-26]()). This addresses a class of community-reported failure modes (BUG-002) where silent skip paths leave operators without feedback. Examples for development and testing live in `examples/` (basic usage, engrams, depth tracker, governance, task queue, recursive mounter) and are run via `PYTHONPATH=src python examples/.py` (Source: [examples/README.md:1-25]()). In production, however, the recommended path is to consume the MCP tools through an MCP client, not the CLI or Python API directly. ## See Also - [README.md](https://github.com/eidetic-works/nucleus-mcp/blob/main/README.md) — quick start, CLI examples, MCP client config - [v1.13.1 release notes](https://github.com/eidetic-works/nucleus-mcp/releases/tag/v1.13.1) — opt-in telemetry - [docs/RABBITHOLE.md](https://github.com/eidetic-works/nucleus-mcp/blob/main/docs/RABBITHOLE.md) — `nucleus-rabbithole` companion tool --- ## Compliance, Governance, Telemetry & Security ### Related Pages Related topics: [The Three Frontiers (GROUND / ALIGN / COMPOUND)](#page-2), [MCP Tools, CLI, Memory & Data Flow](#page-3)
Related Source Files The following source files were used to generate this page: - [README.md](https://github.com/eidetic-works/nucleus-mcp/blob/main/README.md) - [src/mcp_server_nucleus/runtime/agents/oracle/manifest.json](https://github.com/eidetic-works/nucleus-mcp/blob/main/src/mcp_server_nucleus/runtime/agents/oracle/manifest.json) - [src/mcp_server_nucleus/runtime/capabilities/proof_system.py](https://github.com/eidetic-works/nucleus-mcp/blob/main/src/mcp_server_nucleus/runtime/capabilities/proof_system.py) - [src/mcp_server_nucleus/runtime/capabilities/feature_map.py](https://github.com/eidetic-works/nucleus-mcp/blob/main/src/mcp_server_nucleus/runtime/capabilities/feature_map.py) - [src/mcp_server_nucleus/runtime/capabilities/enforcement_ops.py](https://github.com/eidetic-works/nucleus-mcp/blob/main/src/mcp_server_nucleus/runtime/capabilities/enforcement_ops.py) - [src/mcp_server_nucleus/runtime/capabilities/budget_ops.py](https://github.com/eidetic-works/nucleus-mcp/blob/main/src/mcp_server_nucleus/runtime/capabilities/budget_ops.py) - [src/mcp_server_nucleus/sessions/autonomous_wake.py](https://github.com/eidetic-works/nucleus-mcp/blob/main/src/mcp_server_nucleus/sessions/autonomous_wake.py) - [src/mcp_server_nucleus/sessions/_relay_post_helper.py](https://github.com/eidetic-works/nucleus-mcp/blob/main/src/mcp_server_nucleus/sessions/_relay_post_helper.py) - [src/mcp_server_nucleus/flywheel/__init__.py](https://github.com/eidetic-works/nucleus-mcp/blob/main/src/mcp_server_nucleus/flywheel/__init__.py) - [src/mcp_server_nucleus/flywheel/core.py](https://github.com/eidetic-works/nucleus-mcp/blob/main/src/mcp_server_nucleus/flywheel/core.py) - [src/mcp_server_nucleus/flywheel/dashboard.py](https://github.com/eidetic-works/nucleus-mcp/blob/main/src/mcp_server_nucleus/flywheel/dashboard.py) - [src/mcp_server_nucleus/flywheel/report.py](https://github.com/eidetic-works/nucleus-mcp/blob/main/src/mcp_server_nucleus/flywheel/report.py)
# Compliance, Governance, Telemetry & Security Nucleus-MCP treats compliance and governance as a first-class concern rather than an afterthought. The project combines a file-based brain substrate (`MIT licensed`, plain JSON + markdown, no embeddings) with explicit agent manifests, machine-verifiable proofs, and an opt-in telemetry policy. The result is a runtime where every AI action can be traced, audited, and rolled back. Source: [README.md](https://github.com/eidetic-works/nucleus-mcp/blob/main/README.md). ## Governance Model and Agent Manifests Governance in nucleus-mcp is anchored by **The Oracle**, an antifragile co-founder agent whose behavior is declared in a versioned manifest rather than hard-coded. The manifest pins the agent identity, license, and the precise filesystem paths it may read or write. ```mermaid flowchart LR A[Oracle Manifest] -->|declares scope| B[strategy/] A -->|declares scope| C[PROTOCOL_THE_ORACLE.md] A -->|declares scope| D[decisions/] A -->|lifecycle| E[immortal / no cleanup] ``` The Oracle manifest declares `mode: read_write` over `${BRAIN_PATH}/strategy`, the `PROTOCOL_THE_ORACLE.md` policy file, `IMPLEMENTATION_PLAN_PHASE61.md`, and the `decisions` directory. Its lifecycle is marked `persistence: immortal`, signaling that no automated cleanup process may retire its state. Source: [src/mcp_server_nucleus/runtime/agents/oracle/manifest.json](https://github.com/eidetic-works/nucleus-mcp/blob/main/src/mcp_server_nucleus/runtime/agents/oracle/manifest.json). This manifest pattern establishes a governance contract: an agent's authority is enumerable, versioned, and auditable. Combined with the file-based brain, every strategic decision lands in a plain-text artifact that a reviewer can diff without specialized tooling. ## Compliance: Proofs, Features, and the Three Frontiers The compliance surface is split across two MCP capabilities: `proof_system` and `feature_map`. Together they implement the **Three Frontiers** (GROUND, ALIGN, COMPOUND) introduced in v1.8.0 — a loop in which the machine verifies, the human corrects, and the system learns. **GROUND** is the machine-verification tier. `ProofSystem._generate_proof` writes a markdown artifact per `feature_id` containing goal, description, deployment URL, list of modified files, risk level (`low/medium/high`), and a rollback strategy block with timing estimates. The proof path is deterministic: `proofs_dir / f"{feature_id}.md"`. Source: [src/mcp_server_nucleus/runtime/capabilities/proof_system.py](https://github.com/eidetic-works/nucleus-mcp/blob/main/src/mcp_server_nucleus/runtime/capabilities/proof_system.py). **ALIGN** is the human-correction tier. `FeatureMap` exposes `brain_list_features` and `brain_get_feature`, which index shipped features by `product`, `status` (`development`/`staged`/`production`/`released`), and free-form tags. Each feature record carries a `how_to_test` array and an `expected_result` field so a reviewer can independently re-derive the verdict. Source: [src/mcp_server_nucleus/runtime/capabilities/feature_map.py](https://github.com/eidetic-works/nucleus-mcp/blob/main/src/mcp_server_nucleus/runtime/capabilities/feature_map.py). **COMPOUND** is the training-data tier, where corrections become DPO pairs. The enforcement capability (`EnforcementOps`) exposes `brain_enforcement_stats` and `brain_enforcement_patterns`, letting operators inspect learned failure patterns from tool-calling attempts. A companion `budget_ops` capability tracks per-agent and per-hour spend via `brain_budget_status`, so a runaway agent can be throttled before it inflates costs. Source: [src/mcp_server_nucleus/runtime/capabilities/enforcement_ops.py](https://github.com/eidetic-works/nucleus-mcp/blob/main/src/mcp_server_nucleus/runtime/capabilities/enforcement_ops.py), [src/mcp_server_nucleus/runtime/capabilities/budget_ops.py](https://github.com/eidetic-works/nucleus-mcp/blob/main/src/mcp_server_nucleus/runtime/capabilities/budget_ops.py). The community has surfaced two practical gaps in this surface. **BUG-001** documented that placing `gc.collect()` and `np.savez()` before `.train()` invalidates the GROUND/ALIGN chain because TRL precomputes reference logprobs inside `.train()` itself ([issue #8](https://github.com/eidetic-works/nucleus-mcp/issues/8)). **BUG-002** flagged a silent skip path in the ref-logprob cache: when `_loaded_from_cache` is `True`, the post-precompute guard skips the save with no log line, leaving operators unable to confirm whether persistence happened ([issue #9](https://github.com/eidetic-works/nucleus-mcp/issues/9)). Both bugs reinforce the same lesson — verification must be observable, not assumed. ## Security: Autonomous Relay and Pseudonymous Audit The relay subsystem is the highest-trust surface because it forwards messages between agent roles. The `_relay_post_helper.py` module enforces six explicit mitigations before a relay call can return success: | Mitigation | Mechanism | |---|---| | Subject prefix | `[AUTONOMOUS]` forced at helper call site | | Sender lock | LLM cannot impersonate another sender role | | Body cap | 4096 chars, truncated by helper | | Rate limit | 20/hr per role, disk-persistent | | Audit log | Append-only `.brain/ledger/autonomous_relay_posts.jsonl` | | Body privacy | Content never written — only sha256 hash + char count | Source: [src/mcp_server_nucleus/sessions/_relay_post_helper.py](https://github.com/eidetic-works/nucleus-mcp/blob/main/src/mcp_server_nucleus/sessions/_relay_post_helper.py). The recipient set is itself an explicit enum (`main`, `peer`, `tb`, `operator_assistant`, `antigravity`, `antigravity_gq`, `antigravity_voice`, `cc_gq`, `gq`, `ultraplan`, `windsurf`, `board`), making typos non-fatal and validation deterministic. Source: [src/mcp_server_nucleus/sessions/autonomous_wake.py](https://github.com/eidetic-works/nucleus-mcp/blob/main/src/mcp_server_nucleus/sessions/autonomous_wake.py). The helper explicitly comments that audit failure must never block the forward — the ledger is best-effort, the network call is not. As of v1.13.0, the relay gained a bidirectional FS↔HTTP bridge daemon (`nucleus-relay-bridge`) with a launchd plist template under `deploy/mac/`, so the same audit contract now extends across the local↔cloud boundary ([release notes](https://github.com/eidetic-works/nucleus-mcp/releases/tag/v1.13.0)). ## Telemetry, CSR, and the Flywheel Loop Telemetry in nucleus-mcp is structurally opt-in as of v1.13.1. Fresh installs default to disabled; existing installs honor an explicit `telemetry.anonymous.enabled` flag in `nucleus.yaml`. The first `nucleus init` prompt asks `Enable anonymous telemetry? [y/N]` with **N** as the default ([release notes](https://github.com/eidetic-works/nucleus-mcp/releases/tag/v1.13.1)). The flywheel package is the bookkeeping layer. Its public API exposes `Flywheel`, `file_ticket`, `record_survived`, `bump_survived`, `bump_unsurvived`, `read_csr`, `render_dashboard_json`, `render_dashboard_html`, `generate_week_report`, and `curriculum_refresh`. Source: [src/mcp_server_nucleus/flywheel/__init__.py](https://github.com/eidetic-works/nucleus-mcp/blob/main/src/mcp_server_nucleus/flywheel/__init__.py). The **6-action accountability helper** turns every failure into six best-effort, idempotent records: a markdown memory note in `.brain/flywheel/pending_issues.jsonl`, a CSR unsurvived bump, a DPO training-pair seed appended to `unified_dpo_pending.jsonl`, a weekly report append, a GitHub issue attempt (graceful fallback when `gh` is missing or offline), and a task registration in `pending_tasks.jsonl`. If GitHub is unreachable, the other five still write so the loop keeps turning. Source: [src/mcp_server_nucleus/flywheel/core.py](https://github.com/eidetic-works/nucleus-mcp/blob/main/src/mcp_server_nucleus/flywheel/core.py). The dashboard surface (`render_dashboard_json`) projects CSR totals — `claims_total`, `claims_survived`, `claims_unsurvived`, and ratio — alongside open ticket, open task, and pending training-pair counts. Source: [src/mcp_server_nucleus/flywheel/dashboard.py](https://github.com/eidetic-works/nucleus-mcp/blob/main/src/mcp_server_nucleus/flywheel/dashboard.py). Weekly markdown reports (`generate_week_report`) scope tickets by ISO week, producing `week-N.md` files that preserve the append-only log below a regenerable header. Source: [src/mcp_server_nucleus/flywheel/report.py](https://github.com/eidetic-works/nucleus-mcp/blob/main/src/mcp_server_nucleus/flywheel/report.py). ## Common Failure Modes and Mitigations | Symptom | Likely Cause | Mitigation | |---|---|---| | `[OOM guard] GPU free` logged but cache state unknown | Silent skip in `_PostPrecomputeGuard` (BUG-002) | Patch guard to emit explicit `[cache] skipped/saved` line | | Verification runs but `.train()` produces no logprobs | Pre-`.train()` precomputation assumption (BUG-001) | Run `gc.collect()` + `np.savez()` inside the training callback | | Relay posts fail silently | Audit log write blocking the forward | Audit failures are caught and logged; check `autonomous_relay_posts.jsonl` | | CSR ratio drifts downward | Unsolved tickets accumulating | Run `Flywheel.curriculum_refresh()` to close the training loop | ## See Also - [Three Frontiers (v1.8.0 release notes)](https://github.com/eidetic-works/nucleus-mcp/releases/tag/v1.8.0) - [Opt-In Telemetry & Release-Protocol Audit (v1.13.1)](https://github.com/eidetic-works/nucleus-mcp/releases/tag/v1.13.1) - [Treatment Program & Relay v0.2 Bridge (v1.13.0)](https://github.com/eidetic-works/nucleus-mcp/releases/tag/v1.13.0) - [BUG-001: Callback timing](https://github.com/eidetic-works/nucleus-mcp/issues/8) - [BUG-002: Silent cache skip](https://github.com/eidetic-works/nucleus-mcp/issues/9) --- --- ## Pitfall Log Project: eidetic-works/nucleus-mcp Summary: Found 9 structured pitfall item(s), including 0 high/blocking item(s). Top priority: Installation risk - Installation risk requires verification. ## 1. Installation risk - Installation risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/eidetic-works/nucleus-mcp/issues/8 ## 2. Installation risk - Installation risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/eidetic-works/nucleus-mcp/issues/9 ## 3. Configuration risk - Configuration risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: capability.host_targets | https://github.com/eidetic-works/nucleus-mcp ## 4. Capability evidence risk - Capability evidence risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: README/documentation is current enough for a first validation pass. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: capability.assumptions | https://github.com/eidetic-works/nucleus-mcp ## 5. Maintenance risk - Maintenance risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: evidence.maintainer_signals | https://github.com/eidetic-works/nucleus-mcp ## 6. Security or permission risk - Security or permission risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: no_demo - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: downstream_validation.risk_items | https://github.com/eidetic-works/nucleus-mcp ## 7. Security or permission risk - Security or permission risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: no_demo - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: risks.scoring_risks | https://github.com/eidetic-works/nucleus-mcp ## 8. Maintenance risk - Maintenance risk requires verification - Severity: low - Evidence strength: source_linked - Finding: issue_or_pr_quality=unknown。 - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: evidence.maintainer_signals | https://github.com/eidetic-works/nucleus-mcp ## 9. Maintenance risk - Maintenance risk requires verification - Severity: low - Evidence strength: source_linked - Finding: release_recency=unknown。 - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: evidence.maintainer_signals | https://github.com/eidetic-works/nucleus-mcp