@mastra/libsql 1.17.1-alpha.0 → 1.17.1

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # @mastra/libsql
 
+## 1.17.1
+
+### Patch Changes
+
+- Fixed data loss and corruption in observational memory when it is written to concurrently on a local SQLite database. Buffered observations could previously be dropped or leave the memory record in an inconsistent state under load; memory updates are now serialized so concurrent writes are preserved. ([#20110](https://github.com/mastra-ai/mastra/pull/20110))
+
+- Fixed local LibSQL stores changing shared database journal state when they close. ([#20227](https://github.com/mastra-ai/mastra/pull/20227))
+
+- Updated dependencies [[`c8d8a01`](https://github.com/mastra-ai/mastra/commit/c8d8a010ee2efe2b7bf4d07707382c34c87b14e4), [`df6a9ce`](https://github.com/mastra-ai/mastra/commit/df6a9ce87214f7aadb2edfe62f67605fe998a0a4), [`73839cb`](https://github.com/mastra-ai/mastra/commit/73839cb58322679c170627d1015669ede5f619aa), [`371cf60`](https://github.com/mastra-ai/mastra/commit/371cf6075cef88ac6919a08d59a82e485397364a), [`8e4dc79`](https://github.com/mastra-ai/mastra/commit/8e4dc793dcf035ea506f9ce79f56d2d501a4be14), [`2db93cc`](https://github.com/mastra-ai/mastra/commit/2db93ccd0b872e4de7853a93383efe0647901df8), [`094ab61`](https://github.com/mastra-ai/mastra/commit/094ab6129a1a3ecf6eeb86decac17d5faea4e02a), [`fe80944`](https://github.com/mastra-ai/mastra/commit/fe80944f3ef6681fea6eae8200fce387b7bb3c2f), [`263d2ca`](https://github.com/mastra-ai/mastra/commit/263d2cac80ba3b03b9c0f008db6f1f1b9eb0278c), [`75f843d`](https://github.com/mastra-ai/mastra/commit/75f843d09f758223e6eeb321321bdcc5c7e779d0), [`e51e166`](https://github.com/mastra-ai/mastra/commit/e51e166c52e220abc9b64554ce37359dca8544b1)]:
+  - @mastra/core@1.53.0
+
+## 1.17.1-alpha.1
+
+### Patch Changes
+
+- Fixed local LibSQL stores changing shared database journal state when they close. ([#20227](https://github.com/mastra-ai/mastra/pull/20227))
+
+- Updated dependencies [[`73839cb`](https://github.com/mastra-ai/mastra/commit/73839cb58322679c170627d1015669ede5f619aa), [`8e4dc79`](https://github.com/mastra-ai/mastra/commit/8e4dc793dcf035ea506f9ce79f56d2d501a4be14), [`2db93cc`](https://github.com/mastra-ai/mastra/commit/2db93ccd0b872e4de7853a93383efe0647901df8), [`094ab61`](https://github.com/mastra-ai/mastra/commit/094ab6129a1a3ecf6eeb86decac17d5faea4e02a), [`fe80944`](https://github.com/mastra-ai/mastra/commit/fe80944f3ef6681fea6eae8200fce387b7bb3c2f), [`e51e166`](https://github.com/mastra-ai/mastra/commit/e51e166c52e220abc9b64554ce37359dca8544b1)]:
+  - @mastra/core@1.53.0-alpha.4
+
 ## 1.17.1-alpha.0
 
 ### 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.17.1-alpha.0"
+  version: "1.17.1"
 ---
 
 ## When to use

package/dist/docs/assets/SOURCE_MAP.json

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

package/dist/docs/references/docs-memory-message-history.md

@@ -124,7 +124,7 @@ You can use this history in two ways:
 
 ## Thread title generation
 
-Mastra can automatically generate descriptive thread titles based on the user's first message when `generateTitle` is enabled. Use this option when you build a chat interface that renders conversation titles in a thread list or sidebar.
+Mastra can automatically generate descriptive thread titles from the conversation transcript when `generateTitle` is enabled. Use this option when you build a chat interface that renders conversation titles in a thread list or sidebar.
 
 ```typescript
 import { Agent } from '@mastra/core/agent'
@@ -263,6 +263,24 @@ const { messages } = await memory.recall({
 })
 ```
 
+Filter by shallow message metadata:
+
+```typescript
+const { messages } = await memory.recall({
+  threadId: 'thread-123',
+  filter: {
+    metadata: {
+      category: 'billing',
+      escalated: true,
+      priority: 2,
+      archivedAt: null,
+    },
+  },
+})
+```
+
+Metadata filters match shallow scalar values only: `string`, finite `number`, `boolean`, and `null`. All specified metadata keys must match with AND semantics, and `null` matches an explicit `null` value, not a missing metadata key. Metadata keys must start with a letter or underscore, may contain only alphanumeric characters and underscores, must be 128 characters or fewer, and can't use reserved prototype keys such as `__proto__`, `constructor`, or `prototype`. Performance depends on the storage backend. Some backends can push parts of the filter into the database, while others scan candidate messages after thread, resource, and date constraints are applied but before pagination.
+
 Fetch a single message by ID:
 
 ```typescript

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

@@ -47,7 +47,7 @@ export const agent = new Agent({
 
 **options.observationalMemory** (`boolean | ObservationalMemoryOptions`): Enable Observational Memory for long-context agentic memory. Set to true for defaults, or pass a config object to customize token budgets, models, and scope. See Observational Memory reference for configuration details.
 
-**options.generateTitle** (`boolean | { model: DynamicArgument<MastraLanguageModel>; instructions?: DynamicArgument<string> }`): Controls automatic thread title generation from the user's first message. Can be a boolean or an object with custom model and instructions.
+**options.generateTitle** (`boolean | { model: DynamicArgument<MastraLanguageModel>; instructions?: DynamicArgument<string> }`): Controls automatic thread title generation from the conversation transcript. Can be a boolean or an object with custom model and instructions.
 
 ## Returns
 

package/dist/index.cjs

@@ -546,29 +546,14 @@ var LibSQLVector = class extends vector.MastraVector {
     this.vectorIndexes = this.isMemoryDb ? Promise.resolve(/* @__PURE__ */ new Set()) : this.discoverVectorIndexes();
   }
   /**
-   * Closes the underlying libsql client, releasing all OS file handles.
-   *
-   * For local file databases, first runs PRAGMA wal_checkpoint(TRUNCATE) and
-   * switches back to journal_mode=DELETE so the -wal and -shm sidecar files
-   * are released promptly (mirrors LibSQLStore.close()).
-   *
-   * Remote (Turso) databases skip the WAL pragmas and just close the client.
+   * Closes the underlying libsql client, releasing this vector store's OS file handles.
    *
    * Safe to call more than once; subsequent calls are no-ops.
    */
   async close() {
-    if (this.turso.closed) {
-      return;
-    }
-    if (this.turso.protocol === "file" && !this.isMemoryDb) {
-      try {
-        await this.turso.execute("PRAGMA wal_checkpoint(TRUNCATE);");
-        await this.turso.execute("PRAGMA journal_mode=DELETE;");
-      } catch (err) {
-        this.logger.warn("LibSQLVector: Failed to checkpoint WAL before close.", err);
-      }
+    if (!this.turso.closed) {
+      this.turso.close();
     }
-    this.turso.close();
   }
   async discoverVectorIndexes() {
     try {
@@ -7023,6 +7008,40 @@ var MCPServersLibSQL = class extends storage.MCPServersStorage {
   }
 };
 var OM_TABLE = "mastra_observational_memory";
+function addSqliteMetadataFilter(conditions, params, metadataFilter) {
+  if (!metadataFilter) return;
+  for (const [key, value] of Object.entries(metadataFilter)) {
+    const path = `$.metadata.${key}`;
+    conditions.push(`CASE WHEN json_valid(content) THEN json_type(content, ?) IS NOT NULL ELSE 0 END`);
+    params.push(path);
+    addSqliteMetadataValuePredicate(conditions, params, path, value);
+  }
+}
+function addSqliteMetadataValuePredicate(conditions, params, path, value) {
+  if (value === null) {
+    conditions.push(`CASE WHEN json_valid(content) THEN json_type(content, ?) = 'null' ELSE 0 END`);
+    params.push(path);
+    return;
+  }
+  if (typeof value === "string") {
+    conditions.push(
+      `CASE WHEN json_valid(content) THEN json_type(content, ?) = 'text' AND json_extract(content, ?) = ? ELSE 0 END`
+    );
+    params.push(path, path, value);
+    return;
+  }
+  if (typeof value === "number") {
+    conditions.push(
+      `CASE WHEN json_valid(content) THEN json_type(content, ?) IN ('integer', 'real') AND json_extract(content, ?) = ? ELSE 0 END`
+    );
+    params.push(path, path, value);
+    return;
+  }
+  conditions.push(
+    `CASE WHEN json_valid(content) THEN json_type(content, ?) = ? AND json_extract(content, ?) = ? ELSE 0 END`
+  );
+  params.push(path, value ? "true" : "false", path, value ? 1 : 0);
+}
 var MemoryLibSQL = class _MemoryLibSQL extends storage.MemoryStorage {
   supportsObservationalMemory = true;
   /**
@@ -7268,6 +7287,7 @@ var MemoryLibSQL = class _MemoryLibSQL extends storage.MemoryStorage {
     }
     const perPage = storage.normalizePerPage(perPageInput, 40);
     const { offset, perPage: perPageForResponse } = storage.calculatePagination(page, perPageInput, perPage);
+    const metadataFilter = storage.validateStorageMetadataFilter(filter?.metadata);
     try {
       const { field, direction } = this.parseOrderBy(orderBy, "ASC");
       const orderByStatement = `ORDER BY "${field}" ${direction}`;
@@ -7292,6 +7312,7 @@ var MemoryLibSQL = class _MemoryLibSQL extends storage.MemoryStorage {
           filter.dateRange.end instanceof Date ? filter.dateRange.end.toISOString() : filter.dateRange.end
         );
       }
+      addSqliteMetadataFilter(conditions, queryParams, metadataFilter);
       const whereClause = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
       if (perPage === 0 && (!include || include.length === 0)) {
         return { messages: [], total: 0, page, perPage: perPageForResponse, hasMore: false };
@@ -7321,6 +7342,7 @@ var MemoryLibSQL = class _MemoryLibSQL extends storage.MemoryStorage {
         args: [...queryParams, limitValue, offset]
       });
       const messages = (dataResult.rows || []).map((row) => this.parseRow(row));
+      const paginatedCount = messages.length;
       if (total === 0 && messages.length === 0 && (!include || include.length === 0)) {
         return {
           messages: [],
@@ -7349,7 +7371,7 @@ var MemoryLibSQL = class _MemoryLibSQL extends storage.MemoryStorage {
         finalMessages.filter((m) => m.threadId && threadIdSet.has(m.threadId)).map((m) => m.id)
       );
       const allThreadMessagesReturned = returnedThreadMessageIds.size >= total;
-      const hasMore = perPageInput !== false && !allThreadMessagesReturned && offset + perPage < total;
+      const hasMore = metadataFilter ? perPageInput !== false && offset + paginatedCount < total : perPageInput !== false && !allThreadMessagesReturned && offset + perPage < total;
       return {
         messages: finalMessages,
         total,
@@ -7407,6 +7429,7 @@ var MemoryLibSQL = class _MemoryLibSQL extends storage.MemoryStorage {
     }
     const perPage = storage.normalizePerPage(perPageInput, 40);
     const { offset, perPage: perPageForResponse } = storage.calculatePagination(page, perPageInput, perPage);
+    const metadataFilter = storage.validateStorageMetadataFilter(filter?.metadata);
     try {
       const { field, direction } = this.parseOrderBy(orderBy, "ASC");
       const orderByStatement = `ORDER BY "${field}" ${direction}`;
@@ -7428,6 +7451,7 @@ var MemoryLibSQL = class _MemoryLibSQL extends storage.MemoryStorage {
           filter.dateRange.end instanceof Date ? filter.dateRange.end.toISOString() : filter.dateRange.end
         );
       }
+      addSqliteMetadataFilter(conditions, queryParams, metadataFilter);
       const whereClause = `WHERE ${conditions.join(" AND ")}`;
       if (perPage === 0 && (!include || include.length === 0)) {
         return { messages: [], total: 0, page, perPage: perPageForResponse, hasMore: false };
@@ -14018,32 +14042,14 @@ var LibSQLStore = class extends storage.MastraCompositeStore {
     await this.initDomainsSequentially();
   }
   /**
-   * Closes the underlying libsql client, releasing all OS file handles.
-   *
-   * For local file databases, first runs PRAGMA wal_checkpoint(TRUNCATE) and
-   * switches back to journal_mode=DELETE so that Windows releases the -wal
-   * and -shm sidecar files promptly. Without this, the handles stay open
-   * until process exit, causing EBUSY errors when callers try to fs.rm the
-   * storage directory after Mastra.shutdown().
-   *
-   * Remote (Turso) databases skip the WAL pragmas and just close the client.
+   * Closes the underlying libsql client, releasing this store's OS file handles.
    *
    * Safe to call more than once; subsequent calls are no-ops.
    */
   async close() {
-    if (this.client.closed) {
-      return;
-    }
-    const isLocalFileDb = this.isLocalDb || this.client.protocol === "file";
-    if (isLocalFileDb) {
-      try {
-        await this.client.execute("PRAGMA wal_checkpoint(TRUNCATE);");
-        await this.client.execute("PRAGMA journal_mode=DELETE;");
-      } catch (err) {
-        this.logger.warn("LibSQLStore: Failed to checkpoint WAL before close.", err);
-      }
+    if (!this.client.closed) {
+      this.client.close();
     }
-    this.client.close();
   }
 };