Neo.mjs v11.9.0 Release Notes

Happy Birthday, Neo.mjs! 🎉

Today, November 23, 2025, marks exactly 6 years since the General Availability (GA) of Neo.mjs on November 23, 2019.

We wanted to make this anniversary release special. Six years ago, we reimagined web development with a multi-threaded, worker-first architecture. Today, we are reimagining it again with the Agent OS.

This release moves beyond the "Tool Use" era into a future where agents are first-class citizens—autonomous developers capable of executing code, managing their own infrastructure, and understanding complex context. We have solidified this vision with a comprehensive documentation overhaul, a unified "Neo-Native" AI architecture, and foundational features for the next generation of spatial web apps.

✨ Highlights

📘 Agent OS: The Comprehensive Manual

We have cemented the "Agent OS" vision with a complete suite of documentation. New guides cover everything from the high-level "Agent OS" concept to deep dives into each MCP server.

• Agent OS Introduction: The high-level vision and architecture.
• Code Execution Guide: A definitive guide to the "Thick Client" pattern (ai/services.mjs), including a real-world case study on self-healing database schemas.
• Real-World Showcase: While v11.8 introduced the concept, v11.9 delivers the proof. We've added concrete examples like ai/examples/debug_session_state.mjs (a "Thick Client" diagnostic tool) and ai/examples/migrate_timestamps.mjs (an autonomous migration utility), proving how agents can maintain their own infrastructure.
• Server Guides: Detailed architecture breakdowns for the Knowledge Base, Memory Core, and GitHub Workflow servers.
• Philosophy: We've documented the "Why" behind our Context Engineering and "Save-Then-Respond" protocols.

🏗 Unified MCP Architecture & The Runner Pattern

We've completely re-architected our AI infrastructure, paying down technical debt by refactoring all three MCP servers (memory-core, knowledge-base, github-workflow) to use a robust Runner Pattern.

Instead of monolithic scripts, we now have a clear separation of concerns:

• The Runner (mcp-stdio.mjs): A lightweight entry point responsible for CLI argument parsing (commander), global config setup, and error trapping. It acts as the "main" function.
• The Server (Server.mjs): A pure Neo.core.Base class that encapsulates the application logic. It leverages the framework's powerful lifecycle hooks (initAsync, ready) to orchestrate complex dependency chains (Database -> Auth -> Transport) without race conditions.

This Neo-Native approach means our AI backend services now share the same DNA as our frontend components—making them easier to test, extend, and maintain.

🪟 Neo.manager.Window: The "God View"

We introduced Neo.manager.Window, a new core manager in the App Worker that tracks the exact geometry of all connected browser windows.

• Geometry Tracking: Automatically tracks screenX, screenY, width, and height for every window.
• Spatial Awareness: Enables getWindowAt(x, y) queries, a prerequisite for cross-window drag-and-drop.
• Reactive Updates: Extends Neo.manager.Base for full observability of window state changes.

🧠 Memory Core: Parallel Sessions & Eventual Consistency

We have upgraded the Memory Core's synchronization engine to move beyond the single-agent "happy path" and fully support Parallel Agent Sessions.

• Eventual Consistency: The system now employs a robust consistency model that can track multiple agents working simultaneously without corrupting the context window.
• Drift Detection: Intelligent logic automatically compares raw memory logs against cached summaries. If a parallel session adds new memories or crashes unexpectedly, the next agent will detect the "drift" and self-heal the summary on startup.
• Numeric Timestamps: We refactored the storage engine to use numeric timestamps (milliseconds), resolving critical compatibility issues with ChromaDB range queries and ensuring precise session discovery.

📦 Full Changelog

Agent OS & Documentation

• [Docs] Re-position Neo.mjs as "Agent Operating System" in Schema and Metadata (Issue #7844)
• Epic: Documentation Overhaul for MCP & Agent OS Architecture (Issue #7848)
• Docs: Create Guide for "Introduction to MCP & Agent OS" (Issue #7849)
• Docs: Create Guide for "The Knowledge Base Server" (Issue #7850)
• Docs: Create Guide for "The Memory Core Server" (Issue #7851)
• Docs: Create Guide for "The GitHub Workflow Server" (Issue #7852)
• Docs: Create Guide for "Code Execution with MCP" (Issue #7853)
• Enhance Knowledge Base MCP Server Guide (Issue #7854)
• Enhance Knowledge Base Guide with 'Why' and Use Cases (Issue #7855)
• Polish Knowledge Base Guide: Config Details & Storytelling (Issue #7856)
• Enhance Memory Core MCP Server Documentation (Issue #7857)
• Documentation: Comprehensive Guide for GitHub Workflow MCP Server (Issue #7858)
• Documentation: Enhance "Code Execution with MCP" Guide (Issue #7859)
• Documentation: Update GitHubWorkflow.md to reference Knowledge Base Server (Issue #7860)
• Enhance Code Execution Guide with Real-World Case Study (Issue #7876)
• Update MCP guides code blocks to be readonly (Issue #7877)
• Enhance README.md with links to new MCP guides and Code Execution section (Issue #7879)

AI Infrastructure (Refactoring & Enhancements)

• Refactor Memory Core MCP Server to use Neo.core.Base class architecture (Issue #7869)
• Refactor Knowledge Base MCP Server to use Neo.core.Base architecture (Issue #7871)
• Refactor GitHub Workflow MCP Server to use Neo.core.Base architecture (Issue #7872)
• Improve Session Summarization to Handle Parallel and Recent Sessions (Issue #7861)
• Add capability to force summarize all sessions (Issue #7862)
• Refactor SessionService for better error handling and config management (Issue #7864)
• Refactor Memory Core to use numeric timestamps for ChromaDB compatibility (Issue #7865)
• Refactor MemoryService to use crypto-based IDs (Issue #7867)
• Implement consistent error handling for Memory Core MCP tools (Issue #7868)
• Standardize version reporting across MCP servers (Issue #7873)

Core Framework

• Feat: Create Neo.manager.Window for Multi-Window Geometry Tracking (Issue #7845)
• Refactor Neo.manager.Window to extend Neo.manager.Base (Issue #7875)
• Docs: Clarify distinction between Non-Reactive Configs and Class Fields in Neo.core.Base (Issue #7870)
• Remove duplicate contains() method in Rectangle.mjs (Issue #7874)
• Add Markdown and YAML to Highlight.js build configuration (Issue #7878)

Bug Fixes

• Bug: Prevent SessionService from summarizing the active session (Issue #7866)

Here is the example of the code execution pattern where Gemini 3 fixed a running MCP server via run-time tool composition scripts:

All changes in 1 commit: https://github.com/neomjs/neo/commit/08ad5e1f2f2598122ec0c083041baa4c7f214af7