[Blog](https://supermemory.ai/blog) · [Engineering](https://supermemory.ai/blog/tag/engineering)

# Introducing @supermemory/tools v2.0.0

By Mahesh Sanikommu April 27, 2026 · 5 min read 

![Supermemory header reading "Tools v2 unifies the interface across integrations" — Different cable connections meet at one common adapter](https://supermemory.ai/_astro/cover.kMFcF6VV_1gNFjX.webp)

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](https://supermemory.ai/docs/migration/tools-v2-upgrade).

## 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](https://supermemory.ai/docs/integrations/ai-sdk).

## 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](https://supermemory.ai/docs/integrations/ai-sdk) or the [migration guide](https://supermemory.ai/docs/migration/tools-v2-upgrade).

## 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](https://supermemory.ai/docs/integrations/voltagent).

## 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](https://supermemory.ai/docs/migration/tools-v2-upgrade).

For a version-pinned implementation and a two-session test, follow [persistent memory with AI SDK](https://supermemory.ai/blog/how-to-use-supermemory-with-ai-sdk/). Before a multi-user rollout, check [tenant and user isolation](https://supermemory.ai/blog/multi-tenant-memory-noisy-neighbor-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](https://console.supermemory.ai/)

**Pick your integration:**

* [Vercel AI SDK](https://supermemory.ai/docs/integrations/ai-sdk)
* [OpenAI SDK](https://supermemory.ai/docs/integrations/openai)
* [Mastra](https://supermemory.ai/docs/integrations/mastra)
* [VoltAgent](https://supermemory.ai/docs/integrations/voltagent)

**Resources:**

* [v1.4 → v2.0 migration guide](https://supermemory.ai/docs/migration/tools-v2-upgrade)
* [@supermemory/tools on npm](https://www.npmjs.com/package/@supermemory/tools)
* [GitHub](https://github.com/supermemoryai/supermemory)

For an existing application, start with [a reversible memory rollout](https://supermemory.ai/blog/add-memory-to-existing-app-rollout/). For coding workflows, compare [filesystem memory design](https://supermemory.ai/blog/filesystem-memory-design/) with the integration boundary your agent uses.

## Other posts.

1. [We're open sourcing the company brain. Here's how we designed the multiplayer harness Company Brain is now open source. A walkthrough of the multiplayer harness behind its Slack experience, from proactivity and memory boundaries to approvals and recovery. NewsSep 25, 2026 ](https://supermemory.ai/blog/open-sourcing-company-brain)
2. [Jev changes a lot in memory & context engineering. Here's exactly how. We tested Jev across reranking, chunking, observation, and harness decisions. Here is where fast decision models help memory systems, where they cost more, and where they still fall short. EngineeringSep 24, 2026 ](https://supermemory.ai/blog/jev-memory-context-engineering)
3. [I reverse-engineered Instinct's memory. Here's exactly how it works Instinct keeps its memory as git-tracked markdown files, found with grep rather than vectors. Here is the whole system as far as black-box probing can reconstruct it, and how to rebuild it on supermemory in about 60 lines. EngineeringSep 20, 2026 ](https://supermemory.ai/blog/reverse-engineering-instinct-memory)
4. [An update to supermemory We've discontinued the supermemory company brain and Nova. Everyone who was charged has been refunded, our MCP and plugins continue to run, and we're going all in on the memory engine. NewsSep 10, 2026 ](https://supermemory.ai/blog/an-update-to-supermemory)
5. [Scaling Conversations: How Adapta Grew Usage Without Losing Context Adapta added Supermemory as a persistent memory layer so every conversation keeps its context — letting the team scale usage without losing the thread. Case StudyJun 12, 2026 ](https://supermemory.ai/blog/adapta-scaling-conversations)
6. [How Chatarmin Ditched RAG and Went Memory-Only with Supermemory Chatarmin replaced a heavy RAG pipeline with Supermemory's memory layer — cutting average AI response time from 40s to 12s and token usage by 40–50%. Case StudyJun 10, 2026 ](https://supermemory.ai/blog/chatarmin-memory-only)
7. [SMFS: making agentic retrieval 55% cheaper AND more accurate We launched SMFS.ai (Supermemory Filesystem) a few weeks ago, with a simple bet: We can redesign the filesystem specifically for agents, with special files, structures, and commands that it can use for it's tasks. Today, SMFS is used by hundreds of companies to power their agents. EngineeringMay 28, 2026 ](https://supermemory.ai/blog/smfs-making-agentic-retrieval-55-cheaper-and-more-accurate)
8. [Introducing Dynamic Dreaming: supermemory now connects the dots, for you. Dreaming is magical. TLDR: We're launching Dynamic Dreaming in supermemory today, which automatically works if you're using supermemory in any way - API, OpenClaw, Hermes agent, etc. EngineeringMay 25, 2026 ](https://supermemory.ai/blog/introducing-dynamic-dreaming-supermemory-now-connects-the-dots-for-you)
9. [Dear reader, we just made supermemory insanely cheap... the Context Cloud When I first started building supermemory, I had one goal: To build the best memory system for AI. I would talk to customers, and find out that memory was not the only thing they needed - They were all setting up 7-8 different vendors at the same time. EngineeringMay 18, 2026 ](https://supermemory.ai/blog/dear-reader-we-just-made-supermemory-insanely-cheap-the-context-cloud)
10. [Solving the Precision-Recall Tradeoff: Search Result Aggregation When you're building memory for AI, search is your foundational layer. The way search generally works is straightforward: the user defines a query, and then sets a limit (top-K) on how many search results they want returned. Usually, this is set to 10 or 20. EngineeringApr 5, 2026 ](https://supermemory.ai/blog/solving-the-precision-recall-tradeoff-search-result-aggregation)
11. [OpenClaw Memory Problems: Why It Forgets and How to Fix It (2026) TLDR: Today, we are releasing a new version of our openclaw plugin - https://github.com/supermemoryai/openclaw-supermemory. This post is going to be a bit technical, so bear with me (or bookmark for later!) In this post, I will talk about what we do about OpenClaw memory, and how we fix it. EngineeringFeb 19, 2026 ](https://supermemory.ai/blog/why-everyone-is-complaining-about-openclaws-memory-it-sucks-and-why-supermemory-fixes-it)
12. [Stateful Coding Agents with Memory: Build Long-Running Agents (2026) We built a plugin for Claude Code and OpenCode that gives your coding agent persistent memory. It remembers your preferences, learns your codebase, and never loses context mid-conversation. The result is an agent you can run for months without starting over. EngineeringFeb 18, 2026 ](https://supermemory.ai/blog/infinitely-running-stateful-coding-agents)
13. [Clawd / Molt bot's memory SUCKS. We gave it supermemory. I'm the founder of supermemory. Clawd/Molt bot is blowing up right now, with many, many use cases. I set it up, too, and have been using it through telegram. TLDR: just go to https://supermemory.ai/docs/integrations/clawdbot to set up supermemory for your clawd bot. EngineeringJan 28, 2026 ](https://supermemory.ai/blog/clawd-molt-bots-memory-sucks-we-gave-it-supermemory)
14. [Catch up with our UNFORGETTABLE Launch Week Over the last year, one belief has guided almost everything we’ve built at Supermemory AI becomes meaningfully useful only when it remembers. Memory shouldn’t be something developers rebuild from scratch. It shouldn’t be fragile, expensive, or trapped inside a single tool. NewsJan 4, 2026 ](https://supermemory.ai/blog/catch-up-with-our-unforgettable-launch-week)
15. [Empowering the Next Generation of Founders: Supermemory Startup Program If there’s one thing we’ve learned while building Supermemory, it’s that most startups don’t fail because they didn't build features; they fail when infrastructure slows them down, or they built too slow. NewsDec 31, 2025 ](https://supermemory.ai/blog/empowering-the-next-generation-of-founders-supermemory-startup-program)
16. [Building code-chunk: AST Aware Code Chunking At Supermemory, we're building context engineering infrastructure for AI. A huge part of that is dealing with code: ingesting repos, understanding structure, and making it searchable. The problem is that most code chunking solutions are terrible. We built code-chunk to fix this. EngineeringDec 29, 2025 ](https://supermemory.ai/blog/building-code-chunk-ast-aware-code-chunking)
17. [Supermemory raises $3 million with the best memory engine for LLMs Today, I am excited to announce our first funding round to accelerate our mission of building an interoperable, scalable and reliable memory for LLMs and agents. Memory is one of the hardest challenges in AI right now. NewsOct 6, 2025 ](https://supermemory.ai/blog/supermemory-raises-3-million-and-building-the-best-memory-engine-for-llms)
18. [Mem0 vs Supermemory: Why Scira Switched Scira AI moved its production memory layer from Mem0 to Supermemory. This is what failed, what improved, and how the team evaluated the two systems. Case StudyOct 2, 2025 ](https://supermemory.ai/blog/why-scira-ai-switched)
19. [Never Record Again: How Montra Uses Supermemory to Rethink Video Creation Campbell Baron, the founder of Montra, has been making videos since he was twelve. By thirteen, he was already doing brand work. Today, he’s betting on a very different future for creators: a world where recording is the exception, and most videos are generated from scratch. Case StudyAug 21, 2025 ](https://supermemory.ai/blog/never-record-again-how-montra-uses-supermemory-to-rethink-video-creation)
20. [Unified Memory That Works Where You Work: Your Second Brain With Supermemory Hi everyone, I’m Dhravya, the founder of Supermemory. I want to start with a little story behind why this product means so much to me. You can also skip straight to what it is and how it works below. EngineeringJul 25, 2025 ](https://supermemory.ai/blog/unified-memory-that-works-where-you-work-your-second-brain-with-supermemory)
21. [Supermemory just got faster on PlanetScale What is Supermemory? Supermemory completes the missing part of the LLM puzzle: memory. Just as memory is crucial for human intelligence, it's essential for truly intelligent AI systems. EngineeringJul 18, 2025 ](https://supermemory.ai/blog/supermemory-just-got-faster-on-planetscale)
22. [Faster, smarter, reliable infinite chat: Supermemory IS context engineering. People are obsessed with prompts and prompt engineering. Sure, what you say is important, but what the model knows when you say it is the difference between a stateless text generator and an intelligent AI system. In short, context is the most crucial component. NewsJul 9, 2025 ](https://supermemory.ai/blog/faster-smarter-reliable-infinite-chat-supermemory-is-context-engineering)
23. [We solved AI API interoperability One API to rule them all, One spec to find them, One library to bring them all and in the TypeScript, bind them. When we were building the Infinite Chat API, initially, we only supported the OpenAI format. This was fine, until a lot of our customers started asking for more. EngineeringJul 7, 2025 ](https://supermemory.ai/blog/we-solved-ai-api-interoperability)
24. [The Wow Factor of Memory - How Flow Used Supermemory To Build Smarter, Stickier Products Overview: Flow is a note-taking app built around a bold vision: to create a more personal, context-aware writing experience powered by AI. At the heart of this mission is memory. Case StudyJun 14, 2025 ](https://supermemory.ai/blog/the-wow-factor-of-memory-how-flow-used-supermemory-to-build-smarter-stickier-products)
25. [The UX and technicalities of awesome MCPs Last month, we launched the Supermemory MCP, mostly to test our own infrastructure and get some initial traction. It blew up. To my absolute surprise, the initial launch itself got half a million impressions (!!!). Then, we launched and got #2 on ProductHunt too. EngineeringJun 8, 2025 ](https://supermemory.ai/blog/the-ux-and-technicalities-of-awesome-mcps)
26. [Architecting a memory engine inspired by the human brain Language is at the heart of intelligence, but what truly powers meaningful interaction is memory — the ability to accumulate, recall, and contextualize information over time. Large Language Models (LLMs) have mastered language, but memory remains their Achilles’ heel. EngineeringJun 5, 2025 ](https://supermemory.ai/blog/memory-engine)

## Start building with supermemory.

Memory and continual learning for any model, any harness. Available through our API, plugins, and MCP.

[Build with supermemory ](https://console.supermemory.ai/)