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	fix: Local MCP Failsafes and Tool Schema Validation (#10041)
author	tobiu
state	Merged
createdAt	Apr 16, 2026, 3:07 PM
updatedAt	Apr 16, 2026, 3:11 PM
closedAt	Apr 16, 2026, 3:11 PM
mergedAt	Apr 16, 2026, 3:11 PM
branches	`dev` ← `agent/10041-mcp-failsafes-and-validation`
url	https://github.com/neomjs/neo/pull/10042

Merged

tobiu commented on Apr 16, 2026, 3:07 PM

Overview

This PR introduces critical stabilization patches for the Agent OS local runtime and native IDE integrations.

Architectural Impact

Database Initialization Safeguards: Flipped default configurations (autoSync, autoStartDatabase) in memory-core and knowledge-base from Opt-Out to Opt-In. This structurally prevents local IDE twin-spawns from triggering redundant background ChromaDB/SQLite boots.
MCP Server Key Sanitization: Replaced periods with dashes in .gemini/settings.json MCP server keys (neo.mjs-knowledge-base -> neo-mjs-knowledge-base). This mitigates schema parsing failures within IDE clients that struggle with dotted JSON keys.
Native Tool Validation constraints: Integrated McpServerToolLimits.spec.mjs unit tests ensuring all exported tools mathematically obey Anthropic/Gemini length bounds (Name ≤ 64, Description ≤ 1024).
Agent Debugging Skill (debugging-antigravity): Embedded a permanent Agent Skill into the repo to autonomously guide future swarm instances through diagnosing and resolving Twin-LSP duplication and SQLite workspace state corruption (__store crash) natively within Anthropic's Progressive Disclosure limits.

Edge Cases Handled

Validated that changing default environment keys (process.env.AUTO_SYNC === 'true') safely captures unset boolean toggles as false.

Resolves #10041

tobiu commented on Apr 16, 2026, 3:10 PM

Input from Gemini 3.1 Pro (Antigravity):

✦ # PR Review Summary

Status: Approved

Thanks for putting this together! Great approach to safely neutralizing the Twin-LSP crash footprint by aggressively enforcing Opt-In defaults and capturing the IDE debugging playbook into a permanent Agent Skill. I've processed the diff and structured the retrospective payload below.

📊 Evaluation Metrics

[ARCH_ALIGNMENT]: 100 - Perfectly aligns with the Neo.core.Base philosophy by strictly enforcing environment variables correctly (=== 'true') rather than relying on weak implicit opt-outs, and formally documenting IDE boundaries.

[CONTENT_COMPLETENESS]: 95 - The debugging-antigravity skill is incredibly thorough and accurately documents the __store null error recovery strategy. The ticket scope was successfully expanded to track this.

[EXECUTION_QUALITY]: 95 - The implementation directly resolves the process collisions without introducing breaking abstractions. The new Playwright limit test utilizes the unified setup.mjs pattern flawlessly.

[PRODUCTIVITY]: 100 - Solved multiple distinct friction points surrounding the Agent OS runtime instantiation in a single targeted changeset.

[IMPACT]: 85 - Massively impacts local developer experience by eliminating phantom background processes and database locking loops.

[COMPLEXITY]: 20 - Low complexity logic shifts, but with exceptionally high functional repercussions.

[EFFORT_PROFILE]: Quick Win - High ROI for system stability achieved through clean configuration normalization.

🕸️ Context & Graph Linking

Target Epic / Issue ID: Resolves #10041

Related Graph Nodes: FILE:.gemini/settings.json, SKILL:debugging-antigravity

🧠 Graph Ingestion Notes

[RETROSPECTIVE]: The transition from implicit opt-out (!== 'false') to explicit opt-in (=== 'true') for background database daemons successfully eliminates autonomous local startup deadlocks when an IDE aggressively fires multiple Language Servers concurrently.

📋 Required Actions

To proceed with merging, please address the following:

Scope verification confirmed (Ticket #10041 was updated to reflect skill addition).

No breaking architectural changes detected.

Ready for merge when you are!