@mastra/oracledb 0.5.0 → 0.5.1-alpha.0

package/dist/docs/SKILL.md

@@ -3,7 +3,7 @@ name: mastra-oracledb
 description: Documentation for @mastra/oracledb. Use when working with @mastra/oracledb APIs, configuration, or implementation.
 metadata:
   package: "@mastra/oracledb"
-  version: "0.5.0"
+  version: "0.5.1-alpha.0"
 ---
 
 ## When to use

package/dist/docs/assets/SOURCE_MAP.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.5.0",
+  "version": "0.5.1-alpha.0",
   "package": "@mastra/oracledb",
   "exports": {},
   "modules": {}

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

@@ -418,6 +418,8 @@ new Agent({
 
 You can also pass an allowlist of mimeType globs (for example `['image/*']`) to forward only the kinds the Observer can handle. Alternatively, set `observeAttachments: 'auto'` so Mastra consults the provider capabilities registry. It forwards attachments when the Observer model supports multimodal input and drops them otherwise. If capability data is unavailable for the model, the setting falls back to `true`.
 
+Attachments that the agent recorded as unavailable, because they could no longer be downloaded, are never sent to the Observer. The Observer still sees their `[Image #1: ...]` or `[File #1: ...]` line. See [attachment download failures](https://mastra.ai/docs/agents/processors) for how Mastra records them.
+
 ```md
 Date: 2026-01-15
 
@@ -765,7 +767,7 @@ When message tokens reach the `messageTokens` threshold, buffered chunks activat
 
 Async buffered Observer calls don't generate continuation hints because delayed hints can be stale by activation time. When buffered chunks activate, any previously stored suggested response and current task are cleared. The main agent receives the compressed observations without those hints.
 
-When message production outpaces the Observer, the `blockAfter` safety threshold allows activation to overshoot the retention target instead of using fewer chunks. Activation still uses no more chunks than needed to reach the target, and the default settings remain unaffected. A synchronous observation runs when the `messageTokens` threshold is reached and buffered activation didn't happen. Buffered activation usually preserves a minimum remaining context (the smaller of \~1k tokens or the configured retention floor), but a single buffered chunk that covers the whole pending window still activates and can leave less.
+When message production outpaces the Observer, the `blockAfter` safety threshold allows activation to overshoot the retention target instead of using fewer chunks. Activation still uses no more chunks than needed to reach the target, and the default settings remain unaffected. A synchronous observation runs when the `messageTokens` threshold is reached and activating buffered chunks doesn't bring pending tokens back under it. For example, this happens when a large tool result arrives after buffering has stopped. Buffered activation usually preserves a minimum remaining context (the smaller of \~1k tokens or the configured retention floor), but a single buffered chunk that covers the whole pending window still activates and can leave less.
 
 Reflection works similarly: the Reflector runs in the background when observations reach a fraction of the reflection threshold.
 
@@ -776,7 +778,7 @@ Reflection works similarly: the Reflector runs in the background when observatio
 | `observation.bufferTokens`            | `0.2`   | How often to buffer. `0.2` means every 20% of `messageTokens`. With the default 30k threshold, that's roughly every 6k tokens. Can also be an absolute token count (e.g. `5000`).                                                                                                                                                                                                |
 | `observation.bufferActivation`        | `0.8`   | How aggressively to clear the message window on activation. `0.8` means remove enough messages to keep only 20% of `messageTokens` remaining. Lower values keep more message history.                                                                                                                                                                                            |
 | `observation.blockAfter`              | `1.2`   | Safety net if buffering can't keep up. Values from 1 up to (but not including) 100 multiply `messageTokens`. For example, `1.2` creates a threshold of 36k tokens (1.2 × 30k), above which activation may overshoot the retention target rather than use fewer chunks. Values of 100 or more are absolute token counts (e.g. `50_000`) and must be greater than `messageTokens`. |
-| `activateAfterIdle`                   | none    | Forces buffered observations to activate after a period of inactivity, even before `observation.messageTokens` is reached. Accepts a numeric millisecond value such as `300_000`, duration strings like `"5m"` or `"1hr"`, or `"auto"` for a provider-aware prompt cache TTL.                                                                                                    |
+| `activateAfterIdle`                   | none    | Forces buffered observations to activate after a period of inactivity, even before `observation.messageTokens` is reached. Accepts a numeric millisecond value such as `300_000`, duration strings like `"5m"` or `"1hr"`, `"auto"` for a provider-aware prompt cache TTL, or an object of per-provider TTLs such as `{ default: 'auto', anthropic: '1h' }`.                     |
 | `activateOnProviderChange`            | `false` | Forces buffered observations to activate when the next step uses a different `provider/model` than the one that produced the latest assistant step. Use this when switching providers or models would invalidate prompt cache reuse.                                                                                                                                             |
 | `reflection.bufferActivation`         | `0.5`   | When to start background reflection. `0.5` means reflection begins when observations reach 50% of the `observationTokens` threshold.                                                                                                                                                                                                                                             |
 | `reflection.activateAfterIdle`        | none    | Opts buffered reflections into idle activation. Reflections don't inherit top-level `activateAfterIdle`.                                                                                                                                                                                                                                                                         |
@@ -814,6 +816,30 @@ With `"auto"`, this activates buffered observations based on the active provider
 
 Changing models or providers mid-thread will invalidate the prompt cache. If your agent can switch between providers or models mid-thread, `activateOnProviderChange: true` forces buffered observations to activate before the new provider runs. That avoids sending a large raw window to a provider that can't reuse the previous prompt cache.
 
+#### Per-provider idle TTLs
+
+`"auto"` can't see a cache TTL that you set on individual messages, such as Anthropic's `cacheControl: { type: 'ephemeral', ttl: '1h' }`. It keeps using the provider's 5-minute default, so buffered observations activate while the 1-hour cache is still warm. Pass an object to set the TTL per provider instead:
+
+```typescript
+const memory = new Memory({
+  options: {
+    observationalMemory: {
+      model: 'google/gemini-2.5-flash',
+      activateAfterIdle: { default: 'auto', anthropic: '1h' },
+    },
+  },
+})
+```
+
+Set the `anthropic` entry to the same TTL as your `cacheControl.ttl`. Mastra doesn't read the per-message cache setting, so the two must be kept in sync by hand.
+
+How the object resolves:
+
+- Keys are provider names. Mastra compares them case-insensitively with the part of the model's provider before the first `.`, so `anthropic` matches both `anthropic` and `anthropic.messages`. Claude served through another provider uses that provider's key instead, for example `amazon-bedrock`. Keys must not contain `.` or `/`.
+- Each value accepts the same forms as a single TTL: milliseconds, a duration string, `"auto"`, or `false` to turn off idle activation for that provider.
+- `default` applies to every provider without its own key. Without `default`, those providers don't idle-activate.
+- `observation.activateAfterIdle` and `reflection.activateAfterIdle` accept the same object. An `observation.activateAfterIdle` object replaces the top-level value and isn't merged with it.
+
 ### Disabling
 
 To disable async buffering and use synchronous observation/reflection instead:

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

@@ -20,7 +20,7 @@ After getting a response from the LLM, all new messages (user, assistant, and to
 
 ## Quickstart
 
-Semantic recall is disabled by default. To enable it, set `semanticRecall: true` in `options` and provide a `vector` store and `embedder`:
+Semantic recall is disabled by default. To enable it, set `semanticRecall: true` in `options` and provide a `vector` store and an `embedder`. A store that generates embeddings itself, such as MongoDB with Automated Embedding, works without one. See [Server-side embeddings](#server-side-embeddings).
 
 **LibSQL**:
 
@@ -242,6 +242,40 @@ const options = {
 }
 ```
 
+## Server-side embeddings
+
+Some vector stores generate the embeddings themselves. With one of those, semantic recall runs without an `embedder`: the database embeds each message on write and the search string on arrival. The embedding provider stays out of your application entirely.
+
+MongoDB does this through [Automated Embedding](https://mastra.ai/reference/vectors/mongodb): name a Voyage AI model on the vector store and leave the `embedder` out.
+
+```typescript
+import { Memory } from '@mastra/memory'
+import { MongoDBStore, MongoDBVector } from '@mastra/mongodb'
+
+const memory = new Memory({
+  storage: new MongoDBStore({
+    id: 'agent-storage',
+    uri: process.env.MONGODB_URI,
+    dbName: process.env.MONGODB_DB_NAME,
+  }),
+  vector: new MongoDBVector({
+    id: 'agent-vector',
+    uri: process.env.MONGODB_URI,
+    dbName: process.env.MONGODB_DB_NAME,
+    autoEmbed: { model: 'voyage-4' },
+  }),
+  options: {
+    semanticRecall: { topK: 3, messageRange: 2 },
+  },
+})
+```
+
+Messages are stored as text and MongoDB embeds them, so the model choice and the vector size belong to the index rather than to your application. Recall works the same way through an agent and through [`recall()`](#using-the-recall-method).
+
+MongoDB embeds newly written messages in the background. A message saved moments ago may not be recallable immediately.
+
+Every other store expects your application to supply the vectors, and keeps requiring an `embedder`. Enabling semantic recall with neither an `embedder` nor a store that embeds server-side raises an error naming both options.
+
 ## Embedder configuration
 
 Semantic recall relies on an [embedding model](https://mastra.ai/reference/memory/memory-class) to convert messages into embeddings. Mastra supports embedding models through the model router using `provider/model` strings, or you can use any [embedding model](https://sdk.vercel.ai/docs/ai-sdk-core/embeddings) compatible with the AI SDK.
@@ -377,11 +411,11 @@ PostgreSQL supports both IVFFlat and HNSW indexes. By default, Mastra creates an
 
 ```typescript
 import { Memory } from '@mastra/memory'
-import { PgStore, PgVector } from '@mastra/pg'
+import { PostgresStore, PgVector } from '@mastra/pg'
 
 const agent = new Agent({
   memory: new Memory({
-    storage: new PgStore({
+    storage: new PostgresStore({
       id: 'agent-storage',
       connectionString: process.env.DATABASE_URL,
     }),

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

@@ -272,6 +272,22 @@ Schema-based working memory uses **merge semantics**, meaning the agent only nee
 - **Set a field to `null` to delete it:** This explicitly removes the field from memory
 - **Arrays are replaced entirely:** When an array field is provided, it replaces the existing array (arrays aren't merged element-by-element)
 
+### Concurrent updates
+
+With `scope: 'resource'` and a storage adapter that supports atomic merges (currently `@mastra/pg`), each merge runs inside a row-locked database transaction. Concurrent updates to different fields from separate processes are all kept. Other adapters merge in the application, which only serializes writers inside a single process.
+
+To merge a partial update from your own code, call `memory.mergeWorkingMemory()`:
+
+```typescript
+await memory.mergeWorkingMemory({
+  threadId: 'thread-1',
+  resourceId: 'user-123',
+  workingMemory: { preferences: { tone: 'formal' } },
+})
+```
+
+It throws if working memory isn't schema-based and resource-scoped, or if the storage adapter doesn't support atomic merges. Check `await memory.supportsAtomicWorkingMemoryMerge()` first if you need to fall back.
+
 ## Choosing between template and schema
 
 - Use a **template** (Markdown) if you want the agent to maintain memory as a free-form text block, such as a user profile or scratchpad. Templates use **replace semantics**: the agent must provide the complete memory content on each update.

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

@@ -194,6 +194,7 @@ Each provider page includes installation instructions, configuration parameters,
 
 - [Aurora DSQL](https://mastra.ai/integrations/databases/aurora-dsql)
 - [ClickHouse](https://mastra.ai/integrations/databases/clickhouse)
+- [ClickHouse Managed Postgres](https://mastra.ai/integrations/databases/clickhouse-managed-postgres)
 - [Cloudflare D1](https://mastra.ai/integrations/databases/cloudflare-d1)
 - [Cloudflare KV](https://mastra.ai/integrations/databases/cloudflare-kv)
 - [Convex](https://mastra.ai/integrations/databases/convex)

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

@@ -231,7 +231,7 @@ await store.createIndex({
 - [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)
+- [PgVector](https://mastra.ai/reference/vectors/pg)
 - [Pinecone](https://mastra.ai/reference/vectors/pinecone)
 - [Qdrant](https://mastra.ai/reference/vectors/qdrant)
 - [Upstash](https://mastra.ai/reference/vectors/upstash)

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

@@ -50,23 +50,25 @@ console.log(results)
 
 The `topK` parameter specifies the maximum number of most similar results to return from the vector search.
 
-Results include both the text content and a similarity score:
+Each result includes an `id`, a similarity `score`, and the stored `metadata`. When you store chunk text in metadata, it's available as `metadata.text`:
 
 ```ts
 [
   {
-    text: 'Climate change poses significant challenges...',
+    id: 'chunk-1',
     score: 0.89,
-    metadata: { source: 'article1.txt' },
+    metadata: { text: 'Climate change poses significant challenges...', source: 'article1.txt' },
   },
   {
-    text: 'Rising temperatures affect crop yields...',
+    id: 'chunk-2',
     score: 0.82,
-    metadata: { source: 'article1.txt' },
+    metadata: { text: 'Rising temperatures affect crop yields...', source: 'article1.txt' },
   },
 ]
 ```
 
+Results can also include `vector` when you set `includeVector: true`, and `document` when the store returns the original document (Chroma only).
+
 ## Advanced retrieval options
 
 ### Metadata Filtering

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

@@ -230,7 +230,7 @@ await store.upsert({
 **libSQL**:
 
 ```ts
-import { LibSQLVector } from '@mastra/core/vector/libsql'
+import { LibSQLVector } from '@mastra/libsql'
 
 const store = new LibSQLVector({
   id: 'libsql-vector',

package/dist/index.cjs

@@ -7999,7 +7999,7 @@ var WorkflowsOracle = class WorkflowsOracle extends _mastra_core_storage.Workflo
 	async dangerouslyClearAll() {
 		await this.db.clearTable(_mastra_core_storage.TABLE_WORKFLOW_SNAPSHOT);
 	}
-	async updateWorkflowResults({ workflowName, runId, stepId, result, requestContext }) {
+	async updateWorkflowResults({ workflowName, runId, stepId, result, requestContext, state }) {
 		try {
 			return await this.db.tx(async (client) => {
 				await this.ensureWorkflowRunRow(client, workflowName, runId);
@@ -8009,6 +8009,7 @@ var WorkflowsOracle = class WorkflowsOracle extends _mastra_core_storage.Workflo
 				});
 				const snapshot = parseSnapshot(existing.snapshot);
 				snapshot.context[stepId] = result;
+				if (state !== void 0) snapshot.context.__state = state;
 				snapshot.requestContext = {
 					...snapshot.requestContext ?? {},
 					...requestContext