libSQL Storage

libSQL is an open-source, SQLite-compatible database that supports both local and remote deployments. It can be used to store message history, workflow snapshots, traces, and eval scores.

For vectors like semantic recall or traditional RAG, use libSQL Vector which covers embeddings and vector search.

Installation

Storage providers must be installed as separate packages:

npm

npm install @mastra/libsql@latest

pnpm

pnpm add @mastra/libsql@latest

Yarn

yarn add @mastra/libsql@latest

Bun

bun add @mastra/libsql@latest

Usage

import { LibSQLStore } from "@mastra/libsql";
import { Mastra } from "@mastra/core";

const mastra = new Mastra({
  storage: new LibSQLStore({
    id: 'libsql-storage',
    url: "file:./storage.db",
  }),
});

Agent-level file storage:

import { Memory } from "@mastra/memory";
import { Agent } from "@mastra/core/agent";
import { LibSQLStore } from "@mastra/libsql";

export const agent = new Agent({
  id: "example-agent",
  memory: new Memory({
    storage: new LibSQLStore({
      id: 'libsql-storage',
      url: "file:./agent.db",
    }),
  }),
});

warning

File storage doesn't work with serverless platforms that have ephemeral file systems. For serverless deployments, use Turso or a different database engine.

Production with remote database:

storage: new LibSQLStore({
  id: 'libsql-storage',
  url: "libsql://your-db-name.aws-ap-northeast-1.turso.io",
  authToken: process.env.TURSO_AUTH_TOKEN,
})

For local development and testing, you can store data in memory:

storage: new LibSQLStore({
  id: 'libsql-storage',
  url: ":memory:",
})

warning

In-memory storage resets when the process changes. Only suitable for development.

Options

url:

string

Database URL. Use `:memory:` for in-memory database, `file:filename.db` for a file database, or a libSQL connection string (e.g., `libsql://your-database.turso.io`) for remote storage.

authToken?:

string

Authentication token for remote libSQL databases.

Initialization

When you pass storage to the Mastra class, init() is called automatically to create the core schema:

import { Mastra } from "@mastra/core";
import { LibSQLStore } from "@mastra/libsql";

const storage = new LibSQLStore({
  id: 'libsql-storage',
  url: "file:./storage.db",
});

const mastra = new Mastra({
  storage, // init() called automatically
});

If using storage directly without Mastra, call init() explicitly:

import { LibSQLStore } from "@mastra/libsql";

const storage = new LibSQLStore({
  id: 'libsql-storage',
  url: "file:./storage.db",
});

await storage.init();

// Access domain-specific stores via getStore()
const memoryStore = await storage.getStore('memory');
const thread = await memoryStore?.getThreadById({ threadId: "..." });

Observability

libSQL supports observability and is ideal for local development. Use the realtime tracing strategy for immediate visibility while debugging.

For production environments with higher trace volumes, consider using PostgreSQL or ClickHouse via composite storage.