LearnNewsExamplesServices
Frontmatter
id9981
title[Guide] Agent OS Architecture Overview
stateClosed
labels
documentationenhancementai
assigneestobiu
createdAtApr 13, 2026, 7:53 PM
updatedAtApr 13, 2026, 8:09 PM
githubUrlhttps://github.com/neomjs/neo/issues/9981
authortobiu
commentsCount0
parentIssuenull
subIssues
9985 docs: add "The Dream Pipeline & Golden Path" guide
9986 docs: add "Progressive Disclosure Skills" guide
subIssuesCompleted2
subIssuesTotal2
blockedBy[]
blocking[]
closedAtApr 13, 2026, 8:09 PM

[Guide] Agent OS Architecture Overview

Closeddocumentationenhancementai
tobiu
tobiu commented on Apr 13, 2026, 7:53 PM

Summary

Add a new top-level guide agentos/ArchitectureOverview to the learning portal that provides a comprehensive architectural map of the Neo.mjs Agent OS.

Motivation

The "Agent OS & Conversational UIs" section currently has guides for individual MCP servers (Neural Link, Knowledge Base, Memory Core, GitHub Workflow, Code Execution) and Strategic Workflows, but no entry point that ties the entire system together. A developer or contributor encountering the Agent OS for the first time has no single document that explains:

  1. How the frontend runtime engine and the Agent OS relate as "two hemispheres" of a single platform
  2. The cognitive loop (Perceive → Reason → Act → Reflect)
  3. The DreamService REM pipeline (6 phases including deterministic gap inference)
  4. The closed feedback loop that makes the system self-improving
  5. The Neural Link bridge between Node.js agents and the live browser application

Proposed Changes

1. New Guide: learn/guides/agentos/ArchitectureOverview.md

  • Adapted from the architectural artifact created in session 70334eab
  • Sections: Two Hemispheres, Runtime Engine, Agent OS, Neural Link Bridge, Dream Pipeline, The Closed Loop, Structural Inventory
  • Remove internal meta-commentary (Gemini comparison section) — reorient for external audience
  • Include Mermaid diagrams throughout

2. Update: learn/tree.json

  • Add entry "Architecture Overview" as the first child of "AgentOS" (parentId: "AgentOS", id: "agentos/ArchitectureOverview")
  • Position before "Strategic Workflows" to serve as the conceptual entry point

Acceptance Criteria

  • Guide renders correctly in the learning portal with all Mermaid diagrams
  • tree.json updated and the guide appears first under "Agent OS & Conversational UIs"
  • Knowledge Base re-synced (manage_knowledge_base sync) so the guide is discoverable via ask_knowledge_base

A2A Context

  • Origin Session ID: 70334eab-72c9-44a6-8f48-0b6a96604f49
  • Source Artifact: architecture_diagram.md in the session artifacts directory
  • Architectural Rationale: Closes a GUIDE_GAP identified by the DreamService for the Agent OS top-level namespace. The guide serves both human contributors and future agent instances that need to understand the system topology before performing modifications.
tobiu added the documentation label on Apr 13, 2026, 7:53 PM
tobiu added the enhancement label on Apr 13, 2026, 7:53 PM
tobiu added the ai label on Apr 13, 2026, 7:53 PM
tobiu referenced in commit 297c547 - "docs: add Agent OS Architecture Overview guide (#9981)" on Apr 13, 2026, 7:57 PM
tobiu cross-referenced by PR #9982 on Apr 13, 2026, 7:58 PM
tobiu referenced in commit 0619a0b - "docs: add Architecture Overview guide to Benefits section (#9981)" on Apr 13, 2026, 8:03 PM
tobiu referenced in commit 435ce2f - "docs: add cross-reference to Architecture Overview from CodebaseOverview (#9981)" on Apr 13, 2026, 8:06 PM
tobiu assigned to @tobiu on Apr 13, 2026, 8:07 PM
tobiu referenced in commit 2362e4c - "fix: correct cross-link paths after moving guide to benefits/ (#9981)" on Apr 13, 2026, 8:08 PM
tobiu referenced in commit fc6bf3c - "docs: add Agent OS Architecture Overview guide (#9981) (#9982) on Apr 13, 2026, 8:09 PM
tobiu closed this issue on Apr 13, 2026, 8:09 PM
tobiu referenced in commit e246537 - "chore: fix guide title to 'Neo.mjs Architecture Overview' (#9981)" on Apr 13, 2026, 8:17 PM
tobiu cross-referenced by #9983 on Apr 13, 2026, 8:24 PM
tobiu cross-referenced by PR #9984 on Apr 13, 2026, 8:27 PM
tobiu cross-referenced by #9985 on Apr 13, 2026, 8:51 PM
tobiu cross-referenced by #9986 on Apr 13, 2026, 8:51 PM
tobiu added sub-issue #9985 on Apr 13, 2026, 8:51 PM
tobiu added sub-issue #9986 on Apr 13, 2026, 8:51 PM
tobiu cross-referenced by PR #9987 on Apr 13, 2026, 8:59 PM