VoltAgent - supermemory | Memory API for the AI era

Supermemory integrates with VoltAgent, providing long-term memory capabilities for AI agents. Your VoltAgent applications will remember past conversations and provide personalized responses based on user history.

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 @voltagent/core ai@^6 @ai-sdk/openai@^3

Set up your API key as an environment variable:

export SUPERMEMORY_API_KEY=your_supermemory_api_key

You can obtain an API key from console.supermemory.ai.

Quick Start

Supermemory provides a withSupermemory wrapper that enhances any VoltAgent agent config with automatic memory retrieval and storage:

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

// Create an agent with Supermemory memory capabilities
const configWithMemory = withSupermemory({
  agentConfig: {
    name: "my-agent",
    instructions: "You are a helpful assistant.",
    model: openai("gpt-4o"),
  },
  containerTag: "user-123",
  customId: "conversation-123",
})

const agent = new Agent(configWithMemory)

// Memories are automatically injected and saved
const result = await agent.generateText("What's my name?")

Memory saving is enabled by default in the VoltAgent integration. To disable it:

const configWithMemory = withSupermemory({
  agentConfig: {
    name: "my-agent",
    instructions: "You are a helpful assistant.",
    model: openai("gpt-4o"),
  },
  containerTag: "user-123",
  customId: "conversation-123",
  addMemory: "never",
})

How It Works

When integrated with VoltAgent, Supermemory hooks into two lifecycle events:

1. Memory Retrieval (onPrepareMessages)

Before each LLM call, Supermemory automatically:

Extracts the user’s latest message
Searches for relevant memories scoped to the containerTag
Injects retrieved memories into the system prompt

2. Conversation Saving (onEnd)

After each agent response, the conversation is saved to Supermemory for future retrieval. This requires a customId to be set.

Memory Modes

Mode	Description	Use Case
`"profile"`	Retrieves the user’s complete profile	Personalization without search
`"query"`	Searches memories based on the user’s message	Finding relevant past context
`"full"`	Combines profile AND query-based search	Complete memory (recommended)

const configWithMemory = withSupermemory({
  agentConfig: {
    name: "my-agent",
    instructions: "You are a helpful assistant.",
    model: openai("gpt-4o"),
  },
  containerTag: "user-123",
  customId: "conversation-123",
  mode: "full",
})

Configuration Options

const configWithMemory = withSupermemory({
  // Agent configuration
  agentConfig: {
    name: "my-agent",
    instructions: "You are a helpful assistant.",
    model: openai("gpt-4o"),
  },

  // Required
  containerTag: "user-123",        // User/project ID for scoping memories

  // Memory behavior
  mode: "full",                    // "profile" | "query" | "full"
  addMemory: "always",             // "always" | "never"
  customId: "conv-456",            // Groups messages into a conversation

  // Search tuning
  searchMode: "hybrid",            // "memories" | "documents" | "hybrid"
  threshold: 0.6,                  // 0.0-1.0 (higher = more accurate)
  limit: 10,                       // Integer from 1 to 100
  rerank: true,                    // Rerank for best relevance
  rewriteQuery: false,             // AI-rewrite query (+400ms latency)

  // Context
  metadata: { source: "voltagent" },  // Attached to saved conversations

  // API
  apiKey: "sk-...",                // Falls back to SUPERMEMORY_API_KEY env var
  baseUrl: "https://api.supermemory.ai",
})

Parameter	Type	Default	Description
`agentConfig`	object	required	VoltAgent agent configuration object
`containerTag`	string	required	User/project ID for scoping memories
`mode`	string	`"profile"`	Memory retrieval mode
`addMemory`	string	`"always"`	Whether to save conversations after each response
`customId`	string	required	Custom ID to group messages into a conversation
`searchMode`	string	—	`"memories"`, `"documents"`, or `"hybrid"`
`threshold`	number	—	Similarity threshold (0 = more results, 1 = more accurate)
`limit`	number	—	Maximum number of memory results (integer from 1 to 100)
`rerank`	boolean	`false`	Rerank results for relevance
`rewriteQuery`	boolean	`false`	AI-rewrite query for better results (+400ms)
`entityContext`	string	—	Deprecated and ignored. Configure it on the container tag instead.
`metadata`	object	—	Custom metadata attached to saved conversations
`promptTemplate`	function	—	Custom function to format memory data into prompt

When threshold or limit is omitted, the selected Supermemory backend route applies its own default. Set them explicitly when you need consistent search tuning across modes.

Search Modes

The searchMode option controls what type of results are searched:

Mode	Description
`"memories"`	Search only memory entries (atomic facts about the user)
`"documents"`	Search only document chunks
`"hybrid"`	Search both memories AND document chunks (recommended)

@supermemory/tools on npm

​Installation

​Quick Start

​How It Works

​1. Memory Retrieval (onPrepareMessages)

​2. Conversation Saving (onEnd)

​Memory Modes

​Configuration Options

​Search Modes

Installation

Quick Start

How It Works

1. Memory Retrieval (onPrepareMessages)

2. Conversation Saving (onEnd)

Memory Modes

Configuration Options

Search Modes