What is the 'Neural Link'?

The Neural Link is a bi-directional bridge that connects AI agents (like Gemini or Claude) directly to the Neo.mjs runtime. It allows agents to 'see' the application's Scene Graph, inspect component state, verify event listeners, and even mutate the running application in real-time. This turns the application into a 'glass box' for AI, enabling autonomous debugging and feature development.

Why is Neo.mjs called an 'Application Engine' instead of a framework?

Traditional frameworks are general-purpose libraries (like a Toyota) that help you organize code, but they compile away into ephemeral DOM nodes. Neo.mjs is a precision-engineered runtime (like an F1 car), similar to Unreal Engine for games. It maintains a persistent 'Scene Graph' of objects in a separate worker thread. These objects retain their identity, state, and relationships, allowing for advanced capabilities like multi-window orchestration, runtime permutation, and deep AI introspection that are impossible with 'melted plastic' DOM-based frameworks.

What is 'Context Engineering'?

Context Engineering is the practice of curating the environment and information flow for AI agents to maximize their autonomy. In Neo.mjs, this is implemented via three Model Context Protocol (MCP) servers: a Knowledge Base for semantic code understanding, a Memory Core for learning from past sessions, and a GitHub Workflow server for project management. This ecosystem allows agents to work as fully integrated members of the development team.

What is 'Object Permanence' in the context of Neo.mjs?

In Neo.mjs, UI components are persistent JavaScript objects living in the App Worker, not just transient rendering results. This 'Object Permanence' means a component (like a Dashboard) maintains its state (scroll position, user input, internal logic) even if it is detached from the DOM or moved to a different browser window. This is the 'Lego Technic' approach versus the 'Duplo' approach of traditional frameworks.

What is an 'Agent Operating System'?

Neo.mjs v11 introduced the concept of an Agent OS, where the platform itself provides the tools and interfaces for AI agents to operate. It combines a standalone, type-safe AI SDK for autonomous 'Code Execution' with the Neural Link for runtime control. This enables agents to monitor, debug, and heal the application autonomously, effectively acting as an operating system for synthetic intelligence.

How does Neo.mjs handle multi-window applications?

Neo.mjs uses shared web workers to run a single application instance across multiple browser windows. All windows share the same application state and data in real-time. Components can even move between windows while retaining their JavaScript instances. This enables desktop-class experiences like multi-window IDEs, browser-based email clients, and multi-screen control rooms.

What makes Neo.mjs different from React, Angular, or Vue?

Neo.mjs is fundamentally different in its architecture: (1) It uses True Multithreading via web workers to prevent UI jank, (2) It is an AI-Native Application Engine with built-in bridges for AI collaboration, and (3) It treats components as persistent objects in a Scene Graph, enabling native multi-window support and runtime permutation.

Frontmatter

id	7564
title	Epic: Implement Two-Way GitHub Synchronization for Issues
state	Closed
labels	epicai
assignees	tobiu
createdAt	Oct 20, 2025, 1:17 PM
updatedAt	Oct 24, 2025, 11:32 AM
githubUrl	https://github.com/neomjs/neo/issues/7564
author	tobiu
commentsCount	1
parentIssue	null
subIssues	7565 Create Scaffold for the Issue Synchronization Service 7566 Implement GitHub to Local Sync (Pull) 7567 Implement Local to GitHub Sync (Push) 7568 Refine Issue Creation to be API-First 7569 Refactor SyncService to Use Centralized Configuration 7570 Implement and Adopt a Centralized stderr Logger 7571 Refactor Sync Config for Dynamic Date-Based Syncing 7572 Implement Dynamic Release Fetching in SyncService 7573 Filter GitHub Issues by Date in SyncService 7574 Update Archiving Logic to Use Dynamic Release Data 7575 Implement Release Note Synchronization 7576 Fix and Verify GitHub API Field Names in SyncService 7578 Harden Release Caching and Add Fallback 7579 Track and Handle Failed Pushes in SyncService 7580 Add Frontmatter to Synchronized Release Notes 7581 Add Comprehensive JSDoc to SyncService 7582 Externalize Magic Numbers and Strings in SyncService 7583 Implement Abort-on-Startup if Health Check Fails 7584 Fix Semantic Version Comparison in HealthService using ''semver'' 7585 Implement Missing #checkGhAuth Method in HealthService 7587 Implement Graceful Health Handling with Recovery 7588 Enhance Sync Result Payload with Comprehensive Statistics 7589 Refactor Issue Filename Convention
subIssuesCompleted	23
subIssuesTotal	23
blockedBy	[]
blocking	[]
closedAt	Oct 24, 2025, 11:32 AM

Epic: Implement Two-Way GitHub Synchronization for Issues

Name: Neo.mjs Application Engine
Author: Neo.mjs

Closed v11.0.0 epicai

tobiu commented on Oct 20, 2025, 1:17 PM

This epic outlines the implementation of a robust, bi-directional synchronization mechanism for GitHub issues, enabling them to be stored and edited as local Markdown files.

The core architecture follows a GitHub-First model for creation, combined with a powerful local sync capability for content editing. This hybrid approach ensures data integrity and a seamless workflow for both AI agents and human developers.

A new, dedicated SyncService will be created within the github-workflow MCP server to manage all synchronization logic. This service will be stateful, using a central metadata file to track changes efficiently and prevent unnecessary API calls.

Phase 1: Core Issue Synchronization

This initial phase focuses on building the complete, end-to-end synchronization workflow for GitHub Issues.

Key Architectural Pillars:

API-First Issue Creation: New issues will be created directly via the GitHub API (using the gh CLI). This guarantees a single source of truth for issue numbers and initial metadata. A dedicated create_issue tool will be implemented for this.
Dedicated Sync Service: A new SyncService singleton, built on Neo.core.Base, will encapsulate all sync logic. It will be exposed via a sync_issues tool.
Stateful, Metadata-Driven Sync: A central .github/.sync-metadata.json file will store the last sync time and the state of each issue, enabling efficient, delta-based updates.
Push-Then-Pull Logic: The sync process will first push any local changes (detected via file modification times) before pulling the latest updates from GitHub to minimize conflicts.
Structured Local Storage: Issues will be stored as .md files with YAML frontmatter for metadata and inlined comments, creating a complete, self-contained record.
Automated Archiving: Closed issues will be automatically moved to versioned archive directories (e.g., .github/ISSUE_ARCHIVE/v11.0/) based on their milestone or closed date.

Phase 2: Future Enhancements

Once the core issue synchronization is stable and robust, we will expand its capabilities.

Pull Request Synchronization: Implement a parallel sync mechanism for Pull Requests, storing their conversations, reviews, and diffs as local Markdown files in a .github/PULL_REQUESTS/ directory.
Comment Push: Investigate and implement a mechanism to push new comments from the local .md files back to GitHub. This is a complex task that requires careful parsing and state management.
Knowledge Base Integration: Integrate the locally stored issue and PR files into the AI Knowledge Base build process, making them queryable for deep contextual understanding.

tobiu assigned to @tobiu on Oct 20, 2025, 1:17 PM

tobiu added the epic label on Oct 20, 2025, 1:17 PM

tobiu added the ai label on Oct 20, 2025, 1:17 PM

tobiu added sub-issue #7565 on Oct 20, 2025, 1:20 PM

tobiu added sub-issue #7566 on Oct 20, 2025, 1:22 PM

tobiu added sub-issue #7567 on Oct 20, 2025, 1:24 PM

tobiu added sub-issue #7568 on Oct 20, 2025, 1:26 PM

tobiu referenced in commit c46e8dd - "#7564 tickets as md files" on Oct 20, 2025, 1:27 PM

tobiu added sub-issue #7569 on Oct 20, 2025, 2:04 PM

tobiu added sub-issue #7570 on Oct 20, 2025, 2:16 PM

tobiu added sub-issue #7571 on Oct 20, 2025, 2:43 PM

tobiu added sub-issue #7572 on Oct 20, 2025, 2:44 PM

tobiu added sub-issue #7573 on Oct 20, 2025, 2:46 PM

tobiu added sub-issue #7574 on Oct 20, 2025, 2:48 PM

tobiu added sub-issue #7575 on Oct 20, 2025, 2:49 PM

tobiu referenced in commit 83a1208 - "#7564 ticket md files" on Oct 20, 2025, 2:49 PM

tobiu added sub-issue #7576 on Oct 20, 2025, 3:21 PM

tobiu added sub-issue #7577 on Oct 20, 2025, 3:22 PM

tobiu added sub-issue #7578 on Oct 20, 2025, 3:24 PM

tobiu added sub-issue #7579 on Oct 20, 2025, 3:25 PM

tobiu added sub-issue #7580 on Oct 20, 2025, 3:27 PM

tobiu added sub-issue #7581 on Oct 20, 2025, 3:29 PM

tobiu added sub-issue #7582 on Oct 20, 2025, 3:30 PM

tobiu referenced in commit a08874a - "#7564 tickets as md files" on Oct 20, 2025, 3:31 PM

tobiu removed sub-issue #7577 on Oct 20, 2025, 3:34 PM

tobiu added sub-issue #7583 on Oct 20, 2025, 3:37 PM

tobiu added sub-issue #7584 on Oct 20, 2025, 3:47 PM

tobiu added sub-issue #7585 on Oct 20, 2025, 3:50 PM

tobiu added sub-issue #7587 on Oct 20, 2025, 10:47 PM

tobiu added sub-issue #7588 on Oct 21, 2025, 9:55 AM

tobiu referenced in commit 1de91d6 - "#7564 new sub md file" on Oct 21, 2025, 10:10 AM

tobiu added sub-issue #7589 on Oct 21, 2025, 11:33 AM

tobiu Oct 24, 2025, 11:32 AM

epic resolved, there will be new tickets for the new mcp server.

tobiu closed this issue on Oct 24, 2025, 11:32 AM