@mastra/pg 1.10.0 → 1.10.1-alpha.1

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # @mastra/pg
 
+## 1.10.1-alpha.1
+
+### Patch Changes
+
+- Respect optional `resourceId` in `getThreadById` so scoped thread lookups return `null` when the thread belongs to a different resource. ([#14237](https://github.com/mastra-ai/mastra/pull/14237))
+
+  Example:
+
+  ```typescript
+  const thread = await memory.getThreadById({
+    threadId: 'my-thread-id',
+    resourceId: 'my-user-id',
+  });
+  // Returns null if the thread does not belong to 'my-user-id'.
+  ```
+
+- Updated dependencies [[`7c275a8`](https://github.com/mastra-ai/mastra/commit/7c275a810595e1a6c41ccc39720531ab65734700), [`890b24c`](https://github.com/mastra-ai/mastra/commit/890b24cc7d32ed6aa4dfe253e54dc6bf4099f690), [`0f48ebf`](https://github.com/mastra-ai/mastra/commit/0f48ebfc7ac7897b2092a189f45751924cf56d1c), [`f180e49`](https://github.com/mastra-ai/mastra/commit/f180e4990e71b04c9a475b523584071712f0048f), [`9260e01`](https://github.com/mastra-ai/mastra/commit/9260e015276fb1b500f7878ee452b47476bf1583), [`2f6c54e`](https://github.com/mastra-ai/mastra/commit/2f6c54e17c041cac1def54baaa6b771647836414), [`e06a159`](https://github.com/mastra-ai/mastra/commit/e06a1598ca07a6c3778aefc2a2d288363c6294ff), [`db34bc6`](https://github.com/mastra-ai/mastra/commit/db34bc6fb36cf125bda0c46be4d3fdc774b70cc4)]:
+  - @mastra/core@1.33.0-alpha.8
+
+## 1.10.1-alpha.0
+
+### Patch Changes
+
+- Track `suspendedAt` and `suspendPayload` on background tasks. SQL adapters auto-migrate the new columns via `alterTable`. ([#16260](https://github.com/mastra-ai/mastra/pull/16260))
+
+- Updated dependencies [[`9f17410`](https://github.com/mastra-ai/mastra/commit/9f1741080def23d42ee50b39887a385ae316a3c6), [`c6eb39e`](https://github.com/mastra-ai/mastra/commit/c6eb39ea6dca381c6563cb240237fbe608e02f93), [`900d086`](https://github.com/mastra-ai/mastra/commit/900d086bb737b9cf2fcf68f11b0389b801a2738c), [`4c0e286`](https://github.com/mastra-ai/mastra/commit/4c0e28637c9cfb4f416549b55e97ebfa13319dfc), [`25184ff`](https://github.com/mastra-ai/mastra/commit/25184ffaf1293ec95119426eb1a1f8d38831b96c), [`aebde9c`](https://github.com/mastra-ai/mastra/commit/aebde9cfacf56592c6b6350cae721740fe090b8a)]:
+  - @mastra/core@1.33.0-alpha.4
+
 ## 1.10.0
 
 ### Minor Changes

package/dist/docs/SKILL.md

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

package/dist/docs/assets/SOURCE_MAP.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.10.0",
+  "version": "1.10.1-alpha.1",
   "package": "@mastra/pg",
   "exports": {},
   "modules": {}

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

@@ -121,26 +121,88 @@ Each vector store page below includes installation instructions, configuration p
 
 ## Recall configuration
 
-The three main parameters that control semantic recall behavior are:
+The following options control semantic recall behavior:
 
-1. **topK**: How many semantically similar messages to retrieve
-2. **messageRange**: How much surrounding context to include with each match
-3. **scope**: Whether to search within the current thread or across all threads owned by a resource (the default is resource scope).
+1. **topK**: The number of similar messages to retrieve
+2. **messageRange**: The surrounding messages to include with each match
+3. **scope**: Whether to search the current thread or all threads for a resource
+4. **filter**: Metadata criteria that restrict search results
 
 ```typescript
 const agent = new Agent({
   memory: new Memory({
     options: {
       semanticRecall: {
-        topK: 3, // Retrieve 3 most similar messages
+        topK: 3, // Retrieve 3 similar messages
         messageRange: 2, // Include 2 messages before and after each match
-        scope: 'resource', // Search across all threads for this user (default setting if omitted)
+        scope: 'resource', // Search all threads for this resource
+        filter: { projectId: { $eq: 'project-a' } },
       },
     },
   }),
 })
 ```
 
+> **Note:** `scope: 'resource'` is supported by the LibSQL, PostgreSQL, and Upstash storage adapters.
+
+### Metadata filtering
+
+The `filter` option restricts semantic recall results to messages with matching thread metadata.
+
+```typescript
+const agent = new Agent({
+  memory: new Memory({
+    options: {
+      semanticRecall: {
+        scope: 'resource',
+        filter: {
+          projectId: { $eq: 'project-a' },
+          category: { $in: ['work', 'personal'] },
+        },
+      },
+    },
+  }),
+})
+```
+
+Filters match metadata stored on message embeddings when messages are saved. If thread metadata changes later, existing embeddings keep their previous metadata until those messages are saved or indexed again.
+
+Supported filter operators:
+
+- `$and`: Logical AND
+- `$eq`: Equal to
+- `$gt`: Greater than
+- `$gte`: Greater than or equal
+- `$in`: In array
+- `$lt`: Less than
+- `$lte`: Less than or equal
+- `$ne`: Not equal to
+- `$nin`: Not in array
+- `$or`: Logical OR
+
+The following example demonstrates metadata filters for common use cases:
+
+```typescript
+// Filter by project
+const options = {
+  semanticRecall: { filter: { projectId: { $eq: 'my-project' } } },
+}
+
+// Filter by multiple categories
+const options = {
+  semanticRecall: { filter: { category: { $in: ['work', 'research'] } } },
+}
+
+// Filter by project and priority
+const options = {
+  semanticRecall: {
+    filter: {
+      $and: [{ projectId: { $eq: 'project-a' } }, { priority: { $gte: 3 } }],
+    },
+  },
+}
+```
+
 ## Embedder configuration
 
 Semantic recall relies on an [embedding model](https://mastra.ai/reference/memory/memory-class) to convert messages into embeddings. Mastra supports embedding models through the model router using `provider/model` strings, or you can use any [embedding model](https://sdk.vercel.ai/docs/ai-sdk-core/embeddings) compatible with the AI SDK.

package/dist/index.cjs

@@ -4314,11 +4314,13 @@ function rowToTask(row) {
     runId: row.run_id,
     result: parseJson(row.result),
     error: parseJson(row.error),
+    suspendPayload: parseJson(row.suspend_payload),
     retryCount: Number(row.retry_count),
     maxRetries: Number(row.max_retries),
     timeoutMs: Number(row.timeout_ms),
     createdAt: row.createdAt instanceof Date ? row.createdAt : new Date(row.createdAt),
     startedAt: row.startedAt ? row.startedAt instanceof Date ? row.startedAt : new Date(row.startedAt) : void 0,
+    suspendedAt: row.suspendedAt ? row.suspendedAt instanceof Date ? row.suspendedAt : new Date(row.suspendedAt) : void 0,
     completedAt: row.completedAt ? row.completedAt instanceof Date ? row.completedAt : new Date(row.completedAt) : void 0
   };
 }
@@ -4341,6 +4343,11 @@ var BackgroundTasksPG = class _BackgroundTasksPG extends storage.BackgroundTasks
       tableName: storage.TABLE_BACKGROUND_TASKS,
       schema: storage.TABLE_SCHEMAS[storage.TABLE_BACKGROUND_TASKS]
     });
+    await this.#db.alterTable({
+      tableName: storage.TABLE_BACKGROUND_TASKS,
+      schema: storage.TABLE_SCHEMAS[storage.TABLE_BACKGROUND_TASKS],
+      ifNotExists: ["suspend_payload", "suspendedAt"]
+    });
     await this.createDefaultIndexes();
     await this.createCustomIndexes();
   }
@@ -4427,11 +4434,13 @@ var BackgroundTasksPG = class _BackgroundTasksPG extends storage.BackgroundTasks
         args: serializeJson(task.args),
         result: serializeJson(task.result),
         error: serializeJson(task.error),
+        suspend_payload: serializeJson(task.suspendPayload),
         retry_count: task.retryCount,
         max_retries: task.maxRetries,
         timeout_ms: task.timeoutMs,
         createdAt: task.createdAt.toISOString(),
         startedAt: task.startedAt?.toISOString() ?? null,
+        suspendedAt: task.suspendedAt?.toISOString() ?? null,
         completedAt: task.completedAt?.toISOString() ?? null
       }
     });
@@ -4452,6 +4461,10 @@ var BackgroundTasksPG = class _BackgroundTasksPG extends storage.BackgroundTasks
       setClauses.push(`"error" = $${paramIdx++}`);
       params.push(serializeJson(update.error));
     }
+    if ("suspendPayload" in update) {
+      setClauses.push(`"suspend_payload" = $${paramIdx++}`);
+      params.push(serializeJson(update.suspendPayload));
+    }
     if ("retryCount" in update) {
       setClauses.push(`"retry_count" = $${paramIdx++}`);
       params.push(update.retryCount);
@@ -4460,6 +4473,10 @@ var BackgroundTasksPG = class _BackgroundTasksPG extends storage.BackgroundTasks
       setClauses.push(`"startedAt" = $${paramIdx++}`);
       params.push(update.startedAt?.toISOString() ?? null);
     }
+    if ("suspendedAt" in update) {
+      setClauses.push(`"suspendedAt" = $${paramIdx++}`);
+      params.push(update.suspendedAt?.toISOString() ?? null);
+    }
     if ("completedAt" in update) {
       setClauses.push(`"completedAt" = $${paramIdx++}`);
       params.push(update.completedAt?.toISOString() ?? null);
@@ -4505,7 +4522,11 @@ var BackgroundTasksPG = class _BackgroundTasksPG extends storage.BackgroundTasks
       conditions.push(`"tool_name" = $${paramIdx++}`);
       params.push(filter.toolName);
     }
-    const dateCol = filter.dateFilterBy === "startedAt" ? '"startedAt"' : filter.dateFilterBy === "completedAt" ? '"completedAt"' : '"createdAt"';
+    if (filter.toolCallId) {
+      conditions.push(`"tool_call_id" = $${paramIdx++}`);
+      params.push(filter.toolCallId);
+    }
+    const dateCol = filter.dateFilterBy === "startedAt" ? '"startedAt"' : filter.dateFilterBy === "suspendedAt" ? '"suspendedAt"' : filter.dateFilterBy === "completedAt" ? '"completedAt"' : '"createdAt"';
     if (filter.fromDate) {
       conditions.push(`${dateCol} >= $${paramIdx++}`);
       params.push(filter.fromDate.toISOString());
@@ -4520,7 +4541,7 @@ var BackgroundTasksPG = class _BackgroundTasksPG extends storage.BackgroundTasks
       params.slice(0, paramIdx - 1)
     );
     const total = Number(countResult?.count ?? 0);
-    const orderCol = filter.orderBy === "startedAt" ? '"startedAt"' : filter.orderBy === "completedAt" ? '"completedAt"' : '"createdAt"';
+    const orderCol = filter.orderBy === "startedAt" ? '"startedAt"' : filter.orderBy === "suspendedAt" ? '"suspendedAt"' : filter.orderBy === "completedAt" ? '"completedAt"' : '"createdAt"';
     const direction = filter.orderDirection === "desc" ? "DESC" : "ASC";
     let sql = `SELECT * FROM ${table} ${where} ORDER BY ${orderCol} ${direction}`;
     if (filter.perPage != null) {
@@ -4549,7 +4570,7 @@ var BackgroundTasksPG = class _BackgroundTasksPG extends storage.BackgroundTasks
       conditions.push(`"status" IN (${placeholders.join(", ")})`);
       params.push(...statuses);
     }
-    const dateCol = filter.dateFilterBy === "startedAt" ? '"startedAt"' : filter.dateFilterBy === "completedAt" ? '"completedAt"' : '"createdAt"';
+    const dateCol = filter.dateFilterBy === "startedAt" ? '"startedAt"' : filter.dateFilterBy === "suspendedAt" ? '"suspendedAt"' : filter.dateFilterBy === "completedAt" ? '"completedAt"' : '"createdAt"';
     if (filter.fromDate) {
       conditions.push(`${dateCol} >= $${paramIdx++}`);
       params.push(filter.fromDate.toISOString());
@@ -7859,12 +7880,21 @@ var MemoryPG = class _MemoryPG extends storage.MemoryStorage {
       resourceId: row.resourceId
     };
   }
-  async getThreadById({ threadId }) {
+  async getThreadById({
+    threadId,
+    resourceId
+  }) {
     try {
       const tableName = getTableName4({ indexName: storage.TABLE_THREADS, schemaName: getSchemaName4(this.#schema) });
+      let query = `SELECT * FROM ${tableName} WHERE id = $1`;
+      let params = [threadId];
+      if (resourceId !== void 0) {
+        query += ` AND "resourceId" = $2`;
+        params.push(resourceId);
+      }
       const thread = await this.#db.client.oneOrNone(
-        `SELECT * FROM ${tableName} WHERE id = $1`,
-        [threadId]
+        query,
+        params
       );
       if (!thread) {
         return null;