@mastra/pg 1.32.0-alpha.3 → 1.32.0-alpha.5

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.32.0-alpha.3"
+  version: "1.32.0-alpha.5"
 ---
 
 ## When to use

package/dist/docs/assets/SOURCE_MAP.json

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

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

@@ -405,6 +405,26 @@ Multilingual E5 produces 1024-dimensional vectors. Your vector index must be cre
 
 FastEmbed models embed at most 512 tokens per input (roughly 2,000 to 2,500 characters of English text). Longer inputs are truncated, so text past the limit doesn't affect the embedding and can't be found by semantic recall. The AI SDK v3 FastEmbed models return a warning when this happens. The legacy v1 and v2 models don't. If you embed long documents with FastEmbed, chunk them to fit the window, for example with `maxSize: 1500` in `MDocument.chunk()`.
 
+### Setting the embedding dimension
+
+To name the vector index, Memory needs the embedder's output dimension. By default it finds the dimension by embedding a short probe string the first time semantic recall is set up, once per `Memory` instance. If you already know the dimension, set `embeddingDimension`. Memory then skips the probe, so startup makes no embedding call and doesn't depend on the embedding provider being reachable:
+
+```ts
+import { Memory } from '@mastra/memory'
+
+const memory = new Memory({
+  embedder: 'openai/text-embedding-3-small',
+  embeddingDimension: 1536,
+  options: {
+    semanticRecall: true,
+  },
+})
+```
+
+The index name is the same whether the dimension is configured or probed, so existing indexes keep working.
+
+The value must match the vectors the embedder returns. Memory compares it with the first real embedding, and on a mismatch it throws a `MASTRA_MEMORY_EMBEDDING_DIMENSION_MISMATCH` error naming both values before creating or querying any index. Update `embeddingDimension` whenever you change the embedding model or its output dimension.
+
 ## PostgreSQL index optimization
 
 When using PostgreSQL as your vector store, you can optimize semantic recall performance by configuring the vector index. This is particularly important for large-scale deployments with thousands of messages.

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

@@ -37,6 +37,8 @@ export const agent = new Agent({
 
 **embedder** (`EmbeddingModel<string> | EmbeddingModelV2<string>`): Embedder instance for vector embeddings. Required when semantic recall is enabled.
 
+**embeddingDimension** (`number`): Output dimension of the embedder, as a positive integer. When set, Memory uses it to name the semantic recall index instead of embedding a probe string on first use. It must match the vectors the embedder returns: a mismatch throws a MASTRA\_MEMORY\_EMBEDDING\_DIMENSION\_MISMATCH error before any index is created. See Setting the embedding dimension.
+
 **options** (`MemoryConfig`): Memory configuration options.
 
 **options.lastMessages** (`number | false`): Number of most recent messages to include in context. Set to false to disable the message history feature entirely (messages are not loaded into context or saved). Use Number.MAX\_SAFE\_INTEGER to retrieve all messages with no limit. To load messages without saving new ones, use the readOnly option. The window slides forward on every request, so once a thread exceeds the limit, each turn invalidates the provider prompt cache. For long-running conversations, use Observational Memory instead.

package/dist/index.cjs

@@ -19211,7 +19211,26 @@ async function getScorePercentiles(client, schema, args) {
 const TRACE_STATUS_SQL = `CASE WHEN r."error" IS NOT NULL THEN 'error' ELSE 'success' END`;
 /** Core versions without the field reject it in strict query results, so it is only returned when core knows it. */
 const timeToFirstChunkSupported = "timeToFirstChunkMs" in _mastra_core_storage.TRACE_QUERY_FIELD_REGISTRY.trace;
-const timeToFirstChunkFeatures = timeToFirstChunkSupported ? ["trace-query-time-to-first-chunk"] : [];
+/** Core before the sort rejects `orderBy` on the field, so the sort is only declared when core plans it. */
+const timeToFirstChunkSortSupported = _mastra_core_storage.TRACE_QUERY_ORDER_FIELDS?.includes("timeToFirstChunkMs") === true;
+const timeToFirstChunkFeatures = [...timeToFirstChunkSupported ? ["trace-query-time-to-first-chunk"] : [], ...timeToFirstChunkSortSupported ? ["trace-query-time-to-first-chunk-sort"] : []];
+/**
+* Keyset bounds for a cursor's sort value: terms for rows strictly past it in `direction`, and the
+* condition for rows level with it. Empty values sort last in both directions, so they are past
+* every value and level only with each other.
+*/
+function keysetSortBounds(field, direction, sortValue, values) {
+	if (sortValue === null) return {
+		past: [],
+		level: `${field} IS NULL`
+	};
+	values.push(sortValue);
+	const parameter = `$${values.length}::${typeof sortValue === "number" ? "float8" : "timestamptz"}`;
+	return {
+		past: [`${field} ${direction === "asc" ? ">" : "<"} ${parameter}`, `${field} IS NULL`],
+		level: `${field} = ${parameter}`
+	};
+}
 function durationMsSql(startedAt, endedAt) {
 	return `EXTRACT(EPOCH FROM (${endedAt} - ${startedAt}))::numeric * 1000`;
 }
@@ -19227,6 +19246,7 @@ const TRACE_FIELDS = {
 	endedAt: "r.\"endedAt\"",
 	durationMs: durationMsSql("r.\"startedAt\"", "r.\"endedAt\""),
 	timeToFirstChunkMs: "r.\"timeToFirstChunkMs\"",
+	entityId: "r.\"entityId\"",
 	entityName: "r.\"entityName\"",
 	entityType: "r.\"entityType\"",
 	name: "r.\"name\"",
@@ -19528,6 +19548,7 @@ const ROOT_PUSHDOWN_FIELDS = /* @__PURE__ */ new Set([
 	"organizationId",
 	"startedAt",
 	"endedAt",
+	"entityId",
 	"entityName",
 	"entityType",
 	"name",
@@ -19803,8 +19824,8 @@ LIMIT $${values.length}`,
 			values
 		};
 	}
-	const orderField = plan.orderBy.field === "startedAt" ? "\"startedAt\"" : "\"endedAt\"";
-	const direction = plan.orderBy.direction === "asc" ? "ASC" : "DESC";
+	const orderField = `"${plan.orderBy.field}"`;
+	const direction = `${plan.orderBy.direction === "asc" ? "ASC" : "DESC"} NULLS LAST`;
 	if (plan.paginationMode === "page") {
 		values.push(plan.perPage, plan.page * plan.perPage);
 		return {
@@ -19818,10 +19839,9 @@ LIMIT $${values.length - 1} OFFSET $${values.length}`,
 	}
 	let pageCondition = "";
 	if (plan.cursor) {
-		const comparison = plan.orderBy.direction === "asc" ? ">" : "<";
-		const sortParameter = `$${values.length + 1}`;
-		pageCondition = `WHERE (${orderField} ${comparison} ${sortParameter} OR (${orderField} = ${sortParameter} AND "traceId" > ${`$${values.length + 2}`}))`;
-		values.push(plan.cursor.sortValue, plan.cursor.traceId);
+		const { past, level } = keysetSortBounds(orderField, plan.orderBy.direction, plan.cursor.sortValue, values);
+		values.push(plan.cursor.traceId);
+		pageCondition = `WHERE (${[...past, `(${level} AND "traceId" > $${values.length})`].join(" OR ")})`;
 	}
 	values.push(plan.limit + 1);
 	return {
@@ -20154,7 +20174,7 @@ async function queryTraces(client, schema, plan, timeoutMs) {
 		traces,
 		page: { next: rows.length > plan.limit && last ? _mastra_core_storage.encodeTraceQueryCursor(plan, {
 			result: "traces",
-			sortValue: last[plan.orderBy.field],
+			sortValue: last[plan.orderBy.field] ?? null,
 			traceId: last.traceId
 		}) : null }
 	});
@@ -20226,11 +20246,8 @@ function selectedKeys(rows, values) {
 function afterCursor(plan, values) {
 	if (!plan.cursor) return "TRUE";
 	const cursor = plan.cursor;
-	values.push(cursor.sortValue);
-	const timestamp = `$${values.length}::timestamptz`;
-	const field = `s."${plan.orderBy.field}"`;
-	const terms = [`${field} ${plan.orderBy.direction === "asc" ? ">" : "<"} ${timestamp}`];
-	const equal = [`${field} = ${timestamp}`];
+	const { past: terms, level } = keysetSortBounds(`s."${plan.orderBy.field}"`, plan.orderBy.direction, cursor.sortValue, values);
+	const equal = [level];
 	for (const key of identityFields) {
 		const ref = `s."${key}" COLLATE "C"`;
 		const value = cursor[key];
@@ -20296,7 +20313,7 @@ function compilePostgresSpanQuery(schema, plan) {
 			"version"
 		].map((field) => `s."${field}"`).join(", ")}
   FROM candidates s WHERE s."startedAt" >= $1 AND s."startedAt" < $2 AND (${predicate.sql}) AND ${after}
-  ORDER BY s."${plan.orderBy.field}" ${plan.orderBy.direction === "asc" ? "ASC" : "DESC"}, ${identityOrder}
+  ORDER BY s."${plan.orderBy.field}" ${plan.orderBy.direction === "asc" ? "ASC" : "DESC"} NULLS LAST, ${identityOrder}
   LIMIT $${values.length}`,
 		values
 	};
@@ -20617,6 +20634,7 @@ const DIMENSION_SQL = {
 	entityName: "r.\"entityName\"",
 	name: "r.\"name\"",
 	spanType: "r.\"spanType\"",
+	entityId: "r.\"entityId\"",
 	environment: "r.\"environment\"",
 	status: TRACE_STATUS_SQL,
 	serviceName: "r.\"serviceName\"",
@@ -21851,7 +21869,8 @@ var ObservabilityStoragePostgresVNext = class ObservabilityStoragePostgresVNext
 			"feedback",
 			"trace-query-context-ids",
 			...timeToFirstChunkFeatures,
-			"trace-query-root-span-fields"
+			"trace-query-root-span-fields",
+			"trace-query-root-entity-id"
 		];
 		return [
 			"metrics",
@@ -21874,7 +21893,8 @@ var ObservabilityStoragePostgresVNext = class ObservabilityStoragePostgresVNext
 			"feedback",
 			"trace-query-context-ids",
 			...timeToFirstChunkFeatures,
-			"trace-query-root-span-fields"
+			"trace-query-root-span-fields",
+			"trace-query-root-entity-id"
 		];
 	}
 	async #run(op, fn, details) {