@mastra/memory 1.26.1-alpha.3 → 1.26.1-alpha.6

package/CHANGELOG.md

@@ -1,5 +1,47 @@
 # @mastra/memory
 
+## 1.26.1-alpha.6
+
+### Patch Changes
+
+- Updated dependencies [[`2e4624e`](https://github.com/mastra-ai/mastra/commit/2e4624edb6917e61249cb60ee377735e7af7e4a9), [`e6534fa`](https://github.com/mastra-ai/mastra/commit/e6534fab031216f6cb48c4c9907cbfdce9d60bc6), [`7fdcaa6`](https://github.com/mastra-ai/mastra/commit/7fdcaa66105d64290f9b14432a12ec99f39c4d3a), [`5dba2a4`](https://github.com/mastra-ai/mastra/commit/5dba2a41600385751f5aace79878904e1972609d), [`cfd0d9e`](https://github.com/mastra-ai/mastra/commit/cfd0d9ec77ec3c69dd96f79cdb579e03d79f22ce), [`d9d93b2`](https://github.com/mastra-ai/mastra/commit/d9d93b25e4a65ad5fa153fa35be7ed149c8d587f)]:
+  - @mastra/core@1.58.0-alpha.12
+  - @mastra/schema-compat@1.3.6-alpha.3
+
+## 1.26.1-alpha.5
+
+### Patch Changes
+
+- Remove the `image-size` dependency from `@mastra/memory` and measure image dimensions with the already-present `probe-image-size` instead. ([#21120](https://github.com/mastra-ai/mastra/pull/21120))
+
+  Every published version of `image-size` carries unfixed denial-of-service advisories (GHSA-w3rx-r6r6-pgpr / CVE-2025-71330 and GHSA-5p2g-fcmc-qvqq): a malformed image could hang its parse loop and exhaust the heap. The repository is archived, so no fixed release is coming, and the previous pin to `1.2.1` moved between two equally affected releases rather than remediating the flaw. Because image bytes reaching agent memory are untrusted, a crafted 32-byte image was enough to crash the process.
+
+  Dimension detection still covers the formats models accept (PNG, JPEG, WebP, GIF, AVIF, BMP, ICO, PSD, SVG, TIFF). Unrecognized formats now report unknown dimensions, which token counting already handled.
+
+- Updated dependencies [[`b8ce7ec`](https://github.com/mastra-ai/mastra/commit/b8ce7ec96e39343c6c2f36d12d68a9ad816c09f7), [`a3a3624`](https://github.com/mastra-ai/mastra/commit/a3a3624f646b98e409424d8defccbd334da9e8b8), [`6246914`](https://github.com/mastra-ai/mastra/commit/62469146636911f3cbbe0880bd011c6a897a59a7), [`3f73c07`](https://github.com/mastra-ai/mastra/commit/3f73c076727e8c36b4fff7a1b40290fb68957fa8), [`7c1ebb1`](https://github.com/mastra-ai/mastra/commit/7c1ebb15690c4b3f0eabb19077cf8af573311e57), [`32980a3`](https://github.com/mastra-ai/mastra/commit/32980a3e2413d0274ac244d32c37d910edc13f00), [`4bcdfaf`](https://github.com/mastra-ai/mastra/commit/4bcdfaf0eac3199d7cb171b0a19a92c9c341eea4), [`af4636a`](https://github.com/mastra-ai/mastra/commit/af4636a74463275d71c1d13a38f7d2b738f128bf), [`a463cdf`](https://github.com/mastra-ai/mastra/commit/a463cdf1c95c3059e70f0bff27959e8558bb899d), [`0ea6b80`](https://github.com/mastra-ai/mastra/commit/0ea6b8001408ce02b56e8be0536b0fd8cbaf8ad2)]:
+  - @mastra/core@1.58.0-alpha.11
+
+## 1.26.1-alpha.4
+
+### Patch Changes
+
+- Fix Observational Memory undercounting large tool results. Token accounting now serializes tool results in full instead of reusing the Observer-facing representation, which is truncated to 10k tokens. Oversized tool results now push OM past its thresholds and trigger compaction before the provider's context window overflows. ([#21045](https://github.com/mastra-ai/mastra/pull/21045))
+
+- Fixed generated thread titles being clobbered during a turn ([#21041](https://github.com/mastra-ai/mastra/pull/21041))
+
+  `updateThread` required both `title` and `metadata`, so callers that only needed to
+  change metadata (message persistence, working memory, observational memory, channel
+  subscriptions) had to read the thread and pass its title back. When title generation
+  finished between that read and the write, the freshly generated title was overwritten
+  with the stale one.
+
+  `title` and `metadata` are now independently optional: omitting one leaves that column
+  untouched. Callers that only change metadata no longer send a title, and message
+  persistence no longer rewrites a thread row it just read.
+
+- Updated dependencies [[`1c75e32`](https://github.com/mastra-ai/mastra/commit/1c75e32f7fc0b9fb6f548b4407feaec8a1440212), [`c47165c`](https://github.com/mastra-ai/mastra/commit/c47165c983c87594c6952f1fd2fa51a90205034c), [`e08e789`](https://github.com/mastra-ai/mastra/commit/e08e789c1bf4cd2fe46363f7a4728536ceccc9bd), [`35cc901`](https://github.com/mastra-ai/mastra/commit/35cc90102cf834a84827acaf9eee0b6d6d1e2a3b), [`a8b4cf0`](https://github.com/mastra-ai/mastra/commit/a8b4cf02823cffebc4751a53337dfacf097c1ae1), [`f33264f`](https://github.com/mastra-ai/mastra/commit/f33264f517ae603279afd5c4251e2b40f6dd3618), [`689f2c4`](https://github.com/mastra-ai/mastra/commit/689f2c4b6c0835fe455702b01d21daa8abcd9331), [`eeae63e`](https://github.com/mastra-ai/mastra/commit/eeae63e7fbe8e1f237adc69bca6e2ac13c5ca907), [`4c186a0`](https://github.com/mastra-ai/mastra/commit/4c186a017275f45e6ed4c09de0f89550e2d09e8c), [`b0fa077`](https://github.com/mastra-ai/mastra/commit/b0fa077bcbc9b08551846fe372a0d3d15b71ed72)]:
+  - @mastra/core@1.58.0-alpha.8
+
 ## 1.26.1-alpha.3
 
 ### Patch Changes

package/dist/docs/SKILL.md

@@ -3,7 +3,7 @@ name: mastra-memory
 description: Documentation for @mastra/memory. Use when working with @mastra/memory APIs, configuration, or implementation.
 metadata:
   package: "@mastra/memory"
-  version: "1.26.1-alpha.3"
+  version: "1.26.1-alpha.6"
 ---
 
 ## When to use
@@ -50,11 +50,13 @@ Read the individual reference documents for detailed explanations and code examp
 - [Reference: DynamoDB storage](references/reference-storage-dynamodb.md) - Documentation for the DynamoDB storage implementation in Mastra, using a single-table design with ElectroDB.
 - [Reference: libSQL storage](references/reference-storage-libsql.md) - Documentation for the libSQL storage implementation in Mastra.
 - [Reference: MongoDB storage](references/reference-storage-mongodb.md) - Documentation for the MongoDB storage implementation in Mastra.
+- [Reference: OracleDB storage](references/reference-storage-oracledb.md) - Documentation for the Oracle Database storage provider in Mastra.
 - [Reference: PostgreSQL storage](references/reference-storage-postgresql.md) - Documentation for the PostgreSQL storage implementation in Mastra.
 - [Reference: Redis Storage](references/reference-storage-redis.md) - Documentation for the Redis storage implementation in Mastra.
 - [Reference: Upstash storage](references/reference-storage-upstash.md) - Documentation for the Upstash storage implementation in Mastra.
 - [Reference: libSQL vector store](references/reference-vectors-libsql.md) - Documentation for the LibSQLVector class in Mastra, which provides vector search using libSQL with vector extensions.
 - [Reference: MongoDB vector store](references/reference-vectors-mongodb.md) - Documentation for the MongoDBVector class in Mastra, which provides vector search using MongoDB Atlas and Atlas Vector Search.
+- [Reference: OracleDB vector store](references/reference-vectors-oracledb.md) - Documentation for the Oracle Database vector provider in Mastra.
 - [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: Upstash vector store](references/reference-vectors-upstash.md) - Documentation for the UpstashVector class in Mastra, which provides vector search using Upstash Vector.
 

package/dist/docs/assets/SOURCE_MAP.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.26.1-alpha.3",
+  "version": "1.26.1-alpha.6",
   "package": "@mastra/memory",
   "exports": {},
   "modules": {

package/dist/docs/references/docs-agents-agent-approval.md

@@ -90,6 +90,20 @@ for await (const chunk of stream.fullStream) {
 }
 ```
 
+#### Explaining a decline
+
+`declineToolCall()`, `declineToolCallGenerate()`, and `declineNetworkToolCall()` accept an optional `reason`. The reason is returned to the model in place of the tool result, so the model can adjust instead of retrying blindly. It's also stored on the tool call's `approval` metadata, so it's still there when the conversation is recalled.
+
+```typescript
+const declined = await agent.declineToolCall({
+  runId: stream.runId,
+  toolCallId,
+  reason: 'Reading other users PII is not allowed, ask the user for their own email instead',
+})
+```
+
+Without a `reason`, the model receives the default message `Tool call was not approved by the user`.
+
 #### Conditional approval with a function
 
 Instead of a boolean, `requireToolApproval` accepts a function that decides per tool call. It receives the `toolName`, the `args` the model passed, the `requestContext`, and the `workspace`. Return `true` to require approval for that call, or `false` to allow it. This lets you gate approval at runtime, for example, only for tools whose name matches a pattern:

package/dist/docs/references/docs-capabilities-subagents.md

@@ -113,7 +113,7 @@ The `context` object includes:
 
 ### Request context at the delegation boundary
 
-Each delegation receives a request context whose entries are shallowly copied from the parent run, excluding run-scoped identity keys. Setting or deleting entries during the subagent run does not affect the parent's context. Set entries on `context.requestContext` in `onDelegationStart` to pass values to the delegated run:
+Each delegation receives a request context whose entries are shallowly copied from the parent run, excluding run-scoped identity keys. Setting or deleting entries during the subagent run doesn't affect the parent's context. Set entries on `context.requestContext` in `onDelegationStart` to pass values to the delegated run:
 
 ```typescript
 const stream = await parentAgent.stream('Research AI trends', {
@@ -134,6 +134,9 @@ Called after a delegation finishes. Use it to inspect results or provide feedbac
 
 - `context.bail()`: Stop the parent agent's loop immediately
 - Return `{ feedback: '...' }`: Add feedback that gets saved to the parent agent's memory and is visible to subsequent iterations
+- Return `{ resultText: '...' }`: Replace the tool result text the parent model sees for this delegation, within the current run
+
+Use `resultText` when the subagent's own result would mislead the parent immediately. For example, a subagent that stops on a tool-calls step returns empty text, which the parent model reads as a successful but empty delegation. Unlike `feedback`, which only reaches the model on the next turn, `resultText` changes what the parent reasons on right away.
 
 ```typescript
 const stream = await parentAgent.stream('Research AI trends', {

package/dist/docs/references/docs-long-running-agents-goals.md

@@ -4,7 +4,7 @@
 
 **Added in:** `@mastra/core@1.42.0`
 
-> **Beta:** The Goals feature is in beta stage and subject to breaking changes in minor versions until it graduates from its beta status.
+> **Beta:** Breaking changes may occur without a major version bump until the API is stable.
 
 A goal is a durable, thread-scoped objective: a standing instruction the agent keeps working toward across loop iterations until a judge model decides it's satisfied or a run budget is exhausted.
 

package/dist/docs/references/docs-memory-message-history.md

@@ -6,7 +6,7 @@ Message history is the most basic and important form of memory. It gives the LLM
 
 You can also retrieve message history to display past conversations in your UI.
 
-> **Info:** Each message belongs to a thread (the conversation) and a resource (the user or entity it's associated with). See [Threads and resources](#threads-and-resources) for more detail.
+> **Note:** Each message belongs to a thread (the conversation) and a resource (the user or entity it's associated with). See [Threads and resources](#threads-and-resources) for more detail.
 
 > **Warning:** When you use memory with a client application, send **only the new message** from the client instead of the full conversation history.
 >
@@ -113,7 +113,7 @@ await agent.stream('Hello', {
 })
 ```
 
-> **Info:** Threads and messages are created automatically when you call `agent.generate()` or `agent.stream()`, but you can also create them manually with [`createThread()`](https://mastra.ai/reference/memory/createThread) and [`saveMessages()`](https://mastra.ai/reference/memory/memory-class).
+> **Note:** Threads and messages are created automatically when you call `agent.generate()` or `agent.stream()`, but you can also create them manually with [`createThread()`](https://mastra.ai/reference/memory/createThread) and [`saveMessages()`](https://mastra.ai/reference/memory/memory-class).
 
 You can use this history in two ways:
 

package/dist/docs/references/docs-memory-multi-user-threads.md

@@ -156,7 +156,7 @@ const memory = new Memory({
 })
 ```
 
-OM requires a storage adapter that supports it: `@mastra/libsql`, `@mastra/pg`, or `@mastra/mongodb`.
+OM requires a storage adapter that supports it: `@mastra/libsql`, `@mastra/pg`, `@mastra/mongodb`, or `@mastra/oracledb`.
 
 > **Note:** If you switch the Observer to a weaker model and see facts collapse to a generic `User`, use [`observation.instruction`](https://mastra.ai/reference/memory/observational-memory) to teach the Observer how to read the `<turn>` tag.
 

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

@@ -94,7 +94,7 @@ See [configuration options](https://mastra.ai/reference/memory/observational-mem
 >
 > For an AI SDK example, see [Using Mastra Memory](https://mastra.ai/guides/build-your-ui/ai-sdk-ui).
 
-> **Note:** OM currently only supports `@mastra/pg`, `@mastra/libsql`, `@mastra/mysql`, `@mastra/mongodb`, and `@mastra/convex` storage adapters. It uses background agents for managing memory. When no model is set, the default model is `google/gemini-2.5-flash`.
+> **Note:** OM currently only supports `@mastra/pg`, `@mastra/libsql`, `@mastra/mysql`, `@mastra/mongodb`, `@mastra/convex`, and `@mastra/oracledb` storage adapters. It uses background agents for managing memory. When no model is set, the default model is `google/gemini-2.5-flash`.
 
 ## Temporal gap markers
 

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

@@ -148,6 +148,7 @@ Each vector store page below includes installation instructions, configuration p
 - [libSQL](https://mastra.ai/reference/vectors/libsql)
 - [MongoDB](https://mastra.ai/reference/vectors/mongodb)
 - [OpenSearch](https://mastra.ai/reference/vectors/opensearch)
+- [OracleDB](https://mastra.ai/reference/vectors/oracledb)
 - [Pinecone](https://mastra.ai/reference/vectors/pinecone)
 - [PostgreSQL](https://mastra.ai/reference/vectors/pg)
 - [Qdrant](https://mastra.ai/reference/vectors/qdrant)
@@ -180,7 +181,7 @@ const agent = new Agent({
 })
 ```
 
-> **Note:** `scope: 'resource'` is supported by the LibSQL, PostgreSQL, MongoDB, and Upstash storage adapters.
+> **Note:** `scope: 'resource'` is supported by the LibSQL, OracleDB, PostgreSQL, MongoDB, and Upstash storage adapters.
 
 ### Metadata filtering
 

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

@@ -129,6 +129,7 @@ Resource-scoped working memory requires specific storage adapters that support t
 
 - **libSQL** (`@mastra/libsql`)
 - **PostgreSQL** (`@mastra/pg`)
+- **OracleDB** (`@mastra/oracledb`)
 - **Upstash** (`@mastra/upstash`)
 - **MongoDB** (`@mastra/mongodb`)
 

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

@@ -193,6 +193,7 @@ Each provider page includes installation instructions, configuration parameters,
 - [libSQL](https://mastra.ai/reference/storage/libsql)
 - [PostgreSQL](https://mastra.ai/reference/storage/postgresql)
 - [MongoDB](https://mastra.ai/reference/storage/mongodb)
+- [OracleDB](https://mastra.ai/reference/storage/oracledb)
 - [Upstash](https://mastra.ai/reference/storage/upstash)
 - [Redis](https://mastra.ai/reference/storage/redis)
 - [Cloudflare D1](https://mastra.ai/reference/storage/cloudflare-d1)

package/dist/docs/references/reference-file-based-agents-memory.md

@@ -2,6 +2,8 @@
 
 # Memory
 
+> **Beta:** Breaking changes may occur without a major version bump until the API is stable.
+
 A file-based agent gets [memory](https://mastra.ai/docs/memory/overview) from a `memory.ts` file that default-exports a [`Memory`](https://mastra.ai/reference/memory/memory-class) instance. Use this page for the file-based convention; use the memory docs for message history, semantic recall, storage, and processors.
 
 Without `memory.ts` or `config.memory`, the agent has no memory by default. Each `generate()` or `stream()` call starts without remembered conversation state unless you pass the prior context yourself.

package/dist/docs/references/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)