Context
The broader repair investigation in #13496 needs a first deliverable that does not falsely claim the whole repair path is complete. This leaf exists so a PR can ship the low-risk diagnostic slice: make stored-embedding exportability visible as its own Chroma health axis.
Live latest-open sweep: checked the latest 20 open issues on 2026-06-19; only the broader #13496 existed, and no equivalent diagnostic leaf was found.
A2A in-flight claim sweep: checked the latest 30 incoming messages on 2026-06-19; no competing claim for a Chroma stored-embedding exportability diagnostic was present.
Local exact sweep: rg "stored-embedding exportability|stored embedding exportability|exportability probe|Chroma stored-embedding|checkChromaIntegrity" resources/content/issues resources/content/discussions returned no equivalent ticket.
Release classification: boardless (post-release hardening / operator diagnostic; useful immediately, but not a release blocker).
The Problem
The current local Chroma evidence can split into different truths:
- Collection count, metadata/document reads, and query canaries can still work.
- Backup, defrag, and repair workflows that need
include: ['embeddings'] can fail on specific stored vector ids.
Without a separate stored-embedding exportability probe, a healthy query path can hide an export/backup hazard. That delays the decision between safe repair, rebuild, or collection-scoped restore.
The Architectural Reality
ai/scripts/maintenance/checkChromaIntegrity.mjs already owns the copy-first SQLite integrity check and read-only Chroma API probe surface. It is the correct substrate because it is operator-invoked, intentionally outside hot healthcheck paths, and already prints both human and JSON results.
ADR 0017 keeps local and cloud deployments on a single flat unified Chroma store with realm separation at collection/metadata/export layers. A collection-level exportability probe is aligned with that model: it checks the export layer directly without changing daemon topology or adding healthcheck load.
The Fix
Extend ai/scripts/maintenance/checkChromaIntegrity.mjs with a bounded stored-embedding exportability sample:
- Sample ids from each configured collection.
- For each sampled id, run a single-id
collection.get({ ids: [id], include: ['embeddings'] }).
- Report a distinct
stored embedding exportability step with sampled/succeeded/failed counts and per-id failures.
- Add
--exportability-sample-size <count> so operators can keep the probe cheap or deepen it during repair triage.
- Cover the helper behavior in
test/playwright/unit/ai/scripts/maintenance/CheckChromaIntegrity.spec.mjs.
Contract Ledger Matrix
| Target Surface |
Source of Authority |
Proposed Behavior |
Fallback |
Docs |
Evidence |
checkChromaIntegrity.mjs JSON API probe |
Existing maintenance diagnostic |
Add a stored embedding exportability step separate from query by existing embedding |
Step fails with a bounded error/failure list; script remains read-only |
Script usage block and PR body |
Focused unit coverage |
| Human CLI output |
Existing printHuman() diagnostic surface |
Print sampled/succeeded/failed counts for exportability steps |
If the API cannot connect, keep the existing API-level error |
Script output |
Syntax check + unit coverage |
--exportability-sample-size <count> |
Existing Commander CLI options |
Bound the number of sampled ids per collection |
Invalid or less-than-one values normalize to the exported default |
Commander help text |
Unit coverage |
Decision Record impact
aligned-with ADR 0017 (learn/agentos/decisions/0017-chroma-single-flat-unified-store.md): probes collection-scoped export behavior inside the unified store, without adding a daemon, folder split, or hot healthcheck dependency.
Acceptance Criteria
Out of Scope
- Repairing corrupt or orphaned Chroma embeddings.
- Rebuilding any collection.
- Changing backup/restore payload formats.
- Changing KB/MC healthcheck hot paths.
- Closing the broader #13496 repair investigation.
Related
Related: #13496
Related: #13467
Handoff Retrieval Hint: query_raw_memories("Chroma stored embedding exportability checkChromaIntegrity #13496")
Context
The broader repair investigation in #13496 needs a first deliverable that does not falsely claim the whole repair path is complete. This leaf exists so a PR can ship the low-risk diagnostic slice: make stored-embedding exportability visible as its own Chroma health axis.
Live latest-open sweep: checked the latest 20 open issues on 2026-06-19; only the broader #13496 existed, and no equivalent diagnostic leaf was found.
A2A in-flight claim sweep: checked the latest 30 incoming messages on 2026-06-19; no competing claim for a Chroma stored-embedding exportability diagnostic was present.
Local exact sweep:
rg "stored-embedding exportability|stored embedding exportability|exportability probe|Chroma stored-embedding|checkChromaIntegrity" resources/content/issues resources/content/discussionsreturned no equivalent ticket.Release classification: boardless (post-release hardening / operator diagnostic; useful immediately, but not a release blocker).
The Problem
The current local Chroma evidence can split into different truths:
include: ['embeddings']can fail on specific stored vector ids.Without a separate stored-embedding exportability probe, a healthy query path can hide an export/backup hazard. That delays the decision between safe repair, rebuild, or collection-scoped restore.
The Architectural Reality
ai/scripts/maintenance/checkChromaIntegrity.mjsalready owns the copy-first SQLite integrity check and read-only Chroma API probe surface. It is the correct substrate because it is operator-invoked, intentionally outside hot healthcheck paths, and already prints both human and JSON results.ADR 0017 keeps local and cloud deployments on a single flat unified Chroma store with realm separation at collection/metadata/export layers. A collection-level exportability probe is aligned with that model: it checks the export layer directly without changing daemon topology or adding healthcheck load.
The Fix
Extend
ai/scripts/maintenance/checkChromaIntegrity.mjswith a bounded stored-embedding exportability sample:collection.get({ ids: [id], include: ['embeddings'] }).stored embedding exportabilitystep with sampled/succeeded/failed counts and per-id failures.--exportability-sample-size <count>so operators can keep the probe cheap or deepen it during repair triage.test/playwright/unit/ai/scripts/maintenance/CheckChromaIntegrity.spec.mjs.Contract Ledger Matrix
checkChromaIntegrity.mjsJSON API probestored embedding exportabilitystep separate fromquery by existing embeddingprintHuman()diagnostic surface--exportability-sample-size <count>Decision Record impact
aligned-with ADR 0017 (
learn/agentos/decisions/0017-chroma-single-flat-unified-store.md): probes collection-scoped export behavior inside the unified store, without adding a daemon, folder split, or hot healthcheck dependency.Acceptance Criteria
checkChromaIntegrity.mjsreports stored-embedding exportability as a separate read-only API step.Out of Scope
Related
Related: #13496 Related: #13467
Handoff Retrieval Hint:
query_raw_memories("Chroma stored embedding exportability checkChromaIntegrity #13496")