Skip to main content

​
Requirements

  • Python 3.10+ — 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

The standard installation includes everything you need for REST-based ingestion and retrieval:
pip install maximem-synap
This installs the core SDK with the following dependencies:
  • httpx — Async HTTP client for REST API calls
  • pydantic — Data validation and settings management
  • cryptography — Credential handling

​
JavaScript / TypeScript SDK

For Node.js environments, install the JavaScript SDK: 
npm install @maximem/synap-js-sdk
The JS SDK is a wrapper around the Python SDK and requires Node.js 18+. TypeScript types are included out of the box.
The Python SDK is the recommended primary integration path. Use the JavaScript SDK when your application is Node.js-based and cannot run a Python subprocess.

​
Environment variables

The SDK reads configuration from environment variables. This is the recommended approach for production deployments.
​
SYNAP_INSTANCE_ID
string
required
Your instance identifier, in the format inst_<hex16>. Found in the Dashboard under your instance settings.
​
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_INSTANCE_ID="inst_a1b2c3d4e5f67890"
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

After the initial bootstrap, the SDK stores credentials locally for subsequent connections. You can choose between two storage strategies:
Credentials are stored in SDK-managed local secure storage on the host machine. This is the default behavior and works well for single-machine deployments.
# File-based is the default -- no extra configuration needed
sdk = MaximemSynapSDK(
    instance_id="inst_a1b2c3d4e5f67890",
    api_key="synap_your_key_here"
)

​
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(
            instance_id="inst_a1b2c3d4e5f67890",
            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):
    """Synchronous wrapper for async ingestion."""
    async def _ingest():
        sdk = MaximemSynapSDK(
            instance_id="inst_a1b2c3d4e5f67890",
            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
        )
        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

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.
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_INSTANCE_ID and SYNAP_API_KEY are correct and the key is active in the dashboard
The API key provided does not match any active credential for this instance.
  1. Confirm the key is still active: Dashboard > Instances > [instance] > API Keys
  2. Check that SYNAP_API_KEY (or api_key=) matches the key shown in the Dashboard exactly — no extra whitespace or truncation
  3. If the key was revoked, generate a new one and update your environment
Make sure you installed with the gRPC extra:
pip install 'maximem-synap[grpc]'
Verify gRPC is available:
python -c "import grpc; print(grpc.__version__)"

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