Installation

Requirements

Python 3.11+: The SDK uses modern Python features including asyncio, type hints, and structural pattern matching
pip 21.0+, Poetry 1.2+, or uv 0.4+ for package management
An active Synap account: Sign up at synap.maximem.ai

Install the SDK

Synap provides two official SDKs. The Python SDK is the primary integration path. The JavaScript/TypeScript SDK is available for Node.js environments.

Python SDK

pip install maximem-synap

poetry add maximem-synap

uv add maximem-synap
# pip-compatible (existing venv): uv pip install maximem-synap

# Add to your requirements.txt
maximem-synap>=0.2.0

The package name uses a hyphen (maximem-synap) but the import name uses an underscore (maximem_synap). Install with pip install maximem-synap, then from maximem_synap import MaximemSynapSDK in your code.

This installs the SDK with the following dependencies:

httpx: Async HTTP client used by the SDK
pydantic: Data validation and settings management
cryptography: Credential handling
Additional transport dependencies pulled in automatically; no extra install needed.

JavaScript / TypeScript SDK

The JavaScript SDK requires a Python 3.11+ runtime on the host. It is implemented as a thin Node.js wrapper that spawns the Python SDK as a subprocess and bridges over a local IPC channel. This means:

Serverless platforms without a Python runtime are not supported, including Vercel Edge Runtime, Cloudflare Workers, AWS Lambda Node-only runtimes, Deno Deploy, and Bun.
Standard Node.js servers (long-running processes, container deployments, AWS Lambda with custom layers that include Python) work as expected.
If you are on a Python-less runtime, deploy a separate backend service with Python 3.11+ and call it from your Edge handlers, or use @maximem/synap-vercel-adk on the Node.js half of a Next.js app.

For Node.js environments with a Python 3.11+ interpreter available, install the JavaScript SDK:

npm install @maximem/synap-js-sdk

Requires Node.js 18+ and Python 3.11+ on the host. TypeScript types are included out of the box.

The Python SDK is the recommended primary integration path. The JavaScript wrapper exists so Node.js applications can share the same authentication, retry, and caching behavior, but it inherits the Python SDK’s runtime requirement.

API surface: namespaced and flat

From @maximem/synap-js-sdk 0.3.0, the JavaScript client mirrors the Python SDK’s namespaced API one-to-one, so the same call shapes work in both languages:

import { createClient } from "@maximem/synap-js-sdk";

const sdk = createClient();
await sdk.init();

// Ingest a conversation turn
await sdk.conversation.record_message({
  conversationId,           // a UUID
  role: "user",
  content: "I prefer window seats",
  userId,
  customerId,               // required; on B2C pass the same value as userId
});

// Ingest a standalone document
await sdk.memories.create({
  document: "Acme upgraded to the Pro plan",
  userId,
  customerId,
});

// Retrieve context for the scope you ingested at
const userCtx = await sdk.user.context.fetch({
  userId,
  customerId,
  searchQuery: ["seat preference"],
});
const promptCtx = await sdk.conversation.context.get_context_for_prompt({ conversationId });

The namespaced surface is: sdk.fetch(), sdk.conversation.record_message(), sdk.conversation.context.get_context_for_prompt(), sdk.conversation.context.fetch(), sdk.memories.create(), and sdk.{user,customer,client}.context.fetch(). Argument keys may be camelCase or snake_case.

The original flat methods — sdk.addMemory(), sdk.fetchUserContext(), and friends — remain fully supported and unchanged; the namespaced methods are added alongside them. The namespaced methods return the raw (snake_case) response shape that the framework integrations (@maximem/synap-mastra, @maximem/synap-claude-agent) consume, so a createClient() instance can be passed straight into them.

Vercel AI SDK Middleware

If your application uses the Vercel AI SDK, use the @maximem/synap-vercel-adk middleware package. It wraps any LanguageModelV1-compatible model and injects Synap context automatically, with no changes to your existing generateText / streamText calls.

npm install @maximem/synap-vercel-adk

Requires Node.js 18+, Python 3.11+ on the host (the middleware inherits the JavaScript SDK’s runtime requirement above), and ai >=3.0.0 as a peer dependency. TypeScript types are included.

@maximem/synap-vercel-adk inherits the JavaScript SDK’s Python-subprocess requirement and does not run on Next.js Edge Runtime. Pin route handlers to export const runtime = "nodejs". If your Vercel deployment must run on Edge, place a separate Python-capable backend (e.g., a Vercel Serverless Function with Python runtime) between the Edge handler and Synap.

Environment variables

The SDK reads configuration from environment variables. This is the recommended approach for production deployments.

SYNAP_API_KEY

string

required

Your API key for SDK authentication. Generated in the Dashboard: navigate to your instance and click Generate API Key. Starts with synap_.

SYNAP_LOG_LEVEL

string

Logging verbosity for the SDK. Accepts standard Python logging levels: DEBUG, INFO, WARNING, ERROR, CRITICAL. Defaults to INFO.

Set these in your environment:

export SYNAP_API_KEY="synap_your_key_here"
export SYNAP_LOG_LEVEL="INFO"

$env:SYNAP_API_KEY = "synap_your_key_here"
$env:SYNAP_LOG_LEVEL = "INFO"

SYNAP_API_KEY=synap_your_key_here
SYNAP_LOG_LEVEL=INFO

Never commit API keys to version control. Use a secrets manager (AWS Secrets Manager, GCP Secret Manager, HashiCorp Vault) or environment variables in production.

Credential storage

The SDK reads the API key from SYNAP_API_KEY (or the api_key= constructor argument) on every startup. There is no on-disk credential cache; the key lives wherever your secrets manager or environment configuration puts it.

# Reads SYNAP_API_KEY from the environment
sdk = MaximemSynapSDK()

# Or pass the key explicitly
sdk = MaximemSynapSDK(
    api_key="synap_your_key_here"
)

In Kubernetes, mount the API key as a secret and reference it via SYNAP_API_KEY in your pod spec. The same pattern works for Docker, Vercel, and AWS Lambda (Python 3.11+ on host required).

Verify installation

Run this script to verify your installation and connectivity:

verify_synap.py

import asyncio
from maximem_synap import MaximemSynapSDK

async def verify():
    try:
        sdk = MaximemSynapSDK(
            api_key="synap_your_key_here"
        )
        await sdk.initialize()
        print("[OK] SDK initialized successfully")
        print("[OK] Connected to Synap")
        await sdk.shutdown()
        print("[OK] SDK shut down cleanly")
    except Exception as e:
        print(f"[ERROR] {e}")

if __name__ == "__main__":
    asyncio.run(verify())

python verify_synap.py

Expected output:

[OK] SDK initialized successfully
[OK] Connected to instance: inst_a1b2c3d4e5f67890
[OK] SDK shut down cleanly

Async-first design

The Synap SDK is async-first. All SDK methods that interact with Synap Cloud are async and must be called with await inside an async function.If you’re integrating with a synchronous codebase, use asyncio.run() to bridge the gap:

import asyncio
from maximem_synap import MaximemSynapSDK

def ingest_sync(document: str, user_id: str, customer_id: str):
    """Synchronous wrapper for async ingestion."""
    async def _ingest():
        sdk = MaximemSynapSDK(
            api_key="synap_your_key_here"
        )
        await sdk.initialize()
        result = await sdk.memories.create(
            document=document,
            document_type="ai-chat-conversation",
            user_id=user_id,
            customer_id=customer_id,
        )
        await sdk.shutdown()
        return result

    return asyncio.run(_ingest())

For frameworks that already run an event loop (FastAPI, Sanic, aiohttp), use the SDK directly without wrapping.

Troubleshooting

ImportError: No module named 'maximem_synap'

Verify the package is installed in your active Python environment:

pip show maximem-synap

If using a virtual environment, make sure it’s activated. If using Poetry, prefix commands with poetry run.

Connection refused or timeout during initialization

Check that:

Your outbound network connectivity to Synap Cloud is permitted.
If behind a corporate proxy, configure HTTPS_PROXY in your environment
Your SYNAP_API_KEY is correct and the key is active in the dashboard

API key rejected

If the SDK reports an authentication failure:

Confirm SYNAP_API_KEY starts with synap_ and is not wrapped in quotes in your shell
Check the key is still active in the Dashboard (Instance → API Keys)
If the key was revoked, generate a new one and update your .env or secrets manager

Next steps

Authentication

Configure API key authentication, multiple keys per instance, and key rotation.

Integration

Connect Synap to your application framework and infrastructure.

SDK Initialization

Explore all SDK initialization options, including custom credential providers.

Setup

SDK Guide

Requirements

Install the SDK

Python SDK

JavaScript / TypeScript SDK

API surface: namespaced and flat

Vercel AI SDK Middleware

Environment variables

Credential storage

Verify installation

Async-first design

Troubleshooting

Next steps

Authentication

Integration

SDK Initialization

​Requirements

​Install the SDK

​Python SDK

​JavaScript / TypeScript SDK

​API surface: namespaced and flat

​Vercel AI SDK Middleware

​Environment variables

​Credential storage

​Verify installation

​Async-first design

​Troubleshooting

​Next steps

Authentication

Integration

SDK Initialization

Requirements

Install the SDK

Python SDK

JavaScript / TypeScript SDK

API surface: namespaced and flat

Vercel AI SDK Middleware

Environment variables

Credential storage

Verify installation

Async-first design

Troubleshooting

Next steps