@mastra/oracledb 0.2.0-alpha.2 → 0.2.1-alpha.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +62 -0
- package/dist/docs/SKILL.md +2 -2
- package/dist/docs/assets/SOURCE_MAP.json +1 -1
- package/dist/docs/references/docs-memory-observational-memory.md +13 -13
- package/dist/docs/references/docs-memory-semantic-recall.md +1 -1
- package/dist/docs/references/docs-memory-working-memory.md +3 -3
- package/dist/docs/references/{docs-storage-overview.md → docs-storage.md} +9 -7
- package/dist/docs/references/reference-rag-metadata-filters.md +1 -1
- package/dist/docs/references/reference-rag-retrieval.md +26 -18
- package/dist/index.cjs +5 -1
- package/dist/index.cjs.map +1 -1
- package/dist/index.js +6 -2
- package/dist/index.js.map +1 -1
- package/dist/storage/domains/workflows/index.d.ts.map +1 -1
- package/package.json +4 -4
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,67 @@
|
|
|
1
1
|
# @mastra/oracledb
|
|
2
2
|
|
|
3
|
+
## 0.2.1-alpha.0
|
|
4
|
+
|
|
5
|
+
### Patch Changes
|
|
6
|
+
|
|
7
|
+
- Fixed concurrent resume() calls on the same suspended workflow run executing downstream steps more than once. A resume now atomically claims the run before executing anything, so only one caller continues a given suspension. Losing callers throw WORKFLOW_RESUME_ALREADY_CLAIMED without running any steps. Fixes #20443 ([#21725](https://github.com/mastra-ai/mastra/pull/21725))
|
|
8
|
+
|
|
9
|
+
- Workflow state updates now support an optional expectedStatus guard, so a status change is only applied when the stored run is in an expected state. This is what makes concurrent workflow resumes safe. ([#21725](https://github.com/mastra-ai/mastra/pull/21725))
|
|
10
|
+
|
|
11
|
+
- Resume conflicts now return 409 Conflict. When a suspended workflow run has already been resumed by another caller, the resume endpoints respond with 409 instead of a generic error. ([#21725](https://github.com/mastra-ai/mastra/pull/21725))
|
|
12
|
+
|
|
13
|
+
- Updated dependencies [[`88d14ca`](https://github.com/mastra-ai/mastra/commit/88d14cac008582a618fecc3d5c7fd3bdf4f6ddc3), [`84a5b69`](https://github.com/mastra-ai/mastra/commit/84a5b699f84d6bae0a34efe5a970d891090b9f41), [`84a5b69`](https://github.com/mastra-ai/mastra/commit/84a5b699f84d6bae0a34efe5a970d891090b9f41), [`84a5b69`](https://github.com/mastra-ai/mastra/commit/84a5b699f84d6bae0a34efe5a970d891090b9f41), [`038b7b4`](https://github.com/mastra-ai/mastra/commit/038b7b405cb4ac25ab3f3031334111b1f87ac112), [`4132d61`](https://github.com/mastra-ai/mastra/commit/4132d61f8367077120ee9e6420d3224dffd93c93)]:
|
|
14
|
+
- @mastra/core@1.60.1-alpha.0
|
|
15
|
+
|
|
16
|
+
## 0.2.0
|
|
17
|
+
|
|
18
|
+
### Minor Changes
|
|
19
|
+
|
|
20
|
+
- Added `@mastra/oracledb`, a storage and vector provider for Oracle Database 23ai+. ([#19650](https://github.com/mastra-ai/mastra/pull/19650))
|
|
21
|
+
|
|
22
|
+
**New package** with `OracleStore` (composite storage: memory, workflows, observability, scores, scorer definitions, MCP clients, agents) and `OracleVector` (Oracle 23ai+ `VECTOR` columns with exact search by default, optional IVF/HNSW indexes, and Mastra metadata filters over Oracle JSON).
|
|
23
|
+
|
|
24
|
+
```typescript
|
|
25
|
+
import { OracleStore, OracleVector } from '@mastra/oracledb';
|
|
26
|
+
|
|
27
|
+
const storage = new OracleStore({
|
|
28
|
+
id: 'oracle-store',
|
|
29
|
+
|
|
30
|
+
password: process.env.ORACLE_DATABASE_PASSWORD,
|
|
31
|
+
connectString: process.env.ORACLE_DATABASE_CONNECT_STRING,
|
|
32
|
+
});
|
|
33
|
+
|
|
34
|
+
const vector = new OracleVector({
|
|
35
|
+
id: 'oracle-vector',
|
|
36
|
+
|
|
37
|
+
password: process.env.ORACLE_DATABASE_PASSWORD,
|
|
38
|
+
connectString: process.env.ORACLE_DATABASE_CONNECT_STRING,
|
|
39
|
+
});
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
Supersedes [#18011](https://github.com/mastra-ai/mastra/pull/18011).
|
|
43
|
+
|
|
44
|
+
### Patch Changes
|
|
45
|
+
|
|
46
|
+
- Fixed a crash where updating a thread without a title (for example during observational memory buffering) could write a null title and violate the database's not-null constraint when running a newer @mastra/memory against an older storage package. Memory now checks whether the connected storage adapter supports partial thread updates and backfills the existing title for older adapters, so mixed-version deployments keep working. See #21041 for the original title-clobbering fix this makes backward compatible. ([#21257](https://github.com/mastra-ai/mastra/pull/21257))
|
|
47
|
+
|
|
48
|
+
- Storage adapters now declare support for partial thread updates, letting newer @mastra/memory preserve existing thread titles instead of overwriting them, while remaining safe against older versions. ([#21257](https://github.com/mastra-ai/mastra/pull/21257))
|
|
49
|
+
|
|
50
|
+
- Fixed generated thread titles being clobbered during a turn ([#21041](https://github.com/mastra-ai/mastra/pull/21041))
|
|
51
|
+
|
|
52
|
+
`updateThread` required both `title` and `metadata`, so callers that only needed to
|
|
53
|
+
change metadata (message persistence, working memory, observational memory, channel
|
|
54
|
+
subscriptions) had to read the thread and pass its title back. When title generation
|
|
55
|
+
finished between that read and the write, the freshly generated title was overwritten
|
|
56
|
+
with the stale one.
|
|
57
|
+
|
|
58
|
+
`title` and `metadata` are now independently optional: omitting one leaves that column
|
|
59
|
+
untouched. Callers that only change metadata no longer send a title, and message
|
|
60
|
+
persistence no longer rewrites a thread row it just read.
|
|
61
|
+
|
|
62
|
+
- Updated dependencies [[`e7109ee`](https://github.com/mastra-ai/mastra/commit/e7109ee6f731bacc79c885906f3c7dca8d8f013a), [`b8ce7ec`](https://github.com/mastra-ai/mastra/commit/b8ce7ec96e39343c6c2f36d12d68a9ad816c09f7), [`2e4624e`](https://github.com/mastra-ai/mastra/commit/2e4624edb6917e61249cb60ee377735e7af7e4a9), [`45a9147`](https://github.com/mastra-ai/mastra/commit/45a914741f578754d79d8b7de7b4e4f304d8e14a), [`a3a3624`](https://github.com/mastra-ai/mastra/commit/a3a3624f646b98e409424d8defccbd334da9e8b8), [`6246914`](https://github.com/mastra-ai/mastra/commit/62469146636911f3cbbe0880bd011c6a897a59a7), [`6445eba`](https://github.com/mastra-ai/mastra/commit/6445eba6020abac681aba1cc9289f446cb400cbe), [`86b7b77`](https://github.com/mastra-ai/mastra/commit/86b7b777980d30f66e1fd134a37d2af4c22e54cc), [`1c75e32`](https://github.com/mastra-ai/mastra/commit/1c75e32f7fc0b9fb6f548b4407feaec8a1440212), [`296dc9a`](https://github.com/mastra-ai/mastra/commit/296dc9af29f3616e786c7825ec32e0df92d754c5), [`f59032a`](https://github.com/mastra-ai/mastra/commit/f59032a73699443555a08a479e7ac578975784f2), [`cdd5c33`](https://github.com/mastra-ai/mastra/commit/cdd5c33ac6c7118a9f139e6dc0e14e6a8ae31658), [`3f73c07`](https://github.com/mastra-ai/mastra/commit/3f73c076727e8c36b4fff7a1b40290fb68957fa8), [`772c0c8`](https://github.com/mastra-ai/mastra/commit/772c0c897cec383258de2e6178147f8014767c7b), [`d7cf7fa`](https://github.com/mastra-ai/mastra/commit/d7cf7fafc1ae1b50bd8462dd0e6c671a8606db93), [`7c1ebb1`](https://github.com/mastra-ai/mastra/commit/7c1ebb15690c4b3f0eabb19077cf8af573311e57), [`0f9a448`](https://github.com/mastra-ai/mastra/commit/0f9a448502157e59f7b76f24360ad497168f5ef8), [`578bf2e`](https://github.com/mastra-ai/mastra/commit/578bf2e6a88e9d5b8bf502204e15a95dfbb679ae), [`c47165c`](https://github.com/mastra-ai/mastra/commit/c47165c983c87594c6952f1fd2fa51a90205034c), [`289f4ce`](https://github.com/mastra-ai/mastra/commit/289f4ce16e3293370440172132c52ee787cbc09f), [`df31eb0`](https://github.com/mastra-ai/mastra/commit/df31eb0c7087d782a0d9346e467f9a4af4b0eef6), [`9571e3a`](https://github.com/mastra-ai/mastra/commit/9571e3a06ed2c5220196460bf82a2129255c3a8b), [`4f16ff8`](https://github.com/mastra-ai/mastra/commit/4f16ff824bf2f9b0ddc93f210477c10c8a4fb1ab), [`b4c89b4`](https://github.com/mastra-ai/mastra/commit/b4c89b4371b0c86da57403ad1a3b3ef0681f3128), [`e6534fa`](https://github.com/mastra-ai/mastra/commit/e6534fab031216f6cb48c4c9907cbfdce9d60bc6), [`210cb7a`](https://github.com/mastra-ai/mastra/commit/210cb7a167998c7bbf72cb3b93e6eb0563330239), [`06b2d87`](https://github.com/mastra-ai/mastra/commit/06b2d87e63bcdd0ed59215c6789692b9b12de376), [`1c67d85`](https://github.com/mastra-ai/mastra/commit/1c67d85e9da8285662f4dbbf47e0378c3fee0747), [`ac01d63`](https://github.com/mastra-ai/mastra/commit/ac01d6355974aec73fdb8781449ed12bac582094), [`80a3324`](https://github.com/mastra-ai/mastra/commit/80a33245d3110204de6f56d61211523ffe338692), [`e44e8f3`](https://github.com/mastra-ai/mastra/commit/e44e8f370b66c339ddcaba946d33da6d3c3f06cd), [`d9d2881`](https://github.com/mastra-ai/mastra/commit/d9d2881ede6dd6c023d144215fc812062aed0890), [`a810a05`](https://github.com/mastra-ai/mastra/commit/a810a058f62ad407cfc1701e0be36ae91145d7cf), [`ba24be6`](https://github.com/mastra-ai/mastra/commit/ba24be662439c331ab23a600041f93803c89eca8), [`842b5fe`](https://github.com/mastra-ai/mastra/commit/842b5fe22b6a7fa811bd14e48eb9af523ac989f2), [`990611b`](https://github.com/mastra-ai/mastra/commit/990611ba76eb876d86c9c594371ae5f02f94b432), [`80bdf3a`](https://github.com/mastra-ai/mastra/commit/80bdf3ae16ade6ff63bde0cb16fa2df8ab7dd4dd), [`c967a5e`](https://github.com/mastra-ai/mastra/commit/c967a5eec150c5dc5418c4a4388982d1fb7ad27c), [`dc4a25d`](https://github.com/mastra-ai/mastra/commit/dc4a25d41af4e2fe97a816070eaec6aa963ab53b), [`9ba1247`](https://github.com/mastra-ai/mastra/commit/9ba12470c77f1c03642d720ce67e517e878f666e), [`fd96298`](https://github.com/mastra-ai/mastra/commit/fd96298a8367622f4ebfcaa97b5b6c1fbbd14564), [`66bbfb5`](https://github.com/mastra-ai/mastra/commit/66bbfb5f05b473d39f88c0e4a481ccac41634f3a), [`dc4a25d`](https://github.com/mastra-ai/mastra/commit/dc4a25d41af4e2fe97a816070eaec6aa963ab53b), [`f8da216`](https://github.com/mastra-ai/mastra/commit/f8da21633e7eb0e31c9ce0fc30567870d19416d3), [`4a09a9c`](https://github.com/mastra-ai/mastra/commit/4a09a9c0474ef643558fcb5f0edc542b82f1cab0), [`5f798b3`](https://github.com/mastra-ai/mastra/commit/5f798b3362e9bdf4d690f85245606e146eef60b9), [`6a84954`](https://github.com/mastra-ai/mastra/commit/6a84954a2667f85b6d59da652dab1bbff007ccb0), [`1e83a47`](https://github.com/mastra-ai/mastra/commit/1e83a4734ab61ba5926af6793e3569a78b72ed37), [`52d8ef0`](https://github.com/mastra-ai/mastra/commit/52d8ef03801f1deb7ee48532fc4190dd4a33916c), [`cdd5c33`](https://github.com/mastra-ai/mastra/commit/cdd5c33ac6c7118a9f139e6dc0e14e6a8ae31658), [`7fdcaa6`](https://github.com/mastra-ai/mastra/commit/7fdcaa66105d64290f9b14432a12ec99f39c4d3a), [`d6c56f9`](https://github.com/mastra-ai/mastra/commit/d6c56f951db3213330b98b0abafa9778c8770e58), [`e08e789`](https://github.com/mastra-ai/mastra/commit/e08e789c1bf4cd2fe46363f7a4728536ceccc9bd), [`bf936e2`](https://github.com/mastra-ai/mastra/commit/bf936e2c89b2ff0dad5695b873ddc009ba96d41e), [`7fb580a`](https://github.com/mastra-ai/mastra/commit/7fb580ac73fbcacf2ff00872a3395f73ae1b9fa5), [`ed5d606`](https://github.com/mastra-ai/mastra/commit/ed5d606739c5e3fbdfa9f272df7809aa5ab43b1d), [`f53d5bd`](https://github.com/mastra-ai/mastra/commit/f53d5bd4885b29e4ac29a428a6044088ea8d6aa3), [`32980a3`](https://github.com/mastra-ai/mastra/commit/32980a3e2413d0274ac244d32c37d910edc13f00), [`01a2943`](https://github.com/mastra-ai/mastra/commit/01a2943a7d886edefdff072bfa51f055bab54437), [`82e3365`](https://github.com/mastra-ai/mastra/commit/82e3365ef7c9bf7bee2e7a7029035ea262d68895), [`6104347`](https://github.com/mastra-ai/mastra/commit/61043473ba6bfd0a25156824e853e13165562e6c), [`35cc901`](https://github.com/mastra-ai/mastra/commit/35cc90102cf834a84827acaf9eee0b6d6d1e2a3b), [`a8b4cf0`](https://github.com/mastra-ai/mastra/commit/a8b4cf02823cffebc4751a53337dfacf097c1ae1), [`9571e3a`](https://github.com/mastra-ai/mastra/commit/9571e3a06ed2c5220196460bf82a2129255c3a8b), [`333785c`](https://github.com/mastra-ai/mastra/commit/333785c93cbb01e42c60167e995457c28897ddbf), [`bda2235`](https://github.com/mastra-ai/mastra/commit/bda22353ee28f2df0eaea555f7cae1549f979c0b), [`efd5c81`](https://github.com/mastra-ai/mastra/commit/efd5c81cc25fde3c2ddd86fc1178deb4ec176e19), [`1b482c2`](https://github.com/mastra-ai/mastra/commit/1b482c2d89244dd758c41e5f927a2b44041388d2), [`45bfb88`](https://github.com/mastra-ai/mastra/commit/45bfb88fd52f1dd3be20e2a38905777c96499c90), [`ff28284`](https://github.com/mastra-ai/mastra/commit/ff2828416f14daff9d956e6a352fdaa23c950979), [`4bcdfaf`](https://github.com/mastra-ai/mastra/commit/4bcdfaf0eac3199d7cb171b0a19a92c9c341eea4), [`e3b9307`](https://github.com/mastra-ai/mastra/commit/e3b9307098daefbfae2a52ae2ef51bc9fc701190), [`d6834c5`](https://github.com/mastra-ai/mastra/commit/d6834c5a7866b16734d23900163c2414ed70d791), [`f33264f`](https://github.com/mastra-ai/mastra/commit/f33264f517ae603279afd5c4251e2b40f6dd3618), [`689f2c4`](https://github.com/mastra-ai/mastra/commit/689f2c4b6c0835fe455702b01d21daa8abcd9331), [`fcd0667`](https://github.com/mastra-ai/mastra/commit/fcd0667a4e378be35c9a1b1eb19cce78fbfd7282), [`cfd0d9e`](https://github.com/mastra-ai/mastra/commit/cfd0d9ec77ec3c69dd96f79cdb579e03d79f22ce), [`acc3513`](https://github.com/mastra-ai/mastra/commit/acc3513b19f79bf0a7ec2998694580edca54086c), [`1670533`](https://github.com/mastra-ai/mastra/commit/1670533986f6bacf567746245348125e3a106448), [`a7eb4a1`](https://github.com/mastra-ai/mastra/commit/a7eb4a11450f6170274ed5141bffe821d4fdd5a6), [`0976933`](https://github.com/mastra-ai/mastra/commit/0976933142333ec78451feef265b68bcb45aa5e7), [`242b945`](https://github.com/mastra-ai/mastra/commit/242b94558777bfbdeb42cbfea84afff0b6ad0633), [`c52d346`](https://github.com/mastra-ai/mastra/commit/c52d3462ec831a5d95926ecd3d3373f5928ad2e5), [`af4636a`](https://github.com/mastra-ai/mastra/commit/af4636a74463275d71c1d13a38f7d2b738f128bf), [`01a2943`](https://github.com/mastra-ai/mastra/commit/01a2943a7d886edefdff072bfa51f055bab54437), [`2eabc09`](https://github.com/mastra-ai/mastra/commit/2eabc097d86d52fbd0123da36a7c874154cc384f), [`0023e79`](https://github.com/mastra-ai/mastra/commit/0023e7919431078280abd11c89d1edeae35fcc69), [`c2ad51e`](https://github.com/mastra-ai/mastra/commit/c2ad51e2467f901eecba8c9f4a45e22a50bd7c18), [`25ca73d`](https://github.com/mastra-ai/mastra/commit/25ca73d25dee7ce9f0ca72939e3a505c4db7257e), [`2f9ef3f`](https://github.com/mastra-ai/mastra/commit/2f9ef3f4ca06fc2dcdd5088c26b7f4da6a016791), [`e7eefcb`](https://github.com/mastra-ai/mastra/commit/e7eefcb162cda7c493e8c3bf43050ead0efbcb2c), [`fea5cae`](https://github.com/mastra-ai/mastra/commit/fea5caedc7e2cfea51784a15e015952692027abf), [`4d7aca2`](https://github.com/mastra-ai/mastra/commit/4d7aca2fe75f225c83d1502d63079568e6ec163f), [`e1cead1`](https://github.com/mastra-ai/mastra/commit/e1cead17b5f3653cf00d2f90cc19b113119c02ba), [`01a2943`](https://github.com/mastra-ai/mastra/commit/01a2943a7d886edefdff072bfa51f055bab54437), [`d9d93b2`](https://github.com/mastra-ai/mastra/commit/d9d93b25e4a65ad5fa153fa35be7ed149c8d587f), [`c4ec889`](https://github.com/mastra-ai/mastra/commit/c4ec889561c0264c43f66d04d587bee4ce35e792), [`4b59f78`](https://github.com/mastra-ai/mastra/commit/4b59f786cbc9a7d1ef07a07517dbd4b96865e99d), [`eeae63e`](https://github.com/mastra-ai/mastra/commit/eeae63e7fbe8e1f237adc69bca6e2ac13c5ca907), [`3dc97ea`](https://github.com/mastra-ai/mastra/commit/3dc97ea415fad353b48a13095fad1835933cc12a), [`94e7ae9`](https://github.com/mastra-ai/mastra/commit/94e7ae970b37c888cd1244ef013292639a2fe6d1), [`e6a2860`](https://github.com/mastra-ai/mastra/commit/e6a2860649cc51f87d32d78b766ae2126446ba07), [`7010c5d`](https://github.com/mastra-ai/mastra/commit/7010c5d15728bf9c5dfe4fb6b1bf80ce23bf143a), [`bab06b1`](https://github.com/mastra-ai/mastra/commit/bab06b18923873a584bdfc71a6b4ec7fb4727fb7), [`3d01cd3`](https://github.com/mastra-ai/mastra/commit/3d01cd387321b6f9c5cac31d487c84bf51b19c78), [`7bf3086`](https://github.com/mastra-ai/mastra/commit/7bf308663f0115ca74ad20554ade740f06640859), [`4c186a0`](https://github.com/mastra-ai/mastra/commit/4c186a017275f45e6ed4c09de0f89550e2d09e8c), [`b0fa077`](https://github.com/mastra-ai/mastra/commit/b0fa077bcbc9b08551846fe372a0d3d15b71ed72), [`0282e16`](https://github.com/mastra-ai/mastra/commit/0282e16115538c8e9b248b90f0748eb01cb5dc98), [`a8dd139`](https://github.com/mastra-ai/mastra/commit/a8dd1391a9fe9a6632c25809ef236980afa9a020), [`6a667b4`](https://github.com/mastra-ai/mastra/commit/6a667b4b7cd6a93fe41fcdd357b08c5a8c09b9ab), [`9be8878`](https://github.com/mastra-ai/mastra/commit/9be8878dcf0388e84fc4873e0eec27bd49b881a4), [`e5786be`](https://github.com/mastra-ai/mastra/commit/e5786be02bb903073082bd9d6da880ebaacc343f), [`2440e09`](https://github.com/mastra-ai/mastra/commit/2440e096ea6c2def1ccc1eb2d0f3f5b88c4af940), [`2093fbd`](https://github.com/mastra-ai/mastra/commit/2093fbd53bb744bae19ec89f6d73db9a66fbe8a7), [`a59049b`](https://github.com/mastra-ai/mastra/commit/a59049b1652a13efff66ac826326b5ed9a550342), [`7bd85ea`](https://github.com/mastra-ai/mastra/commit/7bd85ea7588b71c25ce9f4019c88f8539be5dcbc), [`83fa004`](https://github.com/mastra-ai/mastra/commit/83fa0044bfda8b703a83883dbd8bef204844d13f), [`a463cdf`](https://github.com/mastra-ai/mastra/commit/a463cdf1c95c3059e70f0bff27959e8558bb899d), [`e7a5da4`](https://github.com/mastra-ai/mastra/commit/e7a5da4ef8e4dd452d2f232961b4e682a85ffe43), [`7b4393d`](https://github.com/mastra-ai/mastra/commit/7b4393d557411fdcf07b0e30e5acaf7cc85154ae), [`0ea6b80`](https://github.com/mastra-ai/mastra/commit/0ea6b8001408ce02b56e8be0536b0fd8cbaf8ad2)]:
|
|
63
|
+
- @mastra/core@1.58.0
|
|
64
|
+
|
|
3
65
|
## 0.2.0-alpha.2
|
|
4
66
|
|
|
5
67
|
### Patch Changes
|
package/dist/docs/SKILL.md
CHANGED
|
@@ -3,7 +3,7 @@ name: mastra-oracledb
|
|
|
3
3
|
description: Documentation for @mastra/oracledb. Use when working with @mastra/oracledb APIs, configuration, or implementation.
|
|
4
4
|
metadata:
|
|
5
5
|
package: "@mastra/oracledb"
|
|
6
|
-
version: "0.2.
|
|
6
|
+
version: "0.2.1-alpha.0"
|
|
7
7
|
---
|
|
8
8
|
|
|
9
9
|
## When to use
|
|
@@ -19,7 +19,7 @@ Read the individual reference documents for detailed explanations and code examp
|
|
|
19
19
|
- [Observational Memory](references/docs-memory-observational-memory.md) - Learn how Observational Memory keeps your agent's context window small while preserving long-term memory across conversations.
|
|
20
20
|
- [Semantic recall](references/docs-memory-semantic-recall.md) - Learn how to use semantic recall in Mastra to retrieve relevant messages from past conversations using vector search and embeddings.
|
|
21
21
|
- [Working memory](references/docs-memory-working-memory.md) - Learn how to configure working memory in Mastra to store persistent user data, preferences.
|
|
22
|
-
- [Storage
|
|
22
|
+
- [Storage](references/docs-storage.md) - Configure storage for Mastra to persist runtime state across agents, workflows, observability, evals, schedules, and memory.
|
|
23
23
|
|
|
24
24
|
### Integrations
|
|
25
25
|
|
|
@@ -418,7 +418,7 @@ With default settings, the context window doesn't grow unbounded. It oscillates
|
|
|
418
418
|
3. **Repeat**: History grows from \~6k back toward 30k and shrinks again. Each cycle appends to the observation log, which grows much more slowly than raw history.
|
|
419
419
|
4. **Observations reach 40k**: The Reflector creates a smaller log from the current observations and any earlier reflections.
|
|
420
420
|
|
|
421
|
-
In the normal buffered cycle, raw history oscillates between roughly 6k and 30k tokens. The observation log stays around 40k tokens, however long the conversation runs. These are activation thresholds rather than hard caps
|
|
421
|
+
In the normal buffered cycle, raw history oscillates between roughly 6k and 30k tokens. The observation log stays around 40k tokens, however long the conversation runs. These are activation thresholds rather than hard caps, so history can grow past the threshold whenever background buffering doesn't keep pace. Above `blockAfter` (default `1.2`, \~36k tokens) activation is allowed to overshoot the retention target instead of activating fewer chunks. It doesn't drain the buffer, and with the default settings it removes the same amount of history as below the threshold. Reflection falls back to a synchronous run above its own `blockAfter` (\~48k tokens).
|
|
422
422
|
|
|
423
423
|
With [`shareTokenBudget`](https://mastra.ai/reference/memory/observational-memory) enabled, the two budgets pool together. While the observation log is small, message history can expand into the unused observation space (up to \~70k tokens with the defaults) before observation triggers. It then shrinks as observations accumulate.
|
|
424
424
|
|
|
@@ -714,23 +714,23 @@ When message tokens reach the `messageTokens` threshold, buffered chunks activat
|
|
|
714
714
|
|
|
715
715
|
Buffered observations also include continuation hints, a suggested next response and the current task, so the main agent maintains conversational continuity after activation shrinks the context window.
|
|
716
716
|
|
|
717
|
-
If the agent produces messages faster than the Observer can process them,
|
|
717
|
+
If the agent produces messages faster than the Observer can process them, the `blockAfter` safety threshold lets activation overshoot the retention target instead of activating fewer chunks. It never activates more chunks than are needed to reach that target, and with the default settings it changes nothing. A synchronous observation runs when the `messageTokens` threshold is reached and buffered activation didn't happen. Buffered activation usually preserves a minimum remaining context (the smaller of \~1k tokens or the configured retention floor), but a single buffered chunk that covers the whole pending window still activates and can leave less.
|
|
718
718
|
|
|
719
719
|
Reflection works similarly, the Reflector runs in the background when observations reach a fraction of the reflection threshold.
|
|
720
720
|
|
|
721
721
|
### Settings
|
|
722
722
|
|
|
723
|
-
| Setting | Default | What it controls
|
|
724
|
-
| ------------------------------------- | ------- |
|
|
725
|
-
| `observation.bufferTokens` | `0.2` | How often to buffer. `0.2` means every 20% of `messageTokens`. With the default 30k threshold, that's roughly every 6k tokens. Can also be an absolute token count (e.g. `5000`).
|
|
726
|
-
| `observation.bufferActivation` | `0.8` | How aggressively to clear the message window on activation. `0.8` means remove enough messages to keep only 20% of `messageTokens` remaining. Lower values keep more message history.
|
|
727
|
-
| `observation.blockAfter` | `1.2` | Safety net if buffering can't keep up. Values from 1 up to (but not including) 100 multiply `messageTokens`: at `1.2`,
|
|
728
|
-
| `activateAfterIdle` | none | Forces buffered observations to activate after a period of inactivity, even before `observation.messageTokens` is reached. Accepts a numeric millisecond value such as `300_000`, duration strings like `"5m"` or `"1hr"`, or `"auto"` for a provider-aware prompt cache TTL.
|
|
729
|
-
| `activateOnProviderChange` | `false` | Forces buffered observations to activate when the next step uses a different `provider/model` than the one that produced the latest assistant step. Use this when switching providers or models would invalidate prompt cache reuse.
|
|
730
|
-
| `reflection.bufferActivation` | `0.5` | When to start background reflection. `0.5` means reflection begins when observations reach 50% of the `observationTokens` threshold.
|
|
731
|
-
| `reflection.activateAfterIdle` | none | Opts buffered reflections into idle activation. Reflections don't inherit top-level `activateAfterIdle`.
|
|
732
|
-
| `reflection.activateOnProviderChange` | `false` | Opts buffered reflections into provider-change activation. Reflections don't inherit top-level `activateOnProviderChange`.
|
|
733
|
-
| `reflection.blockAfter` | `1.2` | Safety threshold for reflection
|
|
723
|
+
| Setting | Default | What it controls |
|
|
724
|
+
| ------------------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
725
|
+
| `observation.bufferTokens` | `0.2` | How often to buffer. `0.2` means every 20% of `messageTokens`. With the default 30k threshold, that's roughly every 6k tokens. Can also be an absolute token count (e.g. `5000`). |
|
|
726
|
+
| `observation.bufferActivation` | `0.8` | How aggressively to clear the message window on activation. `0.8` means remove enough messages to keep only 20% of `messageTokens` remaining. Lower values keep more message history. |
|
|
727
|
+
| `observation.blockAfter` | `1.2` | Safety net if buffering can't keep up. Values from 1 up to (but not including) 100 multiply `messageTokens`: at `1.2`, the threshold is 36k tokens (1.2 × 30k). Above it, activation may overshoot the retention target instead of activating fewer chunks. Values of 100 or more are absolute token counts (e.g. `50_000`) and must be greater than `messageTokens`. |
|
|
728
|
+
| `activateAfterIdle` | none | Forces buffered observations to activate after a period of inactivity, even before `observation.messageTokens` is reached. Accepts a numeric millisecond value such as `300_000`, duration strings like `"5m"` or `"1hr"`, or `"auto"` for a provider-aware prompt cache TTL. |
|
|
729
|
+
| `activateOnProviderChange` | `false` | Forces buffered observations to activate when the next step uses a different `provider/model` than the one that produced the latest assistant step. Use this when switching providers or models would invalidate prompt cache reuse. |
|
|
730
|
+
| `reflection.bufferActivation` | `0.5` | When to start background reflection. `0.5` means reflection begins when observations reach 50% of the `observationTokens` threshold. |
|
|
731
|
+
| `reflection.activateAfterIdle` | none | Opts buffered reflections into idle activation. Reflections don't inherit top-level `activateAfterIdle`. |
|
|
732
|
+
| `reflection.activateOnProviderChange` | `false` | Opts buffered reflections into provider-change activation. Reflections don't inherit top-level `activateOnProviderChange`. |
|
|
733
|
+
| `reflection.blockAfter` | `1.2` | Safety threshold for reflection. Same value format as observation (absolute values must be greater than `observationTokens`), but above it reflection runs synchronously when no buffered reflection is ready to activate. |
|
|
734
734
|
|
|
735
735
|
If you're relying on prompt caching, set `activateAfterIdle` to `"auto"` or to a specific cache TTL. That way, once a thread has been idle long enough for the cache to expire, the next request can activate buffered observations first and send a smaller compressed context window.
|
|
736
736
|
|
|
@@ -270,7 +270,7 @@ Supported embedding models:
|
|
|
270
270
|
|
|
271
271
|
- **OpenAI**: `text-embedding-3-small`, `text-embedding-3-large`, `text-embedding-ada-002`
|
|
272
272
|
- **Google**: `gemini-embedding-001`
|
|
273
|
-
- **OpenRouter**: Access embedding models from
|
|
273
|
+
- **OpenRouter**: Access embedding models from multiple providers
|
|
274
274
|
|
|
275
275
|
```ts
|
|
276
276
|
import { Agent } from '@mastra/core/agent'
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
|
|
2
2
|
|
|
3
|
-
# Working
|
|
3
|
+
# Working memory
|
|
4
4
|
|
|
5
5
|
While [message history](https://mastra.ai/docs/memory/message-history) and [semantic recall](https://mastra.ai/docs/memory/semantic-recall) help agents remember conversations, working memory allows them to maintain persistent information about users across interactions.
|
|
6
6
|
|
|
@@ -213,7 +213,7 @@ const paragraphMemory = new Memory({
|
|
|
213
213
|
|
|
214
214
|
## Structured working memory
|
|
215
215
|
|
|
216
|
-
Working memory can also be defined using a structured schema instead of a Markdown template.
|
|
216
|
+
Working memory can also be defined using a structured schema instead of a Markdown template. A [Standard JSON Schema](https://standardschema.dev/json-schema) ([Zod](https://zod.dev/), [Valibot](https://valibot.dev/), [ArkType](https://arktype.io/), etc.). When using a schema, the agent will see and update working memory as a JSON object matching your schema.
|
|
217
217
|
|
|
218
218
|
**Requirement:** You must specify either `template` or `schema`, but not both.
|
|
219
219
|
|
|
@@ -400,7 +400,7 @@ const response = await agent.generate('What do you know about me?', {
|
|
|
400
400
|
|
|
401
401
|
## Opt in to state signals (experimental)
|
|
402
402
|
|
|
403
|
-
By default, working memory reaches the model as part of the system message. You can opt into delivering it as a [state signal](https://mastra.ai/docs/
|
|
403
|
+
By default, working memory reaches the model as part of the system message. You can opt into delivering it as a [state signal](https://mastra.ai/docs/harness/signals) instead by setting `useStateSignals: true`:
|
|
404
404
|
|
|
405
405
|
```typescript
|
|
406
406
|
const memory = new Memory({
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
|
|
2
2
|
|
|
3
|
-
# Storage
|
|
3
|
+
# Storage
|
|
4
4
|
|
|
5
5
|
Storage is the persistence layer for the Mastra runtime. It keeps memory, workflow state, observability data, eval results, schedules, and long-running agent state available after a process restarts.
|
|
6
6
|
|
|
@@ -10,7 +10,7 @@ Storage powers:
|
|
|
10
10
|
- [Workflows](https://mastra.ai/docs/workflows/overview): Durable snapshots for suspended and resumed workflow runs.
|
|
11
11
|
- [Observability](https://mastra.ai/docs/observability/overview): Traces, spans, metrics, logs, and feedback.
|
|
12
12
|
- [Evals](https://mastra.ai/docs/evals/overview): Scores, datasets, experiments, and evaluation results.
|
|
13
|
-
- [Long-running agents](https://mastra.ai/docs/
|
|
13
|
+
- [Long-running agents](https://mastra.ai/docs/harness/durable-agents): Background tasks, schedules, goals, and thread state.
|
|
14
14
|
|
|
15
15
|
## When to configure storage
|
|
16
16
|
|
|
@@ -188,25 +188,27 @@ You can also route `observability` to a dedicated analytics backend. See the [ob
|
|
|
188
188
|
|
|
189
189
|
## Supported providers
|
|
190
190
|
|
|
191
|
-
Each provider page includes installation instructions, configuration parameters, and usage examples
|
|
191
|
+
Each provider page includes installation instructions, configuration parameters, and usage examples. libSQL is the fastest path for local development because it doesn't require running a separate database server.
|
|
192
192
|
|
|
193
|
+
- [Aurora DSQL](https://mastra.ai/integrations/databases/aurora-dsql)
|
|
194
|
+
- [ClickHouse](https://mastra.ai/integrations/databases/clickhouse)
|
|
193
195
|
- [Cloudflare D1](https://mastra.ai/integrations/databases/cloudflare-d1)
|
|
194
|
-
- [Cloudflare KV
|
|
196
|
+
- [Cloudflare KV](https://mastra.ai/integrations/databases/cloudflare-kv)
|
|
195
197
|
- [Convex](https://mastra.ai/integrations/databases/convex)
|
|
198
|
+
- [DuckDB](https://mastra.ai/integrations/databases/duckdb)
|
|
196
199
|
- [DynamoDB](https://mastra.ai/integrations/databases/dynamodb)
|
|
197
200
|
- [Google Cloud Spanner](https://mastra.ai/integrations/databases/spanner)
|
|
198
201
|
- [LanceDB](https://mastra.ai/integrations/databases/lancedb)
|
|
199
202
|
- [libSQL](https://mastra.ai/integrations/databases/libsql)
|
|
200
|
-
- [
|
|
203
|
+
- [Mastra](https://mastra.ai/docs/mastra-platform/database)
|
|
201
204
|
- [MongoDB](https://mastra.ai/integrations/databases/mongodb)
|
|
205
|
+
- [MSSQL](https://mastra.ai/integrations/databases/mssql)
|
|
202
206
|
- [Neon Postgres](https://mastra.ai/integrations/databases/neon)
|
|
203
207
|
- [OracleDB](https://mastra.ai/integrations/databases/oracledb)
|
|
204
208
|
- [PostgreSQL](https://mastra.ai/integrations/databases/postgresql)
|
|
205
209
|
- [Redis](https://mastra.ai/integrations/databases/redis)
|
|
206
210
|
- [Upstash](https://mastra.ai/integrations/databases/upstash)
|
|
207
211
|
|
|
208
|
-
> **Tip:** libSQL is the fastest path for local development because it doesn't require running a separate database server.
|
|
209
|
-
|
|
210
212
|
## Next steps
|
|
211
213
|
|
|
212
214
|
- [Composite storage](https://mastra.ai/reference/storage/composite)
|
|
@@ -201,7 +201,7 @@ const results = await store.query({
|
|
|
201
201
|
### Amazon S3 Vectors
|
|
202
202
|
|
|
203
203
|
- Equality values must be primitives (string/number/boolean). `null`/`undefined`, arrays, objects, and Date aren't allowed for equality. Range operators accept numbers or Date (Dates are normalized to epoch ms).
|
|
204
|
-
- `$in`/`$nin` require **non-empty arrays of primitives
|
|
204
|
+
- `$in`/`$nin` require **non-empty arrays of primitives**. Date elements are allowed and normalized to epoch ms. **Array equality** isn't supported.
|
|
205
205
|
- Implicit AND is canonicalized (`{a:1,b:2}` → `{$and:[{a:1},{b:2}]`). Logical operators must contain field conditions and use non-empty arrays. They may appear only at the root or within other logical operators (not inside field values).
|
|
206
206
|
- Keys listed in `nonFilterableMetadataKeys` at index creation are stored but not filterable. This setting is immutable.
|
|
207
207
|
- $exists requires a boolean value.
|
|
@@ -266,6 +266,23 @@ For detailed configuration options and advanced usage, see the [Vector Query Too
|
|
|
266
266
|
|
|
267
267
|
Vector store prompts define query patterns and filtering capabilities for each vector database implementation. When implementing filtering, these prompts are required in the agent's instructions to specify valid operators and syntax for each vector store implementation.
|
|
268
268
|
|
|
269
|
+
**MongoDB**:
|
|
270
|
+
|
|
271
|
+
```ts
|
|
272
|
+
import { MONGODB_PROMPT } from '@mastra/mongodb'
|
|
273
|
+
|
|
274
|
+
export const ragAgent = new Agent({
|
|
275
|
+
id: 'rag-agent',
|
|
276
|
+
name: 'RAG Agent',
|
|
277
|
+
model: 'openai/gpt-5.6-sol',
|
|
278
|
+
instructions: `
|
|
279
|
+
Process queries using the provided context. Structure responses to be concise and relevant.
|
|
280
|
+
${MONGODB_PROMPT}
|
|
281
|
+
`,
|
|
282
|
+
tools: { vectorQueryTool },
|
|
283
|
+
})
|
|
284
|
+
```
|
|
285
|
+
|
|
269
286
|
**pgVector**:
|
|
270
287
|
|
|
271
288
|
```ts
|
|
@@ -402,23 +419,6 @@ export const ragAgent = new Agent({
|
|
|
402
419
|
})
|
|
403
420
|
```
|
|
404
421
|
|
|
405
|
-
**MongoDB**:
|
|
406
|
-
|
|
407
|
-
```ts
|
|
408
|
-
import { MONGODB_PROMPT } from '@mastra/mongodb'
|
|
409
|
-
|
|
410
|
-
export const ragAgent = new Agent({
|
|
411
|
-
id: 'rag-agent',
|
|
412
|
-
name: 'RAG Agent',
|
|
413
|
-
model: 'openai/gpt-5.6-sol',
|
|
414
|
-
instructions: `
|
|
415
|
-
Process queries using the provided context. Structure responses to be concise and relevant.
|
|
416
|
-
${MONGODB_PROMPT}
|
|
417
|
-
`,
|
|
418
|
-
tools: { vectorQueryTool },
|
|
419
|
-
})
|
|
420
|
-
```
|
|
421
|
-
|
|
422
422
|
**OpenSearch**:
|
|
423
423
|
|
|
424
424
|
```ts
|
|
@@ -520,7 +520,13 @@ The weights control how different factors influence the final ranking:
|
|
|
520
520
|
|
|
521
521
|
> **Note:** For semantic scoring to work properly during re-ranking, each result must include the text content in its `metadata.text` field.
|
|
522
522
|
|
|
523
|
-
You can also use other relevance score providers like Cohere or ZeroEntropy:
|
|
523
|
+
You can also use other relevance score providers like Voyage AI, Cohere, or ZeroEntropy:
|
|
524
|
+
|
|
525
|
+
```ts
|
|
526
|
+
import { VoyageRelevanceScorer } from '@mastra/voyageai'
|
|
527
|
+
|
|
528
|
+
const relevanceProvider = new VoyageRelevanceScorer({ model: 'rerank-2.5' })
|
|
529
|
+
```
|
|
524
530
|
|
|
525
531
|
```ts
|
|
526
532
|
const relevanceProvider = new CohereRelevanceScorer('rerank-v3.5')
|
|
@@ -530,6 +536,8 @@ const relevanceProvider = new CohereRelevanceScorer('rerank-v3.5')
|
|
|
530
536
|
const relevanceProvider = new ZeroEntropyRelevanceScorer('zerank-1')
|
|
531
537
|
```
|
|
532
538
|
|
|
539
|
+
Voyage AI provides dedicated reranking models: `rerank-2.5` and `rerank-2.5-lite` both allow up to 32,000 tokens for the query and any single document combined, and up to 600,000 tokens across a request. `VoyageRelevanceScorer` reads `VOYAGE_API_KEY` from the environment, or accepts an `apiKey` in its config.
|
|
540
|
+
|
|
533
541
|
The re-ranked results combine vector similarity with semantic understanding to improve retrieval quality.
|
|
534
542
|
|
|
535
543
|
For more details about re-ranking, see the [rerank()](https://mastra.ai/reference/rag/rerankWithScorer) method.
|
package/dist/index.cjs
CHANGED
|
@@ -8960,7 +8960,11 @@ var WorkflowsOracle = class _WorkflowsOracle extends storage.WorkflowsStorage {
|
|
|
8960
8960
|
if (!snapshot?.context) {
|
|
8961
8961
|
throw new Error(`Snapshot not found for runId ${runId}`);
|
|
8962
8962
|
}
|
|
8963
|
-
const
|
|
8963
|
+
const { expectedStatus, ...state } = opts;
|
|
8964
|
+
if (!storage.matchesExpectedWorkflowStatus(snapshot.status, expectedStatus)) {
|
|
8965
|
+
return void 0;
|
|
8966
|
+
}
|
|
8967
|
+
const updatedSnapshot = { ...snapshot, ...state };
|
|
8964
8968
|
await client.none(
|
|
8965
8969
|
`UPDATE ${this.table()} SET snapshot = :snapshot, ${WORKFLOW_UPDATED_AT} = :updatedAt WHERE workflow_name = :workflowName AND run_id = :runId`,
|
|
8966
8970
|
{ workflowName, runId, snapshot: jsonBind(updatedSnapshot), updatedAt: /* @__PURE__ */ new Date() }
|