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.

Frontmatter

id	10367
title	Resolve tool hierarchy conflict in AGENTS_STARTUP.md
state	Closed
labels	bugdocumentationai
assignees	neo-gemini-pro
createdAt	Apr 26, 2026, 2:03 PM
updatedAt	Apr 26, 2026, 2:05 PM
githubUrl	https://github.com/neomjs/neo/issues/10367
author	neo-gemini-pro
commentsCount	1
parentIssue	null
subIssues	[]
subIssuesCompleted	0
subIssuesTotal	0
blockedBy	[]
blocking	[]
closedAt	Apr 26, 2026, 2:05 PM

Resolve tool hierarchy conflict in AGENTS_STARTUP.md

Closed v13.0.0/archive-v13-0-0-chunk-6 bugdocumentationai

neo-gemini-pro commented on Apr 26, 2026, 2:03 PM

Context A user pointed out a structural conflict in AGENTS_STARTUP.md. While PRs #9893 and #9900 successfully added the ask_knowledge_base tool to AGENTS.md (§2.1 Tool Hierarchy) and AGENTS_STARTUP.md (§3.4 "Ask the Expert" Protocol), they left legacy instructions untouched in earlier sections of AGENTS_STARTUP.md.

The Problem Currently, AGENTS_STARTUP.md contains conflicting instructions for agents during session initialization:

§3.1 The Query Command explicitly states: "Your most important tool is the local AI knowledge base. To use it, call the query_documents tool."
§3.3 The Two-Stage Query Protocol (Stage 1) dictates: "Use the query_documents tool to find relevant source code..."
Yet, §3.4 The "Ask the Expert" Protocol states: "ask_knowledge_base ... is the #1 tool in the Anti-Hallucination hierarchy"

This creates a split-brain scenario where agents reading the file sequentially are first told to use query_documents in-depth for conceptual understanding, which wastes context window and violates the newer Tool Hierarchy defined in AGENTS.md.

The Architectural Reality AGENTS_STARTUP.md sections 3.1 and 3.3 are out of sync with AGENTS.md §2.1. The tool ask_knowledge_base acts as a zero-cost subagent that retrieves, reads, and synthesizes answers, making it strictly superior to query_documents for Stage 1 knowledge querying. query_documents should be restricted to file path discovery only.

The Fix Refactor AGENTS_STARTUP.md to establish ask_knowledge_base as the undisputed primary tool for conceptual queries:

Update §3.1 to introduce ask_knowledge_base as the primary tool.
Update §3.3 (Stage 1) to mandate ask_knowledge_base for "how/why" queries, demoting query_documents to file discovery.
Consolidate §3.4 into the broader Knowledge Base strategy to remove the redundancy.

Acceptance Criteria

§3.1 reflects ask_knowledge_base as the primary query tool.
§3.3 specifies ask_knowledge_base for Stage 1 conceptual queries.
The conflict where query_documents is recommended over ask_knowledge_base is completely eliminated from AGENTS_STARTUP.md.
Documentation aligns perfectly with the Tool Hierarchy in AGENTS.md §2.1.

Out of Scope

Modifying AGENTS.md (it is already correct).
Altering the implementation of the MCP tools themselves.

Origin Session ID: 27016011-8ae9-48bb-af87-9479dd5b0fd0