@mastra/pg 1.8.0-alpha.0 → 1.8.0

package/CHANGELOG.md

@@ -1,5 +1,67 @@
 # @mastra/pg
 
+## 1.8.0
+
+### Minor Changes
+
+- Added `metadataIndexes` option to `createIndex()` for PgVector. This allows creating btree indexes on specific metadata fields in vector tables, significantly improving query performance when filtering by those fields. This is especially impactful for Memory's `memory_messages` table, which filters by `thread_id` and `resource_id` — previously causing sequential scans under load. ([#14034](https://github.com/mastra-ai/mastra/pull/14034))
+
+  **Usage example:**
+
+  ```ts
+  await pgVector.createIndex({
+    indexName: 'my_vectors',
+    dimension: 1536,
+    metadataIndexes: ['thread_id', 'resource_id'],
+  });
+  ```
+
+  Fixes #12109
+
+- Add support for pgvector's `bit` and `sparsevec` vector storage types ([#12815](https://github.com/mastra-ai/mastra/pull/12815))
+
+  You can now store binary and sparse vectors in `@mastra/pg`:
+
+  ```ts
+  // Binary vectors for fast similarity search
+  await db.createIndex({
+    indexName: 'my_binary_index',
+    dimension: 128,
+    metric: 'hamming', // or 'jaccard'
+    vectorType: 'bit',
+  });
+
+  // Sparse vectors for BM25/TF-IDF representations
+  await db.createIndex({
+    indexName: 'my_sparse_index',
+    dimension: 500,
+    metric: 'cosine',
+    vectorType: 'sparsevec',
+  });
+  ```
+
+  What's new:
+  - `vectorType: 'bit'` for binary vectors with `'hamming'` and `'jaccard'` distance metrics
+  - `vectorType: 'sparsevec'` for sparse vectors (cosine, euclidean, dotproduct)
+  - Automatic metric normalization: `bit` defaults to `'hamming'` when no metric is specified
+  - `includeVector` round-trips work correctly for all vector types
+  - Requires pgvector >= 0.7.0
+
+- Added `requestContext` column to the spans table. Request context data from tracing is now persisted alongside other span data. ([#14020](https://github.com/mastra-ai/mastra/pull/14020))
+
+- Added `requestContext` and `requestContextSchema` column support to dataset storage. Dataset items now persist request context alongside input and ground truth data. ([#13938](https://github.com/mastra-ai/mastra/pull/13938))
+
+### Patch Changes
+
+- Added resilient column handling to insert and update operations. Unknown columns in records are now silently dropped instead of causing SQL errors, ensuring forward compatibility when newer domain packages add fields that haven't been migrated yet. ([#14021](https://github.com/mastra-ai/mastra/pull/14021))
+
+  For example, calling `db.insert({ tableName, record: { id: '1', title: 'Hello', futureField: 'value' } })` will silently ignore `futureField` if it doesn't exist in the database table, rather than throwing. The same applies to `update` — unknown fields in the data payload are dropped before building the SQL statement.
+
+- Fixed slow semantic recall in the Postgres storage adapter for large threads. Recall now completes in under 500ms even for threads with 7,000+ messages, down from ~30 seconds. (Fixes #11702) ([#14022](https://github.com/mastra-ai/mastra/pull/14022))
+
+- Updated dependencies [[`4f71b43`](https://github.com/mastra-ai/mastra/commit/4f71b436a4a6b8839842d8da47b57b84509af56c), [`a070277`](https://github.com/mastra-ai/mastra/commit/a07027766ce195ba74d0783116d894cbab25d44c), [`b628b91`](https://github.com/mastra-ai/mastra/commit/b628b9128b372c0f54214d902b07279f03443900), [`332c014`](https://github.com/mastra-ai/mastra/commit/332c014e076b81edf7fe45b58205882726415e90), [`6b63153`](https://github.com/mastra-ai/mastra/commit/6b63153878ea841c0f4ce632ba66bb33e57e9c1b), [`4246e34`](https://github.com/mastra-ai/mastra/commit/4246e34cec9c26636d0965942268e6d07c346671), [`b8837ee`](https://github.com/mastra-ai/mastra/commit/b8837ee77e2e84197609762bfabd8b3da326d30c), [`866cc2c`](https://github.com/mastra-ai/mastra/commit/866cc2cb1f0e3b314afab5194f69477fada745d1), [`5d950f7`](https://github.com/mastra-ai/mastra/commit/5d950f7bf426a215a1808f0abef7de5c8336ba1c), [`28c85b1`](https://github.com/mastra-ai/mastra/commit/28c85b184fc32b40f7f160483c982da6d388ecbd), [`e9a08fb`](https://github.com/mastra-ai/mastra/commit/e9a08fbef1ada7e50e961e2f54f55e8c10b4a45c), [`1d0a8a8`](https://github.com/mastra-ai/mastra/commit/1d0a8a8acf33203d5744fc429b090ad8598aa8ed), [`631ffd8`](https://github.com/mastra-ai/mastra/commit/631ffd82fed108648b448b28e6a90e38c5f53bf5), [`6bcbf8a`](https://github.com/mastra-ai/mastra/commit/6bcbf8a6774d5a53b21d61db8a45ce2593ca1616), [`aae2295`](https://github.com/mastra-ai/mastra/commit/aae2295838a2d329ad6640829e87934790ffe5b8), [`aa61f29`](https://github.com/mastra-ai/mastra/commit/aa61f29ff8095ce46a4ae16e46c4d8c79b2b685b), [`7ff3714`](https://github.com/mastra-ai/mastra/commit/7ff37148515439bb3be009a60e02c3e363299760), [`18c3a90`](https://github.com/mastra-ai/mastra/commit/18c3a90c9e48cf69500e308affeb8eba5860b2af), [`41d79a1`](https://github.com/mastra-ai/mastra/commit/41d79a14bd8cb6de1e2565fd0a04786bae2f211b), [`f35487b`](https://github.com/mastra-ai/mastra/commit/f35487bb2d46c636e22aa71d90025613ae38235a), [`6dc2192`](https://github.com/mastra-ai/mastra/commit/6dc21921aef0f0efab15cd0805fa3d18f277a76f), [`eeb3a3f`](https://github.com/mastra-ai/mastra/commit/eeb3a3f43aca10cf49479eed2a84b7d9ecea02ba), [`e673376`](https://github.com/mastra-ai/mastra/commit/e6733763ad1321aa7e5ae15096b9c2104f93b1f3), [`05f8d90`](https://github.com/mastra-ai/mastra/commit/05f8d9009290ce6aa03428b3add635268615db85), [`b2204c9`](https://github.com/mastra-ai/mastra/commit/b2204c98a42848bbfb6f0440f005dc2b6354f1cd), [`a1bf1e3`](https://github.com/mastra-ai/mastra/commit/a1bf1e385ed4c0ef6f11b56c5887442970d127f2), [`b6f647a`](https://github.com/mastra-ai/mastra/commit/b6f647ae2388e091f366581595feb957e37d5b40), [`0c57b8b`](https://github.com/mastra-ai/mastra/commit/0c57b8b0a69a97b5a4ae3f79be6c610f29f3cf7b), [`b081f27`](https://github.com/mastra-ai/mastra/commit/b081f272cf411716e1d6bd72ceac4bcee2657b19), [`4b8da97`](https://github.com/mastra-ai/mastra/commit/4b8da97a5ce306e97869df6c39535d9069e563db), [`0c09eac`](https://github.com/mastra-ai/mastra/commit/0c09eacb1926f64cfdc9ae5c6d63385cf8c9f72c), [`6b9b93d`](https://github.com/mastra-ai/mastra/commit/6b9b93d6f459d1ba6e36f163abf62a085ddb3d64), [`31b6067`](https://github.com/mastra-ai/mastra/commit/31b6067d0cc3ab10e1b29c36147f3b5266bc714a), [`797ac42`](https://github.com/mastra-ai/mastra/commit/797ac4276de231ad2d694d9aeca75980f6cd0419), [`0bc289e`](https://github.com/mastra-ai/mastra/commit/0bc289e2d476bf46c5b91c21969e8d0c6864691c), [`9b75a06`](https://github.com/mastra-ai/mastra/commit/9b75a06e53ebb0b950ba7c1e83a0142047185f46), [`4c3a1b1`](https://github.com/mastra-ai/mastra/commit/4c3a1b122ea083e003d71092f30f3b31680b01c0), [`256df35`](https://github.com/mastra-ai/mastra/commit/256df3571d62beb3ad4971faa432927cc140e603), [`85cc3b3`](https://github.com/mastra-ai/mastra/commit/85cc3b3b6f32ae4b083c26498f50d5b250ba944b), [`97ea28c`](https://github.com/mastra-ai/mastra/commit/97ea28c746e9e4147d56047bbb1c4a92417a3fec), [`d567299`](https://github.com/mastra-ai/mastra/commit/d567299cf81e02bd9d5221d4bc05967d6c224161), [`716ffe6`](https://github.com/mastra-ai/mastra/commit/716ffe68bed81f7c2690bc8581b9e140f7bf1c3d), [`8296332`](https://github.com/mastra-ai/mastra/commit/8296332de21c16e3dfc3d0b2d615720a6dc88f2f), [`4df2116`](https://github.com/mastra-ai/mastra/commit/4df211619dd922c047d396ca41cd7027c8c4c8e7), [`2219c1a`](https://github.com/mastra-ai/mastra/commit/2219c1acbd21da116da877f0036ffb985a9dd5a3), [`17c4145`](https://github.com/mastra-ai/mastra/commit/17c4145166099354545582335b5252bdfdfd908b)]:
+  - @mastra/core@1.11.0
+
 ## 1.8.0-alpha.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.8.0-alpha.0"
+  version: "1.8.0"
 ---
 
 ## When to use
@@ -16,25 +16,25 @@ Read the individual reference documents for detailed explanations and code examp
 
 ### Docs
 
-- [Semantic Recall](references/docs-memory-semantic-recall.md) - Learn how to use semantic recall in Mastra to retrieve relevant messages from past conversations using vector search and embeddings.
+- [Semantic recall](references/docs-memory-semantic-recall.md) - Learn how to use semantic recall in Mastra to retrieve relevant messages from past conversations using vector search and embeddings.
 - [Storage](references/docs-memory-storage.md) - Configure storage for Mastra's memory system to persist conversations, workflows, and traces.
-- [Working Memory](references/docs-memory-working-memory.md) - Learn how to configure working memory in Mastra to store persistent user data, preferences.
+- [Working memory](references/docs-memory-working-memory.md) - Learn how to configure working memory in Mastra to store persistent user data, preferences.
 - [RAG (Retrieval-Augmented Generation) in Mastra](references/docs-rag-overview.md) - Overview of Retrieval-Augmented Generation (RAG) in Mastra, detailing its capabilities for enhancing LLM outputs with relevant context.
-- [Retrieval, Semantic Search, Reranking](references/docs-rag-retrieval.md) - Guide on retrieval processes in Mastra's RAG systems, including semantic search, filtering, and re-ranking.
-- [Storing Embeddings in A Vector Database](references/docs-rag-vector-databases.md) - Guide on vector storage options in Mastra, including embedded and dedicated vector databases for similarity search.
+- [Retrieval, semantic search, reranking](references/docs-rag-retrieval.md) - Guide on retrieval processes in Mastra's RAG systems, including semantic search, filtering, and re-ranking.
+- [Storing embeddings in a vector database](references/docs-rag-vector-databases.md) - Guide on vector storage options in Mastra, including embedded and dedicated vector databases for similarity search.
 
 ### Reference
 
-- [Reference: Memory Class](references/reference-memory-memory-class.md) - Documentation for the `Memory` class in Mastra, which provides a robust system for managing conversation history and thread-based message storage.
-- [Reference: Message History Processor](references/reference-processors-message-history-processor.md) - Documentation for the MessageHistory processor in Mastra, which handles retrieval and persistence of conversation history.
-- [Reference: Semantic Recall Processor](references/reference-processors-semantic-recall-processor.md) - Documentation for the SemanticRecall processor in Mastra, which enables semantic search over conversation history using vector embeddings.
-- [Reference: Working Memory Processor](references/reference-processors-working-memory-processor.md) - Documentation for the WorkingMemory processor in Mastra, which injects persistent user/context data as system instructions.
-- [Reference: Metadata Filters](references/reference-rag-metadata-filters.md) - Documentation for metadata filtering capabilities in Mastra, which allow for precise querying of vector search results across different vector stores.
-- [Reference: Composite Storage](references/reference-storage-composite.md) - Documentation for combining multiple storage backends in Mastra.
-- [Reference: DynamoDB Storage](references/reference-storage-dynamodb.md) - Documentation for the DynamoDB storage implementation in Mastra, using a single-table design with ElectroDB.
-- [Reference: PostgreSQL Storage](references/reference-storage-postgresql.md) - Documentation for the PostgreSQL storage implementation in Mastra.
+- [Reference: Memory class](references/reference-memory-memory-class.md) - Documentation for the `Memory` class in Mastra, which provides a robust system for managing conversation history and thread-based message storage.
+- [Reference: MessageHistory](references/reference-processors-message-history-processor.md) - Documentation for the MessageHistory processor in Mastra, which handles retrieval and persistence of conversation history.
+- [Reference: SemanticRecall](references/reference-processors-semantic-recall-processor.md) - Documentation for the SemanticRecall processor in Mastra, which enables semantic search over conversation history using vector embeddings.
+- [Reference: WorkingMemory](references/reference-processors-working-memory-processor.md) - Documentation for the WorkingMemory processor in Mastra, which injects persistent user/context data as system instructions.
+- [Reference: Metadata filters](references/reference-rag-metadata-filters.md) - Documentation for metadata filtering capabilities in Mastra, which allow for precise querying of vector search results across different vector stores.
+- [Reference: Composite storage](references/reference-storage-composite.md) - Documentation for combining multiple storage backends in Mastra.
+- [Reference: DynamoDB storage](references/reference-storage-dynamodb.md) - Documentation for the DynamoDB storage implementation in Mastra, using a single-table design with ElectroDB.
+- [Reference: PostgreSQL storage](references/reference-storage-postgresql.md) - Documentation for the PostgreSQL storage implementation in Mastra.
 - [Reference: createVectorQueryTool()](references/reference-tools-vector-query-tool.md) - Documentation for the Vector Query Tool in Mastra, which facilitates semantic search over vector stores with filtering and reranking capabilities.
-- [Reference: PG Vector Store](references/reference-vectors-pg.md) - Documentation for the PgVector class in Mastra, which provides vector search using PostgreSQL with pgvector extension.
+- [Reference: PG vector store](references/reference-vectors-pg.md) - Documentation for the PgVector class in Mastra, which provides vector search using PostgreSQL with pgvector extension.
 
 
 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.8.0-alpha.0",
+  "version": "1.8.0",
   "package": "@mastra/pg",
   "exports": {},
   "modules": {}

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

@@ -1,10 +1,10 @@
-# Semantic Recall
+# Semantic recall
 
 If you ask your friend what they did last weekend, they will search in their memory for events associated with "last weekend" and then tell you what they did. That's sort of like how semantic recall works in Mastra.
 
 > **Watch 📹:** What semantic recall is, how it works, and how to configure it in Mastra → [YouTube (5 minutes)](https://youtu.be/UVZtK8cK8xQ)
 
-## How Semantic Recall Works
+## How semantic recall works
 
 Semantic recall is RAG-based search that helps agents maintain context across longer interactions when messages are no longer within [recent message history](https://mastra.ai/docs/memory/message-history).
 
@@ -16,7 +16,7 @@ When it's enabled, new messages are used to query a vector DB for semantically s
 
 After getting a response from the LLM, all new messages (user, assistant, and tool calls/results) are inserted into the vector DB to be recalled in later interactions.
 
-## Quick Start
+## Quick start
 
 Semantic recall is enabled by default, so if you give your agent memory it will be included:
 
@@ -33,7 +33,7 @@ const agent = new Agent({
 })
 ```
 
-## Using the recall() Method
+## Using the `recall()` method
 
 While `listMessages` retrieves messages by thread ID with basic pagination, [`recall()`](https://mastra.ai/reference/memory/recall) adds support for **semantic search**. When you need to find messages by meaning rather than recency, use `recall()` with a `vectorSearchString`:
 
@@ -182,7 +182,7 @@ const agent = new Agent({
 })
 ```
 
-### Using FastEmbed (Local)
+### Using FastEmbed (local)
 
 To use FastEmbed (a local embedding model), install `@mastra/fastembed`:
 
@@ -224,7 +224,7 @@ const agent = new Agent({
 })
 ```
 
-## PostgreSQL Index Optimization
+## 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.
 
@@ -283,6 +283,6 @@ You might want to disable semantic recall in scenarios like:
 - 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.
 
-## Viewing Recalled Messages
+## Viewing recalled messages
 
 When tracing is enabled, any messages retrieved via semantic recall will appear in the agent's trace output, alongside recent message history (if configured).

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

@@ -13,7 +13,7 @@ Working memory can persist at two different scopes:
 
 **Important:** Switching between scopes means the agent won't see memory from the other scope - thread-scoped memory is completely separate from resource-scoped memory.
 
-## Quick Start
+## Quick start
 
 Here's a minimal example of setting up an agent with working memory:
 
@@ -37,13 +37,13 @@ const agent = new Agent({
 })
 ```
 
-## How it Works
+## How it works
 
 Working memory is a block of Markdown text that the agent is able to update over time to store continuously relevant information:
 
 [YouTube video player](https://www.youtube-nocookie.com/embed/UMy_JHLf1n8)
 
-## Memory Persistence Scopes
+## Memory persistence scopes
 
 Working memory can operate in two different scopes, allowing you to choose how memory persists across conversations:
 
@@ -117,7 +117,7 @@ const memory = new Memory({
 - Temporary or session-specific information
 - Workflows where each thread needs working memory but threads are ephemeral and not related to each other
 
-## Storage Adapter Support
+## Storage adapter support
 
 Resource-scoped working memory requires specific storage adapters that support the `mastra_resources` table:
 
@@ -128,7 +128,7 @@ Resource-scoped working memory requires specific storage adapters that support t
 - **Upstash** (`@mastra/upstash`)
 - **MongoDB** (`@mastra/mongodb`)
 
-## Custom Templates
+## Custom templates
 
 Templates guide the agent on what information to track and update in working memory. While a default template is used if none is provided, you'll typically want to define a custom template tailored to your agent's specific use case to ensure it remembers the most relevant information.
 
@@ -142,7 +142,7 @@ const memory = new Memory({
       template: `
 # User Profile
 
-## Personal Info
+## Personal info
 
 - Name:
 - Location:
@@ -156,7 +156,7 @@ const memory = new Memory({
   - [Deadline 1]: [Date]
   - [Deadline 2]: [Date]
 
-## Session State
+## Session state
 
 - Last Task Discussed:
 - Open Questions:
@@ -168,7 +168,7 @@ const memory = new Memory({
 })
 ```
 
-## Designing Effective Templates
+## Designing effective templates
 
 A well-structured template keeps the information straightforward for the agent to parse and update. Treat the template as a short form that you want the assistant to keep up to date.
 
@@ -206,7 +206,7 @@ const paragraphMemory = new Memory({
 })
 ```
 
-## Structured Working Memory
+## Structured working memory
 
 Working memory can also be defined using a structured schema instead of a Markdown template. This allows you to specify the exact fields and types that should be tracked, using a [Zod](https://zod.dev/) schema. When using a schema, the agent will see and update working memory as a JSON object matching your schema.
 
@@ -265,20 +265,20 @@ Schema-based working memory uses **merge semantics**, meaning the agent only nee
 - **Set a field to `null` to delete it:** This explicitly removes the field from memory
 - **Arrays are replaced entirely:** When an array field is provided, it replaces the existing array (arrays aren't merged element-by-element)
 
-## Choosing Between Template and Schema
+## Choosing between template and schema
 
 - Use a **template** (Markdown) if you want the agent to maintain memory as a free-form text block, such as a user profile or scratchpad. Templates use **replace semantics** — the agent must provide the complete memory content on each update.
 - Use a **schema** if you need structured, type-safe data that can be validated and programmatically accessed as JSON. Schemas use **merge semantics** — the agent only provides fields to update, and existing fields are preserved.
 - Only one mode can be active at a time: setting both `template` and `schema` isn't supported.
 
-## Example: Multi-step Retention
+## Example: Multi-step retention
 
 Below is a simplified view of how the `User Profile` template updates across a short user conversation:
 
 ```nohighlight
 # User Profile
 
-## Personal Info
+## Personal info
 
 - Name:
 - Location:
@@ -303,7 +303,7 @@ The agent can now refer to `Sam` or `Berlin` in later responses without requesti
 
 If your agent isn't properly updating working memory when you expect it to, you can add system instructions on _how_ and _when_ to use this template in your agent's `instructions` setting.
 
-## Setting Initial Working Memory
+## Setting initial working memory
 
 While agents typically update working memory through the `updateWorkingMemory` tool, you can also set initial working memory programmatically when creating or updating threads. This is useful for injecting user data (like their name, preferences, or other info) that you want available to the agent without passing it in every request.
 
@@ -372,7 +372,7 @@ await memory.updateWorkingMemory({
 })
 ```
 
-## Read-Only Working Memory
+## Read-only working memory
 
 In some scenarios, you may want an agent to have access to working memory data without the ability to modify it. This is useful for:
 

package/dist/docs/references/docs-rag-overview.md

@@ -59,11 +59,11 @@ console.log('Similar chunks:', results)
 
 This example shows the essentials: initialize a document, create chunks, generate embeddings, store them, and query for similar content.
 
-## Document Processing
+## Document processing
 
 The basic building block of RAG is document processing. Documents can be chunked using various strategies (recursive, sliding window, etc.) and enriched with metadata. See the [chunking and embedding doc](https://mastra.ai/docs/rag/chunking-and-embedding).
 
-## Vector Storage
+## Vector storage
 
 Mastra supports multiple vector stores for embedding persistence and similarity search, including pgvector, Pinecone, Qdrant, and MongoDB. See the [vector database doc](https://mastra.ai/docs/rag/vector-databases).
 

package/dist/docs/references/docs-rag-retrieval.md

@@ -1,10 +1,10 @@
-# Retrieval in RAG Systems
+# Retrieval in RAG systems
 
 After storing embeddings, you need to retrieve relevant chunks to answer user queries.
 
 Mastra provides flexible retrieval options with support for semantic search, filtering, and re-ranking.
 
-## How Retrieval Works
+## How retrieval works
 
 1. The user's query is converted to an embedding using the same model used for document embeddings
 2. This embedding is compared to stored embeddings using vector similarity
@@ -14,7 +14,7 @@ Mastra provides flexible retrieval options with support for semantic search, fil
 - Re-ranked for better relevance
 - Processed through a knowledge graph
 
-## Basic Retrieval
+## Basic retrieval
 
 The simplest approach is direct semantic search. This method uses vector similarity to find chunks that are semantically similar to the query:
 
@@ -63,7 +63,7 @@ Results include both the text content and a similarity score:
 ]
 ```
 
-## Advanced Retrieval options
+## Advanced retrieval options
 
 ### Metadata Filtering
 

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

@@ -1,8 +1,8 @@
-# Storing Embeddings in A Vector Database
+# Storing embeddings in a vector database
 
 After generating embeddings, you need to store them in a database that supports vector similarity search. Mastra provides a consistent interface for storing and querying embeddings across various vector databases.
 
-## Supported Databases
+## Supported databases
 
 **MongoDB**:
 
@@ -234,7 +234,7 @@ await store.upsert({
 })
 ```
 
-**ElasticSearch**:
+**Elasticsearch**:
 
 ```ts
 import { ElasticSearchVector } from '@mastra/elasticsearch'
@@ -337,7 +337,7 @@ await store.upsert({
 })
 ```
 
-## Using Vector Storage
+## Using vector storage
 
 Once initialized, all vector stores share the same interface for creating indexes, upserting embeddings, and querying.
 
@@ -355,9 +355,9 @@ await store.createIndex({
 
 The dimension size must match the output dimension of your chosen embedding model. Common dimension sizes are:
 
-- OpenAI text-embedding-3-small: 1536 dimensions (or custom, e.g., 256)
-- Cohere embed-multilingual-v3: 1024 dimensions
-- Google gemini-embedding-001: 768 dimensions (or custom)
+- `OpenAI text-embedding-3-small`: 1536 dimensions (or custom, e.g., 256)
+- `Cohere embed-multilingual-v3`: 1024 dimensions
+- `Google gemini-embedding-001`: 768 dimensions (or custom)
 
 > **Warning:** Index dimensions can't be changed after creation. To use a different model, delete and recreate the index with the new dimension size.
 
@@ -490,7 +490,7 @@ Index names must:
 - Example: `My_Index` is not valid (contains uppercase letters)
 - Example: `_myindex` is not valid (begins with underscore)
 
-**ElasticSearch**:
+**Elasticsearch**:
 
 Index names must:
 
@@ -543,7 +543,7 @@ The upsert operation:
 - Creates new vectors if they don't exist
 - Automatically handles batching for large datasets
 
-## Adding Metadata
+## Adding metadata
 
 Vector stores support rich metadata (any JSON-serializable fields) for filtering and organization. Since metadata is stored with no fixed schema, use consistent field naming to avoid unexpected query results.
 
@@ -581,7 +581,7 @@ Key metadata considerations:
 - Only include fields you plan to filter or sort by - extra fields add overhead
 - Add timestamps (e.g., 'createdAt', 'lastUpdated') to track content freshness
 
-## Deleting Vectors
+## Deleting vectors
 
 When building RAG applications, you often need to clean up stale vectors when documents are deleted or updated. Mastra provides the `deleteVectors` method that supports deleting vectors by metadata filters, making it straightforward to remove all embeddings associated with a specific document.
 
@@ -637,7 +637,7 @@ await store.deleteVectors({
 })
 ```
 
-## Best Practices
+## Best practices
 
 - Create indexes before bulk insertions
 - Use batch operations for large insertions (the upsert method handles batching automatically)

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

@@ -1,4 +1,4 @@
-# Memory Class
+# Memory class
 
 The `Memory` class provides a robust system for managing conversation history and thread-based message storage in Mastra. It enables persistent storage of conversations, semantic search capabilities, and efficient message retrieval. You must configure a storage provider for conversation history, and if you enable semantic recall you will also need to provide a vector store and embedder.
 

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

@@ -1,8 +1,8 @@
-# Metadata Filters
+# Metadata filters
 
 Mastra provides a unified metadata filtering syntax across all vector stores, based on MongoDB/Sift query syntax. Each vector store translates these filters into their native format.
 
-## Basic Example
+## Basic example
 
 ```typescript
 import { PgVector } from '@mastra/pg'
@@ -24,7 +24,7 @@ const results = await store.query({
 })
 ```
 
-## Supported Operators
+## Supported operators
 
 ### Basic Comparison
 
@@ -46,7 +46,7 @@ const results = await store.query({
 
 `$contains`Text contains substring{ description: { $contains: "sale" } }Supported by: Upstash, libSQL, PgVector`$regex`Regular expression match{ name: { $regex: "^test" } }Supported by: Qdrant, PgVector, Upstash, MongoDB`$size`Array length check{ tags: { $size: { $gt: 2 } } }Supported by: Astra, libSQL, PgVector, MongoDB`$geo`Geospatial query{ location: { $geo: { type: "radius", ... } } }Supported by: Qdrant`$datetime`Datetime range query{ created: { $datetime: { range: { gt: "2024-01-01" } } } }Supported by: Qdrant`$hasId`Vector ID existence check{ $hasId: \["id1", "id2"] }Supported by: Qdrant`$hasVector`Vector existence check{ $hasVector: true }Supported by: Qdrant
 
-## Common Rules and Restrictions
+## Common rules and restrictions
 
 1. Field names can't:
 
@@ -87,7 +87,7 @@ const results = await store.query({
    - Valid: `{ "$and": [{ "field": { "$gt": 100 } }] }`
    - Invalid: `{ "$and": [{ "$gt": 100 }] }`
 
-## Store-Specific Notes
+## Store-specific notes
 
 ### Astra
 

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

@@ -1,4 +1,4 @@
-# Composite Storage
+# Composite storage
 
 `MastraCompositeStore` can compose storage domains from different providers. Use it when you need different databases for different purposes. For example, use LibSQL for memory and PostgreSQL for workflows.
 

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

@@ -1,4 +1,4 @@
-# DynamoDB Storage
+# DynamoDB storage
 
 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/).
 
@@ -120,7 +120,7 @@ For local development, you can use [DynamoDB Local](https://docs.aws.amazon.com/
 
 **config.ttl** (`object`): TTL (Time To Live) configuration for automatic data expiration. Configure per entity type: thread, message, trace, eval, workflow\_snapshot, resource, score. Each entity config includes: enabled (boolean), attributeName (string, default: 'ttl'), defaultTtlSeconds (number).
 
-## TTL (Time To Live) Configuration
+## TTL (time to live) configuration
 
 DynamoDB TTL allows you to automatically delete items after a specified time period. This is useful for:
 
@@ -216,7 +216,7 @@ aws dynamodb update-time-to-live \
 
 > **Note:** DynamoDB deletes expired items within 48 hours after expiration. Items remain queryable until actually deleted.
 
-## AWS IAM Permissions
+## AWS IAM permissions
 
 The IAM role or user executing the code needs appropriate permissions to interact with the specified DynamoDB table and its indexes. Below is a sample policy. Replace `${YOUR_TABLE_NAME}` with your actual table name and `${YOUR_AWS_REGION}` and `${YOUR_AWS_ACCOUNT_ID}` with appropriate values.
 
@@ -246,7 +246,7 @@ The IAM role or user executing the code needs appropriate permissions to interac
 }
 ```
 
-## Key Considerations
+## Key considerations
 
 Before diving into the architectural details, keep these key points in mind when working with the DynamoDB storage adapter:
 
@@ -255,7 +255,7 @@ Before diving into the architectural details, keep these key points in mind when
 - **Understanding GSIs:** Familiarity with how the GSIs are structured (as per `TABLE_SETUP.md`) is important for understanding data retrieval and potential query patterns.
 - **ElectroDB:** The adapter uses ElectroDB to manage interactions with DynamoDB, providing a layer of abstraction and type safety over raw DynamoDB operations.
 
-## Architectural Approach
+## Architectural approach
 
 This storage adapter utilizes a **single-table design pattern** leveraging [ElectroDB](https://electrodb.dev/), a common and recommended approach for DynamoDB. This differs architecturally from relational database adapters (like `@mastra/pg` or `@mastra/libsql`) that typically use multiple tables, each dedicated to a specific entity (threads, messages, etc.).
 

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

@@ -1,4 +1,4 @@
-# PostgreSQL Storage
+# PostgreSQL storage
 
 The PostgreSQL storage implementation provides a production-ready storage solution using PostgreSQL databases.
 
@@ -71,7 +71,7 @@ const storage = new PostgresStore({
 
 **indexes** (`CreateIndexOptions[]`): Custom indexes to create during initialization.
 
-## Constructor Examples
+## Constructor examples
 
 You can instantiate `PostgresStore` in the following ways:
 
@@ -119,7 +119,7 @@ const store4 = new PostgresStore({
 })
 ```
 
-## Additional Notes
+## Additional notes
 
 ### Schema Management
 
@@ -316,7 +316,7 @@ This pattern ensures only one `PostgresStore` instance is created regardless of
 
 > **Tip:** This singleton pattern is only necessary during local development with HMR. In production builds, modules are only loaded once.
 
-## Usage Example
+## Usage example
 
 ### Adding memory to an agent
 
@@ -387,7 +387,7 @@ for await (const chunk of stream.textStream) {
 }
 ```
 
-## Index Management
+## Index management
 
 PostgreSQL storage provides index management to optimize query performance.
 

package/dist/docs/references/reference-tools-vector-query-tool.md

@@ -2,7 +2,7 @@
 
 The `createVectorQueryTool()` function creates a tool for semantic search over vector stores. It supports filtering, reranking, database-specific configurations, and integrates with various vector store backends.
 
-## Basic Usage
+## Basic usage
 
 ```typescript
 import { createVectorQueryTool } from '@mastra/rag'
@@ -79,7 +79,7 @@ The tool returns an object with:
 
 **sources** (`QueryResult[]`): Array of full retrieval result objects. Each object contains all information needed to reference the original document, chunk, and similarity score.
 
-### QueryResult object structure
+### `QueryResult` object structure
 
 ```typescript
 {
@@ -91,7 +91,7 @@ The tool returns an object with:
 }
 ```
 
-## Default Tool Description
+## Default tool description
 
 The default description focuses on:
 
@@ -99,11 +99,11 @@ The default description focuses on:
 - Answering user questions
 - Retrieving factual content
 
-## Result Handling
+## Result handling
 
 The tool determines the number of results to return based on the user's query, with a default of 10 results. This can be adjusted based on the query requirements.
 
-## Example with Filters
+## Example with filters
 
 ```typescript
 const queryTool = createVectorQueryTool({
@@ -134,7 +134,7 @@ For detailed filter syntax and store-specific capabilities, see the [Metadata Fi
 
 For an example of how agent-driven filtering works, see the [Agent-Driven Metadata Filtering](https://github.com/mastra-ai/mastra/tree/main/examples/basics/rag/filter-rag) example.
 
-## Example with Reranking
+## Example with reranking
 
 ```typescript
 const queryTool = createVectorQueryTool({
@@ -164,7 +164,7 @@ Reranking improves result quality by combining:
 
 The reranker processes the initial vector search results and returns a reordered list optimized for relevance.
 
-## Example with Custom Description
+## Example with custom description
 
 ```typescript
 const queryTool = createVectorQueryTool({
@@ -178,7 +178,7 @@ const queryTool = createVectorQueryTool({
 
 This example shows how to customize the tool description for a specific use case while maintaining its core purpose of information retrieval.
 
-## Database-Specific Configuration Examples
+## Database-specific configuration examples
 
 The `databaseConfig` parameter allows you to leverage unique features and optimizations specific to each vector database. These configurations are automatically applied during query execution.
 
@@ -335,7 +335,7 @@ This approach allows you to:
 - Adjust performance parameters based on load
 - Apply different filtering strategies per request
 
-## Example: Using Request Context
+## Example: Using request context
 
 ```typescript
 const queryTool = createVectorQueryTool({
@@ -374,7 +374,7 @@ For more information on request context, please see:
 - [Agent Request Context](https://mastra.ai/docs/server/request-context)
 - [Request Context](https://mastra.ai/docs/server/request-context)
 
-## Usage Without a Mastra Server
+## Usage without a Mastra server
 
 The tool can be used by itself to retrieve documents matching a query:
 
@@ -401,7 +401,7 @@ const queryResult = await vectorQueryTool.execute({ queryText: 'foo', topK: 1 },
 console.log(queryResult.sources)
 ```
 
-## Dynamic Vector Store for Multi-Tenant Applications
+## Dynamic vector store for multi-tenant applications
 
 For multi-tenant applications where each tenant has isolated data (e.g., separate PostgreSQL schemas), you can pass a resolver function instead of a static vector store instance. The function receives the request context and can return the appropriate vector store for the current tenant:
 
@@ -457,7 +457,7 @@ This pattern is similar to how `Agent.memory` supports dynamic configuration and
 - **Database isolation**: Route to different database instances per tenant
 - **Dynamic configuration**: Adjust vector store settings based on request context
 
-## Tool Details
+## Tool details
 
 The tool is created with:
 

package/dist/docs/references/reference-vectors-pg.md

@@ -1,8 +1,8 @@
-# PG Vector Store
+# PG vector store
 
 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 options
 
 **connectionString** (`string`): PostgreSQL connection URL
 
@@ -26,7 +26,7 @@ The PgVector class provides vector search using [PostgreSQL](https://www.postgre
 
 **pgPoolOptions** (`PoolConfig`): Additional pg pool configuration options
 
-## Constructor Examples
+## Constructor examples
 
 ### Connection String
 
@@ -70,7 +70,7 @@ const vectorStore = new PgVector({
 
 ## Methods
 
-### createIndex()
+### `createIndex()`
 
 **indexName** (`string`): Name of the index to create
 
@@ -84,7 +84,7 @@ const vectorStore = new PgVector({
 
 **metadataIndexes** (`string[]`): Array of metadata field names to create btree indexes on. Improves query performance when filtering by these metadata fields.
 
-#### IndexConfig
+#### `IndexConfig`
 
 **type** (`'flat' | 'hnsw' | 'ivfflat'`): Index type (Default: `ivfflat`)
 
@@ -114,7 +114,7 @@ HNSW indexes require significant shared memory during construction. For 100K vec
 
 Higher M values or efConstruction values will increase memory requirements significantly. Adjust your system's shared memory limits if needed.
 
-### upsert()
+### `upsert()`
 
 **indexName** (`string`): Name of the index to upsert vectors into
 
@@ -124,7 +124,7 @@ Higher M values or efConstruction values will increase memory requirements signi
 
 **ids** (`string[]`): Optional vector IDs (auto-generated if not provided)
 
-### query()
+### `query()`
 
 **indexName** (`string`): Name of the index to query
 
@@ -144,11 +144,11 @@ Higher M values or efConstruction values will increase memory requirements signi
 
 **options.probes** (`number`): IVF search parameter
 
-### listIndexes()
+### `listIndexes()`
 
 Returns an array of index names as strings.
 
-### describeIndex()
+### `describeIndex()`
 
 **indexName** (`string`): Name of the index to describe
 
@@ -169,11 +169,11 @@ interface PGIndexStats {
 }
 ```
 
-### deleteIndex()
+### `deleteIndex()`
 
 **indexName** (`string`): Name of the index to delete
 
-### updateVector()
+### `updateVector()`
 
 Update a single vector by ID or by metadata filter. Either `id` or `filter` must be provided, but not both.
 
@@ -208,7 +208,7 @@ await pgVector.updateVector({
 })
 ```
 
-### deleteVector()
+### `deleteVector()`
 
 **indexName** (`string`): Name of the index containing the vector
 
@@ -220,7 +220,7 @@ Deletes a single vector by ID from the specified index.
 await pgVector.deleteVector({ indexName: 'my_vectors', id: 'vector123' })
 ```
 
-### deleteVectors()
+### `deleteVectors()`
 
 Delete multiple vectors by IDs or by metadata filter. Either `ids` or `filter` must be provided, but not both.
 
@@ -230,11 +230,11 @@ Delete multiple vectors by IDs or by metadata filter. Either `ids` or `filter` m
 
 **filter** (`Record<string, any>`): Metadata filter to identify vectors to delete (mutually exclusive with ids)
 
-### disconnect()
+### `disconnect()`
 
 Closes the database connection pool. Should be called when done using the store.
 
-### buildIndex()
+### `buildIndex()`
 
 **indexName** (`string`): Name of the index to define
 
@@ -268,7 +268,7 @@ await pgVector.buildIndex('my_vectors', 'cosine', {
 })
 ```
 
-## Response Types
+## Response types
 
 Query results are returned in this format:
 
@@ -281,7 +281,7 @@ interface QueryResult {
 }
 ```
 
-## Error Handling
+## Error handling
 
 The store throws typed errors that can be caught:
 
@@ -299,7 +299,7 @@ try {
 }
 ```
 
-## Index Configuration Guide
+## Index configuration guide
 
 ### Performance Optimization
 
@@ -331,14 +331,14 @@ The system automatically detects configuration changes and only rebuilds indexes
 - Changed configuration: Index is dropped and rebuilt
 - This prevents the performance issues from unnecessary index recreations
 
-## Best Practices
+## 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
+## Direct pool access
 
 The `PgVector` class exposes its underlying PostgreSQL connection pool as a public field:
 
@@ -354,7 +354,7 @@ This enables advanced usage such as running direct SQL queries, managing transac
 
 This design supports advanced use cases but requires careful resource management by the user.
 
-## Usage Example
+## Usage example
 
 ### Local embeddings with fastembed
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/pg",
-  "version": "1.8.0-alpha.0",
+  "version": "1.8.0",
   "description": "Postgres provider for Mastra - includes both vector and db storage capabilities",
   "type": "module",
   "main": "dist/index.js",
@@ -33,10 +33,10 @@
     "tsup": "^8.5.1",
     "typescript": "^5.9.3",
     "vitest": "4.0.18",
-    "@internal/lint": "0.0.66",
-    "@internal/types-builder": "0.0.41",
-    "@mastra/core": "1.11.0-alpha.0",
-    "@internal/storage-test-utils": "0.0.62"
+    "@internal/lint": "0.0.67",
+    "@internal/types-builder": "0.0.42",
+    "@internal/storage-test-utils": "0.0.63",
+    "@mastra/core": "1.11.0"
   },
   "peerDependencies": {
     "@mastra/core": ">=1.4.0-0 <2.0.0-0"