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	12417
title	Ticket A — NEO_AI_DATA_ROOT canonical shared data-root resolution
state	Closed
labels	enhancementaiarchitectureneeds-re-triage
assignees	[]
createdAt	Jun 3, 2026, 5:49 AM
updatedAt	Jun 5, 2026, 7:26 PM
githubUrl	https://github.com/neomjs/neo/issues/12417
author	neo-opus-ada
commentsCount	4
parentIssue	12416
subIssues	[]
subIssuesCompleted	0
subIssuesTotal	0
blockedBy	[]
blocking	[]
closedAt	Jun 5, 2026, 7:26 PM

Ticket A — NEO_AI_DATA_ROOT canonical shared data-root resolution

Closed Backlog/active-chunk-17 enhancementaiarchitectureneeds-re-triage

neo-opus-ada commented on Jun 3, 2026, 5:49 AM

Part of Epic #12416 (graduated from Discussion #12412).

Context

Each clone/worktree defaults .neo-ai-data to cwd-relative, requiring a manual bootstrapWorktree --link-data symlink pass. Missing it -> isolated graph -> bound:false (the live @neo-claude-opus failure tonight, #11812: the memory-core clone missed the identityRoots.mjs pull -> empty per-clone graph).

Scope

Introduce a NEO_AI_DATA_ROOT config/env that resolves the shared canonical data root, so all consumers that persist Agent OS runtime state can read one shared location by config instead of depending on per-clone symlinks.

The shipped surface is broader than the original graph/chroma/wake shorthand:

Top-level AI config: aiDataRoot, backup path, wake-daemon heartbeat sentinel, and Chroma persist directory defaults.
Memory Core config: graph SQLite, wake-daemon watermarks/cursors, REM run state, RLAIF dataset path, and shared MCP logs.
Knowledge Base / Neural Link configs: shared aiDataRoot and shared log directory; KB Chroma path follows top-level AiConfig.engines.chroma.dataDir. Their telemetry/action-log DB sinks stay on their existing explicit keys unless narrower overrides move them.
Daemon and lifecycle runtime state: bridge DB/state/logs, orchestrator task/chroma/data defaults, orchestrator daemon state, heavy-maintenance lease, wake-decision backoff, wake safety gate, inflight/heartbeat locks, trio/resume cooldowns, harness lifecycle state, and heartbeat liveness lookup.
Operator startup guidance: AGENTS_STARTUP.md documents when NEO_AI_DATA_ROOT replaces --link-data for independent clones and that identity-root seeding is additive, not garbage-collecting.

Existing narrower overrides still win when explicitly set.

Acceptance Criteria

AC1: NEO_AI_DATA_ROOT (env/config) resolves the shared data root; memory-core graph, Chroma, wake-daemon state, and sibling Agent OS runtime-data surfaces honor it.
AC2: with it set, a fresh clone needs NO .neo-ai-data symlinks to share the graph -- the clone-staleness bound:false class is structurally removed.
AC3: back-compat -- unset -> current cwd/script-root defaults (no regression); narrower overrides preserve prior precedence.
AC4: AGENTS_STARTUP docs updated.

Contract Ledger

Surface	Source of Authority	Behavior	Fallback	Evidence
`NEO_AI_DATA_ROOT` / `aiDataRoot`	this ticket / Epic #12416 / Discussion #12412	canonical shared Agent OS runtime data root for graph, Chroma, wake-daemon state, backups, logs, REM, datasets, orchestrator state, locks, cooldowns, harness state, and heartbeat liveness	historical cwd/script-root `.neo-ai-data` defaults when unset	unit + post-merge fresh-clone validation
Narrower path overrides	existing config/env contract	path-specific overrides win over the shared-root default (`NEO_MEMORY_DB_PATH`, `NEO_AI_DB_PATH`, `NEO_AI_DAEMON_DIR`, `NEO_CHROMA_DATA_DIR`, `NEO_BACKUP_PATH`, `NEO_HEARTBEAT_ALIVE_PATH`, `WAKE_GATE_FILE_PATH`, and sibling explicit keys)	shared-root-derived path	unit
Top-level `ai/config.template.mjs`	this ticket	`backupPath`, `wakeDaemonHeartbeatAlivePath`, and `engines.chroma.dataDir` derive from `aiDataRoot`	`<neoRootDir>/.neo-ai-data/...`	unit / static config-shape
Memory Core config template	this ticket	graph SQLite, wake-daemon watermarks/cursors, REM run state, RLAIF dataset path, and Memory Core logs derive from `aiDataRoot`	`<neoRootDir>/.neo-ai-data/...` or explicit narrower override	unit
Knowledge Base / Neural Link config templates	this ticket	shared `aiDataRoot` and shared logs directory; KB Chroma follows top-level `AiConfig.engines.chroma.dataDir`; telemetry/action-log DB sinks remain on their existing explicit keys	existing per-server defaults / explicit DB overrides	unit
Bridge / orchestrator / lifecycle runtime defaults	this ticket	bridge DB/state/logs, orchestrator state/tasks, Chroma launch path, heavy-maintenance lease, wake decision/backoff, wake safety gate, inflight and heartbeat locks, trio/resume cooldowns, harness lifecycle state, and heartbeat liveness resolve below `NEO_AI_DATA_ROOT` when set	prior relative or script-root defaults when unset	unit + `node --check`
Operator startup guidance	`AGENTS_STARTUP.md`	documents `NEO_AI_DATA_ROOT` as the tracked config/runtime equivalent of data symlinks for independent clones and documents additive identity-root seeding	`bootstrapWorktree --link-data` remains the default for true git worktrees	docs + peer A2A

Epic #12416; design Discussion #12412; failure anchor #11812; PR #12420; complements bootstrapWorktree --link-data (#12401 bridge-to-wake rename adjacent).

tobiu Jun 5, 2026, 7:26 PM

already resolved.

tobiu closed this issue on Jun 5, 2026, 7:26 PM