Cloud-Native KB Ingestion — Configuration

Status — Phase 3B. This guide documents the configuration surface a cloud deployment uses to control Knowledge Base ingestion — the deployment-wide aiConfig keys (Phase 0/1) and the per-tenant KnowledgeBaseTenantConfig graph-node storage (Phase 2E, #11637).

Two configuration layers

Cloud KB ingestion is configured at two layers:

aiConfig carries the deployment's defaults — the single-tenant case is fully described by it. KnowledgeBaseTenantConfig is the multi-tenant layer: each tenant's source/parser config stored durably, per-tenant, versioned.

The deployment config — aiConfig

A deployment's config.mjs is gitignored and copied from config.template.mjs. A zero-config deployment edits nothing — every key carries a default matching the pre-substrate single-repo behaviour. The cloud-ingestion-relevant keys:

Source / parser registry

Tenant identity + write-side policy

Transport + auth (cloud / SSE)

Compose healthchecks use ai/scripts/diagnostics/mcpHealthcheck.mjs against the same /mcp route as external callers. When a deployment sets NEO_AUTH_MODE=gitlab-pat, also set NEO_MCP_HEALTHCHECK_TOKEN (or NEO_MCP_HEALTHCHECK_TOKEN_ENV) to a GitLab bearer with read_user; otherwise the server can answer correctly while Compose keeps it unhealthy.

Each key is also bindable via an environment variable (NEO_KB_DEFAULT_TENANT_ID, NEO_TRANSPORT, MCP_HTTP_PORT, …) — see config.template.mjs's envBindings map for the full set.

Tenant push-client environment

npm run ai:kb-push-client runs in the tenant workspace or CI job, not inside the KB server process. It therefore has its own small environment surface:

The token is a KB MCP authorization credential, not a Git credential. Store it in the tenant hook/CI secret store and rotate it using the deployment's normal OIDC, GitLab OAuth, or PAT-rotation policy.

Per-tenant config storage — KnowledgeBaseTenantConfig (#11637)

A multi-tenant deployment cannot express every tenant's source/parser config as static aiConfig keys — each tenant needs its own, mutable at runtime, durable across restarts. Phase 2E (#11637) stores it as a graph node.

The node. One KnowledgeBaseTenantConfig node per tenant, id kb-config:<tenantId>, in the Native Edge Graph. Its properties carry the tenant's config payload — {useDefaultSources, rawRepoSource, useDefaultParsers, customSources, customParsers, sourcePaths, tenantRepos, version, userId}. version increments on every mutation; userId is the #10011 RLS ownership stamp — a tenant cannot read or mutate another tenant's config node.

Resolution. KnowledgeBaseIngestionService.getTenantConfig({tenantId}) resolves a tenant's effective config through three tiers, first hit wins:

1. The kb-config:<tenantId> graph node — the canonical, runtime-mutable state.
2. kb-config.yaml — a deployment-root bootstrap file (below).
3. The deployment's default registry (aiConfig) — always resolves.

Mutation. KnowledgeBaseIngestionService.setTenantConfig({tenantId, config}) upserts the node, incrementing version. It is RLS-gated: a cross-tenant write is rejected with KB_INGEST_TENANT_MISMATCH.

Bootstrap — kb-config.yaml. A deployment seeds initial per-tenant config with a kb-config.yaml at <neoRootDir>/kb-config.yaml:

tenants:
  client-org:
    useDefaultSources: false
    rawRepoSource: true
    customParsers: [...]
    sourcePaths: {...}
    tenantRepos:
      - cloneUrl: https://github.com/neomjs/create-app.git  # clean URL; no userinfo@
        credentialRef: env:GIT_TOKEN                          # reference-only pointer; token lives outside the repo
        branchRef: dev                                        # optional; defaults to 'HEAD' = remote default branch

The tenantRepos: block is the bootstrap tier for the pull-mode polling config — listConfiguredTenantRepos() resolves it under the graph node → kb-config.yaml → aiConfig tiering. Graph-only tenant config nodes are included through the graph service's RLS-aware tenant-config enumeration surface; an unreadable graph tier degrades deployment diagnostics instead of silently behaving like an empty pull-mode config.

The YAML is bootstrap-only — the graph node is canonical once written. A malformed or absent file is fail-soft (logged, treated as absent → tier 3).

Config versioning. Every ingested chunk is stamped with the tenantConfigVersion active at ingest time (server-stamped chunk metadata). A tier-3 (default-registry) resolution stamps tenantConfigVersion: 0. The stamp lets a future config change drive retroactive invalidation of chunks ingested under a now-stale config.

Zero-config inheritance

The default-resolved tier means a single-repo deployment needs no tenant config at all: getTenantConfig falls through to tier 3 (aiConfig), which carries Neo's defaults. Divergence is opt-in and granular — a tenant overrides only the keys its topology requires. See Migration Path for the full zero-config upgrade story.

Model-provider runtime + orchestrator-readiness

Beyond KB ingestion, a cloud deployment chooses where model calls run. External provider endpoints remain the default operational posture; the optional local-model compose profile is a self-hosted OpenAI-compatible provider that operators opt into explicitly.

Provider selection

The request behaviour and orchestrator-readiness probe below carry resident-friendly defaults — when a local provider profile is selected, Neo keeps the configured chat and embedding roles warm across REM/Sandman cycles and probes patiently on cold start.

Provider request keep_alive

Native server var vs Neo per-request override. A self-hosted Ollama server also reads a native OLLAMA_KEEP_ALIVE env var that controls the server's default cache retention for requests arriving without a per-request keep_alive. These are distinct surfaces, and the interaction matters:

• Native OLLAMA_KEEP_ALIVE is the server default for requests that omit keep_alive.
• Neo's NEO_OLLAMA_KEEP_ALIVE (default -1) is sent on every Neo-issued request and overrides the server default for that request.
• So with Neo's -1 default, the model stays resident regardless of the native OLLAMA_KEEP_ALIVE value.
• An operator who shortens native OLLAMA_KEEP_ALIVE to reclaim host memory must also set NEO_OLLAMA_KEEP_ALIVE to a matching shorter window — otherwise Neo's per-request -1 keeps the model pinned and the native shortening has no effect on Neo traffic.

Orchestrator provider-readiness probe

Before the orchestrator runs a model-dependent task (e.g. the REM/Sandman dream cycle), it probes the configured provider until the provider answers or the retry budget is exhausted. Tuning is useful on cold-start-slow or capacity-constrained hosts.

These three are orchestrator-config-scoped (ai/config.template.mjs orchestrator.providerReadiness) and are not read by the MCP server processes, so — unlike the two keep_alive vars above — they are scoped to the orchestrator, not the MCP server env surface.

For llama.cpp deployments, keep the provider selector as openAiCompatible and follow the dedicated llama.cpp profile. It documents the extra operator proof required before handoff: /v1/models must expose both the configured chat and embedding model ids, both role routes must pass, and the deployment must not depend on switching hosts or rebuilding model context between role calls.

Related

• Overview — the contract split + default-source inheritance.
• llama.cpp Profile — OpenAI-compatible llama.cpp provider profile and dual-residency smoke.
• Custom Sources / Custom Parsers — authoring the classes customSources / customParsers register.
• Hook Wiring — mcpSyncMaxChunks and the ingestion facades.
• Security — spoofRejectionMode and the fail-closed posture.
• Migration Path — zero-config upgrade for existing deployments.
• #11637 Phase 2E tenant config storage · #11658 Phase 0/1B registry · #10572 work-volume gate.