@mastra/pg 1.8.4 → 1.8.5-alpha.0

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # @mastra/pg
 
+## 1.8.5-alpha.0
+
+### Patch Changes
+
+- Fixed thread and message timestamp handling to use timezone-aware columns (TIMESTAMPTZ) for sorting and date range filtering. Previously, ORDER BY and date range queries used TIMESTAMP columns which could produce incorrect ordering when the PostgreSQL server timezone differs from UTC. Also fixed timestamp values passed to UPDATE queries to use Date objects instead of ISO strings, preventing timezone information from being stripped when stored in TIMESTAMP columns. ([#14297](https://github.com/mastra-ai/mastra/pull/14297))
+
+- Updated dependencies [[`9140989`](https://github.com/mastra-ai/mastra/commit/91409890e83f4f1d9c1b39223f1af91a6a53b549), [`d7c98cf`](https://github.com/mastra-ai/mastra/commit/d7c98cfc9d75baba9ecbf1a8835b5183d0a0aec8), [`acf5fbc`](https://github.com/mastra-ai/mastra/commit/acf5fbcb890dc7ca7167bec386ce5874dfadb997), [`24ca2ae`](https://github.com/mastra-ai/mastra/commit/24ca2ae57538ec189fabb9daee6175ad27035853), [`0762516`](https://github.com/mastra-ai/mastra/commit/07625167e029a8268ea7aaf0402416e6d8832874), [`2de3d36`](https://github.com/mastra-ai/mastra/commit/2de3d36932b7f73ad26bc403f7da26cfe89e903e), [`d3736cb`](https://github.com/mastra-ai/mastra/commit/d3736cb9ce074d2b8e8b00218a01f790fe81a1b4), [`c627366`](https://github.com/mastra-ai/mastra/commit/c6273666f9ef4c8c617c68b7d07fe878a322f85c)]:
+  - @mastra/core@1.18.1-alpha.1
+
 ## 1.8.4
 
 ### Patch 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.8.4"
+  version: "1.8.5-alpha.0"
 ---
 
 ## When to use

package/dist/docs/assets/SOURCE_MAP.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.8.4",
+  "version": "1.8.5-alpha.0",
   "package": "@mastra/pg",
   "exports": {},
   "modules": {}

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

@@ -18,18 +18,33 @@ After getting a response from the LLM, all new messages (user, assistant, and to
 
 ## Quickstart
 
-Semantic recall is enabled by default, so if you give your agent memory it will be included:
+Semantic recall is disabled by default. To enable it, set `semanticRecall: true` in `options` and provide a `vector` store and `embedder`:
 
 ```typescript
 import { Agent } from '@mastra/core/agent'
 import { Memory } from '@mastra/memory'
+import { LibSQLStore, LibSQLVector } from '@mastra/libsql'
+import { ModelRouterEmbeddingModel } from '@mastra/core/llm'
 
 const agent = new Agent({
   id: 'support-agent',
   name: 'SupportAgent',
   instructions: 'You are a helpful support agent.',
   model: 'openai/gpt-5.4',
-  memory: new Memory(),
+  memory: new Memory({
+    storage: new LibSQLStore({
+      id: 'agent-storage',
+      url: 'file:./local.db',
+    }),
+    vector: new LibSQLVector({
+      id: 'agent-vector',
+      url: 'file:./local.db',
+    }),
+    embedder: new ModelRouterEmbeddingModel('openai/text-embedding-3-small'),
+    options: {
+      semanticRecall: true,
+    },
+  }),
 })
 ```
 
@@ -77,6 +92,9 @@ const agent = new Agent({
       id: 'agent-vector',
       url: 'file:./local.db',
     }),
+    options: {
+      semanticRecall: true,
+    },
   }),
 })
 ```
@@ -139,6 +157,9 @@ import { ModelRouterEmbeddingModel } from '@mastra/core/llm'
 const agent = new Agent({
   memory: new Memory({
     embedder: new ModelRouterEmbeddingModel('openai/text-embedding-3-small'),
+    options: {
+      semanticRecall: true,
+    },
   }),
 })
 ```
@@ -262,26 +283,14 @@ const agent = new Agent({
 
 For detailed information about index configuration options and performance tuning, see the [PgVector configuration guide](https://mastra.ai/reference/vectors/pg).
 
-## Disabling
+## Disable semantic recall
 
-Semantic recall has a performance impact. New messages are converted into embeddings and used to query a vector database before new messages are sent to the LLM.
-
-Semantic recall is enabled by default but can be disabled when not needed:
-
-```typescript
-const agent = new Agent({
-  memory: new Memory({
-    options: {
-      semanticRecall: false,
-    },
-  }),
-})
-```
+Semantic recall is disabled by default (`semanticRecall: false`). Each call adds latency because new messages are converted into embeddings and used to query a vector database before the LLM receives them.
 
-You might want to disable semantic recall in scenarios like:
+Keep semantic recall disabled when:
 
-- When message history provides sufficient context for the current conversation.
-- In performance-sensitive applications, like realtime two-way audio, where the added latency of creating embeddings and running vector queries is noticeable.
+- Message history provides sufficient context for the current conversation.
+- You're building performance-sensitive applications, like realtime two-way audio, where embedding and vector query latency is noticeable.
 
 ## Viewing recalled messages
 

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

@@ -14,7 +14,7 @@ export const mastra = new Mastra({
 })
 ```
 
-> **Sharing the database with Mastra Studio:** When running `mastra dev` alongside your application (e.g., Next.js), use an absolute path to ensure both processes access the same database:
+> **Sharing the database with Studio:** When running `mastra dev` alongside your application (e.g., Next.js), use an absolute path to ensure both processes access the same database:
 >
 > ```typescript
 > url: 'file:/absolute/path/to/your/project/mastra.db'
@@ -129,7 +129,7 @@ Mastra organizes conversations using two identifiers:
 
 Both identifiers are required for agents to store information:
 
-**Generate**:
+**.generate()**:
 
 ```typescript
 const response = await agent.generate('hello', {
@@ -140,7 +140,7 @@ const response = await agent.generate('hello', {
 })
 ```
 
-**Stream**:
+**.stream()**:
 
 ```typescript
 const stream = await agent.stream('hello', {
@@ -151,7 +151,7 @@ const stream = await agent.stream('hello', {
 })
 ```
 
-> **Note:** [Studio](https://mastra.ai/docs/getting-started/studio) automatically generates a thread and resource ID for you. When calling `stream()` or `generate()` yourself, remember to provide these identifiers explicitly.
+> **Note:** [Studio](https://mastra.ai/docs/studio/overview) automatically generates a thread and resource ID for you. When calling `stream()` or `generate()` yourself, remember to provide these identifiers explicitly.
 
 ### Thread title generation
 

package/dist/docs/references/reference-storage-dynamodb.md

@@ -2,7 +2,7 @@
 
 The DynamoDB storage implementation provides a scalable and performant NoSQL database solution for Mastra, leveraging a single-table design pattern with [ElectroDB](https://electrodb.dev/).
 
-> **Observability Not Supported:** DynamoDB storage **doesn't support the observability domain**. Traces from the `DefaultExporter` can't be persisted to DynamoDB, and Mastra Studio's observability features won't work with DynamoDB as your only storage provider. To enable observability, use [composite storage](https://mastra.ai/reference/storage/composite) to route observability data to a supported provider like ClickHouse or PostgreSQL.
+> **Observability Not Supported:** DynamoDB storage **doesn't support the observability domain**. Traces from the `DefaultExporter` can't be persisted to DynamoDB, and [Studio's](https://mastra.ai/docs/studio/overview) observability features won't work with DynamoDB as your only storage provider. To enable observability, use [composite storage](https://mastra.ai/reference/storage/composite) to route observability data to a supported provider like ClickHouse or PostgreSQL.
 
 > **Item Size Limit:** DynamoDB enforces a **400 KB maximum item size**. This limit can be exceeded when storing messages with base64-encoded attachments such as images. See [Handling large attachments](https://mastra.ai/docs/memory/storage) for workarounds including uploading attachments to external storage.
 

package/dist/index.cjs

@@ -7355,7 +7355,7 @@ var MemoryPG = class _MemoryPG extends storage.MemoryStorage {
         };
       }
       const limitValue = perPageInput === false ? total : perPage;
-      const dataQuery = `SELECT id, "resourceId", title, metadata, "createdAt", "createdAtZ", "updatedAt", "updatedAtZ" ${baseQuery} ORDER BY "${field}" ${direction} LIMIT $${paramIndex} OFFSET $${paramIndex + 1}`;
+      const dataQuery = `SELECT id, "resourceId", title, metadata, "createdAt", "createdAtZ", "updatedAt", "updatedAtZ" ${baseQuery} ORDER BY COALESCE("${field}Z", "${field}") ${direction} LIMIT $${paramIndex} OFFSET $${paramIndex + 1}`;
       const rows = await this.#db.client.manyOrNone(
         dataQuery,
         [...queryParams, limitValue, offset]
@@ -7473,7 +7473,7 @@ var MemoryPG = class _MemoryPG extends storage.MemoryStorage {
       ...metadata
     };
     try {
-      const now = (/* @__PURE__ */ new Date()).toISOString();
+      const now = /* @__PURE__ */ new Date();
       const thread = await this.#db.client.one(
         `UPDATE ${threadTableName}
                     SET
@@ -7719,7 +7719,7 @@ var MemoryPG = class _MemoryPG extends storage.MemoryStorage {
     const { offset, perPage: perPageForResponse } = storage.calculatePagination(page, perPageInput, perPage);
     try {
       const { field, direction } = this.parseOrderBy(orderBy, "ASC");
-      const orderByStatement = `ORDER BY "${field}" ${direction}`;
+      const orderByStatement = `ORDER BY COALESCE("${field}Z", "${field}") ${direction}`;
       const selectStatement = `SELECT id, content, role, type, "createdAt", "createdAtZ", thread_id AS "threadId", "resourceId"`;
       const tableName = getTableName3({ indexName: storage.TABLE_MESSAGES, schemaName: getSchemaName3(this.#schema) });
       const conditions = [`thread_id IN (${inPlaceholders(threadIds.length)})`];
@@ -7858,7 +7858,7 @@ var MemoryPG = class _MemoryPG extends storage.MemoryStorage {
     const { offset, perPage: perPageForResponse } = storage.calculatePagination(page, perPageInput, perPage);
     try {
       const { field, direction } = this.parseOrderBy(orderBy, "ASC");
-      const orderByStatement = `ORDER BY "${field}" ${direction}`;
+      const orderByStatement = `ORDER BY COALESCE("${field}Z", "${field}") ${direction}`;
       const selectStatement = `SELECT id, content, role, type, "createdAt", "createdAtZ", thread_id AS "threadId", "resourceId"`;
       const tableName = getTableName3({ indexName: storage.TABLE_MESSAGES, schemaName: getSchemaName3(this.#schema) });
       const conditions = [];
@@ -7868,12 +7868,12 @@ var MemoryPG = class _MemoryPG extends storage.MemoryStorage {
       queryParams.push(resourceId);
       if (filter?.dateRange?.start) {
         const startOp = filter.dateRange.startExclusive ? ">" : ">=";
-        conditions.push(`"createdAt" ${startOp} $${paramIndex++}`);
+        conditions.push(`COALESCE("createdAtZ", "createdAt") ${startOp} $${paramIndex++}`);
         queryParams.push(filter.dateRange.start);
       }
       if (filter?.dateRange?.end) {
         const endOp = filter.dateRange.endExclusive ? "<" : "<=";
-        conditions.push(`"createdAt" ${endOp} $${paramIndex++}`);
+        conditions.push(`COALESCE("createdAtZ", "createdAt") ${endOp} $${paramIndex++}`);
         queryParams.push(filter.dateRange.end);
       }
       const whereClause = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
@@ -8013,8 +8013,8 @@ var MemoryPG = class _MemoryPG extends storage.MemoryStorage {
               message.id,
               message.threadId,
               typeof message.content === "string" ? message.content : JSON.stringify(message.content),
-              message.createdAt || (/* @__PURE__ */ new Date()).toISOString(),
-              message.createdAt || (/* @__PURE__ */ new Date()).toISOString(),
+              message.createdAt || /* @__PURE__ */ new Date(),
+              message.createdAt || /* @__PURE__ */ new Date(),
               message.role,
               message.type || "v2",
               message.resourceId
@@ -8022,14 +8022,14 @@ var MemoryPG = class _MemoryPG extends storage.MemoryStorage {
           );
         }
         const threadTableName = getTableName3({ indexName: storage.TABLE_THREADS, schemaName: getSchemaName3(this.#schema) });
-        const nowStr = (/* @__PURE__ */ new Date()).toISOString();
+        const now = /* @__PURE__ */ new Date();
         await t.none(
           `UPDATE ${threadTableName}
             SET
               "updatedAt" = $1,
               "updatedAtZ" = $2
             WHERE id = $3`,
-          [nowStr, nowStr, threadId]
+          [now, now, threadId]
         );
       });
       const messagesWithParsedContent = messages.map((message) => {