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	11117
title	Chunk resources/content/pulls/ to bypass GitHub''s 1000-file folder cap (sibling to #11113)
state	Closed
labels	enhancementaimodel-experience
assignees	neo-gemini-3-1-pro
createdAt	May 10, 2026, 4:23 PM
updatedAt	May 10, 2026, 6:17 PM
githubUrl	https://github.com/neomjs/neo/issues/11117
author	neo-opus-4-7
commentsCount	0
parentIssue	11120
subIssues	[]
subIssuesCompleted	0
subIssuesTotal	0
blockedBy	[]
blocking	[]
closedAt	May 10, 2026, 6:17 PM

to bypass GitHub's 1000-file folder cap (sibling to #11113)

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

Closedenhancementaimodel-experience

neo-opus-4-7 commented on May 10, 2026, 4:23 PM

Context

Operator @tobiu surfaced 2026-05-10 during PR #11114 (Issue Chunk Migration) review:

"follow up tickets (where we can do better!) => we also sync discussions and pr conversations now. we do not have archives and chunking in place there yet."

resources/content/pulls/ currently holds 713 markdown files (one per synced PR conversation). At GitHub's 1000-file folder cap, that's ~287 files of headroom — at current PR cadence (this session alone added 8+ PRs in ~2 hours), the cap will be reached within weeks. Sibling directory discussions/ (64 files) is a preventive case filed separately.

The Problem

When resources/content/pulls/ exceeds 1000 files, GitHub's web UI folder tree truncates display — files beyond the 1000th become invisible / inaccessible via web UI. Same friction class as #11113 fixed for resources/content/issues/. Without chunking + archive separation, the substrate degrades the GitHub UX for the swarm + future contributors browsing PR-content.

Additionally: there is no pr-archive/ separation today (only issue-archive/). Active PRs and merged-PR archives co-mingle under pulls/. As Neo grows, the archive substrate should mirror the issue substrate.

The Architectural Reality

ai/services/github-workflow/sync/PullRequestSyncer.mjs determines local file paths (currently flat resources/content/pulls/pr-NNNN.md). Build-script consumers read this directory for analysis (e.g., buildScripts/release/analyzeClosedSinceRelease.mjs).

Per #11113 substrate (post-#11114 merge): XXxx-style chunking convention for issues. The substrate-correct shape is to inherit the chunking convention from #11113 rather than introduce a parallel-but-different shape — single substrate primitive across all GH-content syncs (issues, PRs, discussions).

The Fix

Apply the same chunking + archive pattern that #11114 established for issues:

Subdivide resources/content/pulls/ into chunked sub-folders using whatever convention #11114 cycle-3 documents (currently XXxx per PR #11114; pending operator-is-key defense by Gemini).
Create resources/content/pr-archive/ mirror with same chunked structure for closed/merged PRs.
Update PullRequestSyncer.mjs to dynamically compute + write to the correct chunked path based on PR number (#getPrPath mirror of #getIssuePath).
Update consumers for recursive readdir parsing (mirror the 5 consumers updated in PR #11114: IssueIngestor → PRIngestor; TicketSource → PRSource if/where applicable; tickets.mjs index-builder → PR equivalents; analyzeClosedSinceRelease; SEO generate.mjs).
Migration script to organize existing 713 files into chunked structure.

Per #11116 friction-gold lesson (separate code-change from data-migration commits): consider splitting this into 2 sub-tickets:

Sub-A: code-side chunking implementation in PullRequestSyncer.mjs + consumer updates (small, reviewable in isolation)
Sub-B: data-migration of 713 existing files into the chunked structure (mechanical, separate review pass)

Sequencing: Sub-A lands first (enables new shape); Sub-B after (populates the new shape).

Acceptance Criteria

PullRequestSyncer.mjs writes new PRs to chunked sub-folder per chosen convention
resources/content/pr-archive/ exists with same chunked structure
All build-script consumers updated for recursive readdir (mirror PR #11114's 5-consumer pattern)
Existing 713 PR markdown files migrated into chunked structure
No broken cross-references in consumers (build / sync / portal)
Naming convention documented (inheriting from #11114 cycle-3 outcome — defer to whatever convention lands there to keep a single substrate)

Out of Scope

Naming-convention re-decision — defer to #11114 cycle-3 outcome; this ticket inherits whatever convention lands there. Don't introduce a parallel divergent shape.
Generalized GH-content-chunking utility — could be extracted as shared substrate after issues + PRs + discussions are all chunked individually. Premature abstraction now.
Discussion chunking — separate sibling ticket (filed parallel to this one).
Active vs archive lifecycle policy — currently merged/closed PRs stay in pulls/; archive-separation is a UX improvement, not a functional contract change. Define the policy in a separate ticket if scope requires.

Avoided Traps / Gold Standards Rejected

Decision Matrix

Mirror #11113/#11114 chunking + archive pattern directly (Selected): Reuses established substrate primitives + naming convention. Lowest implementation cost. Aligned with single-substrate-primitive-across-content-types shape.
Introduce a different chunking convention specific to PRs: Rejected. Divergent conventions across content types (issues vs PRs vs discussions) compound cognitive load + tooling complexity. Single substrate primitive is the substrate-correct shape.
Defer until cap is actually hit: Rejected. 713 → 1000 at current cadence is weeks. Preventive substrate-evolution is cheaper than reactive (no broken-UI period for swarm).
Generalize as a single GH-content-chunking utility before fixing PRs: Rejected as premature abstraction. Pattern is established by #11114 post-merge; abstract after we have 3+ instances (issues + PRs + discussions). Extract substrate when the friction of duplication exceeds the friction of the abstraction itself.

Trap: Treating pulls/ chunking as independent of issues/ chunking. Rejection: Same friction class, same cap, same consumer pattern (sync writer + recursive readdir consumers). Substrate-correct shape is single primitive applied across content types.

#11113 (canonical substrate ticket for issue chunking + archive)
PR #11114 (in flight; #11113 implementation; cycle-2 naming-convention defense pending)
#11116 (sister substrate-evolution: code-vs-data-migration commit-shape discipline; informs sub-ticket split shape for this ticket)
Operator framing 2026-05-10 (this session, A2A-only — [paraphrase] for peer corroboration: "we also sync discussions and pr conversations now. we do not have archives and chunking in place there yet.")
Sibling ticket: discussion chunking (filed in parallel)
Substrate-quality observation worth [RETROSPECTIVE]: GH-content sync substrate should evolve as a SHARED primitive once 3+ content types (issues + PRs + discussions) hit the chunking pattern. Not in this ticket's scope; flag as future generalization candidate.

Origin Session ID: c2912891-b459-4a03-b2af-154d5e264df1 Retrieval Hint: "PR conversations chunking", "resources/content/pulls 1k cap", "PullRequestSyncer chunked path"

tobiu closed this issue on May 10, 2026, 6:17 PM

tobiu referenced in commit 83c0eb0 - "refactor(github-workflow): implement chunked storage for pull requests (#11123) on May 10, 2026, 6:17 PM