docs/src/content/en/reference/vectors/libsql.mdx
The libSQL storage implementation provides a SQLite-compatible vector search libSQL, a fork of SQLite with vector extensions, and Turso with vector extensions, offering a lightweight and efficient vector database solution.
It's part of the @mastra/libsql package and offers efficient vector similarity search with metadata filtering.
npm install @mastra/libsql@latest
import { LibSQLVector } from "@mastra/libsql";
// Create a new vector store instance
const store = new LibSQLVector({
id: 'libsql-vector',
url: process.env.DATABASE_URL,
// Optional: for Turso cloud databases
authToken: process.env.DATABASE_AUTH_TOKEN,
});
// Create an index
await store.createIndex({
indexName: "myCollection",
dimension: 1536,
});
// Add vectors with metadata
const vectors = [[0.1, 0.2, ...], [0.3, 0.4, ...]];
const metadata = [
{ text: "first document", category: "A" },
{ text: "second document", category: "B" }
];
await store.upsert({
indexName: "myCollection",
vectors,
metadata,
});
// Query similar vectors
const queryVector = [0.1, 0.2, ...];
const results = await store.query({
indexName: "myCollection",
queryVector,
topK: 10, // top K results
filter: { category: "A" } // optional metadata filter
});
<PropertiesTable content={[ { name: 'url', type: 'string', description: "libSQL database URL. Use ':memory:' for in-memory database, 'file:dbname.db' for local file, or a libSQL-compatible connection string like 'libsql://your-database.turso.io'.", }, { name: 'authToken', type: 'string', isOptional: true, description: 'Authentication token for Turso cloud databases', }, { name: 'syncUrl', type: 'string', isOptional: true, description: 'URL for database replication (Turso specific)', }, { name: 'syncInterval', type: 'number', isOptional: true, description: 'Interval in milliseconds for database sync (Turso specific)', }, ]} />
createIndex()Creates a new vector collection. The index name must start with a letter or underscore and can only contain letters, numbers, and underscores. The dimension must be a positive integer.
<PropertiesTable content={[ { name: 'indexName', type: 'string', description: 'Name of the index to create', }, { name: 'dimension', type: 'number', description: 'Vector dimension size (must match your embedding model)', }, { name: 'metric', type: "'cosine' | 'euclidean' | 'dotproduct'", isOptional: true, defaultValue: 'cosine', description: 'Distance metric for similarity search. Note: Currently only cosine similarity is supported by libSQL.', }, ]} />
upsert()Adds or updates vectors and their metadata in the index. Uses a transaction to ensure all vectors are inserted atomically - if any insert fails, the entire operation is rolled back.
<PropertiesTable content={[ { name: 'indexName', type: 'string', description: 'Name of the index to insert into', }, { name: 'vectors', type: 'number[][]', description: 'Array of embedding vectors', }, { name: 'metadata', type: 'Record<string, any>[]', isOptional: true, description: 'Metadata for each vector', }, { name: 'ids', type: 'string[]', isOptional: true, description: 'Optional vector IDs (auto-generated if not provided)', }, ]} />
query()Searches for similar vectors with optional metadata filtering.
<PropertiesTable content={[ { name: 'indexName', type: 'string', description: 'Name of the index to search in', }, { name: 'queryVector', type: 'number[]', description: 'Query vector to find similar vectors for', }, { name: 'topK', type: 'number', isOptional: true, defaultValue: '10', description: 'Number of results to return', }, { name: 'filter', type: 'Filter', isOptional: true, description: 'Metadata filters', }, { name: 'includeVector', type: 'boolean', isOptional: true, defaultValue: 'false', description: 'Whether to include vector data in results', }, { name: 'minScore', type: 'number', isOptional: true, defaultValue: '0', description: 'Minimum similarity score threshold', }, ]} />
describeIndex()Gets information about an index.
<PropertiesTable content={[ { name: 'indexName', type: 'string', description: 'Name of the index to describe', }, ]} />
Returns:
interface IndexStats {
dimension: number
count: number
metric: 'cosine' | 'euclidean' | 'dotproduct'
}
deleteIndex()Deletes an index and all its data.
<PropertiesTable content={[ { name: 'indexName', type: 'string', description: 'Name of the index to delete', }, ]} />
listIndexes()Lists all vector indexes in the database.
Returns: Promise<string[]>
truncateIndex()Removes all vectors from an index while keeping the index structure.
<PropertiesTable content={[ { name: 'indexName', type: 'string', description: 'Name of the index to truncate', }, ]} />
updateVector()Update a single vector by ID or by metadata filter. Either id or filter must be provided, but not both.
<PropertiesTable content={[ { name: 'indexName', type: 'string', description: 'Name of the index containing the vector', }, { name: 'id', type: 'string', isOptional: true, description: 'ID of the vector entry to update (mutually exclusive with filter)', }, { name: 'filter', type: 'Record<string, any>', isOptional: true, description: 'Metadata filter to identify vector(s) to update (mutually exclusive with id)', }, { name: 'update', type: 'object', description: 'Update data containing vector and/or metadata', }, { name: 'update.vector', type: 'number[]', isOptional: true, description: 'New vector data to update', }, { name: 'update.metadata', type: 'Record<string, any>', isOptional: true, description: 'New metadata to update', }, ]} />
deleteVector()Deletes a specific vector entry from an index by its ID.
<PropertiesTable content={[ { name: 'indexName', type: 'string', description: 'Name of the index containing the vector', }, { name: 'id', type: 'string', description: 'ID of the vector entry to delete', }, ]} />
deleteVectors()Delete multiple vectors by IDs or by metadata filter. Either ids or filter must be provided, but not both.
<PropertiesTable content={[ { name: 'indexName', type: 'string', description: 'Name of the index containing the vectors to delete', }, { name: 'ids', type: 'string[]', isOptional: true, description: 'Array of vector IDs to delete (mutually exclusive with filter)', }, { name: 'filter', type: 'Record<string, any>', isOptional: true, description: 'Metadata filter to identify vectors to delete (mutually exclusive with ids)', }, ]} />
Query results are returned in this format:
interface QueryResult {
id: string
score: number
metadata: Record<string, any>
vector?: number[] // Only included if includeVector is true
}
The store throws specific errors for different failure cases:
try {
await store.query({
indexName: 'my-collection',
queryVector: queryVector,
})
} catch (error) {
// Handle specific error cases
if (error.message.includes('Invalid index name format')) {
console.error(
'Index name must start with a letter/underscore and contain only alphanumeric characters',
)
} else if (error.message.includes('Table not found')) {
console.error('The specified index does not exist')
} else {
console.error('Vector store error:', error.message)
}
}
Common error cases include:
Embeddings are numeric vectors used by memory's semanticRecall to retrieve related messages by meaning (not keywords). This setup uses @mastra/fastembed to generate vector embeddings.
Install fastembed to get started:
npm install @mastra/fastembed@latest
Add the following to your agent:
import { Memory } from '@mastra/memory'
import { Agent } from '@mastra/core/agent'
import { LibSQLStore, LibSQLVector } from '@mastra/libsql'
import { fastembed } from '@mastra/fastembed'
export const libsqlAgent = new Agent({
id: 'libsql-agent',
name: 'libSQL Agent',
instructions:
'You are an AI agent with the ability to automatically recall memories from previous interactions.',
model: 'openai/gpt-5.4',
memory: new Memory({
storage: new LibSQLStore({
id: 'libsql-agent-storage',
url: 'file:libsql-agent.db',
}),
vector: new LibSQLVector({
id: 'libsql-agent-vector',
url: 'file:libsql-agent.db',
}),
embedder: fastembed,
options: {
lastMessages: 10,
semanticRecall: {
topK: 3,
messageRange: 2,
},
generateTitle: true, // Explicitly enable automatic title generation
},
}),
})