Installation - Maximem Synap

Synap ships two native SDKs: one for Python, one for JavaScript and TypeScript. Pick your language below. Each has a complete setup path of its own.

	Python	JavaScript / TypeScript
Package	`maximem-synap` (PyPI)	`@maximem/synap-js-sdk` (npm)
Runtime	Python 3.11+	Node.js 20+
Setup steps	1 (install)	1 (install)
Types	Built-in type hints	Bundled `.d.ts`, no extra step
Guide	Python SDK	JavaScript and TypeScript SDK

JavaScript and TypeScript are served by the same npm package. TypeScript is not a separate SDK and needs no separate installation: types ship with the package.

Python SDK

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

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

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.

Pin at least 0.4.1 if one process ever uses more than one API key: a per-tenant backend, a worker that switches keys between jobs, or staging and production side by side. In 0.4.0 and earlier, the second and later SDKs in a process silently adopted the first one’s credentials, so their reads returned the first key’s memory and their writes were committed against it. See the 0.4.1 release notes. A single-API-key process is unaffected.

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.

Configure

Set your API key. See environment variables for all options.

export SYNAP_API_KEY="synap_your_key_here"

Verify

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

JavaScript and TypeScript SDK

One package serves both: @maximem/synap-js-sdk. Type definitions ship with it, so TypeScript is typed the moment you install and needs no extra step.

Requirements

Node.js 20+
An active Synap account: Sign up at synap.maximem.ai

Install

npm install @maximem/synap-js-sdk

That is the whole installation, in both languages. The anticipation stream is optional and needs two more packages. Skip this unless you want it:

npm install @grpc/grpc-js @grpc/proto-loader

Writing plain JavaScript, not TypeScript?

Nothing changes. There is no separate JavaScript build, no typescript dependency to add, no tsconfig.json to create, and no compile step. npm install and you are done.The bundled type definitions are inert at runtime, so they cost you nothing. Most editors read them anyway, which means you get autocomplete and inline parameter help in a plain .js file without opting into TypeScript.Use require() or import depending on how your project is written; see module format. The examples below are labelled ts, but they use no type annotations, so they are valid JavaScript exactly as written. Swap the import line for a require() if your project is CommonJS. The one section that is genuinely TypeScript-only is exported types, which you can skip.

Configure

Set your API key. See environment variables for all options.

export SYNAP_API_KEY="synap_your_key_here"

Your client_id and instance_id are resolved from the key when you call initialize(), so you do not need to plumb them separately.

Verify

Check the install and your credentials in one go:

verify-synap.mjs

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

const synap = new SynapClient({ apiKey: process.env.SYNAP_API_KEY });

try {
  await synap.initialize();
  console.log("[OK] client initialized");
  console.log(`[OK] connected to instance: ${synap.instance_id || "(resolved from key)"}`);
  await synap.shutdown();
  console.log("[OK] shut down cleanly");
} catch (error) {
  console.error(`[ERROR] ${error.message}`);
}

node verify-synap.mjs

Expected output:

[OK] client initialized
[OK] connected to instance: inst_a1b2c3d4e5f67890
[OK] shut down cleanly

Module format

The package ships both ES modules and CommonJS, with types for each. Import it whichever way your project is written:

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

const { SynapClient } = require("@maximem/synap-js-sdk");

Because a dual-format dependency graph can hand you two copies of the same class, every error also carries a stable .code string. Branch on error.code rather than instanceof when you cannot guarantee a single copy. See typed error handling.

Where it runs

Runtime	Context and memories	Anticipation stream
Node.js 20+	Yes	Yes (opt-in)
Bun	Yes	Unverified
Deno 2	Yes	Unverified
Vercel Edge	Yes	No
Cloudflare Workers	Yes	No
Browser	Yes (do not ship an API key to a browser)	No

The anticipation stream needs raw TCP and node:http2, which Edge runtimes and Workers do not provide. Importing the SDK there is safe: the stream lives behind the @maximem/synap-js-sdk/grpc subpath and is only ever loaded lazily, so it never enters an Edge bundle. Bun and Deno have both, so the stream is plausible on each, but bidirectional streaming has not been verified there.

tsconfig requirements

None specific to this package. It is verified against TypeScript 5.7 and 7.0 with moduleResolution set to node, node16, nodenext and bundler, and it typechecks under strict, exactOptionalPropertyTypes and noUncheckedIndexedAccess. A minimal configuration:

tsconfig.json

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "strict": true,
    "skipLibCheck": true,
    "outDir": "dist"
  },
  "include": ["src/**/*.ts"]
}

Next: using it

Installation is done. For the client surface, the cross-scope fetch, LLM tool definitions, typed errors and the anticipation stream, see Using the JavaScript SDK.

Vercel AI SDK Middleware

If your application uses the Vercel AI SDK, the @maximem/synap-vercel-adk middleware wraps any 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+ and ai >=3.0.0 as a peer dependency. TypeScript types are included.

It runs on the Next.js Edge Runtime for context fetching and memory writes, which use fetch only. You do not need to pin export const runtime = "nodejs" for those.The one exception is the optional gRPC anticipation stream, which needs @grpc/grpc-js and therefore a Node.js runtime. It is loaded lazily, so importing the package on Edge is safe; only enabling the stream requires Node.js.

Environment variables

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

All languages

string

required

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

string

Records which instance you are on. Optional; the dashboard gives you it alongside the API key so you can paste both in one go. Starts with inst_.

string

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

Set the instance id as an environment variable, not as a constructor argument. SYNAP_INSTANCE_ID records which instance you are on and leaves the SDK keyed on your credential. Passing instance_id= to MaximemSynapSDK(...) is different: it makes the id the identity, so a second key used under it is silently discarded and key rotation stops taking effect. See Singleton Pattern.

string

API base URL. Set it when you run a self-hosted deployment; otherwise leave it unset and the SDK uses Synap Cloud.

string

Optional. Skips one identity round trip during initialize(). Resolved from the API key when omitted.

Anticipation stream

Only needed when you use the anticipation stream, and only when your deployment is not the default.

string

Stream host. Defaults to the same deployment your API calls go to.

string

Stream port. Defaults to 443.

string

Set to 0 for a plaintext connection. Only sensible against a local or tunnelled deployment.

Setting them

export SYNAP_API_KEY="synap_your_key_here"
export SYNAP_INSTANCE_ID="inst_your_instance_id"
export SYNAP_LOG_LEVEL="INFO"

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

SYNAP_API_KEY=synap_your_key_here
SYNAP_INSTANCE_ID=inst_your_instance_id
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 / apiKey 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"
)

// Reads SYNAP_API_KEY from the environment
const synap = new SynapClient();

// Or pass the key explicitly
const synap = new SynapClient({
  apiKey: "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.

Troubleshooting

Python: 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.

JS/TS: No Synap API key found

The client could not resolve a credential. Set SYNAP_API_KEY in the environment, or pass apiKey to the constructor:

const synap = new SynapClient({ apiKey: process.env.SYNAP_API_KEY });

JS/TS: Cannot find module '@grpc/grpc-js'

The anticipation stream needs two optional peers that are not installed by default, because most applications never open a stream:

npm install @grpc/grpc-js @grpc/proto-loader

Everything except instance.listen() works without them.

JS/TS: the stream will not open on Edge or Workers

It cannot. The stream needs raw TCP and node:http2, which those runtimes do not provide. Context fetching and memory writes work there normally; only the stream is unavailable. See where it runs.

JS/TS: requests are going to the wrong deployment

Check SYNAP_BASE_URL. When it is unset the SDK uses Synap Cloud, and an explicit baseUrl in the constructor beats the environment. If you point the HTTP base at one deployment, point SYNAP_GRPC_HOST at the same one.

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.

​Python SDK

​Requirements

​Install

​Configure

​Verify

​Async-first design

​JavaScript and TypeScript SDK

​Requirements

​Install

​Configure

​Verify

​Module format

​Where it runs

​tsconfig requirements

​Next: using it

​Vercel AI SDK Middleware

​Environment variables

​All languages

​Anticipation stream

​Setting them

​Credential storage

​Troubleshooting

​Next steps

Authentication

Integration

SDK Initialization

Python SDK

Requirements

Install

Configure

Verify

Async-first design

JavaScript and TypeScript SDK

Requirements

Install

Configure

Verify

Module format

Where it runs

tsconfig requirements

Next: using it

Vercel AI SDK Middleware

Environment variables

All languages

Anticipation stream

Setting them

Credential storage

Troubleshooting

Next steps