neo.mjs Files

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