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	10244
title	docs(ai): extend MemoryCoreMcpAuth.md Troubleshooting with identity race failure mode
state	Closed
labels	documentationaicore
assignees	neo-gemini-pro
createdAt	Apr 23, 2026, 5:54 PM
updatedAt	Apr 24, 2026, 12:19 AM
githubUrl	https://github.com/neomjs/neo/issues/10244
author	neo-gemini-pro
commentsCount	0
parentIssue	null
subIssues	[]
subIssuesCompleted	0
subIssuesTotal	0
blockedBy	[]
blocking	[]
closedAt	Apr 24, 2026, 12:19 AM

docs(ai): extend MemoryCoreMcpAuth.md Troubleshooting with identity race failure mode

Closed v13.0.0/archive-v13-0-0-chunk-5 documentationaicore

neo-gemini-pro commented on Apr 23, 2026, 5:54 PM

Context

During the resolution of the boot-time identity race condition in #10241, we empirically proved that the failure mode (where GraphService.getNode failed to find identity nodes during MCP server boot, despite the nodes existing in SQLite) was caused by cross-process WAL lock contention between the Antigravity hardlinked SQLite process and the Claude Code process.

The primary remediation, applying pragma busy_timeout = 5000 to the SQLite connection, entirely resolved the issue.

The Problem

The learn/agentos/tooling/MemoryCoreMcpAuth.md troubleshooting section currently lacks documentation of this specific failure mode (SQLite lock contention leading to silent bindAgentIdentity failures at boot).

The Architectural Reality

The Neo.mjs MCP server swarm architecture connects multiple independent agent processes to a single shared .neo-ai-data/sqlite/memory-core-graph.sqlite file. Under concurrent boot conditions, read operations like GraphService.getNode({id: graphNodeId}) may fail if another process is holding an exclusive write lock (SQLITE_BUSY) and no busy_timeout is configured.

The Fix

Extend learn/agentos/tooling/MemoryCoreMcpAuth.md §Troubleshooting with a paragraph documenting this failure mode.

Acceptance Criteria

Add a subsection under Troubleshooting in learn/agentos/tooling/MemoryCoreMcpAuth.md documenting the boot-time identity race condition.
Explicitly mention pragma busy_timeout = 5000 as the architectural solution to cross-process SQLite WAL lock contention.

Out of Scope

Making changes to the GraphService or Server codebase. This ticket is strictly documentation.

Avoided Traps

Re-derivation of the retry pattern: The documentation must emphasize that adding arbitrary retry loops masks the underlying SQLITE_BUSY error. The busy_timeout mechanism is the correct, native SQLite solution.

Resolves the documentation chore from #10241
#10242 (The PR that implemented the fix)

Origin Session ID: 1c5933cc-a2d0-4296-ae3f-f4e815d385a2