VoltAgent

Integrate Supermemory with VoltAgent for long-term memory in AI agents

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

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

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.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",
})

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	0.1	Similarity threshold (0 = more results, 1 = more accurate)
limit	number	10	Maximum number of memory results
rerank	boolean	false	Rerank results for relevance
rewriteQuery	boolean	false	AI-rewrite query for better results (+400ms)
entityContext	string	—	Context for memory extraction (max 1500 chars)
metadata	object	—	Custom metadata attached to saved conversations
promptTemplate	function	—	Custom function to format memory data into prompt

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)