Vercel AI SDK - supermemory | Memory API for the AI era

The Supermemory AI SDK provides native integration with Vercel’s AI SDK through two approaches: User Profiles for automatic personalization and Memory Tools for agent-based interactions.

Migrating to v2 from 1.4.x? Check the migration guide.

@supermemory/tools on npm

Check out the NPM page for more details

Installation

npm install @supermemory/tools

Quick Comparison

Approach	Use Case	Setup
User Profiles	Personalized LLM responses with automatic user context	Simple middleware
Memory Tools	AI agents that need explicit memory control	Tool definitions

User Profiles with Middleware

Automatically inject user profiles into every LLM call for instant personalization.

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

const modelWithMemory = withSupermemory(openai("gpt-5"), {
  containerTag: "user-123",
  customId: "conversation-456",
})

const result = await generateText({
  model: modelWithMemory,
  messages: [{ role: "user", content: "What do you know about me?" }]
})

Required fields

Both containerTag and customId are required.

containerTag — who the memories belong to. Use a stable identifier per user, workspace, or tenant (e.g. "user-123", "acme-workspace"). Memory search and writes are scoped to this tag.
customId — which conversation this turn belongs to. Use it to group messages from the same chat session into a single document (e.g. "chat-2026-04-25", a thread ID, or a UUID per session).

Memory saving is enabled by default (addMemory: "always"). New conversations are persisted automatically. To opt out, set addMemory: "never":

const modelWithMemory = withSupermemory(openai("gpt-5"), {
  containerTag: "user-123",
  customId: "conversation-456",
  addMemory: "never",
})

Memory Search Modes

Profile Mode (Default) - Retrieves the user’s complete profile:

const model = withSupermemory(openai("gpt-4"), { containerTag: "user-123", customId: "conv-1", mode: "profile" })

Query Mode - Searches memories based on the user’s message:

const model = withSupermemory(openai("gpt-4"), { containerTag: "user-123", customId: "conv-1", mode: "query" })

Full Mode - Combines profile AND query-based search:

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

Custom Prompt Templates

Customize how memories are formatted. The template receives userMemories, generalSearchMemories, and searchResults (raw array for filtering by metadata):

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

const claudePrompt = (data: MemoryPromptData) => `
<context>
  <user_profile>
    ${data.userMemories}
  </user_profile>
  <relevant_memories>
    ${data.generalSearchMemories}
  </relevant_memories>
</context>
`.trim()

const model = withSupermemory(anthropic("claude-3-sonnet"), {
  containerTag: "user-123",
  customId: "conv-1",
  mode: "full",
  promptTemplate: claudePrompt,
})

Verbose Logging

const model = withSupermemory(openai("gpt-4"), {
  containerTag: "user-123",
  customId: "conv-1",
  verbose: true,
})
// Console output shows memory retrieval details

When Supermemory errors (default: continue without memories)

If the Supermemory API returns an error, is unreachable, or retrieval hits the internal time limit, memory injection is skipped. skipMemoryOnError defaults to true, so the LLM call still runs with the original prompt (no injected memories). Use verbose: true if you want console output when that happens. To fail the call when memory retrieval fails instead, set skipMemoryOnError: false:

const model = withSupermemory(openai("gpt-5"), {
  containerTag: "user-123",
  customId: "conv-1",
  skipMemoryOnError: false,
})

Persisting Tool Calls (default: off)

By default, saved conversations include only user and assistant text — tool calls and tool results are dropped, since tool payloads are often large and low-signal and would pollute memory extraction. To persist the full tool round trip (tool calls with their arguments, plus tool results, in their original order), set includeToolCalls: true:

const model = withSupermemory(openai("gpt-5"), {
  containerTag: "user-123",
  customId: "conv-1",
  includeToolCalls: true,
})

Memory Tools

Add memory capabilities to AI agents with search, add, and fetch operations.

import { streamText } from "ai"
import { createAnthropic } from "@ai-sdk/anthropic"
import { supermemoryTools } from "@supermemory/tools/ai-sdk"

const anthropic = createAnthropic({ apiKey: "YOUR_ANTHROPIC_KEY" })

const result = await streamText({
  model: anthropic("claude-3-sonnet"),
  prompt: "Remember that my name is Alice",
  tools: supermemoryTools("YOUR_SUPERMEMORY_KEY")
})

Available Tools

Search Memories - Semantic search through user memories:

const result = await streamText({
  model: openai("gpt-5"),
  prompt: "What are my dietary preferences?",
  tools: supermemoryTools("API_KEY")
})
// AI will call: searchMemories({ informationToGet: "dietary preferences" })

Add Memory - Store new information:

const result = await streamText({
  model: anthropic("claude-3-sonnet"),
  prompt: "Remember that I'm allergic to peanuts",
  tools: supermemoryTools("API_KEY")
})
// AI will call: addMemory({ memory: "User is allergic to peanuts" })

Using Individual Tools

For more control, import tools separately:

import {
  searchMemoriesTool,
  addMemoryTool
} from "@supermemory/tools/ai-sdk"

const result = await streamText({
  model: openai("gpt-5"),
  prompt: "What do you know about me?",
  tools: {
    searchMemories: searchMemoriesTool("API_KEY", { projectId: "personal" }),
    createEvent: yourCustomTool,
  }
})

Tool Results

// searchMemories result
{ success: true, results: [...], count: 5 }

// addMemory result
{ success: true, memory: { id: "mem_123", ... } }

@supermemory/tools on npm

​Installation

​Quick Comparison

​User Profiles with Middleware

​Required fields

​Memory Search Modes

​Custom Prompt Templates

​Verbose Logging

​When Supermemory errors (default: continue without memories)

​Persisting Tool Calls (default: off)

​Memory Tools

​Available Tools

​Using Individual Tools

​Tool Results

Installation

Quick Comparison

User Profiles with Middleware

Required fields

Memory Search Modes

Custom Prompt Templates

Verbose Logging

When Supermemory errors (default: continue without memories)

Persisting Tool Calls (default: off)

Memory Tools

Available Tools

Using Individual Tools

Tool Results