@@ -34,9 +34,9 @@ const agent = new Agent(withSupermemory(
3434 model: openai (" gpt-4o" ),
3535 instructions: " You are a helpful assistant." ,
3636 },
37- " user-123" , // containerTag - scopes memories to this user
38- " conv-456" , // conversationId - groups messages into the same document
3937 {
38+ containerTag: " user-123" , // scopes memories to this user
39+ customId: " conv-456" , // groups messages into the same document
4040 mode: " full" ,
4141 addMemory: " always" ,
4242 }
@@ -51,9 +51,11 @@ const response = await agent.generate("What do you know about me?")
5151 ``` typescript
5252 const agent = new Agent (withSupermemory (
5353 { id: " my-assistant" , model: openai (" gpt-4o" ), ... },
54- " user-123" ,
55- " conv-456" ,
56- { addMemory: " always" }
54+ {
55+ containerTag: " user-123" ,
56+ customId: " conv-456" ,
57+ addMemory: " always" ,
58+ }
5759 ))
5860 ```
5961</Note >
@@ -108,19 +110,19 @@ sequenceDiagram
108110** Profile Mode (Default)** - Retrieves the user's complete profile without query-based filtering:
109111
110112``` typescript
111- const agent = new Agent (withSupermemory (config , " user-123" , " conv-456" , { mode: " profile" }))
113+ const agent = new Agent (withSupermemory (config , { containerTag: " user-123" , customId: " conv-456" , mode: " profile" }))
112114```
113115
114116** Query Mode** - Searches memories based on the user's message:
115117
116118``` typescript
117- const agent = new Agent (withSupermemory (config , " user-123" , " conv-456" , { mode: " query" }))
119+ const agent = new Agent (withSupermemory (config , { containerTag: " user-123" , customId: " conv-456" , mode: " query" }))
118120```
119121
120122** Full Mode** - Combines profile AND query-based search for maximum context:
121123
122124``` typescript
123- const agent = new Agent (withSupermemory (config , " user-123" , " conv-456" , { mode: " full" }))
125+ const agent = new Agent (withSupermemory (config , { containerTag: " user-123" , customId: " conv-456" , mode: " full" }))
124126
125127### Mode Comparison
126128
@@ -134,14 +136,16 @@ const agent = new Agent(withSupermemory(config, "user-123", "conv-456", { mode:
134136
135137## Saving Conversations
136138
137- Enable automatic conversation saving with ` addMemory: "always" ` . The ` conversationId ` parameter groups messages into the same document :
139+ Enable automatic conversation saving with ` addMemory: "always" ` . The ` customId ` parameter groups messages into the same document :
138140
139141` ` ` typescript
140142const agent = new Agent(withSupermemory(
141143 { id: "my-assistant", model: openai("gpt-4o"), instructions: "..." },
142- "user-123",
143- "conv-456",
144- { addMemory: "always" }
144+ {
145+ containerTag: "user-123",
146+ customId: "conv-456",
147+ addMemory: "always",
148+ }
145149))
146150
147151// All messages in this conversation are saved
@@ -173,9 +177,9 @@ const claudePrompt = (data: MemoryPromptData) => `
173177
174178const agent = new Agent(withSupermemory(
175179 { id: "my-assistant", model: openai("gpt-4o"), instructions: "..." },
176- "user-123",
177- "conv-456",
178180 {
181+ containerTag: "user-123",
182+ customId: "conv-456",
179183 mode: "full",
180184 promptTemplate: claudePrompt,
181185 }
@@ -202,7 +206,9 @@ const agent = new Agent({
202206 name: "My Assistant",
203207 model: openai("gpt-4o"),
204208 inputProcessors: [
205- createSupermemoryProcessor("user-123", "conv-456", {
209+ createSupermemoryProcessor({
210+ containerTag: "user-123",
211+ customId: "conv-456",
206212 mode: "full",
207213 verbose: true,
208214 }),
@@ -224,7 +230,9 @@ const agent = new Agent({
224230 name: "My Assistant",
225231 model: openai("gpt-4o"),
226232 outputProcessors: [
227- createSupermemoryOutputProcessor("user-123", "conv-456", {
233+ createSupermemoryOutputProcessor({
234+ containerTag: "user-123",
235+ customId: "conv-456",
228236 addMemory: "always",
229237 }),
230238 ],
@@ -240,7 +248,9 @@ import { Agent } from "@mastra/core/agent"
240248import { createSupermemoryProcessors } from "@supermemory/tools/mastra"
241249import { openai } from "@ai-sdk/openai"
242250
243- const { input, output } = createSupermemoryProcessors("user-123", "conv-456", {
251+ const { input, output } = createSupermemoryProcessors({
252+ containerTag: "user-123",
253+ customId: "conv-456",
244254 mode: "full",
245255 addMemory: "always",
246256 verbose: true,
@@ -259,7 +269,7 @@ const agent = new Agent({
259269
260270## Using RequestContext
261271
262- Mastra ' s `RequestContext` can provide a dynamic conversation ID override:
272+ Mastra ' s `RequestContext` can provide a dynamic custom ID override:
263273
264274` ` ` typescript
265275import { Agent } from "@mastra/core/agent"
@@ -269,15 +279,15 @@ import { openai } from "@ai-sdk/openai"
269279
270280const agent = new Agent(withSupermemory(
271281 { id: "my-assistant", model: openai("gpt-4o"), instructions: "..." },
272- "user-123",
273- "default-conv-id",
274282 {
283+ containerTag: "user-123",
284+ customId: "default-conv-id",
275285 mode: "full",
276286 addMemory: "always",
277287 }
278288))
279289
280- // Override conversationId dynamically via RequestContext
290+ // Override customId dynamically via RequestContext
281291const ctx = new RequestContext()
282292ctx.set(MASTRA_THREAD_ID_KEY, "dynamic-thread-id")
283293
@@ -293,9 +303,11 @@ Enable detailed logging for debugging:
293303` ` ` typescript
294304const agent = new Agent(withSupermemory(
295305 { id: "my-assistant", model: openai("gpt-4o"), instructions: "..." },
296- "user-123",
297- "conv-456",
298- { verbose: true }
306+ {
307+ containerTag: "user-123",
308+ customId: "conv-456",
309+ verbose: true,
310+ }
299311))
300312
301313// Console output:
@@ -321,8 +333,10 @@ const agent = new Agent(withSupermemory(
321333 inputProcessors: [myLoggingProcessor],
322334 outputProcessors: [myAnalyticsProcessor],
323335 },
324- "user-123",
325- "conv-456"
336+ {
337+ containerTag: "user-123",
338+ customId: "conv-456",
339+ }
326340))
327341` ` `
328342
@@ -337,17 +351,13 @@ Enhances a Mastra agent config with memory capabilities.
337351` ` ` typescript
338352function withSupermemory<T extends AgentConfig>(
339353 config: T,
340- containerTag: string,
341- conversationId: string,
342- options?: SupermemoryMastraOptions
354+ options: SupermemoryMastraOptions
343355): T
344356` ` `
345357
346358** Parameters :**
347359- ` config ` - The Mastra agent configuration object
348- - ` containerTag ` - User / container ID for scoping memories
349- - ` conversationId ` - Conversation ID to group messages into the same document
350- - ` options ` - Configuration options
360+ - ` options ` - Configuration options including ` containerTag ` and ` customId `
351361
352362** Returns :** Enhanced config with Supermemory processors injected
353363
@@ -357,9 +367,7 @@ Creates an input processor for memory injection.
357367
358368` ` ` typescript
359369function createSupermemoryProcessor(
360- containerTag: string,
361- conversationId: string,
362- options?: SupermemoryMastraOptions
370+ options: SupermemoryMastraOptions
363371): SupermemoryInputProcessor
364372` ` `
365373
@@ -369,9 +377,7 @@ Creates an output processor for conversation saving.
369377
370378` ` ` typescript
371379function createSupermemoryOutputProcessor(
372- containerTag: string,
373- conversationId: string,
374- options?: SupermemoryMastraOptions
380+ options: SupermemoryMastraOptions
375381): SupermemoryOutputProcessor
376382` ` `
377383
@@ -381,9 +387,7 @@ Creates both processors with shared configuration.
381387
382388` ` ` typescript
383389function createSupermemoryProcessors(
384- containerTag: string,
385- conversationId: string,
386- options?: SupermemoryMastraOptions
390+ options: SupermemoryMastraOptions
387391): {
388392 input: SupermemoryInputProcessor
389393 output: SupermemoryOutputProcessor
@@ -394,6 +398,8 @@ function createSupermemoryProcessors(
394398
395399` ` ` typescript
396400interface SupermemoryMastraOptions {
401+ containerTag: string // User/container ID for scoping memories
402+ customId: string // Custom ID to group messages into the same document
397403 apiKey?: string
398404 baseUrl?: string
399405 mode?: "profile" | "query" | "full"
@@ -419,15 +425,17 @@ Processors gracefully handle errors without breaking the agent:
419425
420426- ** API errors ** - Logged and skipped ; agent continues without memories
421427- ** Missing API key ** - Throws immediately with helpful error message
422- - ** Empty conversationId ** - Throws immediately with helpful ` [supermemory] ` - prefixed error message
428+ - ** Empty customId ** - Throws immediately with helpful ` [supermemory] ` - prefixed error message
423429
424430` ` ` typescript
425431// Missing API key throws immediately
426432const agent = new Agent(withSupermemory(
427433 { id: "my-assistant", model: openai("gpt-4o"), instructions: "..." },
428- "user-123",
429- "conv-456",
430- { apiKey: undefined } // Will check SUPERMEMORY_API_KEY env
434+ {
435+ containerTag: "user-123",
436+ customId: "conv-456",
437+ apiKey: undefined, // Will check SUPERMEMORY_API_KEY env
438+ }
431439))
432440// Error: SUPERMEMORY_API_KEY is not set
433441` ` `
0 commit comments