SuperMemory

https://github.com/supermemoryai/supermemory
Admin
Supermemory is a developer-friendly API that integrates external knowledge into AI applications,...
Tokens:463,240
Snippets:3,436
Trust Score:7.3
License:MIT
Update:2 days ago
Show doc for...
Tokens:
Raw
### Python: Install and Start Client

Source: https://github.com/supermemoryai/supermemory/blob/main/apps/docs/integrations/supermemory-sdk.mdx

Shows how to install the Supermemory Python SDK and start a client, including adding a document, searching, and getting a user profile.

```APIDOC
## Install the Python SDK

### Description
Install the Supermemory Python SDK using pip.

### Method
Installation

### Command
```bash
pip install supermemory
```

## Start a Python client

### Description
Create a Supermemory client instance and perform basic operations like adding a document, searching, and getting a user profile.

### Method
Client Initialization and Operations

### Parameters
#### Client Constructor
- **api_key** (string) - Optional - API key. Defaults to environment variable `SUPERMEMORY_API_KEY`.

#### Add Document
- **user_id** (string) - Required - The user identifier.
- **content** (string) - Required - The document content.
- **id** (string) - Optional - Custom document ID; the response echoes it.
- **metadata** (dict) - Optional - Metadata associated with the document.
- **dreaming** (string) - Optional - Dreaming mode, e.g., "instant".

#### Search
- **user_id** (string) - Required - The user identifier.
- **query** (string) - Required - The search query.
- **limit** (int) - Optional - Maximum number of results.

#### Get User Profile
- **user_id** (string) - Required - The user identifier.

### Request Example
```python
import os
from supermemory import Supermemory

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

# Add a document
result = client.add(
    "user_123",
    content="Meeting notes from Q1 planning",
    id="meeting-q1",  # optional, your own id; the response echoes it
    metadata={"category": "engineering", "priority": "high"},
    dreaming="instant",
)
print(result.id, result.status)

# Search (hybrid by default: memories plus document chunks)
response = client.search("user_123", query="planning notes", limit=10)
for hit in response.results:
    print(hit.memory or hit.chunk, hit.similarity)

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

--------------------------------

### Development setup with uv

Source: https://github.com/supermemoryai/supermemory/blob/main/packages/openai-sdk-python/README.md

Install uv, clone the repository, and sync development dependencies.

```bash
# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# Clone and setup
git clone <repository-url>
cd packages/openai-sdk-python
uv sync --dev
```

--------------------------------

### Install AI SDK packages for chat example

Source: https://github.com/supermemoryai/supermemory/blob/main/apps/docs/integrations/convex.mdx

Install additional packages needed for the AI chat example.

```bash
npm install @supermemory/tools @ai-sdk/openai ai
```

--------------------------------

### Install and run the playground with bun

Source: https://github.com/supermemoryai/supermemory/blob/main/apps/memory-graph-playground/README.md

Run these commands in the project root to install dependencies and start the development server. Then open http://localhost:3000 and enter your Supermemory API key.

```bash
bun install
bun dev
```

--------------------------------

### Run OpenClaw Supermemory setup wizard

Source: https://github.com/supermemoryai/supermemory/blob/main/apps/docs/integrations/openclaw.mdx

Starts the interactive setup wizard for the Supermemory plugin. You will be prompted to paste your API key (starts with sm_) from the console.

```bash
openclaw supermemory setup
```

--------------------------------

### Development Setup Commands

Source: https://github.com/supermemoryai/supermemory/blob/main/packages/cartesia-sdk-python/README.md

Commands to clone the repository, install the package in development mode, run tests, and format code.

```bash
# Clone repository
git clone https://github.com/supermemoryai/supermemory
cd supermemory/packages/cartesia-sdk-python

# Install in development mode
pip install -e ".[dev]"

# Run tests
pytest

# Format code
black .
isort .
```

--------------------------------

### Start the development server

Source: https://github.com/supermemoryai/supermemory/blob/main/CONTRIBUTING.md

Starts the development server for all apps on localhost ports. Note that apps/web only redirects to the console and needs no env setup.

```bash
bun run dev:local
```

--------------------------------

### Install dependencies and copy environment file

Source: https://github.com/supermemoryai/supermemory/blob/main/apps/sdk-playground/README.md

Run from the repository root. Installs dependencies with a frozen lockfile and copies the example environment file to .env.local. Required variables are SUPERMEMORY_API_KEY and OPENAI_API_KEY.

```bash
bun install --frozen-lockfile

cp apps/sdk-playground/.env.example apps/sdk-playground/.env.local
# Required:
# SUPERMEMORY_API_KEY=...
# OPENAI_API_KEY=...
```

--------------------------------

### JavaScript Development Setup

Source: https://github.com/supermemoryai/supermemory/blob/main/apps/docs/integrations/openai.mdx

Commands to install dependencies, run tests, type-check, and lint the JavaScript SDK.

```bash
# Install dependencies
npm install

# Run tests
npm test

# Type checking
npm run type-check

# Linting
npm run lint
```

--------------------------------

### Python Development Setup

Source: https://github.com/supermemoryai/supermemory/blob/main/apps/docs/integrations/openai.mdx

Commands to install uv, clone the repository, sync dependencies, run tests, type-check with mypy, and format code with black and isort.

```bash
# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# Setup project
git clone <repository-url>
cd packages/openai-sdk-python
uv sync --dev

# Run tests
uv run pytest

# Type checking
uv run mypy src/supermemory_openai

# Formatting
uv run black src/ tests/
uv run isort src/ tests/
```

--------------------------------

### Run advanced setup for custom container tags

Source: https://github.com/supermemoryai/supermemory/blob/main/apps/docs/integrations/openclaw.mdx

Starts the advanced setup wizard for the Supermemory plugin, which enables custom container tags and read-only Twitter bookmarks container.

```bash
openclaw supermemory setup-advanced
```

--------------------------------

### Setup by client

Source: https://github.com/supermemoryai/supermemory/blob/main/apps/docs/agents-and-mcp.mdx

Configuration examples for connecting to the Supermemory docs MCP server in various coding clients (Cursor, Claude Code, Codex, OpenCode, VS Code, Other).

```APIDOC
## Setup by client

### Description
Configuration examples for connecting to the Supermemory docs MCP server in various coding clients.

### Cursor
Add to `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "supermemory-docs": {
      "url": "https://supermemory.ai/docs/mcp"
    }
  }
}
```

### Claude Code
```bash
claude mcp add --transport http supermemory-docs https://supermemory.ai/docs/mcp
```

Or project `.mcp.json`:

```json
{
  "mcpServers": {
    "supermemory-docs": {
      "type": "http",
      "url": "https://supermemory.ai/docs/mcp"
    }
  }
}
```

### Codex
```bash
codex mcp add supermemory-docs --url https://supermemory.ai/docs/mcp
```

Or `~/.codex/config.toml`:

```toml
[mcp_servers.supermemory-docs]
url = "https://supermemory.ai/docs/mcp"
```

### OpenCode
```json
{
  "mcp": {
    "supermemory-docs": {
      "type": "remote",
      "url": "https://supermemory.ai/docs/mcp",
      "enabled": true
    }
  }
}
```

### VS Code
Add to `.vscode/mcp.json`:

```json
{
  "servers": {
    "supermemory-docs": {
      "type": "http",
      "url": "https://supermemory.ai/docs/mcp"
    }
  }
}
```

### Other
```json
{
  "mcpServers": {
    "supermemory-docs": {
      "url": "https://supermemory.ai/docs/mcp"
    }
  }
}
```

Stdio-only clients can proxy:

```json
{
  "mcpServers": {
    "supermemory-docs": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://supermemory.ai/docs/mcp"]
    }
  }
}
```
```

--------------------------------

### CLI setup and help commands

Source: https://github.com/supermemoryai/supermemory/blob/main/apps/docs/agents-and-mcp.mdx

Commands for coding agents to set up a project, print integration prompts, get agent-readable help, and migrate projects. The `--prompt` flag prints only the integration prompt, and `--json` outputs a command catalog.

```bash
npx supermemory setup              # detect project, launch/print integration flow
```

```bash
npx supermemory setup --prompt     # print integration prompt only
```

```bash
npx supermemory help --json        # agent-readable command catalog
```

```bash
npx supermemory help --all
```

```bash
npx supermemory migrate            # move a v3/v4 project to v5 with your agent
```

--------------------------------

### Orchestration (Python)

Source: https://github.com/supermemoryai/supermemory/blob/main/apps/docs/smfs/providers/daytona.mdx

Creates a Daytona sandbox with environment variables for API keys, installs SMFS, mounts the memory filesystem, uploads and runs the agent, then deletes the sandbox. Requires the SMFS_INSTALL variable from the setup snippet.

```python
import os
from pathlib import Path
from daytona_sdk import Daytona, DaytonaConfig

daytona = Daytona(DaytonaConfig(
    api_key=os.environ["DAYTONA_API_KEY"],
))
sandbox = daytona.create(
    env_vars={
        "SUPERMEMORY_API_KEY": os.environ["SUPERMEMORY_API_KEY"],
        "ANTHROPIC_API_KEY": os.environ["ANTHROPIC_API_KEY"],
    },
)

# See "Install SMFS in a Daytona sandbox" above
sandbox.process.exec(SMFS_INSTALL)

# Mount memory
sandbox.process.exec("$HOME/.local/bin/smfs login --key $SUPERMEMORY_API_KEY")
sandbox.process.exec(
    "bash -c '$HOME/.local/bin/smfs mount my_agent --ephemeral"
    " --path /home/daytona/memory --foreground &' && sleep 3"
)

# Upload and run the agent
sandbox.fs.upload_file(Path("agent.py").read_bytes(), "agent.py")
result = sandbox.process.exec("python3 agent.py")
print(result.result)

daytona.delete(sandbox)
```

--------------------------------

### Python SDK quick start with OpenAI

Source: https://github.com/supermemoryai/supermemory/blob/main/apps/docs/integrations/openai.mdx

Initialize the SupermemoryTools with your API key and project config, then use it with OpenAI's chat completions. The example shows how to handle tool calls by executing them with execute_memory_tool_calls.

```python
import asyncio
import openai
from supermemory_openai import SupermemoryTools, execute_memory_tool_calls

async def main():
    # Initialize OpenAI client
    client = openai.AsyncOpenAI(api_key="your-openai-api-key")

    # Initialize Supermemory tools
    tools = SupermemoryTools(
        api_key="your-supermemory-api-key",
        config={"project_id": "my-project"}
    )

    # Chat with memory tools
    response = await client.chat.completions.create(
        model="gpt-5",
        messages=[
            {
                "role": "system",
                "content": "You are a helpful assistant with access to user memories."
            },
            {
                "role": "user",
                "content": "Remember that I prefer tea over coffee"
            }
        ],
        tools=tools.get_tool_definitions()
    )

    # Handle tool calls if present
    if response.choices[0].message.tool_calls:
        tool_results = await execute_memory_tool_calls(
            api_key="your-supermemory-api-key",
            tool_calls=response.choices[0].message.tool_calls,
            config={"project_id": "my-project"}
        )
        print("Tool results:", tool_results)

    print(response.choices[0].message.content)

asyncio.run(main())
```

--------------------------------

### JavaScript/TypeScript SDK quick start with OpenAI

Source: https://github.com/supermemoryai/supermemory/blob/main/apps/docs/integrations/openai.mdx

Initialize the tools with getToolDefinitions and createToolCallExecutor, then use them with OpenAI's chat completions. The example shows how to execute tool calls in a loop.

```typescript
import { supermemoryTools, getToolDefinitions, createToolCallExecutor } from "@supermemory/tools/openai"
import OpenAI from "openai"

const client = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY!,
})

// Get tool definitions for OpenAI
const toolDefinitions = getToolDefinitions()

// Create tool executor
const executeToolCall = createToolCallExecutor(process.env.SUPERMEMORY_API_KEY!, {
  namespace: "your-project-id",
})

// Use with OpenAI Chat Completions
const completion = await client.chat.completions.create({
  model: "gpt-5",
  messages: [
    {
      role: "user",
      content: "What do you remember about my preferences?",
    },
  ],
  tools: toolDefinitions,
})

// Execute tool calls if any
if (completion.choices[0]?.message.tool_calls) {
  for (const toolCall of completion.choices[0].message.tool_calls) {
    const result = await executeToolCall(toolCall)
    console.log(result)
  }
}
```

--------------------------------

### Run Supermemory CLI

Source: https://github.com/supermemoryai/supermemory/blob/main/apps/docs/agents-and-mcp.mdx

Launches the Supermemory CLI for setup and integration. Useful for agents and humans to start the integration flow.

```bash
npx supermemory
```

--------------------------------

### Install with uv

Source: https://github.com/supermemoryai/supermemory/blob/main/packages/openai-sdk-python/README.md

Install the package using uv, the recommended package manager.

```bash
uv add supermemory-openai-sdk
```

--------------------------------

### Install Dependencies

Source: https://github.com/supermemoryai/supermemory/blob/main/packages/tools/test/chatapp/README.md

Run npm install to install all required dependencies for the chat app.

```bash
npm install
```

--------------------------------

### Python: Start a Supermemory client and perform basic operations

Source: https://github.com/supermemoryai/supermemory/blob/main/apps/docs/integrations/supermemory-sdk.mdx

Initialize the client with an API key (default can be omitted), then add a document, search, and get a user profile. The add method returns a result with id and status. Search is hybrid by default, returning memories and document chunks.

```python
import os
from supermemory import Supermemory

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

# Add a document
result = client.add(
    "user_123",
    content="Meeting notes from Q1 planning",
    id="meeting-q1",  # optional, your own id; the response echoes it
    metadata={"category": "engineering", "priority": "high"},
    dreaming="instant",
)
print(result.id, result.status)

# Search (hybrid by default: memories plus document chunks)
response = client.search("user_123", query="planning notes", limit=10)
for hit in response.results:
    print(hit.memory or hit.chunk, hit.similarity)

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

--------------------------------

### Install with pip

Source: https://github.com/supermemoryai/supermemory/blob/main/packages/openai-sdk-python/README.md

Install the package using pip.

```bash
pip install supermemory-openai-sdk
```

--------------------------------

### Orchestration (TypeScript)

Source: https://github.com/supermemoryai/supermemory/blob/main/apps/docs/smfs/providers/daytona.mdx

Creates a Daytona sandbox with environment variables for API keys, installs SMFS, mounts the memory filesystem, uploads and runs the agent, then deletes the sandbox. Requires the SMFS_INSTALL variable from the setup snippet.

```typescript
import { Daytona } from "@daytonaio/sdk";
import { readFileSync } from "fs";

const daytona = new Daytona({
  apiKey: process.env.DAYTONA_API_KEY!,
});
const sandbox = await daytona.create({
  envVars: {
    SUPERMEMORY_API_KEY: process.env.SUPERMEMORY_API_KEY!,
    ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY!,
  },
});

// See "Install SMFS in a Daytona sandbox" above
await sandbox.process.exec(SMFS_INSTALL);

// Mount memory
await sandbox.process.exec(
  "$HOME/.local/bin/smfs login --key $SUPERMEMORY_API_KEY"
);
await sandbox.process.exec(
  "bash -c '$HOME/.local/bin/smfs mount my_agent --ephemeral " +
  "--path /home/daytona/memory --foreground &' && sleep 3"
);

// Upload and run the agent
await sandbox.fs.uploadFile(readFileSync("agent.py"), "agent.py");
const result = await sandbox.process.exec("python3 agent.py");
console.log(result.result);

await daytona.delete(sandbox);
```

--------------------------------

### Install the OpenClaw Supermemory plugin

Source: https://github.com/supermemoryai/supermemory/blob/main/apps/docs/integrations/openclaw.mdx

Installs the @supermemory/openclaw-supermemory plugin. Restart OpenClaw after installing.

```bash
openclaw plugins install @supermemory/openclaw-supermemory
```

--------------------------------

### Installation

Source: https://github.com/supermemoryai/supermemory/blob/main/apps/docs/migration/from-zep.mdx

Install the Supermemory SDK for Python or TypeScript.

```APIDOC
## Installation

### Python
```bash
pip install supermemory
```

### TypeScript
```bash
npm install supermemory
```
```

--------------------------------

### Installation

Source: https://github.com/supermemoryai/supermemory/blob/main/apps/docs/integrations/ai-sdk.mdx

Install the @supermemory/tools package to use the Supermemory AI SDK.

```APIDOC
## Installation

### Description
Install the @supermemory/tools package to use the Supermemory AI SDK.

### Command
```bash
npm install @supermemory/tools
```
```

--------------------------------

### Install @supermemory/tools and @mastra/core

Source: https://github.com/supermemoryai/supermemory/blob/main/apps/docs/integrations/mastra.mdx

Install the required packages for the Mastra integration.

```bash
npm install @supermemory/tools @mastra/core
```

--------------------------------

### Install claude-agent-sdk

Source: https://github.com/supermemoryai/supermemory/blob/main/apps/docs/smfs/providers/daytona.mdx

Use pip install claude-agent-sdk to install the agent SDK (PyPI is reachable).

```bash
pip install claude-agent-sdk
```

--------------------------------

### Install with async support

Source: https://github.com/supermemoryai/supermemory/blob/main/packages/openai-sdk-python/README.md

Install the package with optional async dependencies using pip.

```bash
pip install 'supermemory-openai-sdk[async]'
```

--------------------------------

### Parallel Memory Operations with StateGraph

Source: https://github.com/supermemoryai/supermemory/blob/main/apps/docs/integrations/langgraph.mdx

Run retrieve_context and categorize nodes in parallel after START. Both must complete before the respond node runs. This example shows the graph setup with StateGraph and edges.

```python
from langgraph.graph import StateGraph, START, END

graph = StateGraph(State)
graph.add_node("retrieve", retrieve_context)
graph.add_node("categorize", categorize)
graph.add_node("respond", respond)

# Both run in parallel after START
graph.add_edge(START, "retrieve")
graph.add_edge(START, "categorize")

# Both must complete before respond
graph.add_edge("retrieve", "respond")
graph.add_edge("categorize", "respond")
graph.add_edge("respond", END)
```

--------------------------------

### Quickstart: create_bash and exec

Source: https://github.com/supermemoryai/supermemory/blob/main/apps/docs/smfs/bash-tool-python.mdx

Shows how to create a bash tool with create_bash, passing an API key and container tag, then execute a command and print its stdout. The returned CreateBashResult provides a Shell instance with .exec(cmd), a tool_description, configure_memory_paths(paths) to scope extracted paths, and refresh() to re-prime the path index after external writes.

```python
import asyncio
import os
from supermemory_bash import create_bash


async def main() -> None:
    result = await create_bash(
        api_key=os.environ["SUPERMEMORY_API_KEY"],
        container_tag="user_42",
    )
    bash = result.bash
    r = await bash.exec("ls /")
    print(r.stdout)


asyncio.run(main())
```

--------------------------------

### Install supermemory-bash with uv

Source: https://github.com/supermemoryai/supermemory/blob/main/apps/docs/smfs/bash-tool-python.mdx

Install the supermemory-bash package using uv.

```bash
uv add supermemory-bash
```

--------------------------------

### Complete configuration example

Source: https://github.com/supermemoryai/supermemory/blob/main/packages/openai-sdk-python/README.md

Shows a full configuration with all options: required container_tag and custom_id, verbose logging, full mode, and auto-save memory.

```python
from supermemory_openai import with_supermemory, OpenAIMiddlewareOptions

openai_with_memory = with_supermemory(
    openai_client,
    OpenAIMiddlewareOptions(
        container_tag="user-123",        # Required: unique user/container identifier
        custom_id="chat-session-456",    # Required: groups messages into documents
        verbose=True,                    # Enable detailed logging
        mode="full",                     # Use both profile and query
        add_memory="always"              # Auto-save conversations (default)
    )
)
```

--------------------------------

### Run Supermemory with Docker Compose

Source: https://github.com/supermemoryai/supermemory/blob/main/README.md

For a new installation, download the compose file, set your OpenAI API key and version, then start the stack. The API listens on http://localhost:6767 and data persists in the supermemory_supermemory-data volume. Get the local API key with docker compose exec supermemory cat /data/api-key.

```bash
release_url=https://github.com/supermemoryai/supermemory/releases
curl -fL "$release_url/download/server-v0.0.9/compose.yaml" -o compose.yaml
export OPENAI_API_KEY=your_openai_api_key_here
export SUPERMEMORY_VERSION=0.0.9
docker compose up -d --wait --wait-timeout 180
```

--------------------------------

### Install @supermemory/bash with bun

Source: https://github.com/supermemoryai/supermemory/blob/main/apps/docs/smfs/bash-tool.mdx

Alternative installation using bun package manager.

```bash
bun add @supermemory/bash
```

--------------------------------

### Install @supermemory/tools 3.0 and supermemory 5

Source: https://github.com/supermemoryai/supermemory/blob/main/apps/docs/migration/tools-v3-upgrade.mdx

Install the required packages for the 3.0 upgrade.

```bash
npm install @supermemory/tools@3 supermemory@5
```

--------------------------------

### Installation

Source: https://github.com/supermemoryai/supermemory/blob/main/packages/pipecat-sdk-python/README.md

Install the Supermemory Pipecat SDK via pip.

```APIDOC
## Installation

```bash
pip install supermemory-pipecat
```
```

--------------------------------

### Install supermemory and convex packages

Source: https://github.com/supermemoryai/supermemory/blob/main/apps/docs/integrations/convex.mdx

Install the core packages required for the integration.

```bash
npm install supermemory convex
```

--------------------------------

### Install Supermemory locally with curl or npx

Source: https://github.com/supermemoryai/supermemory/blob/main/README.md

Use either command to install Supermemory. The curl command pipes the install script to bash, while npx runs the package directly. Both are one-liners for a zero-config setup.

```bash
curl -fsSL https://supermemory.ai/install | bash
# or
npx supermemory local
```

--------------------------------

### Basic setup for OpenClaw Supermemory

Source: https://github.com/supermemoryai/supermemory/blob/main/apps/docs/integrations/openclaw.mdx

Runs the setup command and restarts the gateway. Enter your API key from the console when prompted.

```bash
openclaw supermemory setup
openclaw gateway restart
```

--------------------------------

### Quickstart: createBash and exec

Source: https://github.com/supermemoryai/supermemory/blob/main/apps/docs/smfs/bash-tool.mdx

Initializes the bash tool with an API key and container tag, then executes a command. The result's stdout is logged.

```typescript
import { createBash } from "@supermemory/bash";

const { bash, toolDescription } = await createBash({
  apiKey: process.env.SUPERMEMORY_API_KEY!,
  containerTag: "user_42",
});

const result = await bash.exec("ls /");
console.log(result.stdout);
```

--------------------------------

### Getting all memories: Mem0 Python vs Supermemory TypeScript

Source: https://github.com/supermemoryai/supermemory/blob/main/apps/docs/migration/from-mem0.mdx

Shows how to get all memories in Mem0 using the Python client and in Supermemory using the TypeScript client. The Mem0 example uses client.get_all with user_id, while the Supermemory example uses client.list with a user ID, type, and limit.

```python
memories = client.get_all(
    user_id="alice"
)
```

```typescript
const { memories } = await client.list("user_alice", "memories", {
  limit: 100,
});
```

--------------------------------

### Install packages with pip

Source: https://github.com/supermemoryai/supermemory/blob/main/apps/docs/integrations/agno.mdx

Install the required packages: agno, supermemory, and python-dotenv.

```bash
pip install agno supermemory python-dotenv
```

--------------------------------

### Starter prompt (docs + setup)

Source: https://github.com/supermemoryai/supermemory/blob/main/apps/docs/agents-and-mcp.mdx

A prompt template for coding agents that includes canonical API endpoints, authentication, SDK usage, and migration guidance.

```APIDOC
## Starter prompt (docs + setup)

### Description
A prompt template for coding agents integrating Supermemory, covering canonical endpoints, auth, SDK usage, and migration.

### Prompt
```text
You are integrating Supermemory into my app.

- Use the supermemory-docs MCP (or https://supermemory.ai/docs/llms.txt) before inventing endpoints.
- Prefer `npx supermemory setup` / the supermemory skill for correct auth, namespace, and SDK usage.
- Canonical writes: POST /ns/{namespace}/document · search: POST /ns/{namespace}/search · profile: POST /ns/{namespace}/profile
- Auth: Authorization: Bearer $SUPERMEMORY_API_KEY only
- Always scope with one namespace in the URL path on write and search; there is no namespace field in the body
- SDK: import { Supermemory } from "supermemory"; version 5 or later; the namespace is the first argument: client.add(namespace, { content }), client.search(namespace, { query })
- For demos use dreaming: "instant" when memories must be ready right after status done
- Already on Supermemory v3/v4? Run `npx supermemory@latest migrate` instead of rewriting calls by hand
```
```

--------------------------------

### GET /ns/{namespace}

Source: https://github.com/supermemoryai/supermemory/blob/main/apps/docs/v5/api-reference/namespaces.mdx

Retrieves the context guiding a specific namespace.

```APIDOC
## GET /ns/{namespace}

### Description
Retrieves the context guiding a specific namespace.

### Method
GET

### Endpoint
/ns/{namespace}

### Parameters
#### Path Parameters
- **namespace** (string) - Required - The namespace identifier.

### Response
#### Success Response (200)
- **supportingContext** (string) - The context guiding the namespace.

#### Response Example
{
  "supportingContext": "Research project for distributed systems"
}
```

--------------------------------

### Install JavaScript SDK

Source: https://github.com/supermemoryai/supermemory/blob/main/apps/docs/integrations/supermemory-sdk.mdx

Install the Supermemory JavaScript SDK via npm.

```bash
npm install supermemory
```

--------------------------------

### Quick Start

Source: https://github.com/supermemoryai/supermemory/blob/main/packages/pipecat-sdk-python/README.md

Create a memory service and integrate it into a Pipecat pipeline.

```APIDOC
## Quick Start

```python
import os
from pipecat.pipeline.pipeline import Pipeline
from pipecat.processors.aggregators.llm_context import LLMContext
from supermemory_pipecat import SupermemoryPipecatService

# Create memory service
memory = SupermemoryPipecatService(
    api_key=os.getenv("SUPERMEMORY_API_KEY"),
    user_id="user-123",  # Required: used as container_tag
    session_id="conversation-456",  # Optional: groups memories by session
)

# Use the universal LLM context supported by current Pipecat releases.
context = LLMContext([{"role": "system", "content": "You are a helpful assistant."}])
context_aggregator = llm.create_context_aggregator(context)

# Create pipeline with memory
pipeline = Pipeline([
    transport.input(),
    stt,
    context_aggregator.user(),
    memory,  # Automatically retrieves and injects relevant memories
    llm,
    transport.output(),
    context_aggregator.assistant(),
])
```
```

--------------------------------

### Install dependencies and copy environment file

Source: https://github.com/supermemoryai/supermemory/blob/main/packages/livekit-sdk-python/examples/README.md

Install the required packages and copy the environment template. Fill in .env with LiveKit Cloud project keys and a Supermemory API key.

```bash
pip install supermemory-livekit python-dotenv
cp .env.example .env
```

--------------------------------

### TypeScript profile() example: get user profile with search

Source: https://github.com/supermemoryai/supermemory/blob/main/skills/supermemory/references/sdk-guide.md

Example of retrieving a user profile with a search query. The response includes profile.static, profile.dynamic, and searchResults (since q is provided).

```typescript
const response = await client.profile({
  containerTag: "user_123",
  q: "What are the user's preferences and settings?"
});

console.log(response.profile.static);    // ["User John Doe", "Prefers dark mode", ...]
console.log(response.profile.dynamic);   // ["Recently mentioned...", "Last conversation..."]
console.log(response.searchResults);     // Search results for the query (if provided)
```

--------------------------------

### Multi-container tag configuration example

Source: https://github.com/supermemoryai/supermemory/blob/main/apps/docs/integrations/hermes.mdx

Example supermemory.json configuration enabling custom container tags. Set enable_custom_container_tags to true, list allowed tags in custom_containers, and provide custom_container_instructions to guide the model.

```json
{
  "container_tag": "hermes",
  "enable_custom_container_tags": true,
  "custom_containers": ["work", "personal", "shared-knowledge"],
  "custom_container_instructions": "Use work for job and coding context, personal for life and hobbies, shared-knowledge for facts that apply across both."
}
```

--------------------------------

### First boot output

Source: https://github.com/supermemoryai/supermemory/blob/main/apps/docs/self-hosting/quickstart.mdx

Example output after first boot. Shows the server URL (http://localhost:6767), encrypted local storage (~/.supermemory), local embeddings (Xenova/bge-base-en-v1.5, 768d), workflow (rivet), API key, org ID, and boot time. Every request needs the API key as a bearer token.

```text
╭───────────────────────────────────────────────────────────────╮
│  → supermemory ready                                          │
│                                                               │
│    url         http://localhost:6767                          │
│    database    encrypted local storage (~/.supermemory)       │
│    embeddings  local · Xenova/bge-base-en-v1.5 · 768d         │
│    workflow    rivet                                          │
│    api key     sm_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx              │
│    org id      xxxxxxxxxxxxxxxxxxxxxx                         │
│    boot        4.2s                                           │
╰───────────────────────────────────────────────────────────────╯
  every request needs this key: Authorization: Bearer <api key>
```

--------------------------------

### Install Supermemory SDK and set API key

Source: https://github.com/supermemoryai/supermemory/blob/main/apps/docs/install.md

Install the supermemory npm or pip package, optionally the Vercel AI SDK tools package, and set the SUPERMEMORY_API_KEY environment variable. Get the API key from the Supermemory console.

```bash
# Get API key: https://console.supermemory.ai
npm install supermemory  # or: pip install supermemory
# For Vercel AI SDK: npm install @supermemory/tools
export SUPERMEMORY_API_KEY="sm_..."
```

--------------------------------

### Supermemory Python quickstart

Source: https://github.com/supermemoryai/supermemory/blob/main/README.md

Initialize the Supermemory client, store a conversation, and retrieve a user profile with relevant memories in one call.

```python
from supermemory import Supermemory

client = Supermemory()

client.add(
    content="User loves TypeScript and prefers functional patterns",
    container_tag="user_123"
)

result = client.profile(container_tag="user_123", q="programming style")

print(result.profile.static)   # Long-term facts
print(result.profile.dynamic)  # Recent context
```

--------------------------------

### Run the Development Server

Source: https://github.com/supermemoryai/supermemory/blob/main/packages/tools/test/chatapp/README.md

Start the Next.js development server with npm run dev.

```bash
npm run dev
```

--------------------------------

### GET /organization

Source: https://github.com/supermemoryai/supermemory/blob/main/apps/docs/snippets/api-v5-organization.mdx

Reads the organization-wide context used to guide memory formation. Returns the organizational context and the total namespace count.

```APIDOC
## GET /organization

### Description
Reads the organization-wide context used to guide memory formation. Returns the organizational context and the total namespace count.

### Method
GET

### Endpoint
/organization

### Response
#### Success Response (200)
- **organizationalContext** (string) - The organization-wide context used to guide memory formation.
- **namespaceCount** (integer) - The total number of namespaces in the organization. Informational and cannot be changed through PATCH.

#### Response Example
{
  "organizationalContext": "Acme builds security tools for enterprises",
  "namespaceCount": 42
}
```

--------------------------------

### Read bucket definitions response

Source: https://github.com/supermemoryai/supermemory/blob/main/apps/docs/snippets/api-v5-profiles.mdx

Example JSON response for the v5 bucket definitions GET request. The response is a map of bucket names to descriptions.

```json
{"buckets":{"work":"Professional preferences and ongoing work"}}
```

--------------------------------

### Get meter events with curl

Source: https://github.com/supermemoryai/supermemory/blob/main/apps/docs/overview/billing.mdx

Retrieves meter events by day and feature. Optionally override the billing period with start and end query parameters.

```bash
curl -s "https://api.supermemory.ai/v3/auth/billing/usage-events" \
  -H "Authorization: Bearer $SUPERMEMORY_API_KEY"
```

--------------------------------

### Install with async HTTP support

Source: https://github.com/supermemoryai/supermemory/blob/main/packages/openai-sdk-python/README.md

Install the package with async HTTP support, recommended for async usage.

```bash
uv add supermemory-openai-sdk[async]
# or
pip install 'supermemory-openai-sdk[async]'
```

--------------------------------

### Response with Picker URL

Source: https://github.com/supermemoryai/supermemory/blob/main/apps/docs/connectors/managing-resources.mdx

Example JSON response from the GET endpoint with include=picker. Shows capabilities, selection, and picker fields. The picker URL is one-time and expires.

```json
{
  "id": "PTzGiUYei7pgzg5buzZHgA",
  "provider": "github",
  "namespace": "user-123",
  "capabilities": { "selectable": true, "webhooks": true },
  "selection": {
    "repos": [
      { "id": "123456789", "name": "your-org/documentation" }
    ]
  },
  "picker": {
    "url": "https://...",
    "expiresAt": "2024-01-15T11:30:00.000Z"
  }
}
```

--------------------------------

### Set up Environment Variables

Source: https://github.com/supermemoryai/supermemory/blob/main/packages/tools/test/chatapp/README.md

Create a .env.local file with your OpenAI and Supermemory API keys.

```env
OPENAI_API_KEY=your_openai_api_key_here
SUPERMEMORY_API_KEY=your_supermemory_api_key_here
```

--------------------------------

### Hybrid search with searchMode: "hybrid"

Source: https://github.com/supermemoryai/supermemory/blob/main/apps/docs/concepts/super-rag.mdx

Example of using supermemory.search with searchMode: "hybrid" to get both RAG results and memory-based personalization.

```typescript
const results = await supermemory.search("user_123", {
  query: "how do I deploy the app?",
  searchMode: "hybrid",
});

// Returns:
// - Deployment docs from your knowledge base (RAG)
// - User's previous deployment preferences (Memory)
// - Their specific environment configs (Memory)
```

--------------------------------

### Build and start for production smoke check

Source: https://github.com/supermemoryai/supermemory/blob/main/apps/sdk-playground/README.md

Builds the Next.js app and then starts both the built Next.js app and the Python server. Intended for local use only.

```bash
bun run --cwd apps/sdk-playground build
bun run --cwd apps/sdk-playground start
```

--------------------------------

### Development setup and testing commands

Source: https://github.com/supermemoryai/supermemory/blob/main/packages/agent-framework-python/README.md

Commands to set up the development environment, run tests, perform type checking, and format code for the Supermemory Agent Framework Python package.

```bash
# Setup
cd packages/agent-framework-python
uv sync --dev

# Run tests
uv run pytest

# Type checking
uv run mypy src/supermemory_agent_framework

# Formatting
uv run black src/ tests/
uv run isort src/ tests/
uv run flake8 src/ tests/ --ignore=E501,W503,E704
```

--------------------------------

### GET /v3/auth/billing/usage-events

Source: https://github.com/supermemoryai/supermemory/blob/main/apps/docs/overview/billing.mdx

Retrieves meter events aggregated by day and feature, including memory and superrag totals, with optional start and end date parameters to override the billing period.

```APIDOC
## GET /v3/auth/billing/usage-events

### Description
Retrieves meter events aggregated by day and feature, including memory and superrag totals, with optional start and end date parameters to override the billing period.

### Method
GET

### Endpoint
https://api.supermemory.ai/v3/auth/billing/usage-events

### Authentication
Authorization: Bearer YOUR_API_KEY

### Query Parameters
- **start** (string) - Optional - ISO start date to override the billing period.
- **end** (string) - Optional - ISO end date to override the billing period.

### Request Example
```bash
curl -s "https://api.supermemory.ai/v3/auth/billing/usage-events" \
  -H "Authorization: Bearer $SUPERMEMORY_API_KEY"
```

### Response
#### Success Response (200)
- **byFeature** (object) - Usage aggregated by feature.
- **byDay** (object) - Usage aggregated by day.
- **memoryTotal** (number) - Total memory usage.
- **superragTotal** (number) - Total superrag usage.
- **period** (object) - Billing period start and end.
```

--------------------------------

### Run the playground in development mode

Source: https://github.com/supermemoryai/supermemory/blob/main/apps/sdk-playground/README.md

Starts the development server. Opens the Chat UI at https://sdk.dev.supermemory.ai via Portless, the Next.js server at http://127.0.0.1:3005, and the Python server at http://127.0.0.1:8792.

```bash
bun run --cwd apps/sdk-playground dev
```

--------------------------------

### View command examples

Source: https://github.com/supermemoryai/supermemory/blob/main/apps/docs/integrations/claude-memory.mdx

The view command lists directory contents, reads file contents, or reads specific lines using view_range. Paths must start with /memories/.

```typescript
// List directory contents
{ command: "view", path: "/memories/" }

// Read file contents
{ command: "view", path: "/memories/preferences.txt" }

// Read specific lines
{ command: "view", path: "/memories/notes.txt", view_range: [1, 10] }
```

--------------------------------

### Start the Supermemory server

Source: https://github.com/supermemoryai/supermemory/blob/main/README.md

Run the server binary. On first boot, it sets up the embedded graph engine, local embeddings, and credentials, then prints an API key. The full Memory API is available at http://localhost:6767.

```bash
supermemory-server
```

--------------------------------

### Supporting Context Example

Source: https://github.com/supermemoryai/supermemory/blob/main/apps/docs/ingestion/add-memories.mdx

Demonstrates how to guide memory extraction for a namespace using the supportingContext parameter. It persists on the namespace and combines with org-level organizational context. Max 1500 characters.

```typescript
// Guide memory extraction for this namespace
await supermemory.add("session_abc123", {
  content: "...",
  supportingContext: `Design exploration conversation between john@acme.com and Brand.ai assistant.
    Focus on John's design preferences and brand requirements.`,
});
```

--------------------------------

### Install @supermemory/memory-graph with npm, bun, or pnpm

Source: https://github.com/supermemoryai/supermemory/blob/main/packages/memory-graph/README.md

Install the package using your preferred package manager. Choose one of the three commands.

```bash
npm install @supermemory/memory-graph
# or
bun add @supermemory/memory-graph
# or
pnpm add @supermemory/memory-graph
```

--------------------------------

### Python: Run common operations for search, profiles, documents, memories, namespaces, and connectors

Source: https://github.com/supermemoryai/supermemory/blob/main/apps/docs/integrations/supermemory-sdk.mdx

Perform common operations: search chunks with filters, manage profile buckets, list/get/update/batch add/upload/delete documents, forget memories with preview, manage namespaces and organization, and create/get/sync/delete connectors. Note the connector setup requires sending the user to setup.authorization.url before expiry.

```python
import json

# Search document chunks with a filter
results = client.search(
    "user_123",
    query="design document",
    search_mode="chunks",
    filter={"field": "category", "operator": "eq", "value": "engineering"},
)

# Profile buckets
client.profiles.set_buckets("user_123", buckets={"work": "Job, team, and current projects"})
buckets = client.profiles.get_buckets("user_123")
client.profiles.delete_buckets("user_123", buckets=["work"])

# List documents
page = client.list("user_123", "documents", page=1, limit=20, sort="createdAt", order="desc")
print(page.pagination.total_pages)

# Get, update, batch add, upload
doc = client.documents.get("user_123", "meeting-q1", include=["chunks", "memories"])
client.documents.update("user_123", "meeting-q1", metadata={"priority": "low"})
client.documents.batch_add(
    "user_123",
    documents=[{"content": "First note"}, {"content": "Second note"}],
)
with open("notes.pdf", "rb") as f:
    client.documents.upload_file("user_123", file=f, metadata=json.dumps({"source": "upload"}))

# Delete documents
result = client.documents.delete("user_123", ids=["meeting-q1"])

# Forget memories: preview, then apply
preview = client.memories.forget_matching("user_123", query="old office address", dry_run=True)
client.memories.forget("user_123", ids=[m.id for m in preview.matches])

# Namespaces and organization
page = client.namespaces.list()  # page.namespaces, page.pagination
ns = client.namespaces.get("user_123")
client.namespaces.update("user_123", supporting_context="A paying customer on the Pro plan")
client.namespaces.delete("user_123", move_to="archive")  # optional, moves content instead of deleting it
client.organization.update(organizational_context="Acme sells billing software to dental clinics")

# Connectors
setup = client.connectors.create(
    "user_123",
    request={"provider": "notion", "redirectUrl": "https://app.example.com/connected"},
)
# send the user to setup.authorization.url before setup.authorization.expires_at
connector = client.connectors.get("user_123", setup.id, include=["syncs", "picker"])
client.connectors.sync("user_123", setup.id)
client.connectors.delete("user_123", setup.id, delete_documents=True)
```

--------------------------------

### List and update namespaces with TypeScript and curl

Source: https://github.com/supermemoryai/supermemory/blob/main/apps/docs/v5/api-reference/namespaces.mdx

Shows how to list namespaces and update a namespace's supporting context using the Supermemory SDK (TypeScript) and the REST API (curl). The TypeScript example uses `supermemory.namespaces.list()` and `supermemory.namespaces.update()`. The curl example uses `GET /namespaces` and `PATCH /ns/{namespace}` with an Authorization header.

```TypeScript
const { namespaces } = await supermemory.namespaces.list()

await supermemory.namespaces.update("project_alpha", {
  supportingContext: "Research project for distributed systems",
})
```

```bash
curl "https://api.supermemory.ai/namespaces" \
  -H "Authorization: Bearer $SUPERMEMORY_API_KEY"

curl -X PATCH "https://api.supermemory.ai/ns/project_alpha" \
  -H "Authorization: Bearer $SUPERMEMORY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"supportingContext":"Research project for distributed systems"}'
```

--------------------------------

### Full integration prompt for Supermemory

Source: https://github.com/supermemoryai/supermemory/blob/main/apps/docs/agents-and-mcp.mdx

Optional prompt to paste when the skill is not installed, guiding the agent to use the canonical API surface, avoid deprecated endpoints, and follow scoping rules.

```markdown
You are integrating Supermemory into my application. Supermemory provides user memory, semantic search, and automatic knowledge extraction for AI applications.

Note: You can always reference the documentation by using the **supermemory-docs MCP** or content on **supermemory.ai/docs**. Prefer `npx supermemory setup` / `npx supermemory help --json` when scaffolding.

CANONICAL API SURFACE (use these, nothing else):

- Auth header: `Authorization: Bearer $SUPERMEMORY_API_KEY` — the only supported auth header
- Write content:     POST https://api.supermemory.ai/ns/{namespace}/document
- Search:            POST https://api.supermemory.ai/ns/{namespace}/search
- Profile:           POST https://api.supermemory.ai/ns/{namespace}/profile
- Org settings:      PATCH https://api.supermemory.ai/organization
- Scoping:           one `namespace` in the URL path — never in the body or a header
- SDK:               `import { Supermemory } from "supermemory"`; `supermemory.add(namespace, { content, id?, metadata? })`, `supermemory.search(namespace, { query })`, `supermemory.profile(namespace)`

DO NOT USE — deprecated, undocumented, or fabricated:

- Endpoints:  /v1/anything, /v3/documents, /v3/search, /v4/search, /v4/profile, /v4/memories   (use /ns/{namespace}/...)
- Headers:    x-supermemory-api-key, x-api-key, x-sm-user-id (for API auth)
- Body keys:  containerTag, containerTags, customId (use `id`), entityContext (use `supportingContext`), filterByMetadata (use `group`), documentDate (use `date`), q (use `query`), filters (use `filter`), userId, spaces
- SDK:        `client.add({ containerTag })`, `client.search.execute`, `client.memories.add` / `client.memories.updateMemory`, `client.profile({ q })`

SCOPING IS LOAD-BEARING. Every write and every search MUST name one namespace in the path.

Prefer for tutorials:
- Ingest conversations with a stable `id` + dreaming: "instant" when you need memories immediately
- Wait until document system.status is done before search
- search with searchMode: "chunks" for RAG, searchMode: "memories" (+ include.related) for the graph, profile for always-on context

STEP 1: Ask what I'm building, integration style (AI SDK / OpenAI / Direct SDK / API), data model (user/org/both), profiles yes/no.
STEP 2: Install supermemory (npm/pip), set SUPERMEMORY_API_KEY from https://console.supermemory.ai
STEP 3: Generate complete working code.

DOCS: https://supermemory.ai/docs
```

--------------------------------

### Install Supermemory Agent Framework adapter with uv

Source: https://github.com/supermemoryai/supermemory/blob/main/apps/docs/integrations/agent-framework.mdx

Alternative installation using uv. Same version constraints as pip.

```bash
uv add "supermemory-agent-framework>=2.0.0,<3" agent-framework-openai
```

--------------------------------

### Hybrid search with searchMode 'hybrid'

Source: https://github.com/supermemoryai/supermemory/blob/main/apps/docs/quickstart.mdx

Omit searchMode or set it to 'hybrid' (the default) to get extracted memories and document chunks together. This example uses the same query with searchMode 'hybrid' and limit 5.

```TypeScript
await supermemory.search(user, {
  query: "gift ideas for a VP promotion after a Tokyo offsite",
  searchMode: "hybrid",
  limit: 5,
});
```

--------------------------------

### Global settings example

Source: https://github.com/supermemoryai/supermemory/blob/main/apps/docs/integrations/muse-code.mdx

Global settings file at ~/.supermemory-muse/settings.json. 'maxProfileItems' controls max profile facts injected at session start (default: 5). 'debug' logs hook activity to stderr.

```json
{
  "maxProfileItems": 5,
  "debug": false
}
```

--------------------------------

### Install OpenCode-Supermemory plugin

Source: https://github.com/supermemoryai/supermemory/blob/main/apps/docs/integrations/opencode.mdx

Installs the plugin using bunx. Use the --no-tui flag for non-interactive environments like LLM agents.

```bash
bunx opencode-supermemory@latest install
```

```bash
bunx opencode-supermemory@latest install --no-tui
```

--------------------------------

### Install Supermemory with bunx

Source: https://github.com/supermemoryai/supermemory/blob/main/apps/docs/self-hosting/quickstart.mdx

Alternative installation method using bunx to run the local command.

```bash
bunx supermemory local
```
Tokens:
Raw