Skip to main content

Configuration

All configuration is environment-driven. The server is built and tested against SurrealDB 4.0.0 (SDK pin =4.0.0, server image v4.0.0).

Database​

VariableDefaultNotes
SURREAL_MODEembeddedembedded or server
SURREAL_PATH./data/memory.dbEmbedded SurrealKV directory. With AUTH_MODE=jwt, each tenant gets <path>/tenants/<tenant>
SURREAL_ENDPOINT—e.g. ws://127.0.0.1:28000
SURREAL_USERNAME / SURREAL_PASSWORD—Server mode credentials
SURREAL_AUTH_LEVELrootroot, namespace or database
SURREAL_NAMESPACE / SURREAL_DATABASEmemory / mcpTarget namespace/database
SURREAL_EMBEDDED_MAX_INFLIGHT16Embedded-mode concurrency bound; sized on RocksDB, not re-measured on SurrealKV
SURREAL_QUERY_TIMEOUT_MS10000Per-query ceiling (also the operation-ledger deadline)
SURREAL_OPERATION_DEADLINE_MS30000Ceiling for one retried storage operation

Retry​

VariableDefault
SURREAL_MAX_CONNECT_RETRIES10
SURREAL_MAX_OPERATION_RETRIES3
SURREAL_BASE_RETRY_DELAY_MS100
SURREAL_MAX_RETRY_DELAY_MS5000
SURREAL_RETRY_JITTER_FACTOR0.25

Embeddings​

VariableDefaultNotes
EMBEDDING_PROVIDERlocallocal, openai, cohere, fast
LOCAL_EMBEDDING_MODELBAAI/bge-small-en-v1.5384 dimensions
MODEL_CACHE_DIRplatform cacheHF home; hub is appended
MODEL_DOWNLOAD_TIMEOUT_SECS600hf-hub ships no timeout of its own
EMBEDDING_WARMUPtrueSet false for purely lazy loading
LOCAL_EMBEDDING_BACKENDcandlecandle or mlx (Apple Silicon only)
LOCAL_EMBEDDING_EXECUTOR—Path to the MLX executor binary
LOCAL_EMBEDDING_MODEL_REVISIONpinned commitHugging Face revision of the model
LOCAL_EMBEDDING_DIMENSIONS384Must match the model
LOCAL_EMBEDDING_DEVICEautoauto or cpu (candle)
SURREAL_MEMORY_QUERY_EMBED_CACHE512Entries in the query-embedding cache (0 disables caching)
OPENAI_API_KEY / OPENAI_EMBEDDING_MODEL—OpenAI provider
COHERE_API_KEY / COHERE_EMBEDDING_MODEL—Cohere provider

Memory expiry​

See also the Memory expiry guide.

A memory with valid_until set is expired once valid_until is strictly before the operation's cutoff; a valid_until equal to the cutoff is still live. The cutoff is read once per operation.

Expired memories are excluded from every normal read as soon as they expire, whether or not cleanup has run: get by id, list, vector and hybrid search (both legs, before the result limit is applied), task-stream context, compression and v1 near-duplicate checks. Updating an expired memory is refused; it is never renewed or merged into.

The TTL worker only deletes them. Each deletion writes a deleted history row and removes the primary record. The pass reports what it actually removed: a deletion that fails is logged as an error, the memory stays (still hidden) and is retried on the next pass. History and the physical record stay available to audit and cleanup code through get_memory_including_expired and get_memory_history.

Expiry is a visibility guarantee, not erasure: history rows are kept by design.

Compression (summarizer)​

See also the Compression guide.

auto_summarize_task_stream and compress_memories run an evidence-backed pipeline: a summarizer proposes claims that quote their source text, a deterministic gate checks every quote and the token budget, and the summary is published atomically. The sources are archived, not deleted, and stay readable by id as evidence. If nothing can be kept safely, the call returns no summary and changes nothing.

By default the summarizer is extractive: it selects sentences, makes no network calls, and labels its output extractive. A model provider is opt-in: memory text leaves the process, so it needs explicit consent.

VariableDefaultMeaning
SUMMARIZER_PROVIDERextractiveextractive or openai_compatible
SUMMARIZER_EGRESS_ALLOWEDunsetMust be true for any network provider; startup fails otherwise
SUMMARIZER_BASE_URLnoneOpenAI-compatible base URL (for example a local gateway)
SUMMARIZER_MODELnoneModel name sent to the provider
SUMMARIZER_API_KEYnoneOptional bearer token
SUMMARIZER_TIMEOUT_MS20000Per-call time limit
SUMMARIZER_MAX_INPUT_TOKENS32000Larger inputs are deferred
SUMMARIZER_MAX_OUTPUT_TOKENS1500Rendered summary budget
SUMMARIZER_MIN_REDUCTION0.2Required shrink (0.2 = at most 80% of the input)
SUMMARIZER_MAX_RETRIES1Retries on 429/5xx/timeouts
SUMMARIZER_MAX_TOTAL_TOKENS2000000Provider spend cap for the process; further calls fail closed

A summary never has a wider owner than its sources: sources with different user_id, agent_id, session_id or scope are not merged. Source text is sent as untrusted data, and neither source text nor provider responses are logged.

Executor​

VariableDefaultCovers
SURREAL_EXECUTOR_STARTUP_MS300000spawn → readiness
SURREAL_EXECUTOR_WATCHDOG_MS30000per-request progress

Authentication and tenancy​

The Authentication and tenancy guide has the token format, examples and the deployment profile.

AUTH_MODE=local (the default) serves an unauthenticated API for the trusted local client and is refused at startup unless API_HOST is a loopback address. AUTH_MODE=jwt is the shared-deployment mode: every route except /health and /ready requires a Gate-issued bearer token, and startup fails if any setting below is missing.

VariableDefaultNotes
AUTH_MODElocallocal or jwt
AUTH_JWT_ISSUER–required; must match the token iss
AUTH_JWT_AUDIENCE–required; must match the token aud
AUTH_JWT_ALGORITHM–required; HS256, RS256, ES256 or EdDSA
AUTH_JWT_KEY / AUTH_JWT_KEY_FILE–one is required; an HS256 secret (at least 32 bytes) or a public-key PEM
AUTH_JWT_MAX_AGE_SECS300a token older than this is refused, so a revoked grant stops working within this window

Token claims: iss, aud, sub, tenant ([a-z0-9_]{1,48}), iat, exp, optional ops ("operator" allows retry, reject and re-key of durable operations) and optional user_id (restricts the credential to one user's memories, and to the /api/v1/memory and /api/v1/search routes only).

Isolation model: one database per tenant. The tenant comes only from the verified token. In server mode it maps to the namespace <SURREAL_NAMESPACE>_<tenant> (the SurrealDB user needs rights to create namespaces); in embedded mode to the directory <SURREAL_PATH>/tenants/<tenant>. Operation IDs, receipts, events, stats and replay live in that tenant's database, so the same client operation ID in two tenants is two independent operations. MCP sessions (streamable HTTP and legacy SSE) are bound to the (tenant, sub) that opened them. The local stdio MCP transport remains the trusted local client.

Server​

VariableDefaultNotes
API_HOST127.0.0.1Bind address. Anything other than loopback requires AUTH_MODE=jwt
API_PORT3001
MCP_STDIOtrueSet false for HTTP-only daemons
RUST_LOGinfo
TTL_INTERVAL_SECS3600TTL cleanup interval; a positive integer, otherwise the default is used with a warning

Client commands​

The hook and statusline subcommands read one variable. See CLI and hooks.

VariableDefaultNotes
SURREAL_MEMORY_URLhttp://localhost:23001Server the hook client talks to