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 Swarm Intelligence & Autonomous Sub-Agents guide (#9983)
author	tobiu
state	Merged
createdAt	Apr 13, 2026, 8:27 PM
updatedAt	Apr 13, 2026, 8:31 PM
closedAt	Apr 13, 2026, 8:31 PM
mergedAt	Apr 13, 2026, 8:31 PM
branches	`dev` ← `agent/9983-swarm-intelligence-guide`
url	https://github.com/neomjs/neo/pull/9984

Merged

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

Summary

Adds a new guide learn/agentos/SwarmIntelligence.md documenting the autonomous narrow sub-agent architecture built on Neo.ai.Agent.

What This Guide Covers

The Delegation Model — How Agent.delegate() boots sub-agents with their own cognitive loops
Three Profiles — Librarian (research), QA Bot (local test generation), Browser (visual inspection)
Capability Gating — Server-level isolation + SDK Zod validation boundary
Cost Control — Local vs cloud inference tiering (QA on Gemma = zero marginal cost)
Context Window Management — maxSubAgentLifespan recycling to prevent hallucination drift
The delegate_task Native Tool — How the LLM autonomously decides when to delegate
Event Scheduler — Priority queue (critical > high > normal > low) for event processing
Orchestrator Pipeline — Golden Path parsing from sandman_handoff.md
Adding New Profiles — Step-by-step guide for extending the swarm

Includes 4 Mermaid diagrams.

Files Changed

[NEW] learn/agentos/SwarmIntelligence.md — The guide
[MODIFY] learn/tree.json — Registered after Strategic Workflows in Agent OS section
[MODIFY] learn/benefits/ArchitectureOverview.md — Added cross-link in Next Steps

Architectural Impact

Closes the GUIDE_GAP for the swarm intelligence layer. The Architecture Overview (#9981) treats the Agent OS as a monolithic cognitive loop — this guide decomposes it into the delegation hierarchy that actually exists in the codebase.

Resolves #9983

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

Input from Claude Opus 4.6 (Antigravity):

❋ # PR Review Summary

Status: Approved

This guide fills the most significant documentation gap identified during the Architecture Overview session (#9981). The existing guides treat the Agent OS as a monolithic loop — this PR decomposes it into the delegation hierarchy that actually exists in ai/Agent.mjs. The cross-reference in CodebaseOverview.md ensures fresh agent sessions won't be blindsided by the swarm layer (as I was earlier today).

📊 Evaluation Metrics

[ARCH_ALIGNMENT]: 95 - Accurately reflects the source: delegate() lifecycle matches Agent.mjs:195-241, profile configs match all three profile files, Scheduler priority heuristics match Scheduler.mjs:83-88, Orchestrator Golden Path regex matches Orchestrator.mjs:49.

[CONTENT_COMPLETENESS]: 93 - Covers 9 distinct concepts across 370 lines with 4 Mermaid diagrams, code examples, structural inventory, and a "how to add new profiles" section. Cross-references added to both Architecture Overview and CodebaseOverview.

[EXECUTION_QUALITY]: 92 - All Mermaid diagrams use ASCII-safe labels and avoid the graph reserved keyword issue. Relative paths verified (../benefits/, ./ for siblings). No broken links.

[PRODUCTIVITY]: 100 - All acceptance criteria from #9983 addressed: delegation model, three profiles, capability gating, cost control, context management, and tree.json registration.

[IMPACT]: 75 - Closes a GUIDE_GAP for a core architectural layer. Higher impact than the Architecture Overview because this documents the safety mechanisms (server isolation + Zod) that prevent destructive agent behavior.

[COMPLEXITY]: 35 - Documentation-only PR with 4 files touched. Source code was read but not modified.

[EFFORT_PROFILE]: Quick Win - High ROI for documentation discoverability with low implementation complexity.

🕸️ Context & Graph Linking

Target Issue: Resolves #9983

Related Graph Nodes: Neo.ai.Agent, Neo.ai.agent.Loop, Neo.ai.agent.Orchestrator, Neo.ai.agent.Scheduler, Neo.ai.agent.profile.Librarian, Neo.ai.agent.profile.QA, Neo.ai.agent.profile.Browser, Neo.ai.services

Parent: #9981 (Architecture Overview — this guide decomposes its "Right Hemisphere" section)

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

🧠 Graph Ingestion Notes

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

[TOOLING_GAP]: None encountered during this PR.

[RETROSPECTIVE]: The user's challenge to add a CodebaseOverview.md cross-reference was the most architecturally valuable insight. Without it, agents read CodebaseOverview during startup and see the "two hemispheres" but have zero awareness that the Agent OS delegates to narrow sub-agents. This session proved the gap empirically — I (the agent) had to be told about the profiles. The cross-reference closes the feedback loop: agent reads CodebaseOverview → discovers delegation model exists → queries knowledge base for details → operates with full architectural awareness.

📋 Required Actions

None — all polish was addressed pre-PR.

Guide created at learn/agentos/SwarmIntelligence.md

Registered in tree.json after Strategic Workflows

Cross-link added to Architecture Overview Next Steps

Cross-link added to CodebaseOverview (startup discovery path)

LGTM — ready to merge.