@mastra/rag 2.5.0 → 2.6.0-alpha.0

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # @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

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"
+  version: "2.6.0-alpha.0"
 ---
 
 ## When to use

package/dist/docs/assets/SOURCE_MAP.json

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

package/dist/docs/references/reference-rag-chunking-and-embedding.md

@@ -127,7 +127,7 @@ 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
 

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/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

package/dist/graph-rag/index.d.ts

@@ -29,6 +29,17 @@ export interface GraphChunk {
 export interface GraphEmbedding {
     vector: number[];
 }
+/**
+ * JSON-safe snapshot of a GraphRAG instance, produced by `serialize()` and
+ * restored with `GraphRAG.deserialize()`.
+ */
+export interface GraphRAGSnapshot {
+    version: 1;
+    dimension: number;
+    threshold: number;
+    nodes: GraphNode[];
+    edges: GraphEdge[];
+}
 export declare class GraphRAG {
     private nodes;
     private edges;
@@ -40,6 +51,23 @@ export declare class GraphRAG {
     getNodes(): GraphNode[];
     getEdges(): GraphEdge[];
     getEdgesByType(type: string): GraphEdge[];
+    /**
+     * Produce a JSON-safe snapshot of the graph so it can be persisted and
+     * restored later instead of rebuilt with `createGraph`.
+     *
+     * The snapshot is a deep copy, including nested node metadata, so mutating it
+     * does not affect this instance.
+     * Note that every node carries its full embedding, so snapshots of large
+     * graphs can be several megabytes of JSON.
+     */
+    serialize(): GraphRAGSnapshot;
+    /**
+     * Rebuild a GraphRAG instance from a snapshot produced by `serialize()`.
+     *
+     * @throws if the snapshot version is unsupported, a node embedding does not
+     * match the snapshot dimension, or an edge references an unknown node.
+     */
+    static deserialize(snapshot: GraphRAGSnapshot): GraphRAG;
     clear(): void;
     updateNodeContent(id: string, newContent: string): void;
     private getNeighbors;

package/dist/graph-rag/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/graph-rag/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,KAAK,iBAAiB,GAAG,UAAU,CAAC;AACpC,KAAK,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;AAGzC,MAAM,WAAW,SAAS;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,QAAQ,CAAC,EAAE,aAAa,CAAC;CAC1B;AAED,MAAM,WAAW,UAAW,SAAQ,SAAS;IAC3C,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,SAAS;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,iBAAiB,CAAC;CACzB;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CAC/B;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,qBAAa,QAAQ;IACnB,OAAO,CAAC,KAAK,CAAyB;IACtC,OAAO,CAAC,KAAK,CAAc;IAC3B,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,SAAS,CAAS;gBAEd,SAAS,GAAE,MAAa,EAAE,SAAS,GAAE,MAAY;IAQ7D,OAAO,CAAC,IAAI,EAAE,SAAS,GAAG,IAAI;IAW9B,OAAO,CAAC,IAAI,EAAE,SAAS,GAAG,IAAI;IAe9B,QAAQ,IAAI,SAAS,EAAE;IAKvB,QAAQ,IAAI,SAAS,EAAE;IAIvB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,EAAE;IAIzC,KAAK,IAAI,IAAI;IAKb,iBAAiB,CAAC,EAAE,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI;IASvD,OAAO,CAAC,YAAY;IAWpB,OAAO,CAAC,gBAAgB;IAgCxB,WAAW,CAAC,MAAM,EAAE,UAAU,EAAE,EAAE,UAAU,EAAE,cAAc,EAAE;IAuC9D,OAAO,CAAC,sBAAsB;IAoB9B,OAAO,CAAC,qBAAqB;IA2C7B;;;;;;;;OAQG;IAEH,KAAK,CAAC,EACJ,KAAK,EACL,IAAS,EACT,eAAqB,EACrB,WAAkB,EAClB,MAAM,GACP,EAAE;QACD,KAAK,EAAE,MAAM,EAAE,CAAC;QAChB,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,eAAe,CAAC,EAAE,MAAM,CAAC;QACzB,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,MAAM,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,CAAC;KACjC,GAAG,UAAU,EAAE;CA+DjB"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/graph-rag/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,KAAK,iBAAiB,GAAG,UAAU,CAAC;AACpC,KAAK,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;AAGzC,MAAM,WAAW,SAAS;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,QAAQ,CAAC,EAAE,aAAa,CAAC;CAC1B;AAED,MAAM,WAAW,UAAW,SAAQ,SAAS;IAC3C,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,SAAS;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,iBAAiB,CAAC;CACzB;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CAC/B;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,CAAC,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,SAAS,EAAE,CAAC;IACnB,KAAK,EAAE,SAAS,EAAE,CAAC;CACpB;AAID,qBAAa,QAAQ;IACnB,OAAO,CAAC,KAAK,CAAyB;IACtC,OAAO,CAAC,KAAK,CAAc;IAC3B,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,SAAS,CAAS;gBAEd,SAAS,GAAE,MAAa,EAAE,SAAS,GAAE,MAAY;IAQ7D,OAAO,CAAC,IAAI,EAAE,SAAS,GAAG,IAAI;IAW9B,OAAO,CAAC,IAAI,EAAE,SAAS,GAAG,IAAI;IAe9B,QAAQ,IAAI,SAAS,EAAE;IAKvB,QAAQ,IAAI,SAAS,EAAE;IAIvB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,EAAE;IAIzC;;;;;;;;OAQG;IACH,SAAS,IAAI,gBAAgB;IAc7B;;;;;OAKG;IACH,MAAM,CAAC,WAAW,CAAC,QAAQ,EAAE,gBAAgB,GAAG,QAAQ;IAiCxD,KAAK,IAAI,IAAI;IAKb,iBAAiB,CAAC,EAAE,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI;IASvD,OAAO,CAAC,YAAY;IAWpB,OAAO,CAAC,gBAAgB;IAgCxB,WAAW,CAAC,MAAM,EAAE,UAAU,EAAE,EAAE,UAAU,EAAE,cAAc,EAAE;IAuC9D,OAAO,CAAC,sBAAsB;IAoB9B,OAAO,CAAC,qBAAqB;IA2C7B;;;;;;;;OAQG;IAEH,KAAK,CAAC,EACJ,KAAK,EACL,IAAS,EACT,eAAqB,EACrB,WAAkB,EAClB,MAAM,GACP,EAAE;QACD,KAAK,EAAE,MAAM,EAAE,CAAC;QAChB,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,eAAe,CAAC,EAAE,MAAM,CAAC;QACzB,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,MAAM,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,CAAC;KACjC,GAAG,UAAU,EAAE;CA+DjB"}

package/dist/index.cjs

@@ -6224,7 +6224,8 @@ async function rerank(results, query, model, options) {
 }
 //#endregion
 //#region src/graph-rag/index.ts
-var GraphRAG = class {
+const GRAPH_RAG_SNAPSHOT_VERSION = 1;
+var GraphRAG = class GraphRAG {
 	nodes;
 	edges;
 	dimension;
@@ -6259,6 +6260,49 @@ var GraphRAG = class {
 	getEdgesByType(type) {
 		return this.edges.filter((edge) => edge.type === type);
 	}
+	/**
+	* Produce a JSON-safe snapshot of the graph so it can be persisted and
+	* restored later instead of rebuilt with `createGraph`.
+	*
+	* The snapshot is a deep copy, including nested node metadata, so mutating it
+	* does not affect this instance.
+	* Note that every node carries its full embedding, so snapshots of large
+	* graphs can be several megabytes of JSON.
+	*/
+	serialize() {
+		return {
+			version: GRAPH_RAG_SNAPSHOT_VERSION,
+			dimension: this.dimension,
+			threshold: this.threshold,
+			nodes: Array.from(this.nodes.values()).map((node) => ({
+				...node,
+				...node.embedding ? { embedding: [...node.embedding] } : {},
+				...node.metadata ? { metadata: structuredClone(node.metadata) } : {}
+			})),
+			edges: this.edges.map((edge) => ({ ...edge }))
+		};
+	}
+	/**
+	* Rebuild a GraphRAG instance from a snapshot produced by `serialize()`.
+	*
+	* @throws if the snapshot version is unsupported, a node embedding does not
+	* match the snapshot dimension, or an edge references an unknown node.
+	*/
+	static deserialize(snapshot) {
+		if (snapshot?.version !== GRAPH_RAG_SNAPSHOT_VERSION) throw new Error(`Unsupported GraphRAG snapshot version: ${snapshot?.version}`);
+		const graph = new GraphRAG(snapshot.dimension, snapshot.threshold);
+		for (const node of snapshot.nodes ?? []) graph.addNode({
+			...node,
+			...node.embedding ? { embedding: [...node.embedding] } : {},
+			...node.metadata ? { metadata: structuredClone(node.metadata) } : {}
+		});
+		for (const edge of snapshot.edges ?? []) {
+			if (!graph.nodes.has(edge.source)) throw new Error(`Edge references unknown node: ${edge.source}`);
+			if (!graph.nodes.has(edge.target)) throw new Error(`Edge references unknown node: ${edge.target}`);
+		}
+		graph.edges = (snapshot.edges ?? []).map((edge) => ({ ...edge }));
+		return graph;
+	}
 	clear() {
 		this.nodes.clear();
 		this.edges = [];