@mastra/memory 1.1.0-alpha.1 → 1.2.0-alpha.0

package/CHANGELOG.md

@@ -1,5 +1,117 @@
 # @mastra/memory
 
+## 1.2.0-alpha.0
+
+### Minor Changes
+
+- **Async buffering for observational memory is now enabled by default.** Observations are pre-computed in the background as conversations grow — when the context window fills up, buffered observations activate instantly with no blocking LLM call. This keeps agents responsive during long conversations. ([#12891](https://github.com/mastra-ai/mastra/pull/12891))
+
+  **Default settings:**
+  - `observation.bufferTokens: 0.2` — buffer every 20% of `messageTokens` (~6k tokens with the default 30k threshold)
+  - `observation.bufferActivation: 0.8` — on activation, retain 20% of the message window
+  - `reflection.bufferActivation: 0.5` — start background reflection at 50% of the observation threshold
+
+  **Disabling async buffering:**
+
+  Set `observation.bufferTokens: false` to disable async buffering for both observations and reflections:
+
+  ```ts
+  const memory = new Memory({
+    options: {
+      observationalMemory: {
+        model: 'google/gemini-2.5-flash',
+        observation: {
+          bufferTokens: false,
+        },
+      },
+    },
+  });
+  ```
+
+  **Model is now required** when passing an observational memory config object. Use `observationalMemory: true` for the default (google/gemini-2.5-flash), or set a model explicitly:
+
+  ```ts
+  // Uses default model (google/gemini-2.5-flash)
+  observationalMemory: true
+
+  // Explicit model
+  observationalMemory: {
+    model: "google/gemini-2.5-flash",
+  }
+  ```
+
+  **`shareTokenBudget` requires `bufferTokens: false`** (temporary limitation). If you use `shareTokenBudget: true`, you must explicitly disable async buffering:
+
+  ```ts
+  observationalMemory: {
+    model: "google/gemini-2.5-flash",
+    shareTokenBudget: true,
+    observation: { bufferTokens: false },
+  }
+  ```
+
+  **New streaming event:** `data-om-status` replaces `data-om-progress` with a structured status object containing active window usage, buffered observation/reflection state, and projected activation impact.
+
+  **Buffering markers:** New `data-om-buffering-start`, `data-om-buffering-end`, and `data-om-buffering-failed` streaming events for UI feedback during background operations.
+
+### Patch Changes
+
+- Fixed working memory tools being injected when no thread or resource context is provided. Made working memory tool execute scope-aware: thread-scoped requires threadId, resource-scoped requires resourceId (previously both were always required regardless of scope). ([#12831](https://github.com/mastra-ai/mastra/pull/12831))
+
+- Updated dependencies [[`717ffab`](https://github.com/mastra-ai/mastra/commit/717ffab42cfd58ff723b5c19ada4939997773004), [`e4b6dab`](https://github.com/mastra-ai/mastra/commit/e4b6dab171c5960e340b3ea3ea6da8d64d2b8672), [`5719fa8`](https://github.com/mastra-ai/mastra/commit/5719fa8880e86e8affe698ec4b3807c7e0e0a06f), [`83cda45`](https://github.com/mastra-ai/mastra/commit/83cda4523e588558466892bff8f80f631a36945a), [`11804ad`](https://github.com/mastra-ai/mastra/commit/11804adf1d6be46ebe216be40a43b39bb8b397d7), [`aa95f95`](https://github.com/mastra-ai/mastra/commit/aa95f958b186ae5c9f4219c88e268f5565c277a2), [`f5501ae`](https://github.com/mastra-ai/mastra/commit/f5501aedb0a11106c7db7e480d6eaf3971b7bda8), [`44573af`](https://github.com/mastra-ai/mastra/commit/44573afad0a4bc86f627d6cbc0207961cdcb3bc3), [`00e3861`](https://github.com/mastra-ai/mastra/commit/00e3861863fbfee78faeb1ebbdc7c0223aae13ff), [`7bfbc52`](https://github.com/mastra-ai/mastra/commit/7bfbc52a8604feb0fff2c0a082c13c0c2a3df1a2), [`1445994`](https://github.com/mastra-ai/mastra/commit/1445994aee19c9334a6a101cf7bd80ca7ed4d186), [`61f44a2`](https://github.com/mastra-ai/mastra/commit/61f44a26861c89e364f367ff40825bdb7f19df55), [`37145d2`](https://github.com/mastra-ai/mastra/commit/37145d25f99dc31f1a9105576e5452609843ce32), [`fdad759`](https://github.com/mastra-ai/mastra/commit/fdad75939ff008b27625f5ec0ce9c6915d99d9ec), [`e4569c5`](https://github.com/mastra-ai/mastra/commit/e4569c589e00c4061a686c9eb85afe1b7050b0a8), [`7309a85`](https://github.com/mastra-ai/mastra/commit/7309a85427281a8be23f4fb80ca52e18eaffd596), [`99424f6`](https://github.com/mastra-ai/mastra/commit/99424f6862ffb679c4ec6765501486034754a4c2), [`44eb452`](https://github.com/mastra-ai/mastra/commit/44eb4529b10603c279688318bebf3048543a1d61), [`6c40593`](https://github.com/mastra-ai/mastra/commit/6c40593d6d2b1b68b0c45d1a3a4c6ac5ecac3937), [`8c1135d`](https://github.com/mastra-ai/mastra/commit/8c1135dfb91b057283eae7ee11f9ec28753cc64f), [`dd39e54`](https://github.com/mastra-ai/mastra/commit/dd39e54ea34532c995b33bee6e0e808bf41a7341), [`b6fad9a`](https://github.com/mastra-ai/mastra/commit/b6fad9a602182b1cc0df47cd8c55004fa829ad61), [`4129c07`](https://github.com/mastra-ai/mastra/commit/4129c073349b5a66643fd8136ebfe9d7097cf793), [`5b930ab`](https://github.com/mastra-ai/mastra/commit/5b930aba1834d9898e8460a49d15106f31ac7c8d), [`4be93d0`](https://github.com/mastra-ai/mastra/commit/4be93d09d68e20aaf0ea3f210749422719618b5f), [`047635c`](https://github.com/mastra-ai/mastra/commit/047635ccd7861d726c62d135560c0022a5490aec), [`8c90ff4`](https://github.com/mastra-ai/mastra/commit/8c90ff4d3414e7f2a2d216ea91274644f7b29133), [`ed232d1`](https://github.com/mastra-ai/mastra/commit/ed232d1583f403925dc5ae45f7bee948cf2a182b), [`3891795`](https://github.com/mastra-ai/mastra/commit/38917953518eb4154a984ee36e6ededdcfe80f72), [`4f955b2`](https://github.com/mastra-ai/mastra/commit/4f955b20c7f66ed282ee1fd8709696fa64c4f19d), [`55a4c90`](https://github.com/mastra-ai/mastra/commit/55a4c9044ac7454349b9f6aeba0bbab5ee65d10f)]:
+  - @mastra/core@1.3.0-alpha.1
+
+## 1.1.0
+
+### Minor Changes
+
+- Added Observational Memory — a new memory system that keeps your agent's context window small while preserving long-term memory across conversations. ([#12599](https://github.com/mastra-ai/mastra/pull/12599))
+
+  **Why:** Long conversations cause context rot and waste tokens. Observational Memory compresses conversation history into observations (5–40x compression) and periodically condenses those into reflections. Your agent stays fast and focused, even after thousands of messages.
+
+  **Usage:**
+
+  ```ts
+  import { Memory } from '@mastra/memory';
+  import { PostgresStore } from '@mastra/pg';
+
+  const memory = new Memory({
+    storage: new PostgresStore({ connectionString: process.env.DATABASE_URL }),
+    options: {
+      observationalMemory: true,
+    },
+  });
+
+  const agent = new Agent({
+    name: 'my-agent',
+    model: openai('gpt-4o'),
+    memory,
+  });
+  ```
+
+  **What's new:**
+  - `observationalMemory: true` enables the three-tier memory system (recent messages → observations → reflections)
+  - Thread-scoped (per-conversation) and resource-scoped (shared across all threads for a user) modes
+  - Manual `observe()` API for triggering observation outside the normal agent loop
+  - New OM storage methods for pg, libsql, and mongodb adapters (conditionally enabled)
+  - `Agent.findProcessor()` method for looking up processors by ID
+  - `processorStates` for persisting processor state across loop iterations
+  - Abort signal propagation to processors
+  - `ProcessorStreamWriter` for custom stream events from processors
+
+- Expose token usage from embedding operations ([#12556](https://github.com/mastra-ai/mastra/pull/12556))
+  - `saveMessages` now returns `usage: { tokens: number }` with aggregated token count from all embeddings
+  - `recall` now returns `usage: { tokens: number }` from the vector search query embedding
+  - Updated abstract method signatures in `MastraMemory` to include optional `usage` in return types
+
+  This allows users to track embedding token usage when using the Memory class.
+
+### Patch Changes
+
+- Updated dependencies [[`e6fc281`](https://github.com/mastra-ai/mastra/commit/e6fc281896a3584e9e06465b356a44fe7faade65), [`97be6c8`](https://github.com/mastra-ai/mastra/commit/97be6c8963130fca8a664fcf99d7b3a38e463595), [`2770921`](https://github.com/mastra-ai/mastra/commit/2770921eec4d55a36b278d15c3a83f694e462ee5), [`b1695db`](https://github.com/mastra-ai/mastra/commit/b1695db2d7be0c329d499619c7881899649188d0), [`5fe1fe0`](https://github.com/mastra-ai/mastra/commit/5fe1fe0109faf2c87db34b725d8a4571a594f80e), [`4133d48`](https://github.com/mastra-ai/mastra/commit/4133d48eaa354cdb45920dc6265732ffbc96788d), [`abae238`](https://github.com/mastra-ai/mastra/commit/abae238c755ebaf867bbfa1a3a219ef003a1021a), [`5dd01cc`](https://github.com/mastra-ai/mastra/commit/5dd01cce68d61874aa3ecbd91ee17884cfd5aca2), [`13e0a2a`](https://github.com/mastra-ai/mastra/commit/13e0a2a2bcec01ff4d701274b3727d5e907a6a01), [`f6673b8`](https://github.com/mastra-ai/mastra/commit/f6673b893b65b7d273ad25ead42e990704cc1e17), [`cd6be8a`](https://github.com/mastra-ai/mastra/commit/cd6be8ad32741cd41cabf508355bb31b71e8a5bd), [`9eb4e8e`](https://github.com/mastra-ai/mastra/commit/9eb4e8e39efbdcfff7a40ff2ce07ce2714c65fa8), [`c987384`](https://github.com/mastra-ai/mastra/commit/c987384d6c8ca844a9701d7778f09f5a88da7f9f), [`cb8cc12`](https://github.com/mastra-ai/mastra/commit/cb8cc12bfadd526aa95a01125076f1da44e4afa7), [`aa37c84`](https://github.com/mastra-ai/mastra/commit/aa37c84d29b7db68c72517337932ef486c316275), [`62f5d50`](https://github.com/mastra-ai/mastra/commit/62f5d5043debbba497dacb7ab008fe86b38b8de3), [`47eba72`](https://github.com/mastra-ai/mastra/commit/47eba72f0397d0d14fbe324b97940c3d55e5a525)]:
+  - @mastra/core@1.2.0
+  - @mastra/schema-compat@1.1.0
+
 ## 1.1.0-alpha.1
 
 ### Minor Changes

package/dist/_types/@internal_ai-sdk-v4/dist/index.d.ts

@@ -3480,7 +3480,16 @@ export declare type JSONValue = null | string | number | boolean | {
     [value: string]: JSONValue;
 } | Array<JSONValue>;
 
-declare type JSONValue_2 = null | string | number | boolean | JSONObject | JSONArray;
+declare type JSONValue_2 = null | string | number | boolean | JSONObject | JSONArray;
+
+export declare namespace LangChainAdapter {
+    export {
+        mergeIntoDataStream$1 as mergeIntoDataStream,
+        toDataStream$1 as toDataStream,
+        toDataStreamResponse$1 as toDataStreamResponse,
+    };
+}
+
 /**
  Language model that is used by the AI SDK Core functions.
  */
@@ -4419,8 +4428,16 @@ declare interface Link {
     attributes?: SpanAttributes;
     /** Count of attributes of the link that were dropped due to collection limits */
     droppedAttributesCount?: number;
-}
-
+}
+
+export declare namespace LlamaIndexAdapter {
+    export {
+        llamaindexAdapter_mergeIntoDataStream as mergeIntoDataStream,
+        llamaindexAdapter_toDataStream as toDataStream,
+        llamaindexAdapter_toDataStreamResponse as toDataStreamResponse,
+    };
+}
+
 export declare class LoadAPIKeyError extends AISDKError {
     private readonly [symbol$6_2];
     constructor({ message }: {
@@ -4762,8 +4779,16 @@ export declare type ObjectStreamPart<PARTIAL> = {
     usage: LanguageModelUsage;
     response: LanguageModelResponseMetadata;
     providerMetadata?: ProviderMetadata;
-};
-
+};
+
+export declare namespace Output {
+    export {
+        output_Output as Output,
+        output_object as object,
+        output_text as text,
+    };
+}
+
 declare interface Output_2<OUTPUT, PARTIAL> {
     readonly type: 'object' | 'text';
     injectIntoSystemPrompt(options: {
@@ -7535,15 +7560,3 @@ export declare function zodSchema<OBJECT>(zodSchema: z.Schema<OBJECT, z.ZodTypeD
 
 export { }
 export { LanguageModelV1Message as LanguageModelV1Message, LanguageModelV1CallSettings as LanguageModelV1CallSettings, LanguageModelV1FunctionTool as LanguageModelV1FunctionTool, LanguageModelV1ProviderDefinedTool as LanguageModelV1ProviderDefinedTool, LanguageModelV1ToolChoice as LanguageModelV1ToolChoice, LanguageModelV1ObjectGenerationMode as LanguageModelV1ObjectGenerationMode, LanguageModelV1FunctionToolCall as LanguageModelV1FunctionToolCall, LanguageModelV1Source as LanguageModelV1Source, LanguageModelV1LogProbs as LanguageModelV1LogProbs, FetchFunction as FetchFunction, TextUIPart as TextUIPart, ReasoningUIPart as ReasoningUIPart, ToolInvocationUIPart as ToolInvocationUIPart, SourceUIPart as SourceUIPart, FileUIPart as FileUIPart, StepStartUIPart as StepStartUIPart, AssistantStreamPartType as AssistantStreamPartType, AssistantStreamPartValueType as AssistantStreamPartValueType, AssistantStreamString as AssistantStreamString, DataStreamPartType as DataStreamPartType, DataStreamPartValueType as DataStreamPartValueType, DeepPartialInternal as DeepPartialInternal, Validator as Validator, JSONSchema7 as JSONSchema7, LanguageModelV1FinishReason as LanguageModelV1FinishReason, LanguageModelV1CallWarning as LanguageModelV1CallWarning, JSONValue_2 as JSONValue_2, Source as Source, DataStreamString as DataStreamString, AttributeValue as AttributeValue, Tracer as Tracer, EmbeddingModelV1 as EmbeddingModelV1, EmbeddingModelV1Embedding as EmbeddingModelV1Embedding, ImageModelV1CallWarning as ImageModelV1CallWarning, TranscriptionModelV1CallWarning as TranscriptionModelV1CallWarning, SpeechModelV1CallWarning as SpeechModelV1CallWarning, ProviderOptions as ProviderOptions, ReasoningPart as ReasoningPart, RedactedReasoningPart as RedactedReasoningPart, ToolResultContent as ToolResultContent, inferParameters as inferParameters, ToolParameters as ToolParameters, JSONRPCRequestSchema as JSONRPCRequestSchema, JSONRPCResponseSchema as JSONRPCResponseSchema, JSONRPCErrorSchema as JSONRPCErrorSchema, JSONRPCNotificationSchema as JSONRPCNotificationSchema, JSONRPCMessageSchema as JSONRPCMessageSchema, MCPClientConfig as MCPClientConfig, MCPClient as MCPClient, ValueOf as ValueOf, ToToolResultObject as ToToolResultObject, ToToolsWithDefinedExecute as ToToolsWithDefinedExecute, ToToolsWithExecute as ToToolsWithExecute, ReasoningDetail as ReasoningDetail, ToolCallArray as ToolCallArray, ToolResultArray as ToolResultArray, ResponseMessage as ResponseMessage, Output_2 as Output_2, ConsumeStreamOptions as ConsumeStreamOptions, ImageModelV1 as ImageModelV1, CallSettings as CallSettings, Prompt as Prompt, StreamObjectOnErrorCallback as StreamObjectOnErrorCallback, AsyncIterableStream as AsyncIterableStream, SpeechModelV1 as SpeechModelV1, TranscriptionModelV1 as TranscriptionModelV1, LanguageModelV1ProviderMetadata as LanguageModelV1ProviderMetadata, ExtractModelId as ExtractModelId, ExtractLiteralUnion as ExtractLiteralUnion, ProviderV1 as ProviderV1, SingleRequestTextStreamPart as SingleRequestTextStreamPart, RetryErrorReason as RetryErrorReason, AssistantResponseSettings as AssistantResponseSettings, AssistantResponseCallback as AssistantResponseCallback };
-
-export namespace LangChainAdapter {
-        export { mergeIntoDataStream$1 as mergeIntoDataStream, toDataStream$1 as toDataStream, toDataStreamResponse$1 as toDataStreamResponse };
-}
-
-export namespace LlamaIndexAdapter {
-    export { llamaindexAdapter_mergeIntoDataStream as mergeIntoDataStream, llamaindexAdapter_toDataStream as toDataStream, llamaindexAdapter_toDataStreamResponse as toDataStreamResponse };
-}
-
-export namespace Output {
-    export { output_Output as Output, output_object as object, output_text as text };
-}