# How to Integrate Supermemory with Other Tools: SDKs, APIs, and Frameworks

> Discover how to integrate Supermemory with your preferred tools using our SDKs, APIs, and frameworks. Connect seamlessly to any HTTP-compatible environment.

- Repository: [supermemory/supermemory](https://github.com/supermemoryai/supermemory)
- Tags: how-to-guide
- Published: 2026-03-25

---

**You can integrate Supermemory with any environment that supports HTTP requests using the official TypeScript or Python SDKs, or by calling the REST endpoints directly with standard authentication headers.**

Supermemory exposes a unified memory layer through a RESTful HTTP API, enabling you to add persistent context to AI applications built with any framework. The repository provides first-class SDKs that wrap the raw API defined in [`packages/lib/api.ts`](https://github.com/supermemoryai/supermemory/blob/main/packages/lib/api.ts), making it straightforward to integrate Supermemory with other tools like Vercel AI SDK, LangChain, and CrewAI.

## Understanding the Core API Architecture

All public routes are centralized in **[`packages/lib/api.ts`](https://github.com/supermemoryai/supermemory/blob/main/packages/lib/api.ts)**, which uses `better-fetch` to declare strongly-typed request and response schemas. This file exposes the fundamental memory operations that every integration method uses under the hood.

```typescript
// packages/lib/api.ts
"@post/documents": {               // ←  [Add memory]
  input: MemoryAddSchema,
  output: MemoryResponseSchema,
},
"@post/search": {                  // ←  [Semantic search]
  input: SearchRequestSchema,
  output: SearchResponseSchema,
},

```

The **base URL** defaults to `https://api.supermemory.ai/v3` but can be overridden when initializing clients. The exact request contracts are enforced by Zod schemas located in **[`packages/validation/api.ts`](https://github.com/supermemoryai/supermemory/blob/main/packages/validation/api.ts)**, ensuring type safety across all integration methods.

## Authentication Methods

Supermemory supports two authentication mechanisms: **API key** authentication for server-to-server communication, and **session cookie** authentication for browser-based clients.

The authentication logic lives in **[`packages/lib/auth.ts`](https://github.com/supermemoryai/supermemory/blob/main/packages/lib/auth.ts)**, which implements a `better-auth` client supporting API keys and magic links:

```typescript
// packages/lib/auth.ts
export const authClient = createAuthClient({
  baseURL: process.env.NEXT_PUBLIC_BACKEND_URL ?? "https://api.supermemory.ai",
  fetchOptions: { credentials: "include", throw: true },
  plugins: [ usernameClient(), magicLinkClient(), apiKeyClient(), … ],
});

```

When using the raw API, include the header `x-api-key: YOUR_KEY` in your requests. When using the SDKs, pass the key during initialization and the client handles header injection automatically.

## Data Isolation with Container Tags

Every memory operation supports a **`containerTag`** parameter that creates isolated data partitions. This enables multi-tenant architectures where user data remains strictly separated.

```typescript
await client.add({ content: "...", containerTag: "user_123" });

```

When querying, passing the same tag to `profile` or `search.memories` scopes results to that specific container. This pattern is essential when you integrate Supermemory with other tools that serve multiple users or projects from a single backend.

## Integration Approaches

Choose the integration method that matches your technology stack:

- **Official TypeScript SDK** – Best for Node.js or frontend applications requiring full TypeScript support and built-in retry logic.
- **Official Python SDK** – Ideal for backend services, data science notebooks, and async workflows.
- **Direct HTTP Calls** – Use for languages without an SDK or when you need custom low-level control over requests.

All approaches share identical payload shapes defined in the validation schemas, ensuring consistent behavior across implementations.

## SDK Implementation Examples

### TypeScript SDK Integration

Install the SDK via npm (`npm install supermemory`), then initialize the client with your API key:

```typescript
import { Supermemory } from "supermemory";

const client = new Supermemory({
  apiKey: process.env.SUPERMEMORY_API_KEY,   // optional if env var set
  baseURL: "https://api.supermemory.ai",      // defaults to this
});

// Store a memory with metadata
await client.add({
  content: "User prefers dark mode and TypeScript",
  containerTag: "user_123",
  metadata: { source: "preferences", timestamp: new Date().toISOString() },
});

// Retrieve contextual profile
const profile = await client.profile({
  containerTag: "user_123",
  q: "What are the user's recent preferences?",
});

```

### Python SDK Integration

Install with pip (`pip install supermemory`) for synchronous support, or `pip install supermemory[aiohttp]` for async:

```python
import os
from supermemory import Supermemory

client = Supermemory(
    api_key=os.getenv("SUPERMEMORY_API_KEY"),
    base_url="https://api.supermemory.ai",
)

# Store a memory

client.add(
    content="User prefers dark mode and Python",
    container_tag="user_456",
    metadata={"source": "preferences", "timestamp": "2024-09-01T12:00:00Z"},
)

# Search with context

profile = client.profile(container_tag="user_456", q="recent settings")
print(profile)

```

### Direct HTTP Integration

For environments without SDK support, call the endpoints directly using standard HTTP clients:

```bash

# Add a memory

curl -X POST https://api.supermemory.ai/v3/documents \
  -H "Content-Type: application/json" \
  -H "x-api-key: $SUPERMEMORY_API_KEY" \
  -d '{
        "content": "User likes pizza",
        "containerTag": "user_789",
        "metadata": {"source":"chat"}
      }'

```

```bash

# Semantic search

curl -X POST https://api.supermemory.ai/v3/search \
  -H "Content-Type: application/json" \
  -H "x-api-key: $SUPERMEMORY_API_KEY" \
  -d '{
        "q": "food preferences",
        "containerTag": "user_789",
        "limit": 5,
        "threshold": 0.4
      }'

```

## Framework-Specific Integrations

### Vercel AI SDK

When using the Vercel AI SDK, wrap Supermemory calls inside your tool definitions to inject contextual memories before generation:

```typescript
import { Supermemory } from "supermemory";
import { openai } from "@ai-sdk/openai";
import { generateText } from "ai";

const memory = new Supermemory();

async function chat(userId: string, prompt: string) {
  // Pull contextual memories
  const ctx = await memory.profile({ containerTag: userId, q: prompt });

  const { text } = await generateText({
    model: openai("gpt-4"),
    system: `User profile: ${JSON.stringify(ctx.profile)}\nRelevant memories: ${JSON.stringify(
      ctx.memories ?? {}
    )}`,
    prompt,
  });

  // Store the exchange for future context
  await memory.add({
    content: `User: ${prompt}\nAssistant: ${text}`,
    containerTag: userId,
  });

  return text;
}

```

### LangChain Integration

For LangChain applications, use Supermemory to hydrate the system message with relevant context before invoking the model:

```typescript
import { Supermemory } from "supermemory";
import { ChatOpenAI } from "@langchain/openai";
import { HumanMessage, SystemMessage } from "@langchain/core/messages";

const memory = new Supermemory();
const llm = new ChatOpenAI({ model: "gpt-4" });

async function chatWithMemory(userId: string, userMsg: string) {
  const ctx = await memory.profile({ containerTag: userId, q: userMsg });

  const msgs = [
    new SystemMessage(`Context: ${JSON.stringify(ctx)}`),
    new HumanMessage(userMsg),
  ];

  const response = await llm.invoke(msgs);

  await memory.add({
    content: `${userMsg}\n${response.content}`,
    containerTag: userId,
  });

  return response.content;
}

```

### CrewAI Integration

In Python-based CrewAI workflows, initialize agents with profiles retrieved from Supermemory:

```python
from supermemory import Supermemory
from crewai import Agent, Task, Crew

memory = Supermemory()

def create_memory_agent(user_id: str):
    ctx = memory.profile(container_tag=user_id, query="user preferences")
    return Agent(
        role="Personal Assistant",
        goal="Help the user with personalized assistance",
        backstory=f"User context: {ctx['profile']}\nRecent memory: {ctx.get('memories')}",
        verbose=True,
    )

assistant = create_memory_agent("user_123")
task = Task(
    description="Suggest a TypeScript project structure for a new app",
    agent=assistant,
)
crew = Crew(agents=[assistant], tasks=[task])
result = crew.kickoff()

```

## Best Practices for Production

When you integrate Supermemory with other tools in production environments, follow these guidelines:

- **Maintain consistent container tags** – Use deterministic naming schemes like `user_<id>` or `org_<id>_proj_<id>` to ensure proper data isolation between tenants.
- **Leverage rich metadata** – Include searchable fields such as `source`, `type`, and timestamps to enable advanced filtering and audit trails.
- **Implement idempotent writes** – Provide `customId` when adding memories to prevent duplicates during retries and simplify updates.
- **Tune search thresholds** – Start with the default `0.5` threshold for balanced recall; increase to `0.7` or higher when precision is critical.
- **Handle error codes** – Watch for `401` (invalid API key) and `429` (rate limiting) when using direct HTTP integration.
- **Cache profile responses** – Cache `profile()` results for short TTLs (seconds) when querying the same user repeatedly to reduce latency.

## Summary

- Integrate Supermemory using the **TypeScript SDK**, **Python SDK**, or **direct HTTP calls** to `https://api.supermemory.ai/v3` depending on your stack.
- Authenticate via the **`x-api-key`** header or session cookies as implemented in [`packages/lib/auth.ts`](https://github.com/supermemoryai/supermemory/blob/main/packages/lib/auth.ts).
- Use **`containerTag`** to isolate data between users or projects, enabling secure multi-tenant architectures.
- Framework wrappers for **Vercel AI SDK**, **LangChain**, and **CrewAI** follow the same pattern: retrieve context with `profile()`, generate a response, then store the exchange with `add()`.
- Reference the Zod schemas in [`packages/validation/api.ts`](https://github.com/supermemoryai/supermemory/blob/main/packages/validation/api.ts) and route definitions in [`packages/lib/api.ts`](https://github.com/supermemoryai/supermemory/blob/main/packages/lib/api.ts) for exact payload specifications.

## Frequently Asked Questions

### What is the default base URL for Supermemory API calls?

The default base URL is `https://api.supermemory.ai/v3`, as defined in the SDK initialization and [`packages/lib/api.ts`](https://github.com/supermemoryai/supermemory/blob/main/packages/lib/api.ts). You can override this by passing a custom `baseURL` (TypeScript) or `base_url` (Python) when instantiating the client, which is useful for self-hosted or enterprise deployments.

### How do I keep different users' memories separate in Supermemory?

Use the **`containerTag`** parameter on every `add`, `search`, and `profile` operation. This arbitrary string acts as a namespace that completely isolates data. For example, using `containerTag: "user_123"` ensures that queries for "user_456" will never return memories from "user_123".

### Can I use Supermemory without the official SDKs?

Yes. The API is fully accessible via standard HTTP requests to endpoints like `POST /v3/documents` and `POST /v3/search`. Set the `Content-Type: application/json` and `x-api-key` headers as shown in the curl examples, and structure your payloads according to the Zod schemas in [`packages/validation/api.ts`](https://github.com/supermemoryai/supermemory/blob/main/packages/validation/api.ts).

### Which AI frameworks support direct Supermemory integration?

Supermemory works with any framework that can execute HTTP requests or JavaScript/Python code, including **Vercel AI SDK**, **LangChain** (TypeScript and Python), **CrewAI**, and custom agent frameworks. The integration pattern remains consistent: fetch relevant context using `profile()`, inject it into the prompt, and persist the interaction using `add()`.