Skip to main content
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.

@supermemory/tools on npm

Check out the NPM page for more details

​
Installation

npm install @supermemory/tools @voltagent/core
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({
  messages: [{ role: "user", content: "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

ModeDescriptionUse Case
"profile"Retrieves the user’s complete profilePersonalization without search
"query"Searches memories based on the user’s messageFinding relevant past context
"full"Combines profile AND query-based searchComplete 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.1,                  // 0.0-1.0 (higher = more accurate)
  limit: 10,                       // Max results to return
  rerank: true,                    // Rerank for best relevance
  rewriteQuery: false,             // AI-rewrite query (+400ms latency)

  // Context
  entityContext: "This is John, a software engineer",  // Guides memory extraction (max 1500 chars)
  metadata: { source: "voltagent" },                   // Attached to saved conversations

  // API
  apiKey: "sk-...",                // Falls back to SUPERMEMORY_API_KEY env var
  baseUrl: "https://api.supermemory.ai",
})
ParameterTypeDefaultDescription
agentConfigobjectrequiredVoltAgent agent configuration object
containerTagstringrequiredUser/project ID for scoping memories
modestring"profile"Memory retrieval mode
addMemorystring"always"Whether to save conversations after each response
customIdstringrequiredCustom ID to group messages into a conversation
searchModestring—"memories", "documents", or "hybrid"
thresholdnumber0.1Similarity threshold (0 = more results, 1 = more accurate)
limitnumber10Maximum number of memory results
rerankbooleanfalseRerank results for relevance
rewriteQuerybooleanfalseAI-rewrite query for better results (+400ms)
entityContextstring—Context for memory extraction (max 1500 chars)
metadataobject—Custom metadata attached to saved conversations
promptTemplatefunction—Custom function to format memory data into prompt

​
Search Modes

The searchMode option controls what type of results are searched:
ModeDescription
"memories"Search only memory entries (atomic facts about the user)
"documents"Search only document chunks
"hybrid"Search both memories AND document chunks (recommended)