Skip to main content
This page is the Python shape. The JavaScript SDK takes the same settings as plain options on the constructor rather than an SDKConfig object, so the TypeScript tabs differ in shape, not just in syntax. Four differences worth knowing before you read them:
  • Four Python-only settings do nothing here: storage_path, cache_backend, session_timeout_minutes and log_level. configure() accepts and ignores them. The constructor does not list them, so TypeScript flags them in an object literal.
  • The stream endpoint moves. It is set on instance.listen({ host, port, use_tls }), or with SYNAP_GRPC_HOST, SYNAP_GRPC_PORT and SYNAP_GRPC_USE_TLS, not on the client.
  • The retry policy and the read timeout work, with the same defaults as Python: read 30s, 3 attempts, backoff base 1s capped at 10s. connect and write are accepted but have no effect in JavaScript.
  • logger. Pass (level, message) => void and the client’s warnings go there instead of the console. Messages from the real-time stream and the event backup file still print to the console.
Full surface: JavaScript: client options below.

Overview

The Synap SDK is configured via the SDKConfig object, which controls storage, caching, timeouts, retries, logging and endpoints. Sensible defaults are provided for all fields, so you only need to override what matters for your environment.

SDKConfig Reference

Field Reference

At a glance, SDKConfig accepts:
  • storage_path: directory for the local SQLite cache and transient state. Defaults to an SDK-managed directory. The API key is never written here; it is read from SYNAP_API_KEY (or the api_key= constructor argument) on each start. See Storage Path.
  • cache_backend: "sqlite" (default) for on-disk caching, or None to disable it. See Cache Backend.
  • session_timeout_minutes: accepted for compatibility; it has no effect today. Default 30, valid range 5 to 1440. See Session Timeout.
  • timeouts: a TimeoutConfig for per-operation network timeouts.
  • retry_policy: a RetryPolicy for transient-error retries, or None to disable retries.
  • log_level: logging verbosity, one of "DEBUG", "INFO", "WARNING" (default), "ERROR", "CRITICAL". configure() rejects other values with InvalidInputError. See Log Level.
  • grpc_host / grpc_port / grpc_use_tls: endpoint overrides for the real-time anticipation stream. Only needed for self-hosted or local deployments. See gRPC Connection.
  • agent_model / agent_context_window: the model your agent runs on, and its context window if Synap does not know the model. Sent with every recorded turn so Synap sizes compaction to your model: it compacts when the last compaction plus the new text reaches about 11.7% of the window (15K tokens on a 128K model), or after about 30 new messages (once they add up to about 2,000 tokens), whichever comes first. Without them Synap assumes a 128K window. The per-call model and context_window on record_message and send_message override them. Python 0.5.11 and later, JavaScript and TypeScript 0.5.9 and later.
  • history_search_model: the local model for searching earlier turns after a compaction, and for matching a fetch to context the SDK already holds, by meaning. "auto" (default) uses the SDK’s multilingual model when it is installed; None keeps keyword matching only. SYNAP_SDK_LOCAL_MODEL=off also turns it off. Python 0.5.11 and later, JavaScript and TypeScript 0.5.9 and later.

Full parameter reference →

The complete field list, types, accepted ranges, and the configure() rules (including the logger override).

TimeoutConfig

Controls how long the SDK waits for individual network operations.
float
default:"5.0"
Maximum time in seconds to establish a TCP connection to Synap Cloud. Increase this if your network has high latency or unreliable DNS resolution. JavaScript ignores this value.
float
default:"30.0"
Maximum time in seconds. Python: the longest wait for response data. JavaScript: the longest time to wait for the response to start, counted from when the request is sent. This should be higher than your expected query latency. For compaction of very large conversations, you may need to increase this.
float
default:"10.0"
Maximum time in seconds to upload request data. Relevant for large batch ingestion payloads. Increase if you are sending very large documents. JavaScript ignores this value.
float
default:"60.0"
Accepted for compatibility; it has no effect today.

gRPC Connection

Cloud only Synap Core is REST only and has no real-time stream. These three fields point the real-time anticipation stream (instance.listen()) at a specific endpoint. Leave them unset for Synap Cloud; the defaults are correct and TLS is on.
string | None
default:"None"
Hostname for the real-time stream. None uses the Synap Cloud endpoint. Set this when running against a self-hosted or local Synap deployment.
int | None
default:"None"
Port for the real-time stream, commonly 50051 for local deployments. None uses the Synap Cloud default.
bool | None
default:"None"
None uses the transport default (TLS on). If you leave a field None, the matching SYNAP_GRPC_* variable is used. Set to False only for a plaintext endpoint, such as a local container. Never disable TLS against a remote host.
These fields affect only the streaming transport. REST calls use the separate api_base_url. Point both at the same deployment or the SDK will authenticate against one environment and stream against another.

Caching and async ingestion

Ingestion is asynchronous: memories from a turn are not immediately retrievable. The local read cache keeps a non-empty result for its TTL (5 minutes by default), and a write does not clear it, so a fetch right after a write can return the older result. For live agents that ingest and retrieve in the same loop, turn the local read cache off:
The anticipation cache is unaffected and keeps working.

RetryPolicy

Controls automatic retry behavior for transient errors.
int
default:"3"
The total number of attempts including the initial request. Setting this to 1 means no retries (only the initial attempt). Setting to 5 means up to 4 retries after the initial failure.
float
default:"1.0"
The base delay in seconds for exponential backoff. The wait after the first failure is backoff_base, then it doubles each time, up to backoff_max. A higher base means longer waits between retries, which is gentler on rate-limited endpoints.
float
default:"10.0"
The maximum delay in seconds between retry attempts. Prevents exponential backoff from growing unbounded for high max_attempts values.
bool
default:"True"
When enabled, adds a random component to the backoff delay. This prevents the “thundering herd” problem where multiple SDK instances retry at the exact same time after a shared failure. Strongly recommended for production deployments.
List[str]
The list of error type names that should be automatically retried. Only errors in this list trigger the retry policy. All other errors are raised immediately.For RateLimitError, the SDK uses the server-provided retry_after_seconds value instead of the exponential backoff calculation. The server’s wait time is capped at backoff_max. A rate-limit error that says you are out of credits or at your trial limit is not retried. A write that timed out after it was sent is not retried, because it may have gone through; a context fetch that timed out is.

Storage Path

The storage_path directory holds the local SQLite cache and transient state. The SDK uses your default file permissions. Put storage_path in a folder only your service can read. The API key is never stored here; it comes from SYNAP_API_KEY or the api_key= constructor argument.

When to Override

Credentials

The SDK reads the API key on every start. There are exactly two sources: The SDK uses your API key for every call. The instance ID is resolved automatically from the API key; you do not need to set it manually.

Cache Backend

The SQLite cache stores recent retrieval results locally, enabling sub-millisecond cache hits for repeated queries. The cache respects TTL values from the server (ttl_seconds in response metadata) and evicts stale entries automatically. Benefits:
  • Sub-millisecond cache hits for repeated context fetches
  • Persists across SDK restarts (within TTL)
  • Automatic size management and TTL-based eviction
  • Zero configuration (SQLite is bundled with Python)

Disabled

Turns off the local read cache. A fetch goes to Synap Cloud unless the real-time stream has already delivered the answer. Use this when:
  • You do not want a fetch to return an older cached result
  • You are running in a read-only filesystem (and cannot use a RAM-backed path)
  • You are debugging cache-related issues

Session Timeout

session_timeout_minutes is accepted and validated (5 to 1440) but has no effect today. The SDK authenticates every request with your API key.

Log Level

The SDK uses Python’s standard logging module. The log level sets the synap.sdk logger. Python prints its warnings and errors to stderr without any setup; to see its INFO and DEBUG lines, your app needs a log handler, for example logging.basicConfig().
log_level is accepted and ignored in JavaScript, so a shared config object still works. Filter by the level argument in your own sink instead: it is one of debug, info, warn, error.
The DEBUG level logs cache keys, which contain user and customer ids. Do not use it where logs are shared.

Using configure()

The configure() method allows you to update individual configuration fields after constructing the SDK but before calling initialize().
Calling configure() after initialize() raises InvalidInputError('Cannot reconfigure after initialization').

Environment Variables

These settings can come from the environment; others are set in code.
Explicit configuration wins, with these exceptions: SYNAP_SDK_ST_AUTHORITATIVE and SYNAP_ST_VERBATIM_OVERLAY override the value set in code, and SYNAP_SDK_LOCAL_MODEL=off turns the local search model off whatever the code says.

Common Configurations

Verbose logging, short timeouts and quick-failing retries for fast feedback during development.
Conservative timeouts, standard retries with jitter, minimal logging, and persistent storage.
Isolated storage, disabled caching for deterministic tests, no retries for immediate failure feedback.
Optimized for batch ingestion workloads with generous timeouts and higher retry limits.

Full Configuration Example

A fuller example:

Next Steps

Initializing the SDK

Learn the full initialization lifecycle with configuration.

API Error Reference

Understand how retry policies interact with the error hierarchy.

Production Checklist

Review configuration best practices before going live.

Ingesting Memories

Start ingesting data with your configured SDK.

JavaScript: client options

Pass these to new SynapClient({ ... }):
string
Your Synap API key. Falls back to SYNAP_API_KEY when omitted.
string
API base URL. Falls back to SYNAP_BASE_URL, then the Synap Cloud default. Set it when you run a self-hosted deployment.
string
Optional. Resolved from the API key during initialize() when omitted. Falls back to SYNAP_INSTANCE_ID.
string
Optional. Resolved from the API key during initialize() when omitted. Falls back to SYNAP_CLIENT_ID.
object
{ connect, read, write } in seconds. Only read (default 30) has an effect.
object
{ maxAttempts, backoffBase, backoffMax, backoffJitter }. Defaults to 3 attempts with jittered exponential backoff.
object
{ keepAliveExpiryMs, maxConnections, heartbeatIntervalMs }. Connection reuse on Node: idle connections are kept for 5 minutes (keepAliveExpiryMs, in milliseconds) and up to 20 are open at once. heartbeatIntervalMs (default 4 minutes) sets the ping interval used when heartbeat is true.
boolean
default:"false"
Keep the connection warm with a periodic health ping. Worth it for a long-lived process, pointless in serverless where the container is frozen between requests.
function
Supply your own fetch. Useful for testing or for routing through a proxy.
function
(level, message) => void. Receives the client’s warnings. Defaults to console.warn with a [synap] prefix.
string
The model your agent runs on, for example 'gpt-4o'. Sent with every recorded turn so Synap sizes compaction to it. Also accepted as agentModel.
number
Your model’s context window in tokens. Only needed for a model Synap does not know. Also accepted as agentContextWindow.
string | null
default:"'auto'"
The local model for searching earlier turns after a compaction, and for matching a fetch to context the client already holds. 'auto' uses the SDK’s multilingual model when it is installed; null keeps keyword matching only. Also accepted as historySearchModel.
boolean
default:"false"
Render prompts locally: answer prompt and compacted-context requests from turns the client already holds, when it holds the whole conversation. SYNAP_SDK_ST_AUTHORITATIVE overrides it. Also accepted as sdkStAuthoritative.
boolean
default:"true"
Show a turn you just wrote in the next conversation fetch, before the server has processed it. SYNAP_ST_VERBATIM_OVERLAY overrides it. Also accepted as stVerbatimOverlay.