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	14356
title	Rewrite NeuralLink.md as the Possession Interface guide
state	Closed
labels	documentationenhancementaiarchitecture
assignees	neo-gpt
createdAt	Jun 29, 2026, 5:56 PM
updatedAt	Jun 29, 2026, 9:10 PM
githubUrl	https://github.com/neomjs/neo/issues/14356
author	neo-gpt
commentsCount	0
parentIssue	14310
subIssues	[]
subIssuesCompleted	0
subIssuesTotal	0
contentTrust
projected
quarantined	0
signals	[]
blockedBy	[]
blocking	[]
closedAt	Jun 29, 2026, 9:10 PM

Rewrite NeuralLink.md as the Possession Interface guide

Closed v13.1.0/archive-v13-1-0-chunk-8 documentationenhancementaiarchitecture

neo-gpt commented on Jun 29, 2026, 5:56 PM

Part of #14310 · spawned from #14333 Checkpoint 9. Refs #14310, #14333.

Context

The #14333 capability-coverage audit found that Neural Link is source-real and already registered, but the public Learn guide is still framed as # Neural Link MCP Server. The v13 identity surfaces have moved on: README.md and the v13 release notes call Neural Link the Possession Interface / semantic possession interface, the Body↔Brain hinge. No equivalent #14310 sub was found.

Live latest-open sweep: checked the latest 20 open GitHub issues on 2026-06-29 at 15:54Z; no equivalent Neural Link guide rewrite was present.

A2A claim sweep: checked the latest 30 A2A messages on 2026-06-29 at 15:54Z; no active [lane-claim] or [lane-intent] overlapped this scope. The fresh claim was Grace on #14233 / #14312 sequencing, not Neural Link docs.

Duplicate sweep: live GitHub searches for "Neural Link" "guide", "Possession Interface", and "NeuralLink" found adjacent runtime, blog, parity, and harness tickets (#14222, #13376, #13012, #13318, #13309, #9299) but no Learn-guide rewrite sub. KB ticket search likewise surfaced adjacent Neural Link runtime/parity history, not this guide rewrite.

The Problem

learn/agentos/NeuralLink.md is valuable but below the v13.1 guide bar for this crown-jewel capability:

the title and spine say "MCP Server", not "Possession Interface"
large inline tool catalog/reference tables dilute the narrative
README.md / release notes carry the stronger v13 story: agents inhabit live apps, mutate UI/data, conversational UIs become in-app agents, and the primitive transcends web UI
the guide must explain the exact mechanism, not hype: object permanence precondition, toJSON Rich Blueprint, 50-tool OpenAPI, write tools, transaction/undo model, multi-agent co-inhabitation, and security/local/trusted boundaries

Architectural Reality

learn/tree.json registers agentos/NeuralLink.
README.md contains "The Possession Interface" framing.
v13 release notes name the Neural Link semantic possession interface as the Body↔Brain connection.
learn/agentos/NeuralLink.md currently includes configuration, installation, tool reference, security, and troubleshooting.
ai/mcp/server/neural-link/openapi.yaml currently exposes 50 operationIds across component, data, instance, runtime, routing, interaction, windowing, transaction, and patching domains.
ai/services/neural-link/ implements the service layer: ComponentService, DataService, InstanceService, InteractionService, RuntimeService, HealthService, ConnectionService, RecorderService, windowOps, and resolveCallTarget.
ai/mcp/server/neural-link/ owns the Bridge, tool service, OpenAPI contract, server entry, token verification, and bridge protocol.
src/ai/Client.mjs and the App Worker Neo.ai.Client are the runtime bridge; src/core/Base.mjs / toJSON is part of the semantic blueprint substrate.
ADR 0020 and ADR 0021 are aligned context: embodiment/co-habitation and multi-writer write enforcement.

The Fix

Rewrite learn/agentos/NeuralLink.md to the v13.1 guide bar:

lead with Possession Interface / live application mutability, not MCP-server setup
tell the why-care story for CTOs, architects, developers, and AI maintainers
ground claims in source, not hype
keep the strongest mechanism: object permanence -> semantic runtime graph -> toJSON Rich Blueprint -> read/write/verify loop -> transaction/undo guardrails
move or compress the tool catalog out of the conceptual narrative; if a full catalog is still needed, create/link a learn/agentos/tooling/NeuralLinkMcpApi.md reference and register it
preserve security honesty: local/trusted/admin boundaries, opt-in client, hot patching disabled by default, no untrusted public exposure
register/update learn/tree.json and generated SEO surfaces if files/routes change

Contract Ledger Matrix

N/A — docs-only conceptual rewrite. If a new tooling reference page is created, its source of authority is ai/mcp/server/neural-link/openapi.yaml; do not invent tool names by hand.

Decision Record impact

Aligned with ADR 0018, ADR 0020, and ADR 0021. No ADR amendment expected.

Acceptance Criteria

learn/agentos/NeuralLink.md becomes a rich hero-piece guide centered on Neural Link as the Possession Interface / live application mutability, not a tool catalog.
The guide explicitly explains the Body↔Brain hinge: object permanence, App Worker Neo.ai.Client, Bridge/MCP route, toJSON Rich Blueprint, and read/write/verify loop.
The guide covers multi-agent co-inhabitation and transaction/undo guardrails using verified source reality.
Tool catalog is extracted to or linked from a reference surface instead of dominating the conceptual guide; if a new reference page is created, register it in learn/tree.json.
Security/trust boundaries are explicit and honest: local/trusted/admin use, opt-in, audit logging, hot-patch opt-in, no public/untrusted exposure.
Includes at least one render-checked TD Mermaid diagram that carries the story.
Runs node buildScripts/docs/seo/generate.mjs if tree/routes change; generated SEO diffs are included or confirmed no-op.
PR body includes V-B-A evidence from learn/agentos/NeuralLink.md, ai/mcp/server/neural-link/openapi.yaml, ai/services/neural-link/, src/ai/Client.mjs, README.md Possession Interface framing, and v13 release notes.

Out of Scope

No new Neural Link runtime/API work.
No security redesign beyond accurately documenting existing boundaries; open implementation/security epics like #13376 remain separate.
No blog-post rewrite; #14222 / #9849 are adjacent publication lanes, not this Learn guide.
No broad ArchitectureOverview or AgentOSOnYourCodebase rewrite; #14315 / #14316 own those.

Avoided Traps

Do not call Neo or Neural Link a "framework".
Do not oversell Neural Link as arbitrary external-runtime possession; the current proven runtime is Neo.
Do not hand-maintain a 50-tool table in the conceptual guide when OpenAPI is source of truth.
Do not flatten Neural Link into generic browser automation; the moat is semantic runtime possession through persistent Neo objects.

Parent epic: #14310
Spawn source: #14333
Adjacent docs: #14315, #14316, #14320, #14321
Adjacent blog/runtime work: #14222, #9849, #13376, #13012
Source references: README.md, resources/content/release-notes/chunk-2/v13.0.0.md, learn/agentos/NeuralLink.md, ai/mcp/server/neural-link/openapi.yaml, ai/services/neural-link/, src/ai/Client.mjs

Origin Session ID: f9ecf11e-78ce-4a48-b353-b970adf49d92

Handoff Retrieval Hints: #14333 Neural Link Possession Interface guide coverage; Neural Link toJSON Rich Blueprint transaction undo; Possession Interface README v13 release notes.