@mastra/mcp-docs-server 1.2.15-alpha.1 → 1.2.15-alpha.10

package/.docs/reference/file-based-agents/instructions.md

@@ -2,9 +2,11 @@
 
 # Instructions
 
-An agent's `instructions.md` holds its always-on system prompt: the model reads it on every turn. Use it to define the agent's identity, tone, role, and standing rules.
+An agent's instructions hold its always-on system prompt: the model reads it on every turn. Use them to define the agent's identity, tone, role, and standing rules.
 
-Instructions are always in context, so keep them for stable behavior that applies to every request. Move anything conditional, large, or action-oriented out of `instructions.md` and into [`tools/`](https://mastra.ai/reference/file-based-agents/tools) or [`skills/`](https://mastra.ai/reference/file-based-agents/skills), which the model uses only when relevant.
+Write them in one of two files at the agent root. Use `instructions.md` when the prompt is fixed text. Use `instructions.ts` when the prompt needs code, for example when it's built from shared constants or resolved per request.
+
+Instructions are always in context, so keep them for stable behavior that applies to every request. Move anything conditional, large, or action-oriented into [`tools/`](https://mastra.ai/reference/file-based-agents/tools) or [`skills/`](https://mastra.ai/reference/file-based-agents/skills), which the model uses only when relevant.
 
 ## Quickstart
 
@@ -25,30 +27,53 @@ Effective instructions cover the parts of an agent's behavior that don't change
 
 Move conditional, large, or action-oriented guidance into [`tools/`](https://mastra.ai/reference/file-based-agents/tools) or [`skills/`](https://mastra.ai/reference/file-based-agents/skills), which the model uses only when relevant.
 
-## Dynamic instructions
+## Instructions in TypeScript
+
+Use `instructions.ts` when markdown can't express the prompt. The file default-exports a string, a system message, or a function returning one, and `agentInstructions()` types the export without changing it.
+
+Export a string when the prompt is assembled in code, for example from constants shared with the rest of your app:
+
+```typescript
+import { agentInstructions } from '@mastra/core/agent'
+import { SUPPORTED_UNITS } from '../../constants'
+
+export default agentInstructions(`
+You are a helpful weather assistant.
+Report conditions using one of these units: ${SUPPORTED_UNITS.join(', ')}.
+`)
+```
 
-When the prompt needs to change per request, for example based on the current user or runtime context, set a runtime-defined `instructions` function in [`config.ts`](https://mastra.ai/reference/file-based-agents/config) instead of using `instructions.md`. A function `instructions` wins over `instructions.md`, so the static file is ignored when both are present.
+Export a function when the prompt depends on the request. Mastra calls it on every turn and passes the request context:
 
 ```typescript
-import { agentConfig } from '@mastra/core/agent'
-
-export default agentConfig({
-  model: 'openai/gpt-5.6-sol',
-  instructions: ({ runtimeContext }) => {
-    const tier = runtimeContext.get('tier') ?? 'standard'
-    return `You are a support agent. Treat this as a ${tier}-tier customer.`
-  },
+import { agentInstructions } from '@mastra/core/agent'
+
+export default agentInstructions(({ requestContext }) => {
+  const tier = requestContext.get('tier') ?? 'standard'
+  return `You are a support agent. Treat this as a ${tier}-tier customer.`
 })
 ```
 
+The function can be `async` and receives `mastra` alongside `requestContext`, so it can read from storage or another registered primitive before returning the prompt.
+
+Both files can also live in a [subagent](https://mastra.ai/reference/file-based-agents/subagents) directory, which follows the same rules.
+
 ## Build-time behavior
 
-Mastra reads `instructions.md` and inlines its contents into the generated code when the bundler builds your project. The deployed agent doesn't read the file at runtime, so changes to `instructions.md` take effect only after the next build.
+`instructions.md` and `instructions.ts` reach the deployed agent differently:
+
+- `instructions.md`: Mastra reads the file and inlines its contents into the generated code at build time.
+- `instructions.ts`: The generated code imports the module, so it's bundled like any other TypeScript file and can import from the rest of your project.
+
+Under `mastra dev`, editing either file triggers a rebuild. In a deployed app neither file is read from disk at runtime, so changes take effect after the next build.
 
 ## Precedence with config
 
-Instructions can come from `instructions.md` or from the `instructions` field in [`config.ts`](https://mastra.ai/reference/file-based-agents/config):
+Instructions can come from `instructions.ts`, `instructions.md`, or the `instructions` field in [`config.ts`](https://mastra.ai/reference/file-based-agents/config):
+
+- A runtime-defined (function) `instructions` in `config.ts` wins over both files.
+- Otherwise `instructions.ts` wins over `instructions.md`.
+- `instructions.md` wins over a static `instructions` string in `config.ts`.
+- If none is present, the build fails and names the agent directory.
 
-- A runtime-defined (function) `instructions` in `config.ts` wins over `instructions.md`.
-- Otherwise `instructions.md` wins over a static `instructions` string.
-- If neither is present, the build fails and names the agent directory.
+Defining instructions in more than one place logs a warning that names both sources and which one wins. Keep one source per agent.

package/.docs/reference/index.md

@@ -82,9 +82,9 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [createCodingAgent()](https://mastra.ai/reference/coding-agent/create-coding-agent)
 - [Mastra Class](https://mastra.ai/reference/core/mastra-class)
 - [MastraModelGateway](https://mastra.ai/reference/core/mastra-model-gateway)
+- [.addDynamicWorkflow()](https://mastra.ai/reference/core/addDynamicWorkflow)
+- [.addDynamicWorkflows()](https://mastra.ai/reference/core/addDynamicWorkflows)
 - [.addGateway()](https://mastra.ai/reference/core/addGateway)
-- [.addStoredWorkflow()](https://mastra.ai/reference/core/addStoredWorkflow)
-- [.addStoredWorkflows()](https://mastra.ai/reference/core/addStoredWorkflows)
 - [.getAgent()](https://mastra.ai/reference/core/getAgent)
 - [.getAgentById()](https://mastra.ai/reference/core/getAgentById)
 - [.getDeployer()](https://mastra.ai/reference/core/getDeployer)
@@ -285,6 +285,7 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [libSQL Storage](https://mastra.ai/reference/storage/libsql)
 - [MongoDB Storage](https://mastra.ai/reference/storage/mongodb)
 - [MSSQL Storage](https://mastra.ai/reference/storage/mssql)
+- [OracleDB Storage](https://mastra.ai/reference/storage/oracledb)
 - [PostgreSQL Storage](https://mastra.ai/reference/storage/postgresql)
 - [Redis Storage](https://mastra.ai/reference/storage/redis)
 - [Retention (prune)](https://mastra.ai/reference/storage/retention)
@@ -302,6 +303,7 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [Overview](https://mastra.ai/reference/templates/overview)
 - [askUserTool](https://mastra.ai/reference/tools/ask-user-tool)
 - [Bright Data Tools](https://mastra.ai/reference/tools/brightdata)
+- [createBedrockKBTool()](https://mastra.ai/reference/tools/bedrock-kb-tool)
 - [createCodeMode()](https://mastra.ai/reference/tools/create-code-mode)
 - [createDocumentChunkerTool()](https://mastra.ai/reference/tools/document-chunker-tool)
 - [createGraphRAGTool()](https://mastra.ai/reference/tools/graph-rag-tool)
@@ -326,6 +328,7 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [libSQL Vector Store](https://mastra.ai/reference/vectors/libsql)
 - [MongoDB Vector Store](https://mastra.ai/reference/vectors/mongodb)
 - [OpenSearch Vector Store](https://mastra.ai/reference/vectors/opensearch)
+- [OracleDB Vector Store](https://mastra.ai/reference/vectors/oracledb)
 - [PG Vector Store](https://mastra.ai/reference/vectors/pg)
 - [Pinecone Vector Store](https://mastra.ai/reference/vectors/pinecone)
 - [Qdrant Vector Store](https://mastra.ai/reference/vectors/qdrant)
@@ -365,9 +368,9 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [.speak()](https://mastra.ai/reference/voice/voice.speak)
 - [.updateConfig()](https://mastra.ai/reference/voice/voice.updateConfig)
 - [Overview](https://mastra.ai/reference/workers/overview)
+- [Dynamic Workflow Definition](https://mastra.ai/reference/workflows/dynamic-workflow-definition)
 - [Run Class](https://mastra.ai/reference/workflows/run)
 - [Step Class](https://mastra.ai/reference/workflows/step)
-- [Stored Workflow Definition](https://mastra.ai/reference/workflows/stored-workflow-definition)
 - [Workflow Class](https://mastra.ai/reference/workflows/workflow)
 - [Workflow State Reader](https://mastra.ai/reference/workflows/workflow-state-reader)
 - [.agent()](https://mastra.ai/reference/workflows/workflow-methods/agent)

package/.docs/reference/observability/metrics/automatic-metrics.md

@@ -64,17 +64,19 @@ The detailed breakdown metrics (everything except `total_input` and `total_outpu
 
 ### When cost context is attached
 
-Cost context is attached to token metrics when the embedded pricing registry has a matching entry for the provider and model. Mastra includes the registry and covers common providers and models. If no match is found, token metrics are still emitted but without cost fields.
+Cost context is attached to token metrics when the provider reports a valid cost for every completed model step or when the embedded pricing registry has a matching entry for the provider and model. Mastra sums the per-step provider costs into one query total. If any completed step lacks a valid reported cost, Mastra uses the pricing registry instead of reporting a partial total. If neither source is available, token metrics are still emitted without cost fields.
+
+A caller-supplied `costContext` takes precedence over provider-reported costs and pricing registry estimates. Provider-reported totals use `costMetadata.source: 'provider_reported'`, `costMetadata.scope: 'query_total'`, and `costMetadata.reportedStepCount` to identify the source, scope, and number of completed steps included in the total.
 
 ### What cost fields may be included
 
-| Field           | Description                                                                  |
-| --------------- | ---------------------------------------------------------------------------- |
-| `provider`      | Provider name (e.g. `openai`, `anthropic`)                                   |
-| `model`         | Model identifier (e.g. `gpt-4o`, `claude-sonnet-4-20250514`)                 |
-| `estimatedCost` | Estimated cost for this metric, calculated from token count and pricing tier |
-| `costUnit`      | Currency unit (e.g. `USD`)                                                   |
-| `costMetadata`  | Additional pricing context (tier information, error details)                 |
+| Field           | Description                                                                                                        |
+| --------------- | ------------------------------------------------------------------------------------------------------------------ |
+| `provider`      | Provider name (e.g. `openai`, `anthropic`)                                                                         |
+| `model`         | Model identifier (e.g. `gpt-4o`, `claude-sonnet-4-20250514`)                                                       |
+| `estimatedCost` | Estimated cost from token count and pricing tier, or a total reported by the provider                              |
+| `costUnit`      | Currency unit (e.g. `USD`)                                                                                         |
+| `costMetadata`  | Additional pricing context, including tier information, error details, and provider-reported cost source and scope |
 
 ## Correlation with traces
 

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

@@ -2,7 +2,7 @@
 
 # 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.
+Mastra provides a unified metadata filtering syntax across all vector stores, based on MongoDB/Sift query syntax. Each vector store translates these filters into its native query format. For example, PgVector uses PostgreSQL JSONB predicates, while OracleDB stores metadata as Oracle JSON and compiles filters to `JSON_VALUE`, `JSON_EXISTS`, `REGEXP_LIKE`, and `LIKE` predicates with bound values.
 
 ## Basic example
 
@@ -34,11 +34,11 @@ const results = await store.query({
 
 ### Array Operators
 
-`$in`Matches any value in array{ category: { $in: \["A", "B"] } }Supported by: All except Couchbase`$nin`Matches none of the values{ status: { $nin: \["deleted", "archived"] } }Supported by: All except Couchbase`$all`Matches arrays containing all elements{ tags: { $all: \["urgent", "high"] } }Supported by: Astra, Pinecone, Upstash, MongoDB`$elemMatch`Matches array elements meeting criteria{ scores: { $elemMatch: { $gt: 80 } } }Supported by: libSQL, PgVector, MongoDB
+`$in`Matches any value in array{ category: { $in: \["A", "B"] } }Supported by: All except Couchbase`$nin`Matches none of the values{ status: { $nin: \["deleted", "archived"] } }Supported by: All except Couchbase`$all`Matches arrays containing all elements{ tags: { $all: \["urgent", "high"] } }Supported by: Astra, Pinecone, Upstash, MongoDB, OracleDB`$elemMatch`Matches array elements meeting criteria{ scores: { $elemMatch: { $gt: 80 } } }Supported by: libSQL, PgVector, MongoDB, OracleDB
 
 ### Logical Operators
 
-`$and`Logical AND{ $and: \[{ price: { $gt: 100 } }, { stock: { $gt: 0 } }] }Supported by: All except Vectorize, Couchbase`$or`Logical OR{ $or: \[{ status: "active" }, { priority: "high" }] }Supported by: All except Vectorize, Couchbase`$not`Logical NOT{ price: { $not: { $lt: 100 } } }Supported by: Astra, Qdrant, Upstash, PgVector, libSQL, MongoDB`$nor`Logical NOR{ $nor: \[{ status: "deleted" }, { archived: true }] }Supported by: Qdrant, Upstash, PgVector, libSQL, MongoDB
+`$and`Logical AND{ $and: \[{ price: { $gt: 100 } }, { stock: { $gt: 0 } }] }Supported by: All except Vectorize, Couchbase`$or`Logical OR{ $or: \[{ status: "active" }, { priority: "high" }] }Supported by: All except Vectorize, Couchbase`$not`Logical NOT{ price: { $not: { $lt: 100 } } }Supported by: Astra, Qdrant, Upstash, PgVector, libSQL, MongoDB, OracleDB`$nor`Logical NOR{ $nor: \[{ status: "deleted" }, { archived: true }] }Supported by: Qdrant, Upstash, PgVector, libSQL, MongoDB, OracleDB
 
 ### Element Operators
 
@@ -46,7 +46,7 @@ const results = await store.query({
 
 ### Custom Operators
 
-`$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
+`$contains`Text contains substring{ description: { $contains: "sale" } }Supported by: Upstash, libSQL, PgVector, OracleDB`$regex`Regular expression match{ name: { $regex: "^test" } }Supported by: Qdrant, PgVector, Upstash, MongoDB, OracleDB`$size`Array length check{ tags: { $size: 3 } }Supported by: Astra, libSQL, PgVector, MongoDB, OracleDB`$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
 
@@ -124,6 +124,14 @@ const results = await store.query({
 - Empty arrays in conditions are handled gracefully
 - Metadata is stored in a JSONB column for efficient querying
 
+### OracleDB
+
+- Metadata is stored as Oracle JSON alongside each `VECTOR` row
+- Scalar comparisons use `JSON_VALUE`, while array, existence, and element-match checks use `JSON_EXISTS`
+- `$regex` uses Oracle `REGEXP_LIKE`; string `$contains` uses case-insensitive `LIKE`
+- Nested fields are supported with dot notation and are converted to quoted Oracle JSON paths
+- User-provided metadata values are bound as parameters instead of interpolated into SQL
+
 ### PgVector
 
 - Full support for PostgreSQL's native JSON querying capabilities
@@ -211,6 +219,7 @@ const results = await store.query({
 - [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)
 - [PgStore](https://mastra.ai/reference/vectors/pg)
 - [Pinecone](https://mastra.ai/reference/vectors/pinecone)
 - [Qdrant](https://mastra.ai/reference/vectors/qdrant)

package/.docs/reference/server/register-api-route.md

@@ -22,6 +22,8 @@ registerApiRoute("/items/:itemId", { ... })
 
 Custom route paths can't start with the server's configured `apiPrefix` (default: `/api`), as that prefix is reserved for built-in Mastra routes. If you set a custom `apiPrefix`, only that prefix is reserved. For example, with `apiPrefix: '/mastra/api'`, paths like `/api/my-endpoint` are allowed.
 
+> **Warning:** The default auth configuration protects `/api/*` and treats `/api`, `/api/auth/*` as public. When you change `apiPrefix`, those defaults no longer match and built-in routes fall outside the protected pattern. Update `server.auth.protected` and `server.auth.public` to reference the new prefix, and update any client code (including `MastraClient` `apiPrefix`) that hits `/api/*`.
+
 ### options
 
 **method** (`'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'ALL'`): HTTP method for the route

package/.docs/reference/server/routes.md

@@ -171,30 +171,44 @@ The route returns:
 
 ## Workflows
 
-| Method | Path                                      | Description                     |
-| ------ | ----------------------------------------- | ------------------------------- |
-| `GET`  | `/api/workflows`                          | List all workflows              |
-| `GET`  | `/api/workflows/:workflowId`              | Get workflow by ID              |
-| `POST` | `/api/workflows/:workflowId/create-run`   | Create a new workflow run       |
-| `POST` | `/api/workflows/:workflowId/start-async`  | Start workflow and await result |
-| `POST` | `/api/workflows/:workflowId/stream`       | Stream workflow execution       |
-| `POST` | `/api/workflows/:workflowId/resume`       | Resume suspended workflow       |
-| `POST` | `/api/workflows/:workflowId/resume-async` | Resume asynchronously           |
-| `GET`  | `/api/workflows/:workflowId/runs`         | List workflow runs              |
-| `GET`  | `/api/workflows/:workflowId/runs/:runId`  | Get specific run                |
-
-### Stored workflows
-
-Stored workflow definitions (beta) are workflows expressed as JSON, persisted through the `workflowDefinitions` storage domain, and live-registered on the running instance. See [Stored workflows](https://mastra.ai/docs/workflows/stored-workflows).
-
-| Method   | Path                                      | Description                                                                    |
-| -------- | ----------------------------------------- | ------------------------------------------------------------------------------ |
-| `GET`    | `/api/stored/workflows`                   | List stored workflow definitions, filterable by `status` and `authorId`        |
-| `GET`    | `/api/stored/workflows/:storedWorkflowId` | Get a stored workflow definition by ID                                         |
-| `POST`   | `/api/stored/workflows`                   | Upsert a definition (plus optional helper `dependencies`) and live-register it |
-| `DELETE` | `/api/stored/workflows/:storedWorkflowId` | Delete a stored definition and unregister the live workflow                    |
-
-On authenticated servers, the read routes require the `stored-workflows:read` permission and the write routes require `stored-workflows:write`. Registered stored workflows are executed through the ordinary `/api/workflows/:workflowId` routes above.
+| Method | Path                                      | Description                                           |
+| ------ | ----------------------------------------- | ----------------------------------------------------- |
+| `GET`  | `/api/workflows`                          | List all workflows                                    |
+| `GET`  | `/api/workflows/run-counts`               | Get per-workflow counts of running and suspended runs |
+| `GET`  | `/api/workflows/:workflowId`              | Get workflow by ID                                    |
+| `POST` | `/api/workflows/:workflowId/create-run`   | Create a new workflow run                             |
+| `POST` | `/api/workflows/:workflowId/start-async`  | Start workflow and await result                       |
+| `POST` | `/api/workflows/:workflowId/stream`       | Stream workflow execution                             |
+| `POST` | `/api/workflows/:workflowId/resume`       | Resume suspended workflow                             |
+| `POST` | `/api/workflows/:workflowId/resume-async` | Resume asynchronously                                 |
+| `GET`  | `/api/workflows/:workflowId/runs`         | List workflow runs                                    |
+| `GET`  | `/api/workflows/:workflowId/runs/:runId`  | Get specific run                                      |
+
+### Run counts response
+
+The `/api/workflows/run-counts` endpoint returns counts of `running` and [`suspended`](https://mastra.ai/docs/workflows/suspend-and-resume) runs for every registered workflow. The record is keyed by the workflow's registry key from the Mastra config, and the server may cache the response for a few seconds:
+
+```typescript
+{
+  [workflowRegistryKey: string]: {
+    running: number;
+    suspended: number;
+  };
+}
+```
+
+### Dynamic workflows
+
+Dynamic workflow definitions (beta) are workflows expressed as JSON, persisted through the `workflowDefinitions` storage domain, and live-registered on the running instance. See [Dynamic workflows](https://mastra.ai/docs/workflows/dynamic-workflows).
+
+| Method   | Path                                       | Description                                                                    |
+| -------- | ------------------------------------------ | ------------------------------------------------------------------------------ |
+| `GET`    | `/api/stored/workflows`                    | List dynamic workflow definitions, filterable by `status` and `authorId`       |
+| `GET`    | `/api/stored/workflows/:dynamicWorkflowId` | Get a dynamic workflow definition by ID                                        |
+| `POST`   | `/api/stored/workflows`                    | Upsert a definition (plus optional helper `dependencies`) and live-register it |
+| `DELETE` | `/api/stored/workflows/:dynamicWorkflowId` | Delete a dynamic workflow definition and unregister the live workflow          |
+
+On authenticated servers, the read routes require the `stored-workflows:read` permission and the write routes require `stored-workflows:write`. Registered dynamic workflows are executed through the ordinary `/api/workflows/:workflowId` routes above.
 
 ### Create run request body
 

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

@@ -251,6 +251,64 @@ const memoryStore = await storage.getStore('memory')
 const thread = await memoryStore?.getThreadById({ threadId: '...' })
 ```
 
+## Closing connections
+
+`close()` releases the connections of the stores a composite was built from: the `default` and `editor` stores, plus any domain that owns its own client. Each store is closed once, even when it backs several domains. When passed to the Mastra class, `close()` is called by `shutdown()`:
+
+```typescript
+import { MastraCompositeStore } from '@mastra/core/storage'
+import { PostgresStore } from '@mastra/pg'
+import { Mastra } from '@mastra/core'
+
+const pgStore = new PostgresStore({
+  id: 'pg-storage',
+  connectionString: process.env.DATABASE_URL,
+})
+
+export const mastra = new Mastra({
+  storage: new MastraCompositeStore({ id: 'composite', default: pgStore }),
+})
+
+process.on('SIGTERM', async () => {
+  // Releases the Postgres pool, so the process can exit
+  await mastra.shutdown()
+})
+```
+
+A store you construct only to supply a domain isn't reachable through the composite. Keep a reference to it and close it yourself:
+
+```typescript
+import { MastraCompositeStore } from '@mastra/core/storage'
+import { ClickhouseStore } from '@mastra/clickhouse'
+import { PostgresStore } from '@mastra/pg'
+import { Mastra } from '@mastra/core'
+
+const pgStore = new PostgresStore({
+  id: 'pg-storage',
+  connectionString: process.env.DATABASE_URL,
+})
+
+const clickhouseStore = new ClickhouseStore({
+  id: 'clickhouse-storage',
+  url: process.env.CLICKHOUSE_URL,
+  username: process.env.CLICKHOUSE_USERNAME,
+  password: process.env.CLICKHOUSE_PASSWORD,
+})
+
+export const mastra = new Mastra({
+  storage: new MastraCompositeStore({
+    id: 'composite',
+    default: pgStore,
+    domains: { observability: clickhouseStore.stores?.observability },
+  }),
+})
+
+process.on('SIGTERM', async () => {
+  await mastra.shutdown()
+  await clickhouseStore.close()
+})
+```
+
 ## Use cases
 
 ### Separate databases for different workloads

package/.docs/reference/storage/oracledb.md

@@ -0,0 +1,239 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# OracleDB storage
+
+The OracleDB storage provider stores Mastra application state in Oracle Database. It implements Mastra's composite storage interface, so one `OracleStore` instance can back memory, workflow snapshots, observability, scores, scorer definitions, MCP client metadata, and agent registry data.
+
+## Installation
+
+**npm**:
+
+```bash
+npm install @mastra/oracledb@latest
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/oracledb@latest
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/oracledb@latest
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/oracledb@latest
+```
+
+## Usage
+
+```ts
+import { OracleStore } from '@mastra/oracledb'
+
+const storage = new OracleStore({
+  id: 'oracle-storage',
+  user: process.env.ORACLE_DATABASE_USER,
+  password: process.env.ORACLE_DATABASE_PASSWORD,
+  connectString: process.env.ORACLE_DATABASE_CONNECT_STRING,
+})
+```
+
+Use it with Mastra:
+
+```ts
+import { Mastra } from '@mastra/core/mastra'
+
+export const mastra = new Mastra({
+  storage,
+})
+```
+
+## Parameters
+
+**id** (`string`): Unique identifier for this storage instance.
+
+**user** (`string`): Oracle Database user. Required unless using pool or externalAuth.
+
+**password** (`string`): Password for the Oracle Database user. Required unless using pool or externalAuth.
+
+**connectString** (`string`): Oracle connect string, service name, TNS alias, or Autonomous Database connect descriptor. Required unless using pool.
+
+**pool** (`oracledb.Pool`): Existing Oracle connection pool. When provided, Mastra uses the pool but doesn't close it when store.close() is called.
+
+**poolManager** (`OraclePoolManager`): Shared Oracle pool manager. Use this to share one Oracle pool between OracleStore and OracleVector.
+
+**schemaName** (`string`): Oracle schema name used to qualify storage tables.
+
+**poolMin** (`number`): Minimum number of Oracle pool connections. (Default: `0`)
+
+**poolMax** (`number`): Maximum number of Oracle pool connections. (Default: `4`)
+
+**poolIncrement** (`number`): Number of connections to add when the pool grows. (Default: `1`)
+
+**configDir** (`string`): Directory containing Oracle Network configuration files such as tnsnames.ora.
+
+**walletLocation** (`string`): Oracle wallet directory for mTLS connections such as Autonomous Database.
+
+**walletPassword** (`string`): Password for the Oracle wallet, when required by the wallet configuration.
+
+**externalAuth** (`boolean`): Use Oracle external authentication instead of username/password authentication.
+
+**disableInit** (`boolean`): When true, automatic schema initialization is disabled. Use this when schema changes are applied separately before the app starts. (Default: `false`)
+
+**messageBatchSize** (`number`): Number of messages sent per Oracle executeMany call when saving messages. The operation still commits once at the transaction boundary. (Default: `200`)
+
+**skipDefaultIndexes** (`boolean`): When true, default storage indexes aren't created during initialization.
+
+**indexes** (`OracleCreateIndexOptions[]`): Custom Oracle index definitions to create during initialization. Indexes are routed to the storage domain that owns the target table.
+
+**migrationTableName** (`string`): Oracle table used to track storage schema migrations. (Default: `'MASTRA_ORACLE_MIGRATIONS'`)
+
+**vectorRegistryTableName** (`string`): OracleVector registry table used to discover semantic-recall vector tables when threads or messages are deleted. Set this to match OracleVector's registryTableName when that option is customized.
+
+## Connection examples
+
+The basic username/password constructor is shown above. For Autonomous Database, add wallet options to the same constructor:
+
+```ts
+const storage = new OracleStore({
+  id: 'oracle-storage',
+  user: process.env.ORACLE_DATABASE_USER,
+  password: process.env.ORACLE_DATABASE_PASSWORD,
+  connectString: process.env.ORACLE_DATABASE_CONNECT_STRING,
+  walletLocation: process.env.ORACLE_DATABASE_WALLET_DIR,
+  walletPassword: process.env.ORACLE_DATABASE_WALLET_PASSWORD,
+  configDir: process.env.ORACLE_DATABASE_CONFIG_DIR,
+})
+```
+
+For external authentication, set `externalAuth: true` and omit `password`. To reuse an existing `oracledb.Pool`, pass it as `pool`. Mastra uses it but doesn't close it.
+
+`OracleStore` backs memory, workflow snapshots, observability, scores, scorer definitions, MCP client metadata, and agent registry data. When using the store outside a `Mastra` instance, call `await storage.init()` and access a domain with `await storage.getStore('memory')`.
+
+## Initialization
+
+When you pass `OracleStore` to `Mastra`, `init()` is called automatically before storage operations run. If you use `OracleStore` directly, call `init()` before reading or writing:
+
+```ts
+await storage.init()
+```
+
+> **Warning:** If initialization is disabled or skipped, storage operations require the Oracle tables and indexes to already exist.
+
+`OracleStore.init()` runs repeatable migrations and records the result in the migration ledger table. The default ledger table is `MASTRA_ORACLE_MIGRATIONS`.
+
+```ts
+await storage.migrate()
+const history = await storage.listMigrations()
+```
+
+Repeatable migrations are idempotent. They reconcile the tables and indexes owned by each storage domain on startup, which lets new domain indexes or compatible schema additions apply without changing application code.
+
+Initialization also creates the provider's default indexes for common Mastra query paths. Use `skipDefaultIndexes` when indexes are managed separately, or pass `indexes` for custom Oracle indexes. Custom definitions support Oracle options such as `bitmap`, `online`, `invisible`, `parallel`, `compress`, `noLogging`, and `reverse`, as well as function-based expressions like `JSON_VALUE(...)`.
+
+Custom indexes are useful when your app repeatedly filters on JSON metadata or when database administrators (DBAs) want to test an index before the optimizer uses it:
+
+```ts
+const storage = new OracleStore({
+  id: 'oracle-storage',
+  user,
+  password,
+  connectString,
+  indexes: [
+    {
+      name: 'idx_messages_status',
+      table: 'mastra_messages',
+      columns: [
+        "JSON_VALUE(metadata, '$.status' RETURNING VARCHAR2(32) NULL ON ERROR)",
+        'thread_id',
+      ],
+      online: true,
+      invisible: true,
+    },
+  ],
+})
+```
+
+Use `invisible` for staged rollout, then remove it after validating query plans. Use `skipDefaultIndexes: true` only when a DBA-managed indexing strategy replaces the defaults.
+
+Use `disableInit: true` when schema changes are applied by a separate deployment step or by a database administrator.
+
+## Schema export
+
+Use `exportSchemas()` to generate Oracle DDL without connecting to a database. This is useful when schema changes are reviewed or applied outside application startup.
+
+```ts
+import { exportSchemas } from '@mastra/oracledb'
+
+const ddl = exportSchemas({
+  schemaName: 'MASTRA_APP',
+  domains: [
+    'memory',
+    'workflows',
+    'observability',
+    'scores',
+    'scorerDefinitions',
+    'mcpClients',
+    'agents',
+  ],
+})
+
+console.log(ddl)
+```
+
+`domains` defaults to every supported domain, including `vector`, when omitted.
+
+## Operational notes
+
+Use the same `OraclePoolManager` when `OracleStore` and `OracleVector` should share one Oracle connection lifecycle:
+
+```ts
+import { OracleStore, OracleVector } from '@mastra/oracledb'
+
+const storage = new OracleStore({ id: 'oracle-storage', user, password, connectString })
+const vector = new OracleVector({
+  id: 'oracle-vector',
+  poolManager: storage.getPoolManager(),
+})
+```
+
+`OracleStore` exposes `storage.db` and `await storage.getPool()` for advanced use cases. When using these APIs directly, you're responsible for transaction boundaries and connection lifecycle.
+
+JSON metadata, payloads, and snapshots are stored in native Oracle JSON columns and encoded server-side, so the rows are readable directly with standard Oracle JDBC tools such as DBeaver and SQL Developer.
+
+## Usage example
+
+### Adding OracleDB memory to an agent
+
+```ts
+import { Agent } from '@mastra/core/agent'
+import { Memory } from '@mastra/memory'
+import { OracleStore } from '@mastra/oracledb'
+
+const storage = new OracleStore({
+  id: 'oracle-storage',
+  user: process.env.ORACLE_DATABASE_USER,
+  password: process.env.ORACLE_DATABASE_PASSWORD,
+  connectString: process.env.ORACLE_DATABASE_CONNECT_STRING,
+})
+
+export const oracleAgent = new Agent({
+  id: 'oracle-agent',
+  name: 'Oracle Agent',
+  instructions: 'You are an assistant with persistent OracleDB-backed memory.',
+  model: 'openai/gpt-5.6-sol',
+  memory: new Memory({ storage }),
+})
+```
+
+## Related
+
+- [OracleDB vector store](https://mastra.ai/reference/vectors/oracledb)
+- [Storage overview](https://mastra.ai/reference/storage/overview)
+- [Working memory](https://mastra.ai/docs/memory/working-memory)
+- [Workflow snapshots](https://mastra.ai/docs/workflows/snapshots)

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

@@ -10,15 +10,15 @@ Mastra storage is organized into domains. Each domain owns a set of tables or co
 
 Not every storage adapter implements every domain. Composite storage lets you mix adapters per domain when the adapter packages export the corresponding domain classes.
 
-| Domain                | Description                                                                                                                            |
-| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
-| `memory`              | Conversation persistence: messages, threads, and resources (including working memory).                                                 |
-| `workflows`           | Workflow run snapshots used for suspend and resume.                                                                                    |
-| `workflowDefinitions` | Persisted [stored workflow](https://mastra.ai/docs/workflows/stored-workflows) definitions (beta). Loaded and live-registered on boot. |
-| `scores`              | Evaluation score records from eval runs.                                                                                               |
-| `observability`       | Traces and spans used by observability exporters and Studio.                                                                           |
-| `datasets`            | Dataset records, versioned items, and dataset versions used by experiments.                                                            |
-| `experiments`         | Experiment runs and per-item experiment results.                                                                                       |
+| Domain                | Description                                                                                                                              |
+| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| `memory`              | Conversation persistence: messages, threads, and resources (including working memory).                                                   |
+| `workflows`           | Workflow run snapshots used for suspend and resume.                                                                                      |
+| `workflowDefinitions` | Persisted [dynamic workflow](https://mastra.ai/docs/workflows/dynamic-workflows) definitions (beta). Loaded and live-registered on boot. |
+| `scores`              | Evaluation score records from eval runs.                                                                                                 |
+| `observability`       | Traces and spans used by observability exporters and Studio.                                                                             |
+| `datasets`            | Dataset records, versioned items, and dataset versions used by experiments.                                                              |
+| `experiments`         | Experiment runs and per-item experiment results.                                                                                         |
 
 The schema definitions below cover the built-in database-backed tables documented for `memory`, `workflows`, `scores`, and `observability`. Other domains, and non-database adapters, use implementation-specific storage structures.