Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.maximem.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
Authentication

The SDK authenticates with an API key generated when you create an Instance in the Synap Dashboard. One key per Instance; rotate or revoke at any time.
Never expose your API key in client-side code, public repositories, or browser requests. API keys should only be used in server-side environments.
See Authentication for a detailed walkthrough of API key generation and the credential lifecycle.

​
SDK versioning

The SDK and the underlying wire protocol are versioned. Non-breaking additions (new fields, new optional parameters) may be added within a major version without notice. Breaking changes ship in new major versions of the SDK; the upgrade path is documented in the Changelog.

​
Pagination

List methods on the SDK return paginated results. Pass page and page_size to control the window:
​
page
integer
Page number to retrieve. Defaults to 1.
​
page_size
integer
Number of items per page. Defaults to 20. Maximum 100.
Returned objects include both the data and the pagination envelope: 
result = await sdk.memories.list(page=1, page_size=20)

result.data          # list of memory records
result.page          # 1
result.page_size     # 20
result.total         # 42
result.total_pages   # 3

​
Rate Limiting

Requests are rate-limited per API key. When the limit is exceeded, the SDK raises RateLimitError. Tier limits:
TierRequests per minuteBurst
Free6010
Pro60050
EnterpriseCustomCustom
The SDK automatically retries with exponential backoff on rate-limit errors. You can read the limits from the exception: 
try:
    await sdk.memories.create(...)
except RateLimitError as e:
    print(e.limit)         # 60
    print(e.remaining)     # 0
    print(e.retry_after)   # seconds to wait

​
Correlation IDs

Every SDK call records a correlation ID — a unique identifier propagated through the full request lifecycle, including background jobs like ingestion. Access it from any SDK response: 
result = await sdk.memories.create(...)
print(result.correlation_id)  # "req_7f3a2b1c-9d4e-4f5a-8b6c-1d2e3f4a5b6c"
Always include the correlation_id when contacting support. It allows the team to trace the exact request path and identify issues quickly.

​
Error handling

The SDK raises typed exceptions for different failure classes. Each exception exposes a code (machine-readable), a message (human-readable), and a details object with context: 
from maximem_synap import (
    SynapError,
    AuthenticationError,
    InvalidInputError,
    ContextNotFoundError,
    RateLimitError,
    ServiceUnavailableError,
)

try:
    await sdk.memories.get("mem_nonexistent")
except ContextNotFoundError as e:
    print(e.code)      # machine-readable code from the server
    print(e.message)   # human-readable description
    print(e.details)   # additional context (e.g., the missing id)
All SDK exceptions inherit from SynapError and split into two branches: SynapTransientError (the SDK auto-retries) and SynapPermanentError (your code must handle). Common exceptions:
ExceptionBranchWhen raised
AuthenticationErrorPermanentAPI key missing, invalid, or revoked
InvalidInputErrorPermanentRequest parameters invalid or missing required fields (see details)
InvalidInstanceIdErrorPermanentProvided instance_id does not match a real instance
InvalidConversationIdErrorPermanentProvided conversation_id is malformed
ContextNotFoundErrorPermanentRequested instance, conversation, or memory does not exist
SessionExpiredErrorPermanentSession expired; re-authenticate
InsufficientCreditsErrorPermanentWallet has insufficient credits for this operation
ListeningAlreadyActiveErrorPermanentinstance.listen() called while another stream is open
ListeningNotActiveErrorPermanentinstance.send_message() called without an active stream
RateLimitErrorTransientRate limit exceeded — SDK auto-retries with backoff
NetworkTimeoutErrorTransientRequest timed out — SDK auto-retries with backoff
ServiceUnavailableErrorTransientSynap temporarily unavailable — SDK auto-retries with backoff
AgentUnavailableErrorTransientInternal agent unavailable — SDK auto-retries with backoff
For the full hierarchy and per-exception handling guidance, see Error Handling. For wire-level error codes (when interpreting the server’s code field), see Error Codes.

​
SDK installation

The official Python SDK is the primary customer interface. 
pip install maximem-synap

from maximem_synap import MaximemSynapSDK

sdk = MaximemSynapSDK(
    api_key="synap_your_key_here"
)

await sdk.initialize()

# All SDK methods are async
context = await sdk.conversation.context.fetch(
    conversation_id="conv_456",
    search_query=["user preferences"]
)
A JavaScript/TypeScript SDK is also available for Node.js environments: 
npm install @maximem/synap-js-sdk
The JavaScript SDK is a thin Node.js wrapper around the Python SDK and requires a Python 3.11+ runtime on the host. Edge Runtime, Cloudflare Workers, Bun, Deno Deploy, and AWS Lambda Node-only runtimes are not supported on the JS SDK — those platforms need a separate backend with Python 3.11+. See Installation → JavaScript / TypeScript SDK.
See the Installation guide for full setup instructions for both SDKs.