SDK Configuration

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. Three differences worth knowing before you read them:

Three keys do nothing here. storage_path, cache_backend and session_timeout_minutes are accepted and ignored, so one config object can be shared between the two SDKs. The cache is in memory, so there is no path to point at and no backend to swap. log_level is ignored too, but logger is real: see below.
The stream endpoint moves. grpc_host, grpc_port and grpc_use_tls are options on instance.listen(), not on the client.
Timeouts and the retry policy are real, and their defaults match Python exactly: connect 5s, read 30s, write 10s, 3 attempts, backoff base 1s capped at 10s.
logger works. Pass (level, message) => void and every diagnostic the SDK emits routes there instead of the console. JavaScript has no global logging framework whose level there would be to set, so the SDK takes the sink directly rather than a level plus a framework.

Full surface: JavaScript: client options below.

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
    grpc_host=None,                       # Override the real-time stream host
    grpc_port=None,                       # Override the real-time stream port
    grpc_use_tls=None                     # None = TLS on; False = plaintext
)

import { SynapClient } from '@maximem/synap-js-sdk';

const sdk = new SynapClient({
  apiKey: undefined,                                    // Default: SYNAP_API_KEY
  instanceId: undefined,                                // Default: resolved from the key
  baseUrl: undefined,                                   // Default: Synap Cloud
  timeouts: { connect: 5.0, read: 30.0, write: 10.0 },  // Seconds
  retryPolicy: { maxAttempts: 3 },                      // null disables retries
  keepAlive: {},                                        // Connection reuse
  heartbeat: false,                                     // Periodic /health ping
  logger: (level, message) => {},                       // Default: console.warn
  sdk_st_authoritative: false,                          // Render prompts locally
  st_verbatim_overlay: true,                            // See a turn you just wrote
});

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

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
)

const 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
});

const 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
});

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.

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.

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.

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.

gRPC Connection

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.

config = SDKConfig(
    grpc_host="localhost",   # Default: Synap Cloud
    grpc_port=50051,         # Default: Synap Cloud
    grpc_use_tls=False,      # Default: None (TLS on)
)

// listen() options here, not client configuration.
await sdk.instance.listen({
  host: 'localhost',   // Default: Synap Cloud
  port: 50051,         // Default: Synap Cloud
  use_tls: false,      // Default: TLS 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). 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. If you fetch right after writing, an empty result is a legitimate response, and with cache_backend="sqlite" the local read cache will hold onto that empty result for its TTL, so later turns keep seeing nothing. For live agents that ingest and retrieve in the same loop, disable the local read cache:

config = SDKConfig(cache_backend=None)

// Nothing to disable: the JavaScript read cache is in memory, and a write
// invalidates the scope it touched.

The anticipation cache is unaffected and keeps working: the server pushes fresh bundles, so it invalidates correctly on its own.

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

import type { RetryPolicy } from '@maximem/synap-js-sdk';

// camelCase, and no retryable_errors: see the note below.
const retryPolicy: RetryPolicy = {
  maxAttempts: 3,       // Total attempts (1 initial + 2 retries)
  backoffBase: 1.0,     // Base delay in seconds
  backoffMax: 10.0,     // Maximum delay cap
  backoffJitter: true,  // Add randomized jitter
};

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

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.

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)

// Python only: the JavaScript cache is in memory, so there is no
// backend to disable.

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

// JavaScript has no global logging framework, so there is no level to set.
// Pass the sink instead: every diagnostic the SDK emits goes to it.
const sdk = new SynapClient({
  logger: (level, message) => myLogger[level](`[synap] ${message}`),
});

// Silence them entirely:
const quiet = new SynapClient({ logger: () => {} });

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.

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

const sdk = new SynapClient({ apiKey: 'synap_your_key_here' });

// Accepted and ignored:
sdk.configure({ log_level: 'DEBUG' });
sdk.configure({ session_timeout_minutes: 120 });
sdk.configure({ cache_backend: null });

// Real:
sdk.configure({ logger: (level, message) => myLogger[level](message) });

// These two are real:
sdk.configure({ timeouts: { read: 45.0 } });
sdk.configure({ retryPolicy: { maxAttempts: 5 } });

await sdk.initialize();

Calling configure() after initialize() raises InvalidInputError('Cannot reconfigure after initialization').

Environment Variables

A small set of connection settings can come from the environment. Everything else must be set in code via SDKConfig; pass it to the constructor (or configure()) before initialize().

Variable	Sets
`SYNAP_API_KEY`	API key, when no `api_key=` argument is passed
`SYNAP_BASE_URL`	`api_base_url`, the REST endpoint
`SYNAP_INSTANCE_ID`	`instance_id`, when no argument is passed

Explicit configuration always wins. Each variable is consulted only when the corresponding SDKConfig field is left as None, so setting a value in code makes the environment variable inert.

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")),
)

import { SynapClient } from '@maximem/synap-js-sdk';

// SYNAP_API_KEY is read automatically. Route diagnostics with `logger`.
const sdk = new SynapClient({
  logger: (level, message) => myLogger[level](`[synap] ${message}`),
});

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

// Development
const sdk = new SynapClient({
  timeouts: { connect: 3.0, read: 15.0, write: 5.0 },
  retryPolicy: { maxAttempts: 2, backoffBase: 0.5, backoffMax: 3.0 },
});

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

// Production
const sdk = new SynapClient({
  timeouts: { connect: 10.0, read: 30.0, write: 10.0 },
  retryPolicy: { maxAttempts: 3, backoffBase: 1.0, backoffMax: 10.0, backoffJitter: true },
  heartbeat: true,   // JS-only: keeps a long-lived connection warm
});

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
)

// Testing. _force_new gives this test its own client; call shutdown() in
// teardown, because nothing else will.
const sdk = new SynapClient({
  timeouts: { connect: 2.0, read: 5.0, write: 3.0 },
  retryPolicy: null,   // no retries: fail fast in tests
  _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"
)

// High throughput
const sdk = new SynapClient({
  timeouts: { connect: 5.0, read: 60.0, write: 15.0 },
  retryPolicy: { maxAttempts: 5, backoffBase: 0.5, backoffMax: 20.0, backoffJitter: true },
  keepAlive: {},   // JS-only: reuse connections across requests
});

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

import { SynapClient } from '@maximem/synap-js-sdk';

const sdk = new SynapClient({
  apiKey: 'synap_your_key_here',
  timeouts: { connect: 10.0, read: 30.0, write: 10.0 },
  retryPolicy: {
    maxAttempts: 3,
    backoffBase: 1.0,
    backoffMax: 10.0,
    backoffJitter: true,   // No retryable_errors; see the note below
  },
});

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.

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.

object

{ connect, read, write } in seconds. Defaults to 5s connect and 30s read.

object

{ maxAttempts, backoffBase, backoffMax, backoffJitter }. Defaults to 3 attempts with jittered exponential backoff.

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.

Setup

SDK Guide

Overview

SDKConfig Reference

Field Reference

Full parameter reference →

TimeoutConfig

gRPC Connection

Caching and async ingestion

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

JavaScript: client options

​Overview

​SDKConfig Reference

​Field Reference

Full parameter reference →

​TimeoutConfig

​gRPC Connection

​Caching and async ingestion

​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

​JavaScript: client options

Overview

SDKConfig Reference

Field Reference

TimeoutConfig

gRPC Connection

Caching and async ingestion

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

JavaScript: client options