@mastra/mysql 0.12.2-alpha.0 → 0.13.0-alpha.1

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, 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, executeRetentionPrune, hasErrorCode, isKnowledgeScopeVisible, knowledgeScopeKey, knowledgeSemanticDocumentId, knowledgeSemanticIdempotencyKey, listTracesArgsSchema, matchesExpectedWorkflowStatus, normalizePerPage, normalizeScheduleTarget, parseKnowledgeNodeCursor, parseKnowledgeWikilinks, resolveListOrderBy, resolveRetentionTargets, retentionCutoffMs, 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_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_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, calculatePagination, canonicalizeKnowledgeScope, createKnowledgeUlid, createStorageErrorId, executeRetentionPrune, hasErrorCode, isKnowledgeScopeVisible, knowledgeScopeKey, knowledgeSemanticDocumentId, knowledgeSemanticIdempotencyKey, listTracesArgsSchema, matchesExpectedWorkflowStatus, normalizePerPage, normalizeScheduleTarget, parseKnowledgeNodeCursor, parseKnowledgeWikilinks, resolveListOrderBy, resolveRetentionTargets, retentionCutoffMs, toTraceSpans, validateStorageMetadataFilter } from "@mastra/core/storage";
 import { createPool } from "mysql2/promise";
 import { parseSqlIdentifier } from "@mastra/core/utils";
 import { MessageList } from "@mastra/core/agent";
@@ -4174,6 +4174,13 @@ async function assertKnowledgeDescriptionWithinBoundCompat(description) {
 	}
 	assertWithinBound(description);
 }
+let assertRecordTextWithinBound;
+async function assertKnowledgeRecordTextWithinBoundCompat(text) {
+	if (!assertRecordTextWithinBound) assertRecordTextWithinBound = (await import("@mastra/core/storage")).assertKnowledgeRecordTextWithinBound ?? ((value) => {
+		if (value.length > 1e3) throw new Error("Knowledge record text exceeds the 1000 UTF-16 code unit limit; split it into separate facts or summarize it");
+	});
+	assertRecordTextWithinBound(text);
+}
 function mysqlSql(sql) {
 	return sql.replaceAll("jsonb(?)", "CAST(? AS JSON)").replaceAll("INSERT OR IGNORE", "INSERT IGNORE").replaceAll("\"", "`");
 }
@@ -4192,7 +4199,21 @@ function createExecutor(client) {
 		};
 	} };
 }
-const visibleSql = `(scopeKey = ? OR LEFT(?, CHAR_LENGTH(scopeKey) + 1) = CONCAT(scopeKey, char(31)))`;
+/**
+* Scope keys visible to a caller holding `scope`: a row is visible when its scope is a subset of the
+* caller's (companion entries such as `resource:x:uncurated` make this more than a prefix match).
+* Matching rows by `scopeKey` keeps visibility filters on an index; a caller scope has only a few
+* entries, so the list stays small.
+*/
+function visibleScopeKeys(scope) {
+	const canonical = canonicalizeKnowledgeScope(scope);
+	const keys = /* @__PURE__ */ new Set();
+	for (let mask = 1; mask < 1 << canonical.length; mask++) try {
+		keys.add(knowledgeScopeKey(canonical.filter((_, index) => mask & 1 << index)));
+	} catch {}
+	return [...keys];
+}
+const visibleSql = (keys, scopeKeyColumn = "scopeKey") => `${scopeKeyColumn} IN (${keys.map(() => "?").join(",")})`;
 function parseJson$1(value) {
 	if (typeof value === "string") return JSON.parse(value);
 	if (value instanceof Uint8Array) return JSON.parse(new TextDecoder().decode(value));
@@ -4242,7 +4263,6 @@ function parseKnowledge(row) {
 		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)
@@ -4268,13 +4288,17 @@ function parseOutbox(row) {
 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_nodes_name ON "${TABLE_KNOWLEDGE_NODES}" (type(32), canonicalName(255))`,
 	`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 INDEX idx_knowledge_records_scope ON "${TABLE_KNOWLEDGE_RECORDS}" (scopeKey(255), id(26))`,
+	`CREATE INDEX idx_knowledge_activity_scope ON "${TABLE_KNOWLEDGE_ACTIVITY}" (scopeKey(255), 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)`
 ];
+const KNOWLEDGE_CURATION_CURSOR_REMOVED_MESSAGE = "Knowledge curation cursors were removed: observation-time curate is the only Knowledge writer and needs no cursor.";
 var KnowledgeMySQL = class extends KnowledgeStorage {
 	static getExportDDL() {
 		return [
@@ -4295,11 +4319,6 @@ var KnowledgeMySQL = class extends KnowledgeStorage {
 					"recordId"
 				]
 			}),
-			generateTableSQL({
-				tableName: TABLE_KNOWLEDGE_CURSORS,
-				schema: KNOWLEDGE_CURSORS_SCHEMA,
-				compositePrimaryKey: ["sourceThreadId", "agent"]
-			}),
 			generateTableSQL({
 				tableName: TABLE_KNOWLEDGE_ACTIVITY,
 				schema: KNOWLEDGE_ACTIVITY_SCHEMA
@@ -4338,10 +4357,6 @@ var KnowledgeMySQL = class extends KnowledgeStorage {
 			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
@@ -4362,7 +4377,6 @@ var KnowledgeMySQL = class extends KnowledgeStorage {
 				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}"`);
@@ -4370,6 +4384,11 @@ var KnowledgeMySQL = class extends KnowledgeStorage {
 	}
 	async createNode(input) {
 		await assertKnowledgeDescriptionWithinBoundCompat(input.description);
+		if (input.scopeAddresses?.length) {
+			const error = /* @__PURE__ */ new Error("This Knowledge storage adapter does not expose structural scope placement.");
+			error.name = "KnowledgeUnsupportedCapabilityError";
+			throw error;
+		}
 		const scope = canonicalizeKnowledgeScope(input.scope);
 		return this.#transaction(async (tx) => {
 			const existing = await this.#getNodeByName(tx, input.name, scope);
@@ -4424,13 +4443,13 @@ var KnowledgeMySQL = class extends KnowledgeStorage {
 		return this.#resolveNode(this.#client, input.name, canonicalizeKnowledgeScope(input.scope));
 	}
 	async listNodes(input) {
-		const key = knowledgeScopeKey(canonicalizeKnowledgeScope(input.scope));
+		const keys = visibleScopeKeys(canonicalizeKnowledgeScope(input.scope));
 		const clauses = [
 			`type = 'node'`,
 			"mergedInto IS NULL",
-			visibleSql
+			visibleSql(keys)
 		];
-		const args = [key, key];
+		const args = [...keys];
 		if (input.namePrefix) {
 			clauses.push("canonicalName LIKE ? ESCAPE '='");
 			args.push(`${escapeLikePattern(canonicalName(input.namePrefix))}%`);
@@ -4577,10 +4596,10 @@ var KnowledgeMySQL = class extends KnowledgeStorage {
 		});
 	}
 	async appendKnowledge(input) {
+		await assertKnowledgeRecordTextWithinBoundCompat(input.text);
 		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));
@@ -4592,11 +4611,10 @@ var KnowledgeMySQL = class extends KnowledgeStorage {
 				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)`,
+				sql: `INSERT INTO "${TABLE_KNOWLEDGE_RECORDS}" (id,node,text,scope,scopeKey,sourceThreadId,capturedAt,"when",metadata,deletedAt,deletedBy) VALUES (?,?,?,jsonb(?),?,?,?,?,jsonb(?),NULL,NULL)`,
 				args: [
 					record.id,
 					record.node,
@@ -4606,7 +4624,6 @@ var KnowledgeMySQL = class extends KnowledgeStorage {
 					record.sourceThreadId,
 					record.capturedAt.toISOString(),
 					record.when?.toISOString() ?? null,
-					record.maxScope ?? null,
 					record.metadata ? JSON.stringify(record.metadata) : null
 				]
 			});
@@ -4633,17 +4650,13 @@ var KnowledgeMySQL = class extends KnowledgeStorage {
 		return this.#queryKnowledge(input, "related");
 	}
 	async knowledgeBySource(input) {
-		const key = knowledgeScopeKey(canonicalizeKnowledgeScope(input.scope));
-		const args = [
-			input.sourceThreadId,
-			key,
-			key
-		];
+		const keys = visibleScopeKeys(canonicalizeKnowledgeScope(input.scope));
+		const args = [input.sourceThreadId, ...keys];
 		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 ?`,
+			sql: `SELECT *,scope AS scopeJson FROM "${TABLE_KNOWLEDGE_RECORDS}" WHERE sourceThreadId=? AND ${visibleSql(keys)}${input.includeDeleted ? "" : " AND deletedAt IS NULL"}${input.after ? " AND id > ?" : ""} ORDER BY id ASC LIMIT ?`,
 			args
 		})).rows.map(parseKnowledge);
 		return {
@@ -4697,7 +4710,6 @@ var KnowledgeMySQL = class extends KnowledgeStorage {
 		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: [
@@ -4715,33 +4727,16 @@ var KnowledgeMySQL = class extends KnowledgeStorage {
 			};
 		});
 	}
-	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 keys = visibleScopeKeys(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 '=' OR lower(COALESCE(description,'')) LIKE ? ESCAPE '=') ORDER BY updatedAt DESC LIMIT ?`,
+			sql: `SELECT *,scope AS scopeJson FROM "${TABLE_KNOWLEDGE_NODES}" WHERE mergedInto IS NULL AND ${visibleSql(keys)} AND (canonicalName LIKE ? ESCAPE '=' OR lower(COALESCE(kind,'')) LIKE ? ESCAPE '=' OR lower(COALESCE(content,'')) LIKE ? ESCAPE '=' OR lower(COALESCE(description,'')) LIKE ? ESCAPE '=') ORDER BY updatedAt DESC LIMIT ?`,
 			args: [
-				key,
-				key,
+				...keys,
 				query,
 				query,
 				query,
@@ -4762,10 +4757,9 @@ var KnowledgeMySQL = class extends KnowledgeStorage {
 		}));
 		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 ?`,
+				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(keys, "f.scopeKey")} AND lower(f.text) LIKE ? ESCAPE '=' ORDER BY f.id DESC LIMIT ?`,
 				args: [
-					key,
-					key,
+					...keys,
 					query,
 					(input.limit ?? 20) - results.length
 				]
@@ -4775,7 +4769,7 @@ var KnowledgeMySQL = class extends KnowledgeStorage {
 				return {
 					type: "record",
 					id: String(row.id),
-					recordId: String(row.node),
+					recordId: parentVisible ? String(row.node) : String(row.id),
 					name: parentVisible ? String(row.name) : "(private node)",
 					text: String(row.text),
 					scope: parseJson$1(row.scopeJson)
@@ -4784,41 +4778,26 @@ var KnowledgeMySQL = class extends KnowledgeStorage {
 		}
 		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
-		};
+	/**
+	* @deprecated Curation cursors were removed. Observation-time curate is the only Knowledge writer and needs no
+	* cursor. Always throws.
+	*/
+	async getCurationCursor(_input) {
+		throw new Error(KNOWLEDGE_CURATION_CURSOR_REMOVED_MESSAGE);
+	}
+	/**
+	* @deprecated Curation cursors were removed. Observation-time curate is the only Knowledge writer and needs no
+	* cursor. Always throws.
+	*/
+	async advanceCurationCursor(_input) {
+		throw new Error(KNOWLEDGE_CURATION_CURSOR_REMOVED_MESSAGE);
 	}
 	async listActivity(input) {
-		const key = knowledgeScopeKey(canonicalizeKnowledgeScope(input.scope));
+		const keys = visibleScopeKeys(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 ?`,
+			sql: `SELECT *,scope AS scopeJson FROM "${TABLE_KNOWLEDGE_ACTIVITY}" WHERE ${visibleSql(keys)}${input.after ? " AND id < ?" : ""} ORDER BY id DESC LIMIT ?`,
 			args: [
-				key,
-				key,
+				...keys,
 				...input.after ? [input.after] : [],
 				input.limit ?? 100
 			]
@@ -4840,9 +4819,9 @@ var KnowledgeMySQL = class extends KnowledgeStorage {
 			args.push(input.status);
 		}
 		if (input.scope) {
-			const key = knowledgeScopeKey(canonicalizeKnowledgeScope(input.scope));
-			clauses.push(visibleSql);
-			args.push(key, key);
+			const keys = visibleScopeKeys(input.scope);
+			clauses.push(visibleSql(keys));
+			args.push(...keys);
 		}
 		args.push(input.limit ?? 100);
 		return (await this.#client.execute({
@@ -4861,9 +4840,9 @@ var KnowledgeMySQL = class extends KnowledgeStorage {
 			];
 			const args = [now.toISOString(), stale.toISOString()];
 			if (input.scope) {
-				const key = knowledgeScopeKey(canonicalizeKnowledgeScope(input.scope));
-				clauses.push(visibleSql);
-				args.push(key, key);
+				const keys = visibleScopeKeys(input.scope);
+				clauses.push(visibleSql(keys));
+				args.push(...keys);
 			}
 			args.push(input.limit ?? 100);
 			const ids = (await tx.execute({
@@ -4941,12 +4920,14 @@ var KnowledgeMySQL = class extends KnowledgeStorage {
 		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;
-			}
+		const keys = visibleScopeKeys(scope);
+		const candidates = (await executor.execute({
+			sql: `SELECT *,scope AS scopeJson FROM "${TABLE_KNOWLEDGE_NODES}" WHERE type='node' AND canonicalName=? AND (scopeKey IN (${keys.map(() => "?").join(",")}) OR mergedInto IS NOT NULL)`,
+			args: [canonicalName(name), ...keys]
+		})).rows.map(parseNode).sort((left, right) => right.scope.length - left.scope.length);
+		for (const candidate of candidates) {
+			const terminal = await this.#resolveTerminalNode(executor, candidate.id);
+			if (terminal && isKnowledgeScopeVisible(terminal.scope, scope)) return terminal;
 		}
 		return null;
 	}
@@ -4971,17 +4952,16 @@ var KnowledgeMySQL = class extends KnowledgeStorage {
 		const scope = canonicalizeKnowledgeScope(input.scope);
 		const node = await this.#resolveTerminalNode(this.#client, nodeReferenceId(input.node));
 		if (!node) return { records: [] };
-		const key = knowledgeScopeKey(scope);
+		const keys = visibleScopeKeys(scope);
 		const args = [
 			node.id,
 			...relationship === "related" ? [node.id] : [],
-			key,
-			key
+			...keys
 		];
 		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 ?`,
+			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(keys, "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;