Skip to content

Commit 0cbf5e7

Browse files
sreedharsreeramsreedharsreeram
committed
voltagent-sdk
1 parent 2ce55c4 commit 0cbf5e7

File tree

11 files changed

+1632
-34
lines changed

11 files changed

+1632
-34
lines changed

‎apps/docs/docs.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -153,6 +153,7 @@
153153
"integrations/openai-agents-sdk",
154154
"integrations/agent-framework",
155155
"integrations/mastra",
156+
"integrations/voltagent",
156157
"integrations/langchain",
157158
"integrations/crewai",
158159
"integrations/agno",

‎apps/docs/integrations/voltagent.mdx‎

Lines changed: 153 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,153 @@
1+
---
2+
title: "VoltAgent"
3+
sidebarTitle: "VoltAgent"
4+
description: "Integrate Supermemory with VoltAgent for long-term memory in AI agents"
5+
icon: "bolt"
6+
---
7+
8+
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.
9+
10+
<Card title="@supermemory/tools on npm" icon="npm" href="https://www.npmjs.com/package/@supermemory/tools">
11+
Check out the NPM page for more details
12+
</Card>
13+
14+
## Installation
15+
16+
```bash
17+
npm install @supermemory/tools @voltagent/core
18+
```
19+
20+
Set up your API key as an environment variable:
21+
22+
```bash
23+
export SUPERMEMORY_API_KEY=your_supermemory_api_key
24+
```
25+
26+
You can obtain an API key from [console.supermemory.ai](https://console.supermemory.ai).
27+
28+
## Quick Start
29+
30+
Supermemory provides a `withSupermemory` wrapper that enhances any VoltAgent agent config with automatic memory retrieval and storage:
31+
32+
```typescript
33+
import { withSupermemory } from "@supermemory/tools/voltagent"
34+
import { Agent } from "@voltagent/core"
35+
import { openai } from "@ai-sdk/openai"
36+
37+
// Step 1: Define your agent config
38+
const baseConfig = {
39+
name: "my-agent",
40+
instructions: "You are a helpful assistant.",
41+
model: openai("gpt-4o"),
42+
}
43+
44+
// Step 2: Wrap with Supermemory
45+
const configWithMemory = withSupermemory(baseConfig, {
46+
containerTag: "user-123",
47+
})
48+
49+
// Step 3: Create the agent
50+
const agent = new Agent(configWithMemory)
51+
52+
// Memories are automatically injected and saved
53+
const result = await agent.generateText({
54+
messages: [{ role: "user", content: "What's my name?" }],
55+
})
56+
```
57+
58+
<Note>
59+
**Memory saving is enabled by default** in the VoltAgent integration. To disable it:
60+
61+
```typescript
62+
const configWithMemory = withSupermemory(baseConfig, {
63+
containerTag: "user-123",
64+
addMemory: "never",
65+
})
66+
```
67+
</Note>
68+
69+
## How It Works
70+
71+
When integrated with VoltAgent, Supermemory hooks into two lifecycle events:
72+
73+
### 1. Memory Retrieval (onPrepareMessages)
74+
75+
Before each LLM call, Supermemory automatically:
76+
- Extracts the user's latest message
77+
- Searches for relevant memories scoped to the `containerTag`
78+
- Injects retrieved memories into the system prompt
79+
80+
### 2. Conversation Saving (onEnd)
81+
82+
After each agent response, the conversation is saved to Supermemory for future retrieval. This requires either a `threadId` or `customId` to be set.
83+
84+
## Memory Modes
85+
86+
| Mode | Description | Use Case |
87+
| ----------- | ------------------------------------------- | ------------------------------ |
88+
| `"profile"` | Retrieves the user's complete profile | Personalization without search |
89+
| `"query"` | Searches memories based on the user's message | Finding relevant past context |
90+
| `"full"` | Combines profile AND query-based search | Complete memory (recommended) |
91+
92+
```typescript
93+
const configWithMemory = withSupermemory(baseConfig, {
94+
containerTag: "user-123",
95+
mode: "full",
96+
})
97+
```
98+
99+
## Configuration Options
100+
101+
```typescript
102+
const configWithMemory = withSupermemory(baseConfig, {
103+
// Required
104+
containerTag: "user-123", // User/project ID for scoping memories
105+
106+
// Memory behavior
107+
mode: "full", // "profile" | "query" | "full"
108+
addMemory: "always", // "always" | "never"
109+
threadId: "conv-456", // Groups messages into a conversation
110+
customId: "my-custom-id", // Alternative to threadId
111+
112+
// Search tuning
113+
searchMode: "hybrid", // "memories" | "documents" | "hybrid"
114+
threshold: 0.1, // 0.0-1.0 (higher = more accurate)
115+
limit: 10, // Max results to return
116+
rerank: true, // Rerank for best relevance
117+
rewriteQuery: false, // AI-rewrite query (+400ms latency)
118+
119+
// Context
120+
entityContext: "This is John, a software engineer", // Guides memory extraction (max 1500 chars)
121+
metadata: { source: "voltagent" }, // Attached to saved conversations
122+
123+
// API
124+
apiKey: "sk-...", // Falls back to SUPERMEMORY_API_KEY env var
125+
baseUrl: "https://api.supermemory.ai",
126+
})
127+
```
128+
129+
| Parameter | Type | Default | Description |
130+
| --------------- | -------- | ------------ | -------------------------------------------------------- |
131+
| `containerTag` | string | **required** | User/project ID for scoping memories |
132+
| `mode` | string | `"profile"` | Memory retrieval mode |
133+
| `addMemory` | string | `"always"` | Whether to save conversations after each response |
134+
| `threadId` | string | — | Conversation ID to group messages |
135+
| `searchMode` | string | — | `"memories"`, `"documents"`, or `"hybrid"` |
136+
| `threshold` | number | `0.1` | Similarity threshold (0 = more results, 1 = more accurate) |
137+
| `limit` | number | `10` | Maximum number of memory results |
138+
| `rerank` | boolean | `false` | Rerank results for relevance |
139+
| `rewriteQuery` | boolean | `false` | AI-rewrite query for better results (+400ms) |
140+
| `entityContext` | string | — | Context for memory extraction (max 1500 chars) |
141+
| `metadata` | object | — | Custom metadata attached to saved conversations |
142+
| `promptTemplate` | function | — | Custom function to format memory data into prompt |
143+
144+
## Search Modes
145+
146+
The `searchMode` option controls what type of results are searched:
147+
148+
| Mode | Description |
149+
| ------------- | ------------------------------------------------------ |
150+
| `"memories"` | Search only memory entries (atomic facts about the user) |
151+
| `"documents"` | Search only document chunks |
152+
| `"hybrid"` | Search both memories AND document chunks (recommended) |
153+

0 commit comments

Comments
 (0)