Installation

This page covers installing the Synap SDK, configuring environment variables, and verifying your setup.

Requirements

• Python 3.11+ — The SDK uses modern Python features including asyncio, type hints, and structural pattern matching
• pip 21.0+ or Poetry 1.2+ 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

pip install maximem-synap

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 for transport
• pydantic — Data validation and settings management
• cryptography — Credential handling
• grpcio — gRPC client for real-time streaming
• protobuf — Required by grpcio to deserialize streaming message schemas

protobuf is pulled in as a direct dependency. If you see ModuleNotFoundError: No module named 'google' at runtime — usually the first time the SDK opens its gRPC stream — your environment is missing it. Install it explicitly with pip install protobuf and re-run; see Troubleshooting below.

gRPC streaming is enabled by default — no extra install needed. See Authentication for details.

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.

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 — 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:

Linux / macOS

export SYNAP_API_KEY="synap_your_key_here"
export 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, AWS Lambda, and Cloudflare Workers.

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(f"[OK] Connected to instance: {sdk.instance_id}")
        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:

1. Your network allows outbound HTTPS connections on port 443
2. If behind a corporate proxy, configure HTTPS_PROXY in your environment
3. Your SYNAP_API_KEY is correct and the key is active in the dashboard

API key rejected

If the SDK reports an authentication failure:

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

gRPC streaming not available

gRPC is included by default. Verify it imports cleanly:

python -c "import grpc; print(grpc.__version__)"

If the import fails, reinstall the SDK:

pip install --force-reinstall maximem-synap

ModuleNotFoundError: No module named 'google'

This surfaces the first time the SDK opens its gRPC stream — typically on sdk.instance.listen() rather than sdk.initialize() — so the SDK can appear to start cleanly and then fail seconds later. The root cause is a missing protobuf package, which grpcio does not pull in transitively.

Install it directly:

pip install protobuf

Then re-run your script. If you are pinning versions in a lockfile, add protobuf>=4.0 alongside grpcio.

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.