OpenAI SDK

Add memory capabilities to the official OpenAI SDKs using Supermemory. Two approaches available:

withSupermemory wrapper - Automatic memory injection into system prompts (zero-config)
Function calling tools - Explicit tool calls for search/add memory operations

Migrating to v2 from 1.4.x? Check the migration guide.

New to Supermemory? Start with withSupermemory for the simplest integration. It automatically injects relevant memories into your prompts.

Supermemory tools on npm

Check out the NPM page for more details

Supermemory AI SDK

Check out the PyPI page for more details

withSupermemory Wrapper

The simplest way to add memory to your OpenAI client. Wraps your client to automatically inject relevant memories into system prompts.

Installation

npm install @supermemory/tools openai

Quick Start

import OpenAI from "openai"
import { withSupermemory } from "@supermemory/tools/openai"

const openai = new OpenAI()

// Wrap client with memory - memories auto-injected into system prompts
const client = withSupermemory(openai, {
  containerTag: "user-123",     // Required: identifies the user/container
  customId: "conversation-456", // Required: groups messages into the same document 
  mode: "full",                 // "profile" | "query" | "full"
  addMemory: "always",          // "always" (default) | "never"
})

// Use normally - memories are automatically included
const response = await client.chat.completions.create({
  model: "gpt-5",
  messages: [
    { role: "system", content: "You are a helpful assistant." },
    { role: "user", content: "What's my favorite programming language?" }
  ]
})

Configuration Options

const client = withSupermemory(openai, {
  // Required: identifies the user/container
  containerTag: "user-123",

  // Required: Group messages into the same document
  customId: "conv-456",

  // Memory search mode
  mode: "full",  // "profile" (user profile only), "query" (search only), "full" (both)

  // Auto-save conversations as memories (default: "always")
  addMemory: "always",  // "always" | "never"

  // Enable debug logging
  verbose: true,

  // Custom API endpoint
  baseUrl: "https://custom.api.com"
})

Modes Explained

Mode	Description	Use Case
`profile`	Injects user profile (static + dynamic facts)	General personalization
`query`	Searches memories based on user message	Question answering
`full`	Both profile and query-based search	Best for chatbots

Works with Responses API Too

const client = withSupermemory(openai, { containerTag: "user-123", customId: "conv-456", mode: "full" })

// Memories injected into instructions
const response = await client.responses.create({
  model: "gpt-5",
  instructions: "You are a helpful assistant.",
  input: "What do you know about me?"
})

Environment Variables

SUPERMEMORY_API_KEY=your_supermemory_key
OPENAI_API_KEY=your_openai_key

Function Calling Tools

For explicit control over memory operations, use function calling tools. The model decides when to search or add memories.

Installation

# Using uv (recommended)
uv add supermemory-openai-sdk

# Or with pip
pip install supermemory-openai-sdk

npm install @supermemory/tools

Quick Start

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())

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!, {
  projectId: "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)
  }
}

Configuration

Memory Tools Configuration

from supermemory_openai import SupermemoryTools

tools = SupermemoryTools(
    api_key="your-supermemory-api-key",
    config={
        "project_id": "my-project",  # or use container_tags
        "base_url": "https://custom-endpoint.com",  # optional
    }
)

import { supermemoryTools } from "@supermemory/tools/openai"

const tools = supermemoryTools(process.env.SUPERMEMORY_API_KEY!, {
  containerTags: ["your-user-id"],
  baseUrl: "https://custom-endpoint.com", // optional
})

Available Tools

Search Memories

Search through user memories using semantic search:

# Search memories
result = await tools.search_memories(
    information_to_get="user preferences",
    limit=10,
    include_full_docs=True
)
print(f"Found {len(result.memories)} memories")

// Search memories
const searchResult = await tools.searchMemories({
  informationToGet: "user preferences",
  limit: 10,
})
console.log(`Found ${searchResult.memories.length} memories`)

Add Memory

Store new information in memory:

# Add memory
result = await tools.add_memory(
    memory="User prefers tea over coffee"
)
print(f"Added memory with ID: {result.memory.id}")

// Add memory
const addResult = await tools.addMemory({
  memory: "User prefers dark roast coffee",
})
console.log(`Added memory with ID: ${addResult.memory.id}`)

Individual Tools

Use tools separately for more granular control:

from supermemory_openai import (
    create_search_memories_tool,
    create_add_memory_tool
)

search_tool = create_search_memories_tool("your-api-key")
add_tool = create_add_memory_tool("your-api-key")

# Use individual tools in OpenAI function calling
tools_list = [search_tool, add_tool]

import {
  createSearchMemoriesTool,
  createAddMemoryTool
} from "@supermemory/tools/openai"

const searchTool = createSearchMemoriesTool(process.env.SUPERMEMORY_API_KEY!)
const addTool = createAddMemoryTool(process.env.SUPERMEMORY_API_KEY!)

// Use individual tools
const toolDefinitions = [searchTool.definition, addTool.definition]

Complete Chat Example

Here’s a complete example showing a multi-turn conversation with memory:

import asyncio
import openai
from supermemory_openai import SupermemoryTools, execute_memory_tool_calls

async def chat_with_memory():
    client = openai.AsyncOpenAI()
    tools = SupermemoryTools(
        api_key="your-supermemory-api-key",
        config={"project_id": "chat-example"}
    )

    messages = [
        {
            "role": "system",
            "content": """You are a helpful assistant with memory capabilities.
            When users share personal information, remember it using addMemory.
            When they ask questions, search your memories to provide personalized responses."""
        }
    ]

    while True:
        user_input = input("You: ")
        if user_input.lower() == 'quit':
            break

        messages.append({"role": "user", "content": user_input})

        # Get AI response with tools
        response = await client.chat.completions.create(
            model="gpt-5",
            messages=messages,
            tools=tools.get_tool_definitions()
        )

        # Handle tool calls
        if response.choices[0].message.tool_calls:
            messages.append(response.choices[0].message)

            tool_results = await execute_memory_tool_calls(
                api_key="your-supermemory-api-key",
                tool_calls=response.choices[0].message.tool_calls,
                config={"project_id": "chat-example"}
            )

            messages.extend(tool_results)

            # Get final response after tool execution
            final_response = await client.chat.completions.create(
                model="gpt-5",
                messages=messages
            )

            assistant_message = final_response.choices[0].message.content
        else:
            assistant_message = response.choices[0].message.content
            messages.append({"role": "assistant", "content": assistant_message})

        print(f"Assistant: {assistant_message}")

# Run the chat
asyncio.run(chat_with_memory())

import OpenAI from "openai"
import { getToolDefinitions, createToolCallExecutor } from "@supermemory/tools/openai"
import readline from 'readline'

const client = new OpenAI()
const executeToolCall = createToolCallExecutor(process.env.SUPERMEMORY_API_KEY!, {
  projectId: "chat-example",
})

const rl = readline.createInterface({
  input: process.stdin,
  output: process.stdout,
})

async function chatWithMemory() {
  const messages: OpenAI.Chat.ChatCompletionMessageParam[] = [
    {
      role: "system",
      content: `You are a helpful assistant with memory capabilities.
      When users share personal information, remember it using addMemory.
      When they ask questions, search your memories to provide personalized responses.`
    }
  ]

  const askQuestion = () => {
    rl.question("You: ", async (userInput) => {
      if (userInput.toLowerCase() === 'quit') {
        rl.close()
        return
      }

      messages.push({ role: "user", content: userInput })

      // Get AI response with tools
      const response = await client.chat.completions.create({
        model: "gpt-5",
        messages,
        tools: getToolDefinitions(),
      })

      const choice = response.choices[0]
      if (choice?.message.tool_calls) {
        messages.push(choice.message)

        // Execute tool calls
        for (const toolCall of choice.message.tool_calls) {
          const result = await executeToolCall(toolCall)
          messages.push({
            role: "tool",
            tool_call_id: toolCall.id,
            content: JSON.stringify(result),
          })
        }

        // Get final response after tool execution
        const finalResponse = await client.chat.completions.create({
          model: "gpt-5",
          messages,
        })

        const assistantMessage = finalResponse.choices[0]?.message.content || "No response"
        console.log(`Assistant: ${assistantMessage}`)
        messages.push({ role: "assistant", content: assistantMessage })
      } else {
        const assistantMessage = choice?.message.content || "No response"
        console.log(`Assistant: ${assistantMessage}`)
        messages.push({ role: "assistant", content: assistantMessage })
      }

      askQuestion()
    })
  }

  console.log("Chat with memory started. Type 'quit' to exit.")
  askQuestion()
}

chatWithMemory()

Error Handling

Handle errors gracefully in your applications:

from supermemory_openai import SupermemoryTools
import openai

async def safe_chat():
    try:
        client = openai.AsyncOpenAI()
        tools = SupermemoryTools(api_key="your-api-key")

        response = await client.chat.completions.create(
            model="gpt-5",
            messages=[{"role": "user", "content": "Hello"}],
            tools=tools.get_tool_definitions()
        )

    except openai.APIError as e:
        print(f"OpenAI API error: {e}")
    except Exception as e:
        print(f"Unexpected error: {e}")

import OpenAI from "openai"
import { getToolDefinitions } from "@supermemory/tools/openai"

async function safeChat() {
  try {
    const client = new OpenAI()

    const response = await client.chat.completions.create({
      model: "gpt-5",
      messages: [{ role: "user", content: "Hello" }],
      tools: getToolDefinitions(),
    })

  } catch (error) {
    if (error instanceof OpenAI.APIError) {
      console.error("OpenAI API error:", error.message)
    } else {
      console.error("Unexpected error:", error)
    }
  }
}

API Reference

Python SDK

`SupermemoryTools`

Constructor

SupermemoryTools(
    api_key: str,
    config: Optional[SupermemoryToolsConfig] = None
)

Methods

get_tool_definitions() - Get OpenAI function definitions
search_memories(information_to_get, limit, include_full_docs) - Search user memories
add_memory(memory) - Add new memory
execute_tool_call(tool_call) - Execute individual tool call

`execute_memory_tool_calls`

execute_memory_tool_calls(
    api_key: str,
    tool_calls: List[ToolCall],
    config: Optional[SupermemoryToolsConfig] = None
) -> List[dict]

JavaScript SDK

`supermemoryTools`

supermemoryTools(
  apiKey: string,
  config?: { projectId?: string; baseUrl?: string }
)

`createToolCallExecutor`

createToolCallExecutor(
  apiKey: string,
  config?: { projectId?: string; baseUrl?: string }
) -> (toolCall: OpenAI.Chat.ChatCompletionMessageToolCall) => Promise<any>

Environment Variables

Set these environment variables:

SUPERMEMORY_API_KEY=your_supermemory_key
OPENAI_API_KEY=your_openai_key
SUPERMEMORY_BASE_URL=https://custom-endpoint.com  # optional

Development

Python Setup

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

JavaScript Setup

# Install dependencies
npm install

# Run tests
npm test

# Type checking
npm run type-check

# Linting
npm run lint

Migration Guides

Supermemory tools on npm

Supermemory AI SDK

withSupermemory Wrapper

Installation

Quick Start

Configuration Options

Modes Explained

Works with Responses API Too

Environment Variables

Function Calling Tools

Installation

Quick Start

Configuration

Memory Tools Configuration

Available Tools

Search Memories

Add Memory

Individual Tools

Complete Chat Example

Error Handling

API Reference

Python SDK

`SupermemoryTools`

`execute_memory_tool_calls`

JavaScript SDK

`supermemoryTools`

`createToolCallExecutor`

Environment Variables

Development

Python Setup

JavaScript Setup

Next Steps

AI SDK Integration

Memory API

Supermemory tools on npm

Supermemory AI SDK

​withSupermemory Wrapper

​Installation

​Quick Start

​Configuration Options

​Modes Explained

​Works with Responses API Too

​Environment Variables

​Function Calling Tools

​Installation

​Quick Start

​Configuration

​Memory Tools Configuration

​Available Tools

​Search Memories

​Add Memory

​Individual Tools

​Complete Chat Example

​Error Handling

​API Reference

​Python SDK

​SupermemoryTools

​execute_memory_tool_calls

​JavaScript SDK

​supermemoryTools

​createToolCallExecutor

​Environment Variables

​Development

​Python Setup

​JavaScript Setup

​Next Steps

AI SDK Integration

Memory API

withSupermemory Wrapper

Installation

Quick Start

Configuration Options

Modes Explained

Works with Responses API Too

Environment Variables

Function Calling Tools

Installation

Quick Start

Configuration

Memory Tools Configuration

Available Tools

Search Memories

Add Memory

Individual Tools

Complete Chat Example

Error Handling

API Reference

Python SDK

`SupermemoryTools`

`execute_memory_tool_calls`

JavaScript SDK

`supermemoryTools`

`createToolCallExecutor`

Environment Variables

Development

Python Setup

JavaScript Setup

Next Steps