@mastra/oracledb 0.0.0-openai-schema-compat-issue-20260810211758

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.
Files changed (94) hide show
  1. package/CHANGELOG.md +104 -0
  2. package/LICENSE.md +30 -0
  3. package/README.md +398 -0
  4. package/dist/docs/SKILL.md +37 -0
  5. package/dist/docs/assets/SOURCE_MAP.json +6 -0
  6. package/dist/docs/references/docs-memory-observational-memory.md +835 -0
  7. package/dist/docs/references/docs-memory-semantic-recall.md +402 -0
  8. package/dist/docs/references/docs-memory-working-memory.md +432 -0
  9. package/dist/docs/references/docs-storage-overview.md +215 -0
  10. package/dist/docs/references/guides-rag-overview.md +74 -0
  11. package/dist/docs/references/guides-rag-retrieval.md +537 -0
  12. package/dist/docs/references/guides-rag-vector-databases.md +710 -0
  13. package/dist/docs/references/reference-rag-metadata-filters.md +227 -0
  14. package/dist/docs/references/reference-storage-oracledb.md +239 -0
  15. package/dist/docs/references/reference-vectors-oracledb.md +347 -0
  16. package/dist/index.cjs +10217 -0
  17. package/dist/index.cjs.map +1 -0
  18. package/dist/index.d.ts +7 -0
  19. package/dist/index.d.ts.map +1 -0
  20. package/dist/index.js +10196 -0
  21. package/dist/index.js.map +1 -0
  22. package/dist/schema.d.ts +27 -0
  23. package/dist/schema.d.ts.map +1 -0
  24. package/dist/shared/connection.d.ts +46 -0
  25. package/dist/shared/connection.d.ts.map +1 -0
  26. package/dist/storage/db/index.d.ts +128 -0
  27. package/dist/storage/db/index.d.ts.map +1 -0
  28. package/dist/storage/domain-utils.d.ts +18 -0
  29. package/dist/storage/domain-utils.d.ts.map +1 -0
  30. package/dist/storage/domains/agents/index.d.ts +54 -0
  31. package/dist/storage/domains/agents/index.d.ts.map +1 -0
  32. package/dist/storage/domains/mcp-clients/index.d.ts +46 -0
  33. package/dist/storage/domains/mcp-clients/index.d.ts.map +1 -0
  34. package/dist/storage/domains/memory/index.d.ts +88 -0
  35. package/dist/storage/domains/memory/index.d.ts.map +1 -0
  36. package/dist/storage/domains/memory/messages.d.ts +37 -0
  37. package/dist/storage/domains/memory/messages.d.ts.map +1 -0
  38. package/dist/storage/domains/memory/observational-buffering.d.ts +7 -0
  39. package/dist/storage/domains/memory/observational-buffering.d.ts.map +1 -0
  40. package/dist/storage/domains/memory/observational.d.ts +56 -0
  41. package/dist/storage/domains/memory/observational.d.ts.map +1 -0
  42. package/dist/storage/domains/memory/resources.d.ts +14 -0
  43. package/dist/storage/domains/memory/resources.d.ts.map +1 -0
  44. package/dist/storage/domains/memory/schema.d.ts +43 -0
  45. package/dist/storage/domains/memory/schema.d.ts.map +1 -0
  46. package/dist/storage/domains/memory/threads.d.ts +37 -0
  47. package/dist/storage/domains/memory/threads.d.ts.map +1 -0
  48. package/dist/storage/domains/memory/utils.d.ts +68 -0
  49. package/dist/storage/domains/memory/utils.d.ts.map +1 -0
  50. package/dist/storage/domains/observability/binds.d.ts +21 -0
  51. package/dist/storage/domains/observability/binds.d.ts.map +1 -0
  52. package/dist/storage/domains/observability/index.d.ts +49 -0
  53. package/dist/storage/domains/observability/index.d.ts.map +1 -0
  54. package/dist/storage/domains/observability/logs.d.ts +5 -0
  55. package/dist/storage/domains/observability/logs.d.ts.map +1 -0
  56. package/dist/storage/domains/observability/schema.d.ts +38 -0
  57. package/dist/storage/domains/observability/schema.d.ts.map +1 -0
  58. package/dist/storage/domains/observability/scores-bridge.d.ts +7 -0
  59. package/dist/storage/domains/observability/scores-bridge.d.ts.map +1 -0
  60. package/dist/storage/domains/observability/spans.d.ts +18 -0
  61. package/dist/storage/domains/observability/spans.d.ts.map +1 -0
  62. package/dist/storage/domains/scorer-definitions/index.d.ts +46 -0
  63. package/dist/storage/domains/scorer-definitions/index.d.ts.map +1 -0
  64. package/dist/storage/domains/scores/index.d.ts +63 -0
  65. package/dist/storage/domains/scores/index.d.ts.map +1 -0
  66. package/dist/storage/domains/workflows/index.d.ts +61 -0
  67. package/dist/storage/domains/workflows/index.d.ts.map +1 -0
  68. package/dist/storage/index.d.ts +45 -0
  69. package/dist/storage/index.d.ts.map +1 -0
  70. package/dist/storage/migrations.d.ts +55 -0
  71. package/dist/storage/migrations.d.ts.map +1 -0
  72. package/dist/storage/types.d.ts +44 -0
  73. package/dist/storage/types.d.ts.map +1 -0
  74. package/dist/vector/ddl.d.ts +58 -0
  75. package/dist/vector/ddl.d.ts.map +1 -0
  76. package/dist/vector/filter.d.ts +7 -0
  77. package/dist/vector/filter.d.ts.map +1 -0
  78. package/dist/vector/identifiers.d.ts +11 -0
  79. package/dist/vector/identifiers.d.ts.map +1 -0
  80. package/dist/vector/index.d.ts +32 -0
  81. package/dist/vector/index.d.ts.map +1 -0
  82. package/dist/vector/prompt.d.ts +6 -0
  83. package/dist/vector/prompt.d.ts.map +1 -0
  84. package/dist/vector/query.d.ts +5 -0
  85. package/dist/vector/query.d.ts.map +1 -0
  86. package/dist/vector/sql.d.ts +12 -0
  87. package/dist/vector/sql.d.ts.map +1 -0
  88. package/dist/vector/stats.d.ts +9 -0
  89. package/dist/vector/stats.d.ts.map +1 -0
  90. package/dist/vector/types.d.ts +80 -0
  91. package/dist/vector/types.d.ts.map +1 -0
  92. package/dist/vector/upsert.d.ts +20 -0
  93. package/dist/vector/upsert.d.ts.map +1 -0
  94. package/package.json +71 -0
package/CHANGELOG.md ADDED
@@ -0,0 +1,104 @@
1
+ # @mastra/oracledb
2
+
3
+ ## 0.0.0-openai-schema-compat-issue-20260810211758
4
+
5
+ ### Minor Changes
6
+
7
+ - Added `@mastra/oracledb`, a storage and vector provider for Oracle Database 23ai+. ([#19650](https://github.com/mastra-ai/mastra/pull/19650))
8
+
9
+ **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).
10
+
11
+ ```typescript
12
+ import { OracleStore, OracleVector } from '@mastra/oracledb';
13
+
14
+ const storage = new OracleStore({
15
+ id: 'oracle-store',
16
+
17
+ password: process.env.ORACLE_DATABASE_PASSWORD,
18
+ connectString: process.env.ORACLE_DATABASE_CONNECT_STRING,
19
+ });
20
+
21
+ const vector = new OracleVector({
22
+ id: 'oracle-vector',
23
+
24
+ password: process.env.ORACLE_DATABASE_PASSWORD,
25
+ connectString: process.env.ORACLE_DATABASE_CONNECT_STRING,
26
+ });
27
+ ```
28
+
29
+ Supersedes [#18011](https://github.com/mastra-ai/mastra/pull/18011).
30
+
31
+ ### Patch Changes
32
+
33
+ - Fixed generated thread titles being clobbered during a turn ([#21041](https://github.com/mastra-ai/mastra/pull/21041))
34
+
35
+ `updateThread` required both `title` and `metadata`, so callers that only needed to
36
+ change metadata (message persistence, working memory, observational memory, channel
37
+ subscriptions) had to read the thread and pass its title back. When title generation
38
+ finished between that read and the write, the freshly generated title was overwritten
39
+ with the stale one.
40
+
41
+ `title` and `metadata` are now independently optional: omitting one leaves that column
42
+ untouched. Callers that only change metadata no longer send a title, and message
43
+ persistence no longer rewrites a thread row it just read.
44
+
45
+ - 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), [`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), [`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), [`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), [`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), [`f8da216`](https://github.com/mastra-ai/mastra/commit/f8da21633e7eb0e31c9ce0fc30567870d19416d3), [`6a84954`](https://github.com/mastra-ai/mastra/commit/6a84954a2667f85b6d59da652dab1bbff007ccb0), [`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), [`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), [`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), [`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), [`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), [`76e5132`](https://github.com/mastra-ai/mastra/commit/76e51328dbc0749c8304e6b3f21e4401f451b081), [`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), [`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), [`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), [`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), [`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), [`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), [`9be8878`](https://github.com/mastra-ai/mastra/commit/9be8878dcf0388e84fc4873e0eec27bd49b881a4), [`e5786be`](https://github.com/mastra-ai/mastra/commit/e5786be02bb903073082bd9d6da880ebaacc343f), [`2093fbd`](https://github.com/mastra-ai/mastra/commit/2093fbd53bb744bae19ec89f6d73db9a66fbe8a7), [`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)]:
46
+ - @mastra/core@0.0.0-openai-schema-compat-issue-20260810211758
47
+
48
+ ## 0.2.0-alpha.1
49
+
50
+ ### Patch Changes
51
+
52
+ - Fixed generated thread titles being clobbered during a turn ([#21041](https://github.com/mastra-ai/mastra/pull/21041))
53
+
54
+ `updateThread` required both `title` and `metadata`, so callers that only needed to
55
+ change metadata (message persistence, working memory, observational memory, channel
56
+ subscriptions) had to read the thread and pass its title back. When title generation
57
+ finished between that read and the write, the freshly generated title was overwritten
58
+ with the stale one.
59
+
60
+ `title` and `metadata` are now independently optional: omitting one leaves that column
61
+ untouched. Callers that only change metadata no longer send a title, and message
62
+ persistence no longer rewrites a thread row it just read.
63
+
64
+ - Updated dependencies [[`1c75e32`](https://github.com/mastra-ai/mastra/commit/1c75e32f7fc0b9fb6f548b4407feaec8a1440212), [`c47165c`](https://github.com/mastra-ai/mastra/commit/c47165c983c87594c6952f1fd2fa51a90205034c), [`e08e789`](https://github.com/mastra-ai/mastra/commit/e08e789c1bf4cd2fe46363f7a4728536ceccc9bd), [`35cc901`](https://github.com/mastra-ai/mastra/commit/35cc90102cf834a84827acaf9eee0b6d6d1e2a3b), [`a8b4cf0`](https://github.com/mastra-ai/mastra/commit/a8b4cf02823cffebc4751a53337dfacf097c1ae1), [`f33264f`](https://github.com/mastra-ai/mastra/commit/f33264f517ae603279afd5c4251e2b40f6dd3618), [`689f2c4`](https://github.com/mastra-ai/mastra/commit/689f2c4b6c0835fe455702b01d21daa8abcd9331), [`eeae63e`](https://github.com/mastra-ai/mastra/commit/eeae63e7fbe8e1f237adc69bca6e2ac13c5ca907), [`4c186a0`](https://github.com/mastra-ai/mastra/commit/4c186a017275f45e6ed4c09de0f89550e2d09e8c), [`b0fa077`](https://github.com/mastra-ai/mastra/commit/b0fa077bcbc9b08551846fe372a0d3d15b71ed72)]:
65
+ - @mastra/core@1.58.0-alpha.8
66
+
67
+ ## 0.2.0-alpha.0
68
+
69
+ ### Minor Changes
70
+
71
+ - Added `@mastra/oracledb`, a storage and vector provider for Oracle Database 23ai+. ([#19650](https://github.com/mastra-ai/mastra/pull/19650))
72
+
73
+ **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).
74
+
75
+ ```typescript
76
+ import { OracleStore, OracleVector } from '@mastra/oracledb';
77
+
78
+ const storage = new OracleStore({
79
+ id: 'oracle-store',
80
+
81
+ password: process.env.ORACLE_DATABASE_PASSWORD,
82
+ connectString: process.env.ORACLE_DATABASE_CONNECT_STRING,
83
+ });
84
+
85
+ const vector = new OracleVector({
86
+ id: 'oracle-vector',
87
+
88
+ password: process.env.ORACLE_DATABASE_PASSWORD,
89
+ connectString: process.env.ORACLE_DATABASE_CONNECT_STRING,
90
+ });
91
+ ```
92
+
93
+ Supersedes [#18011](https://github.com/mastra-ai/mastra/pull/18011).
94
+
95
+ ### Patch Changes
96
+
97
+ - Updated dependencies [[`f59032a`](https://github.com/mastra-ai/mastra/commit/f59032a73699443555a08a479e7ac578975784f2), [`bf936e2`](https://github.com/mastra-ai/mastra/commit/bf936e2c89b2ff0dad5695b873ddc009ba96d41e)]:
98
+ - @mastra/core@1.58.0-alpha.6
99
+
100
+ ## 0.1.0
101
+
102
+ - Added `OracleStore` with storage domains for memory, workflows, observability traces/logs, scores, scorer definitions, MCP clients, and agents.
103
+ - Added `OracleVector` with vector table management, metadata filtering, and Oracle vector index support.
104
+ - Added shared Oracle connection/pool management, migrations, schema export, identifier helpers, docs, and correctness tests.
package/LICENSE.md ADDED
@@ -0,0 +1,30 @@
1
+ Portions of this software are licensed as follows:
2
+
3
+ - All content that resides under any directory named "ee/" within this
4
+ repository, including but not limited to:
5
+ - `packages/core/src/auth/ee/`
6
+ - `packages/server/src/server/auth/ee/`
7
+ is licensed under the license defined in `ee/LICENSE`.
8
+
9
+ - All third-party components incorporated into the Mastra Software are
10
+ licensed under the original license provided by the owner of the
11
+ applicable component.
12
+
13
+ - Content outside of the above-mentioned directories or restrictions is
14
+ available under the "Apache License 2.0" as defined below.
15
+
16
+ # Apache License 2.0
17
+
18
+ Copyright (c) 2025 Kepler Software, Inc.
19
+
20
+ Licensed under the Apache License, Version 2.0 (the "License");
21
+ you may not use this file except in compliance with the License.
22
+ You may obtain a copy of the License at
23
+
24
+ http://www.apache.org/licenses/LICENSE-2.0
25
+
26
+ Unless required by applicable law or agreed to in writing, software
27
+ distributed under the License is distributed on an "AS IS" BASIS,
28
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
29
+ See the License for the specific language governing permissions and
30
+ limitations under the License.
package/README.md ADDED
@@ -0,0 +1,398 @@
1
+ # @mastra/oracledb
2
+
3
+ Oracle Database provider for Mastra, providing storage and vector similarity search with Oracle JSON, Oracle `VECTOR`, connection pooling, and transaction support.
4
+
5
+ ## Installation
6
+
7
+ ```bash
8
+ npm install @mastra/oracledb
9
+ ```
10
+
11
+ ## Prerequisites
12
+
13
+ - Oracle Database access through the Node.js `oracledb` driver
14
+ - Oracle Database 23ai or later when using vector search
15
+ - A database user with permission to create the Mastra tables and indexes, unless schema initialization is managed separately
16
+
17
+ ## Driver Modes
18
+
19
+ `@mastra/oracledb` uses node-oracledb Thin mode by default. Thin mode connects directly to Oracle Database and does not require a separate Oracle Client or Oracle Instant Client installation. No workspace configuration change is needed.
20
+
21
+ To use Thick mode features, install compatible Oracle Client libraries and initialize node-oracledb before creating an `OracleStore`, an `OracleVector`, or any Oracle connection pool. Applications that import `oracledb` directly should declare it as a direct dependency using a version compatible with `@mastra/oracledb`.
22
+
23
+ ```typescript
24
+ import oracledb from 'oracledb';
25
+
26
+ // macOS or Windows
27
+ oracledb.initOracleClient({ libDir: '/path/to/oracle/instantclient' });
28
+ ```
29
+
30
+ On Linux, configure the system library search path and call `initOracleClient()` without `libDir`. All Oracle connections in a Node.js process use the same mode. See the [node-oracledb initialization guide](https://node-oracledb.readthedocs.io/en/v6.10.0/user_guide/initialization.html) for platform-specific setup.
31
+
32
+ ## Usage
33
+
34
+ ### Storage
35
+
36
+ ```typescript
37
+ import { OracleStore } from '@mastra/oracledb';
38
+
39
+ const store = new OracleStore({
40
+ id: 'oracle-store',
41
+ user: process.env.ORACLE_DATABASE_USER,
42
+ password: process.env.ORACLE_DATABASE_PASSWORD,
43
+ connectString: process.env.ORACLE_DATABASE_CONNECT_STRING,
44
+ });
45
+
46
+ await store.init();
47
+ const memory = await store.getStore('memory');
48
+ if (!memory) throw new Error('Oracle memory store is not available');
49
+
50
+ // Create a thread
51
+ await memory.saveThread({
52
+ thread: {
53
+ id: 'thread-123',
54
+ resourceId: 'resource-456',
55
+ title: 'My Thread',
56
+ metadata: { key: 'value' },
57
+ createdAt: new Date(),
58
+ },
59
+ });
60
+
61
+ // Add messages to thread
62
+ await memory.saveMessages({
63
+ messages: [
64
+ {
65
+ id: 'msg-789',
66
+ threadId: 'thread-123',
67
+ role: 'user',
68
+ content: { content: 'Hello' },
69
+ resourceId: 'resource-456',
70
+ createdAt: new Date(),
71
+ },
72
+ ],
73
+ });
74
+
75
+ // Query threads and messages
76
+ const savedThread = await memory.getThreadById({ threadId: 'thread-123' });
77
+ const { messages } = await memory.listMessages({ threadId: 'thread-123' });
78
+ ```
79
+
80
+ ### Vector Store
81
+
82
+ ```typescript
83
+ import { OracleVector } from '@mastra/oracledb';
84
+
85
+ const vectorStore = new OracleVector({
86
+ id: 'oracle-vector',
87
+ user: process.env.ORACLE_DATABASE_USER,
88
+ password: process.env.ORACLE_DATABASE_PASSWORD,
89
+ connectString: process.env.ORACLE_DATABASE_CONNECT_STRING,
90
+ });
91
+
92
+ // Create a vector table
93
+ await vectorStore.createIndex({
94
+ indexName: 'my_vectors',
95
+ dimension: 1536,
96
+ metric: 'cosine',
97
+ });
98
+
99
+ // Add vectors
100
+ const ids = await vectorStore.upsert({
101
+ indexName: 'my_vectors',
102
+ vectors: [[0.1, 0.2, ...], [0.3, 0.4, ...]],
103
+ metadata: [{ text: 'doc1' }, { text: 'doc2' }],
104
+ });
105
+
106
+ // Query vectors
107
+ const results = await vectorStore.query({
108
+ indexName: 'my_vectors',
109
+ queryVector: [0.1, 0.2, ...],
110
+ topK: 10,
111
+ filter: { text: { $eq: 'doc1' } },
112
+ includeVector: false,
113
+ });
114
+ ```
115
+
116
+ ### Shared Pool
117
+
118
+ `OracleStore` and `OracleVector` can share the same Oracle connection pool.
119
+
120
+ ```typescript
121
+ const store = new OracleStore({
122
+ id: 'oracle-store',
123
+ user: process.env.ORACLE_DATABASE_USER,
124
+ password: process.env.ORACLE_DATABASE_PASSWORD,
125
+ connectString: process.env.ORACLE_DATABASE_CONNECT_STRING,
126
+ });
127
+
128
+ const vectorStore = new OracleVector({
129
+ id: 'oracle-vector',
130
+ poolManager: store.getPoolManager(),
131
+ });
132
+ ```
133
+
134
+ ## Configuration
135
+
136
+ Both `OracleStore` and `OracleVector` support:
137
+
138
+ - Username/password connections
139
+ - Autonomous Database wallet and mTLS configuration
140
+ - External authentication
141
+ - Existing Oracle pools through `OraclePoolManager`
142
+ - Custom schema names
143
+
144
+ ### Storage Options
145
+
146
+ - `id`: Unique identifier for this store instance
147
+ - `schemaName`: Oracle schema name to use for Mastra tables
148
+ - `messageBatchSize`: Number of messages per batch insert
149
+ - `skipDefaultIndexes`: Skip default storage indexes when DBAs manage indexes separately
150
+ - `indexes`: Custom Oracle index definitions to create during initialization
151
+ - `disableInit`: Disable automatic schema initialization
152
+ - `migrationTableName`: Custom migration ledger table name
153
+ - `vectorRegistryTableName`: Vector registry table used to clean semantic-recall rows when `OracleVector.registryTableName` is customized
154
+
155
+ ### Vector Options
156
+
157
+ - `id`: Unique identifier for this vector store instance
158
+ - `schemaName`: Oracle schema name to use for vector tables
159
+ - `tablePrefix`: Prefix for generated physical vector table names
160
+ - `registryTableName`: Table used to map Mastra index names to Oracle vector tables
161
+ - `defaultIndexConfig`: Default Oracle vector index configuration
162
+ - `defaultMetadataIndexes`: Metadata fields to index by default
163
+ - `defaultVectorFormat`: Vector format (`vector`, `bit`, or `int8`)
164
+ - `upsertBatchSize`: Number of vectors per batch insert
165
+
166
+ ## Features
167
+
168
+ ### Storage Features
169
+
170
+ - Thread, message, resource, working memory, and observational memory storage
171
+ - Workflow snapshot persistence
172
+ - Observability spans and logs
173
+ - Scores and scorer definitions
174
+ - Agent and MCP client registries
175
+ - Oracle JSON support for metadata, payloads, snapshots, and versioned state
176
+ - Repeatable schema migrations
177
+ - Offline schema export
178
+ - Shared connection pooling
179
+
180
+ ### Vector Store Features
181
+
182
+ - Oracle `VECTOR` storage
183
+ - Vector similarity search with cosine, euclidean, dot product, hamming, and jaccard metrics
184
+ - Exact search by default
185
+ - Optional IVF and HNSW vector indexes
186
+ - Metadata filtering with MongoDB-like query syntax
187
+ - Dense, binary, and int8 vector formats
188
+ - Automatic vector ID generation
189
+ - Logical index registry for stable Mastra index names
190
+
191
+ ## Supported Filter Operators
192
+
193
+ The following metadata filter operators are supported:
194
+
195
+ - Comparison: `$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte`
196
+ - Logical: `$and`, `$or`, `$not`, `$nor`
197
+ - Array: `$in`, `$nin`, `$all`, `$elemMatch`, `$size`
198
+ - Text: `$contains`, `$regex`
199
+ - Existence: `$exists`
200
+
201
+ Example filter:
202
+
203
+ ```typescript
204
+ {
205
+ $and: [{ resourceId: { $eq: 'resource-456' } }, { category: { $in: ['docs', 'memory'] } }];
206
+ }
207
+ ```
208
+
209
+ ## Vector Indexes
210
+
211
+ OracleVector uses exact search by default, which requires no vector index and is useful for local development, tests, and small datasets.
212
+
213
+ Use IVF or HNSW when the dataset size and latency requirements justify approximate indexing:
214
+
215
+ ```typescript
216
+ await vectorStore.createIndex({
217
+ indexName: 'my_vectors',
218
+ dimension: 1536,
219
+ metric: 'cosine',
220
+ indexConfig: {
221
+ type: 'ivf',
222
+ accuracy: 95,
223
+ ivf: {
224
+ neighborPartitions: 16,
225
+ },
226
+ },
227
+ });
228
+ ```
229
+
230
+ HNSW may require Oracle Vector Pool memory to be configured before index creation.
231
+
232
+ ## Vector memory (HNSW only)
233
+
234
+ Oracle's `VECTOR_MEMORY_SIZE` parameter sizes the shared "Vector Pool" used by **HNSW** indexes.
235
+ Exact search (the `OracleVector` default) and **IVF** indexes do not use the Vector Pool at all —
236
+ both work correctly with `VECTOR_MEMORY_SIZE = 0`, including against an empty, minimally-privileged
237
+ database.
238
+
239
+ ### Minimum grants
240
+
241
+ A brand-new Oracle user needs nothing beyond what any other Mastra storage/vector consumer needs:
242
+
243
+ ```sql
244
+ CREATE USER mastra IDENTIFIED BY "<password>";
245
+ GRANT CREATE SESSION, CREATE TABLE TO mastra;
246
+ ALTER USER mastra QUOTA UNLIMITED ON USERS;
247
+ ```
248
+
249
+ This is enough for storage, exact vector search, and IVF indexes. No DBA-level grants or Vector
250
+ Pool configuration are required unless you plan to build HNSW indexes.
251
+
252
+ ### Local Docker container (this package's `docker-compose.yaml`)
253
+
254
+ `scripts/configure-vector-memory.sql` runs during container init and persists
255
+ `VECTOR_MEMORY_SIZE = 256M` at the CDB root via `SCOPE=SPFILE`. That value only takes effect after
256
+ the instance restarts, so enabling HNSW locally is a one-time, two-step flow:
257
+
258
+ ```bash
259
+ docker compose up -d --wait
260
+ docker compose restart db
261
+ docker compose up --wait
262
+ ```
263
+
264
+ Skip the restart if you only need exact search or IVF — the container works fine with the Vector
265
+ Pool left at 0, and this package's integration suite detects that case and skips HNSW-specific
266
+ tests with a clear message instead of failing.
267
+
268
+ ### Autonomous Database
269
+
270
+ Oracle Autonomous Database manages Vector Pool memory automatically. `scripts/configure-vector-memory.sql`
271
+ is specific to self-managed containers (like the local Docker setup above) and is unnecessary —
272
+ and inapplicable — on Autonomous Database.
273
+
274
+ ## Migrations and Schema Export
275
+
276
+ `OracleStore.init()` runs repeatable migrations for the included storage domains.
277
+
278
+ ```typescript
279
+ await store.init();
280
+ const migrations = await store.listMigrations();
281
+ ```
282
+
283
+ Use `exportSchemas()` to generate Oracle DDL for review or externally managed deployments:
284
+
285
+ ```typescript
286
+ import { exportSchemas } from '@mastra/oracledb';
287
+
288
+ const ddl = exportSchemas({
289
+ schemaName: 'APP_SCHEMA',
290
+ domains: [
291
+ 'migrations',
292
+ 'memory',
293
+ 'workflows',
294
+ 'observability',
295
+ 'scores',
296
+ 'scorerDefinitions',
297
+ 'mcpClients',
298
+ 'agents',
299
+ 'vector',
300
+ ],
301
+ vector: {
302
+ indexes: [{ indexName: 'memory_messages', dimension: 1536 }],
303
+ },
304
+ });
305
+ ```
306
+
307
+ ## Methods
308
+
309
+ ### Vector Store Methods
310
+
311
+ - `createIndex({ indexName, dimension, metric?, indexConfig?, vectorFormat? })`: Create a vector table
312
+ - `upsert({ indexName, vectors, metadata?, ids? })`: Add or update vectors
313
+ - `query({ indexName, queryVector, topK?, filter?, includeVector?, minScore? })`: Search for similar vectors
314
+ - `updateVector({ indexName, id?, filter?, update })`: Update a vector by ID or metadata filter
315
+ - `deleteVector({ indexName, id })`: Delete a vector by ID
316
+ - `deleteVectors({ indexName, ids?, filter? })`: Delete vectors by IDs or metadata filter
317
+ - `listIndexes()`: List vector indexes
318
+ - `describeIndex({ indexName })`: Get vector index statistics
319
+ - `deleteIndex({ indexName })`: Delete a vector index and its table
320
+ - `buildIndex({ indexName, metric?, indexConfig? })`: Build an Oracle vector index
321
+ - `rebuildIndex({ indexName, metric?, indexConfig? })`: Rebuild an Oracle vector index
322
+ - `configureVectorMemory({ size, scope? })`: Configure Oracle Vector Pool memory
323
+ - `getIndexStatus({ indexName, ownerName? })`: Read Oracle vector index status
324
+ - `indexAccuracyQuery({ indexName, queryVector, topK?, targetAccuracy? })`: Estimate Oracle vector index accuracy
325
+ - `disconnect()`: Close the Oracle connection pool owned by the provider
326
+
327
+ ### Storage Methods
328
+
329
+ `OracleStore` implements Mastra composite storage and exposes the standard storage methods for supported domains, including memory, workflows, observability, scores, scorer definitions, agents, and MCP clients.
330
+
331
+ It also provides:
332
+
333
+ - `init()`: Initialize storage schema
334
+ - `migrate()`: Run repeatable storage migrations
335
+ - `listMigrations()`: List migration ledger records
336
+ - `getPoolManager()`: Access the shared Oracle pool manager
337
+ - `disconnect()`: Close the Oracle connection pool owned by the provider
338
+
339
+ ## Testing
340
+
341
+ ### Monorepo setup notes
342
+
343
+ **1. Use the default Thin mode** — The monorepo keeps the optional `oracledb` install lifecycle disabled. Unit and integration tests use Thin mode, so `pnpm install` and the OracleDB test commands do not require a manual `pnpm-workspace.yaml` change or an Oracle Client installation.
344
+
345
+ **2. Build workspace dependencies first** — The integration tests depend on built artifacts from `@mastra/core`. Run this from the monorepo root before the first test run:
346
+
347
+ ```bash
348
+ pnpm build:core
349
+ ```
350
+
351
+ You will get cryptic `Cannot find module` errors if this is missing.
352
+
353
+ **3. Docker setup** — Docker Compose requires the Docker daemon to be running. On a fresh Linux install you may need:
354
+
355
+ ```bash
356
+ sudo systemctl start docker
357
+ ```
358
+
359
+ For local development, create `stores/oracledb/.env` from the Mastra monorepo root. The file is gitignored and is loaded by Vitest and Docker Compose:
360
+
361
+ ```dotenv
362
+ ORACLE_DATABASE_USER=mastra
363
+ ORACLE_DATABASE_PASSWORD=<your-local-test-password>
364
+ ORACLE_DATABASE_CONNECT_STRING=localhost:1521/FREEPDB1
365
+ ```
366
+
367
+ Run unit tests and type checks from the monorepo root:
368
+
369
+ ```bash
370
+ pnpm --filter @mastra/oracledb test
371
+ pnpm --filter @mastra/oracledb typecheck
372
+ ```
373
+
374
+ Live Oracle integration tests are opt-in because they require Docker or Oracle Database credentials:
375
+
376
+ ```bash
377
+ pnpm --filter @mastra/oracledb test:integration
378
+ ```
379
+
380
+ The integration script starts an Oracle Database Free container with Docker Compose, creates the configured test user on the `USERS` tablespace, runs the shared storage and vector integration suites, and tears the container down afterward.
381
+
382
+ To use an existing Oracle database instead of the Docker Compose container, provide your own connection values and run the integration suites directly:
383
+
384
+ ```bash
385
+ export ORACLE_DATABASE_USER=...
386
+ export ORACLE_DATABASE_CONNECT_STRING=...
387
+ # Load ORACLE_DATABASE_PASSWORD from your environment or secret manager.
388
+
389
+ pnpm --filter @mastra/oracledb test:storage-integration
390
+ pnpm --filter @mastra/oracledb test:vector-integration
391
+ ```
392
+
393
+ ## Related Links
394
+
395
+ - [Oracle AI Vector Search](https://docs.oracle.com/en/database/oracle/oracle-database/23/vecse/)
396
+ - [Oracle Database Node.js Driver](https://node-oracledb.readthedocs.io/)
397
+ - [Mastra Storage Documentation](https://mastra.ai/en/docs/memory/storage)
398
+ - [Mastra Vector Database Documentation](https://mastra.ai/en/docs/rag/vector-databases)
@@ -0,0 +1,37 @@
1
+ ---
2
+ name: mastra-oracledb
3
+ description: Documentation for @mastra/oracledb. Use when working with @mastra/oracledb APIs, configuration, or implementation.
4
+ metadata:
5
+ package: "@mastra/oracledb"
6
+ version: "0.0.0-openai-schema-compat-issue-20260810211758"
7
+ ---
8
+
9
+ ## When to use
10
+
11
+ Use this skill whenever you are working with @mastra/oracledb to obtain the domain-specific knowledge.
12
+
13
+ ## How to use
14
+
15
+ Read the individual reference documents for detailed explanations and code examples.
16
+
17
+ ### Docs
18
+
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
+ - [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
+ - [Working memory](references/docs-memory-working-memory.md) - Learn how to configure working memory in Mastra to store persistent user data, preferences.
22
+ - [Storage overview](references/docs-storage-overview.md) - Configure storage for Mastra to persist runtime state across agents, workflows, observability, evals, schedules, and memory.
23
+
24
+ ### Guides
25
+
26
+ - [RAG (Retrieval-Augmented Generation) in Mastra](references/guides-rag-overview.md) - Overview of Retrieval-Augmented Generation (RAG) in Mastra, detailing its capabilities for enhancing LLM outputs with relevant context.
27
+ - [Retrieval, semantic search, reranking](references/guides-rag-retrieval.md) - Guide on retrieval processes in Mastra's RAG systems, including semantic search, filtering, and re-ranking.
28
+ - [Storing embeddings in a vector database](references/guides-rag-vector-databases.md) - Guide on vector storage options in Mastra, including embedded and dedicated vector databases for similarity search.
29
+
30
+ ### Reference
31
+
32
+ - [Reference: Metadata filters](references/reference-rag-metadata-filters.md) - Documentation for metadata filtering capabilities in Mastra, which allow for precise querying of vector search results across different vector stores.
33
+ - [Reference: OracleDB storage](references/reference-storage-oracledb.md) - Documentation for the Oracle Database storage provider in Mastra.
34
+ - [Reference: OracleDB vector store](references/reference-vectors-oracledb.md) - Documentation for the Oracle Database vector provider in Mastra.
35
+
36
+
37
+ Read [assets/SOURCE_MAP.json](assets/SOURCE_MAP.json) for source code references.
@@ -0,0 +1,6 @@
1
+ {
2
+ "version": "0.0.0-openai-schema-compat-issue-20260810211758",
3
+ "package": "@mastra/oracledb",
4
+ "exports": {},
5
+ "modules": {}
6
+ }