Operator Knowledge Base

This guide is organized around the jobs an operator actually performs in the console: understand current state, inspect memory, inspect runs, trust the system, and only then open advanced controls.

1. How Memory Works Across Clients

Nexus Prime runs as a local-first MCP control plane. It sits between the driving client and the repo, providing shared memory recall, orchestration, runtime selection, verification, and persisted dashboard truth across Codex, Claude Code, Windsurf, and other connected clients.

Mental Model

Treat Nexus Prime as an operator console backed by a local memory layer. Start non-trivial work with nexus_session_bootstrap, let nexus_orchestrate choose the runtime path by default, and inspect the packet, ledger, memory trace, token telemetry, and usage snapshots when you need to understand what actually happened. Shared memory is designed to survive client switches; repo state, approvals, and destructive actions remain local to the active workspace.

Memory is now split into four operator-facing lanes: workspace for repo and project knowledge, profile for stable user preferences, shared for explicitly shared verified learnings, and inbox for noisy or unverified candidates. Workspace memory is repo-scoped by default, so architecture decisions from one repository do not silently leak into another.

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, trust review, and advanced override cases.

Mandatory Client Lifecycle

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.
Optimize before broad reading: Call nexus_optimize_tokens before reading 3+ files from client-visible intent.
Run governance before mutation: Call nexus_mindkit_check before any file modification or destructive work, and use nexus_ghost_pass before refactoring 3+ files.
Store and close explicitly: nexus_orchestrate does not replace nexus_store_memory or nexus_session_dna at session close.

3. Inspect a Run

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 current runtime health, the latest run, lifetime totals, and per-run details even after restart.

The run surfaces now expose per-gate evidence instead of one global pass/fail bit. That means you can see which review gates were ready, blocked, planned, or skipped, why a specialist or workflow was selected or rejected, and how token optimization changed the prompt budget before execution.

Operator transcript example

Called Nexus Session Bootstrap tool from Nexus Prime MCP

Session bootstrap ready.
- Client: Codex (primaryActive)
- Recommended next step: nexus_orchestrate
- Token optimization: required
- Knowledge fabric: repo

4. Memory, Local State, and Advanced Controls

Memory and Context Sources

Tool Name	Required Params	Description
nexus_recall_memory	`query` (str), `k` (num)	Performs a Vector/TF-IDF similarity search across the local SQLite memory database and retrieves historical context.
nexus_store_memory	`content` (str), `priority` (num), `tags` (arr)	Persists an insight to local memory. Durable storage defaults to user plus repo/workspace context; low-confidence or contradictory memory is routed to inbox or quarantine instead of polluting active recall.
nexus_memory_stats	None	Returns Zettelkasten metrics: total nodes, dominant tags, and cache tier capacities.

What Stays Local

By default, Nexus Prime remains single-binary and local-first. Memory lives in the configured local state directory. If the requested memory database path is readonly, Nexus Prime falls back to a writable Nexus state location and reports that fallback in dashboard health so operators can see it instead of silently losing writes.

Before any compaction or model summary step, Nexus Prime writes an immutable pre-compaction backup bundle. Operators can inspect that backup path in the Trust surface to prove that raw evidence was preserved before summarization or forgetting logic ran.

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 destructive guard filters.

Advanced Controls

The operator console now keeps advanced controls behind an explicit fold. The default path is: search memory, inspect a run, launch a guided task, then open advanced controls only when you need asset selection, backend override, or worker tuning.

Parallel execution remains guarded. Nexus Prime caps default autonomous worker fan-out, shows the bounded worker plan in the Runs surface, and keeps the selection audit visible so operators can explain why a given specialist, skill, or workflow was chosen for investor demos or production debugging.

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.

Investor-Proof Use Cases

Repo-scoped engineering memory: architecture decisions, bug fixes, and file-boundary knowledge stay attached to the active repository.
Cross-session investigation: root causes and verified fixes recall cleanly while chat noise and orchestration chatter stay out of the active working set.
Explainable autonomy: runs show token savings, gate evidence, selected assets, rejected assets, and bounded parallel execution before any advanced override is opened.

5. Trust, Quarantine, and Guardrails

Nexus Prime acts as the enforcement layer for the policies defined by the sir-ad/mindkit repository. Trust surfaces explain quarantine, guardrails, worktree health, and federation state without forcing operators to inspect the full control plane first.

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.

Trust surfaces also show MCP interpretation issues explicitly. When low-confidence selector matches are rejected, when noisy memory is quarantined, or when a stale runtime would make mutation unsafe, the dashboard exposes that reasoning directly instead of leaving operators to infer it from logs.

When to Open Advanced Controls

Open advanced controls when you need explicit worker counts, backend overrides, deploy/revoke actions, or direct trust review. Keep the default console path simple for routine operation; escalate only when the surface data tells you a run, memory, or trust condition actually needs intervention.

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.