@mastra/libsql 1.17.1-alpha.1 → 1.18.0-alpha.0

package/CHANGELOG.md

@@ -1,5 +1,41 @@
 # @mastra/libsql
 
+## 1.18.0-alpha.0
+
+### Minor Changes
+
+- Added exact metadata filtering to message history queries across Memory APIs and supported storage providers. ([#19991](https://github.com/mastra-ai/mastra/pull/19991))
+
+  ```ts
+  const messages = await memory.recall({
+    threadId: 'thread-1',
+    filter: {
+      metadata: {
+        status: 'done',
+        priority: 'high',
+      },
+    },
+  });
+  ```
+
+  Multiple fields use AND semantics. Supported values are strings, finite numbers, booleans, and `null`.
+
+### Patch Changes
+
+- Updated dependencies [[`0dca9d0`](https://github.com/mastra-ai/mastra/commit/0dca9d0b1356024a53b72ea6f040db528b126caa)]:
+  - @mastra/core@1.54.0-alpha.0
+
+## 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

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

package/dist/docs/assets/SOURCE_MAP.json

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

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

@@ -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/index.cjs

@@ -7008,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;
   /**
@@ -7253,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}`;
@@ -7277,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 };
@@ -7306,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: [],
@@ -7334,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,
@@ -7392,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}`;
@@ -7413,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 };