SDK Configuration

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 maximem_synap import SDKConfig

config = SDKConfig(
    storage_path=None,                    # Default: SDK-managed local directory (cache only)
    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

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: how long a session stays active before re-authentication. 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". See Log Level.

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.

from maximem_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 reconnecting the event 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 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 the SDK’s real-time event stream (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 maximem_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",
        "SynapTransientError"
    ]
)

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 holds the local SQLite cache and transient state. The SDK sets restrictive filesystem permissions on this directory on creation. The API key is never stored here; it comes from SYNAP_API_KEY or the api_key= constructor argument.

When to Override

Scenario	Recommended `storage_path`
Standard deployment	`None` (use SDK default)
Docker container	`/var/lib/synap/` mapped to a persistent volume (optional, cache only)
Serverless function	Disable the cache (`cache_backend=None`)
Multiple instances on same host	`/var/lib/synap/<instance_id>/`
Testing	`/tmp/synap-test/`

Credentials

The SDK reads the API key on every start. There are exactly two sources:

Source	Description
`api_key="..."` constructor argument	Passed directly to `MaximemSynapSDK(...)`
`SYNAP_API_KEY` environment variable	Read automatically when the constructor argument is omitted

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

SQLite (Default, Recommended)

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

Setting	Value	Use Case
Short session	5-15 min	High-security environments, compliance requirements
Default	30 min	General-purpose applications
Long session	60-120 min	Long-running batch processes
Maximum	1440 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")

Level	What is Logged
`DEBUG`	All internal operations: request/response bodies, cache lookups, retry decisions, credential rotation timing
`INFO`	Initialization, connection events, credential rotation, compaction triggers
`WARNING`	Deprecation notices, approaching rate limits, cache size warnings
`ERROR`	Failed 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(
    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() raises InvalidInputError('Cannot reconfigure after initialization').

Environment Variables

Only SYNAP_API_KEY is read from the environment. All other SDK settings must be set in code via SDKConfig; pass it to the constructor (or configure()) before initialize().

import os
from maximem_synap import MaximemSynapSDK, SDKConfig

sdk = MaximemSynapSDK(
    api_key=os.environ["SYNAP_API_KEY"],
    config=SDKConfig(log_level=os.environ.get("LOG_LEVEL", "WARNING")),
)

Common Configurations

Development

Verbose logging, short timeouts, and aggressive retries for fast feedback during development.

from maximem_synap import SDKConfig, TimeoutConfig, RetryPolicy

dev_config = SDKConfig(
    storage_path="/tmp/synap-dev",  # Temporary path for dev
    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"
)

Production

Conservative timeouts, standard retries with jitter, minimal logging, and persistent storage.

from maximem_synap import SDKConfig, TimeoutConfig, RetryPolicy

prod_config = SDKConfig(
    storage_path="/var/lib/synap",
    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"
)

Testing

Isolated storage, disabled caching for deterministic tests, no retries for immediate failure feedback.

from maximem_synap import SDKConfig, TimeoutConfig

test_config = SDKConfig(
    storage_path="/tmp/synap-test",
    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(
    api_key="synap_test_key",
    config=test_config,
    _force_new=True
)

High-Throughput

Optimized for batch ingestion workloads with generous timeouts, higher retry limits, and long sessions.

from maximem_synap import SDKConfig, TimeoutConfig, RetryPolicy

throughput_config = SDKConfig(
    storage_path="/var/lib/synap",
    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 maximem_synap import MaximemSynapSDK, SDKConfig, TimeoutConfig, RetryPolicy

sdk = MaximemSynapSDK(
    api_key="synap_your_key_here",
    config=SDKConfig(
        storage_path="/var/lib/myapp/synap",
        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",
                "SynapTransientError"
            ]
        ),
        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.

Setup

SDK Guide

Overview

SDKConfig Reference

Field Reference

Full parameter reference →

TimeoutConfig

RetryPolicy

Storage Path

When to Override

Credentials

Cache Backend

SQLite (Default, Recommended)

Disabled

Session Timeout

Log Level

Using `configure()`

Environment Variables

Common Configurations

Full Configuration Example

Next Steps

Initializing the SDK

API Error Reference

Production Checklist

Ingesting Memories

​Overview

​SDKConfig Reference

​Field Reference

Full parameter reference →

​TimeoutConfig

​RetryPolicy

​Storage Path

​When to Override

​Credentials

​Cache Backend

​SQLite (Default, Recommended)

​Disabled

​Session Timeout

​Log Level

​Using configure()

​Environment Variables

​Common Configurations

​Full Configuration Example

​Next Steps

Initializing the SDK

API Error Reference

Production Checklist

Ingesting Memories

Overview

SDKConfig Reference

Field Reference

TimeoutConfig

RetryPolicy

Storage Path

When to Override

Credentials

Cache Backend

SQLite (Default, Recommended)

Disabled

Session Timeout

Log Level

Using `configure()`

Environment Variables

Common Configurations

Full Configuration Example

Next Steps