@mastra/rag 2.5.0-alpha.0 → 2.6.0-alpha.0

package/CHANGELOG.md

@@ -1,5 +1,53 @@
 # @mastra/rag
 
+## 2.6.0-alpha.0
+
+### Minor Changes
+
+- Added `serialize()` and `GraphRAG.deserialize()` so a knowledge graph can be saved and restored instead of rebuilt on every process start. Building a graph compares every chunk against every other chunk, which is slow for large document sets; now you can do that work once and reload the result. ([#21704](https://github.com/mastra-ai/mastra/pull/21704))
+
+  ```typescript
+  // Before: the graph had to be rebuilt every time
+  const graphRag = new GraphRAG(1536, 0.7);
+  graphRag.createGraph(documentChunks, embeddings);
+
+  // After: build once, save the snapshot, and reload it later
+  const snapshot = graphRag.serialize();
+  await writeFile('./graph.json', JSON.stringify(snapshot));
+
+  const restored = GraphRAG.deserialize(JSON.parse(await readFile('./graph.json', 'utf8')));
+  restored.query({ query: queryEmbedding, topK: 10 });
+  ```
+
+  A snapshot is plain JSON, so you can store it in any database, file, or cache you already use. Loading a snapshot that does not match the graph's embedding dimension now fails immediately with a clear error instead of later during a query. Closes #3926.
+
+### Patch Changes
+
+- Updated dependencies [[`b0a2a07`](https://github.com/mastra-ai/mastra/commit/b0a2a07800d42bd9823292e7db832374ed084c9c), [`ccbbcd9`](https://github.com/mastra-ai/mastra/commit/ccbbcd974eedff4367a54ed0e24c9ee742ab2f61), [`3f5c6f7`](https://github.com/mastra-ai/mastra/commit/3f5c6f728ea35da344248de9aa070f12849f3aa0), [`77e6b1b`](https://github.com/mastra-ai/mastra/commit/77e6b1bc4c46ce94fe501023fb4393c812ec6be3), [`2e1d098`](https://github.com/mastra-ai/mastra/commit/2e1d0984e325fd319d32ea182f596b3170be3847)]:
+  - @mastra/core@1.60.0-alpha.9
+
+## 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.6.0-alpha.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.6.0-alpha.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',
 })
 ```
 
@@ -125,55 +127,50 @@ const { embeddings } = await embedMany({
 })
 ```
 
-> **Vector Database Compatibility:** When storing embeddings, the vector database index must be configured to match the output size of your embedding model. If the dimensions don't match, you may get errors or data corruption.
+> **Vector Database Compatibility:** When storing embeddings, configure the vector database index to match the output size of your embedding model to avoid errors or data corruption from mismatched dimensions.
 
 ## 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/reference-rag-graph-rag.md

@@ -9,10 +9,7 @@ The `GraphRAG` class implements a graph-based approach to retrieval augmented ge
 ```typescript
 import { GraphRAG } from '@mastra/rag'
 
-const graphRag = new GraphRAG({
-  dimension: 1536,
-  threshold: 0.7,
-})
+const graphRag = new GraphRAG(1536, 0.7)
 
 // Create the graph from chunks and embeddings
 graphRag.createGraph(documentChunks, embeddings)
@@ -88,13 +85,79 @@ Returns an array of `RankedNode` objects, where each node contains:
 
 **score** (`number`): Combined relevance score from graph traversal
 
+### `serialize`
+
+Returns a JSON-safe snapshot of the graph so it can be persisted and restored later instead of rebuilt with `createGraph`.
+
+```typescript
+serialize(): GraphRAGSnapshot
+```
+
+#### Returns
+
+Returns a `GraphRAGSnapshot` object containing:
+
+**version** (`number`): Snapshot format version, used to reject snapshots this version of the class can't load
+
+**dimension** (`number`): Dimension of the embedding vectors the graph was built with
+
+**threshold** (`number`): Similarity threshold the graph was built with
+
+**nodes** (`GraphNode[]`): All nodes in the graph, each including its full embedding
+
+**edges** (`GraphEdge[]`): All edges in the graph
+
+The snapshot is a deep copy, so mutating it doesn't affect the graph it came from. Every node carries its full embedding, so snapshots are large: a 1,000-node graph built with 1536-dimension embeddings serializes to about 20 MB of JSON. Size your storage column accordingly.
+
+### `deserialize`
+
+Rebuilds a `GraphRAG` instance from a snapshot produced by `serialize`.
+
+```typescript
+static deserialize(snapshot: GraphRAGSnapshot): GraphRAG
+```
+
+#### Parameters
+
+**snapshot** (`GraphRAGSnapshot`): A snapshot previously returned by serialize
+
+Throws if the snapshot version is unsupported, if a node embedding doesn't match the snapshot dimension, or if an edge references a node that isn't in the snapshot. A bad snapshot therefore fails at load time instead of during a later query.
+
+## Persisting a graph
+
+Building a graph is O(n²) in the number of chunks, so rebuilding it on every process start is wasteful. Serialize the graph once and store the snapshot wherever you already keep state. A snapshot is plain JSON, so any store works (a file, a blob column, a key-value cache), and `GraphRAG` doesn't depend on a storage backend.
+
+```typescript
+import { readFile, writeFile } from 'node:fs/promises'
+import { GraphRAG } from '@mastra/rag'
+import type { GraphRAGSnapshot } from '@mastra/rag'
+
+const SNAPSHOT_PATH = './docs-graph.json'
+
+async function loadOrBuildGraph() {
+  try {
+    const snapshot = JSON.parse(await readFile(SNAPSHOT_PATH, 'utf8')) as GraphRAGSnapshot
+    return GraphRAG.deserialize(snapshot)
+  } catch {
+    // No usable snapshot yet, so build the graph from scratch
+  }
+
+  const graphRag = new GraphRAG(1536, 0.7)
+  graphRag.createGraph(documentChunks, embeddings)
+
+  await writeFile(SNAPSHOT_PATH, JSON.stringify(graphRag.serialize()))
+
+  return graphRag
+}
+```
+
+A snapshot reflects the chunks it was built from and isn't updated incrementally. When the underlying documents change, build the graph again and store a new snapshot.
+
 ## Advanced example
 
 ```typescript
-const graphRag = new GraphRAG({
-  dimension: 1536,
-  threshold: 0.8, // Stricter similarity threshold
-})
+// Stricter similarity threshold
+const graphRag = new GraphRAG(1536, 0.8)
 
 // Create graph from chunks and embeddings
 graphRag.createGraph(documentChunks, embeddings)

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-tools-bedrock-kb-tool.md

@@ -65,7 +65,7 @@ The tool returns an object with:
 | ---------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
 | `content`  | `string`                  | The text content of the retrieved passage.                                                                                            |
 | `source`   | `string \| undefined`     | The source URI when Bedrock provides one. Agentic retrieval only includes this field when the result metadata contains `_source_uri`. |
-| `score`    | `number \| undefined`     | The relevance score returned by standard retrieval. The agentic API doesn't return a score for result items.                          |
+| `score`    | `number \| undefined`     | The relevance score returned by standard retrieval, which the agentic API omits from result items.                                    |
 | `metadata` | `Record<string, unknown>` | Additional metadata from the retrieval result.                                                                                        |
 
 ## Retrieval Modes

package/dist/docs/references/reference-tools-vector-query-tool.md

@@ -353,7 +353,7 @@ const response = await agent.generate('Find information about deployment', {
 })
 ```
 
-This approach allows you to:
+Runtime configuration supports these use cases:
 
 - Switch between environments (dev/staging/prod)
 - Adjust performance parameters based on load