> ## Documentation Index
> Fetch the complete documentation index at: https://supermemory-capy-add-llmstxt-summary-and.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# VoltAgent

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

Supermemory integrates with [VoltAgent](https://github.com/VoltAgent/voltagent), providing long-term memory capabilities for AI agents. Your VoltAgent applications will remember past conversations and provide personalized responses based on user history.

<Note>
  Migrating to v2 from 1.4.x? Check the [migration guide](/migration/tools-v2-upgrade).
</Note>

<Card title="@supermemory/tools on npm" icon="https://mintcdn.com/supermemory-capy-add-llmstxt-summary-and/LIMkcglt81IfjBVR/icons/hugeicons/package.svg?fit=max&auto=format&n=LIMkcglt81IfjBVR&q=85&s=e4fde81dc315fb6f6f50b11f4d2f8220" href="https://www.npmjs.com/package/@supermemory/tools" width="24" height="24" data-path="icons/hugeicons/package.svg">
  Check out the NPM page for more details
</Card>

## Installation

```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
npm install @supermemory/tools @voltagent/core ai@^6 @ai-sdk/openai@^3
```

Set up your API key as an environment variable:

```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
export SUPERMEMORY_API_KEY=your_supermemory_api_key
```

You can obtain an API key from [console.supermemory.ai](https://console.supermemory.ai).

## Quick start

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

```typescript theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
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?")
```

<Note>
  **Memory saving is enabled by default** in the VoltAgent integration. To disable it:

  ```typescript theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  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",
  })
  ```
</Note>

## 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) |

```typescript theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
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

```typescript theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
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](/concepts/customization#entity-context). |
| `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) |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.