Configuration

Each SurrealDB Agent Memory Context has its own configuration: the models and provider keys it uses, its token budget, and its extraction, cache, retention, scope and key settings. This page lists the fields a Context has and their defaults.

On SurrealDB Cloud, admins and owners change a Context's configuration in SurrealDB Studio under Settings → configuration. Changes apply immediately to new requests.

Per-Context configuration

Each Context stores a config object. It is set when the Context is created and can be changed at any time afterwards.

Full config schema

{
  "token_limit": 1000000,
  "models": {
    "extraction": { "provider": "google", "model": "gemini-3.5-flash-lite" },
    "synthesis": { "provider": "anthropic", "model": "claude-opus-4-8" },
    "elaboration_consolidation": { "provider": "google", "model": "gemini-3.8-flash" },
    "embedding": "gemini-embedding-2"
  },
  "providers": {
    "google": "…",
    "openai": "sk-…",
    "anthropic": "sk-ant-…"
  }
}

Config fields

Each stage takes an object with a provider (openai, anthropic, google, cerebras or openrouter) and a model. The provider must have a key available to the Context. For OpenAI and Google, the model must be one the server knows for that provider, so an id such as gemini-2.5-pro is rejected with 400. Anthropic accepts any non-empty id, OpenRouter needs a vendor/model id, and Cerebras needs an id with no /.

A stage with no selection uses the deployment default model. With Google as the provider, that is gemini-3.5-flash-lite for extraction and reconciliation and gemini-3.8-flash for synthesis, elaboration and consolidation, and for /chat and /reflect. The Google models the server accepts are gemini-3.1-flash-lite, gemini-3.5-flash-lite, gemini-3.6-flash, gemini-3.8-flash and gemini-4-argon, as well as gemini-2.5-flash and gemini-2.5-flash-lite, which Google no longer offers to new API users. The embedding model is fixed to gemini-embedding-2 (3072 dimensions) for the whole deployment, so models.embedding accepts no other value.

Default provider API keys

The deployment provides default provider keys, so a Context can use a stage without storing a key of its own. A key set in providers.* applies to this Context only and takes precedence over the deployment default for that provider. Embeddings always use Gemini.

Reranker (optional)

Cross-encoder reranking for /documents/query with use_reranker=true depends on the deployment having a reranker provider. Without one, requests fall back to bi-encoder ordering.

Multimodal providers (optional)

OCR, visual embeddings (CLIP) and speech-to-text during document ingestion depend on the providers available to the deployment. They are not Context configuration fields. The ingestion_profile field decides which of these steps run for a Context. See Multimodal content.

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"]
  }
}

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, so changing the configuration does not change them.

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

Trace retention

Scope and label limits

A write that passes a scope or label limit returns 409. A change to scope_limits, label_limits or label_dimensions replaces the stored value as a whole.

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 in SurrealDB Studio, or with self-service POST /{ctx}/keys.

Request and list limits

These limits apply to the whole deployment:

Raising k only returns more of the fused answer. The candidate pool that retrieval searches is internal and does not grow with k. Section expansion is on by default.

Requests above the query ceiling return 400 Bad Request.

Reconciliation

Defaults reference

When a per-Context field is not set, the default applies. SurrealDB Studio shows a Context's configuration under Settings → configuration. A field the Context has not set shows its default value. The one exception is models: a stage with no selection is left out, and resolves to the deployment default when it is used.