Developer Knowledge Base

This page is for operators and integrators who need to understand how Nexus Prime behaves at runtime, how the MCP path should be used, and what the dashboard is actually reporting.

1. Introduction

Nexus Prime runs as a local-first MCP control plane. It sits between the driving client and the repo, providing memory recall, orchestration, runtime selection, verification, and persisted dashboard truth.

Mental Model

Treat Nexus Prime as a control plane. Start non-trivial work with nexus_session_bootstrap, let nexus_orchestrate choose the runtime path by default, and inspect the packet, ledger, token telemetry, and usage snapshots when you need to understand what actually happened.

2. Client Operating Guideline

External clients should follow a compact sequence instead of manually chaining every subsystem. The default path is bootstrap first, orchestrate second, with explicit low-level tools reserved for diagnostics and expert override cases.

Recommended Client Sequence

When coding in a Nexus Prime environment, use these principles:

Bootstrap first: Start non-trivial work with nexus_session_bootstrap.
Orchestrate by default: Call nexus_orchestrate with the raw request unless the operator explicitly wants low-level control.
Inspect plans on request: Use nexus_plan_execution only when you want the ledger before mutation.
Treat token routing as runtime truth: Use nexus_optimize_tokens manually only when you need to inspect or override the reading plan.
Store durable learnings: Close meaningful work with nexus_store_memory and nexus_session_dna.

3. Reading Session Telemetry

Nexus Prime automatically formats its log outputs back to the MCP Client using Grain primitives. Every successful MCP action appends a state header to the response:

<state type="telemetry">
─── 📡 Nexus Prime (12s) ───
3 calls │ 20.3k tokens saved │ 2 stored │ 5 recalled
</state>

Operators do not need to parse this by hand. The dashboard and runtime snapshot persist the same state so you can inspect lifetime totals and per-run details even after restart.

4. API Reference

Memory Operations

Tool Name	Required Params	Description
nexus_recall_memory	`query` (str), `k` (num)	Performs a Vector/TF-IDF similarity search across the SQLite Cortex database. Retrieves historical context.
nexus_store_memory	`content` (str), `priority` (num), `tags` (arr)	Persists an insight to the Cortex. Priority > 0.8 keeps the memory active in the Hippocampus cache.
nexus_memory_stats	None	Returns Zettelkasten metrics: total nodes, dominant tags, and cache tier capacities.

Intelligence Ops

Tool Name	Required Params	Description
nexus_optimize_tokens	`task` (str), `files` (arr)	Evaluates codebase relevancy relative to your task. Returns a strict reading plan (Read, Outline, Skip).
nexus_ghost_pass	`goal` (str), `files` (arr)	Performs a read-only AST simulation on target files to spot syntax risks and breaking changes before they happen.
nexus_mindkit_check	`action`, `filesToModify`	Strict policy evaluation. Returns PASS/FAIL based on Token Budgets and the Destructive Guard filters.

Parallel Workers

Tool Name	Required Params	Description
nexus_spawn_workers	`goal` (str), `files` (arr)	Spawns headless Phantom Workers into isolated `git worktrees`. Evaluates differing solutions via Byzantine Merge Oracle.
nexus_audit_evolution	None	Reads the SQLite history for "hotspot" files that break frequently. Pushes these evolution candidates back to MindKit sync.

5. MindKit Guardrails & Sync

Nexus Prime acts as the enforcement layer for the policies defined by the sir-ad/mindkit repository.

Destructive File Protection

Any agent attempting to rewrite configurations spanning more than 10 files simultaneously will automatically trigger the BULK_FILE_GUARD. The MCP server will respond with a warning exception requesting a fallback to a nexus_ghost_pass.

Bidirectional MindKit Sync

When the nexus_audit_evolution tool runs, Nexus Prime pushes analytical telemetry directly back to the MindKit repository via the GitHub REST API. This forms a continuous feedback loop where MindKit's rules get smarter based on the bugs you encounter in your local environment.