@mastra/libsql 1.8.1 → 1.9.0-alpha.1

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # @mastra/libsql
 
+## 1.9.0-alpha.1
+
+### Minor Changes
+
+- Use DiskANN vector_top_k() index for faster vector queries when available ([#14913](https://github.com/mastra-ai/mastra/pull/14913))
+
+  LibSQLVector.query() now automatically uses the existing DiskANN index for approximate nearest neighbor search instead of brute-force full table scans, providing 10-25x query speedups on larger datasets. Falls back to brute-force when no index exists.
+
+### Patch Changes
+
+- Updated dependencies [[`16e34ca`](https://github.com/mastra-ai/mastra/commit/16e34caa98b9a114b17a6125e4e3fd87f169d0d0)]:
+  - @mastra/core@1.26.0-alpha.9
+
+## 1.8.2-alpha.0
+
+### Patch Changes
+
+- Add `BackgroundTasksStorage` domain implementation so `@mastra/core` background task execution works with any storage adapter. ([#15307](https://github.com/mastra-ai/mastra/pull/15307))
+
+- Updated dependencies [[`d63ffdb`](https://github.com/mastra-ai/mastra/commit/d63ffdbb2c11e76fe5ea45faab44bc15460f010c)]:
+  - @mastra/core@1.25.1-alpha.0
+
 ## 1.8.1
 
 ### Patch Changes

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.8.1"
+  version: "1.9.0-alpha.1"
 ---
 
 ## When to use

package/dist/docs/assets/SOURCE_MAP.json

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

package/dist/index.cjs

@@ -511,6 +511,9 @@ var LibSQLVector = class extends vector.MastraVector {
   turso;
   maxRetries;
   initialBackoffMs;
+  overFetchMultiplier;
+  isMemoryDb;
+  vectorIndexes;
   constructor({
     url,
     authToken,
@@ -518,6 +521,7 @@ var LibSQLVector = class extends vector.MastraVector {
     syncInterval,
     maxRetries = 5,
     initialBackoffMs = 100,
+    vectorTopKOverFetchMultiplier = 10,
     id
   }) {
     super({ id });
@@ -529,10 +533,27 @@ var LibSQLVector = class extends vector.MastraVector {
     });
     this.maxRetries = maxRetries;
     this.initialBackoffMs = initialBackoffMs;
-    if (url.includes(`file:`) || url.includes(`:memory:`)) {
+    if (!Number.isInteger(vectorTopKOverFetchMultiplier) || vectorTopKOverFetchMultiplier < 1) {
+      throw new Error("vectorTopKOverFetchMultiplier must be a positive integer");
+    }
+    this.overFetchMultiplier = vectorTopKOverFetchMultiplier;
+    this.isMemoryDb = url.includes(":memory:");
+    if (url.includes(`file:`) || this.isMemoryDb) {
       this.turso.execute("PRAGMA journal_mode=WAL;").then(() => this.logger.debug("LibSQLStore: PRAGMA journal_mode=WAL set.")).catch((err) => this.logger.warn("LibSQLStore: Failed to set PRAGMA journal_mode=WAL.", err));
       this.turso.execute("PRAGMA busy_timeout = 5000;").then(() => this.logger.debug("LibSQLStore: PRAGMA busy_timeout=5000 set.")).catch((err) => this.logger.warn("LibSQLStore: Failed to set PRAGMA busy_timeout=5000.", err));
     }
+    this.vectorIndexes = this.isMemoryDb ? Promise.resolve(/* @__PURE__ */ new Set()) : this.discoverVectorIndexes();
+  }
+  async discoverVectorIndexes() {
+    try {
+      const result = await this.turso.execute({
+        sql: `SELECT name FROM sqlite_master WHERE type='index' AND name LIKE '%_vector_idx'`,
+        args: []
+      });
+      return new Set(result.rows.map((row) => row.name));
+    } catch {
+      return /* @__PURE__ */ new Set();
+    }
   }
   async executeWriteOperationWithRetry(operation, isTransaction = false) {
     let attempts = 0;
@@ -566,6 +587,40 @@ var LibSQLVector = class extends vector.MastraVector {
     const translator = new LibSQLFilterTranslator();
     return translator.translate(filter);
   }
+  async hasVectorIndex(parsedIndexName) {
+    const indexes = await this.vectorIndexes;
+    return indexes.has(`${parsedIndexName}_vector_idx`);
+  }
+  async queryWithIndex(parsedIndexName, vectorStr, topK, filter, includeVector, minScore) {
+    const translatedFilter = this.transformFilter(filter);
+    const { sql: filterQuery, values: filterValues } = buildFilterQuery(translatedFilter);
+    const hasFilter = filterQuery.length > 0;
+    const fetchCount = hasFilter ? topK * this.overFetchMultiplier : topK * 2;
+    const embeddingSelect = includeVector ? ", vector_extract(t.embedding) as embedding" : "";
+    const filterCondition = hasFilter ? filterQuery.replace(/^\s*WHERE\s+/i, "") : "";
+    const whereClause = hasFilter ? `WHERE ${filterCondition} AND score > ?` : "WHERE score > ?";
+    const query = `
+      WITH candidates AS (
+        SELECT t.vector_id AS id,
+               (1 - vector_distance_cos(t.embedding, vector32(?))) AS score,
+               t.metadata
+               ${embeddingSelect}
+        FROM vector_top_k('${parsedIndexName}_vector_idx', vector32(?), ?) AS v
+        JOIN "${parsedIndexName}" AS t ON t.rowid = v.id
+      )
+      SELECT * FROM candidates
+      ${whereClause}
+      ORDER BY score DESC
+      LIMIT ?`;
+    const args = [vectorStr, vectorStr, fetchCount, ...filterValues, minScore, topK];
+    const result = await this.turso.execute({ sql: query, args });
+    return result.rows.map(({ id, score, metadata, embedding }) => ({
+      id,
+      score,
+      metadata: JSON.parse(metadata ?? "{}"),
+      ...includeVector && embedding && { vector: JSON.parse(embedding) }
+    }));
+  }
   async query({
     indexName,
     queryVector,
@@ -596,6 +651,23 @@ var LibSQLVector = class extends vector.MastraVector {
     try {
       const parsedIndexName = utils.parseSqlIdentifier(indexName, "index name");
       const vectorStr = `[${queryVector.join(",")}]`;
+      if (!this.isMemoryDb && await this.hasVectorIndex(parsedIndexName)) {
+        try {
+          const indexedResults = await this.queryWithIndex(
+            parsedIndexName,
+            vectorStr,
+            topK,
+            filter,
+            includeVector,
+            minScore
+          );
+          if (!filter || indexedResults.length >= topK) {
+            return indexedResults;
+          }
+        } catch (err) {
+          this.logger.warn("LibSQLVector: indexed query failed, falling back to brute-force", err);
+        }
+      }
       const translatedFilter = this.transformFilter(filter);
       const { sql: filterQuery, values: filterValues } = buildFilterQuery(translatedFilter);
       filterValues.push(minScore);
@@ -729,6 +801,7 @@ var LibSQLVector = class extends vector.MastraVector {
         `,
       args: []
     });
+    void this.vectorIndexes.then((indexes) => indexes.add(`${parsedIndexName}_vector_idx`));
   }
   deleteIndex(args) {
     try {
@@ -751,6 +824,7 @@ var LibSQLVector = class extends vector.MastraVector {
       sql: `DROP TABLE IF EXISTS ${parsedIndexName}`,
       args: []
     });
+    void this.vectorIndexes.then((indexes) => indexes.delete(`${parsedIndexName}_vector_idx`));
   }
   async listIndexes() {
     try {
@@ -2884,6 +2958,235 @@ var AgentsLibSQL = class extends storage.AgentsStorage {
     };
   }
 };
+function serializeJson(v) {
+  if (typeof v === "object" && v != null) return JSON.stringify(v);
+  return v ?? null;
+}
+function parseJson(val) {
+  if (val == null) return void 0;
+  if (typeof val === "string") {
+    try {
+      return JSON.parse(val);
+    } catch {
+      return val;
+    }
+  }
+  return val;
+}
+function rowToTask(row) {
+  return {
+    id: String(row.id),
+    status: String(row.status),
+    toolName: String(row.tool_name),
+    toolCallId: String(row.tool_call_id),
+    args: parseJson(row.args) ?? {},
+    agentId: String(row.agent_id),
+    threadId: row.thread_id != null ? String(row.thread_id) : void 0,
+    resourceId: row.resource_id != null ? String(row.resource_id) : void 0,
+    runId: String(row.run_id),
+    result: parseJson(row.result),
+    error: parseJson(row.error),
+    retryCount: Number(row.retry_count),
+    maxRetries: Number(row.max_retries),
+    timeoutMs: Number(row.timeout_ms),
+    createdAt: new Date(String(row.createdAt)),
+    startedAt: row.startedAt ? new Date(String(row.startedAt)) : void 0,
+    completedAt: row.completedAt ? new Date(String(row.completedAt)) : void 0
+  };
+}
+var BackgroundTasksLibSQL = class extends storage.BackgroundTasksStorage {
+  #db;
+  #client;
+  constructor(config) {
+    super();
+    const client = resolveClient(config);
+    this.#client = client;
+    this.#db = new LibSQLDB({ client, maxRetries: config.maxRetries, initialBackoffMs: config.initialBackoffMs });
+  }
+  async init() {
+    await this.#db.createTable({
+      tableName: storage.TABLE_BACKGROUND_TASKS,
+      schema: storage.TABLE_SCHEMAS[storage.TABLE_BACKGROUND_TASKS]
+    });
+  }
+  async dangerouslyClearAll() {
+    await this.#db.deleteData({ tableName: storage.TABLE_BACKGROUND_TASKS });
+  }
+  async createTask(task) {
+    await this.#db.insert({
+      tableName: storage.TABLE_BACKGROUND_TASKS,
+      record: {
+        id: task.id,
+        tool_call_id: task.toolCallId,
+        tool_name: task.toolName,
+        agent_id: task.agentId,
+        thread_id: task.threadId ?? null,
+        resource_id: task.resourceId ?? null,
+        run_id: task.runId,
+        status: task.status,
+        args: task.args,
+        result: task.result ?? null,
+        error: task.error ?? null,
+        retry_count: task.retryCount,
+        max_retries: task.maxRetries,
+        timeout_ms: task.timeoutMs,
+        createdAt: task.createdAt.toISOString(),
+        startedAt: task.startedAt?.toISOString() ?? null,
+        completedAt: task.completedAt?.toISOString() ?? null
+      }
+    });
+  }
+  async updateTask(taskId, update) {
+    const setClauses = [];
+    const params = [];
+    if ("status" in update) {
+      setClauses.push("status = ?");
+      params.push(update.status);
+    }
+    if ("result" in update) {
+      setClauses.push("result = jsonb(?)");
+      params.push(serializeJson(update.result));
+    }
+    if ("error" in update) {
+      setClauses.push("error = jsonb(?)");
+      params.push(serializeJson(update.error));
+    }
+    if ("retryCount" in update) {
+      setClauses.push("retry_count = ?");
+      params.push(update.retryCount);
+    }
+    if ("startedAt" in update) {
+      setClauses.push("startedAt = ?");
+      params.push(update.startedAt?.toISOString() ?? null);
+    }
+    if ("completedAt" in update) {
+      setClauses.push("completedAt = ?");
+      params.push(update.completedAt?.toISOString() ?? null);
+    }
+    if (setClauses.length === 0) return;
+    params.push(taskId);
+    await this.#client.execute({
+      sql: `UPDATE ${storage.TABLE_BACKGROUND_TASKS} SET ${setClauses.join(", ")} WHERE id = ?`,
+      args: params
+    });
+  }
+  async getTask(taskId) {
+    const result = await this.#client.execute({
+      sql: `SELECT ${buildSelectColumns(storage.TABLE_BACKGROUND_TASKS)} FROM ${storage.TABLE_BACKGROUND_TASKS} WHERE id = ?`,
+      args: [taskId]
+    });
+    const row = result.rows[0];
+    return row ? rowToTask(row) : null;
+  }
+  async listTasks(filter) {
+    const conditions = [];
+    const params = [];
+    if (filter.status) {
+      const statuses = Array.isArray(filter.status) ? filter.status : [filter.status];
+      conditions.push(`status IN (${statuses.map(() => "?").join(", ")})`);
+      params.push(...statuses);
+    }
+    if (filter.agentId) {
+      conditions.push("agent_id = ?");
+      params.push(filter.agentId);
+    }
+    if (filter.threadId) {
+      conditions.push("thread_id = ?");
+      params.push(filter.threadId);
+    }
+    if (filter.runId) {
+      conditions.push("run_id = ?");
+      params.push(filter.runId);
+    }
+    if (filter.resourceId) {
+      conditions.push("resource_id = ?");
+      params.push(filter.resourceId);
+    }
+    if (filter.toolName) {
+      conditions.push("tool_name = ?");
+      params.push(filter.toolName);
+    }
+    const dateCol = filter.dateFilterBy === "startedAt" ? "startedAt" : filter.dateFilterBy === "completedAt" ? "completedAt" : "createdAt";
+    if (filter.fromDate) {
+      conditions.push(`${dateCol} >= ?`);
+      params.push(filter.fromDate.toISOString());
+    }
+    if (filter.toDate) {
+      conditions.push(`${dateCol} < ?`);
+      params.push(filter.toDate.toISOString());
+    }
+    const where = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
+    const countResult = await this.#client.execute({
+      sql: `SELECT COUNT(*) as count FROM ${storage.TABLE_BACKGROUND_TASKS} ${where}`,
+      args: [...params]
+    });
+    const total = Number(countResult.rows[0]?.count ?? 0);
+    const orderCol = filter.orderBy === "startedAt" ? "startedAt" : filter.orderBy === "completedAt" ? "completedAt" : "createdAt";
+    const direction = filter.orderDirection === "desc" ? "DESC" : "ASC";
+    let sql = `SELECT ${buildSelectColumns(storage.TABLE_BACKGROUND_TASKS)} FROM ${storage.TABLE_BACKGROUND_TASKS} ${where} ORDER BY ${orderCol} ${direction}`;
+    if (filter.perPage != null) {
+      sql += " LIMIT ?";
+      params.push(filter.perPage);
+      if (filter.page != null) {
+        sql += " OFFSET ?";
+        params.push(filter.page * filter.perPage);
+      }
+    }
+    const result = await this.#client.execute({ sql, args: params });
+    return { tasks: result.rows.map((row) => rowToTask(row)), total };
+  }
+  async deleteTask(taskId) {
+    await this.#client.execute({
+      sql: `DELETE FROM ${storage.TABLE_BACKGROUND_TASKS} WHERE id = ?`,
+      args: [taskId]
+    });
+  }
+  async deleteTasks(filter) {
+    const conditions = [];
+    const params = [];
+    if (filter.status) {
+      const statuses = Array.isArray(filter.status) ? filter.status : [filter.status];
+      conditions.push(`status IN (${statuses.map(() => "?").join(", ")})`);
+      params.push(...statuses);
+    }
+    const dateCol = filter.dateFilterBy === "startedAt" ? "startedAt" : filter.dateFilterBy === "completedAt" ? "completedAt" : "createdAt";
+    if (filter.fromDate) {
+      conditions.push(`${dateCol} >= ?`);
+      params.push(filter.fromDate.toISOString());
+    }
+    if (filter.toDate) {
+      conditions.push(`${dateCol} < ?`);
+      params.push(filter.toDate.toISOString());
+    }
+    if (filter.agentId) {
+      conditions.push("agent_id = ?");
+      params.push(filter.agentId);
+    }
+    if (filter.runId) {
+      conditions.push("run_id = ?");
+      params.push(filter.runId);
+    }
+    if (conditions.length === 0) return;
+    await this.#client.execute({
+      sql: `DELETE FROM ${storage.TABLE_BACKGROUND_TASKS} WHERE ${conditions.join(" AND ")}`,
+      args: params
+    });
+  }
+  async getRunningCount() {
+    const result = await this.#client.execute({
+      sql: `SELECT COUNT(*) as count FROM ${storage.TABLE_BACKGROUND_TASKS} WHERE status = 'running'`,
+      args: []
+    });
+    return Number(result.rows[0]?.count ?? 0);
+  }
+  async getRunningCountByAgent(agentId) {
+    const result = await this.#client.execute({
+      sql: `SELECT COUNT(*) as count FROM ${storage.TABLE_BACKGROUND_TASKS} WHERE status = 'running' AND agent_id = ?`,
+      args: [agentId]
+    });
+    return Number(result.rows[0]?.count ?? 0);
+  }
+};
 var BlobsLibSQL = class extends storage.BlobStore {
   #db;
   #client;
@@ -10639,6 +10942,7 @@ var LibSQLStore = class extends storage.MastraCompositeStore {
     const workspaces = new WorkspacesLibSQL(domainConfig);
     const skills = new SkillsLibSQL(domainConfig);
     const blobs = new BlobsLibSQL(domainConfig);
+    const backgroundTasks = new BackgroundTasksLibSQL(domainConfig);
     this.stores = {
       scores,
       workflows,
@@ -10653,7 +10957,8 @@ var LibSQLStore = class extends storage.MastraCompositeStore {
       mcpServers,
       workspaces,
       skills,
-      blobs
+      blobs,
+      backgroundTasks
     };
   }
 };
@@ -10758,6 +11063,7 @@ Example Complex Query:
 }`;
 
 exports.AgentsLibSQL = AgentsLibSQL;
+exports.BackgroundTasksLibSQL = BackgroundTasksLibSQL;
 exports.BlobsLibSQL = BlobsLibSQL;
 exports.DatasetsLibSQL = DatasetsLibSQL;
 exports.DefaultStorage = LibSQLStore;