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

# 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+**, **Poetry 1.2+**, or **uv 0.4+** for package management
* **An active Synap account**: [Sign up at synap.maximem.ai](https://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

<CodeGroup>
  ```bash pip theme={null}
  pip install maximem-synap
  ```

  ```bash poetry theme={null}
  poetry add maximem-synap
  ```

  ```bash uv theme={null}
  uv add maximem-synap
  # pip-compatible (existing venv): uv pip install maximem-synap
  ```

  ```bash requirements.txt theme={null}
  # Add to your requirements.txt
  maximem-synap>=0.2.0
  ```
</CodeGroup>

<Note>
  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.
</Note>

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

<Warning>
  **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`](#vercel-ai-sdk-middleware) on the Node.js half of a Next.js app.
</Warning>

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

```bash theme={null}
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.

<Info>
  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.
</Info>

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

```typescript theme={null}
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`.

<Note>
  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.
</Note>

### Vercel AI SDK Middleware

If your application uses the [Vercel AI SDK](https://sdk.vercel.ai), 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.

```bash theme={null}
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.

<Warning>
  `@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.
</Warning>

## Environment variables

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

<ResponseField name="SYNAP_API_KEY" type="string" required>
  Your API key for SDK authentication. Generated in the Dashboard: navigate to your instance and click **Generate API Key**. Starts with `synap_`.
</ResponseField>

<ResponseField name="SYNAP_LOG_LEVEL" type="string">
  Logging verbosity for the SDK. Accepts standard Python logging levels: `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`. Defaults to `INFO`.
</ResponseField>

Set these in your environment:

<CodeGroup>
  ```bash Linux / macOS theme={null}
  export SYNAP_API_KEY="synap_your_key_here"
  export SYNAP_LOG_LEVEL="INFO"
  ```

  ```powershell Windows (PowerShell) theme={null}
  $env:SYNAP_API_KEY = "synap_your_key_here"
  $env:SYNAP_LOG_LEVEL = "INFO"
  ```

  ```ini .env file (with python-dotenv) theme={null}
  SYNAP_API_KEY=synap_your_key_here
  SYNAP_LOG_LEVEL=INFO
  ```
</CodeGroup>

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

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

```python theme={null}
# Reads SYNAP_API_KEY from the environment
sdk = MaximemSynapSDK()

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

<Tip>
  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).
</Tip>

## Verify installation

Run this script to verify your installation and connectivity:

```python verify_synap.py theme={null}
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())
```

```bash theme={null}
python verify_synap.py
```

Expected output:

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

## Async-first design

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

  ```python theme={null}
  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.
</Note>

## Troubleshooting

<AccordionGroup>
  <Accordion title="ImportError: No module named 'maximem_synap'">
    Verify the package is installed in your active Python environment:

    ```bash theme={null}
    pip show maximem-synap
    ```

    If using a virtual environment, make sure it's activated. If using Poetry, prefix commands with `poetry run`.
  </Accordion>

  <Accordion title="Connection refused or timeout during initialization">
    Check that:

    1. Your outbound network connectivity to Synap Cloud is permitted.
    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
  </Accordion>

  <Accordion title="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
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup cols={3}>
  <Card title="Authentication" icon="lock" href="/setup/authentication">
    Configure API key authentication, multiple keys per instance, and key rotation.
  </Card>

  <Card title="Integration" icon="plug" href="/setup/detailed-integration">
    Connect Synap to your application framework and infrastructure.
  </Card>

  <Card title="SDK Initialization" icon="code" href="/sdk/initialization">
    Explore all SDK initialization options, including custom credential providers.
  </Card>
</CardGroup>