Introducing @supermemory/tools v2.0.0

Version notice: this is the historical tools v2 release announcement, and its code is preserved for that version. For new integrations, use @supermemory/tools 3.x with namespace and id; follow the tools v3 upgrade guide, current AI SDK guide, and v5 migration guide.

Today we're releasing v2.0.0. This release unifies the API across all agents sdk integrations from AI SDK to Mastra, makes conversation identity a first-class concept, and ships with memory saving on by default.

What's new in v2.0.0:

• Unified config-object API
• customId: required conversation identity
• Memory saving on by default
• VoltAgent: verbose and profile-mode warnings fixed
• Everything that shipped from v1.0 to v2.0

Upgrading from 1.4.x? The changes are mechanical — most teams are done in under 5 minutes. See the v1.4 → v2.0 migration guide.

Unified config-object API

In v1.x, each integration had a slightly different call signature. Vercel AI SDK and OpenAI took containerTag as a positional argument. Mastra used constructor arguments in a different order. Every integration had its own name for the conversation ID field — conversationId in Vercel and OpenAI, threadId in Mastra.

This made the package harder to learn and harder to switch between integrations. If you built on Vercel AI SDK and wanted to add a Mastra processor, you had a different API to memorize.

In v2.0.0, every integration shares the same options object:

import { withSupermemory } from "@supermemory/tools/ai-sdk"
import { openai } from "@ai-sdk/openai"

const model = withSupermemory(openai("gpt-4o"), {
  containerTag: "user-123",
  customId: "conv-456",
  mode: "full",
  addMemory: "always",
})

The same shape works on OpenAI:

import { withSupermemory } from "@supermemory/tools/openai"

const client = withSupermemory(new OpenAI(), {
  containerTag: "user-123",
  customId: "conv-456",
})

And on Mastra:

import { SupermemoryInputProcessor } from "@supermemory/tools/mastra"

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

One API. Four integrations. Same mental model everywhere.

Note

for VoltAgent users: VoltAgent already used a config-object signature before v2.0.0, so your call shape is unchanged. See the VoltAgent section for what actually changed in your integration.

To learn more, see the integration documentation.

customId: required conversation identity

In v1.x, conversationId (or threadId in Mastra) was optional. When omitted, conversations weren't grouped — each turn was saved in isolation, making it impossible to retrieve the full context of a session later.

In v2.0.0, customId is required across all integrations. Omitting it or passing an empty string throws at construction time, so you catch the error immediately rather than silently losing conversation context in production.

// This throws immediately with a clear error message
const model = withSupermemory(openai("gpt-4o"), {
  containerTag: "user-123",
  customId: "",  // ❌ throws: customId must be a non-empty string
})

// Use a stable, meaningful ID — a session UUID, thread ID, or date-scoped key
const model = withSupermemory(openai("gpt-4o"), {
  containerTag: "user-123",
  customId: `chat-${sessionId}`,  // ✅
})

customId groups every message from a session into a single conversation document in Supermemory, making that full context available for retrieval in future sessions.

containerTag vs customId at a glance:

containerTag

customId

Represents

Who the memory belongs to

Which conversation this turn belongs to

Scope

User, workspace, or tenant

Session, thread, or conversation

Example

"user-123", "acme-corp"

"chat-2026-04-26", a UUID

Memory search

Scoped to this tag

Groups messages into one document

To learn more, see the Vercel AI SDK integration or the migration guide.

Memory saving on by default

In v1.x, addMemory defaulted to "never". Memory saving had to be explicitly enabled, which meant it was easy to forget — and easy to deploy an agent that retrieved memories but never built any new ones.

In v2.0.0, addMemory defaults to "always". When a conversation ends, it's automatically saved to Supermemory and becomes available for retrieval in future sessions. No extra configuration required.

// v1.x — had to opt in
const model = withSupermemory(openai("gpt-4o"), "user-123", {
  addMemory: "always",  // easy to forget
})

// v2.0.0 — saves by default
const model = withSupermemory(openai("gpt-4o"), {
  containerTag: "user-123",
  customId: "conv-456",
  // addMemory: "always" is the default
})

If you want to retrieve memories without saving new ones — for example in a read-only context or during testing — opt out explicitly:

const model = withSupermemory(openai("gpt-4o"), {
  containerTag: "user-123",
  customId: "conv-456",
  addMemory: "never",
})

Note

This default applies to Vercel AI SDK, OpenAI SDK, and Mastra. VoltAgent already defaulted to "always" in v1.x.

VoltAgent: verbose and profile-mode warnings

VoltAgent's call shape was already a config object before v2.0.0, so there are no breaking API changes for VoltAgent users.

Profile-mode warnings for ignored search params. When mode: "profile" is set, parameters like threshold, limit, rerank, rewriteQuery, and searchMode have no effect — profile mode fetches the full user profile and doesn't run a search query. Previously these were silently ignored. Now a runtime warning is logged when any of them are set alongside mode: "profile", so configuration mistakes surface immediately.

To learn more, see the VoltAgent integration.

Everything that shipped from v1.0 to v2.0

v2.0.0 is a milestone, but a lot of capability landed across the releases between the initial Vercel AI SDK-only release and today.

New integrations

@supermemory/tools started with Vercel AI SDK support only. Between v1.0 and v2.0, three more integrations were added:

• OpenAI SDK — withSupermemory wrapper for chat.completions.create, with support for the Responses API (responses.create) and automatic assistant response capture
• Mastra — SupermemoryInputProcessor and createSupermemoryOutputProcessor with RequestContext support for per-request thread IDs
• VoltAgent — withSupermemory agent config wrapper that hooks into onPrepareMessages (retrieval) and onEnd (saving) lifecycle events

Memory retrieval modes

Three modes control what gets retrieved before each LLM call:

// "profile" — retrieves the user profile built from past sessions
const model = withSupermemory(openai("gpt-4o"), { containerTag: "user-123", customId: "conv-1", mode: "profile" })

// "query" — semantic search across past memories based on the current message
const model = withSupermemory(openai("gpt-4o"), { containerTag: "user-123", customId: "conv-1", mode: "query" })

// "full" — both profile and query results combined (highest recall)
const model = withSupermemory(openai("gpt-4o"), { containerTag: "user-123", customId: "conv-1", mode: "full" })

Custom prompt templates

The promptTemplate option lets you control exactly how retrieved memories are formatted before they're injected into the system prompt:

import { withSupermemory, type MemoryPromptData } from "@supermemory/tools/ai-sdk"

const model = withSupermemory(openai("gpt-4o"), {
  containerTag: "user-123",
  customId: "conv-456",
  mode: "full",
  promptTemplate: (data: MemoryPromptData) => `
<memory>
  <profile>${data.userMemories}</profile>
  <context>${data.generalSearchMemories}</context>
</memory>
  `.trim(),
})

The data object also exposes raw searchResults so you can filter by metadata before injection.

Resilience: skipMemoryOnError and fetch timeout

Memory retrieval should never block your LLM call. Two additions make this reliable:

• skipMemoryOnError: true (default) — if Supermemory is unreachable or returns an error, the LLM call proceeds with the original prompt. Use verbose: true to log when this happens.
• Internal fetch timeout — memory retrieval is bounded. It never hangs your response indefinitely.

const model = withSupermemory(openai("gpt-4o"), {
  containerTag: "user-123",
  customId: "conv-456",
  skipMemoryOnError: false,  // fail the call if memory retrieval fails
})

Browser and other environments support

apiKey can now be passed via options instead of relying on process.env.SUPERMEMORY_API_KEY, enabling @supermemory/tools to work in browser environments (and others):

const model = withSupermemory(openai("gpt-4o"), {
  containerTag: "user-123",
  customId: "conv-456",
  apiKey: "sm-...",  // no process.env required
})

Performance improvements

• Memory deduplication — duplicate memories are removed before injection, reducing token waste
• LRU cache — repeated memory lookups within the same session are served from cache
• Multi-step prompt caching — compatible with Vercel AI SDK's multi-turn agent flows
• Concurrent tool calls — Claude memory tools execute in parallel instead of sequentially

Migrating from 1.4.x

The changes in v2.0.0 are mechanical. For Vercel AI SDK, OpenAI, and Mastra users:

1. Move containerTag from the positional argument into the options object
2. Rename conversationId or threadId to customId
3. Add addMemory: "never" if you relied on the old default

For VoltAgent users, no API changes are required — only review the verbose behavior if relevant.

npm install @supermemory/tools@^2.0.0

For before/after code for all four integrations, see the full migration guide.

For a version-pinned implementation and a two-session test, follow persistent memory with AI SDK. Before a multi-user rollout, check tenant and user isolation.

Get started

Start using @supermemory/tools v2.0.0:

• Install: npm install @supermemory/tools@^2.0.0
• Get an API key at console.supermemory.ai

Pick your integration:

• Vercel AI SDK
• OpenAI SDK
• Mastra
• VoltAgent

Resources:

• v1.4 → v2.0 migration guide
• @supermemory/tools on npm
• GitHub

For an existing application, start with a reversible memory rollout. For coding workflows, compare filesystem memory design with the integration boundary your agent uses.