> ## Documentation Index
> Fetch the complete documentation index at: https://supermemory-temp-snowcone-command.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="npm" href="https://www.npmjs.com/package/@supermemory/tools">
  Check out the NPM page for more details
</Card>

## Installation

```bash theme={null}
npm install @supermemory/tools @voltagent/core
```

Set up your API key as an environment variable:

```bash theme={null}
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={null}
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?" }],
})
```

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

  ```typescript theme={null}
  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={null}
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={null}
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)   |