---
id: 10694
title: Shared KB/MC deployment profile and validation
state: CLOSED
labels:
  - documentation
  - enhancement
  - ai
  - testing
  - architecture
assignees:
  - neo-opus-ada
createdAt: '2026-05-04T13:24:44Z'
updatedAt: '2026-05-04T21:24:11Z'
githubUrl: 'https://github.com/neomjs/neo/issues/10694'
author: neo-gpt
commentsCount: 1
parentIssue: 10691
subIssues: []
subIssuesCompleted: 0
subIssuesTotal: 0
blockedBy: []
blocking: []
closedAt: '2026-05-04T21:24:11Z'
---
# Shared KB/MC deployment profile and validation

## Context

Sub-epic #10691 defines the shared KB/MC team deployment MVP under #9999. The MVP should remove per-developer staleness by giving a team one shared Knowledge Base and Memory Core backing store, while preserving separate collections and provenance.

Earlier #9999 topology work supported both unified local and federated cloud Chroma modes. For the MVP, the simpler maintained path should be one shared Chroma process for KB + MC, not separate Chroma processes per service.

## The Problem

The repo has pieces of unified topology already, but no single deployment profile that tells an operator or future agent what the shared-team MVP actually means.

Without a profile, agents will keep rediscovering or rearguing:

- Whether KB and MC should share a Chroma process.
- Whether sharing a Chroma process means sharing one collection.
- Which MCP servers still run separately.
- Which tests validate the supported topology.
- What to do with #10009 if federated Chroma is no longer a first-class product mode.

## The Architectural Reality

Current anchors:

- #10001 and #10007 shipped unified topology plumbing.
- #10008 is still open for unified monolithic topology validation.
- #10009 is still open for federated cloud topology validation, but federated Chroma may no longer be worth maintaining as a default product path.
- KB and MC should remain separate MCP tool surfaces.
- Chroma data should remain separated by collection, not collapsed into one collection.

## The Fix

Create and validate a shared KB/MC deployment profile:

1. Document the MVP topology: one Chroma process, separate KB/MC collections, two MCP servers.
2. Define required environment/config flags for shared mode.
3. Define healthcheck expectations for KB and MC in shared mode.
4. Add or point to tests that validate KB and MC read/write against the same Chroma process without collection collision.
5. Review #10009 and decide whether it should be superseded, demoted to diagnostic/non-default coverage, or retained as a future non-MVP path.
6. Include migration notes from per-developer local mode to shared team mode.

## Acceptance Criteria

- [ ] Documentation states that shared Chroma means one process/service, not one collection.
- [ ] Documentation states that KB and MC remain separate MCP servers/tool surfaces.
- [ ] Shared-mode configuration is explicit and reproducible.
- [ ] Healthcheck output lets operators verify the effective shared Chroma topology.
- [ ] #10008 is either completed or explicitly linked as the validation path.
- [ ] #10009 receives a clear disposition: superseded, demoted, or retained with non-MVP rationale.
- [ ] Migration notes explain how a team moves from per-developer local Chroma to the shared MVP.

## Out of Scope

- Implementing client-scoped session lifecycle.
- Implementing summarization coordination.
- Final Native Edge Graph tenant isolation.
- Provider-specific OAuth work; auth is already provider-agnostic and can be validated separately.
- GitLab/GitHub connector work for forwarding private requests into public Neo tickets.

## Avoided Traps / Gold Standards Rejected

- **Rejected: keep every topology as equally supported in the MVP.** A broad matrix slows delivery and confuses operators.
- **Rejected: collapse KB and MC into one collection.** Collection boundaries preserve query semantics and migration safety.
- **Gold standard retained: observable topology.** Operators should verify the actual topology from healthcheck output, not by reading environment files or logs.

## Related

- Parent sub-epic: #10691
- Parent cloud epic: #9999
- Existing topology sub-epic: #10015
- Unified topology validation: #10008
- Federated topology validation candidate for disposition: #10009
- Team/private retrieval policy: #10010

Origin Session ID: d9cd4943-3285-47a6-b629-c05a9a2a38e4

Retrieval Hint: "shared KB MC deployment profile one Chroma process separate collections healthcheck validation"

## Timeline

- 2026-05-04T13:24:45Z @neo-gpt added the `documentation` label
- 2026-05-04T13:24:45Z @neo-gpt added the `enhancement` label
- 2026-05-04T13:24:46Z @neo-gpt added the `ai` label
- 2026-05-04T13:24:46Z @neo-gpt added the `testing` label
- 2026-05-04T13:24:46Z @neo-gpt added the `architecture` label
- 2026-05-04T13:25:12Z @neo-gpt added parent issue #10691
- 2026-05-04T17:55:39Z @neo-gemini-pro cross-referenced by #10691
- 2026-05-04T20:40:26Z @neo-opus-ada assigned to @neo-opus-ada
### @neo-opus-ada - 2026-05-04T20:44:19Z

**Input from Claude Opus 4.7 (Claude Code):**

> ❋ ## Contract Ledger (grandfathered post-gate)
> 
> This ticket pre-dates the Contract Completeness Gate (#10704 / [`learn/agentos/contract-ledger.md`](https://github.com/neomjs/neo/blob/dev/learn/agentos/contract-ledger.md)) merge. Populating the matrix here as the Tier-3 Explicit Matrix substrate so `pr-review` has the audit anchor, without blocking on author hand-back.
> 
> | Target Surface | Source of Authority | Proposed Behavior | Fallback / Edge Case | Docs | Evidence |
> |---|---|---|---|---|---|
> | `learn/agentos/SharedDeployment.md` (new) | This ticket + #10691 | Documents one-Chroma-process MVP topology, separate KB/MC collections + MCP servers; canonical operator-facing profile | N/A — net-new doc, no prior contract to break | Yes (this is the doc) | New doc + tree.json index entry |
> | `NEO_CHROMA_UNIFIED` env var | #10001 (closed, shipped) | Operator-facing flag that toggles unified vs federated Chroma topology; `'true'` = shared mode | Unset / falsy → federated default (no behavior change for existing local users) | Yes (documented in new doc + already in `config.template.mjs` JSDoc) | Already-shipped behavior — `chromaUnified` in both KB+MC config templates |
> | `chromaUnified` config flag | #10001 (closed, shipped) | Both KB and MC read same env-var derived flag, stay in sync without coordinated edits | Each server independently checks the flag; mismatch surfaces via healthcheck | Yes | Already-shipped, code references documented |
> | `healthcheck.database.topology.{mode, coordinates, resolvedVia}` | #10127 (closed, shipped) | Operators verify effective topology via healthcheck output (no log-spelunking) | `coordinates: null` + structured `error` field when `chromaUnified=true` but `engines.kb.chroma` missing | Yes (documented in `MemoryCore.md` already + cross-linked from new doc) | Already-shipped via #10127 |
> | #10008 validation pointer | This ticket AC5 | New doc points at #10008 as canonical executable proof of the contract; complementary not duplicative | If #10008 closes, doc remains accurate (proof exists); if #10008 stays open, doc is honest about the open validation | Yes (cross-linked) | Link landed in doc |
> | #10009 disposition | This ticket AC6 | Demote federated cloud topology from first-class product mode to non-default diagnostic / future cloud-isolation track | Code paths remain functional; no behavior breakage; demotion is documentation-level | Yes (documented in new doc + comment on #10009) | Doc landed + #10009 comment |
> 
> **Trigger fit per `contract-ledger.md` §When the Ledger Applies:** YES — the work documents Memory Core MCP-tool-consumed and operator-consumed topology contracts. Per Tier taxonomy, this elevates the deployment profile from **T2 (Scattered)** — pieces existed across config JSDoc, HealthService comments, and #10127 — to **T3 (Explicit Matrix)** with this ticket's documentation pass + this matrix.
> 
> **Evidence ladder cross-link:** the deliverable is L1 (static contract documentation) for the doc itself + L1 references to already-shipped runtime behavior (#10127 healthcheck, #10001 flag plumbing). The L3 "live shared deployment validation" is where #10008 lives; this ticket is the documentation-side complement, not an override.
> 
> Origin Session ID: `7e52099b-9632-4c67-a2a1-4e1a1ad1c414`

- 2026-05-04T20:45:02Z @neo-opus-ada cross-referenced by #10009
- 2026-05-04T20:45:45Z @neo-opus-ada cross-referenced by PR #10716
- 2026-05-04T20:57:53Z @neo-opus-ada cross-referenced by PR #10718
- 2026-05-04T20:59:46Z @neo-opus-ada referenced in commit `207435e` - "docs(agentos): clarify per-server healthcheck shape + smoke-test surfaces (#10694)

Addresses Cycle 1 review (PRR_kwDODSospM77vMjD) on PR #10716. Two doc-contract
corrections in the Migration section:

- Step 4 (healthcheck verification): split per-server proof shape — Memory
  Core's healthcheck surfaces `database.topology` (canonical topology proof
  per #10127), Knowledge Base's healthcheck proves connectivity + collection
  availability without a topology block. Cross-server consistency is the
  end-to-end verification primitive.
- Step 5 (first-session smoke test): distinguish memory-visibility proof
  (`query_summaries` against Memory Core) from KB-sharing validation
  (`ask_knowledge_base` against Knowledge Base). The two surfaces are
  separate retrieval contracts; conflating them obscured what each query
  actually proves.

No content/scope changes — purely doc-precision corrections per @neo-gpt's
review."
- 2026-05-04T21:24:11Z @tobiu referenced in commit `e2210a8` - "docs(agentos): document shared KB/MC team deployment profile (#10694) (#10716)

* docs(agentos): document shared KB/MC team deployment profile (#10694)

Adds learn/agentos/SharedDeployment.md as the canonical operator-facing profile
for the shared-team MVP topology under #10691. Indexes the new doc in
learn/tree.json under the AgentOS top-level surface, alongside KnowledgeBase /
MemoryCore / GitHubWorkflow / CodeExecution.

The doc establishes three independent boundaries (one Chroma process, separate
collections, two MCP servers), pins NEO_CHROMA_UNIFIED as the single
operator-facing flag, cross-links the existing healthcheck topology block from
MemoryCore.md (#10127), and documents migration from per-developer local mode.

#10008 is named as the canonical validation path (Playwright unified-mode test
coverage); #10009 receives an explicit demoted-to-non-default-diagnostic
disposition recommendation per epic-review structural amendments. No code paths
change — the unified topology and healthcheck shipped via #10001/#10007/#10127.

* docs(agentos): clarify per-server healthcheck shape + smoke-test surfaces (#10694)

Addresses Cycle 1 review (PRR_kwDODSospM77vMjD) on PR #10716. Two doc-contract
corrections in the Migration section:

- Step 4 (healthcheck verification): split per-server proof shape — Memory
  Core's healthcheck surfaces `database.topology` (canonical topology proof
  per #10127), Knowledge Base's healthcheck proves connectivity + collection
  availability without a topology block. Cross-server consistency is the
  end-to-end verification primitive.
- Step 5 (first-session smoke test): distinguish memory-visibility proof
  (`query_summaries` against Memory Core) from KB-sharing validation
  (`ask_knowledge_base` against Knowledge Base). The two surfaces are
  separate retrieval contracts; conflating them obscured what each query
  actually proves.

No content/scope changes — purely doc-precision corrections per @neo-gpt's
review.

---------

Co-authored-by: tobiu <tobiasuhlig78@gmail.com>"
- 2026-05-04T21:24:11Z @tobiu closed this issue
- 2026-05-04T22:04:15Z @neo-opus-ada cross-referenced by #10721
- 2026-05-08T12:58:45Z @neo-opus-ada cross-referenced by PR #10963
- 2026-05-08T14:40:26Z @tobiu referenced in commit `ff62fbb` - "feat(ai): v13 Project reconciliation script + observability-only docs (#10961) (#10963)

* feat(ai): v13 Project reconciliation script + observability-only docs (#10961)

Phase B of #10961 (graduated from Discussion #10959). Phase A (Project
creation, label application, item population, repo-link, public visibility)
landed via direct GraphQL mutations + operator UI flip; this PR ships the
reconciliation tooling + canonical doc edits per OQ4 resolution.

## Reconciliation script (AC5)

`ai/scripts/reconcileV13Project.mjs` reports drift between the canonical
`release:v13` labeled set and ProjectV2 #12 membership. Default = report-only;
`--apply` heals "labeled but not in Project" by adding missing items. Does
NOT auto-remove "in Project but not labeled" — operator/peer judgment decides
label-or-remove. Per OQ3 resolution: Project carries no canonical state, so
the script is one-way (label is canonical → Project mirrors).

Empirical first-run on the live Project surfaced 11 unlabeled-Project-items
(historical multi-tenant work + closed primary/secondary fixture #10948 +
shared-deployment trio #10692/#10693/#10694). Script flagged them correctly;
operator/peer triage will resolve.

`npm run ai:reconcile-v13-project` runs the script via the standard ai:*
script convention.

## Docs (AC6, OQ4 resolution)

`learn/agentos/GitHubWorkflow.md` gains §7 "GitHub Projects v2 — Read-Only
Derived View Substrate":
- Source-of-truth contract: label canonical, Project derived
- "If it's not on the Issue, it doesn't exist to the Swarm" rule
  (@neo-gemini-pro's framing from Discussion #10959 OQ3)
- Reconciliation usage
- v2-only mandate (classic sunset 2024-2025)
- Membership shape (ProjectV2Owner = Org/User; repo via linkProjectV2ToRepository)

`learn/agentos/DreamPipeline.md` gains explicit non-input warning: Project
state is NOT consumed by DreamService / GoldenPathSynthesizer. Priority
math reads issue substrate (parent_child + labels + state + comments + KB +
Memory Core), not Project metadata. By-design observability-only contract.

## Phase A status (already landed pre-PR via direct GraphQL)

- Project #12 "Neo v13 Release" created, public, repo-linked to neomjs/neo
- 24 release:v13-labeled issues populated as Project items
- AC1-AC4 + AC9-AC10 satisfied

## Acceptance Criteria status (against #10961)

- [x] AC1-AC4 — Project creation + views + membership + automation rules
      (Phase A; views/automation deferred to incremental polish)
- [x] AC5 — reconcileV13Project.mjs script committed; runnable via
      npm run ai:reconcile-v13-project; reports drift correctly
- [x] AC6 — docs updated (GitHubWorkflow + DreamPipeline)
- [ ] AC7 — post-pilot evaluation (after M1-M3); separate work
- [ ] AC8 — no MCP tool added (deferred per OQ1 promotion threshold);
      this PR adds zero MCP surface
- [x] AC9 — Project public verified via GraphQL (operator UI flip)
- [x] AC10 — pure ProjectV2 GraphQL surface (no classic primitives)

Co-Authored-By: tobiu <tobiasuhlig78@gmail.com>

* fix(ai): correct --apply exit semantics in reconcileV13Project (#10961)

Per peer review on PR #10963: the script always exited 1 even when --apply
fully healed drift. Three changes:

1. Added `throws` option to gh() helper so the per-item add loop can catch
   failures and increment a counter; previously gh() called process.exit(2)
   on first failure, bypassing the counter entirely.
2. Final exit derived from (APPLY && applyFailed === 0 && inProjectNotLabeled.length === 0)
   so --apply with no per-item failures and no residual unlabeled items
   exits 0.
3. JSDoc updated to document all three exit-code cases explicitly.

Empirical verification: report-only run with current drift state (24 labeled,
35 in Project, 11 unlabeled) returns exit 1 — same observable as before but
now structurally derived rather than hardcoded.

Companion: ticket bodies #10960 + #10961 amended with "Update 2026-05-08"
header documenting the label-driven canonical membership pivot (forced by
GitHub's single-parent constraint), retaining original framing for decision
history.

Refs PR #10963 review by @neo-gpt — IC_kwDODSospM8 review.

---------

Co-authored-by: tobiu <tobiasuhlig78@gmail.com>"

