@mastra/libsql 1.2.0-alpha.0 → 1.3.0-alpha.0

package/dist/docs/references/reference-storage-libsql.md

@@ -0,0 +1,135 @@
+# libSQL Storage
+
+[libSQL](https://docs.turso.tech/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](https://mastra.ai/reference/vectors/libsql) which covers embeddings and vector search.
+
+## Installation
+
+Storage providers must be installed as separate packages:
+
+**npm**:
+
+```bash
+npm install @mastra/libsql@latest
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/libsql@latest
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/libsql@latest
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/libsql@latest
+```
+
+## Usage
+
+```typescript
+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:
+
+```typescript
+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](https://turso.tech) or a different database engine.
+
+Production with remote database:
+
+```typescript
+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:
+
+```typescript
+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](https://mastra.ai/reference/storage/overview):
+
+```typescript
+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:
+
+```typescript
+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](https://mastra.ai/docs/observability/tracing/exporters/default) for immediate visibility while debugging.
+
+For production environments with higher trace volumes, consider using [PostgreSQL](https://mastra.ai/reference/storage/postgresql) or [ClickHouse via composite storage](https://mastra.ai/reference/storage/composite).

package/dist/docs/{vectors/01-reference.md → references/reference-vectors-libsql.md}

@@ -1,21 +1,31 @@
-# Vectors API Reference
+# libSQL Vector Store
 
-> API reference for vectors - 1 entries
+The libSQL storage implementation provides a SQLite-compatible vector search [libSQL](https://github.com/tursodatabase/libsql), a fork of SQLite with vector extensions, and [Turso](https://turso.tech/) 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.
 
+## Installation
 
----
+**npm**:
 
-## Reference: libSQL Vector Store
+```bash
+npm install @mastra/libsql@latest
+```
 
-> Documentation for the LibSQLVector class in Mastra, which provides vector search using libSQL with vector extensions.
+**pnpm**:
 
-The libSQL storage implementation provides a SQLite-compatible vector search [libSQL](https://github.com/tursodatabase/libsql), a fork of SQLite with vector extensions, and [Turso](https://turso.tech/) 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.
+```bash
+pnpm add @mastra/libsql@latest
+```
 
-## Installation
+**Yarn**:
 
-```bash npm2yarn
-npm install @mastra/libsql@latest
+```bash
+yarn add @mastra/libsql@latest
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/libsql@latest
 ```
 
 ## Usage
@@ -61,24 +71,60 @@ const results = await store.query({
 
 ## Constructor Options
 
+**url:** (`string`): 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'.
+
+**authToken?:** (`string`): Authentication token for Turso cloud databases
+
+**syncUrl?:** (`string`): URL for database replication (Turso specific)
+
+**syncInterval?:** (`number`): Interval in milliseconds for database sync (Turso specific)
+
 ## Methods
 
 ### 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.
 
+**indexName:** (`string`): Name of the index to create
+
+**dimension:** (`number`): Vector dimension size (must match your embedding model)
+
+**metric?:** (`'cosine' | 'euclidean' | 'dotproduct'`): Distance metric for similarity search. Note: Currently only cosine similarity is supported by libSQL. (Default: `cosine`)
+
 ### 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.
 
+**indexName:** (`string`): Name of the index to insert into
+
+**vectors:** (`number[][]`): Array of embedding vectors
+
+**metadata?:** (`Record<string, any>[]`): Metadata for each vector
+
+**ids?:** (`string[]`): Optional vector IDs (auto-generated if not provided)
+
 ### query()
 
 Searches for similar vectors with optional metadata filtering.
 
+**indexName:** (`string`): Name of the index to search in
+
+**queryVector:** (`number[]`): Query vector to find similar vectors for
+
+**topK?:** (`number`): Number of results to return (Default: `10`)
+
+**filter?:** (`Filter`): Metadata filters
+
+**includeVector?:** (`boolean`): Whether to include vector data in results (Default: `false`)
+
+**minScore?:** (`number`): Minimum similarity score threshold (Default: `0`)
+
 ### describeIndex()
 
 Gets information about an index.
 
+**indexName:** (`string`): Name of the index to describe
+
 Returns:
 
 ```typescript
@@ -93,6 +139,8 @@ interface IndexStats {
 
 Deletes an index and all its data.
 
+**indexName:** (`string`): Name of the index to delete
+
 ### listIndexes()
 
 Lists all vector indexes in the database.
@@ -103,18 +151,42 @@ Returns: `Promise<string[]>`
 
 Removes all vectors from an index while keeping the index structure.
 
+**indexName:** (`string`): 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.
 
+**indexName:** (`string`): Name of the index containing the vector
+
+**id?:** (`string`): ID of the vector entry to update (mutually exclusive with filter)
+
+**filter?:** (`Record<string, any>`): Metadata filter to identify vector(s) to update (mutually exclusive with id)
+
+**update:** (`object`): Update data containing vector and/or metadata
+
+**update.vector?:** (`number[]`): New vector data to update
+
+**update.metadata?:** (`Record<string, any>`): New metadata to update
+
 ### deleteVector()
 
 Deletes a specific vector entry from an index by its ID.
 
+**indexName:** (`string`): Name of the index containing the vector
+
+**id:** (`string`): 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.
 
+**indexName:** (`string`): Name of the index containing the vectors to delete
+
+**ids?:** (`string[]`): Array of vector IDs to delete (mutually exclusive with filter)
+
+**filter?:** (`Record<string, any>`): Metadata filter to identify vectors to delete (mutually exclusive with ids)
+
 ## Response Types
 
 Query results are returned in this format:
@@ -168,13 +240,33 @@ Embeddings are numeric vectors used by memory's `semanticRecall` to retrieve rel
 
 Install `fastembed` to get started:
 
-```bash npm2yarn
+**npm**:
+
+```bash
 npm install @mastra/fastembed@latest
 ```
 
+**pnpm**:
+
+```bash
+pnpm add @mastra/fastembed@latest
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/fastembed@latest
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/fastembed@latest
+```
+
 Add the following to your agent:
 
-```typescript title="src/mastra/agents/example-libsql-agent.ts"
+```typescript
 import { Memory } from "@mastra/memory";
 import { Agent } from "@mastra/core/agent";
 import { LibSQLStore, LibSQLVector } from "@mastra/libsql";
@@ -210,4 +302,4 @@ export const libsqlAgent = new Agent({
 
 ## Related
 
-- [Metadata Filters](../rag/metadata-filters)
+- [Metadata Filters](https://mastra.ai/reference/rag/metadata-filters)