Configuration

This page is the single source of truth for the target configuration contract. It separates immutable startup/secrets from PostgreSQL-backed runtime policy. Names in this page are the v2 configuration contract.

Sources And Precedence

%%{init: {"flowchart": {"curve": "linear"}}}%%
flowchart LR
  Env["Environment / secret manager<br/>connections, credentials,<br/>listeners, hard caps"] --> Startup["Validated startup config"]
  Global["PostgreSQL app_config<br/>global runtime policy"] --> Effective["Effective runtime config"]
  Team["Allowed team overrides"] --> Effective
  Force["Explicit deployment<br/>force overrides"] --> Effective
  Startup --> Services["Adapters and hard boundaries"]
  Effective --> Services
  Portal["Control portal"] --> Global

Runtime-policy precedence:

explicit deployment force override
team override when that key permits it
global PostgreSQL app_config
built-in default

Credentials, encryption/signing material, listener addresses, hard safety caps, and provider secrets are environment/secret settings only. They are rejected from app_config.

Required Startup Settings

Production startup requires:

• PostgreSQL connection and migration/runtime credentials
• pgvector extension availability, one active embedding contract, and one compatible active search-index profile
• reviewer and verifier provider contracts
• embedding provider contract
• control-portal authentication secret or explicit private/disabled policy
• encryption/signing material required by enabled features

Neo4j settings are not part of normal target runtime. The temporary 2.1.x bridge may read explicitly prefixed legacy Neo4j settings only while the boot-gated migration is pending or running. It closes the connection after a successful cutover. Version 2.2.0 removes that adapter and refuses startup without the completed 2.1.x migration marker. The canonical lifecycle is in Release Process.

Listeners

Keep control and metrics private. Public routing belongs in Public HTTPS And Redis.

PostgreSQL And pgvector

PostgreSQL is authoritative for knowledge, workflow, search, and control state.

Production should separate migration and runtime roles. The runtime role needs only application DML, approved functions, and tenant-scoped/RLS access. The vector extension is installed by the global PostgreSQL migration and is not optional after the pgvector image cutover.

The connection budget is deployment-wide:

service instances * POSTGRES_MAX_OPEN_CONNS
+ separately pooled worker/migration connections
<= database connection limit - operator/failover reserve

Adding service replicas without recalculating this budget fails the production preflight.

Topology is detected from PostgreSQL at boot; it is not selected by an environment hint. This release requires a writable single primary and stops before migrations or normal service startup when pg_is_in_recovery() is true, transaction_read_only is enabled, or Citus is installed. POSTGRES_READ_DSN is rejected because replica reads are not supported yet. The composite tenant keys, scoped lookups, and placement classes in PostgreSQL Cluster-Safe Schema remain the required schema design for future HA or distributed support; they do not imply that those runtime topologies are enabled in this release.

PostgreSQL contains the records listed in Data Model And Storage. No configuration flag can move semantic authority to Redis, a model provider, or a legacy graph store.

Embedding Provider And Contract

Provider adapter, model, dimensions, normalization, and document format are one persisted embedding contract. Dense-Mem does not infer dimensions from a model name. Changing the contract requires a versioned vector rebuild and matched evaluation; mixed vectors fail readiness or remain excluded by version checks. The adapter sends a dimensions request only when the configured provider/model supports it, but every response must have exactly the configured length.

Embedding and cosine meaning is defined in Vector Search And Ranking. Index compatibility and rebuild impact is defined in ANN, HNSW, And Halfvec.

Search Index Construction

These desired startup values resolve to a persisted search-index profile. A different value from the active profile does not silently rebuild during normal startup; it enters the controlled index-build workflow.

auto resolves from the supported pgvector version, dimensions, distance, and canonical full-precision requirement. The dimension matrix, 3,072-dimensional halfvec expression index, exact rerank, and activation procedure belong only in ANN, HNSW, And Halfvec.

Reviewer And Verifier

The structure reviewer and Entity/Relationship verifier may share the embedding endpoint or use a separate OpenAI-compatible endpoint.

%%{init: {"flowchart": {"curve": "linear"}}}%%
flowchart TD
  URL{"AI_VERIFIER_API_URL set?"}
  URL -- No --> Shared["Use AI_API_URL and AI_API_KEY"]
  URL -- Yes --> Key{"AI_VERIFIER_API_KEY set?"}
  Key -- No --> Invalid["Fail startup"]
  Key -- Yes --> Separate["Use separate endpoint and key"]

There is no partial-response retry setting. Each correction regenerates the complete entity_results and relationship_results response. If an ingest cannot fit the declared one-request contract, intake or extraction fails with a size error; the application does not split semantic dependencies and splice model outputs.

The closed contract and validation rules belong in Memory Write Pipeline. The server may fingerprint that local contract for deployment and telemetry, but no schema-version field is sent to or accepted from the model.

Entity Resolution

Vector similarity retrieves candidates only. No threshold authorizes an automatic merge. See Entity Identity And Resolution.

Placement And Embedding Workers

Embedding workers batch before scaling worker count. Each batch claims ready jobs for one team with FOR UPDATE SKIP LOCKED, embeds the document texts with one provider batch call, and completes each job against its claimed attempt and document version. Provider output count, dimensions, and ordering are validated before any vector is written. Batch failure is retried by splitting the batch until the failing document is isolated or the error is classified as a whole-provider/configuration failure.

Worker count must fit database and provider capacity. AI_API_EMBEDDING_MAX_CONCURRENCY is the process-wide provider request cap; EMBEDDING_BATCH_SIZE controls request width. PostgreSQL owns queue, lease, attempt, and result state. Redis may reduce wake-up latency only.

PostgreSQL Search And Recall

These startup settings define the active semantic-v2 recall ranking profile for the process. They are internal telemetry and evaluation metadata; public recall responses do not expose them. Future control-portal management must activate the same complete profile shape atomically instead of mutating individual fields.

There is no candidate tier weight because candidates are ineligible for normal recall. Disabling RRF selects the complete branch-priority profile; it never mixes raw text/vector scores or chooses an implicit order. Relationship, Entity, and adjacency branches are discovery branches and do not contribute to initial evidence fusion. Ranking-profile changes require paired evaluation, including approximate Recall@K against exact filtered search. The algorithm is defined in Vector Search And Ranking.

Predicate Registry

Registry data lives in PostgreSQL. It supplies relationship_kind, current_cardinality, aliases, and endpoint-kind rules. policy_family and graph relationship-type mappings are not target settings.

Redis Coordination

Set DISTRIBUTED_COORDINATION_REQUIRED=true for multiple service instances. When required/configured Redis is unavailable, the server must not silently fall back.

Redis may hold rate-limit counters, provider cooldown coordination, short leases/signals, cleanup wakeups, and SSE concurrency. It cannot own evidence, Entities, Relationships, reviews, queues, API keys, or audit.

Authentication, Limits, And SSO

Detailed public-edge policy is in Public HTTPS And Redis; SSO mapping is in User Portal SSO.

Telemetry And Logging

Debug output still redacts secrets, evidence, vectors, and provider payloads. Metric definitions belong in Telemetry.

Feature-Gated Runtime Policy

These keys are PostgreSQL-backed unless identified as hard environment caps.

Recall feedback and evaluation

Never enable evaluation mode for production teams.

Dreaming

Eligibility and no-new-node behavior belong in Dreaming.

Community detection

The service reads eligible IDs from PostgreSQL into a bounded analytical job; no Neo4j/GDS dependency is implied. See Community And Dreaming.

Scheduling

Startup Validation

%%{init: {"flowchart": {"curve": "linear"}}}%%
flowchart TD
  Load["Load environment and secrets"] --> Static{"Static contract valid?"}
  Static -- No --> Fail["Fail before listeners"]
  Static -- Yes --> PG["Connect PostgreSQL and migrate"]
  PG --> Vector{"pgvector and schema valid?"}
  Vector -- No --> Fail
  Vector -- Yes --> Runtime["Load and validate app_config"]
  Runtime --> Embed["Verify embedding contract"]
  Embed --> Index["Verify active search-index profile"]
  Index --> Models["Verify required model contracts"]
  Models --> Migration{"Compatible migration marker<br/>or 2.1.x bridge available?"}
  Migration -- No --> Fail
  Migration -- Yes --> Distributed{"Distributed coordination required?"}
  Distributed -- Yes --> Redis{"Redis healthy?"}
  Redis -- No --> Fail
  Redis -- Yes --> Gate["Enter migration maintenance<br/>or start normal workers"]
  Distributed -- No --> Gate
  Gate --> Ready["Start normal workers only<br/>after migration gates pass"]

Configuration errors fail visibly. Startup does not substitute another store, embedding model, verifier schema, or coordination mode. During a pending 2.1.x migration, only health/control surfaces start; service logs and the control portal expose durable progress. Version 2.2.0+ has no bridge and fails when the marker is absent.

Secret Rules

• use secret files or a secret manager
• never commit database, provider, control, telemetry, or Redis credentials
• never expose control/metrics listeners publicly
• rotate keys with overlapping validity, then revoke the old key
• sanitize docker compose config and support bundles before sharing
• reject secrets from PostgreSQL app_config

Risks And Mitigations

First-Run Checklist

• set non-template PostgreSQL, provider, Redis-if-needed, control, and telemetry secrets
• keep main/control ports on loopback until HTTPS policy is ready
• install/verify pgvector and run migrations
• verify one embedding has the configured dimensions and contract version
• verify the active search-index profile, query plan, and exact-versus-ANN gate
• verify the cluster-safe schema/key contract and two-team composite-FK/RLS probes
• verify reviewer extraction and the closed verifier schema
• create a manager key and least-privilege client key
• confirm Redis requirement matches one- or multi-instance topology
• run remember → placement → recall → trace, including a pending-vector case
• test PostgreSQL backup/PITR and vector rebuild before important use