@mastra/rag 2.5.0-alpha.0 → 2.5.0

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # @mastra/rag
 
+## 2.5.0
+
+### Minor Changes
+
+- Added Amazon Bedrock Knowledge Base tool (`createBedrockKBTool`) to @mastra/rag. Enables document retrieval from Bedrock Managed Knowledge Bases with agentic retrieval and automatic fallback. ([#19521](https://github.com/mastra-ai/mastra/pull/19521))
+
+  ```typescript
+  import { createBedrockKBTool } from '@mastra/rag';
+
+  const tool = createBedrockKBTool({
+    knowledgeBaseId: 'YOUR_KB_ID',
+    region: 'us-west-2',
+  });
+
+  const results = await tool.execute({ queryText: 'What is RAG?' });
+  ```
+
+### Patch Changes
+
+- 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)]:
+  - @mastra/core@1.58.0
+
 ## 2.5.0-alpha.0
 
 ### Minor Changes

package/dist/docs/SKILL.md

@@ -3,7 +3,7 @@ name: mastra-rag
 description: Documentation for @mastra/rag. Use when working with @mastra/rag APIs, configuration, or implementation.
 metadata:
   package: "@mastra/rag"
-  version: "2.5.0-alpha.0"
+  version: "2.5.0"
 ---
 
 ## When to use
@@ -14,26 +14,25 @@ Use this skill whenever you are working with @mastra/rag to obtain the domain-sp
 
 Read the individual reference documents for detailed explanations and code examples.
 
-### Guides
-
-- [Chunking and embedding documents](references/guides-rag-chunking-and-embedding.md) - Guide on chunking and embedding documents in Mastra for efficient processing and retrieval.
-- [GraphRAG](references/guides-rag-graph-rag.md) - Guide on graph-based retrieval in Mastra's RAG systems for documents with complex relationships.
-- [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.
-- [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.
-
 ### Reference
 
+- [RAG](references/reference-migrations-upgrade-to-v1-rag.md) - Migrate RAG-related breaking changes when upgrading to v1.
 - [Reference: .chunk()](references/reference-rag-chunk.md) - Documentation for the chunk function in Mastra, which splits documents into smaller segments using various strategies.
+- [Chunking and embedding documents](references/reference-rag-chunking-and-embedding.md) - Guide on chunking and embedding documents in Mastra for efficient processing and retrieval.
 - [Reference: DatabaseConfig](references/reference-rag-database-config.md) - API reference for database-specific configuration types used with vector query tools in Mastra RAG systems.
 - [Reference: MDocument](references/reference-rag-document.md) - Documentation for the MDocument class in Mastra, which handles document processing and chunking.
 - [Reference: ExtractParams](references/reference-rag-extract-params.md) - Documentation for metadata extraction configuration in Mastra.
 - [Reference: GraphRAG](references/reference-rag-graph-rag.md) - Documentation for the GraphRAG class in Mastra, which implements a graph-based approach to retrieval augmented generation.
+- [GraphRAG](references/reference-rag-graph-rag-guide.md) - Guide on graph-based retrieval in Mastra's RAG systems for documents with complex relationships.
+- [RAG (Retrieval-Augmented Generation) in Mastra](references/reference-rag-overview.md) - Overview of Retrieval-Augmented Generation (RAG) in Mastra, detailing its capabilities for enhancing LLM outputs with relevant context.
 - [Reference: rerank()](references/reference-rag-rerank.md) - Documentation for the rerank function in Mastra, which provides advanced reranking capabilities for vector search results.
 - [Reference: rerankWithScorer()](references/reference-rag-rerankWithScorer.md) - Documentation for the rerank function in Mastra, which provides advanced reranking capabilities for vector search results.
+- [Retrieval, semantic search, reranking](references/reference-rag-retrieval.md) - Guide on retrieval processes in Mastra's RAG systems, including semantic search, filtering, and re-ranking.
 - [Reference: createBedrockKBTool()](references/reference-tools-bedrock-kb-tool.md) - Documentation for the Bedrock Knowledge Base Tool in Mastra, which retrieves documents from Amazon Bedrock Knowledge Bases with agentic retrieval support.
 - [Reference: createDocumentChunkerTool()](references/reference-tools-document-chunker-tool.md) - Documentation for the Document Chunker Tool in Mastra, which splits documents into smaller chunks for efficient processing and retrieval.
 - [Reference: createGraphRAGTool()](references/reference-tools-graph-rag-tool.md) - Documentation for the GraphRAG Tool in Mastra, which enhances RAG by building a graph of semantic relationships between documents.
 - [Reference: createVectorQueryTool()](references/reference-tools-vector-query-tool.md) - Documentation for the Vector Query Tool in Mastra, which facilitates semantic search over vector stores with filtering and reranking capabilities.
+- [Reference: OracleDB vector store](references/reference-vectors-oracledb.md) - Documentation for the Oracle Database vector provider in Mastra.
 
 
 Read [assets/SOURCE_MAP.json](assets/SOURCE_MAP.json) for source code references.

package/dist/docs/assets/SOURCE_MAP.json

@@ -1,5 +1,5 @@
 {
-  "version": "2.5.0-alpha.0",
+  "version": "2.5.0",
   "package": "@mastra/rag",
   "exports": {},
   "modules": {}

package/dist/docs/references/reference-migrations-upgrade-to-v1-rag.md

@@ -0,0 +1,44 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# RAG
+
+The RAG package has renamed chunking parameters and narrowed their types.
+
+## Changed
+
+### `keepSeparator` to `separatorPosition`
+
+The `keepSeparator` parameter has been renamed to `separatorPosition` with a simplified type. The old parameter had a confusing `boolean | 'start' | 'end'` type where `true` was secretly an alias for `'start'`. The new parameter uses explicit `'start' | 'end'` values, and omitting the parameter discards the separator.
+
+To migrate, replace `keepSeparator` with `separatorPosition` using the mapping below:
+
+| Old value                | New value                    |
+| ------------------------ | ---------------------------- |
+| `keepSeparator: true`    | `separatorPosition: 'start'` |
+| `keepSeparator: 'start'` | `separatorPosition: 'start'` |
+| `keepSeparator: 'end'`   | `separatorPosition: 'end'`   |
+| `keepSeparator: false`   | Remove the parameter         |
+| Parameter omitted        | No change needed             |
+
+```diff
+await doc.chunk({
+    strategy: 'character',
+    separator: '.',
+-   keepSeparator: true,
++   separatorPosition: 'start',
+  });
+
+  await doc.chunk({
+    strategy: 'character',
+    separator: '.',
+-   keepSeparator: 'end',
++   separatorPosition: 'end',
+  });
+
+  await doc.chunk({
+    strategy: 'character',
+    separator: '.',
+-   keepSeparator: false,
++   // Parameter removed - separator is discarded by default
+  });
+```

package/dist/docs/references/{guides-rag-chunking-and-embedding.md → reference-rag-chunking-and-embedding.md}

@@ -5,7 +5,9 @@
 Before processing, create a MDocument instance from your content. You can initialize it from different formats:
 
 ```ts
-const docFromText = MDocument.fromText('Your plain text content...')
+import { MDocument } from '@mastra/rag'
+
+const doc = MDocument.fromText('Your plain text content...')
 const docFromHTML = MDocument.fromHTML('<html>Your HTML content...</html>')
 const docFromMarkdown = MDocument.fromMarkdown('# Your Markdown content...')
 const docFromJSON = MDocument.fromJSON(`{ "key": "value" }`)
@@ -59,7 +61,7 @@ For markdown documents where preserving the semantic relationships between secti
 const chunks = await doc.chunk({
   strategy: 'semantic-markdown',
   joinThreshold: 500,
-  modelName: 'gpt-3.5-turbo',
+  modelName: 'gpt-5',
 })
 ```
 
@@ -129,51 +131,46 @@ const { embeddings } = await embedMany({
 
 ## Example: Complete pipeline
 
-Here's an example showing document processing and embedding generation with both providers:
+Here's an example showing document processing, embedding generation, and vector storage:
 
 ```ts
-import { embedMany } from 'ai'
-
+import { ModelRouterEmbeddingModel } from '@mastra/core/llm'
+import { PgVector } from '@mastra/pg'
 import { MDocument } from '@mastra/rag'
+import { embedMany } from 'ai'
 
-// Initialize document
 const doc = MDocument.fromText(`
   Climate change poses significant challenges to global agriculture.
   Rising temperatures and changing precipitation patterns affect crop yields.
 `)
 
-// Create chunks
 const chunks = await doc.chunk({
   strategy: 'recursive',
   maxSize: 256,
   overlap: 50,
 })
 
-// Generate embeddings with OpenAI
-import { ModelRouterEmbeddingModel } from '@mastra/core/llm'
-
 const { embeddings } = await embedMany({
   model: new ModelRouterEmbeddingModel('openai/text-embedding-3-small'),
   values: chunks.map(chunk => chunk.text),
 })
 
-// OR
+const vectorStore = new PgVector({
+  id: 'pg-vector',
+  connectionString: process.env.POSTGRES_CONNECTION_STRING,
+})
 
-// Generate embeddings with Cohere
-const { embeddings } = await embedMany({
-  model: 'cohere/embed-english-v3.0',
-  values: chunks.map(chunk => chunk.text),
+await vectorStore.createIndex({
+  indexName: 'embeddings',
+  dimension: 1536,
 })
 
-// Store embeddings in your vector database
 await vectorStore.upsert({
   indexName: 'embeddings',
   vectors: embeddings,
 })
 ```
 
-##
-
 For more examples of different chunking strategies and embedding configurations, see:
 
 - [Chunk Reference](https://mastra.ai/reference/rag/chunk)
@@ -181,5 +178,5 @@ For more examples of different chunking strategies and embedding configurations,
 
 For more details on vector databases and embeddings, see:
 
-- [Vector Databases](https://mastra.ai/guides/rag/vector-databases)
+- [Vector Databases](https://mastra.ai/reference/rag/vector-databases)
 - [Embedding API Reference](https://mastra.ai/reference/rag/embeddings)

package/dist/docs/references/reference-rag-database-config.md

@@ -275,5 +275,5 @@ const vectorTool = createVectorQueryTool({
 ## Related
 
 - [createVectorQueryTool()](https://mastra.ai/reference/tools/vector-query-tool)
-- [Hybrid Vector Search](https://mastra.ai/guides/rag/retrieval)
+- [Hybrid Vector Search](https://mastra.ai/reference/rag/retrieval)
 - [Metadata Filters](https://mastra.ai/reference/rag/metadata-filters)

package/dist/docs/references/{guides-rag-graph-rag.md → reference-rag-graph-rag-guide.md}

@@ -14,7 +14,7 @@ GraphRAG is particularly effective when:
 - Understanding connections between concepts is important
 - Simple vector similarity misses important contextual relationships
 
-For straightforward semantic search without relationship traversal, use [standard retrieval methods](https://mastra.ai/guides/rag/retrieval).
+For straightforward semantic search without relationship traversal, use [standard retrieval methods](https://mastra.ai/reference/rag/retrieval).
 
 ## How GraphRAG works
 

package/dist/docs/references/{guides-rag-overview.md → reference-rag-overview.md}

@@ -63,11 +63,11 @@ This example shows the essentials. Initialize a document and create chunks, then
 
 ## Document processing
 
-The basic building block of RAG is document processing. Documents can be chunked using strategies (recursive, sliding window, etc.) and enriched with metadata. See the [chunking and embedding doc](https://mastra.ai/guides/rag/chunking-and-embedding).
+The basic building block of RAG is document processing. Documents can be chunked using strategies (recursive, sliding window, etc.) and enriched with metadata. See the [chunking and embedding doc](https://mastra.ai/reference/rag/chunking-and-embedding).
 
 ## Vector storage
 
-Mastra supports multiple vector stores for embedding persistence and similarity search, including pgvector, Pinecone, Qdrant, and MongoDB. See the [vector database doc](https://mastra.ai/guides/rag/vector-databases).
+Mastra supports multiple vector stores for embedding persistence and similarity search, including pgvector, OracleDB, Pinecone, Qdrant, and MongoDB. See the [vector database doc](https://mastra.ai/reference/rag/vector-databases).
 
 ## More resources
 

package/dist/docs/references/{guides-rag-retrieval.md → reference-rag-retrieval.md}

@@ -436,6 +436,23 @@ export const ragAgent = new Agent({
 })
 ```
 
+**OracleDB**:
+
+```ts
+import { ORACLEDB_PROMPT } from '@mastra/oracledb'
+
+export const ragAgent = new Agent({
+  id: 'rag-agent',
+  name: 'RAG Agent',
+  model: 'openai/gpt-5.6-sol',
+  instructions: `
+  Process queries using the provided context. Structure responses to be concise and relevant.
+  ${ORACLEDB_PROMPT}
+  `,
+  tools: { vectorQueryTool },
+})
+```
+
 **S3Vectors**:
 
 ```ts
@@ -517,4 +534,4 @@ The re-ranked results combine vector similarity with semantic understanding to i
 
 For more details about re-ranking, see the [rerank()](https://mastra.ai/reference/rag/rerankWithScorer) method.
 
-For graph-based retrieval that follows connections between chunks, see the [GraphRAG](https://mastra.ai/guides/rag/graph-rag) documentation.
+For graph-based retrieval that follows connections between chunks, see the [GraphRAG](https://mastra.ai/reference/rag/graph-rag-guide) documentation.

package/dist/docs/references/reference-vectors-oracledb.md

@@ -0,0 +1,347 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# OracleDB vector store
+
+`OracleVector` stores embeddings in Oracle Database `VECTOR` columns and exposes them through Mastra's vector interface. Each logical Mastra vector index is mapped to an Oracle vector table through a registry table, while metadata is stored as Oracle JSON for structured filtering.
+
+## Installation
+
+**npm**:
+
+```bash
+npm install @mastra/oracledb@latest
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/oracledb@latest
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/oracledb@latest
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/oracledb@latest
+```
+
+## Usage
+
+```ts
+import { OracleVector } from '@mastra/oracledb'
+
+const vector = new OracleVector({
+  id: 'oracle-vector',
+  user: process.env.ORACLE_DATABASE_USER,
+  password: process.env.ORACLE_DATABASE_PASSWORD,
+  connectString: process.env.ORACLE_DATABASE_CONNECT_STRING,
+})
+
+await vector.createIndex({
+  indexName: 'memory_messages',
+  dimension: 1536,
+  metric: 'cosine',
+})
+
+await vector.upsert({
+  indexName: 'memory_messages',
+  vectors: [embedding],
+  metadata: [{ resource_id: 'user-1', thread_id: 'thread-1' }],
+})
+
+const results = await vector.query({
+  indexName: 'memory_messages',
+  queryVector,
+  topK: 5,
+  filter: { resource_id: 'user-1' },
+})
+```
+
+By default, `OracleVector` uses exact search with no approximate vector index. Configure IVF or HNSW when your dataset and latency requirements need approximate search.
+
+## Constructor options
+
+Pass Oracle connection options (`user`, `password`, `connectString`, `pool`, wallet options, or `externalAuth`) directly, or pass `poolManager` to share the pool used by `OracleStore`. The vector-specific options are:
+
+**id** (`string`): Unique identifier for this vector store instance.
+
+**poolManager** (`OraclePoolManager`): Shared Oracle pool manager. Use this to share one Oracle pool with OracleStore.
+
+**schemaName** (`string`): Oracle schema name used to qualify the vector registry and vector tables.
+
+**tablePrefix** (`string`): Prefix used for physical Oracle vector tables. (Default: `'MASTRA_VEC'`)
+
+**registryTableName** (`string`): Oracle table used to map Mastra logical index names to physical vector tables. (Default: `'MASTRA_VECTOR_INDEXES'`)
+
+**defaultIndexConfig** (`OracleVectorIndexConfig`): Default Oracle vector index configuration. (Default: `{ type: 'none', accuracy: 95 }`)
+
+**defaultMetadataIndexes** (`string[]`): Metadata fields to index automatically when vector tables are created. (Default: `['thread_id', 'resource_id', 'message_id', 'source_id']`)
+
+**defaultVectorFormat** (`'vector' | 'bit' | 'int8'`): Default Oracle vector format for dense, binary, and int8 embeddings. (Default: `'vector'`)
+
+**upsertBatchSize** (`number`): Number of vectors sent per Oracle executeMany call. The full upsert commits once after all batches succeed. (Default: `200`)
+
+## Constructor examples
+
+### Shared pool with OracleStore
+
+```ts
+import { OracleStore, OracleVector } from '@mastra/oracledb'
+
+const storage = new OracleStore({ id: 'oracle-storage', user, password, connectString })
+
+const vector = new OracleVector({
+  id: 'oracle-vector',
+  poolManager: storage.getPoolManager(),
+})
+```
+
+For Autonomous Database and mTLS connections, pass `walletLocation`, `walletPassword`, and `configDir` in the same constructor.
+
+## Methods
+
+### `createIndex()`
+
+Creates the registry row, physical Oracle vector table, metadata indexes, and optionally an Oracle vector index.
+
+**indexName** (`string`): Logical Mastra index name. The provider maps this to a valid Oracle table name internally.
+
+**dimension** (`number`): Vector dimension. This must match the embedding model output size.
+
+**metric** (`'cosine' | 'euclidean' | 'dotproduct' | 'hamming' | 'jaccard'`): Distance metric for similarity search. Binary vectors support hamming and jaccard. (Default: `cosine`)
+
+**vectorFormat** (`'vector' | 'bit' | 'int8'`): Oracle vector storage format. (Default: `vector`)
+
+**indexConfig** (`OracleVectorIndexConfig`): Oracle vector index configuration. none means exact search with no approximate vector index. (Default: `{ type: 'none', accuracy: 95 }`)
+
+**buildIndex** (`boolean`): Whether to build the Oracle vector index when indexConfig.type is ivf or hnsw. (Default: `true`)
+
+**metadataIndexes** (`string[]`): Metadata field names to index for faster JSON metadata filtering.
+
+#### `OracleVectorIndexConfig`
+
+**type** (`'none' | 'ivf' | 'hnsw'`): Oracle vector index type. (Default: `'none'`)
+
+**accuracy** (`number`): Target accuracy for approximate vector search. (Default: `95`)
+
+**ivf.neighborPartitions** (`number`): Oracle IVF neighbor partitions setting.
+
+**hnsw\.neighbors** (`number`): Oracle HNSW neighbor setting.
+
+**hnsw\.efConstruction** (`number`): Oracle HNSW build-time construction setting.
+
+#### Index configuration
+
+```ts
+await vector.createIndex({
+  indexName: 'support_articles',
+  dimension: 1536,
+  metric: 'cosine',
+  indexConfig: {
+    type: 'ivf',
+    accuracy: 95,
+    ivf: {
+      neighborPartitions: 32,
+    },
+  },
+})
+```
+
+The default is `indexConfig: { type: 'none' }`, which uses exact search and requires no approximate index tuning. Use IVF or HNSW only when your data volume and latency requirements justify approximate search. HNSW is configured with `indexConfig: { type: 'hnsw', hnsw: { neighbors, efConstruction } }` and requires Oracle Vector Pool memory, which `configureVectorMemory()` can allocate for local or self-managed databases.
+
+### `upsert()`
+
+**indexName** (`string`): Name of the index to upsert vectors into.
+
+**vectors** (`number[][]`): Array of embedding vectors.
+
+**metadata** (`Record<string, any>[]`): Metadata stored as Oracle JSON. Must align by position with vectors.
+
+**ids** (`string[]`): Optional vector IDs. IDs are generated when omitted.
+
+### `query()`
+
+**indexName** (`string`): Name of the index to query.
+
+**queryVector** (`number[]`): Query vector.
+
+**topK** (`number`): Number of results to return. (Default: `10`)
+
+**filter** (`Record<string, any>`): Mastra metadata filter translated to Oracle JSON predicates.
+
+**includeVector** (`boolean`): Whether to include the vector in each result. (Default: `false`)
+
+**minScore** (`number`): Minimum similarity score threshold. (Default: `-1`)
+
+**queryMode** (`'exact' | 'approx'`): Oracle query mode. Exact search is used by default when no approximate vector index is configured.
+
+**targetAccuracy** (`number`): Target accuracy for approximate Oracle vector queries.
+
+### `listIndexes()`
+
+Returns the logical Mastra index names recorded in the Oracle vector registry table.
+
+### `describeIndex()`
+
+Returns Oracle index metadata, including the physical table name, dimension, vector count, metric, index type, vector format, and configured accuracy.
+
+### `deleteIndex()`
+
+Deletes the Oracle vector table and removes the registry entry for the logical index.
+
+### `updateVector()`
+
+Update vectors by ID or metadata filter. Either `id` or `filter` must be provided, but not both. The `update` object may include `vector`, `metadata`, or both.
+
+```ts
+await vector.updateVector({
+  indexName: 'support_articles',
+  id: 'doc-1',
+  update: { metadata: { status: 'reviewed' } },
+})
+```
+
+### `deleteVector()`
+
+Deletes a single vector by ID.
+
+### `deleteVectors()`
+
+Deletes multiple vectors by IDs or by metadata filter. Either `ids` or `filter` must be provided, but not both.
+
+### `buildIndex()`
+
+Builds an Oracle vector index for an existing logical index. If the resolved index type is `none`, this method is a no-op.
+
+### `rebuildIndex()`
+
+Drops and recreates the Oracle vector index for an existing logical index, typically after changing approximate-index tuning.
+
+### Index diagnostics
+
+Use `getIndexStatus({ indexName })` to inspect Oracle catalog status, and `indexAccuracyQuery({ indexName, queryVector, topK, targetAccuracy })` to run `DBMS_VECTOR.INDEX_ACCURACY_QUERY` for approximate indexes.
+
+### `configureVectorMemory()`
+
+Allocates Oracle Vector Pool memory, which HNSW indexes require. This calls `ALTER SYSTEM SET VECTOR_MEMORY_SIZE`, so it requires a privileged connection such as `SYSDBA` or `SYSTEM`.
+
+**size** (`string`): Vector pool size, as an integer optionally followed by K, M, or G (for example "512M").
+
+**scope** (`'MEMORY' | 'SPFILE' | 'BOTH'`): Oracle ALTER SYSTEM scope. Use 'SPFILE' or 'BOTH' so the setting survives a database restart. (Default: `'MEMORY'`)
+
+### `disconnect()`
+
+Closes the Oracle pool when `OracleVector` created the pool manager. If you provide `pool` or `poolManager`, you own that lifecycle.
+
+## Metadata filters
+
+`OracleVector` accepts Mastra's standard metadata filter syntax. Filters are translated into Oracle JSON predicates with bound values:
+
+- scalar comparisons use `JSON_VALUE`
+- array, existence, and element-match checks use `JSON_EXISTS`
+- regex filters use `REGEXP_LIKE`
+- string contains filters use case-insensitive `LIKE`
+
+```ts
+const results = await vector.query({
+  indexName: 'memory_messages',
+  queryVector,
+  topK: 5,
+  filter: {
+    resource_id: 'user-1',
+    tags: { $contains: 'support' },
+    score: { $gte: 0.8 },
+    $or: [{ source: 'docs' }, { source: 'tickets' }],
+  },
+})
+```
+
+Metadata is stored as native Oracle JSON, so the rows are also readable directly with standard Oracle JDBC tools such as DBeaver and SQL Developer.
+
+Use `ORACLEDB_PROMPT` when an agent should generate Oracle-compatible metadata filters for `createVectorQueryTool()`:
+
+```ts
+import { Agent } from '@mastra/core/agent'
+import { createVectorQueryTool } from '@mastra/rag'
+import { fastembed } from '@mastra/fastembed'
+import { ORACLEDB_PROMPT } from '@mastra/oracledb'
+
+const vectorQueryTool = createVectorQueryTool({
+  vectorStoreName: 'oracle',
+  indexName: 'support_articles',
+  model: fastembed,
+  enableFilter: true,
+})
+
+export const ragAgent = new Agent({
+  id: 'oracle-rag-agent',
+  name: 'Oracle RAG Agent',
+  model: 'openai/gpt-5.6-sol',
+  instructions: `
+Use the retrieval tool when you need source context.
+Available metadata fields: resource_id, thread_id, source, category, tags.
+${ORACLEDB_PROMPT}
+`,
+  tools: { vectorQueryTool },
+})
+```
+
+## Response types
+
+Query results are returned in this format:
+
+```ts
+interface QueryResult {
+  id: string
+  score: number
+  metadata: Record<string, any>
+  vector?: number[]
+}
+```
+
+## Usage example
+
+```ts
+import { Agent } from '@mastra/core/agent'
+import { Memory } from '@mastra/memory'
+import { fastembed } from '@mastra/fastembed'
+import { OracleStore, OracleVector } from '@mastra/oracledb'
+
+const storage = new OracleStore({
+  id: 'oracle-storage',
+  user: process.env.ORACLE_DATABASE_USER,
+  password: process.env.ORACLE_DATABASE_PASSWORD,
+  connectString: process.env.ORACLE_DATABASE_CONNECT_STRING,
+})
+
+const vector = new OracleVector({
+  id: 'oracle-vector',
+  poolManager: storage.getPoolManager(),
+})
+
+export const oracleAgent = new Agent({
+  id: 'oracle-agent',
+  name: 'Oracle Agent',
+  instructions: 'You are an assistant with OracleDB-backed memory and semantic recall.',
+  model: 'openai/gpt-5.6-sol',
+  memory: new Memory({
+    storage,
+    vector,
+    embedder: fastembed,
+    options: {
+      semanticRecall: { topK: 3, messageRange: 2 },
+    },
+  }),
+})
+```
+
+## Related
+
+- [OracleDB storage](https://mastra.ai/integrations/databases/oracledb)
+- [Metadata Filters](https://mastra.ai/reference/rag/metadata-filters)
+- [Vector databases](https://mastra.ai/reference/rag/vector-databases)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/rag",
-  "version": "2.5.0-alpha.0",
+  "version": "2.5.0",
   "description": "",
   "type": "module",
   "main": "dist/index.js",
@@ -51,10 +51,10 @@
     "typescript": "^6.0.3",
     "vitest": "4.1.10",
     "zod": "^4.4.3",
-    "@internal/lint": "0.0.121",
-    "@internal/ai-sdk-v4": "0.0.68",
-    "@internal/types-builder": "0.0.96",
-    "@mastra/core": "1.58.0-alpha.3"
+    "@internal/ai-sdk-v4": "0.0.69",
+    "@internal/types-builder": "0.0.97",
+    "@internal/lint": "0.0.122",
+    "@mastra/core": "1.58.0"
   },
   "keywords": [
     "rag",