@mastra/pg 1.0.0-beta.11 → 1.0.0-beta.12

package/dist/docs/vectors/01-reference.md

@@ -0,0 +1,307 @@
+# Vectors API Reference
+
+> API reference for vectors - 1 entries
+
+
+---
+
+## Reference: PG Vector Store
+
+> Documentation for the PgVector class in Mastra, which provides vector search using PostgreSQL with pgvector extension.
+
+The PgVector class provides vector search using [PostgreSQL](https://www.postgresql.org/) with [pgvector](https://github.com/pgvector/pgvector) extension.
+It provides robust vector similarity search capabilities within your existing PostgreSQL database.
+
+## Constructor Options
+
+## Constructor Examples
+
+### Connection String
+
+```ts
+import { PgVector } from "@mastra/pg";
+
+const vectorStore = new PgVector({
+  id: 'pg-vector',
+  connectionString: "postgresql://user:password@localhost:5432/mydb",
+});
+```
+
+### Host/Port/Database Configuration
+
+```ts
+const vectorStore = new PgVector({
+  id: 'pg-vector',
+  host: "localhost",
+  port: 5432,
+  database: "mydb",
+  user: "postgres",
+  password: "password",
+});
+```
+
+### Advanced Configuration
+
+```ts
+const vectorStore = new PgVector({
+  id: 'pg-vector',
+  connectionString: "postgresql://user:password@localhost:5432/mydb",
+  schemaName: "custom_schema",
+  max: 30,
+  idleTimeoutMillis: 60000,
+  pgPoolOptions: {
+    connectionTimeoutMillis: 5000,
+    allowExitOnIdle: true,
+  },
+});
+```
+
+## Methods
+
+### createIndex()
+
+#### IndexConfig
+
+#### Memory Requirements
+
+HNSW indexes require significant shared memory during construction. For 100K vectors:
+
+- Small dimensions (64d): ~60MB with default settings
+- Medium dimensions (256d): ~180MB with default settings
+- Large dimensions (384d+): ~250MB+ with default settings
+
+Higher M values or efConstruction values will increase memory requirements significantly. Adjust your system's shared memory limits if needed.
+
+### upsert()
+
+### query()
+
+### listIndexes()
+
+Returns an array of index names as strings.
+
+### describeIndex()
+
+Returns:
+
+```typescript
+interface PGIndexStats {
+  dimension: number;
+  count: number;
+  metric: "cosine" | "euclidean" | "dotproduct";
+  type: "flat" | "hnsw" | "ivfflat";
+  config: {
+    m?: number;
+    efConstruction?: number;
+    lists?: number;
+    probes?: number;
+  };
+}
+```
+
+### deleteIndex()
+
+### updateVector()
+
+Update a single vector by ID or by metadata filter. Either `id` or `filter` must be provided, but not both.
+
+Updates an existing vector by ID or filter. At least one of vector or metadata must be provided in the update object.
+
+```typescript
+// Update by ID
+await pgVector.updateVector({
+  indexName: "my_vectors",
+  id: "vector123",
+  update: {
+    vector: [0.1, 0.2, 0.3],
+    metadata: { label: "updated" },
+  },
+});
+
+// Update by filter
+await pgVector.updateVector({
+  indexName: "my_vectors",
+  filter: { category: "product" },
+  update: {
+    metadata: { status: "reviewed" },
+  },
+});
+```
+
+### deleteVector()
+
+Deletes a single vector by ID from the specified index.
+
+```typescript
+await pgVector.deleteVector({ indexName: "my_vectors", id: "vector123" });
+```
+
+### deleteVectors()
+
+Delete multiple vectors by IDs or by metadata filter. Either `ids` or `filter` must be provided, but not both.
+
+### disconnect()
+
+Closes the database connection pool. Should be called when done using the store.
+
+### buildIndex()
+
+Builds or rebuilds an index with specified metric and configuration. Will drop any existing index before creating the new one.
+
+```typescript
+// Define HNSW index
+await pgVector.buildIndex("my_vectors", "cosine", {
+  type: "hnsw",
+  hnsw: {
+    m: 8,
+    efConstruction: 32,
+  },
+});
+
+// Define IVF index
+await pgVector.buildIndex("my_vectors", "cosine", {
+  type: "ivfflat",
+  ivf: {
+    lists: 100,
+  },
+});
+
+// Define flat index
+await pgVector.buildIndex("my_vectors", "cosine", {
+  type: "flat",
+});
+```
+
+## Response Types
+
+Query results are returned in this format:
+
+```typescript
+interface QueryResult {
+  id: string;
+  score: number;
+  metadata: Record<string, any>;
+  vector?: number[]; // Only included if includeVector is true
+}
+```
+
+## Error Handling
+
+The store throws typed errors that can be caught:
+
+```typescript
+try {
+  await store.query({
+    indexName: "index_name",
+    queryVector: queryVector,
+  });
+} catch (error) {
+  if (error instanceof VectorStoreError) {
+    console.log(error.code); // 'connection_failed' | 'invalid_dimension' | etc
+    console.log(error.details); // Additional error context
+  }
+}
+```
+
+## Index Configuration Guide
+
+### Performance Optimization
+
+#### IVFFlat Tuning
+
+- **lists parameter**: Set to `sqrt(n) * 2` where n is the number of vectors
+- More lists = better accuracy but slower build time
+- Fewer lists = faster build but potentially lower accuracy
+
+#### HNSW Tuning
+
+- **m parameter**:
+  - 8-16: Moderate accuracy, lower memory
+  - 16-32: High accuracy, moderate memory
+  - 32-64: Very high accuracy, high memory
+- **efConstruction**:
+  - 32-64: Fast build, good quality
+  - 64-128: Slower build, better quality
+  - 128-256: Slowest build, best quality
+
+### Index Recreation Behavior
+
+The system automatically detects configuration changes and only rebuilds indexes when necessary:
+
+- Same configuration: Index is kept (no recreation)
+- Changed configuration: Index is dropped and rebuilt
+- This prevents the performance issues from unnecessary index recreations
+
+## Best Practices
+
+- Regularly evaluate your index configuration to ensure optimal performance.
+- Adjust parameters like `lists` and `m` based on dataset size and query requirements.
+- **Monitor index performance** using `describeIndex()` to track usage
+- Rebuild indexes periodically to maintain efficiency, especially after significant data changes
+
+## Direct Pool Access
+
+The `PgVector` class exposes its underlying PostgreSQL connection pool as a public field:
+
+```typescript
+pgVector.pool; // instance of pg.Pool
+```
+
+This enables advanced usage such as running direct SQL queries, managing transactions, or monitoring pool state. When using the pool directly:
+
+- You are responsible for releasing clients (`client.release()`) after use.
+- The pool remains accessible after calling `disconnect()`, but new queries will fail.
+- Direct access bypasses any validation or transaction logic provided by PgVector methods.
+
+This design supports advanced use cases but requires careful resource management by the user.
+
+## Usage Example
+
+### Local embeddings with fastembed
+
+Embeddings are numeric vectors used by memory's `semanticRecall` to retrieve related messages by meaning (not keywords). This setup uses `@mastra/fastembed` to generate vector embeddings.
+
+Install `fastembed` to get started:
+
+```bash
+npm install @mastra/fastembed@beta
+```
+
+Add the following to your agent:
+
+```typescript title="src/mastra/agents/example-pg-agent.ts"
+import { Memory } from "@mastra/memory";
+import { Agent } from "@mastra/core/agent";
+import { PostgresStore, PgVector } from "@mastra/pg";
+import { fastembed } from "@mastra/fastembed";
+
+export const pgAgent = new Agent({
+  id: "pg-agent",
+  name: "PG Agent",
+  instructions:
+    "You are an AI agent with the ability to automatically recall memories from previous interactions.",
+  model: "openai/gpt-5.1",
+  memory: new Memory({
+    storage: new PostgresStore({
+      id: 'pg-agent-storage',
+      connectionString: process.env.DATABASE_URL!,
+    }),
+    vector: new PgVector({
+      id: 'pg-agent-vector',
+      connectionString: process.env.DATABASE_URL!,
+    }),
+    embedder: fastembed,
+    options: {
+      lastMessages: 10,
+      semanticRecall: {
+        topK: 3,
+        messageRange: 2,
+      },
+    },
+  }),
+});
+```
+
+## Related
+
+- [Metadata Filters](../rag/metadata-filters)

package/dist/index.cjs

@@ -3253,13 +3253,19 @@ var MemoryPG = class _MemoryPG extends storage.MemoryStorage {
         };
       }
       const limitValue = perPageInput === false ? total : perPage;
-      const dataQuery = `SELECT id, "resourceId", title, metadata, "createdAt", "updatedAt" ${baseQuery} ORDER BY "${field}" ${direction} LIMIT $2 OFFSET $3`;
-      const rows = await this.#db.client.manyOrNone(dataQuery, [...queryParams, limitValue, offset]);
+      const dataQuery = `SELECT id, "resourceId", title, metadata, "createdAt", "createdAtZ", "updatedAt", "updatedAtZ" ${baseQuery} ORDER BY "${field}" ${direction} LIMIT $2 OFFSET $3`;
+      const rows = await this.#db.client.manyOrNone(
+        dataQuery,
+        [...queryParams, limitValue, offset]
+      );
       const threads = (rows || []).map((thread) => ({
-        ...thread,
+        id: thread.id,
+        resourceId: thread.resourceId,
+        title: thread.title,
         metadata: typeof thread.metadata === "string" ? JSON.parse(thread.metadata) : thread.metadata,
-        createdAt: thread.createdAt,
-        updatedAt: thread.updatedAt
+        // Use timezone-aware columns (*Z) for correct UTC timestamps, with fallback for legacy data
+        createdAt: thread.createdAtZ || thread.createdAt,
+        updatedAt: thread.updatedAtZ || thread.updatedAt
       }));
       return {
         threads,
@@ -3587,11 +3593,13 @@ var MemoryPG = class _MemoryPG extends storage.MemoryStorage {
         queryParams.push(resourceId);
       }
       if (filter?.dateRange?.start) {
-        conditions.push(`"createdAt" >= $${paramIndex++}`);
+        const startOp = filter.dateRange.startExclusive ? ">" : ">=";
+        conditions.push(`"createdAt" ${startOp} $${paramIndex++}`);
         queryParams.push(filter.dateRange.start);
       }
       if (filter?.dateRange?.end) {
-        conditions.push(`"createdAt" <= $${paramIndex++}`);
+        const endOp = filter.dateRange.endExclusive ? "<" : "<=";
+        conditions.push(`"createdAt" ${endOp} $${paramIndex++}`);
         queryParams.push(filter.dateRange.end);
       }
       const whereClause = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
@@ -3976,6 +3984,150 @@ var MemoryPG = class _MemoryPG extends storage.MemoryStorage {
     await this.#db.client.none(`UPDATE ${tableName} SET ${updates.join(", ")} WHERE id = $${paramIndex}`, values);
     return updatedResource;
   }
+  async cloneThread(args) {
+    const { sourceThreadId, newThreadId: providedThreadId, resourceId, title, metadata, options } = args;
+    const sourceThread = await this.getThreadById({ threadId: sourceThreadId });
+    if (!sourceThread) {
+      throw new error.MastraError({
+        id: storage.createStorageErrorId("PG", "CLONE_THREAD", "SOURCE_NOT_FOUND"),
+        domain: error.ErrorDomain.STORAGE,
+        category: error.ErrorCategory.USER,
+        text: `Source thread with id ${sourceThreadId} not found`,
+        details: { sourceThreadId }
+      });
+    }
+    const newThreadId = providedThreadId || crypto.randomUUID();
+    const existingThread = await this.getThreadById({ threadId: newThreadId });
+    if (existingThread) {
+      throw new error.MastraError({
+        id: storage.createStorageErrorId("PG", "CLONE_THREAD", "THREAD_EXISTS"),
+        domain: error.ErrorDomain.STORAGE,
+        category: error.ErrorCategory.USER,
+        text: `Thread with id ${newThreadId} already exists`,
+        details: { newThreadId }
+      });
+    }
+    const threadTableName = getTableName3({ indexName: storage.TABLE_THREADS, schemaName: getSchemaName3(this.#schema) });
+    const messageTableName = getTableName3({ indexName: storage.TABLE_MESSAGES, schemaName: getSchemaName3(this.#schema) });
+    try {
+      return await this.#db.client.tx(async (t) => {
+        let messageQuery = `SELECT id, content, role, type, "createdAt", "createdAtZ", thread_id AS "threadId", "resourceId"
+                            FROM ${messageTableName} WHERE thread_id = $1`;
+        const messageParams = [sourceThreadId];
+        let paramIndex = 2;
+        if (options?.messageFilter?.startDate) {
+          messageQuery += ` AND "createdAt" >= $${paramIndex++}`;
+          messageParams.push(options.messageFilter.startDate);
+        }
+        if (options?.messageFilter?.endDate) {
+          messageQuery += ` AND "createdAt" <= $${paramIndex++}`;
+          messageParams.push(options.messageFilter.endDate);
+        }
+        if (options?.messageFilter?.messageIds && options.messageFilter.messageIds.length > 0) {
+          messageQuery += ` AND id IN (${options.messageFilter.messageIds.map(() => `$${paramIndex++}`).join(", ")})`;
+          messageParams.push(...options.messageFilter.messageIds);
+        }
+        messageQuery += ` ORDER BY "createdAt" ASC`;
+        if (options?.messageLimit && options.messageLimit > 0) {
+          const limitQuery = `SELECT * FROM (${messageQuery.replace('ORDER BY "createdAt" ASC', 'ORDER BY "createdAt" DESC')} LIMIT $${paramIndex}) AS limited ORDER BY "createdAt" ASC`;
+          messageParams.push(options.messageLimit);
+          messageQuery = limitQuery;
+        }
+        const sourceMessages = await t.manyOrNone(messageQuery, messageParams);
+        const now = /* @__PURE__ */ new Date();
+        const lastMessageId = sourceMessages.length > 0 ? sourceMessages[sourceMessages.length - 1].id : void 0;
+        const cloneMetadata = {
+          sourceThreadId,
+          clonedAt: now,
+          ...lastMessageId && { lastMessageId }
+        };
+        const newThread = {
+          id: newThreadId,
+          resourceId: resourceId || sourceThread.resourceId,
+          title: title || (sourceThread.title ? `Clone of ${sourceThread.title}` : void 0),
+          metadata: {
+            ...metadata,
+            clone: cloneMetadata
+          },
+          createdAt: now,
+          updatedAt: now
+        };
+        await t.none(
+          `INSERT INTO ${threadTableName} (
+            id,
+            "resourceId",
+            title,
+            metadata,
+            "createdAt",
+            "createdAtZ",
+            "updatedAt",
+            "updatedAtZ"
+          ) VALUES ($1, $2, $3, $4, $5, $6, $7, $8)`,
+          [
+            newThread.id,
+            newThread.resourceId,
+            newThread.title,
+            newThread.metadata ? JSON.stringify(newThread.metadata) : null,
+            now,
+            now,
+            now,
+            now
+          ]
+        );
+        const clonedMessages = [];
+        const targetResourceId = resourceId || sourceThread.resourceId;
+        for (const sourceMsg of sourceMessages) {
+          const newMessageId = crypto.randomUUID();
+          const normalizedMsg = this.normalizeMessageRow(sourceMsg);
+          let parsedContent = normalizedMsg.content;
+          try {
+            parsedContent = JSON.parse(normalizedMsg.content);
+          } catch {
+          }
+          await t.none(
+            `INSERT INTO ${messageTableName} (id, thread_id, content, "createdAt", "createdAtZ", role, type, "resourceId")
+             VALUES ($1, $2, $3, $4, $5, $6, $7, $8)`,
+            [
+              newMessageId,
+              newThreadId,
+              typeof normalizedMsg.content === "string" ? normalizedMsg.content : JSON.stringify(normalizedMsg.content),
+              normalizedMsg.createdAt,
+              normalizedMsg.createdAt,
+              normalizedMsg.role,
+              normalizedMsg.type || "v2",
+              targetResourceId
+            ]
+          );
+          clonedMessages.push({
+            id: newMessageId,
+            threadId: newThreadId,
+            content: parsedContent,
+            role: normalizedMsg.role,
+            type: normalizedMsg.type,
+            createdAt: new Date(normalizedMsg.createdAt),
+            resourceId: targetResourceId
+          });
+        }
+        return {
+          thread: newThread,
+          clonedMessages
+        };
+      });
+    } catch (error$1) {
+      if (error$1 instanceof error.MastraError) {
+        throw error$1;
+      }
+      throw new error.MastraError(
+        {
+          id: storage.createStorageErrorId("PG", "CLONE_THREAD", "FAILED"),
+          domain: error.ErrorDomain.STORAGE,
+          category: error.ErrorCategory.THIRD_PARTY,
+          details: { sourceThreadId, newThreadId }
+        },
+        error$1
+      );
+    }
+  }
 };
 var ObservabilityPG = class _ObservabilityPG extends storage.ObservabilityStorage {
   #db;