@mastra/mysql 0.7.1-alpha.2 → 0.8.0

package/dist/index.js

@@ -1,5 +1,5 @@
 import { ErrorCategory, ErrorDomain, MastraError } from "@mastra/core/error";
-import { AGENTS_SCHEMA, AGENT_VERSIONS_SCHEMA, AgentsStorage, BackgroundTasksStorage, BlobStore, ChannelsStorage, DATASETS_SCHEMA, DATASET_ITEMS_SCHEMA, DATASET_VERSIONS_SCHEMA, DatasetsStorage, EXPERIMENTS_SCHEMA, EXPERIMENT_RESULTS_SCHEMA, ExperimentsStorage, FAVORITES_SCHEMA, FavoritesStorage, MCPClientsStorage, MCPServersStorage, MCP_CLIENTS_SCHEMA, MCP_CLIENT_VERSIONS_SCHEMA, MCP_SERVERS_SCHEMA, MCP_SERVER_VERSIONS_SCHEMA, MastraCompositeStore, MemoryStorage, OBSERVATIONAL_MEMORY_TABLE_SCHEMA, ObservabilityStorage, PROMPT_BLOCKS_SCHEMA, PROMPT_BLOCK_VERSIONS_SCHEMA, PromptBlocksStorage, SCORERS_SCHEMA, SCORER_DEFINITIONS_SCHEMA, SCORER_DEFINITION_VERSIONS_SCHEMA, SKILLS_SCHEMA, SKILL_BLOBS_SCHEMA, SKILL_VERSIONS_SCHEMA, SPAN_SCHEMA, SchedulesStorage, ScorerDefinitionsStorage, ScoresStorage, SkillsStorage, StoreOperations, TABLE_AGENTS, TABLE_AGENT_VERSIONS, TABLE_BACKGROUND_TASKS, TABLE_CHANNEL_CONFIG, TABLE_CHANNEL_INSTALLATIONS, TABLE_CONFIGS, TABLE_DATASETS, TABLE_DATASET_ITEMS, TABLE_DATASET_VERSIONS, TABLE_EXPERIMENTS, TABLE_EXPERIMENT_RESULTS, TABLE_FAVORITES, TABLE_MCP_CLIENTS, TABLE_MCP_CLIENT_VERSIONS, TABLE_MCP_SERVERS, TABLE_MCP_SERVER_VERSIONS, TABLE_MESSAGES, TABLE_PROMPT_BLOCKS, TABLE_PROMPT_BLOCK_VERSIONS, TABLE_RESOURCES, TABLE_SCHEDULES, TABLE_SCHEDULE_TRIGGERS, TABLE_SCHEMAS, TABLE_SCORERS, TABLE_SCORER_DEFINITIONS, TABLE_SCORER_DEFINITION_VERSIONS, TABLE_SKILLS, TABLE_SKILL_BLOBS, TABLE_SKILL_VERSIONS, TABLE_SPANS, TABLE_THREADS, TABLE_TOOL_PROVIDER_CONNECTIONS, TABLE_WORKFLOW_DEFINITIONS, TABLE_WORKFLOW_SNAPSHOT, TABLE_WORKSPACES, TABLE_WORKSPACE_VERSIONS, TOOL_PROVIDER_CONNECTIONS_SCHEMA, ToolProviderConnectionsStorage, TraceStatus, WORKFLOW_DEFINITIONS_SCHEMA, WORKSPACES_SCHEMA, WORKSPACE_VERSIONS_SCHEMA, WorkflowDefinitionsStorage, WorkflowsStorage, WorkspacesStorage, calculatePagination, createStorageErrorId, hasErrorCode, listTracesArgsSchema, normalizePerPage, normalizeScheduleTarget, toTraceSpans, validateStorageMetadataFilter } from "@mastra/core/storage";
+import { AGENTS_SCHEMA, AGENT_VERSIONS_SCHEMA, AgentsStorage, BackgroundTasksStorage, BlobStore, ChannelsStorage, DATASETS_SCHEMA, DATASET_ITEMS_SCHEMA, DATASET_VERSIONS_SCHEMA, DatasetsStorage, EXPERIMENTS_SCHEMA, EXPERIMENT_RESULTS_SCHEMA, ExperimentsStorage, FAVORITES_SCHEMA, FavoritesStorage, KNOWLEDGE_ACTIVITY_SCHEMA, KNOWLEDGE_CURSORS_SCHEMA, KNOWLEDGE_MENTIONS_SCHEMA, KNOWLEDGE_NODES_SCHEMA, KNOWLEDGE_RECORDS_SCHEMA, KNOWLEDGE_SEMANTIC_OUTBOX_SCHEMA, KnowledgeConflictError, KnowledgeNotFoundError, KnowledgeStorage, MCPClientsStorage, MCPServersStorage, MCP_CLIENTS_SCHEMA, MCP_CLIENT_VERSIONS_SCHEMA, MCP_SERVERS_SCHEMA, MCP_SERVER_VERSIONS_SCHEMA, MastraCompositeStore, MemoryStorage, OBSERVATIONAL_MEMORY_TABLE_SCHEMA, ObservabilityStorage, PROMPT_BLOCKS_SCHEMA, PROMPT_BLOCK_VERSIONS_SCHEMA, PromptBlocksStorage, SCORERS_SCHEMA, SCORER_DEFINITIONS_SCHEMA, SCORER_DEFINITION_VERSIONS_SCHEMA, SKILLS_SCHEMA, SKILL_BLOBS_SCHEMA, SKILL_VERSIONS_SCHEMA, SPAN_SCHEMA, SchedulesStorage, ScorerDefinitionsStorage, ScoresStorage, SkillsStorage, StoreOperations, TABLE_AGENTS, TABLE_AGENT_VERSIONS, TABLE_BACKGROUND_TASKS, TABLE_CHANNEL_CONFIG, TABLE_CHANNEL_INSTALLATIONS, TABLE_CONFIGS, TABLE_DATASETS, TABLE_DATASET_ITEMS, TABLE_DATASET_VERSIONS, TABLE_EXPERIMENTS, TABLE_EXPERIMENT_RESULTS, TABLE_FAVORITES, TABLE_KNOWLEDGE_ACTIVITY, TABLE_KNOWLEDGE_CURSORS, TABLE_KNOWLEDGE_MENTIONS, TABLE_KNOWLEDGE_NODES, TABLE_KNOWLEDGE_RECORDS, TABLE_KNOWLEDGE_SEMANTIC_OUTBOX, TABLE_MCP_CLIENTS, TABLE_MCP_CLIENT_VERSIONS, TABLE_MCP_SERVERS, TABLE_MCP_SERVER_VERSIONS, TABLE_MESSAGES, TABLE_PROMPT_BLOCKS, TABLE_PROMPT_BLOCK_VERSIONS, TABLE_RESOURCES, TABLE_SCHEDULES, TABLE_SCHEDULE_TRIGGERS, TABLE_SCHEMAS, TABLE_SCORERS, TABLE_SCORER_DEFINITIONS, TABLE_SCORER_DEFINITION_VERSIONS, TABLE_SKILLS, TABLE_SKILL_BLOBS, TABLE_SKILL_VERSIONS, TABLE_SPANS, TABLE_THREADS, TABLE_TOOL_PROVIDER_CONNECTIONS, TABLE_WORKFLOW_DEFINITIONS, TABLE_WORKFLOW_SNAPSHOT, TABLE_WORKSPACES, TABLE_WORKSPACE_VERSIONS, TOOL_PROVIDER_CONNECTIONS_SCHEMA, ToolProviderConnectionsStorage, TraceStatus, WORKFLOW_DEFINITIONS_SCHEMA, WORKSPACES_SCHEMA, WORKSPACE_VERSIONS_SCHEMA, WorkflowDefinitionsStorage, WorkflowsStorage, WorkspacesStorage, assertKnowledgeCeilingRaised, assertKnowledgeScopeWithinCeiling, calculatePagination, canonicalizeKnowledgeScope, createKnowledgeUlid, createStorageErrorId, hasErrorCode, isKnowledgeScopeVisible, knowledgeScopeKey, knowledgeSemanticDocumentId, knowledgeSemanticIdempotencyKey, listTracesArgsSchema, normalizePerPage, normalizeScheduleTarget, parseKnowledgeNodeCursor, parseKnowledgeWikilinks, toTraceSpans, validateStorageMetadataFilter } from "@mastra/core/storage";
 import { createPool } from "mysql2/promise";
 import { parseSqlIdentifier } from "@mastra/core/utils";
 import { randomUUID } from "crypto";
@@ -730,7 +730,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) {
@@ -754,9 +754,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";
@@ -1371,7 +1371,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);
@@ -1386,14 +1386,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),
@@ -3821,6 +3821,871 @@ var FavoritesMySQL = class FavoritesMySQL extends FavoritesStorage {
 	}
 };
 //#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 "${TABLE_KNOWLEDGE_NODES}" (type(32), scopeKey(255), canonicalName(255))`,
+	`CREATE INDEX idx_knowledge_nodes_scope ON "${TABLE_KNOWLEDGE_NODES}" (scopeKey(255), type(32))`,
+	`CREATE INDEX idx_knowledge_records_node_latest ON "${TABLE_KNOWLEDGE_RECORDS}" (node(191), id(26) DESC)`,
+	`CREATE INDEX idx_knowledge_records_thread_latest ON "${TABLE_KNOWLEDGE_RECORDS}" (sourceThreadId(191), id(26) DESC)`,
+	`CREATE INDEX idx_knowledge_mentions_record ON "${TABLE_KNOWLEDGE_MENTIONS}" (recordId(191), sourceType(32), sourceId(191))`,
+	`CREATE INDEX idx_knowledge_activity_latest ON "${TABLE_KNOWLEDGE_ACTIVITY}" (id(26) DESC)`,
+	`CREATE UNIQUE INDEX idx_knowledge_outbox_idempotency ON "${TABLE_KNOWLEDGE_SEMANTIC_OUTBOX}" (idempotencyKey(255))`,
+	`CREATE INDEX idx_knowledge_outbox_claim ON "${TABLE_KNOWLEDGE_SEMANTIC_OUTBOX}" (status(32), availableAt, createdAt)`
+];
+var KnowledgeMySQL = class extends KnowledgeStorage {
+	static getExportDDL() {
+		return [
+			generateTableSQL({
+				tableName: TABLE_KNOWLEDGE_NODES,
+				schema: KNOWLEDGE_NODES_SCHEMA
+			}),
+			generateTableSQL({
+				tableName: TABLE_KNOWLEDGE_RECORDS,
+				schema: KNOWLEDGE_RECORDS_SCHEMA
+			}),
+			generateTableSQL({
+				tableName: TABLE_KNOWLEDGE_MENTIONS,
+				schema: KNOWLEDGE_MENTIONS_SCHEMA,
+				compositePrimaryKey: [
+					"sourceType",
+					"sourceId",
+					"recordId"
+				]
+			}),
+			generateTableSQL({
+				tableName: TABLE_KNOWLEDGE_CURSORS,
+				schema: KNOWLEDGE_CURSORS_SCHEMA,
+				compositePrimaryKey: ["sourceThreadId", "agent"]
+			}),
+			generateTableSQL({
+				tableName: TABLE_KNOWLEDGE_ACTIVITY,
+				schema: KNOWLEDGE_ACTIVITY_SCHEMA
+			}),
+			generateTableSQL({
+				tableName: TABLE_KNOWLEDGE_SEMANTIC_OUTBOX,
+				schema: 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: TABLE_KNOWLEDGE_NODES,
+			schema: KNOWLEDGE_NODES_SCHEMA
+		});
+		await this.#operations.createTable({
+			tableName: TABLE_KNOWLEDGE_RECORDS,
+			schema: KNOWLEDGE_RECORDS_SCHEMA
+		});
+		await this.#operations.createTable({
+			tableName: TABLE_KNOWLEDGE_MENTIONS,
+			schema: KNOWLEDGE_MENTIONS_SCHEMA
+		});
+		await this.#operations.createTable({
+			tableName: TABLE_KNOWLEDGE_CURSORS,
+			schema: KNOWLEDGE_CURSORS_SCHEMA
+		});
+		await this.#operations.createTable({
+			tableName: TABLE_KNOWLEDGE_ACTIVITY,
+			schema: KNOWLEDGE_ACTIVITY_SCHEMA
+		});
+		await this.#operations.createTable({
+			tableName: TABLE_KNOWLEDGE_SEMANTIC_OUTBOX,
+			schema: 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 [
+				TABLE_KNOWLEDGE_MENTIONS,
+				TABLE_KNOWLEDGE_RECORDS,
+				TABLE_KNOWLEDGE_NODES,
+				TABLE_KNOWLEDGE_CURSORS,
+				TABLE_KNOWLEDGE_ACTIVITY,
+				TABLE_KNOWLEDGE_SEMANTIC_OUTBOX
+			]) await tx.execute(`DELETE FROM "${table}"`);
+		});
+	}
+	async createNode(input) {
+		const scope = 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 (!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 "${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),
+					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, canonicalizeKnowledgeScope(input.scope));
+	}
+	async resolveNode(input) {
+		return this.#resolveNode(this.#client, input.name, canonicalizeKnowledgeScope(input.scope));
+	}
+	async listNodes(input) {
+		const key = knowledgeScopeKey(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 = 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 "${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 KnowledgeNotFoundError("node", input.id);
+			if (existing.mergedInto) throw new Error(`Cannot update merged knowledge node: ${input.id}`);
+			const scope = 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 "${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),
+					knowledgeScopeKey(scope),
+					now.toISOString(),
+					input.id,
+					input.version
+				]
+			})).rowsAffected === 0) throw new 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 (knowledgeScopeKey(existing.scope) !== knowledgeScopeKey(scope)) {
+				await this.#outbox(tx, "node", input.id, "delete", createKnowledgeUlid(), existing.scope);
+				const records = await tx.execute({
+					sql: `SELECT id,scope AS scopeJson,deletedAt FROM "${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", createKnowledgeUlid(), factScope);
+					if (row.deletedAt == null) await this.#outbox(tx, "record", String(row.id), "upsert", 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 KnowledgeNotFoundError("node", input.sourceId);
+			const target = await this.#resolveTerminalNode(tx, input.targetId);
+			if (!target) throw new KnowledgeNotFoundError("node", input.targetId);
+			if (target.id === source.id) throw new Error("Cannot create a knowledge merge cycle");
+			if (!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 "${TABLE_KNOWLEDGE_MENTIONS}" m LEFT JOIN "${TABLE_KNOWLEDGE_RECORDS}" f ON m.sourceType='record' AND f.id=m.sourceId LEFT JOIN "${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 "${TABLE_KNOWLEDGE_RECORDS}" WHERE node=?`,
+				args: [source.id]
+			});
+			if ((await tx.execute({
+				sql: `UPDATE "${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 KnowledgeConflictError(source.id);
+			await tx.execute({
+				sql: `UPDATE "${TABLE_KNOWLEDGE_RECORDS}" SET node=? WHERE node=?`,
+				args: [target.id, source.id]
+			});
+			await tx.execute({
+				sql: `DELETE source FROM "${TABLE_KNOWLEDGE_MENTIONS}" source JOIN "${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 "${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", 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", 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", createKnowledgeUlid(), target.scope);
+			return target;
+		});
+	}
+	async appendKnowledge(input) {
+		const scope = canonicalizeKnowledgeScope(input.scope);
+		const resolutionScope = canonicalizeKnowledgeScope(input.resolutionScope);
+		const defaultScope = canonicalizeKnowledgeScope(input.defaultScope);
+		assertKnowledgeScopeWithinCeiling(scope, input.maxScope);
+		return this.#transaction(async (tx) => {
+			const parent = await this.#resolveTerminalNode(tx, nodeReferenceId(input.node));
+			if (!parent) throw new KnowledgeNotFoundError("node", nodeReferenceId(input.node));
+			const record = {
+				id: input.id ?? 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 "${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),
+					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 "${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 = knowledgeScopeKey(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 "${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 KnowledgeNotFoundError("record", input.id);
+			if (record.deletedAt) return record;
+			const deletedAt = /* @__PURE__ */ new Date();
+			await tx.execute({
+				sql: `UPDATE "${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 KnowledgeNotFoundError("record", input.id);
+			if (!record.deletedAt) return record;
+			await tx.execute({
+				sql: `UPDATE "${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", createKnowledgeUlid(), record.scope);
+			return {
+				...record,
+				deletedAt: void 0,
+				deletedBy: void 0
+			};
+		});
+	}
+	async rescopeKnowledge(input) {
+		const scope = canonicalizeKnowledgeScope(input.scope);
+		return this.#transaction(async (tx) => {
+			const record = await this.#getKnowledge(tx, input.id, true);
+			if (!record) throw new KnowledgeNotFoundError("record", input.id);
+			assertKnowledgeScopeWithinCeiling(scope, record.maxScope);
+			await tx.execute({
+				sql: `UPDATE "${TABLE_KNOWLEDGE_RECORDS}" SET scope=jsonb(?),scopeKey=? WHERE id=?`,
+				args: [
+					JSON.stringify(scope),
+					knowledgeScopeKey(scope),
+					input.id
+				]
+			});
+			await this.#activity(tx, "record-rescoped", "record", input.id, scope, record.sourceThreadId);
+			if (knowledgeScopeKey(record.scope) !== knowledgeScopeKey(scope)) await this.#outbox(tx, "record", input.id, "delete", createKnowledgeUlid(), record.scope);
+			if (!record.deletedAt) await this.#outbox(tx, "record", input.id, "upsert", 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 KnowledgeNotFoundError("record", input.id);
+			assertKnowledgeScopeWithinCeiling(record.scope, input.maxScope);
+			assertKnowledgeCeilingRaised(record.maxScope, input.maxScope);
+			await tx.execute({
+				sql: `UPDATE "${TABLE_KNOWLEDGE_RECORDS}" SET maxScope=? WHERE id=?`,
+				args: [input.maxScope ?? null, input.id]
+			});
+			return {
+				...record,
+				maxScope: input.maxScope
+			};
+		});
+	}
+	async search(input) {
+		const scope = canonicalizeKnowledgeScope(input.scope);
+		const key = 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 "${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 "${TABLE_KNOWLEDGE_RECORDS}" f JOIN "${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 = 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 "${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 "${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 = knowledgeScopeKey(canonicalizeKnowledgeScope(input.scope));
+		return (await this.#client.execute({
+			sql: `SELECT *,scope AS scopeJson FROM "${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 = knowledgeScopeKey(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 "${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 "${TABLE_KNOWLEDGE_SEMANTIC_OUTBOX}" AS earlier WHERE earlier.documentId = "${TABLE_KNOWLEDGE_SEMANTIC_OUTBOX}".documentId AND earlier.status != 'completed' AND (earlier.createdAt < "${TABLE_KNOWLEDGE_SEMANTIC_OUTBOX}".createdAt OR (earlier.createdAt = "${TABLE_KNOWLEDGE_SEMANTIC_OUTBOX}".createdAt AND earlier.id < "${TABLE_KNOWLEDGE_SEMANTIC_OUTBOX}".id)))`
+			];
+			const args = [now.toISOString(), stale.toISOString()];
+			if (input.scope) {
+				const key = knowledgeScopeKey(canonicalizeKnowledgeScope(input.scope));
+				clauses.push(visibleSql);
+				args.push(key, key);
+			}
+			args.push(input.limit ?? 100);
+			const ids = (await tx.execute({
+				sql: `SELECT id FROM "${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 "${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 "${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 "${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 "${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 "${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 "${TABLE_KNOWLEDGE_NODES}" WHERE type='node' AND scopeKey=? AND canonicalName=?`,
+			args: [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 && 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 "${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 = canonicalizeKnowledgeScope(input.scope);
+		const node = await this.#resolveTerminalNode(this.#client, nodeReferenceId(input.node));
+		if (!node) return { records: [] };
+		const key = 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 "${TABLE_KNOWLEDGE_RECORDS}" f${relationship === "about" ? "" : ` LEFT JOIN "${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 "${TABLE_KNOWLEDGE_MENTIONS}" WHERE sourceType=? AND sourceId=?`,
+			args: [sourceType, sourceId]
+		});
+		for (const name of 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 "${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),
+							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 "${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 "${TABLE_KNOWLEDGE_ACTIVITY}" (id,action,recordType,recordId,scope,scopeKey,sourceThreadId,createdAt) VALUES (?,?,?,?,jsonb(?),?,?,?)`,
+			args: [
+				createKnowledgeUlid(),
+				action,
+				recordType,
+				recordId,
+				JSON.stringify(scope),
+				knowledgeScopeKey(scope),
+				sourceThreadId ?? null,
+				now.toISOString()
+			]
+		});
+	}
+	async #outbox(executor, documentType, id, operation, version, scope) {
+		const documentId = knowledgeSemanticDocumentId(documentType, id);
+		const idempotencyKey = knowledgeSemanticIdempotencyKey(documentId, operation, version);
+		const now = /* @__PURE__ */ new Date();
+		await executor.execute({
+			sql: `INSERT OR IGNORE INTO "${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: [
+				createKnowledgeUlid(),
+				idempotencyKey,
+				documentId,
+				documentType,
+				operation,
+				JSON.stringify(scope),
+				knowledgeScopeKey(scope),
+				now.toISOString(),
+				now.toISOString()
+			]
+		});
+	}
+};
+//#endregion
 //#region src/storage/domains/mcp-clients/index.ts
 var MCPClientsMySQL = class MCPClientsMySQL extends MCPClientsStorage {
 	pool;
@@ -10473,6 +11338,10 @@ var MySQLStore = class extends MastraCompositeStore {
 			skipDefaultIndexes: config.skipDefaultIndexes,
 			indexes: config.indexes
 		});
+		const knowledge = new KnowledgeMySQL({
+			pool: this.pool,
+			operations
+		});
 		const workflows = new WorkflowsMySQL({
 			operations,
 			pool: this.pool,
@@ -10585,6 +11454,7 @@ var MySQLStore = class extends MastraCompositeStore {
 		});
 		this.stores = {
 			memory,
+			knowledge,
 			workflows,
 			scores,
 			observability,