@mastra/mcp-docs-server 1.3.7-alpha.1 → 1.3.7-alpha.5

package/.docs/reference/storage/composite.md

@@ -210,6 +210,40 @@ export const mastra = new Mastra({
 
 **domains.experiments** (`ExperimentsStorage`): Storage for experiment runs and per-item experiment results.
 
+**domains.workflowDefinitions** (`WorkflowDefinitionsStorage`): Storage for persisted workflow definitions.
+
+**domains.promptBlocks** (`PromptBlocksStorage`): Storage for stored prompt blocks and their versions.
+
+**domains.scorerDefinitions** (`ScorerDefinitionsStorage`): Storage for stored scorer definitions and their versions.
+
+**domains.mcpClients** (`MCPClientsStorage`): Storage for stored MCP client configurations and their versions.
+
+**domains.mcpServers** (`MCPServersStorage`): Storage for stored MCP server configurations and their versions.
+
+**domains.workspaces** (`WorkspacesStorage`): Storage for stored workspace configurations and their versions.
+
+**domains.skills** (`SkillsStorage`): Storage for stored skill definitions and their versions.
+
+**domains.favorites** (`FavoritesStorage`): Storage for user favorites on stored entities.
+
+**domains.blobs** (`BlobStore`): Content-addressable storage for file contents used by skill versioning.
+
+**domains.backgroundTasks** (`BackgroundTasksStorage`): Storage for background task state.
+
+**domains.schedules** (`SchedulesStorage`): Storage for schedules that the scheduler fires.
+
+**domains.channels** (`ChannelsStorage`): Storage for channel installations and configuration.
+
+**domains.harness** (`HarnessStorage`): Storage for harness sessions.
+
+**domains.toolProviderConnections** (`ToolProviderConnectionsStorage`): Storage for authorized tool provider connections.
+
+**domains.notifications** (`NotificationsStorage`): Storage for notifications and their delivery state.
+
+**domains.threadState** (`ThreadStateStorage`): Storage for per-thread agent state, such as task lists and goals.
+
+**domains.knowledge** (`KnowledgeStorage`): Storage for knowledge nodes and records. Experimental.
+
 ## Initialization
 
 `MastraCompositeStore` initializes each configured domain independently. When passed to the Mastra class, `init()` is called automatically:

package/.docs/reference/storage/overview.md

@@ -30,7 +30,7 @@ The schema definitions below cover the built-in database-backed tables documente
 
 Stores conversation messages and their metadata. Each message belongs to a thread and contains the actual content along with metadata about the sender role and message type.
 
-iduuidv4PRIMARYKEYNOT NULLUnique identifier for the message (format: `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`)thread\_iduuidv4FK → threads.idNOT NULLParent thread referenceresourceIduuidv4CAN BE NULLID of the resource that owns this messagecontenttextNOT NULLJSON of the message content in V2 format. Example: `{ format: 2, parts: [...] }`roletextNOT NULLEnum of `user | assistant`createdAttimestampNOT NULLUsed for thread message ordering
+idtextPRIMARYKEYNOT NULLUnique identifier for the messagethread\_idtextFK → threads.idNOT NULLParent thread referenceresourceIdtextCAN BE NULLID of the resource that owns this messagecontenttextNOT NULLJSON of the message content in V2 format. Example: `{ format: 2, parts: [...] }`roletextNOT NULLEnum of `user | assistant`createdAttimestampNOT NULLUsed for thread message ordering
 
 The message `content` column contains a JSON object conforming to the `MastraMessageContentV2` type, which is designed to align closely with the AI SDK `UIMessage` message shape.
 
@@ -40,7 +40,7 @@ formatintegerNOT NULLMessage format version (currently 2)partsarray (JSON)NOT NU
 
 Groups related messages together and associates them with a resource. Contains metadata about the conversation.
 
-iduuidv4PRIMARYKEYNOT NULLUnique identifier for the thread (format: `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`)resourceIdtextNOT NULLPrimary identifier of the external resource this thread is associated with. Used to group and retrieve related threads.titletextNOT NULLTitle of the conversation threadmetadatatextCustom thread metadata as stringified JSON. Example:
+idtextPRIMARYKEYNOT NULLUnique identifier for the threadresourceIdtextNOT NULLPrimary identifier of the external resource this thread is associated with. Used to group and retrieve related threads.titletextNOT NULLTitle of the conversation threadmetadatajsonbCAN BE NULLCustom thread metadata as JSON. Example:
 
 ```json
 {
@@ -76,7 +76,7 @@ createdAttimestampNOT NULLWhen the resource record was first createdupdatedAttim
 
 When `suspend()` is called on a workflow, its state is saved in the following format. When `resume()` is called, that state is rehydrated.
 
-workflow\_nametextNOT NULLName of the workflowrun\_iduuidv4NOT NULLUnique identifier for the workflow execution. Used to track state across suspend/resume cycles (format: `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`)snapshottextNOT NULLSerialized workflow state as JSON. Example:
+workflow\_nametextNOT NULLName of the workflowrun\_idtextNOT NULLUnique identifier for the workflow execution. Used to track state across suspend/resume cyclessnapshotjsonbNOT NULLWorkflow state as JSON. Example:
 
 ```json
 {

package/.docs/reference/streaming/agents/MastraModelOutput.md

@@ -101,7 +101,7 @@ These properties resolve to final values after the stream completes:
 
 ## Error properties
 
-**error** (`string | Error | { message: string; stack: string; } | undefined`): Error information if the stream encountered an error. Undefined if no errors occurred. Can be a string message, Error object, or serialized error with stack trace.
+**error** (`Error | undefined`): Error object if the stream encountered an error. Undefined if no errors occurred.
 
 ## Methods
 

package/.docs/reference/streaming/agents/streamUntilIdle.md

@@ -66,7 +66,7 @@ Internally, `streamUntilIdle()`:
 
 1. Runs the initial turn via `agent.stream(...)` and pipes its `fullStream` into the outer stream.
 2. Subscribes to background-task completion events for the resolved memory scope.
-3. Queues each terminal event (`background-task-completed`, `background-task-failed`, `background-task-cancelled`) and, when the outer wrapper is idle between turns, re-invokes `agent.stream([], ...)` with a directive listing the completed `toolCallId`s. The continuation turn flows into the same outer stream.
+3. Queues each terminal event (`background-task-completed`, `background-task-failed`, `background-task-cancelled`, `background-task-suspended`) and, when the outer wrapper is idle between turns, re-invokes `agent.stream([], ...)` with a directive listing the completed `toolCallId`s. The continuation turn flows into the same outer stream.
 4. Closes the outer stream once no tasks are running and no completions are queued.
 
 ## Extended usage example

package/.docs/reference/streaming/workflows/timeTravelStream.md

@@ -37,14 +37,16 @@ All parameters are the same as [`Run.timeTravel()`](https://mastra.ai/reference/
 
 **output.result** (`Promise<WorkflowResult<TState, TInput, TOutput, TSteps>>`): A promise that resolves to the final workflow execution result
 
-**output.traceId** (`string`): The trace ID associated with this execution when Tracing is enabled
+**output.runId** (`string`): The ID of the workflow run
+
+**output.workflowId** (`string`): The ID of the workflow
 
 ## Stream events
 
 The stream emits workflow events during execution:
 
 - `workflow-step-start`: Emitted when a step begins execution
-- `workflow-step-finish`: Emitted when a step completes successfully
+- `workflow-step-result`: Emitted when a step produces a result
 - `workflow-step-error`: Emitted when a step encounters an error
 - `workflow-step-suspended`: Emitted when a step suspends
 - Additional events depending on step types (agents, tools, etc.)
@@ -66,8 +68,8 @@ for await (const event of output.fullStream) {
     case 'workflow-step-start':
       console.log(`Starting step: ${event.payload.stepName}`)
       break
-    case 'workflow-step-finish':
-      console.log(`Completed step: ${event.payload.stepName}`)
+    case 'workflow-step-result':
+      console.log(`Completed step: ${event.payload.id}`)
       break
     case 'workflow-step-error':
       console.error(`Error in step: ${event.payload.stepName}`, event.payload.error)

package/.docs/reference/tools/document-chunker-tool.md

@@ -20,9 +20,9 @@ const chunker = createDocumentChunkerTool({
   doc: document,
   params: {
     strategy: 'recursive',
-    size: 512,
+    maxSize: 512,
     overlap: 50,
-    separator: '\n',
+    separators: ['\n'],
   },
 })
 
@@ -39,11 +39,11 @@ const { chunks } = await chunker.execute()
 
 **strategy** (`'recursive'`): The chunking strategy to use (Default: `'recursive'`)
 
-**size** (`number`): Target size of each chunk in tokens/characters (Default: `512`)
+**maxSize** (`number`): Maximum size of each chunk in tokens/characters (Default: `512`)
 
 **overlap** (`number`): Number of overlapping tokens/characters between chunks (Default: `50`)
 
-**separator** (`string`): Character(s) to use as chunk separator (Default: `'\n'`)
+**separators** (`string[]`): Separators to split on, in order of priority (recursive strategy) (Default: `['\n']`)
 
 ## Returns
 
@@ -64,9 +64,9 @@ const chunker = createDocumentChunkerTool({
   doc: technicalDoc,
   params: {
     strategy: 'recursive',
-    size: 1024, // Larger chunks
+    maxSize: 1024, // Larger chunks
     overlap: 100, // More overlap
-    separator: '\n\n', // Split on double newlines
+    separators: ['\n\n'], // Split on double newlines
   },
 })
 
@@ -82,8 +82,8 @@ chunks.forEach((chunk, index) => {
 
 The chunker is created as a Mastra tool with the following properties:
 
-- **Tool ID**: `Document Chunker {strategy} {size}`
-- **Description**: `Chunks document using {strategy} strategy with size {size} and {overlap} overlap`
+- **Tool ID**: `Document Chunker {strategy} {maxSize}`
+- **Description**: `Chunks document using {strategy} strategy with maxSize {maxSize} and {overlap} overlap`
 - **Input Schema**: Empty object (no additional inputs required)
 - **Output Schema**: Object containing the chunks array
 

package/.docs/reference/tools/mcp-client.md

@@ -76,7 +76,7 @@ The client speaks the MCP `2026-07-28` revision. On connect it asks the server w
 
 **enableProgressTracking** (`boolean`): Whether to send a progressToken with tool calls so the server can report progress. See the progress property. (Default: `false`)
 
-**traceContext** (`() => MCPTraceContext | undefined`): Returns the W3C traceparent, optional tracestate and baggage to send as request \_meta on every call to this server. Called when each request is sent so it can read a request-local carrier. Explicit \_meta keys on a tool call take precedence. Servers built with MCPServer expose the received values to tools as requestContext.get("traceContext"); they are observability data and are never used for authorization.
+**traceContext** (`() => MCPTraceContext | undefined`): Returns the W3C traceparent, optional tracestate and baggage to send as request \_meta on every call to this server. Called when each request is sent so it can read a request-local carrier. Without this option, a tool call made by a traced agent or workflow sends the traceparent of its tool call span. When the reply names the server span that handled the call, as MCPServer does, the tool call span links to it. Set this option to send your own trace context, or return undefined to send none. Explicit \_meta keys on a tool call take precedence. Servers built with MCPServer link their request span to the span the traceparent names and expose the received values to tools as requestContext.get("traceContext"); they are observability data and are never used for authorization.
 
 **forwardInstructions** (`boolean`): Whether to append instructions advertised by this MCP server to an agent's system prompt when the agent uses this server's tools. Disabled by default; enable it only for servers you trust, since the instructions are injected into the agent's system prompt. (Default: `false`)
 

package/.docs/reference/tools/mcp-server.md

@@ -856,6 +856,23 @@ The span is named after the method and target (for example `tools/call lookupOrd
 
 A standalone `MCPServer` with no `mastra` instance produces no spans.
 
+### Linking to the caller's trace
+
+A request that carries a W3C `traceparent` keeps its own trace, root span, and trace summary. Its request span links to the caller's span, so you can follow a tool call from the caller's trace to the request it started.
+
+With a tracing bridge, the request span starts under the span that's active when the request arrives. If HTTP instrumentation on the server continues the caller's trace from the `traceparent` header, the request joins the caller's trace instead of starting its own. Its link then points to a span in the same trace.
+
+The server reads `traceparent` and `tracestate` from two places, in this order:
+
+1. The request `_meta`. `MCPClient` sends `traceparent` there for every traced tool call an agent or workflow makes, over HTTP and stdio.
+2. The HTTP headers. OpenTelemetry HTTP instrumentation in a non-Mastra caller sends them there.
+
+The request span also records a valid `traceparent` as the `callerTraceparent` attribute, and the `tracestate` sent with it as `callerTracestate`, capped at 512 characters. Exporters without span link support still carry these attributes. A request without a valid `traceparent` gets no link and no caller attributes. The trace fields are left out of the span input.
+
+The link also works in the other direction. When a `tools/call` request carried a `traceparent`, the reply's `_meta.mastra.traceparent` names the request span, and `MCPClient` adds a link from its tool call span to it. Callers that sent no trace context get nothing back.
+
+Mastra storage saves the links with the spans. The OpenTelemetry exporter, [`OtelBridge`](https://mastra.ai/integrations/observability/opentelemetry), `DatadogBridge`, `DatadogExporter`, and `SentryExporter` send them as span links. `DatadogExporter` and `SentryExporter` give spans their own IDs, so a link between two Mastra spans doesn't resolve in those backends.
+
 ## Notification delivery
 
 Request-scoped notifications (`context.mcp.log()`, `context.mcp.progress()`) stream inside the request that triggered them, so they reach exactly the caller. Notifications that outlive a request (`resources.notifyListChanged()`, `prompts.notifyListChanged()`, `toolActions.notifyListChanged()`, `resources.notifyUpdated()`) are delivered on the `subscriptions/listen` stream each interested client keeps open. `resources.notifyUpdated()` only reaches clients whose stream includes that resource URI. List-changed notifications reach every client listening for that list. Over stdio the connection itself carries the stream.

package/.docs/reference/tools/submit-plan-tool.md

@@ -66,6 +66,8 @@ The model calls this tool with the following parameters:
 
 The `tool-call-suspended` event carries a `suspendPayload`:
 
+**toolId** (`'submit_plan'`): ID of the tool that suspended the run.
+
 **path** (`string`): Path to the plan file the agent wrote.
 
 **title** (`string`): Plan title, filled by the host after reading the file.

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

@@ -21,13 +21,13 @@ const queryTool = createVectorQueryTool({
 
 ## Parameters
 
-> **Note:** **Parameter Requirements:** Most fields can be set at creation as defaults. Some fields can be overridden at runtime via the request context or input. If a required field is missing from both creation and runtime, an error will be thrown. Note that `model`, `id`, and `description` can only be set at creation time.
+> **Note:** **Parameter Requirements:** Most fields can be set at creation as defaults. Some fields can be overridden at runtime via the request context or input. If a required field is missing from both creation and runtime, an error will be thrown. Note that `id` and `description` can only be set at creation time.
 
-**id** (`string`): Custom ID for the tool. By default: 'VectorQuery {vectorStoreName} {indexName} Tool'. (Set at creation only.)
+**id** (`string`): Custom ID for the tool. By default: 'VectorQuery {vectorStoreName} {indexName} Tool', where {vectorStoreName} is 'DirectVectorStore' when a vectorStore instance is passed without a vectorStoreName. (Set at creation only.)
 
 **description** (`string`): Custom description for the tool. By default: 'Access the knowledge base to find information needed to answer user questions' (Set at creation only.)
 
-**model** (`EmbeddingModel`): Embedding model to use for vector search. (Set at creation only.)
+**model** (`EmbeddingModel`): Embedding model to use for vector search. (Can be set at creation or overridden at runtime via the request context.)
 
 **vectorStoreName** (`string`): Name of the vector store to query. (Can be set at creation or overridden at runtime.)
 
@@ -47,7 +47,7 @@ const queryTool = createVectorQueryTool({
 
 **reranker.options.weights** (`WeightConfig`): Weights for scoring components (semantic: 0.4, vector: 0.4, position: 0.2)
 
-**reranker.options.topK** (`number`): Number of top results to return
+**reranker.options.topK** (`number`): Number of top results to return after reranking. Falls back to the query's topK (from the request context, the tool input, or 10) when unset or 0.
 
 **databaseConfig** (`DatabaseConfig`): Database-specific configuration options for optimizing queries. (Can be set at creation or overridden at runtime.)
 

package/.docs/reference/vectors/astra.md

@@ -110,7 +110,7 @@ try {
   })
 } catch (error) {
   if (error instanceof MastraError) {
-    console.log(error.id) // 'MASTRA_VECTOR_ASTRA_QUERY_FAILED'
+    console.log(error.id) // 'MASTRA_VECTOR_ASTRA_QUERY_DB_ERROR'
     console.log(error.domain) // 'MASTRA_VECTOR'
     console.log(error.category) // 'USER' | 'THIRD_PARTY'
     console.log(error.details) // Additional error context

package/.docs/reference/vectors/azure-ai-search.md

@@ -141,6 +141,7 @@ interface QueryResult {
   id: string
   score: number
   metadata: Record<string, any>
+  document?: string // Matched document content
   vector?: number[] // Only included if includeVector is true
 }
 ```

package/.docs/reference/vectors/chroma.md

@@ -86,7 +86,7 @@ Query an index using a `queryVector`. Returns an array of semantically similar r
   score: number;
   document?: string;
   metadata?: Record<string, string | number | boolean>;
-  embedding?: number[]
+  vector?: number[] // Only included if includeVector is true
 }
 ```
 
@@ -147,7 +147,7 @@ Returns:
 interface IndexStats {
   dimension: number
   count: number
-  metric: 'cosine' | 'euclidean' | 'dotproduct'
+  metric?: 'cosine' | 'euclidean' | 'dotproduct'
 }
 ```
 
@@ -247,17 +247,21 @@ interface QueryResult {
 
 ## Error handling
 
-The store throws typed errors that can be caught:
+The store throws `MastraError` instances from `@mastra/core/error`:
 
 ```typescript
+import { MastraError } from '@mastra/core/error'
+
 try {
   await store.query({
     indexName: 'index_name',
     queryVector: queryVector,
   })
 } catch (error) {
-  if (error instanceof VectorStoreError) {
-    console.log(error.code) // 'connection_failed' | 'invalid_dimension' | etc
+  if (error instanceof MastraError) {
+    console.log(error.id) // 'MASTRA_VECTOR_CHROMA_QUERY_FAILED'
+    console.log(error.domain) // 'MASTRA_VECTOR'
+    console.log(error.category) // 'USER' | 'THIRD_PARTY'
     console.log(error.details) // Additional error context
   }
 }

package/.docs/reference/vectors/convex.md

@@ -387,7 +387,6 @@ const results = await vectorStore.query({
 
 | Operator | Description           |
 | -------- | --------------------- |
-| `$eq`    | Equal to              |
 | `$ne`    | Not equal to          |
 | `$gt`    | Greater than          |
 | `$gte`   | Greater than or equal |
@@ -400,10 +399,9 @@ const results = await vectorStore.query({
 
 ## Architecture
 
-`ConvexVector` stores vectors in the `mastra_vectors` table with the following structure:
+`ConvexVector` stores each index in its own table named `mastra_vector_{indexName}`. Each record has the following structure:
 
 - `id`: Unique vector identifier
-- `indexName`: Name of the index
 - `embedding`: The vector data (array of floats)
 - `metadata`: Optional JSON metadata
 

package/.docs/reference/vectors/couchbase.md

@@ -69,8 +69,6 @@ const store = new CouchbaseVector({
 
 **collectionName** (`string`): Name of the Couchbase collection to use
 
-**options** (`CouchbaseClientOptions`): Optional Couchbase client options
-
 ## Methods
 
 ### `createIndex()`
@@ -83,7 +81,7 @@ Creates a new vector index in Couchbase.
 
 **dimension** (`number`): Vector dimension (must match your embedding model)
 
-**metric** (`'cosine' | 'euclidean' | 'dotproduct'`): Distance metric for similarity search (Default: `cosine`)
+**metric** (`'cosine' | 'euclidean' | 'dotproduct'`): Distance metric for similarity search (Default: `dotproduct`)
 
 ### `upsert()`
 
@@ -111,11 +109,9 @@ Searches for similar vectors.
 
 **topK** (`number`): Number of results to return (Default: `10`)
 
-**filter** (`Record<string, any>`): Metadata filters
-
-**includeVector** (`boolean`): Whether to include vector data in results (Default: `false`)
+**filter** (`Record<string, any>`): Not supported. Filters passed here are ignored.
 
-**minScore** (`number`): Minimum similarity score threshold (Default: `0`)
+**includeVector** (`boolean`): Not supported. Setting this to true throws an error. (Default: `false`)
 
 ### `describeIndex()`
 
@@ -135,7 +131,7 @@ interface IndexStats {
 
 ### `deleteIndex()`
 
-Deletes an index and all its data.
+Deletes the Search index. Documents stored in the collection aren't deleted.
 
 **indexName** (`string`): Name of the index to delete
 
@@ -184,7 +180,6 @@ interface QueryResult {
   id: string
   score: number
   metadata: Record<string, any>
-  vector?: number[] // Only included if includeVector is true
 }
 ```
 

package/.docs/reference/vectors/duckdb.md

@@ -216,7 +216,7 @@ DuckDB vector store supports MongoDB-like filter operators:
 | ---------- | ------------------------------------------ |
 | Comparison | `$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte` |
 | Logical    | `$and`, `$or`, `$not`, `$nor`              |
-| Array      | `$in`, `$nin`                              |
+| Array      | `$in`, `$nin`, `$all`                      |
 | Element    | `$exists`                                  |
 | Text       | `$contains`                                |
 

package/.docs/reference/vectors/libsql.md

@@ -121,7 +121,7 @@ Searches for similar vectors with optional metadata filtering.
 
 **includeVector** (`boolean`): Whether to include vector data in results (Default: `false`)
 
-**minScore** (`number`): Minimum similarity score threshold (Default: `0`)
+**minScore** (`number`): Minimum similarity score threshold (cosine similarity ranges from -1 to 1) (Default: `-1`)
 
 ### `describeIndex()`
 

package/.docs/reference/vectors/mongodb.md

@@ -352,6 +352,7 @@ interface QueryResult {
   score: number
   metadata: Record<string, any>
   vector?: number[] // Only included if includeVector is true
+  document?: string // Source text stored with the vector, when available
 }
 ```
 
@@ -429,7 +430,7 @@ const results = await store.query({
 
 **similarity** (`'cosine' | 'dotProduct' | 'euclidean'`): Vector similarity function. Defaults to MongoDB's own default when omitted.
 
-**numDimensions** (`256 | 512 | 1024 | 2048`): Length of the generated embeddings. (Default: `1024`)
+**numDimensions** (`number`): Length of the generated embeddings. Common values are 256, 512, 1024, and 2048. (Default: `1024`)
 
 **quantization** (`'float' | 'scalar' | 'binary' | 'binaryNoRescore'`): Storage format for the generated vectors. (Default: `scalar`)
 

package/.docs/reference/vectors/pg.md

@@ -82,7 +82,9 @@ const vectorStore = new PgVector({
 
 **dimension** (`number`): Vector dimension (must match your embedding model)
 
-**metric** (`'cosine' | 'euclidean' | 'dotproduct'`): Distance metric for similarity search (Default: `cosine`)
+**metric** (`'cosine' | 'euclidean' | 'dotproduct' | 'hamming' | 'jaccard'`): Distance metric for similarity search. 'hamming' and 'jaccard' are only valid with vectorType 'bit', and 'jaccard' requires an HNSW index. (Default: `'cosine' ('hamming' when vectorType is 'bit')`)
+
+**vectorType** (`'vector' | 'halfvec' | 'bit' | 'sparsevec'`): pgvector storage type for the embeddings (Default: `vector`)
 
 **indexConfig** (`IndexConfig`): Index configuration (Default: `{ type: 'ivfflat' }`)
 
@@ -142,13 +144,11 @@ Higher M values or efConstruction values will increase memory requirements subst
 
 **includeVector** (`boolean`): Whether to include the vector in the result (Default: `false`)
 
-**minScore** (`number`): Minimum similarity score threshold (Default: `0`)
-
-**options** (`{ ef?: number; probes?: number }`): Additional options for HNSW and IVF indexes
+**minScore** (`number`): Minimum similarity score threshold (Default: `-1`)
 
-**options.ef** (`number`): HNSW search parameter
+**ef** (`number`): HNSW search parameter. Higher values improve accuracy at the cost of speed.
 
-**options.probes** (`number`): IVF search parameter
+**probes** (`number`): IVFFlat search parameter. Number of lists to visit during search.
 
 ### `listIndexes()`
 
@@ -164,8 +164,9 @@ Returns:
 interface PGIndexStats {
   dimension: number
   count: number
-  metric: 'cosine' | 'euclidean' | 'dotproduct'
+  metric: 'cosine' | 'euclidean' | 'dotproduct' | 'hamming' | 'jaccard'
   type: 'flat' | 'hnsw' | 'ivfflat'
+  vectorType: 'vector' | 'halfvec' | 'bit' | 'sparsevec'
   config: {
     m?: number
     efConstruction?: number
@@ -246,7 +247,7 @@ Closes the database connection pool. Should be called when done using the store.
 
 **indexName** (`string`): Name of the index to define
 
-**metric** (`'cosine' | 'euclidean' | 'dotproduct'`): Distance metric for similarity search (Default: `cosine`)
+**metric** (`'cosine' | 'euclidean' | 'dotproduct' | 'hamming' | 'jaccard'`): Distance metric for similarity search (Default: `cosine`)
 
 **indexConfig** (`IndexConfig`): Configuration for the index type and parameters
 
@@ -291,17 +292,21 @@ interface QueryResult {
 
 ## Error handling
 
-The store throws typed errors that can be caught:
+The store throws `MastraError` instances from `@mastra/core/error`:
 
 ```typescript
+import { MastraError } from '@mastra/core/error'
+
 try {
   await store.query({
     indexName: 'index_name',
     queryVector: queryVector,
   })
 } catch (error) {
-  if (error instanceof VectorStoreError) {
-    console.log(error.code) // 'connection_failed' | 'invalid_dimension' | etc
+  if (error instanceof MastraError) {
+    console.log(error.id) // 'MASTRA_VECTOR_PG_QUERY_FAILED'
+    console.log(error.domain) // 'MASTRA_VECTOR'
+    console.log(error.category) // 'USER' | 'THIRD_PARTY'
     console.log(error.details) // Additional error context
   }
 }

package/.docs/reference/vectors/pinecone.md

@@ -130,24 +130,28 @@ Query results are returned in this format:
 interface QueryResult {
   id: string
   score: number
-  metadata: Record<string, any>
+  metadata?: Record<string, any>
   vector?: number[] // Only included if includeVector is true
 }
 ```
 
 ## Error handling
 
-The store throws typed errors that can be caught:
+The store throws `MastraError` instances from `@mastra/core/error`:
 
 ```typescript
+import { MastraError } from '@mastra/core/error'
+
 try {
   await store.query({
     indexName: 'index_name',
     queryVector: queryVector,
   })
 } catch (error) {
-  if (error instanceof VectorStoreError) {
-    console.log(error.code) // 'connection_failed' | 'invalid_dimension' | etc
+  if (error instanceof MastraError) {
+    console.log(error.id) // 'MASTRA_VECTOR_PINECONE_QUERY_FAILED'
+    console.log(error.domain) // 'STORAGE'
+    console.log(error.category) // 'USER' | 'THIRD_PARTY'
     console.log(error.details) // Additional error context
   }
 }

package/.docs/reference/vectors/qdrant.md

@@ -198,24 +198,28 @@ Query results are returned in this format:
 interface QueryResult {
   id: string
   score: number
-  metadata: Record<string, any>
+  metadata?: Record<string, any>
   vector?: number[] // Only included if includeVector is true
 }
 ```
 
 ## Error handling
 
-The store throws typed errors that can be caught:
+The store throws `MastraError` instances from `@mastra/core/error`:
 
 ```typescript
+import { MastraError } from '@mastra/core/error'
+
 try {
   await store.query({
     indexName: 'index_name',
     queryVector: queryVector,
   })
 } catch (error) {
-  if (error instanceof VectorStoreError) {
-    console.log(error.code) // 'connection_failed' | 'invalid_dimension' | etc
+  if (error instanceof MastraError) {
+    console.log(error.id) // 'MASTRA_VECTOR_QDRANT_QUERY_FAILED'
+    console.log(error.domain) // 'STORAGE'
+    console.log(error.category) // 'USER' | 'THIRD_PARTY'
     console.log(error.details) // Additional error context
   }
 }

package/.docs/reference/vectors/s3vectors.md

@@ -196,7 +196,7 @@ Query results are returned in this format:
 interface QueryResult {
   id: string
   score: number // 1/(1 + distance)
-  metadata: Record<string, any>
+  metadata?: Record<string, any>
   vector?: number[] // Only included if includeVector is true
 }
 ```
@@ -244,17 +244,21 @@ S3 Vectors supports a strict subset of operators and value types. The Mastra fil
 
 ## Error handling
 
-The store throws typed errors that can be caught:
+The store throws `MastraError` instances from `@mastra/core/error`:
 
 ```typescript
+import { MastraError } from '@mastra/core/error'
+
 try {
   await store.query({
     indexName: 'index-name',
     queryVector: queryVector,
   })
 } catch (error) {
-  if (error instanceof VectorStoreError) {
-    console.log(error.code) // 'connection_failed' | 'invalid_dimension' | etc
+  if (error instanceof MastraError) {
+    console.log(error.id) // 'MASTRA_VECTOR_S3VECTORS_QUERY_FAILED'
+    console.log(error.domain) // 'STORAGE'
+    console.log(error.category) // 'USER' | 'THIRD_PARTY'
     console.log(error.details) // Additional error context
   }
 }