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: Refactor Agent Startup Workflow to delay UI Guide loading (#9873)
author	tobiu
state	Merged
createdAt	Apr 11, 2026, 9:59 AM
updatedAt	Apr 11, 2026, 6:11 PM
closedAt	Apr 11, 2026, 10:02 AM
mergedAt	Apr 11, 2026, 10:02 AM
branches	`dev` ← `agent/9873-startup-workflow`
url	https://github.com/neomjs/neo/pull/9874

Merged

tobiu commented on Apr 11, 2026, 9:59 AM

The Problem

During the mandatory initialization sequence defined in AGENTS_STARTUP.md, Step 4 dictated that the agent should read learn/gettingstarted/DescribingTheUI.md. However, at this specific point in the boot cycle, the agent has not yet fetched the Context Frontier or interacted with the user to determine if the task actually involves frontend UI components. Reading UI guides prematurely when the task might be backend or infrastructure-related wastes cognitive bandwidth and violates context scoping protocols.

The Architectural Reality

The current instructions linearly enforced frontend document processing before the Memory Core determined the strategic task. This flaw has caused agents in past sessions to pollute their initial context window with UI assumptions.

The Solution Implementation

Removed Step 4: Understand the Two Component Models from the rigid, domain-agnostic session initialization loop in AGENTS_STARTUP.md.
Repositioned the requirement to read DescribingTheUI.md as a conditional mandate inside the Implementation Loop (Section 4), explicitly stating that the document should only be loaded after the agent confirms the task involves frontend DOM/VDOM components. This ensures the session initialization remains lean and task-agnostic.

Resolves #9873

tobiu commented on Apr 11, 2026, 10:00 AM

Input from Antigravity (Gemini 3.1 Pro):

✦ # PR Review Summary

Status: Approved

Excellent initiative! Identifying and correcting flaws within our operational protocols strengthens the entire agent swarm. Your refactoring of the initialization sequence directly addresses previous failure modes and ensures a much tighter contextual adherence.

📊 Evaluation Metrics

[ARCH_ALIGNMENT]: 100 - Perfect alignment with the Swarm Architecture's need for lean, domain-agnostic initialization.

[CONTENT_COMPLETENESS]: 100 - The PR body fully adheres to the "Fat Ticket" protocol, clearly detailing the problematic architecture and the solution implementation.

[EXECUTION_QUALITY]: 100 - The logic is sound. Decoupling the frontend guide reading until the task domain logic is confirmed eliminates premature caching of irrelevant views.

[PRODUCTIVITY]: 100 - Solved precisely what was requested.

[IMPACT]: 60 - Eliminates repeated context corruption across all future agent sessions.

[COMPLEXITY]: 10 - A simple file change, but very high conceptual return on investment.

[EFFORT_PROFILE]: Quick Win - High ROI/Low Complexity. This immediately fixes an annoyance without deep code restructuring.

🕸️ Context & Graph Linking

Target Epic / Issue ID: Resolves #9873

Related Graph Nodes: agent-startup, contextual-scoping, ui-guide

🧠 Graph Ingestion Notes

[RETROSPECTIVE]: Excellent application of self-evolving system protocols. When a procedure is identified as insufficient, modifying the core directives (AGENTS_STARTUP.md) is exactly the mandated behavior for long-term swarm stability.

📋 Required Actions

To proceed with merging, please address the following:

Squash Merge this PR to ensure the Fat Ticket context is bound to the trunk history.

LGTM!