refactor mastra to object-based API (v2.0.0)

apps/docs/integrations/mastra.mdx

@@ -34,11 +34,11 @@ const agent = new Agent(withSupermemory(
     model: openai("gpt-4o"),
     instructions: "You are a helpful assistant.",
   },
-  "user-123",  // containerTag - scopes memories to this user
   {
+    containerTag: "user-123",  // scopes memories to this user
+    customId: "conv-456",      // groups messages into the same document
     mode: "full",
     addMemory: "always",
-    threadId: "conv-456",
   }
 ))
 
@@ -51,10 +51,10 @@ const response = await agent.generate("What do you know about me?")
   ```typescript
   const agent = new Agent(withSupermemory(
     { id: "my-assistant", model: openai("gpt-4o"), ... },
-    "user-123",
     {
+      containerTag: "user-123",
+      customId: "conv-456",
       addMemory: "always",
-      threadId: "conv-456"  // Required for conversation grouping
     }
   ))
   ```
@@ -100,7 +100,6 @@ sequenceDiagram
 | `baseUrl` | `string` | `https://api.supermemory.ai` | Custom API endpoint |
 | `mode` | `"profile" \| "query" \| "full"` | `"profile"` | Memory search mode |
 | `addMemory` | `"always" \| "never"` | `"never"` | Auto-save conversations |
-| `threadId` | `string` | - | Conversation ID for grouping messages |
 | `verbose` | `boolean` | `false` | Enable debug logging |
 | `promptTemplate` | `function` | - | Custom memory formatting |
 
@@ -111,19 +110,19 @@ sequenceDiagram
 **Profile Mode (Default)** - Retrieves the user's complete profile without query-based filtering:
 
 ```typescript
-const agent = new Agent(withSupermemory(config, "user-123", { mode: "profile" }))
+const agent = new Agent(withSupermemory(config, { containerTag: "user-123", customId: "conv-456", mode: "profile" }))
 ```
 
 **Query Mode** - Searches memories based on the user's message:
 
 ```typescript
-const agent = new Agent(withSupermemory(config, "user-123", { mode: "query" }))
+const agent = new Agent(withSupermemory(config, { containerTag: "user-123", customId: "conv-456", mode: "query" }))
 ```
 
 **Full Mode** - Combines profile AND query-based search for maximum context:
 
 ```typescript
-const agent = new Agent(withSupermemory(config, "user-123", { mode: "full" }))
+const agent = new Agent(withSupermemory(config, { containerTag: "user-123", customId: "conv-456", mode: "full" }))
 
 ### Mode Comparison
 
@@ -137,15 +136,15 @@ const agent = new Agent(withSupermemory(config, "user-123", { mode: "full" }))
 
 ## Saving Conversations
 
-Enable automatic conversation saving with `addMemory: "always"`. A `threadId` is required to group messages:
+Enable automatic conversation saving with `addMemory: "always"`. The `customId` parameter groups messages into the same document:
 
 ```typescript
 const agent = new Agent(withSupermemory(
   { id: "my-assistant", model: openai("gpt-4o"), instructions: "..." },
-  "user-123",
   {
+    containerTag: "user-123",
+    customId: "conv-456",
     addMemory: "always",
-    threadId: "conv-456",
   }
 ))
 
@@ -154,10 +153,6 @@ await agent.generate("I prefer TypeScript over JavaScript")
 await agent.generate("My favorite framework is Next.js")
 ```
 
-<Warning>
-  Without a `threadId`, the output processor will log a warning and skip saving. Always provide a `threadId` when using `addMemory: "always"`.
-</Warning>
-
 ---
 
 ## Custom Prompt Templates
@@ -182,8 +177,9 @@ const claudePrompt = (data: MemoryPromptData) => `
 
 const agent = new Agent(withSupermemory(
   { id: "my-assistant", model: openai("gpt-4o"), instructions: "..." },
-  "user-123",
   {
+    containerTag: "user-123",
+    customId: "conv-456",
     mode: "full",
     promptTemplate: claudePrompt,
   }
@@ -210,7 +206,9 @@ const agent = new Agent({
   name: "My Assistant",
   model: openai("gpt-4o"),
   inputProcessors: [
-    createSupermemoryProcessor("user-123", {
+    createSupermemoryProcessor({
+      containerTag: "user-123",
+      customId: "conv-456",
       mode: "full",
       verbose: true,
     }),
@@ -232,9 +230,10 @@ const agent = new Agent({
   name: "My Assistant",
   model: openai("gpt-4o"),
   outputProcessors: [
-    createSupermemoryOutputProcessor("user-123", {
+    createSupermemoryOutputProcessor({
+      containerTag: "user-123",
+      customId: "conv-456",
       addMemory: "always",
-      threadId: "conv-456",
     }),
   ],
 })
@@ -249,10 +248,11 @@ import { Agent } from "@mastra/core/agent"
 import { createSupermemoryProcessors } from "@supermemory/tools/mastra"
 import { openai } from "@ai-sdk/openai"
 
-const { input, output } = createSupermemoryProcessors("user-123", {
+const { input, output } = createSupermemoryProcessors({
+  containerTag: "user-123",
+  customId: "conv-456",
   mode: "full",
   addMemory: "always",
-  threadId: "conv-456",
   verbose: true,
 })
 
@@ -269,7 +269,7 @@ const agent = new Agent({
 
 ## Using RequestContext
 
-Mastra's `RequestContext` can provide `threadId` dynamically:
+Mastra's `RequestContext` can provide a dynamic custom ID override:
 
 ```typescript
 import { Agent } from "@mastra/core/agent"
@@ -279,15 +279,15 @@ import { openai } from "@ai-sdk/openai"
 
 const agent = new Agent(withSupermemory(
   { id: "my-assistant", model: openai("gpt-4o"), instructions: "..." },
-  "user-123",
   {
+    containerTag: "user-123",
+    customId: "default-conv-id",
     mode: "full",
     addMemory: "always",
-    // threadId not set - will use RequestContext
   }
 ))
 
-// Set threadId dynamically via RequestContext
+// Override customId dynamically via RequestContext
 const ctx = new RequestContext()
 ctx.set(MASTRA_THREAD_ID_KEY, "dynamic-thread-id")
 
@@ -303,8 +303,11 @@ Enable detailed logging for debugging:
 ```typescript
 const agent = new Agent(withSupermemory(
   { id: "my-assistant", model: openai("gpt-4o"), instructions: "..." },
-  "user-123",
-  { verbose: true }
+  {
+    containerTag: "user-123",
+    customId: "conv-456",
+    verbose: true,
+  }
 ))
 
 // Console output:
@@ -330,7 +333,10 @@ const agent = new Agent(withSupermemory(
     inputProcessors: [myLoggingProcessor],
     outputProcessors: [myAnalyticsProcessor],
   },
-  "user-123"
+  {
+    containerTag: "user-123",
+    customId: "conv-456",
+  }
 ))
 ```
 
@@ -345,15 +351,13 @@ Enhances a Mastra agent config with memory capabilities.
 ```typescript
 function withSupermemory<T extends AgentConfig>(
   config: T,
-  containerTag: string,
-  options?: SupermemoryMastraOptions
+  options: SupermemoryMastraOptions
 ): T
 ```
 
 **Parameters:**
 - `config` - The Mastra agent configuration object
-- `containerTag` - User/container ID for scoping memories
-- `options` - Configuration options
+- `options` - Configuration options including `containerTag` and `customId`
 
 **Returns:** Enhanced config with Supermemory processors injected
 
@@ -363,8 +367,7 @@ Creates an input processor for memory injection.
 
 ```typescript
 function createSupermemoryProcessor(
-  containerTag: string,
-  options?: SupermemoryMastraOptions
+  options: SupermemoryMastraOptions
 ): SupermemoryInputProcessor
 ```
 
@@ -374,8 +377,7 @@ Creates an output processor for conversation saving.
 
 ```typescript
 function createSupermemoryOutputProcessor(
-  containerTag: string,
-  options?: SupermemoryMastraOptions
+  options: SupermemoryMastraOptions
 ): SupermemoryOutputProcessor
 ```
 
@@ -385,8 +387,7 @@ Creates both processors with shared configuration.
 
 ```typescript
 function createSupermemoryProcessors(
-  containerTag: string,
-  options?: SupermemoryMastraOptions
+  options: SupermemoryMastraOptions
 ): {
   input: SupermemoryInputProcessor
   output: SupermemoryOutputProcessor
@@ -397,11 +398,12 @@ function createSupermemoryProcessors(
 
 ```typescript
 interface SupermemoryMastraOptions {
+  containerTag: string           // User/container ID for scoping memories
+  customId: string               // Custom ID to group messages into the same document
   apiKey?: string
   baseUrl?: string
   mode?: "profile" | "query" | "full"
   addMemory?: "always" | "never"
-  threadId?: string
   verbose?: boolean
   promptTemplate?: (data: MemoryPromptData) => string
 }
@@ -423,14 +425,17 @@ Processors gracefully handle errors without breaking the agent:
 
 - **API errors** - Logged and skipped; agent continues without memories
 - **Missing API key** - Throws immediately with helpful error message
-- **Missing threadId** - Warns in console; skips saving
+- **Empty customId** - Throws immediately with helpful `[supermemory]`-prefixed error message
 
 ```typescript
 // Missing API key throws immediately
 const agent = new Agent(withSupermemory(
   { id: "my-assistant", model: openai("gpt-4o"), instructions: "..." },
-  "user-123",
-  { apiKey: undefined } // Will check SUPERMEMORY_API_KEY env
+  {
+    containerTag: "user-123",
+    customId: "conv-456",
+    apiKey: undefined, // Will check SUPERMEMORY_API_KEY env
+  }
 ))
 // Error: SUPERMEMORY_API_KEY is not set
 ```