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	11496
title	Orchestrator still starts Memory Core Chroma after ADR 0003
state	Closed
labels	bugairegressionarchitectureperformancemodel-experience
assignees	neo-gpt
createdAt	May 16, 2026, 10:57 PM
updatedAt	May 16, 2026, 11:33 PM
githubUrl	https://github.com/neomjs/neo/issues/11496
author	neo-gpt
commentsCount	1
parentIssue	null
subIssues	[]
subIssuesCompleted	0
subIssuesTotal	0
blockedBy	[]
blocking	[]
closedAt	May 16, 2026, 11:33 PM

Orchestrator still starts Memory Core Chroma after ADR 0003

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

Closedbugairegressionarchitectureperformancemodel-experience

neo-gpt commented on May 16, 2026, 10:57 PM

Context

The current daemon incident surfaced two separate failure classes:

summary and kbSync can launch in the same restart poll. That is already covered by #11487 / PR #11489.
The orchestrator is still running a second Memory Core Chroma daemon even though ADR 0003 and #11011 retired federated Chroma topology in favor of one shared Chroma instance.

This ticket tracks only the second failure.

The Problem

Live operator logs from 2026-05-16 show the orchestrator adopting both Chroma processes:

Found running chroma daemon process (PID: 2077). Adopting.
Found running memory core chroma process (PID: 2078). Adopting.

V-B-A against the running machine confirmed the topology is real, not log noise:

node 2077 ... chroma run --path .neo-ai-data/chroma/knowledge-base --port 8000
node 2078 ... chroma run --path .neo-ai-data/chroma/memory-core --port 8001

lsof confirmed 2077 listens on 8000 and 2078 listens on 8001. Both processes run from /Users/Shared/github/neomjs/neo.

This directly contradicts the accepted unified-only architecture in ADR 0003.

The Architectural Reality

ADR 0003 (learn/agentos/decisions/0003-chroma-topology-unified-only.md) states:

A single ChromaDB daemon is shared by both Knowledge Base and Memory Core.
chromaUnified is removed from MCP server configurations.
ChromaLifecycleService no longer spawns or manages a local Memory Core daemon.

Current source partially reflects that:

ai/services/memory-core/lifecycle/ChromaLifecycleService.mjs logs unified topology and does not spawn Memory Core Chroma.
ai/services/memory-core/HealthService.mjs reports topology mode as static unified.

But current source also regresses the topology:

ai/daemons/TaskDefinitions.mjs defines a separate memoryCoreChroma task with --path .neo-ai-data/chroma/memory-core --port 8001.
ai/daemons/Orchestrator.mjs includes memoryCoreChroma in continuousTasks.
ai/mcp/server/memory-core/config.mjs still points engines.chroma at port 8001 and retains chromaUnified / engines.kb.chroma remnants.
ai/mcp/server/knowledge-base/config.mjs still retains chromaUnified.

Lineage check: #11011 closed on 2026-05-09, but git blame shows memoryCoreChroma was added later by commit 94cd337c0d on 2026-05-15. This is therefore a post-retirement regression, not unfinished #11011 scope.

The Fix

Restore unified-only topology in the live daemon/runtime path:

Remove the orchestrator-owned memoryCoreChroma continuous task and its PID state from TaskDefinitions / orchestrator expectations.
Point Memory Core's default Chroma client coordinates at the shared Chroma daemon (localhost:8000) instead of a Memory Core-only 8001 daemon.
Remove or neutralize remaining chromaUnified / federated mirror-block config surfaces that survived #11011 where they affect runtime behavior.
Add focused unit coverage proving the orchestrator no longer defines or supervises memoryCoreChroma and Memory Core defaults resolve to the shared Chroma port.
Preserve collection separation (neo-agent-memory, neo-agent-sessions, neo-knowledge-base) inside the single Chroma daemon; do not collapse logical collections.

Contract Ledger Matrix

Target Surface	Source of Authority	Proposed Behavior	Fallback	Docs	Evidence
Orchestrator Chroma process supervision	ADR 0003 + #11011	Only the shared `chroma` daemon is supervised by the orchestrator	Manual operator can still restart `npm run ai:orchestrator`; no `memoryCoreChroma` task exists	ADR 0003	Unit test: task definitions and orchestrator state omit `memoryCoreChroma`
Memory Core Chroma client coordinates	ADR 0003 + `HealthService.buildTopologyBlock()`	Memory Core connects to shared `engines.chroma` on `localhost:8000` by default	Operator override via canonical `NEO_CHROMA_HOST` / `NEO_CHROMA_PORT` remains available	Deployment docs / config comments	Unit test: config default port is `8000`
Logical collection separation	Memory Core / KB collection configs	KB and MC share the daemon but keep distinct collection names	No fallback; collection collision is a correctness bug	Config JSDoc	Existing collection-name tests plus targeted assertion if needed

Acceptance Criteria

buildTaskDefinitions() no longer returns a memoryCoreChroma task.
Orchestrator continuous supervision no longer includes memoryCoreChroma.
Memory Core's default engines.chroma.port resolves to the shared Chroma port (8000) unless explicitly overridden by canonical env vars.
Remaining runtime chromaUnified / federated mirror-block reads are removed or proven inert with tests.
Focused Playwright unit coverage passes for daemon task definitions and Memory Core Chroma defaults.
PR body includes operator validation note: after merge/restart, ps / lsof should show one Chroma listener for KB + MC, not two.

Out of Scope

Does not solve the parallel summary + kbSync startup race; #11487 / PR #11489 owns that.
Does not kill live PIDs as part of the PR. Operational cleanup should happen manually after the code fix lands.
Does not migrate existing vector data between .neo-ai-data/chroma/memory-core and .neo-ai-data/chroma/knowledge-base; if data migration is needed, file a separate explicit migration ticket.
Does not change embedding provider selection or vector dimensions.

#9999 — Cloud-Native Knowledge & Multi-Tenant Memory Core
#11011 — Retire chromaUnified flag + federated Chroma topology
#11487 / PR #11489 — maintenance backpressure for parallel heavy tasks
#11471 — stale MLX Gemma 2 model source fix; distinct from this live stale-process/topology issue
ADR 0003 — learn/agentos/decisions/0003-chroma-topology-unified-only.md

Handoff Retrieval Hints: memoryCoreChroma TaskDefinitions ADR 0003 unified-only Chroma regression, orchestrator adopts memory core chroma PID 2078 port 8001, 94cd337c0d added memoryCoreChroma after #11011

tobiu referenced in commit 91983d6 - "fix(ai): remove memory core chroma daemon task (#11496) (#11499) on May 16, 2026, 11:33 PM

tobiu closed this issue on May 16, 2026, 11:33 PM