@mastra/libsql 1.27.0-alpha.3 → 1.27.0

package/dist/docs/SKILL.md

@@ -3,7 +3,7 @@ name: mastra-libsql
 description: Documentation for @mastra/libsql. Use when working with @mastra/libsql APIs, configuration, or implementation.
 metadata:
   package: "@mastra/libsql"
-  version: "1.27.0-alpha.3"
+  version: "1.27.0"
 ---
 
 ## When to use

package/dist/docs/assets/SOURCE_MAP.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.27.0-alpha.3",
+  "version": "1.27.0",
   "package": "@mastra/libsql",
   "exports": {},
   "modules": {}

package/dist/docs/references/docs-memory-memory-processors.md

@@ -28,13 +28,15 @@ Retrieves message history and persists new messages.
 
 ```typescript
 memory: new Memory({
-  lastMessages: 10,
+  options: {
+    lastMessages: 10,
+  },
 })
 ```
 
 **Mastra internally:**
 
-1. Creates a `MessageHistory` processor with `limit: 10`
+1. Creates a `MessageHistory` processor with `lastMessages: 10`
 2. Adds it to the agent's input processors (runs before the LLM)
 3. Adds it to the agent's output processors (runs after the LLM)
 
@@ -61,7 +63,9 @@ const agent = new Agent({
       id: 'memory-store',
       url: 'file:memory.db',
     }),
-    lastMessages: 10, // MessageHistory processor automatically added
+    options: {
+      lastMessages: 10, // MessageHistory processor automatically added
+    },
   }),
 })
 ```
@@ -85,7 +89,7 @@ memory: new Memory({
 1. Creates a `SemanticRecall` processor
 2. Adds it to the agent's input processors (runs before the LLM)
 3. Adds it to the agent's output processors (runs after the LLM)
-4. Requires both a vector store and embedder to be configured
+4. Requires a vector store, plus an embedder unless the vector store generates embeddings itself
 
 **What it does:**
 
@@ -190,7 +194,9 @@ const agent = new Agent({
   model: 'openai/gpt-5.6-sol',
   memory: new Memory({
     storage: new LibSQLStore({ id: 'memory-store', url: 'file:memory.db' }),
-    lastMessages: 10, // This would normally add MessageHistory(10)
+    options: {
+      lastMessages: 10, // This would normally add MessageHistory(10)
+    },
   }),
   inputProcessors: [
     customMessageHistory, // Your custom one is used instead
@@ -259,7 +265,7 @@ const agent = new Agent({
   name: 'safe-agent',
   instructions: 'You are a helpful assistant',
   model: 'openai/gpt-5.6-sol',
-  memory: new Memory({ lastMessages: 10 }),
+  memory: new Memory({ options: { lastMessages: 10 } }),
   // Your guardrail runs BEFORE memory saves
   outputProcessors: [contentBlocker],
 })
@@ -299,7 +305,7 @@ const agent = new Agent({
   name: 'validated-agent',
   instructions: 'You are a helpful assistant',
   model: 'openai/gpt-5.6-sol',
-  memory: new Memory({ lastMessages: 10 }),
+  memory: new Memory({ options: { lastMessages: 10 } }),
   // Your guardrail runs AFTER memory loads history
   inputProcessors: [inputValidator],
 })
@@ -376,7 +382,7 @@ export const supportAgent = new Agent({
   name: 'Support agent',
   instructions: 'Answer customer support questions.',
   model: 'openai/gpt-5.6-sol',
-  memory: new Memory({ lastMessages: 10 }),
+  memory: new Memory({ options: { lastMessages: 10 } }),
   inputProcessors: [new AttachmentUploader()],
 })
 ```

package/dist/docs/references/docs-memory-semantic-recall.md

@@ -405,6 +405,26 @@ Multilingual E5 produces 1024-dimensional vectors. Your vector index must be cre
 
 FastEmbed models embed at most 512 tokens per input (roughly 2,000 to 2,500 characters of English text). Longer inputs are truncated, so text past the limit doesn't affect the embedding and can't be found by semantic recall. The AI SDK v3 FastEmbed models return a warning when this happens. The legacy v1 and v2 models don't. If you embed long documents with FastEmbed, chunk them to fit the window, for example with `maxSize: 1500` in `MDocument.chunk()`.
 
+### Setting the embedding dimension
+
+To name the vector index, Memory needs the embedder's output dimension. By default it finds the dimension by embedding a short probe string the first time semantic recall is set up, once per `Memory` instance. If you already know the dimension, set `embeddingDimension`. Memory then skips the probe, so startup makes no embedding call and doesn't depend on the embedding provider being reachable:
+
+```ts
+import { Memory } from '@mastra/memory'
+
+const memory = new Memory({
+  embedder: 'openai/text-embedding-3-small',
+  embeddingDimension: 1536,
+  options: {
+    semanticRecall: true,
+  },
+})
+```
+
+The index name is the same whether the dimension is configured or probed, so existing indexes keep working.
+
+The value must match the vectors the embedder returns. Memory compares it with the first real embedding, and on a mismatch it throws a `MASTRA_MEMORY_EMBEDDING_DIMENSION_MISMATCH` error naming both values before creating or querying any index. Update `embeddingDimension` whenever you change the embedding model or its output dimension.
+
 ## PostgreSQL index optimization
 
 When using PostgreSQL as your vector store, you can optimize semantic recall performance by configuring the vector index. This is particularly important for large-scale deployments with thousands of messages.

package/dist/docs/references/docs-memory-working-memory.md

@@ -217,7 +217,7 @@ const paragraphMemory = new Memory({
 
 Working memory can also be defined using a structured schema instead of a Markdown template. A [Standard JSON Schema](https://standardschema.dev/json-schema) ([Zod](https://zod.dev/), [Valibot](https://valibot.dev/), [ArkType](https://arktype.io/), etc.). When using a schema, the agent will see and update working memory as a JSON object matching your schema.
 
-**Requirement:** You must specify either `template` or `schema`, but not both.
+You can specify either `template` or `schema`, but not both. If you omit both, Mastra uses the default working memory template.
 
 ### Example: Schema-Based Working Memory
 

package/dist/docs/references/reference-core-mastra-class.md

@@ -147,9 +147,9 @@ Re-drives every orphaned `running` durable-agent run across all registered durab
 
 Requires persistent storage. With an in-memory store, there's nothing to recover after a process restart.
 
-Agents and their runs are attempted serially. Each built-in `recoverActiveRuns()` attempt waits up to 30 seconds in total for `recover()` setup and settlement of the whole recovered workflow, then traversal can continue to later runs and agents. This isn't an overall recovery deadline: discovery and overridden custom recovery methods aren't bounded by this budget.
+Recovery processes up to five agents concurrently, with up to five run waits per agent, independently of `recovery.workflowConcurrency`. Each built-in `recoverActiveRuns()` attempt waits up to 30 seconds in total for `recover()` setup and settlement of the whole recovered workflow, then frees its slot for another run. These limits bound waiting, not live executions. This isn't an overall recovery deadline: discovery and overridden custom recovery methods aren't bounded by this budget.
 
-A timed-out attempt continues in the background. Its outcome is `status: 'skipped'` with `reason: 'recovery-timeout'` and no `retryAt`. It contributes only to `skipped`, not `recovered`, `succeeded`, or `failed`, and Mastra doesn't automatically retry it. Late settlement doesn't change the returned counts.
+A timed-out attempt continues in the background. Its outcome is `status: 'skipped'` with `reason: 'recovery-timeout'` and a future `retryAt`. It contributes only to `skipped`, not `recovered`, `succeeded`, or `failed`. Mastra schedules re-checks automatically. While the original attempt is pending, re-checks defer without starting another execution. After it settles, recovery checks the persisted snapshot and ownership before retrying; finished or suspended runs aren't restarted. Late settlement doesn't change the returned counts.
 
 When shutdown begins, recovery stops dispatching new agents and runs. The recovery traversal and original attempts, including timed-out setup or execution, participate in the same shared shutdown drain as active executions. A recovery wait timeout doesn't cancel the attempt or give it a separate shutdown drain window.
 

package/dist/docs/references/reference-memory-memory-class.md

@@ -37,6 +37,8 @@ export const agent = new Agent({
 
 **embedder** (`EmbeddingModel<string> | EmbeddingModelV2<string>`): Embedder instance for vector embeddings. Required when semantic recall is enabled.
 
+**embeddingDimension** (`number`): Output dimension of the embedder, as a positive integer. When set, Memory uses it to name the semantic recall index instead of embedding a probe string on first use. It must match the vectors the embedder returns: a mismatch throws a MASTRA\_MEMORY\_EMBEDDING\_DIMENSION\_MISMATCH error before any index is created. See Setting the embedding dimension.
+
 **options** (`MemoryConfig`): Memory configuration options.
 
 **options.lastMessages** (`number | false`): Number of most recent messages to include in context. Set to false to disable the message history feature entirely (messages are not loaded into context or saved). Use Number.MAX\_SAFE\_INTEGER to retrieve all messages with no limit. To load messages without saving new ones, use the readOnly option. The window slides forward on every request, so once a thread exceeds the limit, each turn invalidates the provider prompt cache. For long-running conversations, use Observational Memory instead.

package/dist/index.cjs

@@ -469,12 +469,14 @@ var LibSQLFilterTranslator = class extends _mastra_core_vector_filter.BaseFilter
 		for (const [key, value] of entries) {
 			const newPath = currentPath ? `${currentPath}.${key}` : key;
 			if (this.isLogicalOperator(key)) result[key] = Array.isArray(value) ? value.map((filter) => this.translateNode(filter)) : this.translateNode(value);
-			else if (this.isOperator(key)) if (this.isArrayOperator(key) && !Array.isArray(value) && key !== "$elemMatch") result[key] = [value];
-			else if (this.isBasicOperator(key) && Array.isArray(value)) result[key] = JSON.stringify(value);
-			else result[key] = value;
-			else if (typeof value === "object" && value !== null) if (Object.keys(value).some((k) => this.isOperator(k))) result[newPath] = this.translateNode(value);
-			else Object.assign(result, this.translateNode(value, newPath));
-			else result[newPath] = this.translateNode(value);
+			else if (this.isOperator(key)) {
+				if (this.isArrayOperator(key) && !Array.isArray(value) && key !== "$elemMatch") result[key] = [value];
+				else if (this.isBasicOperator(key) && Array.isArray(value)) result[key] = JSON.stringify(value);
+				else result[key] = value;
+			} else if (typeof value === "object" && value !== null) {
+				if (Object.keys(value).some((k) => this.isOperator(k))) result[newPath] = this.translateNode(value);
+				else Object.assign(result, this.translateNode(value, newPath));
+			} else result[newPath] = this.translateNode(value);
 		}
 		return result;
 	}
@@ -1011,13 +1013,11 @@ var LibSQLVector = class extends _mastra_core_vector.MastraVector {
 				this.logger.warn("LibSQLVector: indexed query failed, falling back to brute-force", err);
 			}
 			const { sql: filterQuery, values: filterValues } = buildFilterQuery(this.transformFilter(filter));
-			filterValues.push(minScore);
-			filterValues.push(topK);
 			const query = `
       WITH vector_scores AS (
         SELECT
           vector_id as id,
-          (1-vector_distance_cos(embedding, '${vectorStr}')) as score,
+          (1-vector_distance_cos(embedding, vector32(?))) as score,
           metadata
           ${includeVector ? ", vector_extract(embedding) as embedding" : ""}
         FROM ${parsedIndexName}
@@ -1030,7 +1030,12 @@ var LibSQLVector = class extends _mastra_core_vector.MastraVector {
       LIMIT ?`;
 			return (await this.turso.execute({
 				sql: query,
-				args: filterValues
+				args: [
+					vectorStr,
+					...filterValues,
+					minScore,
+					topK
+				]
 			})).rows.map(({ id, score, metadata, embedding }) => ({
 				id,
 				score,
@@ -1530,10 +1535,11 @@ async function assertRunFence(tx, { claimsTable, fence, operation }) {
 		sql: `SELECT generation, ownerId FROM ${claimsTable} WHERE runId = ?`,
 		args: [fence.runId]
 	})).rows[0];
-	if (!(0, _mastra_core_storage.matchesRunFence)(row ? {
+	const current = row ? {
 		generation: Number(row.generation),
 		ownerId: String(row.ownerId)
-	} : null, fence)) throw new _mastra_core_storage.RunFenceConflictError(fence, operation);
+	} : null;
+	if (!(0, _mastra_core_storage.matchesRunFence)(current, fence)) throw new _mastra_core_storage.RunFenceConflictError(fence, operation);
 }
 /**
 * Runs `write` behind the client's write lock: directly when there is no
@@ -2267,7 +2273,8 @@ var LibSQLDB = class extends _mastra_core_base.MastraBase {
 			const existingColumns = new Set([...existingColumnsRaw].map((column) => column.toLowerCase()));
 			let addedColumns = false;
 			for (const [columnName, columnDef] of Object.entries(schema)) if (!existingColumns.has(columnName.toLowerCase())) {
-				const alterSql = `ALTER TABLE "${_mastra_core_storage.TABLE_SPANS}" ADD COLUMN "${columnName}" ${this.getSqlType(columnDef.type)}`;
+				const sqlType = this.getSqlType(columnDef.type);
+				const alterSql = `ALTER TABLE "${_mastra_core_storage.TABLE_SPANS}" ADD COLUMN "${columnName}" ${sqlType}`;
 				await this.client.execute(alterSql);
 				addedColumns = true;
 				this.logger.debug(`LibSQLDB: Added column '${columnName}' to ${_mastra_core_storage.TABLE_SPANS}`);
@@ -3534,15 +3541,19 @@ var BackgroundTasksLibSQL = class BackgroundTasksLibSQL extends _mastra_core_sto
 			where += " AND status = ?";
 			params.push(options.expectedStatus);
 		}
-		if (options?.expectedOwnerId !== void 0) if (options.expectedOwnerId === null) where += " AND ownerId IS NULL";
-		else {
-			where += " AND ownerId = ?";
-			params.push(options.expectedOwnerId);
+		if (options?.expectedOwnerId !== void 0) {
+			if (options.expectedOwnerId === null) where += " AND ownerId IS NULL";
+			else {
+				where += " AND ownerId = ?";
+				params.push(options.expectedOwnerId);
+			}
 		}
-		if (options?.expectedLeaseExpiresAt !== void 0) if (options.expectedLeaseExpiresAt === null) where += " AND leaseExpiresAt IS NULL";
-		else {
-			where += " AND leaseExpiresAt = ?";
-			params.push(options.expectedLeaseExpiresAt.toISOString());
+		if (options?.expectedLeaseExpiresAt !== void 0) {
+			if (options.expectedLeaseExpiresAt === null) where += " AND leaseExpiresAt IS NULL";
+			else {
+				where += " AND leaseExpiresAt = ?";
+				params.push(options.expectedLeaseExpiresAt.toISOString());
+			}
 		}
 		return (await this.#client.execute({
 			sql: `UPDATE ${_mastra_core_storage.TABLE_BACKGROUND_TASKS} SET ${setClauses.join(", ")} WHERE ${where}`,
@@ -10102,7 +10113,8 @@ var MemoryLibSQL = class MemoryLibSQL extends _mastra_core_storage.MemoryStorage
 	}
 	async #updateMessages(writer, messages) {
 		const messageIds = messages.map((m) => m.id);
-		const selectSql = `SELECT * FROM ${_mastra_core_storage.TABLE_MESSAGES} WHERE id IN (${messageIds.map(() => "?").join(",")})`;
+		const placeholders = messageIds.map(() => "?").join(",");
+		const selectSql = `SELECT * FROM ${_mastra_core_storage.TABLE_MESSAGES} WHERE id IN (${placeholders})`;
 		const existingMessages = (await writer.execute({
 			sql: selectSql,
 			args: messageIds
@@ -10413,7 +10425,8 @@ var MemoryLibSQL = class MemoryLibSQL extends _mastra_core_storage.MemoryStorage
 					valueType: typeof value
 				}
 			});
-			const baseQuery = `FROM ${_mastra_core_storage.TABLE_THREADS} ${whereClauses.length > 0 ? `WHERE ${whereClauses.join(" AND ")}` : ""}`;
+			const whereClause = whereClauses.length > 0 ? `WHERE ${whereClauses.join(" AND ")}` : "";
+			const baseQuery = `FROM ${_mastra_core_storage.TABLE_THREADS} ${whereClause}`;
 			const mapRowToStorageThreadType = (row) => ({
 				id: row.id,
 				resourceId: row.resourceId,
@@ -12487,18 +12500,18 @@ var ObservabilityLibSQL = class ObservabilityLibSQL extends _mastra_core_storage
 					case _mastra_core_storage.TraceStatus.RUNNING:
 						conditions.push(`endedAt IS NULL AND error IS NULL`);
 						break;
-					case _mastra_core_storage.TraceStatus.SUCCESS:
-						conditions.push(`endedAt IS NOT NULL AND error IS NULL`);
-						break;
+					case _mastra_core_storage.TraceStatus.SUCCESS: conditions.push(`endedAt IS NOT NULL AND error IS NULL`);
 				}
-				if (filters.hasChildError !== void 0) if (filters.hasChildError) conditions.push(`EXISTS (
+				if (filters.hasChildError !== void 0) {
+					if (filters.hasChildError) conditions.push(`EXISTS (
               SELECT 1 FROM ${tableName} c
               WHERE c.traceId = ${tableName}.traceId AND c.error IS NOT NULL
             )`);
-				else conditions.push(`NOT EXISTS (
+					else conditions.push(`NOT EXISTS (
               SELECT 1 FROM ${tableName} c
               WHERE c.traceId = ${tableName}.traceId AND c.error IS NOT NULL
             )`);
+				}
 			}
 			const whereClause = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
 			const sortField = orderBy?.field ?? "startedAt";
@@ -13247,15 +13260,19 @@ var SchedulesLibSQL = class SchedulesLibSQL extends _mastra_core_storage.Schedul
 			conditions.push("json_extract(target, '$.workflowId') = ?");
 			params.push(filter.workflowId);
 		}
-		if (filter?.ownerType !== void 0) if (filter.ownerType === null) conditions.push("owner_type IS NULL");
-		else {
-			conditions.push("owner_type = ?");
-			params.push(filter.ownerType);
+		if (filter?.ownerType !== void 0) {
+			if (filter.ownerType === null) conditions.push("owner_type IS NULL");
+			else {
+				conditions.push("owner_type = ?");
+				params.push(filter.ownerType);
+			}
 		}
-		if (filter?.ownerId !== void 0) if (filter.ownerId === null) conditions.push("owner_id IS NULL");
-		else {
-			conditions.push("owner_id = ?");
-			params.push(filter.ownerId);
+		if (filter?.ownerId !== void 0) {
+			if (filter.ownerId === null) conditions.push("owner_id IS NULL");
+			else {
+				conditions.push("owner_id = ?");
+				params.push(filter.ownerId);
+			}
 		}
 		const where = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
 		return (await this.#client.execute({
@@ -15678,10 +15695,12 @@ var WorkflowsLibSQL = class WorkflowsLibSQL extends _mastra_core_storage.Workflo
 				conditions.push("createdAt <= ?");
 				args.push(toDate.toISOString());
 			}
-			if (resourceId) if (await this.#db.hasColumn(_mastra_core_storage.TABLE_WORKFLOW_SNAPSHOT, "resourceId")) {
-				conditions.push("resourceId = ?");
-				args.push(resourceId);
-			} else this.logger.warn(`[${_mastra_core_storage.TABLE_WORKFLOW_SNAPSHOT}] resourceId column not found. Skipping resourceId filter.`);
+			if (resourceId) {
+				if (await this.#db.hasColumn(_mastra_core_storage.TABLE_WORKFLOW_SNAPSHOT, "resourceId")) {
+					conditions.push("resourceId = ?");
+					args.push(resourceId);
+				} else this.logger.warn(`[${_mastra_core_storage.TABLE_WORKFLOW_SNAPSHOT}] resourceId column not found. Skipping resourceId filter.`);
+			}
 			if (threadId) {
 				conditions.push(`(EXISTS (SELECT 1 FROM json_each(snapshot, '$.context') AS je WHERE json_extract(je.value, '$.status') = 'suspended' AND json_extract(je.value, '$.suspendPayload.__streamState.messageList.memoryInfo.threadId') = ?) OR json_extract(snapshot, '$.context.input.messageListState.memoryInfo.threadId') = ?)`);
 				args.push(threadId, threadId);