supermemory/packages/openai-sdk-python

Supermemory OpenAI Python SDK

Memory tools for OpenAI function calling with Supermemory integration.

This package provides memory management tools for the official OpenAI Python SDK using Supermemory capabilities.

Installation

Install using uv (recommended):

uv add supermemory-openai-sdk

Or with pip:

pip install supermemory-openai-sdk

Quick Start

Using the withSupermemory Wrapper (Recommended)

The withSupermemory wrapper automatically injects relevant memories into your conversations without requiring manual function calls:

import asyncio
import openai
from supermemory_openai import with_supermemory, WithSupermemoryOptions

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

    # Wrap with Supermemory integration
    enhanced_client = with_supermemory(
        client,
        container_tag="user-123",  # Your user/project identifier
        options=WithSupermemoryOptions(
            conversation_id="chat-456",  # Optional: group related messages
            mode="full",  # "profile", "query", or "full"
            add_memory="always",  # "always" or "never"
            verbose=True  # Enable detailed logging
        )
    )

    # Use exactly like a normal OpenAI client - memories are injected automatically
    response = await enhanced_client.chat.completions.create(
        model="gpt-5",
        messages=[
            {"role": "user", "content": "What's my favorite programming language?"}
        ]
    )

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

asyncio.run(main())

Using Memory Tools with OpenAI (Manual Control)

For manual control over when memories are retrieved and stored:

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

Configuration

withSupermemory Wrapper Options

from supermemory_openai import with_supermemory, WithSupermemoryOptions

# Basic usage with minimal configuration
enhanced_client = with_supermemory(client, "user-123")

# Full configuration
enhanced_client = with_supermemory(
    client,
    container_tag="user-123",
    options=WithSupermemoryOptions(
        conversation_id="chat-456",  # Optional: groups messages for contextual memory
        mode="full",  # "profile" (default), "query", or "full"
        add_memory="never",  # "always" or "never" (default)
        verbose=False  # Enable detailed logging (default: False)
    )
)

Mode Options:

• "profile": Retrieves user's static and dynamic profile data only
• "query": Searches memories based on the latest user message only
• "full": Combines both profile data and query-based search results

Memory Storage:

• "always": Automatically saves conversation content to memory
• "never": No automatic memory storage (default)

Memory Tools

SupermemoryTools Class

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

# Search memories
result = await tools.search_memories(
    information_to_get="user preferences",
    limit=10,
    include_full_docs=True
)

# Add memory
result = await tools.add_memory(
    memory="User prefers tea over coffee"
)

# Fetch specific memory
result = await tools.fetch_memory(
    memory_id="memory-id-here"
)

Individual Tools

from supermemory_openai import (
    create_search_memories_tool,
    create_add_memory_tool,
    create_fetch_memory_tool
)

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

Function Calling Integration

from supermemory_openai import execute_memory_tool_calls

# After getting tool calls from OpenAI
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"}
    )

    # Add tool results to conversation
    messages.append(response.choices[0].message)
    messages.extend(tool_results)

API Reference

SupermemoryTools

Memory management tools for function calling.

Constructor

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

Methods

• get_tool_definitions() - Get OpenAI function definitions
• search_memories() - Search user memories
• add_memory() - Add new memory
• fetch_memory() - Fetch specific memory by ID
• execute_tool_call() - Execute individual tool call

Error Handling

try:
    response = await client.chat_completion(
        messages=[{"role": "user", "content": "Hello"}],
        model="gpt-5"
    )
except Exception as e:
    print(f"Error: {e}")

Environment Variables

Set these environment variables for testing:

• SUPERMEMORY_API_KEY - Your Supermemory API key
• OPENAI_API_KEY - Your OpenAI API key
• MODEL_NAME - Model to use (default: "gpt-5-nano")
• SUPERMEMORY_BASE_URL - Custom Supermemory base URL (optional)

Development

Setup

# 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

Testing

# Run tests
uv run pytest

# Run with coverage
uv run pytest --cov=supermemory_openai

# Run specific test file
uv run pytest tests/test_infinite_chat.py

Type Checking

uv run mypy src/supermemory_openai

Formatting

uv run black src/ tests/
uv run isort src/ tests/

License

MIT License - see LICENSE file for details.

Links

• Supermemory - Infinite context memory platform
• OpenAI Python SDK - Official OpenAI Python library
• Documentation - Full API documentation