Skip to main content

Migration Guide

This guide helps you upgrade VoltAgent to newer versions with breaking changes.

0.1.x to 1.0.0​

Breaking Changes​

1. LibSQL Moved to Separate Package​

LibSQL storage has been extracted from @voltagent/core into its own package @voltagent/libsql to improve serverless compatibility and reduce bundle size.

Impact: If you're using LibSQLStorage, you'll need to install the new package and update imports.

2. Default Memory Storage Changed​

The default memory storage has changed from LibSQL to InMemoryStorage.

Impact: Agents without explicit memory configuration will now use in-memory storage instead of persistent SQLite storage.

Migration Steps​

If You Need Persistent Storage with LibSQL​

  1. Install the new LibSQL package:
npm install @voltagent/libsql
# or
yarn add @voltagent/libsql
# or
pnpm add @voltagent/libsql
  1. Update your imports:

Before (0.1.x):

import { Agent, LibSQLStorage } from "@voltagent/core";

After (1.0.0):

import { Agent } from "@voltagent/core";
import { LibSQLStorage } from "@voltagent/libsql";
  1. Configure LibSQL explicitly:

Before (0.1.x):

const agent = new Agent({
  name: "Assistant",
  instructions: "You are a helpful assistant",
  // LibSQL was used by default if memory wasn't specified
});

After (1.0.0):

import { LibSQLStorage } from "@voltagent/libsql";
import { createPinoLogger } from "@voltagent/logger";

const logger = createPinoLogger({
  name: "my-app",
  level: "info",
});

const agent = new Agent({
  name: "Assistant",
  instructions: "You are a helpful assistant",
  memory: new LibSQLStorage({
    url: "file:./.voltagent/memory.db", // It's default value
    logger: logger.child({ component: "libsql" }),
  }),
});

If You're Fine with In-Memory Storage​

No changes needed! Your agents will automatically use InMemoryStorage:

const agent = new Agent({
  name: "Assistant",
  instructions: "You are a helpful assistant",
  // memory defaults to InMemoryStorage (no persistence)
});

Note: In-memory storage means conversations are lost when the application restarts.

Why These Changes?​

  1. Serverless Compatibility: Fixes "Cannot find module '@libsql/linux-x64-gnu'" errors in AWS Lambda and other serverless environments
  2. Smaller Core Bundle: Removes native binary dependencies from the core package
  3. Better Defaults: InMemoryStorage works everywhere without configuration
  4. Modular Architecture: Use only the storage backends you actually need

Complete Migration Example​

Here's a full example of migrating an agent with persistent storage:

Before (0.1.x):

import { VoltAgent, Agent, LibSQLStorage } from "@voltagent/core";
import { VercelAIProvider } from "@voltagent/vercel-ai";
import { openai } from "@ai-sdk/openai";

// Option 1: Using default LibSQL
const agent1 = new Agent({
  name: "Default Agent",
  instructions: "A helpful assistant",
  llm: new VercelAIProvider(),
  model: openai("gpt-4o"),
  // Automatically used LibSQL
});

// Option 2: Explicit LibSQL configuration
const agent2 = new Agent({
  name: "Custom Agent",
  instructions: "A helpful assistant",
  llm: new VercelAIProvider(),
  model: openai("gpt-4o"),
  memory: new LibSQLStorage({
    url: "file:./custom.db",
  }),
});

After (1.0.0):

import { VoltAgent, Agent } from "@voltagent/core";
import { LibSQLStorage } from "@voltagent/libsql"; // New import
import { createPinoLogger } from "@voltagent/logger";
import { VercelAIProvider } from "@voltagent/vercel-ai";
import { openai } from "@ai-sdk/openai";

const logger = createPinoLogger({
  name: "my-app",
  level: "info",
});

// Option 1: Must explicitly configure LibSQL if you need persistence
const agent1 = new Agent({
  name: "Default Agent",
  instructions: "A helpful assistant",
  llm: new VercelAIProvider(),
  model: openai("gpt-4o"),
  memory: new LibSQLStorage({
    url: "file:./.voltagent/memory.db",
    logger: logger.child({ component: "libsql" }),
  }),
});

// Option 2: Explicit LibSQL configuration (same pattern, different import)
const agent2 = new Agent({
  name: "Custom Agent",
  instructions: "A helpful assistant",
  llm: new VercelAIProvider(),
  model: openai("gpt-4o"),
  memory: new LibSQLStorage({
    url: "file:./custom.db",
    logger: logger.child({ component: "libsql" }),
  }),
});

Troubleshooting​

Q: My conversations are being lost after upgrading A: You need to explicitly configure LibSQL storage. The default is now in-memory storage which doesn't persist data.

Q: I'm getting "Cannot find module '@voltagent/libsql'" error A: Install the LibSQL package: npm install @voltagent/libsql

Q: Do I need to migrate my existing database files? A: No, existing .db files are compatible. Just update your code to use the new package.

Need Help?​

Table of Contents