Configuration

SurrealDB Agent Memory has two configuration surfaces: server-wide settings (in the server binary or environment) and per-Context configuration (stored in the control plane and patchable at runtime).

Server-wide configuration

Server configuration is provided via environment variables or a TOML configuration file passed at startup. These settings apply to all Contexts unless overridden at the Context level.

Core settings

Default model settings

Per-stage defaults are cost-tiered for the deployment’s chosen LLM provider (SPECTRON_LLM_PROVIDER / implicit Google). Optional env overrides:

The embedding model is fixed per deployment - it is not a per-Context override. Context config rejects any models.embedding value other than the deployment default. Changing the server embedding model requires a reindex so vectors and HNSW indexes stay in the same embedding space.

Reranker (optional)

Cross-encoder reranking for /documents/query when use_reranker=true:

Multimodal providers (optional)

HTTP OCR, CLIP, and speech-to-text for document ingestion (read by the worker role). An HTTP provider takes precedence over the built-in local fallback for the same modality. Misconfigured URLs fail at boot.

See Multimodal content.

Default provider API keys

Object store configuration

CORS (browser clients)

Cross-origin browser calls to the API are off by default. Enable an origin allowlist when a web client (for example SurrealDB Studio against a Cloud-brokered access token) calls the user API from a different origin than the API host.

Comma-separated origins. Entries are trimmed, lower-cased, and normalised (trailing / stripped). Exact entries match the Origin header verbatim; entries containing * are anchored globs on both sides (bare * or https://* are rejected). Allowed origins are echoed in Access-Control-Allow-Origin; credentials are not used - callers authenticate with Authorization, not cookies. Preflight mirrors request headers so SDK headers (api-version, X-Spectron-Context, Idempotency-Key, and others) pass without a fixed allowlist.

The management API is normally server-side only; CORS is optional there for operator tooling.

Per-Context configuration

Each Context stores a config object in the control plane. This is updated via PATCH /api/v1/contexts/{id} and applies immediately to new requests.

Full config schema

{
  "config": {
    "token_limit": 1000000,
    "models": {
      "extraction": { "provider": "google", "model": "gemini-2.5-flash" },
      "synthesis": { "provider": "google", "model": "gemini-2.5-pro" },
      "elaboration_consolidation": { "provider": "google", "model": "gemini-2.5-flash" },
      "embedding": "gemini-embedding-2"
    },
    "providers": {
      "google": "…",
      "openai": "sk-…",
      "anthropic": "sk-ant-…"
    }
  }
}

Config fields

Provider API key visibility

Provider API keys are write-only on the API surface. The read projection for a Context replaces the key values with a providers_configured summary - names of providers for which this Context stores its own key:

{
  "config": {
    "providers_configured": ["google", "openai", "anthropic"]
  }
}

This is not the same as GET /api/v1/{context_id}/providers, which lists providers reachable via a global deployment key or a per-Context key and includes selectable model ids. The two surfaces are not derivable from each other.

The raw key values never appear in read responses.

Top-level Context fields (outside config)

These fields live on the Context record itself, not inside the config object. A PATCH that only updates config cannot change them.

Patching config

Send only the fields you want to change. Unset fields are left unchanged (deep merge):

PATCH /api/v1/contexts/acme-prod
Content-Type: application/json
Authorization: Bearer mgmt-...

{
  "config": {
    "token_limit": 2000000,
    "models": {
      "reflection": "anthropic/claude-opus-4-7"
    }
  }
}

Extraction tuning

Additional per-Context settings control extraction behaviour:

There is no setting that constrains which entity types, attribute keys, or relation labels extraction may produce. Entity types come from a fixed vocabulary; keys and labels converge through reuse. See Extraction vocabulary.

Cache settings

Key policy

Every data-plane API key must be bound to a principal. Keys with no principal binding are rejected with 401 - there is no unscoped passthrough mode. Mint keys under a principal (management API or self-service POST /{ctx}/keys).

Request and list limits

Operator-tunable ceilings (env vars, read at process start):

Requests above the query ceiling return 400 Bad Request.

Reconciliation

Defaults reference

When a per-Context field is not set, the server-wide default applies. The effective configuration for a Context is always visible at:

GET /api/v1/contexts/{id}

The response includes the config object with all effective values merged - Context-level overrides where set, server-wide defaults elsewhere.