supermemory/apps/docs/integrations/supermemory-sdk.mdx

---
title: 'Supermemory SDK'
sidebarTitle: "Supermemory SDK"
description: 'Official Python and JavaScript SDKs for Supermemory'
icon: "/images/supermemory.svg"
---

<CardGroup cols={2}>
  <Card title="Python SDK" icon="python" href="https://pypi.org/project/supermemory/">
    pip install supermemory
  </Card>
  <Card title="JavaScript SDK" icon="js" href="https://www.npmjs.com/package/supermemory">
    npm install supermemory
  </Card>
</CardGroup>

<Tip>
Both SDKs also work against [self-hosted Supermemory](/self-hosting/overview) — pass `baseURL: "http://localhost:6767"` (TypeScript) or `base_url="http://localhost:6767"` (Python) when creating the client.
</Tip>

<Tabs>
  <Tab title="TypeScript">
    ## Installation

    ```bash
    npm install supermemory
    ```

    ## Quick Start

    ```typescript
    import Supermemory from 'supermemory';

    const client = new Supermemory({
      apiKey: process.env.SUPERMEMORY_API_KEY,  // Default, can be omitted
    });

    // Add a memory
    await client.add({ content: "Meeting notes from Q1 planning", containerTag: "user_123" });

    // Search memories
    const response = await client.search({
      q: "planning notes",
      searchMode: "documents",
      containerTag: "user_123"
    });
    console.log(response.results);

    // Get user profile
    const profile = await client.profile({ containerTag: "user_123" });
    console.log(profile.profile.static);
    console.log(profile.profile.dynamic);
    ```

    ## Common Operations

    ```typescript
    // Add with metadata
    await client.add({
      content: "Technical design doc",
      containerTag: "user_123",
      metadata: { category: "engineering", priority: "high" }
    });

    // Search with filters
    const results = await client.search({
      q: "design document",
      searchMode: "documents",
      containerTag: "user_123",
      filters: {
        AND: [
          { key: "category", value: "engineering" }
        ]
      }
    });

    // List documents
    const docs = await client.documents.list({ containerTags: ["user_123"], limit: 10 });

    // Delete a document
    await client.documents.delete({ docId: "doc_123" });
    ```

    ## Error Handling & Retries

    | Status | Error |
    |--------|-------|
    | 400 | `BadRequestError` |
    | 401 | `AuthenticationError` |
    | 403 | `PermissionDeniedError` |
    | 404 | `NotFoundError` |
    | 409 | `ConflictError` |
    | 422 | `UnprocessableEntityError` |
    | 429 | `RateLimitError` |
    | >=500 | `InternalServerError` |

    Connection errors, 408, 409, 429, and >=500 responses are retried automatically (`maxRetries`, default 2, exponential backoff). Requests time out after 1 minute by default (`timeout` option). Set the `SUPERMEMORY_LOG` env var (or `logLevel` client option) to `debug`/`info`/`warn`/`error`/`off` — defaults to `warn`.

    Requires TypeScript >= 4.9, Node 20+, Deno 1.28+, or Bun 1.0+.
  </Tab>

  <Tab title="Python">
    ## Installation

    ```bash
    pip install supermemory
    ```

    ## Quick Start

    ```python
    import os
    from supermemory import Supermemory

    client = Supermemory(
        api_key=os.environ.get("SUPERMEMORY_API_KEY"),  # Default, can be omitted
    )

    # Add a memory
    client.add(content="Meeting notes from Q1 planning", container_tag="user_123")

    # Search memories
    response = client.search.memories(
        q="planning notes",
        search_mode="documents",
        container_tag="user_123"
    )
    print(response.results)

    # Get user profile
    profile = client.profile(container_tag="user_123")
    print(profile.profile.static)
    print(profile.profile.dynamic)
    ```

    ## Common Operations

    ```python
    # Add with metadata
    client.add(
        content="Technical design doc",
        container_tag="user_123",
        metadata={"category": "engineering", "priority": "high"}
    )

    # Search with filters
    results = client.search.memories(
        q="design document",
        search_mode="documents",
        container_tag="user_123",
        filters={
            "AND": [
                {"key": "category", "value": "engineering"}
            ]
        }
    )

    # List documents
    docs = client.documents.list(container_tags=["user_123"], limit=10)

    # Delete a document
    client.documents.delete(doc_id="doc_123")
    ```

    ## Error Handling & Retries

    Same error classes as the TypeScript SDK (`BadRequestError`, `AuthenticationError`, `PermissionDeniedError`, `NotFoundError`, `ConflictError`, `UnprocessableEntityError`, `RateLimitError`, `InternalServerError`), all inheriting from `supermemory.APIError`. Connection errors, 408, 409, 429, and >=500 responses are retried automatically (`max_retries`, default 2). Requests time out after 1 minute by default (`timeout` option). Set `SUPERMEMORY_LOG=info` (or `debug`) to enable logging.

    Requires Python 3.9+.
  </Tab>
</Tabs>