@mastra/memory 1.28.3 → 1.29.0-alpha.0

package/dist/{src-D4Wm6M4v.cjs → src-CG7RR0Ep.cjs}

@@ -19811,6 +19811,37 @@ async function withOmTracingSpan({ phase, model, inputTokens, requestContext, ob
 	});
 }
 //#endregion
+//#region src/processors/observational-memory/transform-hooks.ts
+/**
+* Run the `beforeObservation` transform hook. Returns the (possibly replaced)
+* message array; `undefined` from the hook means passthrough.
+*/
+async function applyBeforeObservation(hooks, messages, context) {
+	if (!hooks?.beforeObservation) return messages;
+	const result = await hooks.beforeObservation({
+		...context,
+		messages
+	});
+	if (!result) return messages;
+	omDebug(`[OM:hooks] beforeObservation replaced messages: ${messages.length} -> ${result.messages.length}`);
+	return result.messages;
+}
+/**
+* Run one of the text transform hooks. Returns the (possibly replaced)
+* observation text; `undefined` from the hook means passthrough.
+*/
+async function applyTextTransform(hooks, name, observations, context) {
+	const hook = hooks?.[name];
+	if (!hook) return observations;
+	const result = await hook({
+		...context,
+		observations
+	});
+	if (!result) return observations;
+	omDebug(`[OM:hooks] ${name} replaced observations: ${observations.length} -> ${result.observations.length} chars`);
+	return result.observations;
+}
+//#endregion
 //#region src/processors/observational-memory/observer-runner.ts
 function filterObserverExtractors(extractors, skipContinuationHints) {
 	const configuredExtractors = extractors ?? [];
@@ -19823,6 +19854,7 @@ var ObserverRunner = class {
 	resolveModel;
 	tokenCounter;
 	memory;
+	hooks;
 	mastra;
 	/** Captured prompt/response from the last observer call (for repro capture). */
 	lastExchange;
@@ -19833,6 +19865,7 @@ var ObserverRunner = class {
 		this.tokenCounter = opts.tokenCounter;
 		this.mastra = opts.mastra;
 		this.memory = opts.memory;
+		this.hooks = opts.hooks;
 	}
 	__registerMastra(mastra) {
 		this.mastra = mastra;
@@ -19886,9 +19919,25 @@ var ObserverRunner = class {
 		return result;
 	}
 	/**
-	* Call the Observer agent for a single thread.
+	* Call the Observer agent for a single thread, running the config-level
+	* `beforeObservation` / `afterObservation` transform hooks around it.
 	*/
 	async call(existingObservations, messagesToObserve, abortSignal, options) {
+		const context = {
+			threadId: options?.threadId ?? messagesToObserve[0]?.threadId,
+			resourceId: options?.resourceId,
+			trigger: options?.trigger
+		};
+		const messages = await applyBeforeObservation(this.hooks, messagesToObserve, context);
+		if (messages.length === 0) {
+			omDebug("[OM:callObserver] beforeObservation returned no messages, skipping observer call");
+			return { observations: "" };
+		}
+		const result = await this.callObserver(existingObservations, messages, abortSignal, options);
+		result.observations = await applyTextTransform(this.hooks, "afterObservation", result.observations, context);
+		return result;
+	}
+	async callObserver(existingObservations, messagesToObserve, abortSignal, options) {
 		const inputTokens = this.tokenCounter.countMessages(messagesToObserve);
 		const resolvedModel = options?.model ? { model: options.model } : this.resolveModel(inputTokens);
 		const activeExtractors = await resolveExtractors(filterObserverExtractors(this.observationConfig.extractors, options?.skipContinuationHints), {
@@ -20007,7 +20056,30 @@ var ObserverRunner = class {
 	/**
 	* Call the Observer agent for multiple threads in a single batched request.
 	*/
-	async callMultiThread(existingObservations, messagesByThread, threadOrder, abortSignal, requestContext, priorMetadataByThread, observabilityContext, model) {
+	async callMultiThread(existingObservations, allMessagesByThread, allThreadOrder, abortSignal, requestContext, priorMetadataByThread, observabilityContext, model, hookContext) {
+		const contextFor = (threadId) => ({
+			threadId,
+			...hookContext
+		});
+		const messagesByThread = /* @__PURE__ */ new Map();
+		for (const threadId of allThreadOrder) {
+			const filtered = await applyBeforeObservation(this.hooks, allMessagesByThread.get(threadId) ?? [], contextFor(threadId));
+			if (filtered.length > 0) messagesByThread.set(threadId, filtered);
+		}
+		const threadOrder = allThreadOrder.filter((threadId) => messagesByThread.has(threadId));
+		const output = await this.callMultiThreadObserver(existingObservations, messagesByThread, threadOrder, abortSignal, requestContext, priorMetadataByThread, observabilityContext, model);
+		for (const threadId of allThreadOrder) {
+			const threadResult = output.results.get(threadId);
+			if (!threadResult) {
+				output.results.set(threadId, { observations: "" });
+				continue;
+			}
+			threadResult.observations = await applyTextTransform(this.hooks, "afterObservation", threadResult.observations, contextFor(threadId));
+		}
+		return output;
+	}
+	async callMultiThreadObserver(existingObservations, messagesByThread, threadOrder, abortSignal, requestContext, priorMetadataByThread, observabilityContext, model) {
+		if (threadOrder.length === 0) return { results: /* @__PURE__ */ new Map() };
 		const inputTokens = Array.from(messagesByThread.values()).reduce((total, messages) => total + this.tokenCounter.countMessages(messages), 0);
 		const resolvedModel = model ? { model } : this.resolveModel(inputTokens);
 		const firstThreadMessages = messagesByThread.get(threadOrder[0] ?? "") ?? [];
@@ -20026,7 +20098,7 @@ var ObserverRunner = class {
 				totalTokens: 0
 			};
 			for (const threadId of threadOrder) {
-				const threadResult = await this.call(existingObservations, messagesByThread.get(threadId) ?? [], abortSignal, {
+				const threadResult = await this.callObserver(existingObservations, messagesByThread.get(threadId) ?? [], abortSignal, {
 					requestContext,
 					observabilityContext,
 					priorCurrentTask: priorMetadataByThread?.get(threadId)?.currentTask,
@@ -24083,6 +24155,7 @@ var ObservationStrategy = class ObservationStrategy {
 				sendSignal: this.opts.sendSignal,
 				sendStateSignal: this.opts.sendStateSignal,
 				reflectionHooks,
+				trigger: this.opts.trigger,
 				requestContext,
 				observabilityContext: this.opts.observabilityContext
 			});
@@ -24363,7 +24436,9 @@ var SyncObservationStrategy = class extends ObservationStrategy {
 			priorSuggestedResponse: omMeta?.suggestedResponse,
 			priorThreadTitle: omMeta?.threadTitle,
 			priorExtractedValues: this.priorExtractedValues,
+			threadId: this.opts.threadId,
 			resourceId: this.opts.resourceId,
+			trigger: this.opts.trigger,
 			mainAgent: this.opts.agent
 		});
 		const hookedValues = await applyExtractorHooks({
@@ -24548,7 +24623,9 @@ var AsyncBufferObservationStrategy = class extends ObservationStrategy {
 			requestContext: this.opts.requestContext,
 			observabilityContext: this.opts.observabilityContext,
 			priorExtractedValues: this.priorExtractedValues,
+			threadId: this.opts.threadId,
 			resourceId: this.opts.resourceId,
+			trigger: this.opts.trigger,
 			mainAgent: this.opts.agent
 		});
 		const hookedValues = await applyExtractorHooks({
@@ -24872,7 +24949,10 @@ var ResourceScopedObservationStrategy = class extends ObservationStrategy {
 		}
 		if (currentBatch.threadIds.length > 0) batches.push(currentBatch);
 		const batchResults = await Promise.all(batches.map(async (batch) => {
-			return this.deps.observer.callMultiThread(_existingObservations, batch.threadMap, batch.threadIds, this.opts.abortSignal, this.opts.requestContext, this.priorMetadataByThread, this.opts.observabilityContext);
+			return this.deps.observer.callMultiThread(_existingObservations, batch.threadMap, batch.threadIds, this.opts.abortSignal, this.opts.requestContext, this.priorMetadataByThread, this.opts.observabilityContext, void 0, {
+				resourceId: this.opts.resourceId,
+				trigger: this.opts.trigger
+			});
 		}));
 		for (const batchResult of batchResults) {
 			for (const [threadId, result] of batchResult.results) this.multiThreadResults.set(threadId, result);
@@ -25210,7 +25290,8 @@ var ObservationStep = class {
 					threadId,
 					resourceId,
 					trigger: "turn-sync"
-				})
+				}),
+				trigger: "turn-sync"
 			});
 			await this.turn.refreshRecord();
 			if (this.turn.record.generationCount > preReflectGeneration) reflected = true;
@@ -25413,7 +25494,8 @@ var ObservationStep = class {
 						threadId,
 						resourceId,
 						trigger: "turn-sync"
-					})
+					}),
+					trigger: "turn-sync"
 				});
 				return {
 					succeeded: true,
@@ -26050,6 +26132,7 @@ var ReflectorRunner = class {
 	getCompressionStartLevel;
 	memory;
 	onReflectionCommitted;
+	hooks;
 	mastra;
 	/**
 	* Per-lock-key observation-token count of the last unproductive synchronous
@@ -26081,6 +26164,7 @@ var ReflectorRunner = class {
 		this.mastra = opts.mastra;
 		this.memory = opts.memory;
 		this.onReflectionCommitted = opts.onReflectionCommitted;
+		this.hooks = opts.hooks;
 	}
 	__registerMastra(mastra) {
 		this.mastra = mastra;
@@ -26303,7 +26387,7 @@ var ReflectorRunner = class {
 	/**
 	* Start an async buffered reflection in the background.
 	*/
-	startAsyncBufferedReflection(record, observationTokens, lockKey, writer, requestContext, observabilityContext, reflectionHooks, priorExtractedValues, mainAgent, sendSignal) {
+	startAsyncBufferedReflection(record, observationTokens, lockKey, writer, requestContext, observabilityContext, reflectionHooks, priorExtractedValues, mainAgent, sendSignal, trigger) {
 		const bufferKey = this.buffering.getReflectionBufferKey(lockKey);
 		if (this.buffering.isAsyncBufferingInProgress(bufferKey)) return;
 		BufferingCoordinator.lastBufferedBoundary.set(bufferKey, observationTokens);
@@ -26316,7 +26400,7 @@ var ReflectorRunner = class {
 			let reflectionError;
 			try {
 				await reflectionHooks?.onReflectionStart?.();
-				outcome = await this.doAsyncBufferedReflection(record, bufferKey, writer, requestContext, observabilityContext, priorExtractedValues, mainAgent, sendSignal);
+				outcome = await this.doAsyncBufferedReflection(record, bufferKey, writer, requestContext, observabilityContext, priorExtractedValues, mainAgent, sendSignal, trigger);
 			} catch (error) {
 				reflectionError = error instanceof Error ? error : new Error(String(error));
 				if (writer) try {
@@ -26362,7 +26446,7 @@ var ReflectorRunner = class {
 	* Perform async buffered reflection — reflects observations and stores to bufferedReflection.
 	* Does NOT create a new generation or update activeObservations.
 	*/
-	async doAsyncBufferedReflection(record, _bufferKey, writer, requestContext, observabilityContext, priorExtractedValues, mainAgent, sendSignal) {
+	async doAsyncBufferedReflection(record, _bufferKey, writer, requestContext, observabilityContext, priorExtractedValues, mainAgent, sendSignal, trigger) {
 		const currentRecord = await this.storage.getObservationalMemory(record.threadId, record.resourceId) ?? record;
 		const observationTokens = currentRecord.observationTokenCount ?? 0;
 		const reflectThreshold = getMaxThreshold(this.getEffectiveReflectionTokens(currentRecord));
@@ -26375,7 +26459,12 @@ var ReflectorRunner = class {
 		const avgTokensPerLine = totalLines > 0 ? observationTokens / totalLines : 0;
 		const activationPointTokens = reflectThreshold * bufferActivation;
 		const linesToReflect = avgTokensPerLine > 0 ? Math.min(Math.floor(activationPointTokens / avgTokensPerLine), totalLines) : totalLines;
-		const activeObservations = allLines.slice(0, linesToReflect).join("\n");
+		const hookContext = {
+			threadId: currentRecord.threadId ?? void 0,
+			resourceId: currentRecord.resourceId ?? void 0,
+			trigger
+		};
+		const activeObservations = await applyTextTransform(this.hooks, "beforeReflection", allLines.slice(0, linesToReflect).join("\n"), hookContext);
 		const reflectedObservationLineCount = linesToReflect;
 		const sliceTokenEstimate = Math.round(avgTokensPerLine * linesToReflect);
 		const compressionTarget = Math.round(sliceTokenEstimate * .75);
@@ -26399,6 +26488,7 @@ var ReflectorRunner = class {
 		}
 		const compressionStartLevel = await this.getCompressionStartLevel(requestContext);
 		const reflectResult = await this.call(activeObservations, void 0, void 0, compressionTarget, void 0, true, compressionStartLevel, requestContext, priorExtractedValues, observabilityContext, void 0, mainAgent, sendSignal);
+		reflectResult.observations = await applyTextTransform(this.hooks, "afterReflection", reflectResult.observations, hookContext);
 		await persistThreadExtractedValues(this.storage, this.reflectionConfig.extractors, currentRecord.threadId ?? void 0, reflectResult.extractedValues);
 		const reflectionTokenCount = this.tokenCounter.countObservations(reflectResult.observations);
 		omDebug(`[OM:reflect] doAsyncBufferedReflection: reflector returned ${reflectionTokenCount} tokens (${reflectResult.observations?.length} chars), saving to recordId=${currentRecord.id}`);
@@ -26545,7 +26635,7 @@ var ReflectorRunner = class {
 	* @internal Used by observation strategies. Do not call directly.
 	*/
 	async maybeReflect(opts) {
-		const { record, observationTokens, writer, abortSignal, mainAgent, sendSignal, sendStateSignal, messageList, currentModel, reflectionHooks, requestContext, observabilityContext, lastActivityAt, threadId: requestedThreadId } = opts;
+		const { record, observationTokens, writer, abortSignal, mainAgent, sendSignal, sendStateSignal, messageList, currentModel, reflectionHooks, trigger, requestContext, observabilityContext, lastActivityAt, threadId: requestedThreadId } = opts;
 		const lockKey = this.buffering.getLockKey(record.threadId, record.resourceId);
 		const reflectThreshold = getMaxThreshold(this.getEffectiveReflectionTokens(record));
 		const priorExtractedValues = await getThreadExtractedValues(this.storage, this.reflectionConfig.extractors, requestedThreadId ?? record.threadId);
@@ -26563,7 +26653,7 @@ var ReflectorRunner = class {
 				if (record.bufferedReflection) return false;
 				const activationPoint = reflectThreshold * this.reflectionConfig.bufferActivation;
 				return observationTokens >= activationPoint;
-			})()) this.startAsyncBufferedReflection(record, observationTokens, lockKey, writer, requestContext, observabilityContext, reflectionHooks, priorExtractedValues, mainAgent, sendSignal);
+			})()) this.startAsyncBufferedReflection(record, observationTokens, lockKey, writer, requestContext, observabilityContext, reflectionHooks, priorExtractedValues, mainAgent, sendSignal, trigger);
 		}
 		const activateAfterIdle = resolveActivationTTL(this.reflectionConfig.activateAfterIdle, currentModel);
 		const ttlExpiredMs = activateAfterIdle !== void 0 && lastActivityAt !== void 0 ? Date.now() - lastActivityAt : void 0;
@@ -26612,7 +26702,7 @@ var ReflectorRunner = class {
 					return;
 				}
 				omDebug(`[OM:reflect] async activation failed, no blockAfter or below it (obsTokens=${observationTokens}, blockAfter=${this.reflectionConfig.blockAfter}) — starting background reflection`);
-				this.startAsyncBufferedReflection(record, observationTokens, lockKey, writer, requestContext, observabilityContext, reflectionHooks, priorExtractedValues, mainAgent, sendSignal);
+				this.startAsyncBufferedReflection(record, observationTokens, lockKey, writer, requestContext, observabilityContext, reflectionHooks, priorExtractedValues, mainAgent, sendSignal, trigger);
 				return;
 			}
 		}
@@ -26673,7 +26763,13 @@ var ReflectorRunner = class {
 				throw error;
 			}
 			const compressionStartLevel = await this.getCompressionStartLevel(requestContext);
-			const reflectResult = await this.call(record.activeObservations, void 0, streamContext, reflectThreshold, abortSignal, void 0, compressionStartLevel, requestContext, priorExtractedValues, observabilityContext, void 0, mainAgent, sendSignal);
+			const hookContext = {
+				threadId: requestedThreadId ?? record.threadId ?? void 0,
+				resourceId: record.resourceId ?? void 0,
+				trigger
+			};
+			const reflectResult = await this.call(await applyTextTransform(this.hooks, "beforeReflection", record.activeObservations, hookContext), void 0, streamContext, reflectThreshold, abortSignal, void 0, compressionStartLevel, requestContext, priorExtractedValues, observabilityContext, void 0, mainAgent, sendSignal);
+			reflectResult.observations = await applyTextTransform(this.hooks, "afterReflection", reflectResult.observations, hookContext);
 			reflectionUsage = reflectResult.usage;
 			reflectionProviderMetadata = reflectResult.providerMetadata;
 			await persistThreadExtractedValues(this.storage, this.reflectionConfig.extractors, record.threadId ?? void 0, reflectResult.extractedValues);
@@ -27424,7 +27520,8 @@ var ObservationalMemory = class ObservationalMemory {
 			resolveModel: (inputTokens) => this.resolveObservationModel(inputTokens),
 			tokenCounter: this.tokenCounter,
 			mastra: config.mastra,
-			memory: this.memory
+			memory: this.memory,
+			hooks: this.hooks
 		});
 		this.buffering = new BufferingCoordinator({
 			observationConfig: this.observationConfig,
@@ -27445,7 +27542,8 @@ var ObservationalMemory = class ObservationalMemory {
 			resolveModel: (inputTokens) => this.resolveReflectionModel(inputTokens),
 			mastra: config.mastra,
 			memory: this.memory,
-			onReflectionCommitted: config.onReflectionCommitted
+			onReflectionCommitted: config.onReflectionCommitted,
+			hooks: this.hooks
 		});
 		this.validateBufferConfig();
 		omDebug(`[OM:init] new ObservationalMemory instance created — scope=${this.scope}, messageTokens=${JSON.stringify(this.observationConfig.messageTokens)}, obsAsyncEnabled=${this.buffering.isAsyncObservationEnabled()}, bufferTokens=${this.observationConfig.bufferTokens}, bufferActivation=${this.observationConfig.bufferActivation}, blockAfter=${this.observationConfig.blockAfter}, reflectionTokens=${this.reflectionConfig.observationTokens}, refAsyncEnabled=${this.buffering.isAsyncReflectionEnabled()}, refAsyncActivation=${this.reflectionConfig.bufferActivation}, refBlockAfter=${this.reflectionConfig.blockAfter}`);
@@ -28301,7 +28399,8 @@ ${formattedMessages}
 			startedAt,
 			writer,
 			requestContext,
-			observabilityContext
+			observabilityContext,
+			trigger: "async-buffer"
 		}).run());
 		const maxTs = this.getMaxMessageTimestamp(messagesToBuffer);
 		const cursor = new Date(maxTs.getTime() + 1);
@@ -28922,7 +29021,8 @@ ${formattedMessages}
 				sendStateSignal: opts.sendStateSignal,
 				requestContext,
 				currentModel: opts.currentModel,
-				observabilityContext
+				observabilityContext,
+				trigger: "async-buffer"
 			}).run());
 			if (isOmReproCaptureEnabled()) writeObserverExchangeReproCapture({
 				threadId,
@@ -29236,10 +29336,11 @@ ${formattedMessages}
 	async observe(opts) {
 		const { threadId, resourceId, messages, requestContext } = opts;
 		const lockKey = this.buffering.getLockKey(threadId, resourceId);
+		const trigger = opts.trigger ?? "manual";
 		const hooks = this.composeHooks(opts.hooks, {
 			threadId,
 			resourceId,
-			trigger: opts.trigger ?? "manual"
+			trigger
 		});
 		const reflectionHooks = hooks ? {
 			onReflectionStart: hooks.onReflectionStart,
@@ -29270,6 +29371,7 @@ ${formattedMessages}
 					messages: unobservedMessages,
 					messageList: opts.messageList,
 					reflectionHooks,
+					trigger,
 					agent: opts.agent,
 					sendSignal: opts.sendSignal,
 					sendStateSignal: opts.sendStateSignal,
@@ -29336,11 +29438,12 @@ ${formattedMessages}
 		}
 		await this.storage.setReflectingFlag(record.id, true);
 		registerOp(record.id, "reflecting");
-		const hooks = this.composeHooks(void 0, {
+		const hookContext = {
 			threadId,
 			resourceId,
 			trigger: "manual"
-		});
+		};
+		const hooks = this.composeHooks(void 0, hookContext);
 		let reflectionUsage;
 		let reflectionProviderMetadata;
 		let reflectionError;
@@ -29357,7 +29460,8 @@ ${formattedMessages}
 			const previousOmMetadata = (0, _mastra_core_memory.getThreadOMMetadata)(thread?.metadata);
 			const priorExtractedValues = getPriorExtractedValues(previousOmMetadata, this.reflectionConfig.extractors);
 			const reflectThreshold = getMaxThreshold(this.getEffectiveReflectionTokens(record));
-			const reflectResult = await this.reflector.call(record.activeObservations, prompt, void 0, reflectThreshold, void 0, void 0, void 0, requestContext, priorExtractedValues, observabilityContext, void 0);
+			const reflectResult = await this.reflector.call(await applyTextTransform(this.hooks, "beforeReflection", record.activeObservations, hookContext), prompt, void 0, reflectThreshold, void 0, void 0, void 0, requestContext, priorExtractedValues, observabilityContext, void 0);
+			reflectResult.observations = await applyTextTransform(this.hooks, "afterReflection", reflectResult.observations, hookContext);
 			const reflectionTokenCount = this.tokenCounter.countObservations(reflectResult.observations);
 			await this.storage.createReflectionGeneration({
 				currentRecord: record,
@@ -30255,7 +30359,7 @@ var Memory = class Memory extends _mastra_core_memory.MastraMemory {
 		});
 	}
 	async recall(args) {
-		const { threadId, resourceId, perPage: perPageArg, page, orderBy, threadConfig, vectorSearchString, includeSystemReminders, filter } = args;
+		const { threadId, resourceId, perPage: perPageArg, page, orderBy, threadConfig, vectorSearchString, includeSystemReminders, filter, includeTotal } = args;
 		const config = this.getMergedThreadConfig(threadConfig || {});
 		const semanticRecallEnabled = Boolean(config.semanticRecall);
 		const span = this.createMemorySpan("recall", args.observabilityContext, {
@@ -30342,6 +30446,7 @@ var Memory = class Memory extends _mastra_core_memory.MastraMemory {
 				page,
 				orderBy: effectiveOrderBy,
 				filter,
+				...includeTotal !== void 0 ? { includeTotal } : {},
 				...filteredVectorResults?.length ? { include: filteredVectorResults.map((r) => ({
 					id: r.metadata?.message_id,
 					threadId: r.metadata?.thread_id,
@@ -30954,6 +31059,7 @@ ${workingMemory}`;
 							direction: "ASC"
 						},
 						perPage: false,
+						includeTotal: false,
 						filter: dateFilter
 					})).messages;
 				};
@@ -30967,6 +31073,7 @@ ${workingMemory}`;
 							direction: "ASC"
 						},
 						perPage: false,
+						includeTotal: false,
 						filter: dateFilter
 					})).messages;
 				};
@@ -30982,7 +31089,8 @@ ${workingMemory}`;
 					field: "createdAt",
 					direction: "DESC"
 				},
-				perPage: typeof lastMessages === "number" ? lastMessages : void 0
+				perPage: typeof lastMessages === "number" ? lastMessages : void 0,
+				includeTotal: false
 			})).messages.reverse();
 		}
 		return {
@@ -31344,7 +31452,8 @@ Notes:
 				threadId,
 				resourceId,
 				perPage: SUMMARIZE_THREAD_DEFAULTS.pageSize,
-				page
+				page,
+				includeTotal: false
 			});
 			if (batch.length === 0) break;
 			let reachedLimit = false;
@@ -32276,4 +32385,4 @@ Object.defineProperty(exports, "wrapInObservationGroup", {
 	}
 });
 
-//# sourceMappingURL=src-D4Wm6M4v.cjs.map
+//# sourceMappingURL=src-CG7RR0Ep.cjs.map