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.

Neo.mjs - Self-Evolving Software Organism

Frontmatter

title	feat(ai): rename Chroma persist store to unified (#12155)
author	neo-opus-ada
state	Merged
createdAt	May 29, 2026, 3:55 AM
updatedAt	May 31, 2026, 6:26 PM
closedAt	May 31, 2026, 6:26 PM
mergedAt	May 31, 2026, 6:26 PM
branches	`dev` ← `feat/12155-chroma-rename-unified`
url	https://github.com/neomjs/neo/pull/12162

Merged

neo-opus-ada commented on May 29, 2026, 3:55 AM

Authored by Claude Opus 4.8 (Claude Code), @neo-opus-ada. Session efd8dc2e-2052-4089-814a-ab22cd8c6a62.

FAIR-band: moot — sole active implementer (@neo-gpt reviews-only at ~1%; @neo-gemini-pro benched).

Evidence: L2 — config.template + KB/MC config.template + DestructiveOperationGuard specs green (26 passed) + node --check. L3 — the one-time local data move is a manual operator step (below), NOT shipped code.

Resolves #12155 (sub of Epic #12153; implements ADR 0017).

Summary

Renames the single Chroma persist store leaf knowledge-base → unified (local + cloud), implementing ADR 0017's one-flat-store decision + dev/prod parity. The dir holds every realm (KB + MC + sessions + graph), so a realm-specific name misrepresented it.

engines.chroma.dataDir SSOT + the orchestrator chroma --path + the ai:server script → …/chroma/unified.
The three deploy compose files mount /chroma/unified + set PERSIST_DIRECTORY=/chroma/unified (the chromadb/chroma:1.5.9 image persists to its WORKDIR-relative default and ignores a mount-only change — verified vs the 1.5.9 source).
Config test specs + fixtures updated to the unified leaf.

Net diff: 13 files, ~55 lines.

One-time local migration (manual — this is the only deployment that exists)

No migration code ships — it would be permanent dead code after a single run on the one machine that exists. The live data moves once on @tobiu's machine, stack stopped:

Stop the AI stack (orchestrator + the chroma daemon).
Back up: cp -r .neo-ai-data/chroma/knowledge-base .neo-ai-data/backups/chroma-kb-$(date +%s)
mv .neo-ai-data/chroma/knowledge-base .neo-ai-data/chroma/unified
(optional) rm -rf .neo-ai-data/chroma/memory-core — the stale federated leftover.
Restart with the new config.

Decision Record impact

aligned-with ADR 0017 (Single Flat Unified Store). No new ADR.

Deltas from ticket

Trimmed from a migration framework to a rename + a manual step. The first pass (commits f6d47e238 / 803dc3bd1) built an idempotent migration script + an orchestrator strand-guard + a 315-line spec (~1000 lines). Per operator review, that is over-engineering for a ONE-TIME mv on the single machine that exists — it would be permanent dead code. The d3624c7d0 commit removes it; the migration is the documented manual step above. (On squash-merge, dev gets a single clean rename-only commit.)
Out of scope (flagged): stale /chroma/chroma / knowledge-base path refs in learn/agentos/cloud-deployment/PipelineWiring.md + learn/agentos/tooling/RestorationRunbook.md belong to the guides sub #12158.

Test Evidence

npm run test-unit -- <config.template + KB/MC config.template + DestructiveOperationGuard specs> — 26 passed.
node --check on every edited .mjs: clean.

Post-Merge Validation

@tobiu runs the one-time manual migration above (stack stopped → backup → mv → restart); confirm the unified store serves (KB + MC search green).
Cloud (when a deployment exists): confirm PERSIST_DIRECTORY=/chroma/unified + the mount persist on a fresh deploy.

Commits

f6d47e238 rename + (since-removed) migration framework · 803dc3bd1 strip ticket-id comment refs · d3624c7d0 trim to rename-only.

neo-opus-ada commented on May 31, 2026, 3:37 PM

Input from Claude Opus 4.8 (Claude Code):

❋ Author triage (V-B-A on current dev, 2026-05-31):

This branch is 61 commits behind dev with config.template.mjs structurally refactored under it (the leaf() / Provider metaTree work) — 6 conflicts; too stale to cleanly rebase.

Re-reading the actual diff, this PR is rename-only: SSOT engines.chroma.dataDir + orchestrator --path + 3 compose mounts/PERSIST_DIRECTORY env + package.json ai:server + 6 test expectations, all chroma/knowledge-base → chroma/unified. It does not implement #12155's AC2 (one-time migration: relocate live data + delete stale memory-core, snapshot-first) or AC3 (live HealthService topology: 'unified' + KB/MC search-green verification).

Concern: shipping the rename without the companion migration repoints the Chroma persist dir at an empty unified dir → forces a KB re-sync + MC vector re-embed on deploy. That's exactly the disruption AC2's migration exists to avoid, and with the multi-tenant cloud deployment now live it's a high-blast change touching live-deployment data (recoverable, but disruptive). The rename + migration should ship together (or migration-first), with live verification.

Recommendation: Drop+Supersede — close this stale branch and rebuild fresh on current dev, bundling rename + AC2 migration + AC3 verification under a re-scoped #12155. Holding the close pending @neo-gpt (lead) coordination + likely operator awareness, since it touches live-deployment data rather than something I should ship autonomously in an idle window.