What is the Neural Link?

The Neural Link is a bi-directional bridge that connects AI agents directly to the Neo.mjs runtime. It lets agents inspect the Scene Graph, component state, event listeners, computed styles, and DOM rectangles, and mutate the running application in real time.

Why is Neo.mjs called an Application Engine instead of a framework?

Neo.mjs maintains persistent application objects in a worker-backed Scene Graph instead of compiling application state away into ephemeral DOM nodes. That architecture enables multi-window orchestration, runtime permutation, and deep AI introspection.

What is Context Engineering?

Context Engineering shapes the information and tool environment around AI agents. Neo.mjs implements it through Knowledge Base, Memory Core, GitHub Workflow, and Neural Link MCP servers for frontier harnesses, plus a File System MCP server for internal Neo.ai.Agent local loops.

What is the Neo.mjs Agent OS?

The Neo.mjs Agent OS is the repository Brain: source code and services for Memory Core, Knowledge Base, Active Hybrid GraphRAG, DreamService, Golden Path synthesis, A2A coordination, and Neural Link tooling.

Neo.mjs - Self-Evolving Software Organism

Frontmatter

title	docs: add Agent OS Architecture Overview guide (#9981)
author	tobiu
state	Merged
createdAt	Apr 13, 2026, 7:58 PM
updatedAt	Apr 13, 2026, 8:09 PM
closedAt	Apr 13, 2026, 8:09 PM
mergedAt	Apr 13, 2026, 8:09 PM
branches	`dev` ← `agent/9981-architecture-overview-guide`
url	https://github.com/neomjs/neo/pull/9982

Merged

tobiu commented on Apr 13, 2026, 7:58 PM

Summary

Adds a new top-level guide learn/agentos/ArchitectureOverview.md to the learning portal, providing a comprehensive architectural map of the Neo.mjs Agent OS. Registered as the first child of the "Agent OS & Conversational UIs" section in tree.json.

What This Guide Covers

Two Hemispheres — How the frontend runtime engine and the Agent OS share a common class system
Runtime Engine — Multi-worker architecture, triangular VDOM optimization, SharedWorker mode
Agent OS — Cognitive loop (Perceive/Reason/Act/Reflect), SDK Bouncer pattern, five MCP servers
Neural Link Bridge — WebSocket connection between Node.js agents and the live browser application
Dream Pipeline — Six-phase REM pipeline including deterministic capability gap inference
The Closed Loop — The self-improving feedback architecture that makes Neo unique
Structural Inventory — Package-level reference tables for both hemispheres

Includes 6 Mermaid diagrams and cross-links to all sibling Agent OS guides.

Files Changed

[NEW] learn/agentos/ArchitectureOverview.md — The guide
[MODIFY] learn/tree.json — Added entry before Strategic Workflows

Architectural Impact

Closes a GUIDE_GAP for the Agent OS top-level namespace. The existing guides cover individual MCP servers but there was no entry point that ties the system together. This guide serves as the conceptual map for both human contributors and future agent instances.

Resolves #9981

tobiu commented on Apr 13, 2026, 8:08 PM

Input from Claude Opus 4.6 (Antigravity):

❋ # PR Review Summary

Status: Approved (after self-correcting polish commit)

The guide provides a comprehensive, well-structured architectural map of the full Neo.mjs platform. During the review reflection phase, one bug was identified and fixed: the "Next Steps" cross-links were broken after the file was relocated from learn/agentos/ to learn/benefits/. A polish commit has been pushed.

📊 Evaluation Metrics

[ARCH_ALIGNMENT]: 92 - Accurately represents the two-hemisphere architecture, worker topology, and Agent OS cognitive loop. File placement was challenged mid-session and corrected from AgentOS to Benefits for discoverability.

[CONTENT_COMPLETENESS]: 90 - Comprehensive coverage of 7 sections with 6 Mermaid diagrams, 2 structural inventory tables, and cross-links. No JSDoc required (markdown guide). Cross-reference added to CodebaseOverview.

[EXECUTION_QUALITY]: 88 - Self-review caught broken cross-links from the relocation (all 6 ./ paths needed ../agentos/). Fixed in polish commit. All Mermaid diagrams use ASCII-safe labels (lesson learned from classDef graph reserved keyword issue).

[PRODUCTIVITY]: 95 - All three acceptance criteria from #9981 addressed: guide created, tree.json updated, cross-reference in CodebaseOverview added.

[IMPACT]: 65 - Closes a GUIDE_GAP for the platform-level architecture. High value for onboarding but no code changes.

[COMPLEXITY]: 30 - Documentation-only PR with 3 files touched. Low cognitive load.

[EFFORT_PROFILE]: Quick Win - High discoverability ROI for minimal complexity.

🕸️ Context & Graph Linking

Target Issue: Resolves #9981

Related Graph Nodes: DreamService, Neo.ai.Client, ContextAssembler, Agent.Loop

Origin Session: 70334eab-72c9-44a6-8f48-0b6a96604f49

🧠 Graph Ingestion Notes

[KB_GAP]: N/A — this PR closes a KB gap.

[TOOLING_GAP]: Mermaid's reserved keyword graph cannot be used as a classDef name. This caused a silent parse error. Future Mermaid diagrams should avoid graph, subgraph, end, direction as class identifiers.

[RETROSPECTIVE]: The placement challenge (AgentOS → Benefits) was the most valuable part of this PR. The user's instinct for discoverability over taxonomic purity is correct — in a tree-list sidebar, two clicks of nesting makes content invisible. This principle should be applied when creating future guides.

📋 Required Actions

None — all issues were caught and fixed during the reflection phase.

Guide relocated to learn/benefits/ArchitectureOverview.md

tree.json positions it as second child of Benefits (after Introduction)

Cross-reference added to CodebaseOverview.md

Cross-links fixed after relocation (./ → ../agentos/)

LGTM — ready to merge.