open-ai-sdk-conversation-id-update

Author: sreedharsreeram

apps/docs/integrations/openai.mdx

@@ -44,7 +44,9 @@ import { withSupermemory } from "@supermemory/tools/openai"
 const openai = new OpenAI()
 
 // Wrap client with memory - memories auto-injected into system prompts
-const client = withSupermemory(openai, "user-123", {
+const client = withSupermemory(openai, {
+  containerTag: "user-123",
+  conversationId: "conversation-456",
   mode: "full",        // "profile" | "query" | "full"
   addMemory: "always", // "always" | "never"
 })
@@ -62,21 +64,17 @@ const response = await client.chat.completions.create({
 ### Configuration Options
 
 ```typescript
-const client = withSupermemory(openai, "user-123", {
-  // Memory search mode
-  mode: "full",  // "profile" (user profile only), "query" (search only), "full" (both)
-
-  // Auto-save conversations as memories
-  addMemory: "always",  // "always" | "never"
-
-  // Group messages into conversations
-  conversationId: "conv-456",
-
-  // Enable debug logging
-  verbose: true,
-
-  // Custom API endpoint
-  baseUrl: "https://custom.api.com"
+const client = withSupermemory(openai, {
+  // Required options
+  containerTag: "user-123",       // Scopes memories to this user
+  conversationId: "conversation-456", // Groups messages into conversations
+
+  // Optional options
+  mode: "full",         // "profile" (user profile only), "query" (search only), "full" (both)
+  addMemory: "always",  // "always" | "never" - auto-save conversations as memories
+  verbose: true,        // Enable debug logging
+  apiKey: "sm_...",     // Supermemory API key (or use SUPERMEMORY_API_KEY env var)
+  baseUrl: "https://custom.api.com" // Custom API endpoint
 })
 ```
 
@@ -91,7 +89,11 @@ const client = withSupermemory(openai, "user-123", {
 ### Works with Responses API Too
 
 ```typescript
-const client = withSupermemory(openai, "user-123", { mode: "full" })
+const client = withSupermemory(openai, {
+  containerTag: "user-123",
+  conversationId: "conversation-456",
+  mode: "full",
+})
 
 // Memories injected into instructions
 const response = await client.responses.create({

packages/openai-sdk-python/README.md

@@ -44,7 +44,8 @@ async def main():
     # Wrap with Supermemory middleware
     openai_with_memory = with_supermemory(
         openai,
-        container_tag="user-123",  # Unique identifier for user's memories
+        container_tag="user-123",       # Unique identifier for user's memories
+        conversation_id="chat-session-1", # Required: groups messages into conversations
         options=OpenAIMiddlewareOptions(
             mode="full",        # "profile", "query", or "full"
             verbose=True,       # Enable logging
@@ -122,7 +123,7 @@ from supermemory_openai import with_supermemory
 
 # Sync client
 openai = OpenAI(api_key="your-openai-api-key")
-openai_with_memory = with_supermemory(openai, "user-123")
+openai_with_memory = with_supermemory(openai, "user-123", "chat-session-1")
 
 # Works the same way
 response = openai_with_memory.chat.completions.create(
@@ -137,12 +138,12 @@ response = openai_with_memory.chat.completions.create(
 
 ```python
 # Async context manager (recommended)
-async with with_supermemory(openai, "user-123") as client:
+async with with_supermemory(openai, "user-123", "chat-session-1") as client:
     response = await client.chat.completions.create(...)
 # Background tasks automatically waited for on exit
 
 # Manual cleanup
-client = with_supermemory(openai, "user-123")
+client = with_supermemory(openai, "user-123", "chat-session-1")
 response = await client.chat.completions.create(...)
 await client.wait_for_background_tasks()  # Ensure memory is saved
 ```
@@ -160,6 +161,7 @@ Injects all static and dynamic profile memories into every request. Best for mai
 openai_with_memory = with_supermemory(
     openai,
     "user-123",
+    "chat-session-1",
     OpenAIMiddlewareOptions(mode="profile")
 )
 ```
@@ -171,6 +173,7 @@ Only searches for memories relevant to the current user message. More efficient
 openai_with_memory = with_supermemory(
     openai,
     "user-123",
+    "chat-session-1",
     OpenAIMiddlewareOptions(mode="query")
 )
 ```
@@ -182,6 +185,7 @@ Combines both profile and query modes - includes all profile memories plus relev
 openai_with_memory = with_supermemory(
     openai,
     "user-123",
+    "chat-session-1",
     OpenAIMiddlewareOptions(mode="full")
 )
 ```
@@ -206,8 +210,8 @@ from supermemory_openai import with_supermemory, OpenAIMiddlewareOptions
 openai_with_memory = with_supermemory(
     openai_client,
     container_tag="user-123",
+    conversation_id="chat-session-456",
     options=OpenAIMiddlewareOptions(
-        conversation_id="chat-session-456",  # Group messages into conversations
         verbose=True,                        # Enable detailed logging
         mode="full",                         # Use both profile and query
         add_memory="always"                  # Auto-save conversations
@@ -292,13 +296,15 @@ Wraps an OpenAI client with automatic memory injection middleware.
 def with_supermemory(
     openai_client: Union[OpenAI, AsyncOpenAI],
     container_tag: str,
+    conversation_id: str,
     options: Optional[OpenAIMiddlewareOptions] = None
 ) -> Union[OpenAI, AsyncOpenAI]
 ```
 
 **Parameters:**
 - `openai_client`: OpenAI or AsyncOpenAI client instance
 - `container_tag`: Unique identifier for memory storage (e.g., user ID)
+- `conversation_id`: Required identifier for grouping messages into conversations
 - `options`: Configuration options (see `OpenAIMiddlewareOptions`)
 
 #### `OpenAIMiddlewareOptions`
@@ -308,7 +314,6 @@ Configuration dataclass for middleware behavior.
 ```python
 @dataclass
 class OpenAIMiddlewareOptions:
-    conversation_id: Optional[str] = None      # Group messages into conversations
     verbose: bool = False                      # Enable detailed logging
     mode: Literal["profile", "query", "full"] = "profile"  # Memory injection mode
     add_memory: Literal["always", "never"] = "never"       # Auto-save behavior
@@ -349,7 +354,7 @@ from supermemory_openai import (
 
 try:
     # This will raise SupermemoryConfigurationError if API key is missing
-    client = with_supermemory(openai_client, "user-123")
+    client = with_supermemory(openai_client, "user-123", "chat-session-1")
 
     response = await client.chat.completions.create(
         messages=[{"role": "user", "content": "Hello"}],

packages/openai-sdk-python/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "supermemory-openai-sdk"
-version = "1.0.2"
+version = "1.1.0"
 description = "Memory tools for OpenAI function calling with supermemory"
 readme = "README.md"
 license = "MIT"

packages/openai-sdk-python/src/supermemory_openai/middleware.py

@@ -32,7 +32,6 @@
 class OpenAIMiddlewareOptions:
     """Configuration options for OpenAI middleware."""
 
-    conversation_id: Optional[str] = None
     verbose: bool = False
     mode: Literal["profile", "query", "full"] = "profile"
     add_memory: Literal["always", "never"] = "never"
@@ -263,10 +262,12 @@ def __init__(
         self,
         openai_client: Union[OpenAI, AsyncOpenAI],
         container_tag: str,
+        conversation_id: str,
         options: Optional[OpenAIMiddlewareOptions] = None,
     ):
         self._client: Union[OpenAI, AsyncOpenAI] = openai_client
         self._container_tag: str = container_tag
+        self._conversation_id: str = conversation_id
         self._options: OpenAIMiddlewareOptions = options or OpenAIMiddlewareOptions()
         self._logger: Logger = create_logger(self._options.verbose)
 
@@ -336,12 +337,12 @@ async def _create_with_memory_async(
             if user_message and user_message.strip():
                 content = (
                     get_conversation_content(messages)
-                    if self._options.conversation_id
+                    if self._conversation_id
                     else user_message
                 )
                 custom_id = (
-                    f"conversation:{self._options.conversation_id}"
-                    if self._options.conversation_id
+                    f"conversation:{self._conversation_id}"
+                    if self._conversation_id
                     else None
                 )
 
@@ -399,7 +400,7 @@ def handle_task_exception(task_obj):
             "Starting memory search",
             {
                 "container_tag": self._container_tag,
-                "conversation_id": self._options.conversation_id,
+                "conversation_id": self._conversation_id,
                 "mode": self._options.mode,
             },
         )
@@ -430,12 +431,12 @@ def _create_with_memory_sync(
             if user_message and user_message.strip():
                 content = (
                     get_conversation_content(messages)
-                    if self._options.conversation_id
+                    if self._conversation_id
                     else user_message
                 )
                 custom_id = (
-                    f"conversation:{self._options.conversation_id}"
-                    if self._options.conversation_id
+                    f"conversation:{self._conversation_id}"
+                    if self._conversation_id
                     else None
                 )
 
@@ -483,7 +484,7 @@ def _create_with_memory_sync(
             "Starting memory search",
             {
                 "container_tag": self._container_tag,
-                "conversation_id": self._options.conversation_id,
+                "conversation_id": self._conversation_id,
                 "mode": self._options.mode,
             },
         )
@@ -615,19 +616,17 @@ def __getattr__(self, name: str) -> Any:
 def with_supermemory(
     openai_client: Union[OpenAI, AsyncOpenAI],
     container_tag: str,
+    conversation_id: str,
     options: Optional[OpenAIMiddlewareOptions] = None,
 ) -> Union[OpenAI, AsyncOpenAI]:
     """
     Wraps an OpenAI client with SuperMemory middleware to automatically inject relevant memories
     into the system prompt based on the user's message content.
 
-    This middleware searches the supermemory API for relevant memories using the container tag
-    and user message, then either appends memories to an existing system prompt or creates
-    a new system prompt with the memories.
-
     Args:
         openai_client: The OpenAI client to wrap with SuperMemory middleware
         container_tag: The container tag/identifier for memory search (e.g., user ID, project ID)
+        conversation_id: Conversation ID to group messages into a single document
         options: Optional configuration options for the middleware
 
     Returns:
@@ -638,19 +637,17 @@ def with_supermemory(
         from supermemory_openai import with_supermemory, OpenAIMiddlewareOptions
         from openai import OpenAI
 
-        # Create OpenAI client with supermemory middleware
         openai = OpenAI(api_key=os.getenv("OPENAI_API_KEY"))
         openai_with_supermemory = with_supermemory(
             openai,
             "user-123",
+            "conversation-456",
             OpenAIMiddlewareOptions(
-                conversation_id="conversation-456",
                 mode="full",
                 add_memory="always"
             )
         )
 
-        # Use normally - memories will be automatically injected
         response = await openai_with_supermemory.chat.completions.create(
             model="gpt-4",
             messages=[
@@ -663,6 +660,14 @@ def with_supermemory(
         ValueError: When SUPERMEMORY_API_KEY environment variable is not set
         Exception: When supermemory API request fails
     """
-    wrapper = SupermemoryOpenAIWrapper(openai_client, container_tag, options)
+    if not conversation_id or not conversation_id.strip():
+        raise ValueError(
+            "[supermemory] conversation_id is required and cannot be empty. "
+            "Pass a unique identifier (e.g., session ID, chat ID) as the third argument to with_supermemory(). "
+            "This ensures messages are grouped into the same document for a conversation. "
+            "Example: with_supermemory(openai_client, 'user-123', 'conversation-456')"
+        )
+
+    wrapper = SupermemoryOpenAIWrapper(openai_client, container_tag, conversation_id, options)
     # Return the wrapper, which delegates all attributes to the original client
     return cast(Union[OpenAI, AsyncOpenAI], wrapper)