Upgrading @supermemory/tools to v2.0.0

Migrate your code from @supermemory/tools 1.4.x to 2.0.0 — config-object signature, customId, and new defaults

@supermemory/tools v2.0.0 unifies the API across all four integrations (Vercel AI SDK, OpenAI, Mastra, VoltAgent) around a single config-object signature and a consistent conversation-grouping concept. This guide walks you through the breaking changes.

INFO

This release is breaking. Update calls and re-test before bumping in production.

What changed at a glance

Area	v1.4.x	v2.0.0
Signature	withSupermemory(model, "user-123", { ... })	withSupermemory(model, { containerTag: "user-123", ... })
Conversation grouping	conversationId (Vercel/OpenAI), threadId (Mastra)	customId everywhere
customId	Optional	Required — throws if missing or empty
containerTag	Positional argument	Required field on options object
addMemory default	"never"	"always"
VoltAgent verbose	Hardcoded to false	Honored from options

Install

npm install @supermemory/tools@^2.0.0

1. Vercel AI SDK

// v1.4.x
import { withSupermemory } from '@supermemory/tools/ai-sdk';

const model = withSupermemory(openai('gpt-4'), 'user-123', {
  conversationId: 'conv-456',
  mode: 'full',
});

// v2.0.0
import { withSupermemory } from '@supermemory/tools/ai-sdk';

const model = withSupermemory(openai('gpt-4'), {
  containerTag: 'user-123',
  customId: 'conv-456',
  mode: 'full',
});

WARNING

customId is now required. Passing an empty string or omitting it throws at construction time.

2. OpenAI SDK

// v1.4.x
import { withSupermemory } from '@supermemory/tools/openai';

const client = withSupermemory(openai, 'user-123', {
  conversationId: 'conv-456',
});

// v2.0.0
import { withSupermemory } from '@supermemory/tools/openai';

const client = withSupermemory(openai, {
  containerTag: 'user-123',
  customId: 'conv-456',
});

Both containerTag and customId are validated and throw with explicit error messages if missing.

3. Mastra

Processor constructors and factory functions both moved to a single options argument. threadId is gone — use customId instead.

// v1.4.x
import {
  SupermemoryInputProcessor,
  createSupermemoryOutputProcessor,
} from '@supermemory/tools/mastra';

const input = new SupermemoryInputProcessor('user-123', {
  mode: 'full',
});

const output = createSupermemoryOutputProcessor('user-123', {
  threadId: 'conv-456',
  addMemory: 'always',
});

// v2.0.0
import {
  SupermemoryInputProcessor,
  createSupermemoryOutputProcessor,
} from '@supermemory/tools/mastra';

const input = new SupermemoryInputProcessor({
  containerTag: 'user-123',
  customId: 'conv-456',
  mode: 'full',
});

const output = createSupermemoryOutputProcessor({
  containerTag: 'user-123',
  customId: 'conv-456',
});

INFO

In server setups, Mastra's RequestContext thread ID still takes precedence over the construction-time customId — the option now acts as the fallback when no per-request thread ID is provided.

4. VoltAgent

VoltAgent already used a config-object signature, so the call shape is unchanged. Two behavior fixes ship in v2.0.0:

• verbose: true is now honored (was hardcoded to false in v1.4.x).
• A runtime warning is logged when advanced search params (threshold, limit, rerank, rewriteQuery, filters, include, searchMode) are set while mode: "profile" — those parameters are ignored in profile mode.

If you were relying on verbose: false implicitly while passing verbose: true, you will now see logs. Adjust as needed.

5. New default: addMemory: "always"

Across all four integrations, addMemory now defaults to "always". If your v1.4.x code relied on the old default of "never", set it explicitly:

const model = withSupermemory(openai('gpt-4'), {
  containerTag: 'user-123',
  customId: 'conv-456',
  addMemory: 'never', // preserve v1.4.x behavior
});

Conversation persistence

In v1.4.x the Vercel middleware fell back to client.add with a synthesized customId when no conversationId was passed. In v2.0.0, because customId is required, all conversation persistence goes through the /v4/conversations endpoint via addConversation. There is no fallback path.

Migration checklist

Bump the dependency

`npm install @supermemory/tools@^2.0.0`

Find every withSupermemory / processor call

Grep your codebase for `withSupermemory(`, `SupermemoryInputProcessor`,
`SupermemoryOutputProcessor`, `createSupermemoryProcessor`,
`createSupermemoryOutputProcessor`.

Move containerTag into the options object

Drop the positional `containerTag` argument and add it to the options
object.

Rename conversationId / threadId to customId

Make sure every call site provides a non-empty `customId`.

Audit addMemory

If you depended on the old `"never"` default, pass `addMemory: "never"`
explicitly.

Run your test suite

Validation throws happen at construction time, so missing fields surface
immediately.

Need help?

• Vercel AI SDK integration
• OpenAI integration
• Mastra integration
• VoltAgent integration

If you hit something this guide does not cover, open an issue on GitHub.