Neo.mjs Architecture Overview

This guide provides a top-level architectural map of the Neo.mjs Agent OS. It traces the vertical path of intelligence — from a user clicking a button, through the worker threads, up into the Agent OS, through the dream pipeline, and back down as an improved codebase.

For setup and configuration of individual MCP servers, see the dedicated guides linked at the bottom of this document.

The Two Hemispheres

Neo.mjs is a single platform with two distinct hemispheres that share a common nervous system — the Neo Class System:

Both hemispheres are built on the same Neo.core.Base class system. DreamService, GraphService, Agent, Loop, and every MCP service extend Neo.core.Base and use Neo.setupClass() exactly like Neo.button.Base or Neo.grid.Container. The AI infrastructure is not a separate project — it is a native inhabitant of the framework it maintains.

Left Hemisphere: The Runtime Engine

The runtime is Neo's core value proposition. All application logic runs off the Main Thread inside a multi-worker architecture:

Key Concepts

• App Worker: Hosts all components, controllers, state providers, and business logic. This is where your application code lives.
• VDom Worker: A dedicated thread for the JSON diff engine. It receives VDOM blueprints from the App Worker and computes minimal delta updates.
• Data Worker: Handles stores, models, sorting, filtering, and grouping — keeping heavy data operations off the main thread.
• Main Threads: Thin clients that only apply DOM mutations. Each browser window has its own main thread, but they all connect to the same App Worker.

The Triangular Optimization

VDOM updates follow an optimized triangular path:

1. App Worker sends the new JSON VDOM tree to the VDom Worker
2. The Main Thread intercepts the VDom Worker's reply and applies delta mutations to the DOM immediately
3. Main Thread forwards confirmation back to the App Worker

This eliminates a full round-trip vs naively routing updates through the App Worker.

SharedWorker Mode

When useSharedWorkers: true, the App Worker becomes a SharedWorker. Multiple browser windows connect to the same App Worker instance, sharing a single JavaScript heap. Components can be moved between windows — unmounted from one, remounted in another — without losing state. This is the foundation of Neo's multi-window application support.

Right Hemisphere: The Agent OS

The Agent OS is a Node.js infrastructure that provides AI agents with persistent memory, semantic understanding of the codebase, and the ability to introspect the live running application:

The Cognitive Loop

The agent runtime (ai/agent/Loop.mjs) implements a four-phase cognitive loop:

1. Perceive: The ContextAssembler fetches long-term memory (session summaries via RAG), short-term memory (recent session history), and skill metadata to build the LLM context window.
2. Reason: The assembled context is sent to the LLM (e.g., Claude Opus, Gemini) for inference, producing a response that may include tool calls.
3. Act: Tool calls are executed via the MCP protocol (for frontier models) or the SDK (for sub-agents with Zod validation).
4. Reflect: Every thought, decision, and tool call is persisted via add_memory(), creating the episodic memory record that the DreamService will later digest.

The SDK Bouncer Pattern

ai/services.mjs is the critical safety layer. It loads OpenAPI specs from each MCP server and wraps each method with makeSafe() — a function that generates Zod validators at startup.

• Frontier models (Opus, Gemini) access services via MCP protocol (stdio) with unbounded tool access.
• Sub-agents (e.g., Gemma 4-31B for doc patching) access the same services via the SDK, but every call is runtime-validated against the OpenAPI schema, preventing hallucinated JSON from reaching internal databases.

The Five MCP Servers

The Neural Link Bridge

The Neural Link is the connection point between the two hemispheres. It allows the Agent OS to reach into the running browser application:

The AI does not scrape DOM. It queries the semantic component tree directly — asking for components by ntype, reading store data, inspecting state providers, and even hot-patching methods on class prototypes at runtime. The same WebSocket bridge serves both AI agents and Playwright test fixtures, creating a unified "Whitebox E2E" testing architecture.

How it Works

1. The Neo.ai.Client singleton lives inside the App Worker (browser-side)
2. It connects to the Neural Link MCP Server via WebSocket (JSON-RPC 2.0)
3. The MCP Server exposes 5 client-side service categories: Component, Data, Instance, Interaction, and Runtime
4. When a new browser window connects, the client rehydrates the full window topology to the Agent OS

The Dream Pipeline

The DreamService is an autonomous background daemon that runs when agents are idle. It is the mechanism by which the system learns from itself:

The Six Phases

1. File Ingest: FileSystemIngestor.syncWorkspaceToGraph() scans the repository and ingests issues, markdown files, and source files into the Native Edge Graph (SQLite).

2. Tri-Vector Extraction: A local LLM (MLX / OpenAI-compatible) analyzes undigested session memories and extracts three vectors: semantic graph nodes and edges, the feature namespace being worked on, and any roadmap impact.

3. Topological Conflict Detection: Another LLM pass scans for tickets that have been rendered obsolete, superseded, or duplicated by recent session decisions. Alerts are written to sandman_handoff.md.

4. Capability Gap Inference: This phase is deterministic — it does not use an LLM. It cross-references graph nodes directly against the filesystem:

   • Does test/ contain files matching this class's tokens? If not: TEST_GAP
   • Does learn/guides/ have a matching guide? If not: GUIDE_GAP

5. Hebbian Decay: Universal edge weight fade and garbage collection of stale nodes, inspired by synaptic pruning in neuroscience.

6. Golden Path Synthesis: Tri-Vector scoring of all OPEN issues, producing a prioritized roadmap written to sandman_handoff.md. This file is the strategic dashboard that the next agent instance reads on boot.

The Closed Loop

This is the architecture's gravitational center. Every piece connects into a single self-improving feedback loop:

The agent's improvements to the framework also improve the agent's knowledge base, which improves the agent's future decisions. This is what distinguishes Neo.mjs from tools that provide memory, orchestration, or multi-agent roles in isolation — Neo builds the complete organism where the codebase and the agent co-evolve.

Structural Inventory

Runtime Engine (Browser)

Agent OS (Node.js)

Post-M6 (#10986) the per-MCP-server services were lifted from ai/mcp/server/<name>/services/ into the flat SDK boundary at ai/services/<name>/. The ai/mcp/server/<name>/ directories now host only the server entry-point (Server.mjs), config templates, logger, and shared helpers; the service implementations live under ai/services/<name>/. Both rows are listed below for navigability.

Architectural Decision Records

The Agent OS subsystem records its load-bearing architectural trade-offs in learn/agentos/decisions/. Every cross-system trade-off — i.e. one that touches multiple subsystems, sets a precedent for future code, or affects load-bearing invariants — earns an ADR (per the structural-pre-flight skill's Strategy-vs-Tactics threshold). Per-class localized constraints stay inline as Anchor & Echo guards instead.

The map-as-pointer principle: the Structural Inventory above links each subsystem row to its relevant ADRs so readers who follow the map naturally encounter the architectural-decision substrate without needing to remember to consult decisions/ separately. Authors of new ADRs MUST add the link to the affected Structural Inventory rows in the same PR (per #10449 Sub-Issue 2 / structural-pre-flight map-maintenance discipline).

Next Steps

• Strategic Workflows — Advanced agent workflow patterns
• Swarm Intelligence & Sub-Agents — Delegation, profiles, and capability gating
• The Dream Pipeline & Golden Path — Forecasting engine and scoring algorithm
• Neural Link: Live Application Mutability — Deep dive into the Neural Link bridge
• The Knowledge Base Server — Semantic RAG architecture
• The Memory Core Server — Episodic memory and graph storage
• The GitHub Workflow Server — Offline-first issue management
• Code Execution (AI SDK) — The SDK Bouncer pattern in detail