@mastra/pg 1.33.0 → 1.34.0-alpha.1

package/README.md

@@ -28,7 +28,7 @@ const vectorStore = new PgVector({
 
 ## Documentation
 
-- [@mastra/pg documentation](https://mastra.ai/reference/vectors/pg)
+- [@mastra/pg documentation](https://mastra.ai/integrations/vectors/pg)
 
 ## Changelog
 

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.33.0"
+  version: "1.34.0-alpha.1"
 ---
 
 ## When to use
@@ -27,6 +27,7 @@ Read the individual reference documents for detailed explanations and code examp
 - [DynamoDB](references/integrations-databases-dynamodb.md) - Persist Mastra data in Amazon DynamoDB with a single-table ElectroDB design, configurable indexes, TTL support, credentials, and table initialization.
 - [Neon Postgres](references/integrations-databases-neon.md) - Connect Mastra to Neon Postgres with PostgresStore, pooled production connections, schema initialization, vector search, and Neon agent skills.
 - [PostgreSQL](references/integrations-databases-postgresql.md) - Persist Mastra application data in PostgreSQL with PostgresStore, configure connections and pools, initialize schemas, and enable observability.
+- [PG](references/integrations-vectors-pg.md) - Run pgvector similarity search inside PostgreSQL from Mastra with HNSW or IVFFlat indexing, metadata filtering, and direct connection pool access.
 
 ### Reference
 
@@ -42,7 +43,6 @@ Read the individual reference documents for detailed explanations and code examp
 - [Reference: Composite storage](references/reference-storage-composite.md) - MastraCompositeStore can compose storage domains from different providers. Use it when you need different databases for different purposes.
 - [Reference: Storage retention (prune)](references/reference-storage-retention.md) - prune() deletes rows. It caps growth and is safe to run against large tables (batched, bounded, resumable, cancellable).
 - [Reference: createVectorQueryTool()](references/reference-tools-vector-query-tool.md) - The createVectorQueryTool() function creates a tool for semantic search over vector stores.
-- [Reference: PG vector store](references/reference-vectors-pg.md) - The PgVector class provides vector search using PostgreSQL with pgvector extension. It provides reliable vector similarity search capabilities within your existing PostgreSQL database.
 
 
 Read [assets/SOURCE_MAP.json](assets/SOURCE_MAP.json) for source code references.

package/dist/docs/assets/SOURCE_MAP.json

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

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

@@ -141,24 +141,24 @@ const agent = new Agent({
 
 Each vector store page below includes installation instructions, configuration parameters, and usage examples:
 
-- [Astra](https://mastra.ai/reference/vectors/astra)
-- [Chroma](https://mastra.ai/reference/vectors/chroma)
-- [Cloudflare Vectorize](https://mastra.ai/reference/vectors/vectorize)
-- [Convex](https://mastra.ai/reference/vectors/convex)
-- [Couchbase](https://mastra.ai/reference/vectors/couchbase)
-- [DuckDB](https://mastra.ai/reference/vectors/duckdb)
-- [Elasticsearch](https://mastra.ai/reference/vectors/elasticsearch)
-- [LanceDB](https://mastra.ai/reference/vectors/lance)
-- [libSQL](https://mastra.ai/reference/vectors/libsql)
-- [MongoDB](https://mastra.ai/reference/vectors/mongodb)
-- [OpenSearch](https://mastra.ai/reference/vectors/opensearch)
-- [OracleDB](https://mastra.ai/reference/vectors/oracledb)
-- [Pinecone](https://mastra.ai/reference/vectors/pinecone)
-- [PostgreSQL](https://mastra.ai/reference/vectors/pg)
-- [Qdrant](https://mastra.ai/reference/vectors/qdrant)
-- [S3 Vectors](https://mastra.ai/reference/vectors/s3vectors)
-- [Turbopuffer](https://mastra.ai/reference/vectors/turbopuffer)
-- [Upstash](https://mastra.ai/reference/vectors/upstash)
+- [Astra](https://mastra.ai/integrations/vectors/astra)
+- [Chroma](https://mastra.ai/integrations/vectors/chroma)
+- [Cloudflare Vectorize](https://mastra.ai/integrations/vectors/vectorize)
+- [Convex](https://mastra.ai/integrations/vectors/convex)
+- [Couchbase](https://mastra.ai/integrations/vectors/couchbase)
+- [DuckDB](https://mastra.ai/integrations/vectors/duckdb)
+- [Elasticsearch](https://mastra.ai/integrations/vectors/elasticsearch)
+- [LanceDB](https://mastra.ai/integrations/vectors/lance)
+- [libSQL](https://mastra.ai/integrations/vectors/libsql)
+- [MongoDB](https://mastra.ai/integrations/vectors/mongodb)
+- [OpenSearch](https://mastra.ai/integrations/vectors/opensearch)
+- [OracleDB](https://mastra.ai/integrations/vectors/oracledb)
+- [Pinecone](https://mastra.ai/integrations/vectors/pinecone)
+- [PostgreSQL](https://mastra.ai/integrations/vectors/pg)
+- [Qdrant](https://mastra.ai/integrations/vectors/qdrant)
+- [S3 Vectors](https://mastra.ai/integrations/vectors/s3vectors)
+- [Turbopuffer](https://mastra.ai/integrations/vectors/turbopuffer)
+- [Upstash](https://mastra.ai/integrations/vectors/upstash)
 
 ## Recall configuration
 
@@ -250,7 +250,7 @@ const options = {
 
 Some vector stores generate the embeddings themselves. With one of those, semantic recall runs without an `embedder`: the database embeds each message on write and the search string on arrival. The embedding provider stays out of your application entirely.
 
-MongoDB does this through [Automated Embedding](https://mastra.ai/reference/vectors/mongodb): name a Voyage AI model on the vector store and leave the `embedder` out.
+MongoDB does this through [Automated Embedding](https://mastra.ai/integrations/vectors/mongodb): name a Voyage AI model on the vector store and leave the `embedder` out.
 
 ```typescript
 import { Memory } from '@mastra/memory'
@@ -467,7 +467,7 @@ 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).
+For detailed information about index configuration options and performance tuning, see the [PgVector configuration guide](https://mastra.ai/integrations/vectors/pg).
 
 ## Disable semantic recall
 

package/dist/docs/references/integrations-databases-neon.md

@@ -207,7 +207,7 @@ See [Neon connection pooling](https://neon.com/docs/connect/connection-pooling)
 
 ## Vector search
 
-Neon supports the [`pgvector` extension](https://neon.com/docs/extensions/pgvector). Use the direct `DATABASE_URL_UNPOOLED` connection while creating the extension and indexes. After setup, configure [`PgVector`](https://mastra.ai/reference/vectors/pg) with the pooled connection for runtime queries:
+Neon supports the [`pgvector` extension](https://neon.com/docs/extensions/pgvector). Use the direct `DATABASE_URL_UNPOOLED` connection while creating the extension and indexes. After setup, configure [`PgVector`](https://mastra.ai/integrations/vectors/pg) with the pooled connection for runtime queries:
 
 ```typescript
 import { PgVector } from '@mastra/pg'

package/dist/docs/references/integrations-databases-postgresql.md

@@ -174,6 +174,37 @@ const storage = new PostgresStoreVNext({
 
 Lower `lookbackSeconds` if refreshes are slow, and raise `ttlSeconds` if they run more often than your filter values change. Only one process refreshes a given cache entry at a time, so adding server instances doesn't multiply the work.
 
+#### Day partitions
+
+`PostgresStoreVNext` stores observability events in tables partitioned by day. If TimescaleDB or pg_partman is installed, that extension creates partitions for you. Without an extension, `init()` creates the partitions for yesterday, today, and the next `futureDays` days (default 14), and a write that lands on a day inside that window with no partition creates it before it retries, so writes keep working after the pre-created window runs out. Rows dated outside the window are still rejected.
+
+Creating a partition is DDL. If the role your app runs with cannot create tables, or does not own the observability tables, the write fails with an error that names the table and the missing day, and the exporter drops that batch after its retries. In that setup, call `ensurePartitions()` on a schedule, at least once every `futureDays` days, with a role that can create tables and owns the observability tables. It only extends the native day-partition window, and does nothing with TimescaleDB or pg_partman. You can also install TimescaleDB, or pg_partman with its background worker or a scheduled `run_maintenance()` call, so the database maintains the partitions itself.
+
+A larger `futureDays` gives the scheduled job more time between runs:
+
+```typescript
+import { PostgresStoreVNext } from '@mastra/pg'
+
+const storage = new PostgresStoreVNext({
+  id: 'pg-storage',
+  connectionString: process.env.DATABASE_URL,
+  observability: {
+    connectionString: process.env.OBSERVABILITY_DATABASE_URL,
+    partitioning: {
+      futureDays: 60, // pre-create 60 days of partitions on init()
+    },
+  },
+})
+```
+
+Then call `ensurePartitions()` from the scheduled job:
+
+```typescript
+// OBSERVABILITY_DATABASE_URL connects as a role that owns the observability tables
+await storage.ensurePartitions()
+await storage.close()
+```
+
 ### Initialization
 
 When you pass storage to the Mastra class, `init()` is called automatically before any storage operation:

package/dist/docs/references/{reference-vectors-pg.md → integrations-vectors-pg.md}

@@ -8,6 +8,8 @@ The PgVector class provides vector search using [PostgreSQL](https://www.postgre
 
 ## Constructor options
 
+**id** (`string`): Unique identifier for this vector store instance
+
 **connectionString** (`string`): PostgreSQL connection URL
 
 **host** (`string`): PostgreSQL server host
@@ -182,6 +184,16 @@ interface PGIndexStats {
 
 **indexName** (`string`): Name of the index to delete
 
+### `truncateIndex()`
+
+Deletes every vector in an index while keeping the index itself.
+
+**indexName** (`string`): Name of the index to clear
+
+```typescript
+await vectorStore.truncateIndex({ indexName: 'my_vectors' })
+```
+
 ### `updateVector()`
 
 Update a single vector by ID or by metadata filter. Either `id` or `filter` must be provided, but not both.

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

@@ -61,6 +61,83 @@ export const agent = new Agent({
 
 **memory** (`Memory`): A new Memory instance with the specified configuration.
 
+## `saveMessages()`
+
+`agent.generate()` and `agent.stream()` persist messages for you. Call `memory.saveMessages()` when you need to write messages yourself, for example to seed a thread, to import a transcript, or to store messages that originated outside Mastra. Each message needs a `threadId` and a `resourceId`, so create the thread with [`createThread()`](https://mastra.ai/reference/memory/createThread) before saving into it.
+
+```typescript
+await memory.saveMessages({
+  messages: [
+    {
+      id: 'msg-1',
+      threadId: 'thread-123',
+      resourceId: 'user-456',
+      role: 'user',
+      createdAt: new Date(),
+      content: {
+        format: 2,
+        parts: [{ type: 'text', text: 'Where is my order?' }],
+      },
+    },
+  ],
+})
+```
+
+### Parameters
+
+**messages** (`MastraDBMessage[]`): The messages to save. Every message must include a threadId and a resourceId.
+
+**memoryConfig** (`MemoryConfig`): Per-call memory options. Merged over the options passed to the constructor.
+
+**observabilityContext** (`Partial<ObservabilityContext>`): Tracing context attached to the save operation.
+
+Returns `Promise<{ messages: MastraDBMessage[]; usage?: { tokens: number } }>`. `usage` is present when the embedder reports token usage while indexing messages for semantic recall.
+
+### `MastraDBMessage`
+
+Storage uses a single message shape, `MastraDBMessage`. The methods that hand messages back or take them in use this shape, including `saveMessages()` and [`recall()`](https://mastra.ai/reference/memory/recall).
+
+**id** (`string`): Message identifier.
+
+**role** (`'user' | 'assistant' | 'system' | 'signal'`): Who produced the message. System messages and transient signals are not persisted.
+
+**threadId** (`string`): Thread the message belongs to. Required when saving.
+
+**resourceId** (`string`): Resource (usually a user or tenant) the message belongs to. Required when saving.
+
+**createdAt** (`Date`): Message timestamp.
+
+**content** (`MastraMessageContentV2`): The message body. Its parts array holds the text, reasoning, tool calls, and attachments.
+
+`content.parts` is the part the agent actually reads. `content.format` is always `2` for stored messages, and `content.metadata` carries arbitrary custom data. `content.toolInvocations`, `content.reasoning`, and `content.experimental_attachments` are flat mirrors kept for AI SDK v4 compatibility; write to `parts` instead.
+
+```typescript
+const assistantMessage = {
+  id: 'msg-2',
+  threadId: 'thread-123',
+  resourceId: 'user-456',
+  role: 'assistant',
+  createdAt: new Date(),
+  content: {
+    format: 2,
+    parts: [
+      { type: 'text', text: 'It ships tomorrow.' },
+      {
+        type: 'tool-invocation',
+        toolInvocation: {
+          state: 'result',
+          toolCallId: 'call-1',
+          toolName: 'lookupOrder',
+          args: { orderId: 'A-1' },
+          result: { eta: '2026-10-30' },
+        },
+      },
+    ],
+    metadata: { source: 'import' },
+  },
+}
+```
+
 ## Extended usage example
 
 ```typescript

package/dist/docs/references/reference-rag-metadata-filters.md

@@ -225,14 +225,14 @@ await store.createIndex({
 
 ## Related
 
-- [Astra](https://mastra.ai/reference/vectors/astra)
-- [Chroma](https://mastra.ai/reference/vectors/chroma)
-- [Cloudflare Vectorize](https://mastra.ai/reference/vectors/vectorize)
-- [libSQL](https://mastra.ai/reference/vectors/libsql)
-- [MongoDB](https://mastra.ai/reference/vectors/mongodb)
-- [OracleDB](https://mastra.ai/reference/vectors/oracledb)
-- [PgVector](https://mastra.ai/reference/vectors/pg)
-- [Pinecone](https://mastra.ai/reference/vectors/pinecone)
-- [Qdrant](https://mastra.ai/reference/vectors/qdrant)
-- [Upstash](https://mastra.ai/reference/vectors/upstash)
-- [Amazon S3 Vectors](https://mastra.ai/reference/vectors/s3vectors)
+- [Astra](https://mastra.ai/integrations/vectors/astra)
+- [Chroma](https://mastra.ai/integrations/vectors/chroma)
+- [Cloudflare Vectorize](https://mastra.ai/integrations/vectors/vectorize)
+- [libSQL](https://mastra.ai/integrations/vectors/libsql)
+- [MongoDB](https://mastra.ai/integrations/vectors/mongodb)
+- [OracleDB](https://mastra.ai/integrations/vectors/oracledb)
+- [PgVector](https://mastra.ai/integrations/vectors/pg)
+- [Pinecone](https://mastra.ai/integrations/vectors/pinecone)
+- [Qdrant](https://mastra.ai/integrations/vectors/qdrant)
+- [Upstash](https://mastra.ai/integrations/vectors/upstash)
+- [Amazon S3 Vectors](https://mastra.ai/integrations/vectors/s3vectors)

package/dist/docs/references/reference-rag-vector-databases.md

@@ -35,7 +35,7 @@ MongoDB Vector Search is a good solution for teams who want to consolidate vecto
 
 ### Using VoyageAI with MongoDB
 
-MongoDB works directly with VoyageAI's embedding models, which are optimized for retrieval tasks. For complete examples and specialized models, see the [VoyageAI embeddings documentation](https://mastra.ai/models/embeddings) and [MongoDB vector reference](https://mastra.ai/reference/vectors/mongodb).
+MongoDB works directly with VoyageAI's embedding models, which are optimized for retrieval tasks. For complete examples and specialized models, see the [VoyageAI embeddings documentation](https://mastra.ai/models/embeddings) and [MongoDB vector reference](https://mastra.ai/integrations/vectors/mongodb).
 
 ### Hybrid Search (Vector + Full-Text)
 
@@ -52,7 +52,7 @@ const results = await store.hybridQuery({
 })
 ```
 
-See the [MongoDB vector reference](https://mastra.ai/reference/vectors/mongodb) for details on `createSearchIndex()`, `textQuery()`, and `hybridQuery()`.
+See the [MongoDB vector reference](https://mastra.ai/integrations/vectors/mongodb) for details on `createSearchIndex()`, `textQuery()`, and `hybridQuery()`.
 
 ### Automated Embedding
 
@@ -75,7 +75,7 @@ const results = await store.query({
 })
 ```
 
-Automated Embedding is a MongoDB Preview feature and needs a deployment where it's available. See the [MongoDB vector reference](https://mastra.ai/reference/vectors/mongodb) for the supported options and requirements.
+Automated Embedding is a MongoDB Preview feature and needs a deployment where it's available. See the [MongoDB vector reference](https://mastra.ai/integrations/vectors/mongodb) for the supported options and requirements.
 
 **PgVector**: