Related Pages

Related topics: The Three Frontiers (GROUND / ALIGN / COMPOUND), MCP Tools, CLI, Memory & Data Flow

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.

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.

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.

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. 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, 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. 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.

flowchart LR
  Client[MCP Client<br/>Claude Code / Cursor / Windsurf] -->|JSON-RPC| Server[nucleus-mcp server]
  Server --> Caps[Capability Layer<br/>code_ops / feature_map / proof_system / ...]
  Caps --> Brain[".brain/ on disk<br/>plain JSON + markdown"]
  Server --> Flywheel[Flywheel<br/>CSR + tickets + reports]
  Flywheel --> Brain
  Caps --> Agents["Agents<br/>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.

pip install nucleus-mcp

For local development against the source tree, set PYTHONPATH to src/ and invoke examples directly:

cd mcp-server-nucleus
export PYTHONPATH=src
python examples/basic_usage.py

Source: 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:

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

Source: 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.

Key configuration levers:

Sources: src/mcp_server_nucleus/runtime/capabilities/synthesizer.py, 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

Related Pages

Related topics: MCP Tools, CLI, Memory & Data Flow, Compliance, Governance, Telemetry & Security

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

flowchart LR
    A[AI writes code] --> B[GROUND<br/>5-tier verify]
    B -->|receipt| L[.brain/verification_log.jsonl]
    B --> C{Verdict}
    C -->|pass| D[CSR survived++]
    C -->|fail| E[ALIGN<br/>file_ticket]
    E --> F[6 actions:<br/>pending_issues<br/>CSR unsurvived<br/>unified_dpo_pending<br/>week-N.md<br/>gh issue<br/>pending_tasks]
    F --> G[COMPOUND<br/>curriculum_refresh]
    G --> H[Next DPO run]
    H --> A
    D --> I[Dashboard JSON/HTML<br/>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

Related Pages

Related topics: Overview, Installation & Configuration, The Three Frontiers (GROUND / ALIGN / COMPOUND), Compliance, Governance, Telemetry & Security

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:

# 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:

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):

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/<name>.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 — quick start, CLI examples, MCP client config
• v1.13.1 release notes — opt-in telemetry
• docs/RABBITHOLE.md — nucleus-rabbithole companion tool

Related Pages

Related topics: The Three Frontiers (GROUND / ALIGN / COMPOUND), MCP Tools, CLI, Memory & Data Flow

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.

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.

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.

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.

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.

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, 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). 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). 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:

Source: 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. 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).

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).

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.

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.

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. 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.

Common Failure Modes and Mitigations

See Also

• Three Frontiers (v1.8.0 release notes)
• Opt-In Telemetry & Release-Protocol Audit (v1.13.1)
• Treatment Program & Relay v0.2 Bridge (v1.13.0)
• BUG-001: Callback timing
• BUG-002: Silent cache skip

Doramagic Pitfall Log

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
• 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.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/eidetic-works/nucleus-mcp/issues/8

2. Installation risk: Installation risk requires verification

• Severity: medium
• 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.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/eidetic-works/nucleus-mcp/issues/9

3. Configuration risk: Configuration risk requires verification

• Severity: medium
• 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.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.host_targets | https://github.com/eidetic-works/nucleus-mcp

4. Capability evidence risk: Capability evidence risk requires verification

• Severity: medium
• Finding: README/documentation is current enough for a first validation pass.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.assumptions | https://github.com/eidetic-works/nucleus-mcp

5. Maintenance risk: Maintenance risk requires verification

• Severity: medium
• 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.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/eidetic-works/nucleus-mcp

6. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• 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
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: risks.scoring_risks | https://github.com/eidetic-works/nucleus-mcp

8. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: issue_or_pr_quality=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/eidetic-works/nucleus-mcp

9. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: release_recency=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/eidetic-works/nucleus-mcp

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using nucleus-mcp with real data or production workflows.

• BUG-002: Silent skip path in ref logprob cache — no feedback when save i - github / github_issue
• BUG-001: GROUND/ALIGN missed execution-order verification (callback timi - github / github_issue
• v1.13.1 — Opt-In Telemetry + Release-Protocol Audit - github / github_release
• v1.13.0 — Treatment Program + Relay v0.2 Bridge - github / github_release
• v1.8.0 — Three Frontiers - github / github_release
• Repository reset: Please re-star nucleus-mcp - github / github_release
• Configuration risk requires verification - GitHub / issue