@mastra/mysql 0.7.1-alpha.1 → 0.8.0-alpha.3

package/dist/index.cjs

@@ -6,6 +6,46 @@ let _mastra_core_utils = require("@mastra/core/utils");
 let crypto$1 = require("crypto");
 let _mastra_core_agent = require("@mastra/core/agent");
 let _mastra_core_storage_domains_skills = require("@mastra/core/storage/domains/skills");
+//#region src/storage/db/schema-snapshot.ts
+/** Builds the `table.index` presence key the snapshot uses. */
+function indexKey(table, index) {
+	return `${table.toLowerCase()}.${index.toLowerCase()}`;
+}
+const lower = (value) => String(value).toLowerCase();
+/**
+* Reads the catalog for `schemaName` in three queries. Returns null when no
+* schema name is available (a pool with no default database): correctness over
+* optimization, callers fall back to today's per-probe behavior.
+*/
+async function loadSchemaSnapshot(pool, schemaName) {
+	if (!schemaName) return null;
+	const [[tableRows], [columnRows], [indexRows]] = await Promise.all([
+		pool.execute(`SELECT table_name FROM information_schema.tables WHERE table_schema = ?`, [schemaName]),
+		pool.execute(`SELECT table_name, column_name FROM information_schema.columns WHERE table_schema = ?`, [schemaName]),
+		pool.execute(`SELECT DISTINCT table_name, index_name FROM information_schema.statistics WHERE table_schema = ?`, [schemaName])
+	]);
+	const tables = /* @__PURE__ */ new Set();
+	for (const row of tableRows ?? []) tables.add(lower(row.table_name ?? row.TABLE_NAME));
+	const columns = /* @__PURE__ */ new Map();
+	for (const row of columnRows ?? []) {
+		const table = lower(row.table_name ?? row.TABLE_NAME);
+		let set = columns.get(table);
+		if (!set) {
+			set = /* @__PURE__ */ new Set();
+			columns.set(table, set);
+		}
+		set.add(lower(row.column_name ?? row.COLUMN_NAME));
+	}
+	const indexes = /* @__PURE__ */ new Set();
+	for (const row of indexRows ?? []) indexes.add(indexKey(lower(row.table_name ?? row.TABLE_NAME), lower(row.index_name ?? row.INDEX_NAME)));
+	return {
+		schemaName,
+		tables,
+		columns,
+		indexes
+	};
+}
+//#endregion
 //#region src/storage/domains/utils.ts
 function quoteIdentifier(value, context) {
 	return `\`${(0, _mastra_core_utils.parseSqlIdentifier)(value, context)}\``;
@@ -145,12 +185,38 @@ var StoreOperationsMySQL = class extends _mastra_core_storage.StoreOperations {
 	pool;
 	database;
 	resolvedDatabase;
+	/**
+	* Init-scoped catalog snapshot (see db/schema-snapshot.ts). Installed by
+	* MySQLStore.init() for exactly the init window and cleared in its finally;
+	* null at runtime so non-init callers keep probing the live catalog.
+	*/
+	schemaSnapshot = null;
 	constructor({ pool, database }) {
 		super();
 		this.pool = pool;
 		this.database = database;
 		this.resolvedDatabase = database ?? null;
 	}
+	/**
+	* Loads and installs the init-scoped snapshot. A null load (no default
+	* database) or a failed load leaves the snapshot uninstalled, so init
+	* proceeds with today's per-probe behavior: correctness over optimization.
+	*/
+	async loadInitSchemaSnapshot() {
+		try {
+			this.schemaSnapshot = await loadSchemaSnapshot(this.pool, await this.getDatabase());
+		} catch (error) {
+			console.warn("Failed to load init schema snapshot, falling back to per-object probing:", error);
+			this.schemaSnapshot = null;
+		}
+	}
+	clearInitSchemaSnapshot() {
+		this.schemaSnapshot = null;
+	}
+	/** Read by sibling domains (memory's raw index DDL) so snapshot state lives in exactly one place. */
+	getInitSchemaSnapshot() {
+		return this.schemaSnapshot;
+	}
 	getPool() {
 		return this.pool;
 	}
@@ -166,6 +232,8 @@ var StoreOperationsMySQL = class extends _mastra_core_storage.StoreOperations {
 		return this.resolvedDatabase ?? void 0;
 	}
 	async hasColumn(table, column) {
+		const snapshotColumns = this.schemaSnapshot?.columns.get(table.toLowerCase());
+		if (snapshotColumns) return snapshotColumns.has(column.toLowerCase());
 		const db = await this.getDatabase();
 		const params = [table, column];
 		let sql = "SELECT COUNT(*) as count FROM information_schema.columns WHERE table_name = ? AND (column_name = ? OR column_name = ? )";
@@ -243,13 +311,23 @@ var StoreOperationsMySQL = class extends _mastra_core_storage.StoreOperations {
 		return false;
 	}
 	async createTable({ tableName, schema }) {
+		const snapshot = this.schemaSnapshot;
+		if (snapshot?.tables.has(tableName.toLowerCase())) return;
 		const connection = await this.pool.getConnection();
 		try {
-			const db = await this.getDatabase();
-			const [t_rows] = await connection.query("SELECT COUNT(*) AS count FROM information_schema.tables WHERE table_schema = ? AND table_name = ?", [db ?? "", tableName]);
-			if (Array.isArray(t_rows) && t_rows.length > 0 && t_rows[0].count > 0) return;
+			if (!snapshot) {
+				const db = await this.getDatabase();
+				const [t_rows] = await connection.query("SELECT COUNT(*) AS count FROM information_schema.tables WHERE table_schema = ? AND table_name = ?", [db ?? "", tableName]);
+				if (Array.isArray(t_rows) && t_rows.length > 0 && t_rows[0].count > 0) return;
+			}
 			const sql = this.getCreateTableSQL(tableName, schema);
-			await connection.execute(sql);
+			const [result] = await connection.execute(sql);
+			const created = result?.warningStatus === 0;
+			if (snapshot && created) {
+				const table = tableName.toLowerCase();
+				snapshot.tables.add(table);
+				snapshot.columns.set(table, new Set(Object.keys(schema).map((column) => column.toLowerCase())));
+			}
 		} catch (error) {
 			throw new _mastra_core_error.MastraError({
 				id: "MYSQL_STORE_CREATE_TABLE_FAILED",
@@ -305,17 +383,22 @@ var StoreOperationsMySQL = class extends _mastra_core_storage.StoreOperations {
 		const tableName = formatTableName(table, this.database);
 		const indexName = quoteIdentifier(name, "index name");
 		try {
-			const db = await this.getDatabase() ?? "";
-			const [existing] = await this.pool.execute(`SELECT 1 FROM information_schema.STATISTICS 
+			const snapshot = this.schemaSnapshot;
+			if (snapshot) {
+				if (snapshot.indexes.has(indexKey(table, name))) return;
+			} else {
+				const db = await this.getDatabase() ?? "";
+				const [existing] = await this.pool.execute(`SELECT 1 FROM information_schema.STATISTICS 
          WHERE TABLE_SCHEMA = ? AND TABLE_NAME = ? AND INDEX_NAME = ?
          LIMIT 1`, [
-				db,
-				table,
-				name
-			]);
-			if (existing.length > 0) return;
+					db,
+					table,
+					name
+				]);
+				if (existing.length > 0) return;
+			}
 			const [columnMeta] = await this.pool.execute(`SELECT COLUMN_NAME, DATA_TYPE FROM information_schema.COLUMNS
-         WHERE TABLE_SCHEMA = ? AND TABLE_NAME = ?`, [db, table]);
+         WHERE TABLE_SCHEMA = ? AND TABLE_NAME = ?`, [await this.getDatabase() ?? "", table]);
 			const dataTypeByColumn = new Map(columnMeta.map((row) => [String(row.COLUMN_NAME).toLowerCase(), String(row.DATA_TYPE).toLowerCase()]));
 			const PREFIX_TYPES = /* @__PURE__ */ new Set([
 				"tinytext",
@@ -341,6 +424,7 @@ var StoreOperationsMySQL = class extends _mastra_core_storage.StoreOperations {
 			}).join(", ");
 			const sql = `CREATE ${unique ? "UNIQUE " : ""}INDEX ${indexName} ON ${tableName} (${columnsStr})`;
 			await this.pool.execute(sql);
+			this.schemaSnapshot?.indexes.add(indexKey(table, name));
 		} catch (error) {
 			console.warn(`Failed to create index ${name}:`, error);
 		}
@@ -572,17 +656,22 @@ var StoreOperationsMySQL = class extends _mastra_core_storage.StoreOperations {
 	}
 	async alterTable({ tableName, schema, ifNotExists }) {
 		if (!ifNotExists.length) return;
-		const db = await this.getDatabase();
-		const [tableRows] = await this.pool.execute("SELECT COUNT(*) AS count FROM information_schema.tables WHERE table_schema = ? AND table_name = ?", [db ?? "", tableName]);
-		if (!(Array.isArray(tableRows) && tableRows.length > 0 && tableRows[0].count > 0)) return;
-		const params = [tableName];
-		let sql = "SELECT column_name FROM information_schema.columns WHERE table_name = ?";
-		if (db) {
-			sql += " AND table_schema = ?";
-			params.push(db);
+		const snapshotColumns = this.schemaSnapshot?.columns.get(tableName.toLowerCase());
+		let existing;
+		if (snapshotColumns) existing = snapshotColumns;
+		else {
+			const db = await this.getDatabase();
+			const [tableRows] = await this.pool.execute("SELECT COUNT(*) AS count FROM information_schema.tables WHERE table_schema = ? AND table_name = ?", [db ?? "", tableName]);
+			if (!(Array.isArray(tableRows) && tableRows.length > 0 && tableRows[0].count > 0)) return;
+			const params = [tableName];
+			let sql = "SELECT column_name FROM information_schema.columns WHERE table_name = ?";
+			if (db) {
+				sql += " AND table_schema = ?";
+				params.push(db);
+			}
+			const [rows] = await this.pool.execute(sql, params);
+			existing = new Set((rows || []).map((row) => String(row.column_name ?? row.COLUMN_NAME).toLowerCase()));
 		}
-		const [rows] = await this.pool.execute(sql, params);
-		const existing = new Set((rows || []).map((row) => String(row.column_name ?? row.COLUMN_NAME).toLowerCase()));
 		for (const columnName of ifNotExists) {
 			if (existing.has(columnName.toLowerCase())) continue;
 			const column = schema[columnName];
@@ -604,6 +693,7 @@ var StoreOperationsMySQL = class extends _mastra_core_storage.StoreOperations {
 			const alterSql = `ALTER TABLE ${formatTableName(tableName, this.database)} ADD COLUMN ${parts.join(" ")}`;
 			try {
 				await this.pool.execute(alterSql);
+				existing.add(columnName.toLowerCase());
 			} catch (error) {
 				if (error?.code === "ER_DUP_FIELDNAME") continue;
 				throw new _mastra_core_error.MastraError({
@@ -641,7 +731,7 @@ function generateTableSQL({ tableName, schema, compositePrimaryKey }) {
 		const constraints = [];
 		if (def.primaryKey && !compositePrimaryKey?.includes(name)) constraints.push("PRIMARY KEY");
 		if (!def.nullable) constraints.push("NOT NULL");
-		return `${colName} ${mapToMySqlType(def.type)} ${constraints.join(" ")}`;
+		return `${colName} ${mapToMySqlType(def.type, Boolean(def.primaryKey || compositePrimaryKey?.includes(name)))} ${constraints.join(" ")}`;
 	});
 	const tableConstraints = [];
 	if (compositePrimaryKey) {
@@ -665,9 +755,9 @@ function generateIndexSQL(options) {
 		return quoteIdentifier(col, "column name");
 	}).join(", ")});`;
 }
-function mapToMySqlType(type) {
+function mapToMySqlType(type, isKey = false) {
 	switch (type) {
-		case "text": return "TEXT";
+		case "text": return isKey ? "VARCHAR(191)" : "TEXT";
 		case "timestamp": return "DATETIME(3)";
 		case "bigint": return "BIGINT";
 		case "integer": return "INT";
@@ -1282,7 +1372,7 @@ function serializeJson(v) {
 	if (typeof v === "object" && v != null) return JSON.stringify(v);
 	return v ?? null;
 }
-function parseJson$1(val) {
+function parseJson$2(val) {
 	if (val == null) return void 0;
 	if (typeof val === "string") try {
 		return JSON.parse(val);
@@ -1297,14 +1387,14 @@ function rowToTask(row) {
 		status: String(row.status),
 		toolName: String(row.tool_name),
 		toolCallId: String(row.tool_call_id),
-		args: parseJson$1(row.args) ?? {},
+		args: parseJson$2(row.args) ?? {},
 		agentId: String(row.agent_id),
 		threadId: row.thread_id != null ? String(row.thread_id) : void 0,
 		resourceId: row.resource_id != null ? String(row.resource_id) : void 0,
 		runId: String(row.run_id),
-		result: parseJson$1(row.result),
-		error: parseJson$1(row.error),
-		suspendPayload: parseJson$1(row.suspend_payload),
+		result: parseJson$2(row.result),
+		error: parseJson$2(row.error),
+		suspendPayload: parseJson$2(row.suspend_payload),
 		retryCount: Number(row.retry_count),
 		maxRetries: Number(row.max_retries),
 		timeoutMs: Number(row.timeout_ms),
@@ -3732,6 +3822,871 @@ var FavoritesMySQL = class FavoritesMySQL extends _mastra_core_storage.Favorites
 	}
 };
 //#endregion
+//#region src/storage/domains/knowledge/index.ts
+function mysqlSql(sql) {
+	return sql.replaceAll("jsonb(?)", "CAST(? AS JSON)").replaceAll("INSERT OR IGNORE", "INSERT IGNORE").replaceAll("\"", "`");
+}
+function createExecutor(client) {
+	return { async execute(statement) {
+		const sql = typeof statement === "string" ? statement : statement.sql;
+		const args = (typeof statement === "string" ? [] : statement.args ?? []).map((value) => typeof value === "string" && /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/.test(value) ? value.replace("T", " ").replace("Z", "") : value);
+		const [result] = await client.query(mysqlSql(sql), args);
+		if (Array.isArray(result)) return {
+			rows: result,
+			rowsAffected: 0
+		};
+		return {
+			rows: [],
+			rowsAffected: result.affectedRows
+		};
+	} };
+}
+const visibleSql = `(scopeKey = ? OR LEFT(?, CHAR_LENGTH(scopeKey) + 1) = CONCAT(scopeKey, char(31)))`;
+function parseJson$1(value) {
+	if (typeof value === "string") return JSON.parse(value);
+	if (value instanceof Uint8Array) return JSON.parse(new TextDecoder().decode(value));
+	if (value instanceof ArrayBuffer) return JSON.parse(new TextDecoder().decode(value));
+	return value;
+}
+function toDate(value) {
+	return value instanceof Date ? new Date(value) : new Date(String(value));
+}
+function optionalDate(value) {
+	return value == null ? void 0 : toDate(value);
+}
+function databaseTimestamp(value) {
+	const pad = (part, width = 2) => String(part).padStart(width, "0");
+	return `${value.getFullYear()}-${pad(value.getMonth() + 1)}-${pad(value.getDate())} ${pad(value.getHours())}:${pad(value.getMinutes())}:${pad(value.getSeconds())}.${pad(value.getMilliseconds(), 3)}`;
+}
+function canonicalName(name) {
+	return name.trim().toLocaleLowerCase();
+}
+function nodeReferenceId(node) {
+	return typeof node === "string" ? node : node.id;
+}
+function escapeLikePattern(value) {
+	return value.replaceAll("=", "==").replaceAll("%", "=%").replaceAll("_", "=_");
+}
+function parseNode(row) {
+	return {
+		id: String(row.id),
+		type: "node",
+		name: String(row.name),
+		kind: String(row.kind),
+		content: row.content == null ? void 0 : String(row.content),
+		scope: parseJson$1(row.scopeJson ?? row.scope),
+		version: Number(row.version),
+		mergedInto: row.mergedInto == null ? void 0 : String(row.mergedInto),
+		createdAt: toDate(row.createdAt),
+		updatedAt: toDate(row.updatedAt)
+	};
+}
+function parseKnowledge(row) {
+	return {
+		id: String(row.id),
+		node: String(row.node),
+		text: String(row.text),
+		scope: parseJson$1(row.scopeJson ?? row.scope),
+		sourceThreadId: String(row.sourceThreadId),
+		capturedAt: toDate(row.capturedAt),
+		when: optionalDate(row.when),
+		maxScope: row.maxScope == null ? void 0 : String(row.maxScope),
+		metadata: row.metadata == null ? void 0 : parseJson$1(row.metadata),
+		deletedAt: optionalDate(row.deletedAt),
+		deletedBy: row.deletedBy == null ? void 0 : String(row.deletedBy)
+	};
+}
+function parseOutbox(row) {
+	return {
+		id: String(row.id),
+		idempotencyKey: String(row.idempotencyKey),
+		documentId: String(row.documentId),
+		documentType: String(row.documentType),
+		operation: String(row.operation),
+		scope: parseJson$1(row.scopeJson ?? row.scope),
+		status: String(row.status),
+		attempts: Number(row.attempts),
+		availableAt: toDate(row.availableAt),
+		claimedAt: optionalDate(row.claimedAt),
+		claimedBy: row.claimedBy == null ? void 0 : String(row.claimedBy),
+		createdAt: toDate(row.createdAt),
+		completedAt: optionalDate(row.completedAt)
+	};
+}
+const KNOWLEDGE_INDEX_DDL = [
+	`CREATE UNIQUE INDEX idx_knowledge_nodes_identity ON "${_mastra_core_storage.TABLE_KNOWLEDGE_NODES}" (type(32), scopeKey(255), canonicalName(255))`,
+	`CREATE INDEX idx_knowledge_nodes_scope ON "${_mastra_core_storage.TABLE_KNOWLEDGE_NODES}" (scopeKey(255), type(32))`,
+	`CREATE INDEX idx_knowledge_records_node_latest ON "${_mastra_core_storage.TABLE_KNOWLEDGE_RECORDS}" (node(191), id(26) DESC)`,
+	`CREATE INDEX idx_knowledge_records_thread_latest ON "${_mastra_core_storage.TABLE_KNOWLEDGE_RECORDS}" (sourceThreadId(191), id(26) DESC)`,
+	`CREATE INDEX idx_knowledge_mentions_record ON "${_mastra_core_storage.TABLE_KNOWLEDGE_MENTIONS}" (recordId(191), sourceType(32), sourceId(191))`,
+	`CREATE INDEX idx_knowledge_activity_latest ON "${_mastra_core_storage.TABLE_KNOWLEDGE_ACTIVITY}" (id(26) DESC)`,
+	`CREATE UNIQUE INDEX idx_knowledge_outbox_idempotency ON "${_mastra_core_storage.TABLE_KNOWLEDGE_SEMANTIC_OUTBOX}" (idempotencyKey(255))`,
+	`CREATE INDEX idx_knowledge_outbox_claim ON "${_mastra_core_storage.TABLE_KNOWLEDGE_SEMANTIC_OUTBOX}" (status(32), availableAt, createdAt)`
+];
+var KnowledgeMySQL = class extends _mastra_core_storage.KnowledgeStorage {
+	static getExportDDL() {
+		return [
+			generateTableSQL({
+				tableName: _mastra_core_storage.TABLE_KNOWLEDGE_NODES,
+				schema: _mastra_core_storage.KNOWLEDGE_NODES_SCHEMA
+			}),
+			generateTableSQL({
+				tableName: _mastra_core_storage.TABLE_KNOWLEDGE_RECORDS,
+				schema: _mastra_core_storage.KNOWLEDGE_RECORDS_SCHEMA
+			}),
+			generateTableSQL({
+				tableName: _mastra_core_storage.TABLE_KNOWLEDGE_MENTIONS,
+				schema: _mastra_core_storage.KNOWLEDGE_MENTIONS_SCHEMA,
+				compositePrimaryKey: [
+					"sourceType",
+					"sourceId",
+					"recordId"
+				]
+			}),
+			generateTableSQL({
+				tableName: _mastra_core_storage.TABLE_KNOWLEDGE_CURSORS,
+				schema: _mastra_core_storage.KNOWLEDGE_CURSORS_SCHEMA,
+				compositePrimaryKey: ["sourceThreadId", "agent"]
+			}),
+			generateTableSQL({
+				tableName: _mastra_core_storage.TABLE_KNOWLEDGE_ACTIVITY,
+				schema: _mastra_core_storage.KNOWLEDGE_ACTIVITY_SCHEMA
+			}),
+			generateTableSQL({
+				tableName: _mastra_core_storage.TABLE_KNOWLEDGE_SEMANTIC_OUTBOX,
+				schema: _mastra_core_storage.KNOWLEDGE_SEMANTIC_OUTBOX_SCHEMA
+			}),
+			...KNOWLEDGE_INDEX_DDL.map(mysqlSql)
+		];
+	}
+	#pool;
+	#client;
+	#operations;
+	constructor({ pool, operations }) {
+		super();
+		this.#pool = pool;
+		this.#client = createExecutor(pool);
+		this.#operations = operations;
+	}
+	async init() {
+		await this.#operations.createTable({
+			tableName: _mastra_core_storage.TABLE_KNOWLEDGE_NODES,
+			schema: _mastra_core_storage.KNOWLEDGE_NODES_SCHEMA
+		});
+		await this.#operations.createTable({
+			tableName: _mastra_core_storage.TABLE_KNOWLEDGE_RECORDS,
+			schema: _mastra_core_storage.KNOWLEDGE_RECORDS_SCHEMA
+		});
+		await this.#operations.createTable({
+			tableName: _mastra_core_storage.TABLE_KNOWLEDGE_MENTIONS,
+			schema: _mastra_core_storage.KNOWLEDGE_MENTIONS_SCHEMA
+		});
+		await this.#operations.createTable({
+			tableName: _mastra_core_storage.TABLE_KNOWLEDGE_CURSORS,
+			schema: _mastra_core_storage.KNOWLEDGE_CURSORS_SCHEMA
+		});
+		await this.#operations.createTable({
+			tableName: _mastra_core_storage.TABLE_KNOWLEDGE_ACTIVITY,
+			schema: _mastra_core_storage.KNOWLEDGE_ACTIVITY_SCHEMA
+		});
+		await this.#operations.createTable({
+			tableName: _mastra_core_storage.TABLE_KNOWLEDGE_SEMANTIC_OUTBOX,
+			schema: _mastra_core_storage.KNOWLEDGE_SEMANTIC_OUTBOX_SCHEMA
+		});
+		for (const sql of KNOWLEDGE_INDEX_DDL) try {
+			await this.#client.execute(sql);
+		} catch (error) {
+			if (error.code !== "ER_DUP_KEYNAME") throw error;
+		}
+	}
+	async dangerouslyClearAll() {
+		await this.#transaction(async (tx) => {
+			for (const table of [
+				_mastra_core_storage.TABLE_KNOWLEDGE_MENTIONS,
+				_mastra_core_storage.TABLE_KNOWLEDGE_RECORDS,
+				_mastra_core_storage.TABLE_KNOWLEDGE_NODES,
+				_mastra_core_storage.TABLE_KNOWLEDGE_CURSORS,
+				_mastra_core_storage.TABLE_KNOWLEDGE_ACTIVITY,
+				_mastra_core_storage.TABLE_KNOWLEDGE_SEMANTIC_OUTBOX
+			]) await tx.execute(`DELETE FROM "${table}"`);
+		});
+	}
+	async createNode(input) {
+		const scope = (0, _mastra_core_storage.canonicalizeKnowledgeScope)(input.scope);
+		return this.#transaction(async (tx) => {
+			const existing = await this.#getNodeByName(tx, input.name, scope);
+			if (existing) {
+				const terminal = await this.#resolveTerminalNode(tx, existing.id);
+				if (!(0, _mastra_core_storage.isKnowledgeScopeVisible)(terminal.scope, scope)) throw new Error(`Merged knowledge node is not visible from scope: ${input.name}`);
+				return terminal;
+			}
+			const now = /* @__PURE__ */ new Date();
+			const node = {
+				id: input.id ?? crypto.randomUUID(),
+				type: "node",
+				name: input.name.trim(),
+				kind: input.kind,
+				content: input.content,
+				scope,
+				version: 1,
+				createdAt: now,
+				updatedAt: now
+			};
+			await tx.execute({
+				sql: `INSERT INTO "${_mastra_core_storage.TABLE_KNOWLEDGE_NODES}" (id,type,name,canonicalName,kind,content,scope,scopeKey,version,mergedInto,createdAt,updatedAt) VALUES (?,?,?,?,?,?,jsonb(?),?,?,NULL,?,?)`,
+				args: [
+					node.id,
+					"node",
+					node.name,
+					canonicalName(node.name),
+					node.kind,
+					node.content ?? null,
+					JSON.stringify(scope),
+					(0, _mastra_core_storage.knowledgeScopeKey)(scope),
+					node.version,
+					now.toISOString(),
+					now.toISOString()
+				]
+			});
+			await this.#replaceMentions(tx, "node", node.id, node.content ?? "", input.resolutionScope ?? scope, scope);
+			await this.#activity(tx, "node-created", "node", node.id, scope);
+			await this.#outbox(tx, "node", node.id, "upsert", node.version, scope);
+			return node;
+		});
+	}
+	async getNode(id) {
+		return this.#getNode(this.#client, id);
+	}
+	async getNodeByName(input) {
+		return this.#getNodeByName(this.#client, input.name, (0, _mastra_core_storage.canonicalizeKnowledgeScope)(input.scope));
+	}
+	async resolveNode(input) {
+		return this.#resolveNode(this.#client, input.name, (0, _mastra_core_storage.canonicalizeKnowledgeScope)(input.scope));
+	}
+	async listNodes(input) {
+		const key = (0, _mastra_core_storage.knowledgeScopeKey)((0, _mastra_core_storage.canonicalizeKnowledgeScope)(input.scope));
+		const clauses = [
+			`type = 'node'`,
+			"mergedInto IS NULL",
+			visibleSql
+		];
+		const args = [key, key];
+		if (input.namePrefix) {
+			clauses.push("canonicalName LIKE ? ESCAPE '='");
+			args.push(`${escapeLikePattern(canonicalName(input.namePrefix))}%`);
+		}
+		if (input.kind) {
+			clauses.push("kind = ?");
+			args.push(input.kind);
+		}
+		if (input.hasContent !== void 0) clauses.push(input.hasContent ? "content IS NOT NULL AND content <> ''" : "(content IS NULL OR content = '')");
+		if (input.cursor) {
+			const cursor = (0, _mastra_core_storage.parseKnowledgeNodeCursor)(input.cursor, {
+				namePrefix: input.namePrefix,
+				kind: input.kind,
+				hasContent: input.hasContent
+			});
+			const updatedAt = databaseTimestamp(cursor.updatedAt);
+			clauses.push("(updatedAt < ? OR (updatedAt = ? AND (name > ? OR (name = ? AND id > ?))))");
+			args.push(updatedAt, updatedAt, cursor.name, cursor.name, cursor.id);
+		}
+		args.push(input.limit ?? 100);
+		return (await this.#client.execute({
+			sql: `SELECT *, scope AS scopeJson FROM "${_mastra_core_storage.TABLE_KNOWLEDGE_NODES}" WHERE ${clauses.join(" AND ")} ORDER BY updatedAt DESC, name ASC, id ASC LIMIT ?`,
+			args
+		})).rows.map(parseNode);
+	}
+	async updateNode(input) {
+		return this.#transaction(async (tx) => {
+			const existing = await this.#getNode(tx, input.id);
+			if (!existing) throw new _mastra_core_storage.KnowledgeNotFoundError("node", input.id);
+			if (existing.mergedInto) throw new Error(`Cannot update merged knowledge node: ${input.id}`);
+			const scope = (0, _mastra_core_storage.canonicalizeKnowledgeScope)(input.scope ?? existing.scope);
+			const name = (input.name ?? existing.name).trim();
+			const content = input.content ?? existing.content;
+			const now = /* @__PURE__ */ new Date();
+			if ((await tx.execute({
+				sql: `UPDATE "${_mastra_core_storage.TABLE_KNOWLEDGE_NODES}" SET name=?,canonicalName=?,kind=?,content=?,scope=jsonb(?),scopeKey=?,version=version+1,updatedAt=? WHERE id=? AND type='node' AND version=?`,
+				args: [
+					name,
+					canonicalName(name),
+					input.kind ?? existing.kind,
+					content ?? null,
+					JSON.stringify(scope),
+					(0, _mastra_core_storage.knowledgeScopeKey)(scope),
+					now.toISOString(),
+					input.id,
+					input.version
+				]
+			})).rowsAffected === 0) throw new _mastra_core_storage.KnowledgeConflictError(input.id);
+			if (input.content !== void 0 || input.name !== void 0 || input.scope !== void 0) await this.#replaceMentions(tx, "node", input.id, content ?? "", input.resolutionScope ?? scope, scope);
+			await this.#activity(tx, "node-updated", "node", input.id, scope);
+			if ((0, _mastra_core_storage.knowledgeScopeKey)(existing.scope) !== (0, _mastra_core_storage.knowledgeScopeKey)(scope)) {
+				await this.#outbox(tx, "node", input.id, "delete", (0, _mastra_core_storage.createKnowledgeUlid)(), existing.scope);
+				const records = await tx.execute({
+					sql: `SELECT id,scope AS scopeJson,deletedAt FROM "${_mastra_core_storage.TABLE_KNOWLEDGE_RECORDS}" WHERE node=?`,
+					args: [input.id]
+				});
+				for (const row of records.rows) {
+					const factScope = parseJson$1(row.scopeJson);
+					await this.#outbox(tx, "record", String(row.id), "delete", (0, _mastra_core_storage.createKnowledgeUlid)(), factScope);
+					if (row.deletedAt == null) await this.#outbox(tx, "record", String(row.id), "upsert", (0, _mastra_core_storage.createKnowledgeUlid)(), factScope);
+				}
+			}
+			await this.#outbox(tx, "node", input.id, "upsert", input.version + 1, scope);
+			return {
+				...existing,
+				name,
+				kind: input.kind ?? existing.kind,
+				content,
+				scope,
+				version: input.version + 1,
+				updatedAt: now
+			};
+		});
+	}
+	async mergeNodes(input) {
+		if (input.sourceId === input.targetId) throw new Error("Cannot merge a knowledge node into itself");
+		return this.#transaction(async (tx) => {
+			const source = await this.#getNode(tx, input.sourceId);
+			if (!source) throw new _mastra_core_storage.KnowledgeNotFoundError("node", input.sourceId);
+			const target = await this.#resolveTerminalNode(tx, input.targetId);
+			if (!target) throw new _mastra_core_storage.KnowledgeNotFoundError("node", input.targetId);
+			if (target.id === source.id) throw new Error("Cannot create a knowledge merge cycle");
+			if (!(0, _mastra_core_storage.isKnowledgeScopeVisible)(target.scope, source.scope)) throw new Error("Cannot merge a knowledge node into a target that is narrower than its source scope");
+			const affected = await tx.execute({
+				sql: `SELECT DISTINCT m.sourceType,m.sourceId,COALESCE(f.scope,r.scope) AS scopeJson,CASE WHEN f.deletedAt IS NULL THEN 0 ELSE 1 END AS deleted FROM "${_mastra_core_storage.TABLE_KNOWLEDGE_MENTIONS}" m LEFT JOIN "${_mastra_core_storage.TABLE_KNOWLEDGE_RECORDS}" f ON m.sourceType='record' AND f.id=m.sourceId LEFT JOIN "${_mastra_core_storage.TABLE_KNOWLEDGE_NODES}" r ON m.sourceType='node' AND r.id=m.sourceId WHERE m.recordId=?`,
+				args: [source.id]
+			});
+			const movedFacts = await tx.execute({
+				sql: `SELECT id,scope AS scopeJson,deletedAt FROM "${_mastra_core_storage.TABLE_KNOWLEDGE_RECORDS}" WHERE node=?`,
+				args: [source.id]
+			});
+			if ((await tx.execute({
+				sql: `UPDATE "${_mastra_core_storage.TABLE_KNOWLEDGE_NODES}" SET mergedInto=?,version=version+1,updatedAt=? WHERE id=? AND type='node' AND version=? AND mergedInto IS NULL`,
+				args: [
+					target.id,
+					(/* @__PURE__ */ new Date()).toISOString(),
+					source.id,
+					input.sourceVersion
+				]
+			})).rowsAffected === 0) throw new _mastra_core_storage.KnowledgeConflictError(source.id);
+			await tx.execute({
+				sql: `UPDATE "${_mastra_core_storage.TABLE_KNOWLEDGE_RECORDS}" SET node=? WHERE node=?`,
+				args: [target.id, source.id]
+			});
+			await tx.execute({
+				sql: `DELETE source FROM "${_mastra_core_storage.TABLE_KNOWLEDGE_MENTIONS}" source JOIN "${_mastra_core_storage.TABLE_KNOWLEDGE_MENTIONS}" target ON target.sourceType=source.sourceType AND target.sourceId=source.sourceId WHERE source.recordId=? AND target.recordId=?`,
+				args: [source.id, target.id]
+			});
+			await tx.execute({
+				sql: `UPDATE "${_mastra_core_storage.TABLE_KNOWLEDGE_MENTIONS}" SET recordId=? WHERE recordId=?`,
+				args: [target.id, source.id]
+			});
+			for (const row of movedFacts.rows) await this.#outbox(tx, "record", String(row.id), row.deletedAt == null ? "upsert" : "delete", (0, _mastra_core_storage.createKnowledgeUlid)(), parseJson$1(row.scopeJson));
+			for (const row of affected.rows) await this.#outbox(tx, String(row.sourceType), String(row.sourceId), Number(row.deleted) ? "delete" : "upsert", (0, _mastra_core_storage.createKnowledgeUlid)(), parseJson$1(row.scopeJson));
+			await this.#activity(tx, "node-merged", "node", source.id, source.scope);
+			await this.#outbox(tx, "node", source.id, "delete", input.sourceVersion + 1, source.scope);
+			await this.#outbox(tx, "node", target.id, "upsert", (0, _mastra_core_storage.createKnowledgeUlid)(), target.scope);
+			return target;
+		});
+	}
+	async appendKnowledge(input) {
+		const scope = (0, _mastra_core_storage.canonicalizeKnowledgeScope)(input.scope);
+		const resolutionScope = (0, _mastra_core_storage.canonicalizeKnowledgeScope)(input.resolutionScope);
+		const defaultScope = (0, _mastra_core_storage.canonicalizeKnowledgeScope)(input.defaultScope);
+		(0, _mastra_core_storage.assertKnowledgeScopeWithinCeiling)(scope, input.maxScope);
+		return this.#transaction(async (tx) => {
+			const parent = await this.#resolveTerminalNode(tx, nodeReferenceId(input.node));
+			if (!parent) throw new _mastra_core_storage.KnowledgeNotFoundError("node", nodeReferenceId(input.node));
+			const record = {
+				id: input.id ?? (0, _mastra_core_storage.createKnowledgeUlid)(),
+				node: parent.id,
+				text: input.text,
+				scope,
+				sourceThreadId: input.sourceThreadId,
+				capturedAt: /* @__PURE__ */ new Date(),
+				when: input.when ? new Date(input.when) : void 0,
+				maxScope: input.maxScope,
+				metadata: input.metadata
+			};
+			await tx.execute({
+				sql: `INSERT INTO "${_mastra_core_storage.TABLE_KNOWLEDGE_RECORDS}" (id,node,text,scope,scopeKey,sourceThreadId,capturedAt,"when",maxScope,metadata,deletedAt,deletedBy) VALUES (?,?,?,jsonb(?),?,?,?,?,?,jsonb(?),NULL,NULL)`,
+				args: [
+					record.id,
+					record.node,
+					record.text,
+					JSON.stringify(scope),
+					(0, _mastra_core_storage.knowledgeScopeKey)(scope),
+					record.sourceThreadId,
+					record.capturedAt.toISOString(),
+					record.when?.toISOString() ?? null,
+					record.maxScope ?? null,
+					record.metadata ? JSON.stringify(record.metadata) : null
+				]
+			});
+			await this.#replaceMentions(tx, "record", record.id, record.text, resolutionScope, defaultScope);
+			await this.#activity(tx, "record-created", "record", record.id, scope, record.sourceThreadId);
+			await this.#outbox(tx, "record", record.id, "upsert", record.id, scope);
+			return record;
+		});
+	}
+	async getKnowledge(input) {
+		const result = await this.#client.execute({
+			sql: `SELECT *,scope AS scopeJson FROM "${_mastra_core_storage.TABLE_KNOWLEDGE_RECORDS}" WHERE id=?${input.includeDeleted ? "" : " AND deletedAt IS NULL"}`,
+			args: [input.id]
+		});
+		return result.rows[0] ? parseKnowledge(result.rows[0]) : null;
+	}
+	async listKnowledgeAbout(input) {
+		return this.#queryKnowledge(input, "about");
+	}
+	async listKnowledgeMentioning(input) {
+		return this.#queryKnowledge(input, "mentioning");
+	}
+	async listKnowledgeRelatedTo(input) {
+		return this.#queryKnowledge(input, "related");
+	}
+	async knowledgeBySource(input) {
+		const key = (0, _mastra_core_storage.knowledgeScopeKey)((0, _mastra_core_storage.canonicalizeKnowledgeScope)(input.scope));
+		const args = [
+			input.sourceThreadId,
+			key,
+			key
+		];
+		if (input.after) args.push(input.after);
+		const limit = input.limit ?? 100;
+		args.push(limit + 1);
+		const records = (await this.#client.execute({
+			sql: `SELECT *,scope AS scopeJson FROM "${_mastra_core_storage.TABLE_KNOWLEDGE_RECORDS}" WHERE sourceThreadId=? AND ${visibleSql}${input.includeDeleted ? "" : " AND deletedAt IS NULL"}${input.after ? " AND id > ?" : ""} ORDER BY id ASC LIMIT ?`,
+			args
+		})).rows.map(parseKnowledge);
+		return {
+			records: records.slice(0, limit),
+			nextCursor: records.length > limit ? records[limit - 1]?.id : void 0
+		};
+	}
+	async removeKnowledge(input) {
+		return this.#transaction(async (tx) => {
+			const record = await this.#getKnowledge(tx, input.id, true);
+			if (!record) throw new _mastra_core_storage.KnowledgeNotFoundError("record", input.id);
+			if (record.deletedAt) return record;
+			const deletedAt = /* @__PURE__ */ new Date();
+			await tx.execute({
+				sql: `UPDATE "${_mastra_core_storage.TABLE_KNOWLEDGE_RECORDS}" SET deletedAt=?,deletedBy=? WHERE id=? AND deletedAt IS NULL`,
+				args: [
+					deletedAt.toISOString(),
+					input.deletedBy,
+					input.id
+				]
+			});
+			await this.#activity(tx, "record-deleted", "record", input.id, record.scope, record.sourceThreadId);
+			await this.#outbox(tx, "record", input.id, "delete", deletedAt.toISOString(), record.scope);
+			return {
+				...record,
+				deletedAt,
+				deletedBy: input.deletedBy
+			};
+		});
+	}
+	async restoreKnowledge(input) {
+		return this.#transaction(async (tx) => {
+			const record = await this.#getKnowledge(tx, input.id, true);
+			if (!record) throw new _mastra_core_storage.KnowledgeNotFoundError("record", input.id);
+			if (!record.deletedAt) return record;
+			await tx.execute({
+				sql: `UPDATE "${_mastra_core_storage.TABLE_KNOWLEDGE_RECORDS}" SET deletedAt=NULL,deletedBy=NULL WHERE id=?`,
+				args: [input.id]
+			});
+			await this.#activity(tx, "record-restored", "record", input.id, record.scope, record.sourceThreadId);
+			await this.#outbox(tx, "record", input.id, "upsert", (0, _mastra_core_storage.createKnowledgeUlid)(), record.scope);
+			return {
+				...record,
+				deletedAt: void 0,
+				deletedBy: void 0
+			};
+		});
+	}
+	async rescopeKnowledge(input) {
+		const scope = (0, _mastra_core_storage.canonicalizeKnowledgeScope)(input.scope);
+		return this.#transaction(async (tx) => {
+			const record = await this.#getKnowledge(tx, input.id, true);
+			if (!record) throw new _mastra_core_storage.KnowledgeNotFoundError("record", input.id);
+			(0, _mastra_core_storage.assertKnowledgeScopeWithinCeiling)(scope, record.maxScope);
+			await tx.execute({
+				sql: `UPDATE "${_mastra_core_storage.TABLE_KNOWLEDGE_RECORDS}" SET scope=jsonb(?),scopeKey=? WHERE id=?`,
+				args: [
+					JSON.stringify(scope),
+					(0, _mastra_core_storage.knowledgeScopeKey)(scope),
+					input.id
+				]
+			});
+			await this.#activity(tx, "record-rescoped", "record", input.id, scope, record.sourceThreadId);
+			if ((0, _mastra_core_storage.knowledgeScopeKey)(record.scope) !== (0, _mastra_core_storage.knowledgeScopeKey)(scope)) await this.#outbox(tx, "record", input.id, "delete", (0, _mastra_core_storage.createKnowledgeUlid)(), record.scope);
+			if (!record.deletedAt) await this.#outbox(tx, "record", input.id, "upsert", (0, _mastra_core_storage.createKnowledgeUlid)(), scope);
+			return {
+				...record,
+				scope
+			};
+		});
+	}
+	async raiseKnowledgeCeiling(input) {
+		return this.#transaction(async (tx) => {
+			const record = await this.#getKnowledge(tx, input.id, true);
+			if (!record) throw new _mastra_core_storage.KnowledgeNotFoundError("record", input.id);
+			(0, _mastra_core_storage.assertKnowledgeScopeWithinCeiling)(record.scope, input.maxScope);
+			(0, _mastra_core_storage.assertKnowledgeCeilingRaised)(record.maxScope, input.maxScope);
+			await tx.execute({
+				sql: `UPDATE "${_mastra_core_storage.TABLE_KNOWLEDGE_RECORDS}" SET maxScope=? WHERE id=?`,
+				args: [input.maxScope ?? null, input.id]
+			});
+			return {
+				...record,
+				maxScope: input.maxScope
+			};
+		});
+	}
+	async search(input) {
+		const scope = (0, _mastra_core_storage.canonicalizeKnowledgeScope)(input.scope);
+		const key = (0, _mastra_core_storage.knowledgeScopeKey)(scope);
+		const normalizedQuery = input.query.trim().toLocaleLowerCase();
+		if (!normalizedQuery) return [];
+		const query = `%${escapeLikePattern(normalizedQuery)}%`;
+		const results = (await this.#client.execute({
+			sql: `SELECT *,scope AS scopeJson FROM "${_mastra_core_storage.TABLE_KNOWLEDGE_NODES}" WHERE mergedInto IS NULL AND ${visibleSql} AND (canonicalName LIKE ? ESCAPE '=' OR lower(COALESCE(kind,'')) LIKE ? ESCAPE '=' OR lower(COALESCE(content,'')) LIKE ? ESCAPE '=') ORDER BY updatedAt DESC LIMIT ?`,
+			args: [
+				key,
+				key,
+				query,
+				query,
+				query,
+				input.limit ?? 20
+			]
+		})).rows.map((row) => ({
+			type: String(row.type),
+			id: String(row.id),
+			recordId: String(row.id),
+			name: String(row.name),
+			text: row.content ? `${String(row.name)}\n${String(row.content)}` : String(row.name),
+			scope: parseJson$1(row.scopeJson)
+		}));
+		if (results.length < (input.limit ?? 20)) {
+			const records = await this.#client.execute({
+				sql: `SELECT f.*,f.scope AS scopeJson,r.name,r.scope AS parentScopeJson FROM "${_mastra_core_storage.TABLE_KNOWLEDGE_RECORDS}" f JOIN "${_mastra_core_storage.TABLE_KNOWLEDGE_NODES}" r ON r.id=f.node AND r.type='node' AND r.mergedInto IS NULL WHERE f.deletedAt IS NULL AND ${visibleSql.replaceAll("scopeKey", "f.scopeKey")} AND lower(f.text) LIKE ? ESCAPE '=' ORDER BY f.id DESC LIMIT ?`,
+				args: [
+					key,
+					key,
+					query,
+					(input.limit ?? 20) - results.length
+				]
+			});
+			results.push(...records.rows.map((row) => {
+				const parentVisible = (0, _mastra_core_storage.isKnowledgeScopeVisible)(parseJson$1(row.parentScopeJson), scope);
+				return {
+					type: "record",
+					id: String(row.id),
+					recordId: String(row.node),
+					name: parentVisible ? String(row.name) : "(private node)",
+					text: String(row.text),
+					scope: parseJson$1(row.scopeJson)
+				};
+			}));
+		}
+		return results;
+	}
+	async getCurationCursor(input) {
+		const row = (await this.#client.execute({
+			sql: `SELECT * FROM "${_mastra_core_storage.TABLE_KNOWLEDGE_CURSORS}" WHERE sourceThreadId=? AND agent=?`,
+			args: [input.sourceThreadId, input.agent]
+		})).rows[0];
+		return row ? {
+			sourceThreadId: String(row.sourceThreadId),
+			agent: String(row.agent),
+			lastKnowledgeId: String(row.lastKnowledgeId),
+			updatedAt: toDate(row.updatedAt)
+		} : null;
+	}
+	async advanceCurationCursor(input) {
+		const updatedAt = /* @__PURE__ */ new Date();
+		if ((await this.#client.execute({
+			sql: `INSERT INTO "${_mastra_core_storage.TABLE_KNOWLEDGE_CURSORS}" (sourceThreadId,agent,lastKnowledgeId,updatedAt) VALUES (?,?,?,?) ON DUPLICATE KEY UPDATE lastKnowledgeId=IF(VALUES(lastKnowledgeId) >= lastKnowledgeId, VALUES(lastKnowledgeId), lastKnowledgeId),updatedAt=IF(VALUES(lastKnowledgeId) >= lastKnowledgeId, VALUES(updatedAt), updatedAt)`,
+			args: [
+				input.sourceThreadId,
+				input.agent,
+				input.lastKnowledgeId,
+				updatedAt.toISOString()
+			]
+		})).rowsAffected === 0) throw new Error("Knowledge curation cursor cannot move backwards");
+		return {
+			...input,
+			updatedAt
+		};
+	}
+	async listActivity(input) {
+		const key = (0, _mastra_core_storage.knowledgeScopeKey)((0, _mastra_core_storage.canonicalizeKnowledgeScope)(input.scope));
+		return (await this.#client.execute({
+			sql: `SELECT *,scope AS scopeJson FROM "${_mastra_core_storage.TABLE_KNOWLEDGE_ACTIVITY}" WHERE ${visibleSql}${input.after ? " AND id < ?" : ""} ORDER BY id DESC LIMIT ?`,
+			args: [
+				key,
+				key,
+				...input.after ? [input.after] : [],
+				input.limit ?? 100
+			]
+		})).rows.map((row) => ({
+			id: String(row.id),
+			action: String(row.action),
+			recordType: String(row.recordType),
+			recordId: String(row.recordId),
+			scope: parseJson$1(row.scopeJson),
+			sourceThreadId: row.sourceThreadId == null ? void 0 : String(row.sourceThreadId),
+			createdAt: toDate(row.createdAt)
+		}));
+	}
+	async listSemanticOutbox(input = {}) {
+		const clauses = [];
+		const args = [];
+		if (input.status) {
+			clauses.push("status=?");
+			args.push(input.status);
+		}
+		if (input.scope) {
+			const key = (0, _mastra_core_storage.knowledgeScopeKey)((0, _mastra_core_storage.canonicalizeKnowledgeScope)(input.scope));
+			clauses.push(visibleSql);
+			args.push(key, key);
+		}
+		args.push(input.limit ?? 100);
+		return (await this.#client.execute({
+			sql: `SELECT *,scope AS scopeJson FROM "${_mastra_core_storage.TABLE_KNOWLEDGE_SEMANTIC_OUTBOX}"${clauses.length ? ` WHERE ${clauses.join(" AND ")}` : ""} ORDER BY createdAt ASC,id ASC LIMIT ?`,
+			args
+		})).rows.map(parseOutbox);
+	}
+	async claimSemanticOutbox(input) {
+		const now = input.now ?? /* @__PURE__ */ new Date();
+		const stale = new Date(now.getTime() - (input.claimTimeoutMs ?? 6e4));
+		return this.#transaction(async (tx) => {
+			const clauses = [
+				`availableAt <= ?`,
+				`(status='pending' OR (status='processing' AND claimedAt <= ?))`,
+				`NOT EXISTS (SELECT 1 FROM "${_mastra_core_storage.TABLE_KNOWLEDGE_SEMANTIC_OUTBOX}" AS earlier WHERE earlier.documentId = "${_mastra_core_storage.TABLE_KNOWLEDGE_SEMANTIC_OUTBOX}".documentId AND earlier.status != 'completed' AND (earlier.createdAt < "${_mastra_core_storage.TABLE_KNOWLEDGE_SEMANTIC_OUTBOX}".createdAt OR (earlier.createdAt = "${_mastra_core_storage.TABLE_KNOWLEDGE_SEMANTIC_OUTBOX}".createdAt AND earlier.id < "${_mastra_core_storage.TABLE_KNOWLEDGE_SEMANTIC_OUTBOX}".id)))`
+			];
+			const args = [now.toISOString(), stale.toISOString()];
+			if (input.scope) {
+				const key = (0, _mastra_core_storage.knowledgeScopeKey)((0, _mastra_core_storage.canonicalizeKnowledgeScope)(input.scope));
+				clauses.push(visibleSql);
+				args.push(key, key);
+			}
+			args.push(input.limit ?? 100);
+			const ids = (await tx.execute({
+				sql: `SELECT id FROM "${_mastra_core_storage.TABLE_KNOWLEDGE_SEMANTIC_OUTBOX}" WHERE ${clauses.join(" AND ")} ORDER BY createdAt ASC,id ASC LIMIT ? FOR UPDATE SKIP LOCKED`,
+				args
+			})).rows.map((row) => String(row.id));
+			for (const id of ids) await tx.execute({
+				sql: `UPDATE "${_mastra_core_storage.TABLE_KNOWLEDGE_SEMANTIC_OUTBOX}" SET status='processing',attempts=attempts+1,claimedAt=?,claimedBy=? WHERE id=?`,
+				args: [
+					now.toISOString(),
+					input.workerId,
+					id
+				]
+			});
+			if (!ids.length) return [];
+			return (await tx.execute({
+				sql: `SELECT *,scope AS scopeJson FROM "${_mastra_core_storage.TABLE_KNOWLEDGE_SEMANTIC_OUTBOX}" WHERE id IN (${ids.map(() => "?").join(",")}) ORDER BY createdAt ASC,id ASC`,
+				args: ids
+			})).rows.map(parseOutbox);
+		});
+	}
+	async completeSemanticOutbox(input) {
+		if (!input.ids.length) return;
+		const now = (/* @__PURE__ */ new Date()).toISOString();
+		await this.#transaction(async (tx) => {
+			for (const id of input.ids) await tx.execute({
+				sql: `UPDATE "${_mastra_core_storage.TABLE_KNOWLEDGE_SEMANTIC_OUTBOX}" SET status='completed',completedAt=? WHERE id=? AND status='processing' AND claimedBy=?`,
+				args: [
+					now,
+					id,
+					input.workerId
+				]
+			});
+		});
+	}
+	async releaseSemanticOutbox(input) {
+		if (!input.ids.length) return;
+		await this.#transaction(async (tx) => {
+			for (const id of input.ids) await tx.execute({
+				sql: `UPDATE "${_mastra_core_storage.TABLE_KNOWLEDGE_SEMANTIC_OUTBOX}" SET status='pending',availableAt=?,claimedAt=NULL,claimedBy=NULL WHERE id=? AND status='processing' AND claimedBy=?`,
+				args: [
+					(input.retryAt ?? /* @__PURE__ */ new Date()).toISOString(),
+					id,
+					input.workerId
+				]
+			});
+		});
+	}
+	async #transaction(operation) {
+		const connection = await this.#pool.getConnection();
+		try {
+			await connection.beginTransaction();
+			const result = await operation(createExecutor(connection));
+			await connection.commit();
+			return result;
+		} catch (error) {
+			await connection.rollback();
+			throw error;
+		} finally {
+			connection.release();
+		}
+	}
+	async #getNode(executor, id) {
+		const result = await executor.execute({
+			sql: `SELECT *,scope AS scopeJson FROM "${_mastra_core_storage.TABLE_KNOWLEDGE_NODES}" WHERE id=? AND type='node'`,
+			args: [id]
+		});
+		return result.rows[0] ? parseNode(result.rows[0]) : null;
+	}
+	async #getNodeByName(executor, name, scope) {
+		const result = await executor.execute({
+			sql: `SELECT *,scope AS scopeJson FROM "${_mastra_core_storage.TABLE_KNOWLEDGE_NODES}" WHERE type='node' AND scopeKey=? AND canonicalName=?`,
+			args: [(0, _mastra_core_storage.knowledgeScopeKey)(scope), canonicalName(name)]
+		});
+		return result.rows[0] ? parseNode(result.rows[0]) : null;
+	}
+	async #resolveNode(executor, name, scope) {
+		for (let length = scope.length; length > 0; length--) {
+			const node = await this.#getNodeByName(executor, name, scope.slice(0, length));
+			if (node) {
+				const terminal = await this.#resolveTerminalNode(executor, node.id);
+				if (terminal && (0, _mastra_core_storage.isKnowledgeScopeVisible)(terminal.scope, scope)) return terminal;
+			}
+		}
+		return null;
+	}
+	async #resolveTerminalNode(executor, id) {
+		let node = await this.#getNode(executor, id);
+		const seen = /* @__PURE__ */ new Set();
+		while (node?.mergedInto) {
+			if (seen.has(node.id)) throw new Error(`Knowledge merge cycle detected at ${node.id}`);
+			seen.add(node.id);
+			node = await this.#getNode(executor, node.mergedInto);
+		}
+		return node;
+	}
+	async #getKnowledge(executor, id, includeDeleted) {
+		const result = await executor.execute({
+			sql: `SELECT *,scope AS scopeJson FROM "${_mastra_core_storage.TABLE_KNOWLEDGE_RECORDS}" WHERE id=?${includeDeleted ? "" : " AND deletedAt IS NULL"}`,
+			args: [id]
+		});
+		return result.rows[0] ? parseKnowledge(result.rows[0]) : null;
+	}
+	async #queryKnowledge(input, relationship) {
+		const scope = (0, _mastra_core_storage.canonicalizeKnowledgeScope)(input.scope);
+		const node = await this.#resolveTerminalNode(this.#client, nodeReferenceId(input.node));
+		if (!node) return { records: [] };
+		const key = (0, _mastra_core_storage.knowledgeScopeKey)(scope);
+		const args = [
+			node.id,
+			...relationship === "related" ? [node.id] : [],
+			key,
+			key
+		];
+		if (input.after) args.push(input.after);
+		args.push((input.limit ?? 100) + 1);
+		const records = (await this.#client.execute({
+			sql: `SELECT DISTINCT f.*,f.scope AS scopeJson FROM "${_mastra_core_storage.TABLE_KNOWLEDGE_RECORDS}" f${relationship === "about" ? "" : ` LEFT JOIN "${_mastra_core_storage.TABLE_KNOWLEDGE_MENTIONS}" m ON m.sourceType='record' AND m.sourceId=f.id`} WHERE ${relationship === "about" ? "f.node=?" : relationship === "mentioning" ? "m.recordId=?" : "(f.node=? OR m.recordId=?)"} AND ${visibleSql.replaceAll("scopeKey", "f.scopeKey")}${input.includeDeleted ? "" : " AND f.deletedAt IS NULL"}${input.after ? " AND f.id < ?" : ""} ORDER BY f.id DESC LIMIT ?`,
+			args
+		})).rows.map(parseKnowledge);
+		const limit = input.limit ?? 100;
+		return {
+			records: records.slice(0, limit),
+			nextCursor: records.length > limit ? records[limit - 1]?.id : void 0
+		};
+	}
+	async #replaceMentions(tx, sourceType, sourceId, text, resolutionScope, defaultScope) {
+		await tx.execute({
+			sql: `DELETE FROM "${_mastra_core_storage.TABLE_KNOWLEDGE_MENTIONS}" WHERE sourceType=? AND sourceId=?`,
+			args: [sourceType, sourceId]
+		});
+		for (const name of (0, _mastra_core_storage.parseKnowledgeWikilinks)(text)) {
+			let node = await this.#resolveNode(tx, name, resolutionScope);
+			if (!node) {
+				node = await this.#getNodeByName(tx, name, defaultScope);
+				if (node) node = await this.#resolveTerminalNode(tx, node.id);
+				if (!node) {
+					const now = /* @__PURE__ */ new Date();
+					node = {
+						id: crypto.randomUUID(),
+						type: "node",
+						name,
+						kind: "node",
+						scope: defaultScope,
+						version: 1,
+						createdAt: now,
+						updatedAt: now
+					};
+					await tx.execute({
+						sql: `INSERT INTO "${_mastra_core_storage.TABLE_KNOWLEDGE_NODES}" (id,type,name,canonicalName,kind,content,scope,scopeKey,version,mergedInto,createdAt,updatedAt) VALUES (?,?,?,?,?,NULL,jsonb(?),?,?,NULL,?,?)`,
+						args: [
+							node.id,
+							"node",
+							node.name,
+							canonicalName(node.name),
+							node.kind,
+							JSON.stringify(defaultScope),
+							(0, _mastra_core_storage.knowledgeScopeKey)(defaultScope),
+							1,
+							now.toISOString()
+						]
+					});
+					await this.#activity(tx, "node-created", "node", node.id, defaultScope);
+					await this.#outbox(tx, "node", node.id, "upsert", 1, defaultScope);
+				}
+			}
+			await tx.execute({
+				sql: `INSERT OR IGNORE INTO "${_mastra_core_storage.TABLE_KNOWLEDGE_MENTIONS}" (sourceType,sourceId,recordId) VALUES (?,?,?)`,
+				args: [
+					sourceType,
+					sourceId,
+					node.id
+				]
+			});
+		}
+	}
+	async #activity(executor, action, recordType, recordId, scope, sourceThreadId) {
+		const now = /* @__PURE__ */ new Date();
+		await executor.execute({
+			sql: `INSERT INTO "${_mastra_core_storage.TABLE_KNOWLEDGE_ACTIVITY}" (id,action,recordType,recordId,scope,scopeKey,sourceThreadId,createdAt) VALUES (?,?,?,?,jsonb(?),?,?,?)`,
+			args: [
+				(0, _mastra_core_storage.createKnowledgeUlid)(),
+				action,
+				recordType,
+				recordId,
+				JSON.stringify(scope),
+				(0, _mastra_core_storage.knowledgeScopeKey)(scope),
+				sourceThreadId ?? null,
+				now.toISOString()
+			]
+		});
+	}
+	async #outbox(executor, documentType, id, operation, version, scope) {
+		const documentId = (0, _mastra_core_storage.knowledgeSemanticDocumentId)(documentType, id);
+		const idempotencyKey = (0, _mastra_core_storage.knowledgeSemanticIdempotencyKey)(documentId, operation, version);
+		const now = /* @__PURE__ */ new Date();
+		await executor.execute({
+			sql: `INSERT OR IGNORE INTO "${_mastra_core_storage.TABLE_KNOWLEDGE_SEMANTIC_OUTBOX}" (id,idempotencyKey,documentId,documentType,operation,scope,scopeKey,status,attempts,availableAt,claimedAt,claimedBy,createdAt,completedAt) VALUES (?,?,?,?,?,jsonb(?),?,'pending',0,?,NULL,NULL,?,NULL)`,
+			args: [
+				(0, _mastra_core_storage.createKnowledgeUlid)(),
+				idempotencyKey,
+				documentId,
+				documentType,
+				operation,
+				JSON.stringify(scope),
+				(0, _mastra_core_storage.knowledgeScopeKey)(scope),
+				now.toISOString(),
+				now.toISOString()
+			]
+		});
+	}
+};
+//#endregion
 //#region src/storage/domains/mcp-clients/index.ts
 var MCPClientsMySQL = class MCPClientsMySQL extends _mastra_core_storage.MCPClientsStorage {
 	pool;
@@ -4836,10 +5791,14 @@ var MemoryMySQL = class MemoryMySQL extends _mastra_core_storage.MemoryStorage {
 			schema: _mastra_core_storage.TABLE_SCHEMAS[_mastra_core_storage.TABLE_MESSAGES],
 			ifNotExists: ["resourceId"]
 		});
-		if (omSchema) try {
-			await this.pool.execute(`CREATE INDEX idx_om_lookup_key ON ${OM_TABLE_QUOTED} (${quoteIdentifier("lookupKey", "column name")}(191))`);
-		} catch (err) {
-			if (err?.errno !== 1061) throw err;
+		if (omSchema) {
+			const snapshot = this.operations.getInitSchemaSnapshot();
+			if (!snapshot?.indexes.has(indexKey(OM_TABLE, "idx_om_lookup_key"))) try {
+				await this.pool.execute(`CREATE INDEX idx_om_lookup_key ON ${OM_TABLE_QUOTED} (${quoteIdentifier("lookupKey", "column name")}(191))`);
+				snapshot?.indexes.add(indexKey(OM_TABLE, "idx_om_lookup_key"));
+			} catch (err) {
+				if (err?.errno !== 1061) throw err;
+			}
 		}
 		await this.createDefaultIndexes();
 		await this.createCustomIndexes();
@@ -10358,6 +11317,7 @@ function parseConnectionString(connectionString, overrides) {
 }
 var MySQLStore = class extends _mastra_core_storage.MastraCompositeStore {
 	pool;
+	operations;
 	stores;
 	constructor(config) {
 		super({
@@ -10372,12 +11332,17 @@ var MySQLStore = class extends _mastra_core_storage.MastraCompositeStore {
 			pool: this.pool,
 			database
 		});
+		this.operations = operations;
 		const memory = new MemoryMySQL({
 			pool: this.pool,
 			operations,
 			skipDefaultIndexes: config.skipDefaultIndexes,
 			indexes: config.indexes
 		});
+		const knowledge = new KnowledgeMySQL({
+			pool: this.pool,
+			operations
+		});
 		const workflows = new WorkflowsMySQL({
 			operations,
 			pool: this.pool,
@@ -10490,6 +11455,7 @@ var MySQLStore = class extends _mastra_core_storage.MastraCompositeStore {
 		});
 		this.stores = {
 			memory,
+			knowledge,
 			workflows,
 			scores,
 			observability,
@@ -10514,6 +11480,7 @@ var MySQLStore = class extends _mastra_core_storage.MastraCompositeStore {
 	async init() {
 		try {
 			(await this.pool.getConnection()).release();
+			await this.operations.loadInitSchemaSnapshot();
 			await super.init();
 		} catch (error) {
 			throw new _mastra_core_error.MastraError({
@@ -10521,6 +11488,8 @@ var MySQLStore = class extends _mastra_core_storage.MastraCompositeStore {
 				domain: _mastra_core_error.ErrorDomain.STORAGE,
 				category: _mastra_core_error.ErrorCategory.THIRD_PARTY
 			}, error);
+		} finally {
+			this.operations.clearInitSchemaSnapshot();
 		}
 	}
 	async close() {