@mastra/memory 1.27.0-alpha.3 → 1.28.0-alpha.2

package/CHANGELOG.md

@@ -1,5 +1,118 @@
 # @mastra/memory
 
+## 1.28.0-alpha.2
+
+### Patch Changes
+
+- Observational memory now detects observer/reflector output where a multi-line block repeats many times (a model repetition loop). Previously such output could slip past the degenerate-output check and balloon stored observations, causing constant synchronous reflection churn; it is now rejected and retried like other degenerate output. ([#22072](https://github.com/mastra-ai/mastra/pull/22072))
+
+- Fixed observational memory reflection to keep retrying with stronger compression when a result remains above the token threshold. ([#22232](https://github.com/mastra-ai/mastra/pull/22232))
+
+- Updated dependencies [[`ae8790c`](https://github.com/mastra-ai/mastra/commit/ae8790c4bfaa088d2ab279d1dcc06f326b9fd109), [`04a815f`](https://github.com/mastra-ai/mastra/commit/04a815fc8971d29e97fcdcc5008a1eb472fc00ff), [`cced745`](https://github.com/mastra-ai/mastra/commit/cced745a056ec2225c5bc702e32d848847aa8b65)]:
+  - @mastra/core@1.62.0-alpha.7
+
+## 1.28.0-alpha.1
+
+### Minor Changes
+
+- Added opt-in awaited Observational Memory hooks for synchronous cycles. ([#22147](https://github.com/mastra-ai/mastra/pull/22147))
+
+  Set `hookExecution: "await"` to await lifecycle hooks, stop the observer or reflector when a start hook fails, and receive one paired end callback after cleanup. Async-buffer cycles remain fire-and-forget.
+
+  ```ts
+  const memory = new Memory({
+    options: {
+      observationalMemory: {
+        hookExecution: 'await',
+        hooks: {
+          onObservationStart: async context => {
+            await authorizeObservation(context);
+          },
+        },
+      },
+    },
+  });
+  ```
+
+### Patch Changes
+
+- Updated dependencies [[`65edab1`](https://github.com/mastra-ai/mastra/commit/65edab1c233d17b8f163bad12fca410d0e6f16b1), [`ab20a38`](https://github.com/mastra-ai/mastra/commit/ab20a38d0275f8d85e0f3833bd87ef487bcc609f), [`dbbfeb8`](https://github.com/mastra-ai/mastra/commit/dbbfeb85ec949dc9ebc0755e1ad262e4f5eba8db), [`3cc9d00`](https://github.com/mastra-ai/mastra/commit/3cc9d00b2b4333e0377a5e9df5eff92c17ce7630), [`733a537`](https://github.com/mastra-ai/mastra/commit/733a537489a858b5880b2e98809334fba895a221), [`9207dfa`](https://github.com/mastra-ai/mastra/commit/9207dfab8062e5fc68b751684797ff86fe0b4e70), [`12c61d2`](https://github.com/mastra-ai/mastra/commit/12c61d280c8cb208bc3c8dbcbe5dcc60cf9d1cd0), [`9a12ef3`](https://github.com/mastra-ai/mastra/commit/9a12ef3fccf3f4186db0f294f4ee1f02cf4d8db2)]:
+  - @mastra/core@1.62.0-alpha.5
+
+## 1.27.1-alpha.0
+
+### Patch Changes
+
+- Fixed Observational Memory tracing spans (`om.observer`, `om.observer.multi-thread`, `om.reflector`) never being ended. Unended spans kept their traces retained in exporters that hold a trace open until every span in it finishes — a memory leak with the Datadog bridge, which retains full LLM Observability payloads — and meant Observational Memory tracing never reached any exporter. The spans now end when the observer/reflector run completes, and record the error before ending when it fails. ([#22117](https://github.com/mastra-ai/mastra/pull/22117))
+
+- Improved agent turn latency by reusing run-scoped memory reads ([#22076](https://github.com/mastra-ai/mastra/pull/22076))
+
+- Updated dependencies [[`2c85f42`](https://github.com/mastra-ai/mastra/commit/2c85f428e04ccd63ea31a7ec80b5b327afdad555), [`11bbeb9`](https://github.com/mastra-ai/mastra/commit/11bbeb9b108ef2264e05acefc6dafb9cbb342921), [`1a485f3`](https://github.com/mastra-ai/mastra/commit/1a485f3538f5ec64d58bd8b5e1e99de0c695c87b), [`0d37487`](https://github.com/mastra-ai/mastra/commit/0d37487d9f349388a3f1cef6a536cf9dcc4b6273), [`8661d7d`](https://github.com/mastra-ai/mastra/commit/8661d7d7179f0a024456aabdd8679bcecd09ac28), [`575e343`](https://github.com/mastra-ai/mastra/commit/575e343900451021d96110916497d334af7bc252), [`cacb839`](https://github.com/mastra-ai/mastra/commit/cacb8392d9e74189b56d857290b0615f98a2683d), [`b47b26e`](https://github.com/mastra-ai/mastra/commit/b47b26e6fe95cb8a3482be2c5e52de157fe59d0b), [`0d37487`](https://github.com/mastra-ai/mastra/commit/0d37487d9f349388a3f1cef6a536cf9dcc4b6273), [`c46eb09`](https://github.com/mastra-ai/mastra/commit/c46eb09ce4987509af57a0ac582c61241a6dd2f1), [`30ed33e`](https://github.com/mastra-ai/mastra/commit/30ed33ee14084a26019aba15fceadda6d6ddefaf), [`91ad69d`](https://github.com/mastra-ai/mastra/commit/91ad69d64994c89199b0c55399e64ed91c61df2f), [`8dc408d`](https://github.com/mastra-ai/mastra/commit/8dc408d34438f9e13297f792c11a5cfd6cf952e1), [`c92def1`](https://github.com/mastra-ai/mastra/commit/c92def10a13c822972c96f0a4ca6ffc1f4258aed), [`c5eaec5`](https://github.com/mastra-ai/mastra/commit/c5eaec5a860d80d0e3805e67db0414b87ac8cbed), [`e66b2ba`](https://github.com/mastra-ai/mastra/commit/e66b2ba100db63eaeab6e21e1ea34b113f2ec781)]:
+  - @mastra/core@1.62.0-alpha.3
+
+## 1.27.0
+
+### Minor Changes
+
+- Added `continuationHints` to observational memory configuration, so an agent that drives its ([#20665](https://github.com/mastra-ai/mastra/pull/20665))
+  own control flow can stop memory from proposing what it says next.
+
+  `<current-task>` and `<suggested-response>` were always requested and there was no way to turn
+  them off. A `<suggested-response>` is injected into the agent's context and the continuation
+  reminder tells the agent to follow it, which makes memory a second controller competing with
+  the agent's own. Pass `false` to disable both sections, or an object to disable them
+  individually — keeping `<current-task>` while dropping `<suggested-response>` is the common
+  case.
+
+  ```ts
+  import { Memory } from '@mastra/memory';
+
+  const memory = new Memory({
+    options: {
+      observationalMemory: {
+        observation: { continuationHints: { suggestedResponse: false } },
+        reflection: { continuationHints: false },
+      },
+    },
+  });
+  ```
+
+  Disabling a section removes it fully: the Observer and Reflector no longer describe or
+  reference it, and a previously stored hint stops being injected into the agent's context once
+  both observation and reflection disable it.
+
+  Defaults are unchanged — existing configurations keep both sections enabled.
+
+- Added foundational support for an upcoming experimental memory capability across storage, runtime, and developer tooling. ([#19538](https://github.com/mastra-ai/mastra/pull/19538))
+
+### Patch Changes
+
+- Added `settled()` to the base memory class. Memory implementations can do work in the background after an agent run returns, and this gives callers a way to wait for it before closing a storage connection they own. The default implementation does nothing; `@mastra/memory` overrides it. ([#21708](https://github.com/mastra-ai/mastra/pull/21708))
+
+- Added `memory.settled()`, which waits for background memory work to finish. Observational memory runs observation and reflection cycles in the background after an agent run returns, and those cycles kept writing to the database after callers had closed their storage connection. Await `memory.settled()` before closing a store you own. Fixed the observational memory reflector repeating compression attempts that could not succeed: it now stops as soon as an attempt returns the same result as the previous one, instead of always working through the full retry ladder. This cuts the model calls and database statements a single reflection produces. Fixes #21617 ([#21708](https://github.com/mastra-ai/mastra/pull/21708))
+
+- Restored the Studio memory bar token counts after a reload by reading them from the stored observational memory record. ([#21604](https://github.com/mastra-ai/mastra/pull/21604))
+
+- Log discarded degenerate observer/reflector output so failures are diagnosable. When observational memory's degenerate-repetition detector trips, the raw model output was previously thrown away — the error "Observer produced degenerate output after retry" gave no way to tell a real repetition loop apart from a detector false-positive on legitimately repetitive content. Detection sites now log bounded diagnostics (length, duplicate-window ratio, most-repeated window, head/tail snippets) to the OM debug log, and the thrown observer errors include a compact version of the same diagnostics. ([#21807](https://github.com/mastra-ai/mastra/pull/21807))
+
+- Fixed schema-based working memory so that `null` consistently deletes a field. Previously, a `null` only removed a field that already existed: on the very first write, or inside a nested object created for the first time, the `null` was stored literally. This mattered because strict-mode model providers pad every field they are not updating with `null`, so a first write could be saved as `{ "role": null }`. Working memory updates are also no longer stored by reference to the object passed in. ([#21687](https://github.com/mastra-ai/mastra/pull/21687))
+
+- Fixed `MockMemory` so its working memory merge keeps parity with `@mastra/memory`: a `null` now deletes a field on the first write and inside newly created nested objects, instead of being stored literally. ([#21687](https://github.com/mastra-ai/mastra/pull/21687))
+
+- Fixed observational memory removing Markdown link labels from the observation ([#20665](https://github.com/mastra-ai/mastra/pull/20665))
+  context given to agents. Links shared in observations previously collapsed to
+  bare, unlabelled URLs; their label text is now preserved. Semantic tags are
+  still stripped and collapsed-item markers behave as before.
+
+- Improved observational memory step latency by reusing loaded records and token counts across repeated status checks. ([#21562](https://github.com/mastra-ai/mastra/pull/21562))
+
+- Fixed observational memory status updates so they remain available to live clients without creating standalone messages in stored conversation history. ([#21604](https://github.com/mastra-ai/mastra/pull/21604))
+
+- Added regression coverage for resource-scoped observational memory: context loaded from a resource's other threads is accepted on the current thread, keeps its original thread ID, and is never re-saved onto the current thread. ([#21702](https://github.com/mastra-ai/mastra/pull/21702))
+
+- Updated dependencies [[`587f6ef`](https://github.com/mastra-ai/mastra/commit/587f6efcfc25880b93760a8607d1cd381ec612fe), [`7e096f0`](https://github.com/mastra-ai/mastra/commit/7e096f02f0dddbf09b85d306458351245ed2f886), [`d7e6745`](https://github.com/mastra-ai/mastra/commit/d7e67456954863c55440ea9c49bc6ceb9949972d), [`6223446`](https://github.com/mastra-ai/mastra/commit/6223446ddce6166e96e0ba5e00d628b615dee8ca), [`15101bb`](https://github.com/mastra-ai/mastra/commit/15101bb53c0d934f31af6b8813b88191e382a5e5), [`4e7a421`](https://github.com/mastra-ai/mastra/commit/4e7a421dce8a48742f785d1e93ad2f43a572b282), [`c2c3deb`](https://github.com/mastra-ai/mastra/commit/c2c3debcf670c7082d0a5e553aa99818a864698c), [`d8308a2`](https://github.com/mastra-ai/mastra/commit/d8308a2be3c07e777393d1017a381dcae3890d30), [`b0a2a07`](https://github.com/mastra-ai/mastra/commit/b0a2a07800d42bd9823292e7db832374ed084c9c), [`74e5bd3`](https://github.com/mastra-ai/mastra/commit/74e5bd315b8b3a1e04cb6cf480bb0f5fc4951dc8), [`242e324`](https://github.com/mastra-ai/mastra/commit/242e3241e73cbd5c9bb86a31ebb49ca0256488d4), [`217e967`](https://github.com/mastra-ai/mastra/commit/217e9672d8b3160eb729d8e9f0044949e88da239), [`d774e89`](https://github.com/mastra-ai/mastra/commit/d774e8930c781df8c9effe3763e6b501c099b6cc), [`9c27a53`](https://github.com/mastra-ai/mastra/commit/9c27a53cd9d3de4f3f025bc387d94ce371c33f95), [`8f0a332`](https://github.com/mastra-ai/mastra/commit/8f0a3321bf180368d76fe7b36aa1a8f60f00b6de), [`0b4f108`](https://github.com/mastra-ai/mastra/commit/0b4f1089aa8d92e67c2a8e99726822c5ee410784), [`9acb50f`](https://github.com/mastra-ai/mastra/commit/9acb50f71cec9c362f06820033f90ae6b1f8282f), [`46e9e3f`](https://github.com/mastra-ai/mastra/commit/46e9e3f73babe1bc70080a596cf2ac0b9da48519), [`3f9a190`](https://github.com/mastra-ai/mastra/commit/3f9a19057c027155867b9317294ee4ca7bd0581a), [`dff25a1`](https://github.com/mastra-ai/mastra/commit/dff25a1103fa72ee082a9b6f805ebeb5ce400753), [`6db7a5d`](https://github.com/mastra-ai/mastra/commit/6db7a5dd3dd2b6f7ef75dcd804fcffef5fa83963), [`217e967`](https://github.com/mastra-ai/mastra/commit/217e9672d8b3160eb729d8e9f0044949e88da239), [`583e235`](https://github.com/mastra-ai/mastra/commit/583e23519c13af16c1746f9c49722d011216611b), [`b098de9`](https://github.com/mastra-ai/mastra/commit/b098de9d7cb9f672e0883a5c716465a3a689693d), [`e8808e3`](https://github.com/mastra-ai/mastra/commit/e8808e3d8eb585a2565be53e56a7e0e1477352a4), [`a77f8d4`](https://github.com/mastra-ai/mastra/commit/a77f8d4740d2178a74c41e4bf678b4fcd8fa0bb2), [`7f78585`](https://github.com/mastra-ai/mastra/commit/7f785857e401570e2ffb316911f126ed363aa537), [`33374ba`](https://github.com/mastra-ai/mastra/commit/33374ba359e4fb13eaa918ae925fe167a3c55414), [`940bf5c`](https://github.com/mastra-ai/mastra/commit/940bf5ccf04f2c9ebd8a1390431733222a03b1cd), [`c549e2f`](https://github.com/mastra-ai/mastra/commit/c549e2f40edc1cac5d9e74e82f90da22b48df084), [`58c43d3`](https://github.com/mastra-ai/mastra/commit/58c43d3f7cb2eeaeb8ac733ae71dde822348e588), [`ef6e295`](https://github.com/mastra-ai/mastra/commit/ef6e295b59bc25a5b61b633a89c97bcfce9fb465), [`208e1b3`](https://github.com/mastra-ai/mastra/commit/208e1b39f30f4b386e494394e9d71d96f0f90241), [`c938d34`](https://github.com/mastra-ai/mastra/commit/c938d34739936c8ecbabd67ad6a4a4396f41c4c6), [`88ddc7c`](https://github.com/mastra-ai/mastra/commit/88ddc7ce01d40175f13a3228b789a906779680bd), [`f2a4afd`](https://github.com/mastra-ai/mastra/commit/f2a4afd7e37e809669001ed17724b341a5c1f45e), [`d438148`](https://github.com/mastra-ai/mastra/commit/d438148e222c1e2fb3c652725ce75680962ebec4), [`ba05fe0`](https://github.com/mastra-ai/mastra/commit/ba05fe0738f70cb686777546e968237d09269142), [`40d358e`](https://github.com/mastra-ai/mastra/commit/40d358e29d55543803e64b49241122f598ffabc7), [`d26a8d4`](https://github.com/mastra-ai/mastra/commit/d26a8d4281f28414715b333c85bedaf70d0b2890), [`e80cd7e`](https://github.com/mastra-ai/mastra/commit/e80cd7e7683e7d732e1cc6784bcac1d2640d2ce3), [`ccbbcd9`](https://github.com/mastra-ai/mastra/commit/ccbbcd974eedff4367a54ed0e24c9ee742ab2f61), [`1d9a0ea`](https://github.com/mastra-ai/mastra/commit/1d9a0ea4a9901baee6cd56737243bd6d1f631ac0), [`677cdc6`](https://github.com/mastra-ai/mastra/commit/677cdc6af564dec29a13464d12b7ab2a4efc22e9), [`c549e2f`](https://github.com/mastra-ai/mastra/commit/c549e2f40edc1cac5d9e74e82f90da22b48df084), [`a7dd322`](https://github.com/mastra-ai/mastra/commit/a7dd32247d95afc539f483ca37f4594af0387f59), [`3f5c6f7`](https://github.com/mastra-ai/mastra/commit/3f5c6f728ea35da344248de9aa070f12849f3aa0), [`a318490`](https://github.com/mastra-ai/mastra/commit/a318490e17da32f338d50929c770d901a9b3dd72), [`b860493`](https://github.com/mastra-ai/mastra/commit/b86049391100e665d579f700c8a2034c036defc3), [`d4be8c1`](https://github.com/mastra-ai/mastra/commit/d4be8c1739d22d621e3f78790e1dd5eb5ecc3589), [`a5d2eb1`](https://github.com/mastra-ai/mastra/commit/a5d2eb10347eade1ae2816d88f466c25186c54a5), [`3667679`](https://github.com/mastra-ai/mastra/commit/3667679db057edfb086846d13369fdda4902ad65), [`49696e8`](https://github.com/mastra-ai/mastra/commit/49696e8e42f870674a0a58f5abcd22cc54dd2864), [`2ef2f23`](https://github.com/mastra-ai/mastra/commit/2ef2f230a7aed342e7dc3b2000cd42e4c43e08a7), [`763e0c6`](https://github.com/mastra-ai/mastra/commit/763e0c61e04d76ad9a9efd301aa57525ca0cbea9), [`20504b2`](https://github.com/mastra-ai/mastra/commit/20504b2ecebd0e077acda3d457ab57480a98ed3e), [`77e6b1b`](https://github.com/mastra-ai/mastra/commit/77e6b1bc4c46ce94fe501023fb4393c812ec6be3), [`c5f964d`](https://github.com/mastra-ai/mastra/commit/c5f964d3f77064e978f8066ec506eed77ba5c63c), [`23e0be2`](https://github.com/mastra-ai/mastra/commit/23e0be261381e49534b4ff3101c60ee64a946cbf), [`7fc8806`](https://github.com/mastra-ai/mastra/commit/7fc880627d3cbf995d31ea0e8b807bf15417e651), [`0e02eac`](https://github.com/mastra-ai/mastra/commit/0e02eacdb2e30e1697a41910b41163742a181dc1), [`4df174c`](https://github.com/mastra-ai/mastra/commit/4df174c32bddf093a82f273070b8380aef7c9e90), [`f7c25b5`](https://github.com/mastra-ai/mastra/commit/f7c25b5106ddfb48e591f98df7a51e0f2dd01dba), [`7aad631`](https://github.com/mastra-ai/mastra/commit/7aad631b43bc10db77d5b8c66b200d7a49d18bf2), [`512100a`](https://github.com/mastra-ai/mastra/commit/512100a7d8b7e9c920f2590c6b3612f5de0d3cff), [`e81744c`](https://github.com/mastra-ai/mastra/commit/e81744cd13c46619c142dc521dc0baac47607a84), [`f8f653f`](https://github.com/mastra-ai/mastra/commit/f8f653f10980d01a73706cc3c8689ca5e40ce808), [`dc09cc1`](https://github.com/mastra-ai/mastra/commit/dc09cc1083d861cde192c1cd235324dc75b8c731), [`9ef432b`](https://github.com/mastra-ai/mastra/commit/9ef432b6faa534b57b0d182a610e13dd9a7123ff), [`36b4649`](https://github.com/mastra-ai/mastra/commit/36b4649045a3a380cbab8ceca866db4086223aff), [`b9cf308`](https://github.com/mastra-ai/mastra/commit/b9cf30846f97f99ac1906ee8a68f4f2d117b0378), [`2e1d098`](https://github.com/mastra-ai/mastra/commit/2e1d0984e325fd319d32ea182f596b3170be3847), [`377eb81`](https://github.com/mastra-ai/mastra/commit/377eb81ce43b964e3a6b541df172da74a8ff3716), [`1794a79`](https://github.com/mastra-ai/mastra/commit/1794a79178c418004a7261b1ad9114066f7ef01d), [`0cdc5dc`](https://github.com/mastra-ai/mastra/commit/0cdc5dc69024957815da4f51acc4119eb4f447d7), [`5740ec6`](https://github.com/mastra-ai/mastra/commit/5740ec60c760ffdfbfaa59d603d03b847c864e05)]:
+  - @mastra/core@1.60.0
+
 ## 1.27.0-alpha.3
 
 ### Minor 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.27.0-alpha.3"
+  version: "1.28.0-alpha.2"
 ---
 
 ## When to use
@@ -19,6 +19,7 @@ Read the individual reference documents for detailed explanations and code examp
 - [Human-in-the-loop](references/docs-agents-human-in-the-loop.md) - Learn how to require approvals and suspend tool execution, plus automatically resume suspended tools while keeping humans in control of agent workflows.
 - [Agent networks](references/docs-agents-networks.md) - Coordinate multiple agents, workflows, and tools using agent networks for complex, non-deterministic task execution.
 - [Evals with memory](references/docs-evals-evals-with-memory.md) - Run scorers against memory-enabled agents, including observational memory in thread scope, using runEvals and dataset experiments.
+- [Context engineering](references/docs-guides-context-engineering.md) - Learn how to choose, retrieve, persist, and control the context a Mastra agent receives.
 - [Background tasks](references/docs-harness-background-tasks.md) - Learn how to dispatch long-running tool calls in the background and keep the stream open until they complete, plus orchestrate subagents asynchronously.
 - [Goals](references/docs-harness-goals.md) - Learn how to set a durable objective on an agent that's judged in the execution loop, so the agent keeps working until the goal is complete or the run budget is exhausted.
 - [Memory processors](references/docs-memory-memory-processors.md) - Learn how to use memory processors in Mastra to filter, trim, and transform messages before they're sent to the language model to manage context window limits.
@@ -42,6 +43,7 @@ Read the individual reference documents for detailed explanations and code examp
 - [PostgreSQL](references/integrations-databases-postgresql.md) - Documentation for the PostgreSQL storage implementation in Mastra.
 - [Redis](references/integrations-databases-redis.md) - Documentation for the Redis storage implementation in Mastra.
 - [Upstash](references/integrations-databases-upstash.md) - Documentation for the Upstash storage implementation in Mastra.
+- [Valkey](references/integrations-databases-valkey.md) - Documentation for the GLIDE-backed Valkey storage implementation in Mastra.
 
 ### Reference
 
@@ -62,7 +64,7 @@ Read the individual reference documents for detailed explanations and code examp
 - [Memory](references/reference-migrations-upgrade-to-v1-memory.md) - Learn how to migrate memory-related changes when upgrading to v1.
 - [Reference: TokenLimiterProcessor](references/reference-processors-token-limiter-processor.md) - Documentation for the TokenLimiterProcessor in Mastra, which limits the number of tokens in messages.
 - [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: MongoDB vector store](references/reference-vectors-mongodb.md) - Documentation for the MongoDBVector class in Mastra, which provides vector search using MongoDB Atlas and 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.27.0-alpha.3",
+  "version": "1.28.0-alpha.2",
   "package": "@mastra/memory",
   "exports": {},
   "modules": {

package/dist/docs/references/docs-guides-context-engineering.md

@@ -0,0 +1,297 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# Context engineering
+
+A model can only work with the information available in its context window. That might include the current conversation, remembered details, application data, tool results, or relevant passages from a knowledge base.
+
+Context engineering is the practice of deciding what information the model should see and when. The goal isn't to provide as much as possible, but to keep the context relevant and current. Too little context leaves the model without information it needs; too much can make important details harder to find, increase cost, and reduce the quality of the response long before the model reaches its context limit.
+
+Mastra provides different ways to bring information into context, keep it available over time, retrieve it when needed, and reduce or isolate it as a task grows. This guide explains when to use each mechanism and how they fit together.
+
+| Need                                      | Start with                                    | What the model sees                                      |
+| ----------------------------------------- | --------------------------------------------- | -------------------------------------------------------- |
+| Stable identity, rules, or constraints    | [Instructions](#instructions)                 | System context on each model call                        |
+| Data from a database or API               | [Tools](#tools)                               | Tool definitions followed by selected results            |
+| Current customer or application data      | [Inline context](#inline-context)             | Data interpolated into the user message                  |
+| A large, stable knowledge base            | [RAG](#rag)                                   | Semantically relevant chunks from an index               |
+| User- or organization-managed documents   | [Filesystems](#filesystems)                   | Files selected through read or search tools              |
+| Recent conversation or durable facts      | [Memory](#memory)                             | History, observations, or retrieved memories             |
+| A long-running conversation               | [Observational Memory](#observational-memory) | Dense observations plus recent unobserved messages       |
+| New events or changing state during a run | [Signals](#signals)                           | User, reactive, notification, or state messages          |
+| Instructions needed only for some tasks   | [Dynamic skills](#dynamic-skills)             | Skill metadata followed by instructions loaded on demand |
+
+## Instructions
+
+An agent's [`instructions`](https://mastra.ai/reference/agents/agent) define its stable identity, behavior, and constraints. They're system messages and appear before conversation messages in the model request.
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+
+export const supportAgent = new Agent({
+  id: 'support-agent',
+  name: 'Support Agent',
+  instructions: `You help customers understand their account.
+    Today is ${new Date().toDateString()}.
+    Use plain language and don't invent account details.`,
+  model: 'openai/gpt-5.6-sol',
+})
+```
+
+Keep instructions focused on behavior that applies to most calls. Adding current account data, retrieved documents, or task-specific details makes the base prompt larger and harder to reuse.
+
+Instructions can also be resolved at runtime from [`RequestContext`](https://mastra.ai/docs/server/request-context):
+
+```typescript
+instructions: ({ requestContext }) => {
+  const name = requestContext.get('name')
+
+  return `You help ${name} understand their account.`
+}
+```
+
+Use `RequestContext` when instructions depend on data that changes with each request, such as the current user, tenant, locale, role, or feature flags. Values that don't come from the request, such as the current date, can be interpolated directly as shown in the first example.
+
+> **Tip:** If the resolved instructions change often, the model provider may not be able to reuse the same prompt cache prefix. Keep the stable part first, and pass frequently changing background through messages or signals instead.
+>
+> Watch [this short video on prompt caching](https://youtu.be/eBB0dBqfvuQ) to learn how cacheable prompt prefixes reduce latency and cost.
+
+## Inline context
+
+Most applications pass runtime context by interpolating relevant values into the current message. This works well when your code has already loaded customer or application data:
+
+```typescript
+const customer = await db.customer.findById(customerId)
+
+await supportAgent.generate(`
+  Customer: ${customer.name}
+  Plan: ${customer.plan}
+  Question: ${question}
+`)
+```
+
+Select and label the fields the model needs instead of serializing an entire database record. This keeps the prompt smaller and makes the meaning of each value clear.
+
+When memory is enabled, Mastra saves the current user message. Don't interpolate sensitive or temporary data that shouldn't appear in conversation history.
+
+For the less common case where background should affect one response without being saved as conversation history, pass a [`context`](https://mastra.ai/reference/agents/generate) message:
+
+```typescript
+await supportAgent.generate('Recommend the next action.', {
+  context: [{ role: 'user', content: 'The customer has an unresolved billing dispute.' }],
+})
+```
+
+The model sees this background for the current execution, but Mastra doesn't save it to memory. Use `context` when persisting the background would pollute the conversation or expose temporary application state on later turns.
+
+## Tools
+
+[Tools](https://mastra.ai/docs/agents/tools) are the recommended way to fetch current data from a database, API, or service. The model decides when it needs the data and supplies the tool arguments, while your application controls the query and returned fields.
+
+```typescript
+import { createTool } from '@mastra/core/tools'
+import { z } from 'zod'
+
+export const getCustomer = createTool({
+  id: 'get-customer',
+  description: 'Gets the current profile and plan for a customer',
+  inputSchema: z.object({ customerId: z.string() }),
+  execute: async ({ customerId }) => {
+    const customer = await db.customer.findById(customerId)
+    return { name: customer.name, plan: customer.plan, status: customer.status }
+  },
+})
+```
+
+Use [`toModelOutput`](https://mastra.ai/docs/agents/tools) when application code needs the full result but the model needs a smaller representation.
+
+## RAG
+
+[Retrieval-Augmented Generation (RAG)](https://mastra.ai/reference/rag/overview) retrieves semantically relevant chunks from an indexed corpus. It still fits large, stable knowledge bases where users ask open-ended questions that don't map cleanly to structured database queries.
+
+```typescript
+import { ModelRouterEmbeddingModel } from '@mastra/core/llm'
+import { createVectorQueryTool } from '@mastra/rag'
+
+const knowledgeBase = createVectorQueryTool({
+  vectorStoreName: 'knowledgeBase',
+  indexName: 'support-docs',
+  model: new ModelRouterEmbeddingModel('openai/text-embedding-3-small'),
+})
+```
+
+Register the vector store referenced by `vectorStoreName` on the same Mastra instance as the agent. Mastra supports [multiple vector databases](https://mastra.ai/reference/rag/vector-databases). RAG is often exposed through a tool, as in this example. The design choice is whether the agent needs semantic retrieval or can query the source directly.
+
+Many applications now start with direct, source-specific tools. Models have become better at selecting them, and a direct query is often simpler and cheaper because it doesn't require a chunking, embedding, and vector-index pipeline. Choose RAG when semantic search over unstructured content is the actual requirement, then constrain the returned context with metadata filters, reranking, and a conservative `topK`.
+
+## Filesystems
+
+A [filesystem](https://mastra.ai/docs/sandbox/filesystem) gives an agent persistent access to documents and other files. Files can live in a local directory or in providers such as Amazon S3, AgentFS, or Google Drive. The agent receives built-in tools to list, read, and search them.
+
+```typescript
+import { LocalFilesystem, Workspace } from '@mastra/core/workspace'
+
+export const workspace = new Workspace({
+  filesystem: new LocalFilesystem({ basePath: './knowledge-base' }),
+  bm25: true,
+  autoIndexPaths: ['**/*.md'],
+})
+
+// Agents receive tools including read_file, list_files, grep,
+// mastra_workspace_search, and mastra_workspace_index.
+await workspace.init()
+```
+
+[Workspace search](https://mastra.ai/docs/sandbox/search) supports BM25 keyword search, vector semantic search, or a hybrid of both. Use a filesystem for a personal assistant that works with a user's files or an organization knowledge base that teammates update in a service such as Google Drive. Search runs against the workspace index, so changed files must be indexed before the agent can retrieve their latest contents.
+
+> **Tip:** Filesystem search can also use vectors, so it overlaps with RAG. Choose a filesystem when the source of truth is a set of files that the agent may need to list, read, or update. Choose a standalone RAG pipeline when retrieval is the main requirement and the source content doesn't need to behave like files.
+
+## Memory
+
+[Memory](https://mastra.ai/docs/memory/overview) gives an agent conversational coherence across turns. It brings recent messages and remembered details into context without requiring the application to resend the full transcript on every turn.
+
+Memory requires a storage provider. Each call also identifies a `resource` that owns the memory and a `thread` that identifies the conversation. Reuse both values to continue the same conversation:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { Memory } from '@mastra/memory'
+
+export const assistant = new Agent({
+  id: 'assistant',
+  name: 'Assistant',
+  model: 'openai/gpt-5.6-sol',
+  memory: new Memory({
+    options: {
+      lastMessages: 20,
+    },
+  }),
+})
+
+await assistant.generate('Help me plan the next project milestone.', {
+  memory: {
+    resource: 'user-123',
+    thread: 'project-456',
+  },
+})
+```
+
+The example assumes storage is configured on the registered Mastra instance or directly on `Memory`. `lastMessages` controls how many recent messages Mastra loads from the thread. The default is 10.
+
+Message history works well for shorter conversations where recent turns contain the context the agent needs. For long-running conversations, Mastra recommends [Observational Memory](https://mastra.ai/docs/memory/observational-memory), which keeps recent conversation available and turns older history into a dense observation log.
+
+## Observational Memory
+
+Conversation history grows with every user message, response, and tool call. Even before it reaches the model's hard context limit, a long transcript can increase cost and make relevant details harder for the model to find. Compression replaces old, verbose history with a smaller representation.
+
+[Observational Memory](https://mastra.ai/docs/memory/observational-memory) handles this continuously. An Observer turns older messages and tool interactions into dense observations, while periodic reflection reorganizes and compresses those observations.
+
+You don't need to configure `lastMessages` when Observational Memory is enabled. Observational Memory manages history itself, keeping recent unobserved messages in context and replacing older messages with observations.
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { Memory } from '@mastra/memory'
+
+export const assistant = new Agent({
+  id: 'assistant',
+  name: 'Assistant',
+  model: 'openai/gpt-5.6-sol',
+  memory: new Memory({
+    options: {
+      observationalMemory: true,
+    },
+  }),
+})
+```
+
+After messages are observed, the model receives the observation log, recent messages that haven't been observed, and a continuation reminder. The raw messages remain stored but no longer occupy the active model context.
+
+Observations are added in stable chunks, which helps providers reuse the existing prompt prefix. Observational Memory can also activate buffered observations after a prompt cache is likely to expire or before the agent changes providers.
+
+## Signals
+
+> **Beta:** Signals may change without a major version bump until the API is stable.
+
+[Signals](https://mastra.ai/docs/harness/signals) add messages or system-generated context to a memory-backed thread. Delivery depends on the thread's state: a signal can wake an idle agent or enter an active loop. It can also wait for the next turn or persist without waking the agent.
+
+State signals require memory and an existing thread. Notification inbox signals require a storage adapter with notification support.
+
+| API                 | Use                                                                | Context behavior                                                        |
+| ------------------- | ------------------------------------------------------------------ | ----------------------------------------------------------------------- |
+| `sendMessage()`     | User input that the active agent should see now                    | Enters the active loop or wakes an idle thread                          |
+| `queueMessage()`    | User input that should wait for the next turn                      | Starts after the current run finishes                                   |
+| `sendSignal()`      | Background results, policy reminders, or external events           | Adds reactive or notification context according to its delivery options |
+| `sendStateSignal()` | Browser state, editor state, task state, or another changing value | Maintains a thread-scoped state lane with snapshots and deltas          |
+
+Use `sendSignal()` for context produced by the system rather than the user:
+
+```typescript
+const result = agent.sendSignal(
+  {
+    type: 'notification',
+    contents: 'CI failed on pull request 123: three tests failed.',
+    attributes: { source: 'github', pullRequest: 123 },
+  },
+  {
+    resourceId: 'user-123',
+    threadId: 'project-456',
+  },
+)
+
+await result.accepted
+```
+
+A processor can send a reactive signal during `processInputStep()`. This is useful for guidance that depends on the current step or a recent tool result. Set `transient: true` when the signal should reach only the current model call. Re-send it when needed instead of storing repeated reminders in conversation history.
+
+State signals represent context that changes over time. Mastra tracks snapshots and deltas for each state lane and can reinsert a fresh snapshot after the previous one leaves the active context window. Use `computeStateSignal()` when a processor owns the state. Working memory, browser context, and task lists can use this lane to stay available even after history or Observational Memory removes older messages.
+
+Signals append changing context near the current turn instead of rewriting the agent's base instructions. Transient and state signals can therefore preserve a more stable prompt prefix while keeping current guidance and state visible to the model.
+
+## Dynamic skills
+
+[Agent skills](https://mastra.ai/docs/skills) let an agent load task-specific instructions only when needed instead of carrying every procedure in its base instructions. Use them for specialized guidance that applies to some requests and keep the default context smaller.
+
+## Context control
+
+Context control limits what the model sees as a task grows. Compaction and processors reduce context within one agent, while subagent boundaries control what moves between agents.
+
+### Compaction
+
+If you've used Claude Code, you may have seen compaction happen during a long session. The Mastra team likes to joke, "Friends don't let friends do compaction."
+
+Compaction waits until a conversation reaches a token threshold. It then summarizes the transcript and replaces earlier messages. It's a blunt fallback. The compaction turn adds latency, and a single summary has to represent everything that came before. Repeated summaries can flatten chronology or lose details that later become important.
+
+Prefer [Observational Memory](#observational-memory) for long-running conversations. It can process history asynchronously in the background while preserving temporal context. Reflection revisits accumulated memories and naturally prunes details that no longer matter. Mastra doesn't provide compaction out of the box, though you could implement it with a custom [processor](https://mastra.ai/docs/agents/processors).
+
+### Processors
+
+[Processors](https://mastra.ai/docs/agents/processors) control what enters model context and can rewrite content before a model call. Use them when information should remain in stored history or application output but doesn't need to be sent back to the model on every step.
+
+For example, `ToolCallFilter` removes old tool arguments and results from the next model request without deleting those messages from storage. The model gets a smaller prompt, while your application can still display or inspect the complete interaction.
+
+Use `processInput()` or `processInputStep()` to change the active message list. Those changes may later be saved to memory. Use `processLLMRequest()` when a rewrite should apply only to the current provider call and leave memory untouched.
+
+Mastra includes several controls for common sources of context bloat:
+
+- [`toModelOutput`](https://mastra.ai/docs/agents/tools): Replace a verbose tool result with a smaller model-facing representation.
+- [`ToolCallFilter`](https://mastra.ai/reference/processors/tool-call-filter): Remove old tool calls and results from model input while retaining them in memory and the UI.
+- [`ToolSearchProcessor`](https://mastra.ai/reference/processors/tool-search-processor): Replace a large tool catalog with search and load tools.
+- [`TokenLimiter`](https://mastra.ai/reference/processors/token-limiter-processor): Prune non-system messages until the prompt fits a token budget.
+
+Start with [`toModelOutput`](https://mastra.ai/docs/agents/tools) for verbose tool results and `ToolCallFilter` for old tool interactions. Add `TokenLimiter` as a final budget guard rather than relying on the model's maximum context window.
+
+### Subagents
+
+A common source of context bloat is passing too much information to and from [subagents](https://mastra.ai/docs/subagents). A subagent gets a separate model context for its delegated task, but the boundary still needs deliberate controls.
+
+By default, Mastra forwards the parent's conversation to the subagent. Use `messageFilter` to pass only the messages that specialist needs:
+
+```typescript
+await supervisor.generate('Investigate the failed deployment.', {
+  delegation: {
+    messageFilter: ({ messages }) => messages.slice(-10),
+  },
+})
+```
+
+In the other direction, Mastra returns the subagent's text to the parent model by default while keeping nested tool calls and metadata available to application code. Leave `includeSubAgentToolResultsInModelContext` disabled unless the parent must reason over those details. Use `onDelegationStart` to refine the child prompt and `onDelegationComplete` to reduce or replace the text returned to the parent.
+
+See [Subagents](https://mastra.ai/docs/subagents) for delegation hooks, memory isolation, iteration monitoring, and result controls.

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

@@ -207,6 +207,7 @@ Each provider page includes installation instructions, configuration parameters,
 - [OracleDB](https://mastra.ai/integrations/databases/oracledb)
 - [PostgreSQL](https://mastra.ai/integrations/databases/postgresql)
 - [Redis](https://mastra.ai/integrations/databases/redis)
+- [Valkey](https://mastra.ai/integrations/databases/valkey)
 - [Upstash](https://mastra.ai/integrations/databases/upstash)
 
 ## Next steps

package/dist/docs/references/integrations-databases-mongodb.md

@@ -32,7 +32,7 @@ bun add @mastra/mongodb@latest
 
 ## Usage
 
-Ensure you have a [MongoDB Atlas Local (via Docker)](https://www.mongodb.com/docs/atlas/cli/current/atlas-cli-deploy-docker/) or [MongoDB Atlas Cloud](https://www.mongodb.com/docs/atlas/cli/current/atlas-cli-getting-started/) instance with Atlas Search enabled. MongoDB 7.0+ is recommended.
+Ensure you have a [MongoDB Atlas Local (via Docker)](https://www.mongodb.com/docs/atlas/cli/current/atlas-cli-deploy-docker/) or [MongoDB Atlas Cloud](https://www.mongodb.com/docs/atlas/cli/current/atlas-cli-getting-started/) instance with MongoDB Search enabled. MongoDB 7.0+ is recommended.
 
 ```typescript
 import { MongoDBStore } from '@mastra/mongodb'

package/dist/docs/references/integrations-databases-postgresql.md

@@ -146,6 +146,8 @@ PostgreSQL supports observability and can handle low trace volumes. Throughput c
 - Setting up table partitioning for efficient data retention
 - Migrating observability to [ClickHouse via composite storage](https://mastra.ai/reference/storage/composite) if you need to scale further
 
+`PostgresStoreVNext` uses the `event-sourced` [tracing strategy](https://mastra.ai/docs/observability/integrations/exporters/mastra-storage) instead. It writes one row when a span starts and another when it ends, never updating a row in place, and collapses those rows when a trace is read. Writes stay append-only, and traces appear in Studio while the run is still executing.
+
 ### Initialization
 
 When you pass storage to the Mastra class, `init()` is called automatically before any storage operation:

package/dist/docs/references/integrations-databases-valkey.md

@@ -0,0 +1,99 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# Valkey
+
+The Valkey storage implementation provides persistent storage and server-side caching through the [Valkey GLIDE](https://github.com/valkey-io/valkey-glide) client. Use it when your deployment runs Valkey or needs GLIDE features such as native Valkey configuration and authentication.
+
+Use [`@mastra/redis`](https://mastra.ai/integrations/databases/redis) for Redis deployments that use the official `redis` client. The packages are tested independently against their respective servers.
+
+## Installation
+
+**npm**:
+
+```bash
+npm install @mastra/valkey
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/valkey
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/valkey
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/valkey
+```
+
+## Usage
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { ValkeyStore } from '@mastra/valkey'
+
+export const mastra = new Mastra({
+  storage: new ValkeyStore({
+    id: 'valkey-storage',
+    host: 'localhost',
+    port: 6379,
+    password: process.env.VALKEY_PASSWORD,
+  }),
+})
+```
+
+You can also provide a native GLIDE configuration:
+
+```typescript
+import { ValkeyStore } from '@mastra/valkey'
+
+const storage = new ValkeyStore({
+  id: 'valkey-storage',
+  config: {
+    addresses: [{ host: 'localhost', port: 6379 }],
+    useTLS: true,
+  },
+})
+```
+
+For an existing `GlideClient`, connect it before passing it to `ValkeyStore`. The caller remains responsible for closing injected clients.
+
+## Constructor parameters
+
+**id** (`string`): Unique identifier for the storage instance.
+
+**host** (`string`): Valkey host address. Use with the direct connection fields.
+
+**port** (`number`): Valkey port. (Default: `6379`)
+
+**username** (`string`): Valkey authentication username. (Default: `default`)
+
+**password** (`string`): Valkey authentication password.
+
+**db** (`number`): Valkey database number. (Default: `0`)
+
+**useTLS** (`boolean`): Enables TLS for direct connections.
+
+**config** (`GlideClientConfiguration`): Native GLIDE standalone client configuration.
+
+**client** (`GlideClient`): Preconfigured GLIDE standalone client.
+
+**disableInit** (`boolean`): Disables automatic storage initialization.
+
+Provide exactly one connection form: `client`, `config`, or `host` with its optional direct connection fields.
+
+## Closing connections
+
+Close clients created by `ValkeyStore` during graceful shutdown:
+
+```typescript
+await storage.close()
+```
+
+`close()` doesn't close an injected `GlideClient`.