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.

​
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 install maximem-synap
This installs the SDK with the following dependencies:
  • httpx — Async HTTP client for REST API calls
  • pydantic — Data validation and settings management
  • cryptography — Credential handling
  • grpcio — gRPC client for real-time streaming
gRPC streaming is enabled by default — no extra install needed. See Authentication for details.

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

​
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+ and ai >=3.0.0 as a peer dependency. TypeScript types are included.
This package uses gRPC for real-time anticipation cache updates (optional) and falls back to HTTP context fetch on every call. gRPC is lazy-imported so it is safe to use in Next.js Edge Runtime — it simply skips the stream connection.

​
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"
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):
    """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
        )
        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_API_KEY is correct and the key is active in the dashboard
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 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

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