@mastra/oracledb 0.4.1 → 0.4.2-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.4.1"
+  version: "0.4.2-alpha.0"
 ---
 
 ## When to use

package/dist/docs/assets/SOURCE_MAP.json

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

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

@@ -128,7 +128,7 @@ export const agent = new Agent({
 
 Mastra inserts a temporal gap marker when the gap is at least 10 minutes. The marker is stored in memory and also emitted as a transient reminder event, so clients can render it as a lightweight timeline hint.
 
-The observer also sees these markers when it processes the thread, so the observations it writes can anchor memories to when they happened (for example, "User asked about deployment after a 2-day gap").
+The observer also sees these markers when it processes the thread. The observations it writes can anchor memories to when they happened (for example, "User asked about deployment after a 2-day gap").
 
 See [the API reference](https://mastra.ai/reference/memory/observational-memory) for the full configuration shape.
 
@@ -191,13 +191,47 @@ const memory = new Memory({
 
 `bufferOnIdle` is off by default. It's separate from `bufferTokens`: `bufferTokens` controls step-time async buffering, while `bufferOnIdle` controls end-of-turn buffering for idle turns.
 
+### Retries and failure policy
+
+Observer and Reflector model calls are retried on transient provider errors, and a turn aborts if they still fail. Each stage is controlled independently by:
+
+- `maxRetries`: retries after the initial model call (default `8`).
+- `failurePolicy`: what happens once retries are exhausted, either `'abort'` (default) or `'continue'`.
+
+```typescript
+const memory = new Memory({
+  options: {
+    observationalMemory: {
+      observation: {
+        maxRetries: 8,
+        failurePolicy: 'continue',
+      },
+      reflection: {
+        maxRetries: 8,
+        failurePolicy: 'continue',
+      },
+    },
+  },
+})
+```
+
+`maxRetries` governs OM's own retry ladder; the underlying model call is configured with no provider-level retries, so the option is the single retry knob for the stage.
+
+With `failurePolicy: 'continue'`, Mastra retries as configured, reports the failure through the existing OM diagnostics, keeps the failed input pending for a later cycle, and lets the main agent turn continue. It doesn't advance observation boundaries or discard unobserved messages. A Reflector failure under `'continue'` leaves any already-persisted observations committed and defers reflection to the next threshold crossing.
+
+A provider outage usually takes out both stages, so set the policy on both if you want the turn to survive one.
+
+This policy applies only to Observer and Reflector model and provider failures in synchronous, resource-scoped, and buffered observation. Persistence, indexing, transform, locking, invariant, and explicit abort failures remain fatal. It doesn't prevent the underlying provider or network error, change `blockAfter`, or change attachment handling.
+
+> **Warning:** `'continue'` has no backstop for a sustained outage. Unobserved messages stay pending and keep accruing in the main agent's context. A long outage moves the failure from the memory layer to the model's context limit.
+
 See [the API reference](https://mastra.ai/reference/memory/observational-memory) for the full configuration shape.
 
 ## Benefits
 
 - **Prompt caching**: OM's context is stable and observations append over time rather than being retrieved at runtime each turn. This keeps the prompt prefix cacheable, which reduces costs.
 - **Compression**: Raw message history and tool results get compressed into a dense observation log. Smaller context means faster responses and longer coherent conversations.
-- **Zero context rot**: The agent sees relevant information instead of noisy tool calls and irrelevant tokens, so the agent stays on task over long sessions.
+- **Zero context rot**: The agent sees relevant information instead of noisy tool calls and irrelevant tokens, which keeps the agent on task over long sessions.
 
 ## How it works
 
@@ -615,29 +649,42 @@ const memory = new Memory({
 
 Thread scope requires a valid `threadId` to be provided when calling the agent. If `threadId` is missing, Observational Memory throws an error. This prevents multiple threads from silently sharing a single observation record, which can cause database deadlocks.
 
-### Resource scope (experimental)
+### Resource scope (deprecated)
+
+> **Deprecated:** `scope: 'resource'` is deprecated and will be removed in a future release. Mastra logs a warning the first time Observational Memory is created with resource scope. Remove the `scope` option to use the default thread scope, and use the [alternatives below](#cross-thread-continuity-without-resource-scope) for cross-conversation continuity.
+
+In resource scope, observations are shared across all threads for a resource (typically a user). Resource scope works much worse than thread scope for prompt caching and for the agent's understanding of the conversation:
+
+- **Prompt caching:** Observations from every thread share one record. When any thread is observed, the observation context changes for all other threads, which invalidates their cached prompt prefix.
+- **Agent understanding:** Each thread sees a mix of observations from every thread for the resource. Every new thread starts with context from earlier threads, and the agent may continue work that another thread started but didn't finish.
+- **Performance:** Unobserved messages across _all_ threads are processed together, which is slow for users with many existing threads.
+
+A new knowledge and subconscious memory primitive for cross-thread memory is coming soon and will replace resource scope. Until then, use the alternatives below.
+
+#### Cross-thread continuity without resource scope
+
+Switching from resource scope to thread scope doesn't migrate resource-scoped observations. Each thread uses its existing thread-scoped record if it has one, or starts a new, empty one, and messages already observed under resource scope aren't observed again. Keep facts that must carry over in resource-scoped working memory.
 
-Observations are shared across all threads for a resource (typically a user). Enables cross-conversation memory.
+Use thread scope with one or both of these features instead:
+
+- [Retrieval mode](#retrieval-mode): The agent gets a `recall` tool that can list and browse other threads for the same resource, and optionally search them semantically. The agent looks up earlier conversations only when it needs them.
+- [Resource-scoped working memory](https://mastra.ai/docs/memory/working-memory): Stores small, durable facts about the user that every thread can read.
 
 ```typescript
 const memory = new Memory({
   options: {
     observationalMemory: {
       model: 'google/gemini-2.5-flash',
+      retrieval: true,
+    },
+    workingMemory: {
+      enabled: true,
       scope: 'resource',
     },
   },
 })
 ```
 
-Resource scope works, however it's marked as experimental for now until we prove task adherence/continuity across multiple ongoing simultaneous threads. As of today, you may need to tweak your system prompt to prevent one thread from continuing the work that another had already started (but hadn't finished).
-
-This is because in resource scope, each thread is a perspective on _all_ threads for the resource.
-
-For your use-case this may not be a problem, so your mileage may vary.
-
-> **Warning:** In resource scope, unobserved messages across _all_ threads are processed together. For users with many existing threads, this can be slow. Use thread scope for existing apps.
-
 ## Token budgets
 
 OM uses token thresholds to decide when to observe and reflect. See [token budget configuration](https://mastra.ai/reference/memory/observational-memory) for details.
@@ -786,7 +833,7 @@ const memory = new Memory({
 
 Setting `bufferTokens: false` disables both observation and reflection async buffering. See [async buffering configuration](https://mastra.ai/reference/memory/observational-memory) for the full API.
 
-> **Note:** Resource scope automatically disables async buffering.
+> **Note:** Resource scope (deprecated) automatically disables async buffering.
 
 ## Observer Context Optimization
 
@@ -889,7 +936,7 @@ hooks: {
 No manual migration needed. OM reads existing messages and observes them lazily when thresholds are exceeded.
 
 - **Thread scope**: The first time a thread exceeds `observation.messageTokens`, the Observer processes the backlog.
-- **Resource scope**: All unobserved messages across all threads for a resource are processed together. For users with many existing threads, this could take substantial time.
+- **Resource scope (deprecated)**: All unobserved messages across all threads for a resource are processed together. For users with many existing threads, this could take substantial time.
 
 ## Comparing OM with other memory features
 

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

@@ -202,7 +202,7 @@ async function retentionTick() {
 }
 ```
 
-You can also cancel a long-running prune with an `AbortSignal`: the loop stops between batches and returns partial results with `done: false`, so the next run resumes cleanly.
+You can also cancel a long-running prune with an `AbortSignal`: the loop stops between batches and returns partial results with `done: false`. The next run resumes cleanly.
 
 ## ClickHouse native TTL
 

package/dist/index.cjs

@@ -562,7 +562,7 @@ async function upsert(registry, withConnection, upsertBatchSize, { indexName, ve
 		if (error instanceof _mastra_core_error.MastraError) throw error;
 		throw asMastraError("UPSERT", "INVALID_INPUT", { indexName }, error, _mastra_core_error.ErrorCategory.USER);
 	}
-	const vectorIds = ids ?? vectors.map(() => (0, crypto$1.randomUUID)());
+	const vectorIds = ids ?? vectors.map(() => globalThis.crypto.randomUUID());
 	return withConnection(async (connection) => {
 		const indexInfo = await registry.getIndexMetadata(connection, indexName);
 		try {
@@ -3464,7 +3464,7 @@ function parseBufferedChunks(value) {
 	return parsed.map((chunk) => {
 		const item = chunk;
 		return {
-			id: String(item.id ?? `ombuf-${(0, crypto$1.randomUUID)()}`),
+			id: String(item.id ?? `ombuf-${globalThis.crypto.randomUUID()}`),
 			cycleId: String(item.cycleId ?? ""),
 			observations: String(item.observations ?? ""),
 			tokenCount: Math.round(numberOrZero(item.tokenCount)),
@@ -4348,7 +4348,7 @@ async function getObservationalMemoryHistory(ctx, threadId, resourceId, limit =
 async function initializeObservationalMemory(ctx, input) {
 	const now = /* @__PURE__ */ new Date();
 	const record = {
-		id: (0, crypto$1.randomUUID)(),
+		id: globalThis.crypto.randomUUID(),
 		scope: input.scope,
 		threadId: input.threadId,
 		resourceId: input.resourceId,
@@ -4425,7 +4425,7 @@ async function updateActiveObservations(ctx, input) {
 async function createReflectionGeneration(ctx, input) {
 	const now = /* @__PURE__ */ new Date();
 	const record = {
-		id: (0, crypto$1.randomUUID)(),
+		id: globalThis.crypto.randomUUID(),
 		scope: input.currentRecord.scope,
 		threadId: input.currentRecord.threadId,
 		resourceId: input.currentRecord.resourceId,
@@ -4749,7 +4749,7 @@ async function updateBufferedObservations(ctx, input) {
 		await ctx.db.tx(async (_client, connection) => {
 			const existingChunks = parseBufferedChunks((await lockOMRow(ctx, connection, input.id, "UPDATE_BUFFERED_OBSERVATIONS")).bufferedObservationChunks);
 			const newChunk = {
-				id: `ombuf-${(0, crypto$1.randomUUID)()}`,
+				id: `ombuf-${globalThis.crypto.randomUUID()}`,
 				cycleId: input.chunk.cycleId,
 				observations: input.chunk.observations,
 				tokenCount: Math.round(input.chunk.tokenCount),
@@ -4855,7 +4855,7 @@ async function swapBufferedReflectionToActive(ctx, input) {
 			const now = /* @__PURE__ */ new Date();
 			const lockedRecord = parseOMRow(row);
 			const newRecord = {
-				id: (0, crypto$1.randomUUID)(),
+				id: globalThis.crypto.randomUUID(),
 				scope: lockedRecord.scope,
 				threadId: lockedRecord.threadId,
 				resourceId: lockedRecord.resourceId,
@@ -5489,7 +5489,7 @@ var MemoryOracle = class MemoryOracle extends _mastra_core_storage.MemoryStorage
 		const sourceThread = await this.getThreadById({ threadId: args.sourceThreadId });
 		if (!sourceThread) throw storageError$1("CLONE_THREAD", "FAILED", { threadId: args.sourceThreadId }, /* @__PURE__ */ new Error(`Thread ${args.sourceThreadId} not found`), _mastra_core_error.ErrorCategory.USER);
 		const sourceMessages = await this.messagesForClone(args);
-		const newThreadId = args.newThreadId ?? (0, crypto$1.randomUUID)();
+		const newThreadId = args.newThreadId ?? globalThis.crypto.randomUUID();
 		if (await this.getThreadById({ threadId: newThreadId })) throw storageError$1("CLONE_THREAD", "DESTINATION_EXISTS", { threadId: newThreadId }, /* @__PURE__ */ new Error(`Thread ${newThreadId} already exists`), _mastra_core_error.ErrorCategory.USER);
 		const now = /* @__PURE__ */ new Date();
 		const cloneMetadata = {
@@ -5511,7 +5511,7 @@ var MemoryOracle = class MemoryOracle extends _mastra_core_storage.MemoryStorage
 		};
 		const messageIdMap = {};
 		const clonedMessages = sourceMessages.map((message) => {
-			const newMessageId = (0, crypto$1.randomUUID)();
+			const newMessageId = globalThis.crypto.randomUUID();
 			messageIdMap[message.id] = newMessageId;
 			return {
 				...message,
@@ -5988,7 +5988,7 @@ async function batchCreateLogs(db, schemaName, args) {
 	try {
 		const binds = args.logs.map((log) => logRecordBinds({
 			...log,
-			logId: log.logId ?? (0, crypto$1.randomUUID)(),
+			logId: log.logId ?? globalThis.crypto.randomUUID(),
 			executionSource: log.executionSource ?? log.source ?? null
 		}));
 		await db.tx(async (client) => {
@@ -6245,7 +6245,7 @@ function transformObservabilityScoreRow(row) {
 	};
 }
 function scoreRecordToTableRecord(score) {
-	const id = score.scoreId ?? (0, crypto$1.randomUUID)();
+	const id = score.scoreId ?? globalThis.crypto.randomUUID();
 	const timestamp = score.timestamp instanceof Date ? score.timestamp : new Date(score.timestamp ?? Date.now());
 	const source = score.scoreSource ?? score.source ?? "observability";
 	const contextualMetadata = removeUndefined({
@@ -7594,7 +7594,7 @@ var ScoresOracle = class ScoresOracle extends _mastra_core_storage.ScoresStorage
 			}, error, _mastra_core_error.ErrorCategory.USER);
 		}
 		try {
-			const id = (0, crypto$1.randomUUID)();
+			const id = globalThis.crypto.randomUUID();
 			const now = /* @__PURE__ */ new Date();
 			await this.db.insert({
 				tableName: _mastra_core_storage.TABLE_SCORERS,