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.

Frontmatter

id	13358
title	Split miniSummary backfill from KB-sync backpressure
state	Closed
labels	bugaiarchitecturemodel-experience
assignees	neo-gpt
createdAt	Jun 15, 2026, 5:34 PM
updatedAt	Jun 15, 2026, 6:29 PM
githubUrl	https://github.com/neomjs/neo/issues/13358
author	neo-gpt
commentsCount	2
parentIssue	12065
subIssues	[]
subIssuesCompleted	0
subIssuesTotal	0
blockedBy	[]
blocking	[]
closedAt	Jun 15, 2026, 6:29 PM

Split miniSummary backfill from KB-sync backpressure

Closed v13.1.0/archive-v13-1-0-chunk-3 bugaiarchitecturemodel-experience

neo-gpt commented on Jun 15, 2026, 5:34 PM

Context

Operator surfaced a live orchestrator log on 2026-06-15 showing:

[Orchestrator] Deferring memory miniSummary backfill; heavy maintenance task knowledge base sync is active (pending-memory-minisummary:3647).

The immediate correction was precise: this is kb, not graph. The direct add_memory never-fail / health-gate class is already handled by #12972 and merged PR #12975; add_memory no longer writes directly to Chroma and the WAL/drain design is intentionally async. The remaining friction is a scheduler/backpressure coupling: Memory Core mini-summary repair is being deferred solely because the local Knowledge Base full-corpus sync is running.

Operator priority: P0 operational reliability. This ticket is not blaming the earlier fixes; it converts the newly observed friction into a narrow scheduler contract.

Release classification: boardless by default. This is active Agent OS reliability work, but not automatically a v13 release-board item unless the operator promotes it as release-blocking.

The Problem

The orchestrator currently models several unrelated maintenance tasks as one exclusive-heavy class. In live operation that can make a Knowledge Base sync block Memory Core miniSummary backfill, even though the affected domains are separate:

kbSync is the local Neo checkout Knowledge Base full-corpus sync lane.
memory-summary-backfill repairs / enriches Memory Core AGENT_MEMORY graph rows that lack miniSummary.
add_memory itself is supposed to remain a never-fail, WAL-first write path, with enrichment and embedding deferred.

This matters because a long KB sync can now delay Memory Core catch-up and leave thousands of pending-memory-minisummary rows waiting. The log message is the symptom: the scheduler reports Memory Core backfill as blocked by a KB task, not by a shared graph lock, provider capacity check, or actual same-substrate contention.

The Architectural Reality

ai/daemons/orchestrator/scheduling/registry.mjs marks memory-summary-backfill and kbSync as maintenanceClass: 'heavy' with backpressure: 'exclusive-heavy'.
ai/daemons/orchestrator/scheduling/picker.mjs drops all heavy candidates whenever any heavy task is running.
ai/daemons/orchestrator/services/MaintenanceBackpressureService.mjs includes both memory-summary-backfill and kbSync in DEFAULT_HEAVY_MAINTENANCE_TASK_NAMES, so execution-phase backpressure and lease semantics reinforce the same coupling.
ADR 0014 classifies kbSync as local-only: it scans the maintainer checkout's Knowledge Base corpus. The cloud profile disables kbSync; tenant content arrives by push / tenant ingestion lanes, not this local sync path.
memory-summary-backfill is Memory Core work and must honor cloud deployments. It must not depend on a local checkout KB sync lane being present, enabled, or idle.
#12943 / PR #13088 and #12828 / PR #12829 fixed no-progress refire/backoff classes. They did not split the KB-vs-MC backpressure taxonomy.

The Fix

Replace the one-bucket exclusive-heavy treatment for this pair with a compatibility-aware scheduler/backpressure contract.

Expected shape:

memory-summary-backfill must not be deferred solely because kbSync is active.
If the implementation finds a real shared-resource reason to defer, the reason must be explicit and falsifiable, such as the same local model endpoint, a Chroma operation class, or a shared lease scope. The log should name the shared resource, not generic KB task activity.
Preserve safety for genuinely conflicting heavy work: session summarization, dream, backup, graphlog compaction, local checkout sync, and tenant-repo sync still need whatever serialization their actual resource overlap requires.
Keep kbSync local-only per ADR 0014; do not route cloud tenant ingestion through it, and do not make Memory Core backfill depend on local-checkout KB behavior.
Include a test that reproduces today's bug shape: kbSync running, memory-summary-backfill due, and the picker/backpressure layer currently defers it. The fixed behavior should either allow the MC backfill or produce a non-KB shared-resource deferral with explicit evidence.

Contract Ledger Matrix

Target Surface	Source of Authority	Proposed Behavior	Fallback	Docs	Evidence
Orchestrator task registry backpressure classification	`registry.mjs`, ADR 0014	Separates KB local-corpus sync from Memory Core miniSummary repair instead of treating both as one undifferentiated heavy class	If a shared resource is saturated, defer with that resource as the reason	JSDoc / `@summary` on any new policy helper	Unit tests for kbSync-running + memory-backfill-due
Execution-phase heavy-maintenance lease policy	`MaintenanceBackpressureService.mjs`, ADR 0009/0014	Applies compatibility-aware lease/backpressure so unrelated KB and MC work do not block each other	Preserve exclusive lease for proven same-resource collisions	JSDoc / policy comment	Unit tests for allowed pair and still-blocked conflicting pairs
Deferral observability	`recordDeferral()` log / HealthService outcome payload	Reports the actual blocker substrate/resource instead of generic `knowledge base sync` when MC backfill is deferred	Existing skipped outcome remains, but with more specific reason fields	Health payload docs or JSDoc if schema changes	Unit test asserting reasonCode/blocker payload
Cloud deployment profile	ADR 0014, DeploymentCookbook	`memory-summary-backfill` remains cloud-valid while `kbSync` stays disabled/local-only	No local checkout fallback in cloud	Deployment doc update only if config surface changes	Cloud-mode unit negative assertion if touched

Decision Record impact

Aligned with ADR 0014. No ADR amendment is expected if the fix only refines runtime compatibility/backpressure policy. If the implementation changes the documented scheduler lane taxonomy or cloud lane set, update ADR 0014 / DeploymentCookbook in the same PR.

Acceptance Criteria

A unit test proves memory-summary-backfill due work is not deferred solely because kbSync is running.
If MC backfill is deferred under a concurrent KB sync scenario, the deferral reason names a real shared substrate/resource and is not knowledge base sync is active as the only blocker.
Existing safety remains for genuinely conflicting heavy tasks; add regression coverage for at least one still-blocked conflicting pair.
Cloud deployment behavior remains correct: kbSync stays local-only/disabled by default in cloud, and Memory Core miniSummary backfill does not require local checkout KB sync behavior.
The fix does not touch the direct add_memory WAL-first contract or reintroduce Chroma/embedding dependency on the MCP write path.
No memory rows are deleted or tombstoned as part of this ticket.

Out of Scope

Direct add_memory health-gate exemption; that is #12972 / PR #12975.
Never-fail WAL write-ahead and deferred embed design; that is #12838 / PR #12844 plus drain follow-ups.
The no-progress miniSummary backfill loop/backoff fixes; those are #12828 / PR #12829 and #12943 / PR #13088.
Knowledge Base sync implementation internals.
Memory-row deletion, tombstoning, or orphan cleanup.
Re-pointing cloud tenant KB ingestion through kbSync; ADR 0014 rejects that shape.

Avoided Traps / Gold Standards Rejected

Re-opening the direct add_memory gate: rejected. The current evidence is scheduler backpressure, not the MCP write path.
One global heavy mutex forever: rejected. It is safe but over-broad; it makes unrelated substrate work wait and hides the actual resource that caused deferral.
Blind parallelism: rejected. The fix needs a compatibility matrix or equivalent policy so real provider/Chroma/graph conflicts still serialize.
Cloud-local conflation: rejected. kbSync is local-only; Memory Core backfill must remain cloud-valid without local checkout assumptions.

#12972 - direct add_memory health-gate exemption.
#12838 - never-fail add_memory JSONL write-ahead + deferred embed.
#12828 / #12943 - miniSummary no-progress/backoff fixes already completed.
#12065 - orchestrator/REM maintenance parent area.
ADR: learn/agentos/decisions/0014-cloud-deployment-topology-and-scheduler-task-taxonomy.md.

Duplicate / Claim Sweep

Live latest-open sweep: checked the latest 20 open issues immediately before creation on 2026-06-15T15:33:04Z. Relevant results were #13349, #13357, #13287, #13355, #12450, #13353, #13350, #13012, #11829, #13289, and assigned/unrelated backlog items; no open equivalent for KB-sync blocking Memory Core miniSummary backfill was present.

Targeted live GitHub searches: "miniSummary backfill", "memory-summary-backfill", "KB sync", "kbSync", and "pending-memory-minisummary" surfaced older or broader issues: #12743, #12740, #12065, and #12450. The exact prior loop/backoff issues #12828 and #12943 are closed completed; they do not cover the KB-vs-MC backpressure split.

A2A in-flight sweep: native list_messages / add_message tools are not exposed in this Codex Desktop surface. I could not inspect private in-flight A2A claims from this harness. Public GitHub issue/PR state and repo content were checked immediately before filing, and no public duplicate or collision was visible.

Semantic KB sweep: ask_knowledge_base(query='add_memory miniSummary backfill heavy maintenance knowledge base sync graph access daemon cloud deployments', type='all') surfaced Memory Core, Knowledge Base, Graph Backfill, and cloud-deployment context. It supported the substrate distinction: kbSync is Knowledge Base/full-corpus work, while add_memory and miniSummary enrichment are Memory Core concerns.

Exact repo/content sweep: rg "Deferring memory miniSummary|miniSummary backfill|pending-memory-minisummary|add_memory|heavy maintenance|knowledge base sync" ai .agents learn test resources/content/issues -n found the current scheduler code, closed #12972/#12828/#12943 history, ADR/cloud docs, and no open ticket for this exact split.

Origin Session ID: 019ec8a7-1f8e-75a3-b223-fe59cc444776

Retrieval Hint: "kbSync blocks memory-summary-backfill pending-memory-minisummary add_memory WAL backpressure split cloud local-only"