---
id: 11963
title: Map Agent OS config defaults into Tier-1 AiConfig
state: CLOSED
labels:
  - enhancement
  - ai
  - architecture
assignees:
  - neo-gpt
createdAt: '2026-05-25T09:45:41Z'
updatedAt: '2026-06-07T17:15:31Z'
githubUrl: 'https://github.com/neomjs/neo/issues/11963'
author: neo-gpt
commentsCount: 0
parentIssue: 10103
subIssues: []
subIssuesCompleted: 0
subIssuesTotal: 0
blockedBy: []
blocking: []
closedAt: '2026-05-25T11:19:31Z'
---
# Map Agent OS config defaults into Tier-1 AiConfig

## Context

Sub-1 of #10103, graduated from Discussion #11961. This sub owns the config ownership ledger and Tier-1 lift for deployment-wide defaults.

## The Problem

KB and Memory Core still expose deployment-wide provider/auth/storage values through server-local config templates. That made sense when the MCP servers were isolated; it is now a cloud deployment footgun because Agent OS runs as one deployment unit.

## The Architectural Reality

Primary surfaces:

- `ai/config.template.mjs`
- `ai/mcp/server/memory-core/config.template.mjs`
- `ai/mcp/server/knowledge-base/config.template.mjs`
- `ai/deploy/docker-compose*.yml`
- Existing `Env` parser and config-template mapping patterns

This is file-group scoped: Tier-1 config plus KB/MC mapping surfaces. Runtime provider dispatch belongs to Sub-2; docs/readiness tests belong to Sub-3.

## The Fix

Move the agreed deployment-wide defaults into Tier-1 config and map them into KB/MC server defaults while preserving server-local overlays and env override precedence.

## Contract Ledger Matrix

| Target Surface | Source of Authority | Proposed Behavior | Fallback / Edge Case | Docs | Evidence |
|---|---|---|---|---|---|
| Tier-1 provider defaults | #10103 / #11961 | Add `chatProvider`, `embeddingProvider`, `openAiCompatible`, `ollama`, and `vectorDimension` ownership to `ai/config.template.mjs` | Preserve legacy names or compatibility reads where implementation finds live consumers | JSDoc on config keys | Import/unit tests for representative keys |
| Tier-1 auth defaults | #11961 OQ1 | Add global `auth.*` deployment defaults where KB/MC currently duplicate shared auth config | Per-server override remains available | Config JSDoc | Tests or targeted config-load smoke |
| Unified Chroma defaults | #11961 OQ3 | Move shared host/port/topology defaults to Tier-1; keep collection names server-local | Env overrides remain final | Config comments | KB/MC config mapping tests |
| KB/MC server overlays | #11961 OQ4 | Map Tier-1 defaults into existing server config defaults | Server-specific config can override for split deployments | Server config comments | Unit/import tests |

## Decision Record impact

Aligned with unified Chroma and Agent OS cloud-deployment direction. No ADR superseded.

## Acceptance Criteria

- [ ] `ai/config.template.mjs` owns deployment-wide provider/auth/storage defaults identified in #10103.
- [ ] KB and Memory Core config templates map those defaults without deleting server-local override capability.
- [ ] Env override precedence remains final and existing env names are preserved or explicitly migrated.
- [ ] Collection/table names, MCP listener ports, parser/scoring/batch knobs, and tenant data-source config remain server-local.
- [ ] Focused tests prove at least one mapped key per ownership group: provider, auth, storage.

## Out of Scope

- Runtime provider dispatch changes.
- Cloud docs and integration tests beyond focused config-load coverage.
- Per-tenant provider/auth variation.

## Avoided Traps

- Do not re-create the #11869 monolithic catalog. Every moved key needs a consumer proof.
- Do not move collection names or listener ports just because nearby storage keys move.

## Related

- Parent: #10103
- Discussion: #11961
- Sub-2: runtime provider routing + native Ollama wire-up
- Sub-3: cloud docs + readiness tests

Handoff Retrieval Hint: "Sub-1 #10103 Tier-1 config ownership ledger auth storage provider KB MC mapping"

## Timeline

- 2026-05-25T09:45:42Z @neo-gpt assigned to @neo-gpt
- 2026-05-25T09:45:42Z @neo-gpt added the `enhancement` label
- 2026-05-25T09:45:42Z @neo-gpt added the `ai` label
- 2026-05-25T09:45:42Z @neo-gpt added the `architecture` label
- 2026-05-25T09:46:10Z @neo-gpt added parent issue #10103
- 2026-05-25T09:47:51Z @neo-gpt cross-referenced by #10103
- 2026-05-25T09:59:13Z @neo-opus-ada cross-referenced by PR #11966
- 2026-05-25T10:00:19Z @neo-gpt cross-referenced by PR #11967
- 2026-05-25T10:45:51Z @neo-opus-ada cross-referenced by PR #11962
- 2026-05-25T11:19:31Z @tobiu referenced in commit `f877c18` - "feat(ai): map Agent OS config defaults to Tier-1 (#11963) (#11967)

Co-authored-by: tobiu <tobiasuhlig78@gmail.com>"
- 2026-05-25T11:19:31Z @tobiu closed this issue
- 2026-05-25T19:14:11Z @neo-opus-ada cross-referenced by PR #11988
- 2026-05-29T18:57:03Z @neo-opus-ada cross-referenced by PR #12179

