---
id: 12154
title: 'Author amending ADR: one flat unified Chroma store + parity'
state: CLOSED
labels:
  - documentation
  - ai
  - architecture
assignees:
  - neo-opus-ada
createdAt: '2026-05-28T23:43:24Z'
updatedAt: '2026-05-29T01:18:35Z'
githubUrl: 'https://github.com/neomjs/neo/issues/12154'
author: neo-opus-ada
commentsCount: 0
parentIssue: 12153
subIssues: []
subIssuesCompleted: 0
subIssuesTotal: 0
blockedBy: []
blocking: []
closedAt: '2026-05-29T01:18:35Z'
---
# Author amending ADR: one flat unified Chroma store + parity

## Context

Sub of #12153 — the lock-in decision record for the one-flat-`unified`-store topology. This is the formal authority artifact; the code subs (#12153 subs 2–5) implement against it.

## The Fix

- Add a new ADR at `learn/agentos/decisions/00NN-*.md` (next free number), e.g. "Chroma — Single Flat Unified Store + Dev/Prod Parity", `Status: Accepted`.
- **Decision content:** one daemon/container; one flat store named `unified` (local `.neo-ai-data/chroma/unified`, cloud volume `/chroma/unified` — retiring `/chroma/chroma`); **no per-realm folders**; realm/tenant isolation by **collection names + metadata**; KB shipping by **collection-scoped export**; recovery by the **KB-as-cache / MC-as-store backup model**. Local conforms to the cloud reference; the federated-era two-folder layout + stale `memory-core` folder are retired.
- Cross-reference: amends ADR 0003 (preserve its one-daemon core), touches ADR 0014 (cloud topology). Add a forward "amended by #NN" note to ADR 0003.

## Decision Record impact

`amends ADR 0003`; touches `ADR 0014`. `ADR successor-risk: adr-amendment-required` (see parent #12153).

## Acceptance Criteria

- [ ] New ADR added, `Accepted`, amends 0003 + cross-refs 0014.
- [ ] ADR 0003 carries a forward "amended by" pointer.
- [ ] Durable-doc archaeology discipline honored (no decay-prone lane/cycle/AC anchors in the prose; canonical `amends/supersedes #` decision-record refs are fine).

## Out of Scope

All code changes (parent subs 2–5).

## Related

#12153 (parent), ADR 0003, ADR 0014.

Origin Session ID: efd8dc2e-2052-4089-814a-ab22cd8c6a62

## Timeline

- 2026-05-28T23:43:25Z @neo-opus-ada added the `documentation` label
- 2026-05-28T23:43:26Z @neo-opus-ada added the `ai` label
- 2026-05-28T23:43:26Z @neo-opus-ada added the `architecture` label
- 2026-05-28T23:44:22Z @neo-opus-ada added parent issue #12153
- 2026-05-29T00:28:58Z @neo-opus-ada cross-referenced by #12153
- 2026-05-29T00:40:12Z @neo-opus-ada assigned to @neo-opus-ada
- 2026-05-29T00:45:49Z @neo-opus-ada cross-referenced by PR #12159
- 2026-05-29T01:18:35Z @tobiu referenced in commit `7cedc3b` - "docs(ai): ADR 0017 — single flat unified Chroma store + dev/prod parity (#12154) (#12159)

Adds ADR 0017 amending ADR 0003 (Chroma Topology — Unified Only): preserves the
one-daemon core decision and records the store's concrete shape — a single flat
persist store named `unified`, identical local and cloud, with KB/MC/tenant
separation enforced by collection + metadata (isolation), collection-scoped
export (shipping), and the KB-as-cache/MC-as-store backup model (recovery) —
never by directory or daemon split. Retires the federated-era two-folder local
layout (`knowledge-base/` + stale `memory-core/`).

Grounded in a 6-agent plan stress-test of Epic #12153 + a live store/daemon/
cloud-compose audit. Encodes the verified cloud fact (the chromadb image
persists to WORKDIR-relative /chroma/chroma; PERSIST_DIRECTORY is mandatory to
redirect it) and the per-collection-HNSW rationale (one store does not degrade
per-collection search).

Forward-links: ADR 0003 gains an "Amended by ADR 0017" row; ADR 0014 §2.5's
"ADR 0003 needs no amendment" sweep gets a dated forward note (its shared-
primitive / one-container classification is unaffected).

The code subs implement against this record: #12155 (rename+migrate), #12156
(defrag), #12157 (release-privacy), #12158 (guides).

Co-authored-by: tobiu <tobiasuhlig78@gmail.com>"
- 2026-05-29T01:18:35Z @tobiu closed this issue
- 2026-05-31T23:57:27Z @neo-gpt cross-referenced by PR #12280

