Supermemory OpenAI Python SDK

Memory tools and middleware for OpenAI with Supermemory integration.

This package provides both automatic memory injection middleware and manual memory 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

For async HTTP support (recommended):

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

Quick Start

Automatic Memory Injection (Recommended)

The easiest way to add memory capabilities to your OpenAI client is using the with_supermemory() wrapper:

import asyncio
from openai import AsyncOpenAI
from supermemory_openai import with_supermemory, OpenAIMiddlewareOptions

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

    # Wrap with Supermemory middleware
    openai_with_memory = with_supermemory(
        openai,
        OpenAIMiddlewareOptions(
            container_tag="user-123",  # Required: unique identifier for user's memories
            custom_id="chat-123",      # Required: groups messages into documents
            mode="full",               # "profile", "query", or "full"
            verbose=True,              # Enable logging
            add_memory="always",       # Automatically save conversations (default)
            api_key="your-supermemory-api-key",  # Or use SUPERMEMORY_API_KEY
            # base_url="https://api.supermemory.ai",  # Optional custom endpoint
        )
    )

    # Use normally - memories are automatically injected!
    response = await openai_with_memory.chat.completions.create(
        model="gpt-4",
        messages=[
            {"role": "user", "content": "What's my favorite programming language?"}
        ]
    )

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

asyncio.run(main())

Using Memory Tools with OpenAI

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

Sync Client Support

The middleware also works with synchronous OpenAI clients:

from openai import OpenAI
from supermemory_openai import with_supermemory

# Sync client
openai = OpenAI(api_key="your-openai-api-key")
openai_with_memory = with_supermemory(
    openai,
    OpenAIMiddlewareOptions(
        container_tag="user-123",
        custom_id="session-456"
    )
)

# Works the same way
response = openai_with_memory.chat.completions.create(
    model="gpt-4",
    messages=[{"role": "user", "content": "Hello!"}]
)

Event Loop Management: The middleware properly handles event loops using asyncio.run() for sync clients. If called from within an existing async context, it automatically runs in a separate thread to avoid conflicts.

Background Task Management: When add_memory="always", memory storage happens in background tasks. Use context managers or manual cleanup to ensure tasks complete:

from supermemory_openai import with_supermemory, OpenAIMiddlewareOptions

# Async context manager (recommended)
async with with_supermemory(
    openai,
    OpenAIMiddlewareOptions(container_tag="user-123", custom_id="session-456")
) as client:
    response = await client.chat.completions.create(...)
# Background tasks automatically waited for on exit

# Manual cleanup
client = with_supermemory(
    openai,
    OpenAIMiddlewareOptions(container_tag="user-123", custom_id="session-456")
)
response = await client.chat.completions.create(...)
await client.wait_for_background_tasks()  # Ensure memory is saved

Middleware Configuration

Memory Modes

The middleware supports three different modes for memory injection:

"profile" mode (default)

Injects all static and dynamic profile memories into every request. Best for maintaining consistent user context.

openai_with_memory = with_supermemory(
    openai,
    OpenAIMiddlewareOptions(container_tag="user-123", custom_id="session-456", mode="profile")
)

"query" mode

Only searches for memories relevant to the current user message. More efficient for large memory stores.

openai_with_memory = with_supermemory(
    openai,
    OpenAIMiddlewareOptions(container_tag="user-123", custom_id="session-456", mode="query")
)

"full" mode

Combines both profile and query modes - includes all profile memories plus relevant search results.

openai_with_memory = with_supermemory(
    openai,
    OpenAIMiddlewareOptions(container_tag="user-123", custom_id="session-456", mode="full")
)

Memory Storage

Control when conversations are automatically saved as memories:

# Always save conversations as memories (default in v2.0.0+)
OpenAIMiddlewareOptions(container_tag="user-123", custom_id="session-456", add_memory="always")

# Never save conversations
OpenAIMiddlewareOptions(container_tag="user-123", custom_id="session-456", add_memory="never")

Complete Configuration Example

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

Manual Memory Tools

SupermemoryTools exposes seven OpenAI function-calling tools:

• search_memories and add_memory
• get_profile
• document_list, document_add, and document_delete
• memory_forget

The configured project_id or container_tags define the trusted scope. The primary tag is used for profile, list, search, and forget operations, and the model cannot select a different tag.

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
)

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

# Get the configured user's profile
result = await tools.get_profile(query="favorite drinks")

# List, add, or delete source documents
documents = await tools.document_list(limit=10, page=1)
document = await tools.document_add(
    content="Meeting notes...",
    title="Weekly meeting"
)
deleted = await tools.document_delete(document_id="document-id-here")

# Soft-forget one extracted memory
forgotten = await tools.memory_forget(
    memory_id="memory-entry-id-here",
    reason="outdated"
)

include_full_docs is retained as a deprecated Python argument for compatibility, but v4 search returns relevant memories and chunks instead of full source documents. It is no longer exposed in the OpenAI tool schema.

Individual Tools

from supermemory_openai import (
    create_search_memories_tool,
    create_add_memory_tool,
    create_get_profile_tool,
    create_document_list_tool,
    create_document_delete_tool,
    create_document_add_tool,
    create_memory_forget_tool,
)

search_tool = create_search_memories_tool("your-api-key")
add_tool = create_add_memory_tool("your-api-key")
profile_tool = create_get_profile_tool("your-api-key")
list_tool = create_document_list_tool("your-api-key")
delete_tool = create_document_delete_tool("your-api-key")
document_add_tool = create_document_add_tool("your-api-key")
forget_tool = create_memory_forget_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

Middleware Functions

with_supermemory()

Wraps an OpenAI client with automatic memory injection middleware.

def with_supermemory(
    openai_client: Union[OpenAI, AsyncOpenAI],
    options: OpenAIMiddlewareOptions
) -> Union[OpenAI, AsyncOpenAI]

Parameters:

• openai_client: OpenAI or AsyncOpenAI client instance
• options: Configuration options (see OpenAIMiddlewareOptions)

OpenAIMiddlewareOptions

Configuration dataclass for middleware behavior.

@dataclass
class OpenAIMiddlewareOptions:
    container_tag: str                         # Required: unique identifier for memory storage
    custom_id: str                             # Required: groups messages into documents
    verbose: bool = False                      # Enable detailed logging
    mode: Literal["profile", "query", "full"] = "profile"  # Memory injection mode
    add_memory: Literal["always", "never"] = "always"      # Auto-save behavior
    api_key: Optional[str] = None               # Falls back to SUPERMEMORY_API_KEY
    base_url: Optional[str] = None              # Falls back to SUPERMEMORY_BASE_URL

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
• get_profile() - Get the configured user's profile
• document_list() - List source document metadata
• document_add() - Queue a source document for processing
• document_delete() - Delete an in-scope source document
• memory_forget() - Soft-forget one extracted memory
• execute_tool_call() - Execute individual tool call

Error Handling

The package provides specific exception types for better error handling:

from supermemory_openai import (
    with_supermemory,
    OpenAIMiddlewareOptions,
    SupermemoryConfigurationError,
    SupermemoryAPIError,
    SupermemoryNetworkError,
    SupermemoryMemoryOperationError,
)

try:
    # This will raise SupermemoryConfigurationError if API key is missing
    client = with_supermemory(
        openai_client,
        OpenAIMiddlewareOptions(container_tag="user-123", custom_id="session-456")
    )

    response = await client.chat.completions.create(
        messages=[{"role": "user", "content": "Hello"}],
        model="gpt-4"
    )
except SupermemoryConfigurationError as e:
    print(f"Configuration issue: {e}")
except SupermemoryAPIError as e:
    print(f"Supermemory API error: {e} (Status: {e.status_code})")
except SupermemoryNetworkError as e:
    print(f"Network error: {e}")
except SupermemoryMemoryOperationError as e:
    print(f"Memory operation failed: {e}")
except Exception as e:
    print(f"Unexpected error: {e}")

Exception Types

• SupermemoryError - Base class for all Supermemory exceptions
• SupermemoryConfigurationError - Missing API keys, invalid configuration
• SupermemoryAPIError - API request failures (includes status codes)
• SupermemoryNetworkError - Network connectivity issues
• SupermemoryMemoryOperationError - Memory search/add operation failures
• SupermemoryTimeoutError - Operation timeouts

All exceptions include the original error for debugging and have descriptive error messages.

Environment Variables

Set these environment variables:

• SUPERMEMORY_API_KEY - Your Supermemory API key (unless passed in middleware options)
• OPENAI_API_KEY - Your OpenAI API key (required for examples)

Optional for testing:

• MODEL_NAME - Model to use (default: "gpt-4")
• SUPERMEMORY_BASE_URL - Custom Supermemory base URL

Dependencies

Required

• openai>=1.102.0 - Official OpenAI Python SDK
• supermemory>=3.50.0 - Supermemory client
• requests>=2.25.0 - HTTP requests (fallback)

Optional

• aiohttp>=3.8.0 - Async HTTP requests (recommended for async clients)

Install with async support:

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

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