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	16254
title	Compose mounts Chroma storage off the image-pinned /data persist path
state	Closed
labels	[]
assignees	neo-opus-vega
createdAt	Aug 1, 2026, 1:03 PM
updatedAt	Aug 1, 2026, 1:31 PM
githubUrl	https://github.com/neomjs/neo/issues/16254
author	neo-opus-vega
commentsCount	0
parentIssue	null
subIssues	[]
subIssuesCompleted	0
subIssuesTotal	0
contentTrust
projected
quarantined	0
signals	[]
blockedBy	[]
blocking	[]
closedAt	Aug 1, 2026, 1:31 PM

Compose mounts Chroma storage off the image-pinned /data persist path

Closed Backlog/active-chunk-11 []

neo-opus-vega commented on Aug 1, 2026, 1:03 PM

Context

The chromadb/chroma:1.5.9 container's entrypoint executes chroma run /config.yaml; that shipped config pins persist_path: "/data", and PERSIST_DIRECTORY is not read on that path. All three base compose files mounted their storage surface at /chroma/unified and declared PERSIST_DIRECTORY=/chroma/unified — so the live store accumulated in the container's ephemeral writable layer while the mounted volume stayed empty. Live census on the canonical plane: /data = 1.1 GB, mounted /chroma/unified = 4 KB.

Incident owner: #16208 (corrected root cause + the v4.1 recovery plan). This leaf owns exactly the compose mount contract and its authority surfaces — fully delivered by one PR. The recovery execution (quiesced physical seed, recreate-survival proofs, reconciliation receipts) stays on #16208 and must NOT auto-close with this leaf.

Duplicate sweep: #16208 is the incident (open, non-closing here); #16206 is deploy layering; #16219 (Docker-owned volumes) is closed. No open ticket owns the mount contract itself.

Contract Ledger

Target Surface	Source of Authority	Proposed Behavior	Fallback	Docs	Evidence
`ai/deploy/docker-compose.yml` chroma service	the audited image entrypoint + shipped `/config.yaml` (`persist_path: "/data"`); live census	named volume `chroma-data:/data`; `PERSIST_DIRECTORY=/data` declared on the same leaf	exact image-pin assertion forces re-verification of the shipped config before any tag bump	ADR 0017 §2.2 (corrected in place)	`ChromaPersistPathContract.spec.mjs` RED→GREEN
`ai/deploy/docker-compose.dev.yml` chroma service	same	`parity-chroma:/data`; env aligned	same	same	same spec
`ai/deploy/docker-compose.test.yml` chroma service	same	tmpfs at `/data`; env aligned	same	same	same spec
ADR 0017 active prose	the falsification evidence	abstract / Decision / §2.2 / rejected-alternative row / handoff consistently state one-store topology + LOGICAL parity with the image-owned container leaf `/data`; the dated falsification record is retained as archaeology	—	the ADR itself	zero active `/chroma/unified` prescriptions remain
`learn/agentos/cloud-deployment/PipelineWiring.md` persistence row	ADR 0017 §2.2 (corrected)	names `/data` and why	—	the row	updated in the same PR

Acceptance Criteria

All three base compose chroma services mount storage at /data with PERSIST_DIRECTORY aligned; zero storage surfaces target /chroma/unified.
ChromaPersistPathContract.spec.mjs guards the contract per file with a positive control (service exists + exact image pin) so the negatives cannot pass vacuously; demonstrated RED against the old shape, GREEN after.
ADR 0017's ACTIVE prose consistently distinguishes one-store topology / logical parity from the image-pinned container leaf; the falsification record remains.
PipelineWiring's persistence row names /data.
The diff is inert for the live plane (no recreate is triggered by merging); all recovery receipts remain on #16208.

Out of Scope

The v4.1 recovery execution — #16208 owns it.
Overlay compose files (inherit the corrected base definitions; introduce no storage override — reviewer-verified on PR #16252).
Server-side NEO_CHROMA_DATA_DIR / engines.chroma.dataDirProd host-path semantics — a different contract.
Deploy layering — #16206.

#16208 — incident owner (corrected root cause + v4.1 execution receipts); related, non-closing.
#16167 — the migration epic.
#16206 — deploy layering.

Origin Session ID: c4b84de4-d7d9-4cbf-99cc-5bd4a561783e

Retrieval Hint: chroma persist path data compose mount PERSIST_DIRECTORY image pinned named volume ephemeral writable layer store loss ADR 0017

tobiu referenced in commit 247dbbc - "fix(deploy): mount Chroma at its image-pinned /data persist path (#16254) (#16252)" on Aug 1, 2026, 1:31 PM

tobiu closed this issue on Aug 1, 2026, 1:31 PM