Skip to main content

​
Overview

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

​
SDKConfig Reference

from synap import SDKConfig

config = SDKConfig(
    storage_path=None,                    # Default: SDK-managed local directory
    credentials_source="file",            # "file" or "env"
    cache_backend="sqlite",              # "sqlite" or None
    session_timeout_minutes=30,           # Range: 5-1440
    timeouts=TimeoutConfig(),             # Connection and read timeouts
    retry_policy=RetryPolicy(),           # Retry behavior for transient errors
    log_level="WARNING"                   # DEBUG, INFO, WARNING, ERROR
)

​
Field Reference

​
storage_path
str
default:"SDK-managed local directory"
The directory where the SDK stores credentials, cache databases, and local state. The SDK creates this directory (and parents) if it does not exist.Override this when:
  • Your application runs in a container with a specific writable volume
  • Multiple SDK instances on the same machine need isolated storage
  • You want to persist data in a location managed by your deployment tooling
​
credentials_source
str
default:"file"
Where the SDK reads authentication credentials from.
  • "file" — Read credentials from files in storage_path. After the initial bootstrap, credentials are persisted to disk and loaded on subsequent starts.
  • "env" — Read credentials from the SYNAP_API_KEY environment variable. Ideal for containers, serverless, and CI/CD.
​
cache_backend
str
default:"sqlite"
The local cache implementation used to store recent retrieval results.
  • "sqlite" (recommended) — Uses a SQLite database in storage_path for local caching. Provides fast sub-millisecond cache hits, persistence across restarts, and automatic TTL-based eviction.
  • None — Disables local caching entirely. Every retrieval call goes to Synap Cloud. Use this only when you need guaranteed fresh data on every call or are running in a read-only filesystem.
​
session_timeout_minutes
int
default:"30"
How long a session remains active before the SDK re-authenticates. Valid range: 5 to 1440 minutes (24 hours).Shorter timeouts improve security by limiting the window for credential misuse. Longer timeouts reduce re-authentication overhead for long-running processes.
​
timeouts
TimeoutConfig
default:"TimeoutConfig()"
Fine-grained timeout configuration for network operations. See TimeoutConfig below.
​
retry_policy
RetryPolicy
default:"RetryPolicy()"
Configuration for automatic retry of transient errors. Set to None to disable retries. See RetryPolicy below.
​
log_level
str
default:"WARNING"
The logging verbosity for the SDK’s internal logger. Uses Python’s standard logging levels:
  • "DEBUG" — Verbose logging including request/response details, cache hits/misses, retry attempts
  • "INFO" — Initialization events, connection status, credential rotation
  • "WARNING" — Deprecation notices, performance warnings, approaching rate limits
  • "ERROR" — Only errors that affect operation

​
TimeoutConfig

Controls how long the SDK waits for individual network operations. 
from synap import TimeoutConfig

timeouts = TimeoutConfig(
    connect=5.0,       # Seconds to establish TCP connection
    read=30.0,         # Seconds to wait for response data
    write=10.0,        # Seconds to wait for request upload
    stream_idle=60.0   # Seconds of inactivity before closing gRPC stream
)
​
connect
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.
​
read
float
default:"30.0"
Maximum time in seconds to wait for a complete response after sending a request. This should be higher than your expected query latency. For accurate mode retrieval (200-500ms typical), the default is generous. For compaction of very large conversations, you may need to increase this.
​
write
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.
​
stream_idle
float
default:"60.0"
Maximum idle time in seconds for gRPC streaming connections (used by sdk.instance.listen()). If no data is received within this window, the stream is considered stale and reconnected. Increase for low-traffic instances where events are infrequent.

​
RetryPolicy

Controls automatic retry behavior for transient errors. 
from synap import RetryPolicy

retry_policy = RetryPolicy(
    max_attempts=3,            # Total attempts (1 initial + 2 retries)
    backoff_base=1.0,          # Base delay in seconds
    backoff_max=10.0,          # Maximum delay cap
    backoff_jitter=True,       # Add randomized jitter
    retryable_errors=[         # Which error types to retry
        "NetworkTimeoutError",
        "RateLimitError",
        "ServiceUnavailableError"
    ]
)
​
max_attempts
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.
​
backoff_base
float
default:"1.0"
The base delay in seconds for exponential backoff. The delay for attempt N is backoff_base * 2^(N-2), capped at backoff_max. A higher base means longer waits between retries, which is gentler on rate-limited endpoints.
​
backoff_max
float
default:"10.0"
The maximum delay in seconds between retry attempts. Prevents exponential backoff from growing unbounded for high max_attempts values.
​
backoff_jitter
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.
​
retryable_errors
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.

​
Storage Path

The storage_path directory contains all SDK-managed local state: credentials, the SQLite cache database, and instance state. The SDK sets restrictive filesystem permissions on this directory automatically on creation.
The storage directory contains sensitive credential material. In containerized environments, mount this path to a persistent volume so credentials survive container restarts.

​
When to Override

ScenarioRecommended storage_path
Standard deploymentNone (use SDK default)
Docker container/var/lib/synap/ mapped to a persistent volume
Serverless functionUse credentials_source="env" instead
Multiple instances on same host/var/lib/synap/<instance_id>/
Testing/tmp/synap-test/

​
Credentials Source

​
File-Based (Default)

config = SDKConfig(credentials_source="file")
After the first successful initialization, credentials are persisted to storage_path/credentials/. On subsequent SDK starts, they are loaded automatically without needing SYNAP_API_KEY again. This is the recommended approach for persistent environments (VMs, containers with volumes, on-premise servers).

​
Environment-Based

config = SDKConfig(credentials_source="env")
The SDK reads credentials from environment variables:
VariableDescriptionRequired
SYNAP_INSTANCE_IDInstance identifierYes (or pass to constructor)
SYNAP_API_KEYAPI key for authenticationYes (or pass to constructor)
This approach is recommended for ephemeral environments (serverless, CI/CD, Kubernetes pods without persistent volumes) where writing to disk is impractical.

​
Cache Backend

config = SDKConfig(cache_backend="sqlite")
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

config = SDKConfig(cache_backend=None)
Disables local caching entirely. Every conversation.context.fetch() call goes to Synap Cloud. Use this when:
  • You need guaranteed freshness on every call
  • You are running in a read-only filesystem (and cannot use a RAM-backed path)
  • You are debugging cache-related issues

​
Session Timeout

config = SDKConfig(session_timeout_minutes=60)
The session timeout controls how long the SDK’s authenticated session remains valid before re-authentication is required. The valid range is 5 to 1440 minutes (24 hours).
SettingValueUse Case
Short session5-15 minHigh-security environments, compliance requirements
Default30 minGeneral-purpose applications
Long session60-120 minLong-running batch processes
Maximum1440 min (24h)Background workers, data pipelines

​
Log Level

The SDK uses Python’s standard logging module. The log level controls verbosity of the synap logger. 
config = SDKConfig(log_level="DEBUG")
LevelWhat is Logged
DEBUGAll internal operations: request/response bodies, cache lookups, retry decisions, credential rotation timing
INFOInitialization, connection events, credential rotation, compaction triggers
WARNINGDeprecation notices, approaching rate limits, cache size warnings
ERRORFailed operations that could not be retried, authentication failures, data corruption
The DEBUG level may log sensitive information including request payloads. Do not use DEBUG in production environments where logs may be exposed to unauthorized parties.

​
Using configure()

The configure() method allows you to update individual configuration fields after constructing the SDK but before calling initialize(). 
sdk = MaximemSynapSDK(
    instance_id="inst_a1b2c3d4e5f67890",
    api_key="synap_your_key_here"
)

# Override specific fields without constructing a full SDKConfig
sdk.configure(log_level="DEBUG")
sdk.configure(session_timeout_minutes=120)
sdk.configure(cache_backend=None)

await sdk.initialize()
Calling configure() after initialize() has no effect. All configuration must be finalized before initialization.

​
Environment Variable Overrides

In addition to the credentials_source="env" mode for credential management, several SDK settings can be overridden via environment variables. Environment variables take precedence over values in SDKConfig.
Environment VariableOverridesExample
SYNAP_STORAGE_PATHstorage_path/var/lib/synap
SYNAP_CACHE_BACKENDcache_backendsqlite or empty to disable
SYNAP_LOG_LEVELlog_levelDEBUG
SYNAP_SESSION_TIMEOUTsession_timeout_minutes60
SYNAP_CONNECT_TIMEOUTtimeouts.connect10.0
SYNAP_READ_TIMEOUTtimeouts.read45.0
This enables runtime configuration without code changes, useful for different deployment stages.

​
Common Configurations

Verbose logging, short timeouts, and aggressive retries for fast feedback during development.
from synap import SDKConfig, TimeoutConfig, RetryPolicy

dev_config = SDKConfig(
    storage_path="/tmp/synap-dev",  # Temporary path for dev
    credentials_source="file",
    cache_backend="sqlite",
    session_timeout_minutes=120,
    timeouts=TimeoutConfig(
        connect=3.0,
        read=15.0,
        write=5.0,
        stream_idle=30.0
    ),
    retry_policy=RetryPolicy(
        max_attempts=2,
        backoff_base=0.5,
        backoff_max=3.0
    ),
    log_level="DEBUG"
)
Conservative timeouts, standard retries with jitter, minimal logging, and persistent storage.
from synap import SDKConfig, TimeoutConfig, RetryPolicy

prod_config = SDKConfig(
    storage_path="/var/lib/synap",
    credentials_source="file",
    cache_backend="sqlite",
    session_timeout_minutes=30,
    timeouts=TimeoutConfig(
        connect=10.0,
        read=30.0,
        write=10.0,
        stream_idle=120.0
    ),
    retry_policy=RetryPolicy(
        max_attempts=3,
        backoff_base=1.0,
        backoff_max=10.0,
        backoff_jitter=True
    ),
    log_level="WARNING"
)
Isolated storage, disabled caching for deterministic tests, no retries for immediate failure feedback.
from synap import SDKConfig, TimeoutConfig

test_config = SDKConfig(
    storage_path="/tmp/synap-test",
    credentials_source="file",
    cache_backend=None,          # No caching for deterministic tests
    session_timeout_minutes=5,
    timeouts=TimeoutConfig(
        connect=2.0,
        read=5.0,
        write=3.0,
        stream_idle=10.0
    ),
    retry_policy=None,           # No retries -- fail fast in tests
    log_level="DEBUG"
)

# Use _force_new to bypass singleton caching in tests
sdk = MaximemSynapSDK(
    instance_id="inst_test_1234567890ab",
    api_key="synap_test_key",
    config=test_config,
    _force_new=True
)
Optimized for batch ingestion workloads with generous timeouts, higher retry limits, and long sessions.
from synap import SDKConfig, TimeoutConfig, RetryPolicy

throughput_config = SDKConfig(
    storage_path="/var/lib/synap",
    credentials_source="file",
    cache_backend="sqlite",
    session_timeout_minutes=1440,  # 24 hours for long batch jobs
    timeouts=TimeoutConfig(
        connect=15.0,
        read=60.0,               # Long reads for large batch responses
        write=30.0,              # Long writes for large batch payloads
        stream_idle=300.0        # 5 min idle for streaming
    ),
    retry_policy=RetryPolicy(
        max_attempts=5,
        backoff_base=2.0,
        backoff_max=30.0,
        backoff_jitter=True
    ),
    log_level="INFO"
)

​
Full Configuration Example

Putting it all together with explicit values for every field: 
from synap import MaximemSynapSDK, SDKConfig, TimeoutConfig, RetryPolicy

sdk = MaximemSynapSDK(
    instance_id="inst_a1b2c3d4e5f67890",
    api_key="synap_your_key_here",
    config=SDKConfig(
        storage_path="/var/lib/myapp/synap",
        credentials_source="file",
        cache_backend="sqlite",
        session_timeout_minutes=60,
        timeouts=TimeoutConfig(
            connect=10.0,
            read=30.0,
            write=10.0,
            stream_idle=120.0
        ),
        retry_policy=RetryPolicy(
            max_attempts=3,
            backoff_base=1.0,
            backoff_max=10.0,
            backoff_jitter=True,
            retryable_errors=[
                "NetworkTimeoutError",
                "RateLimitError",
                "ServiceUnavailableError"
            ]
        ),
        log_level="WARNING"
    )
)

await sdk.initialize()

​
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.