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

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # @mastra/memory
 
+## 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.4"
 ---
 
 ## 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.4",
   "package": "@mastra/memory",
   "exports": {},
   "modules": {

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-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)