@mastra/libsql 1.25.2-alpha.1 → 1.26.0-alpha.2

package/dist/index.cjs

@@ -8,6 +8,8 @@ let _mastra_core_vector_filter = require("@mastra/core/vector/filter");
 let fs_promises = require("fs/promises");
 let path = require("path");
 let _mastra_core_base = require("@mastra/core/base");
+let crypto$1 = require("crypto");
+let _mastra_core_features = require("@mastra/core/features");
 let _mastra_core_agent = require("@mastra/core/agent");
 let _mastra_core_evals = require("@mastra/core/evals");
 let _mastra_core_storage_domains_skills = require("@mastra/core/storage/domains/skills");
@@ -1787,7 +1789,7 @@ var LibSQLDB = class extends _mastra_core_base.MastraBase {
 	* @param args.tableName - The name of the table to create
 	* @param args.schema - The schema definition for the table columns
 	*/
-	async createTable({ tableName, schema, compositePrimaryKey }) {
+	async createTable({ tableName, schema, compositePrimaryKey, executor = this.client }) {
 		try {
 			const parsedTableName = (0, _mastra_core_utils.parseSqlIdentifier)(tableName, "table name");
 			if (compositePrimaryKey) {
@@ -1805,7 +1807,7 @@ var LibSQLDB = class extends _mastra_core_base.MastraBase {
 			if (tableName === _mastra_core_storage.TABLE_WORKFLOW_SNAPSHOT) tableConstraints.push("UNIQUE (workflow_name, run_id)");
 			if (tableName === _mastra_core_storage.TABLE_SPANS) tableConstraints.push("UNIQUE (spanId, traceId)");
 			const sql = `CREATE TABLE IF NOT EXISTS ${parsedTableName} (\n  ${[...columnDefinitions, ...tableConstraints].join(",\n  ")}\n)`;
-			await this.client.execute(sql);
+			await executor.execute(sql);
 			this.logger.debug(`LibSQLDB: Created table ${tableName}`);
 			if (tableName === _mastra_core_storage.TABLE_SPANS) await this.migrateSpansTable();
 		} catch (error) {
@@ -6048,20 +6050,678 @@ var HarnessLibSQL = class HarnessLibSQL extends _mastra_core_storage.HarnessStor
 	}
 };
 //#endregion
+//#region ../../packages/_internal-core/dist/knowledge-compat/index.js
+const KNOWLEDGE_V2_CORE_FEATURE = "knowledge-v2";
+/** Hard cap on scope nodes returned by one `listScopeNodes` read. */
+const MAX_KNOWLEDGE_SCOPE_NODES = 1e3;
+function knowledgeScopeNodeFilterKey(input) {
+	return JSON.stringify([
+		input.withinAddress ?? null,
+		input.addresses ? [...input.addresses].sort() : null,
+		input.ids ? [...input.ids].sort() : null
+	]);
+}
+function createKnowledgeScopeNodeCursor(scope, input) {
+	return encodeURIComponent(JSON.stringify({
+		version: 1,
+		type: "scope",
+		name: scope.name,
+		id: scope.id,
+		filter: knowledgeScopeNodeFilterKey(input)
+	}));
+}
+/** Validates the page size and cursor of a `listScopeNodes` query; throws on a cursor from a different query. */
+function parseListKnowledgeScopeNodesInput(input = {}) {
+	const requested = Number.isFinite(input.limit) ? Math.trunc(input.limit) : MAX_KNOWLEDGE_SCOPE_NODES;
+	const limit = Math.min(Math.max(requested, 1), MAX_KNOWLEDGE_SCOPE_NODES);
+	if (!input.cursor) return {
+		limit,
+		after: null
+	};
+	let value;
+	try {
+		value = JSON.parse(decodeURIComponent(input.cursor));
+	} catch {
+		throw new Error("Invalid Knowledge scope node cursor.");
+	}
+	const parsed = value && typeof value === "object" ? value : {};
+	if (parsed.version !== 1 || parsed.type !== "scope" || typeof parsed.name !== "string" || typeof parsed.id !== "string" || parsed.filter !== knowledgeScopeNodeFilterKey(input)) throw new Error("Knowledge scope node cursor does not match this query.");
+	return {
+		limit,
+		after: {
+			name: parsed.name,
+			id: parsed.id
+		}
+	};
+}
+/** Builds a page from up to `limit + 1` name/id-ordered scope nodes. */
+function pageKnowledgeScopeNodes(rows, limit, input) {
+	const scopes = rows.slice(0, limit);
+	const last = scopes.at(-1);
+	return {
+		scopes,
+		nextCursor: rows.length > limit && last ? createKnowledgeScopeNodeCursor(last, input) : null
+	};
+}
+/** Clamps a requested member limit to 1–{@link MAX_KNOWLEDGE_SCOPE_MEMBERS_LIMIT}. */
+function knowledgeScopeMembersLimit(limit) {
+	if (limit === void 0 || !Number.isFinite(limit)) return 500;
+	return Math.min(Math.max(Math.trunc(limit), 1), 500);
+}
+/** Validates the page size and cursor of a `listScopeMembers` query; throws on a cursor from another scope. */
+function parseListKnowledgeScopeMembersInput(input) {
+	const limit = knowledgeScopeMembersLimit(input.limit);
+	if (!input.cursor) return {
+		limit,
+		after: null
+	};
+	let value;
+	try {
+		value = JSON.parse(decodeURIComponent(input.cursor));
+	} catch {
+		throw new Error("Invalid Knowledge scope member cursor.");
+	}
+	const parsed = value && typeof value === "object" ? value : {};
+	const updatedAt = typeof parsed.updatedAt === "string" ? new Date(parsed.updatedAt) : /* @__PURE__ */ new Date(NaN);
+	if (parsed.version !== 1 || parsed.type !== "scope-member" || parsed.scopeNodeId !== input.scopeNodeId || typeof parsed.name !== "string" || typeof parsed.id !== "string" || Number.isNaN(updatedAt.getTime())) throw new Error("Knowledge scope member cursor does not match this query.");
+	return {
+		limit,
+		after: {
+			updatedAt,
+			name: parsed.name,
+			id: parsed.id
+		}
+	};
+}
+/** Builds a page from up to `limit + 1` members in `listScopeMembers` order. */
+function pageKnowledgeScopeMembers(rows, limit, input) {
+	const members = rows.slice(0, limit);
+	const last = members.at(-1);
+	const hasMore = rows.length > limit;
+	return {
+		members,
+		hasMore,
+		nextCursor: hasMore && last ? encodeURIComponent(JSON.stringify({
+			version: 1,
+			type: "scope-member",
+			scopeNodeId: input.scopeNodeId,
+			updatedAt: last.updatedAt.toISOString(),
+			name: last.name,
+			id: last.id
+		})) : null
+	};
+}
+const TABLE_KNOWLEDGE_NODES$1 = "mastra_knowledge_nodes";
+const TABLE_KNOWLEDGE_RECORDS$1 = "mastra_knowledge_records";
+const TABLE_KNOWLEDGE_MENTIONS$1 = "mastra_knowledge_mentions";
+const TABLE_KNOWLEDGE_ACTIVITY$1 = "mastra_knowledge_activity";
+const TABLE_KNOWLEDGE_SEMANTIC_OUTBOX$1 = "mastra_knowledge_semantic_outbox";
+const TABLE_KNOWLEDGE_NODE_SCOPES = "mastra_knowledge_node_scopes";
+const TABLE_KNOWLEDGE_RECORD_SCOPES = "mastra_knowledge_record_scopes";
+const TABLE_KNOWLEDGE_SCOPE_GRANTS = "mastra_knowledge_scope_grants";
+const TABLE_KNOWLEDGE_ACCESS_STATE = "mastra_knowledge_access_state";
+const TABLE_KNOWLEDGE_SCOPE_ADDRESSES = "mastra_knowledge_scope_addresses";
+const TABLE_KNOWLEDGE_NODE_ADDRESSES = "mastra_knowledge_node_addresses";
+const TABLE_KNOWLEDGE_IMPORT_STATE = "mastra_knowledge_import_state";
+const TABLE_KNOWLEDGE_IMPORT_RUNS = "mastra_knowledge_import_runs";
+const TABLE_KNOWLEDGE_PROPOSALS = "mastra_knowledge_proposals";
+const KNOWLEDGE_TABLE_NAMES = [
+	TABLE_KNOWLEDGE_NODES$1,
+	TABLE_KNOWLEDGE_RECORDS$1,
+	TABLE_KNOWLEDGE_MENTIONS$1,
+	TABLE_KNOWLEDGE_ACTIVITY$1,
+	TABLE_KNOWLEDGE_SEMANTIC_OUTBOX$1,
+	TABLE_KNOWLEDGE_NODE_SCOPES,
+	TABLE_KNOWLEDGE_RECORD_SCOPES,
+	TABLE_KNOWLEDGE_SCOPE_GRANTS,
+	TABLE_KNOWLEDGE_ACCESS_STATE,
+	TABLE_KNOWLEDGE_SCOPE_ADDRESSES,
+	TABLE_KNOWLEDGE_NODE_ADDRESSES,
+	TABLE_KNOWLEDGE_IMPORT_STATE,
+	TABLE_KNOWLEDGE_IMPORT_RUNS,
+	TABLE_KNOWLEDGE_PROPOSALS
+];
+/** Knowledge v1 tables with no v2 equivalent; an explicit schema reset drops them. */
+const RETIRED_KNOWLEDGE_TABLE_NAMES = ["mastra_knowledge_cursors"];
+/** Tables and indexes published v1 adapters created for every app, whether or not it used Knowledge. */
+const PUBLISHED_KNOWLEDGE_V1_TABLE_NAMES = /* @__PURE__ */ new Set([
+	TABLE_KNOWLEDGE_NODES$1,
+	TABLE_KNOWLEDGE_RECORDS$1,
+	TABLE_KNOWLEDGE_MENTIONS$1,
+	TABLE_KNOWLEDGE_ACTIVITY$1,
+	TABLE_KNOWLEDGE_SEMANTIC_OUTBOX$1,
+	...RETIRED_KNOWLEDGE_TABLE_NAMES
+]);
+const PUBLISHED_KNOWLEDGE_V1_INDEX_NAMES = /* @__PURE__ */ new Set([
+	"idx_knowledge_nodes_identity",
+	"idx_knowledge_nodes_scope",
+	"idx_knowledge_records_node_latest",
+	"idx_knowledge_records_thread_latest",
+	"idx_knowledge_mentions_record",
+	"idx_knowledge_activity_latest",
+	"idx_knowledge_outbox_idempotency",
+	"idx_knowledge_outbox_claim"
+]);
+const KNOWLEDGE_V2_NODES_SCHEMA = {
+	id: {
+		type: "text",
+		nullable: false,
+		primaryKey: true
+	},
+	name: {
+		type: "text",
+		nullable: false
+	},
+	kind: {
+		type: "text",
+		nullable: true
+	},
+	isScope: {
+		type: "boolean",
+		nullable: false
+	},
+	metadata: {
+		type: "jsonb",
+		nullable: true
+	},
+	version: {
+		type: "integer",
+		nullable: false
+	},
+	createdAt: {
+		type: "timestamp",
+		nullable: false
+	},
+	updatedAt: {
+		type: "timestamp",
+		nullable: false
+	},
+	deletedAt: {
+		type: "timestamp",
+		nullable: true
+	},
+	deletedBy: {
+		type: "text",
+		nullable: true
+	},
+	type: {
+		type: "text",
+		nullable: true
+	},
+	canonicalName: {
+		type: "text",
+		nullable: true
+	},
+	content: {
+		type: "text",
+		nullable: true
+	},
+	description: {
+		type: "text",
+		nullable: true
+	},
+	scope: {
+		type: "jsonb",
+		nullable: true
+	},
+	scopeKey: {
+		type: "text",
+		nullable: true
+	},
+	mergedInto: {
+		type: "text",
+		nullable: true
+	}
+};
+const KNOWLEDGE_V2_RECORDS_SCHEMA = {
+	id: {
+		type: "text",
+		nullable: false,
+		primaryKey: true
+	},
+	node: {
+		type: "text",
+		nullable: false,
+		references: {
+			table: TABLE_KNOWLEDGE_NODES$1,
+			column: "id"
+		}
+	},
+	text: {
+		type: "text",
+		nullable: false
+	},
+	metadata: {
+		type: "jsonb",
+		nullable: true
+	},
+	version: {
+		type: "integer",
+		nullable: false
+	},
+	capturedAt: {
+		type: "timestamp",
+		nullable: false
+	},
+	updatedAt: {
+		type: "timestamp",
+		nullable: false
+	},
+	deletedAt: {
+		type: "timestamp",
+		nullable: true
+	},
+	deletedBy: {
+		type: "text",
+		nullable: true
+	},
+	scope: {
+		type: "jsonb",
+		nullable: true
+	},
+	scopeKey: {
+		type: "text",
+		nullable: true
+	},
+	sourceThreadId: {
+		type: "text",
+		nullable: true
+	},
+	when: {
+		type: "timestamp",
+		nullable: true
+	}
+};
+const KNOWLEDGE_V2_MENTIONS_SCHEMA = {
+	recordId: {
+		type: "text",
+		nullable: false,
+		references: {
+			table: TABLE_KNOWLEDGE_RECORDS$1,
+			column: "id"
+		}
+	},
+	targetNodeId: {
+		type: "text",
+		nullable: true,
+		references: {
+			table: TABLE_KNOWLEDGE_NODES$1,
+			column: "id"
+		}
+	},
+	sourceType: {
+		type: "text",
+		nullable: true
+	},
+	sourceId: {
+		type: "text",
+		nullable: true
+	}
+};
+const KNOWLEDGE_NODE_SCOPES_SCHEMA = {
+	nodeId: {
+		type: "text",
+		nullable: false,
+		references: {
+			table: TABLE_KNOWLEDGE_NODES$1,
+			column: "id"
+		}
+	},
+	scopeNodeId: {
+		type: "text",
+		nullable: false,
+		references: {
+			table: TABLE_KNOWLEDGE_NODES$1,
+			column: "id"
+		}
+	},
+	addedAt: {
+		type: "timestamp",
+		nullable: false
+	}
+};
+const KNOWLEDGE_RECORD_SCOPES_SCHEMA = {
+	recordId: {
+		type: "text",
+		nullable: false,
+		references: {
+			table: TABLE_KNOWLEDGE_RECORDS$1,
+			column: "id"
+		}
+	},
+	scopeNodeId: {
+		type: "text",
+		nullable: false,
+		references: {
+			table: TABLE_KNOWLEDGE_NODES$1,
+			column: "id"
+		}
+	},
+	addedAt: {
+		type: "timestamp",
+		nullable: false
+	}
+};
+const KNOWLEDGE_SCOPE_GRANTS_SCHEMA = {
+	scopeNodeId: {
+		type: "text",
+		nullable: false,
+		references: {
+			table: TABLE_KNOWLEDGE_NODES$1,
+			column: "id"
+		}
+	},
+	scopeRefId: {
+		type: "text",
+		nullable: false,
+		references: {
+			table: TABLE_KNOWLEDGE_NODES$1,
+			column: "id"
+		}
+	},
+	role: {
+		type: "text",
+		nullable: false
+	},
+	canSuggest: {
+		type: "boolean",
+		nullable: true
+	}
+};
+const KNOWLEDGE_ACCESS_STATE_SCHEMA = {
+	id: {
+		type: "text",
+		nullable: false,
+		primaryKey: true
+	},
+	epoch: {
+		type: "integer",
+		nullable: false
+	},
+	schemaVersion: {
+		type: "integer",
+		nullable: false
+	}
+};
+const KNOWLEDGE_SCOPE_ADDRESSES_SCHEMA = {
+	address: {
+		type: "text",
+		nullable: false,
+		primaryKey: true
+	},
+	scopeNodeId: {
+		type: "text",
+		nullable: false,
+		references: {
+			table: TABLE_KNOWLEDGE_NODES$1,
+			column: "id"
+		}
+	}
+};
+const KNOWLEDGE_NODE_ADDRESSES_SCHEMA = {
+	source: {
+		type: "text",
+		nullable: false
+	},
+	address: {
+		type: "text",
+		nullable: false
+	},
+	nodeId: {
+		type: "text",
+		nullable: false,
+		references: {
+			table: TABLE_KNOWLEDGE_NODES$1,
+			column: "id"
+		}
+	}
+};
+const KNOWLEDGE_IMPORT_STATE_SCHEMA = {
+	importerId: {
+		type: "text",
+		nullable: false
+	},
+	binding: {
+		type: "text",
+		nullable: false
+	},
+	key: {
+		type: "text",
+		nullable: false
+	},
+	value: {
+		type: "text",
+		nullable: false
+	}
+};
+const KNOWLEDGE_IMPORT_RUNS_SCHEMA = {
+	id: {
+		type: "text",
+		nullable: false,
+		primaryKey: true
+	},
+	importerId: {
+		type: "text",
+		nullable: false
+	},
+	binding: {
+		type: "text",
+		nullable: false
+	},
+	importKind: {
+		type: "text",
+		nullable: false
+	},
+	triggerKind: {
+		type: "text",
+		nullable: false
+	},
+	status: {
+		type: "text",
+		nullable: false
+	},
+	error: {
+		type: "text",
+		nullable: true
+	},
+	transcriptThreadId: {
+		type: "text",
+		nullable: true
+	},
+	traceId: {
+		type: "text",
+		nullable: true
+	},
+	queuedAt: {
+		type: "timestamp",
+		nullable: false
+	},
+	startedAt: {
+		type: "timestamp",
+		nullable: true
+	},
+	completedAt: {
+		type: "timestamp",
+		nullable: true
+	}
+};
+const KNOWLEDGE_V2_ACTIVITY_SCHEMA = {
+	id: {
+		type: "text",
+		nullable: false,
+		primaryKey: true
+	},
+	action: {
+		type: "text",
+		nullable: false
+	},
+	targetType: {
+		type: "text",
+		nullable: true
+	},
+	targetId: {
+		type: "text",
+		nullable: true
+	},
+	contextScopeId: {
+		type: "text",
+		nullable: true,
+		references: {
+			table: TABLE_KNOWLEDGE_NODES$1,
+			column: "id"
+		}
+	},
+	importRunId: {
+		type: "text",
+		nullable: true,
+		references: {
+			table: TABLE_KNOWLEDGE_IMPORT_RUNS,
+			column: "id"
+		}
+	},
+	details: {
+		type: "jsonb",
+		nullable: true
+	},
+	createdAt: {
+		type: "timestamp",
+		nullable: false
+	},
+	recordType: {
+		type: "text",
+		nullable: true
+	},
+	recordId: {
+		type: "text",
+		nullable: true
+	},
+	scope: {
+		type: "jsonb",
+		nullable: true
+	},
+	scopeKey: {
+		type: "text",
+		nullable: true
+	},
+	sourceThreadId: {
+		type: "text",
+		nullable: true
+	}
+};
+const KNOWLEDGE_PROPOSALS_SCHEMA = {
+	id: {
+		type: "text",
+		nullable: false,
+		primaryKey: true
+	},
+	targetType: {
+		type: "text",
+		nullable: false
+	},
+	targetId: {
+		type: "text",
+		nullable: false
+	},
+	action: {
+		type: "text",
+		nullable: false
+	},
+	changes: {
+		type: "jsonb",
+		nullable: false
+	},
+	reason: {
+		type: "text",
+		nullable: true
+	},
+	proposerContextScopeId: {
+		type: "text",
+		nullable: false
+	},
+	expectedVersion: {
+		type: "integer",
+		nullable: false
+	},
+	status: {
+		type: "text",
+		nullable: false
+	},
+	reviewerContextScopeId: {
+		type: "text",
+		nullable: true
+	},
+	reviewedAt: {
+		type: "timestamp",
+		nullable: true
+	},
+	createdAt: {
+		type: "timestamp",
+		nullable: false
+	}
+};
+function assertKnowledgeV2CoreSupport(features) {
+	if (!features.has("knowledge-v2")) throw new Error(`Knowledge v2 requires a @mastra/core release with the "${KNOWLEDGE_V2_CORE_FEATURE}" feature. Upgrade @mastra/core to use Knowledge; other storage domains keep working on this version.`);
+}
+function resolveKnowledgeV2Core(storageModule) {
+	if (typeof storageModule !== "object" || storageModule === null) throw new Error("@mastra/core advertises Knowledge v2 without the required storage API");
+	const { assertKnowledgeDescriptionWithinBound: assertDescription, assertKnowledgeRecordTextWithinBound: assertRecordText, assertKnowledgeSchemaCompatible: assertCompatible, inspectKnowledgeSchema: inspectSchema } = storageModule;
+	if (typeof assertDescription !== "function" || typeof assertRecordText !== "function" || typeof assertCompatible !== "function" || typeof inspectSchema !== "function") throw new Error("@mastra/core advertises Knowledge v2 without the required storage API");
+	return {
+		assertKnowledgeDescriptionWithinBound: (description) => assertDescription(description),
+		assertKnowledgeRecordTextWithinBound: (text) => assertRecordText(text),
+		assertKnowledgeSchemaCompatible: (inspection) => assertCompatible(inspection),
+		inspectKnowledgeSchema: (snapshot) => inspectSchema(snapshot)
+	};
+}
+function createKnowledgeV2CoreLoader(features, loadStorageModule) {
+	let knowledgeV2Core;
+	return async () => {
+		assertKnowledgeV2CoreSupport(features);
+		knowledgeV2Core ??= loadStorageModule().then(resolveKnowledgeV2Core).catch((error) => {
+			knowledgeV2Core = void 0;
+			throw error;
+		});
+		return knowledgeV2Core;
+	};
+}
+//#endregion
 //#region src/storage/domains/knowledge/index.ts
-let assertDescriptionWithinBound;
+const loadKnowledgeV2Core = createKnowledgeV2CoreLoader(_mastra_core_features.coreFeatures, () => import("@mastra/core/storage"));
 async function assertKnowledgeDescriptionWithinBoundCompat(description) {
-	let assertWithinBound = assertDescriptionWithinBound;
-	if (!assertWithinBound) {
-		const resolvedAssert = (await import("@mastra/core/storage")).assertKnowledgeDescriptionWithinBound ?? ((value) => {
-			if (value !== void 0 && value.length > 400) throw new Error("Knowledge node description exceeds the 400 UTF-16 code unit limit");
-		});
-		assertDescriptionWithinBound = resolvedAssert;
-		assertWithinBound = resolvedAssert;
-	}
-	assertWithinBound(description);
+	const { assertKnowledgeDescriptionWithinBound } = await loadKnowledgeV2Core();
+	assertKnowledgeDescriptionWithinBound(description);
+}
+async function assertKnowledgeRecordTextWithinBoundCompat(text) {
+	const { assertKnowledgeRecordTextWithinBound } = await loadKnowledgeV2Core();
+	assertKnowledgeRecordTextWithinBound(text);
+}
+const reconcileChains = /* @__PURE__ */ new Map();
+const unidentifiedClientReconcileKey = {};
+function withReconcileLock(key, operation) {
+	const lockKey = typeof key === "string" ? key : unidentifiedClientReconcileKey;
+	const result = (reconcileChains.get(lockKey) ?? Promise.resolve()).then(operation, operation);
+	const tail = result.then(() => void 0, () => void 0);
+	reconcileChains.set(lockKey, tail);
+	tail.finally(() => {
+		if (reconcileChains.get(lockKey) === tail) reconcileChains.delete(lockKey);
+	});
+	return result;
 }
-const visibleSql = `(scopeKey = ? OR substr(?, 1, length(scopeKey) + 1) = 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 = (0, _mastra_core_storage.canonicalizeKnowledgeScope)(scope);
+	const keys = /* @__PURE__ */ new Set();
+	for (let mask = 1; mask < 1 << canonical.length; mask++) try {
+		keys.add((0, _mastra_core_storage.knowledgeScopeKey)(canonical.filter((_, index) => mask & 1 << index)));
+	} catch {}
+	return [...keys];
+}
+const visibleSql = (keys, scopeKeyColumn = "scopeKey") => `${scopeKeyColumn} IN (${keys.map(() => "?").join(",")})`;
 function parseJson$3(value) {
 	if (typeof value === "string") return JSON.parse(value);
 	if (value instanceof Uint8Array) return JSON.parse(new TextDecoder().decode(value));
@@ -6091,6 +6751,7 @@ function parseNode(row) {
 		kind: row.kind == null ? "" : String(row.kind),
 		content: row.content == null ? void 0 : String(row.content),
 		description: row.description == null ? void 0 : String(row.description),
+		isScope: row.isScope === true || row.isScope === 1 ? true : void 0,
 		scope: parseJson$3(row.scopeJson ?? row.scope),
 		version: Number(row.version),
 		mergedInto: row.mergedInto == null ? void 0 : String(row.mergedInto),
@@ -6107,7 +6768,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.metadataJson ?? row.metadata) == null ? void 0 : parseJson$3(row.metadataJson ?? row.metadata),
 		deletedAt: optionalDate(row.deletedAt),
 		deletedBy: row.deletedBy == null ? void 0 : String(row.deletedBy)
@@ -6130,100 +6790,458 @@ function parseOutbox(row) {
 		completedAt: optionalDate(row.completedAt)
 	};
 }
+const KNOWLEDGE_CURATION_CURSOR_REMOVED_MESSAGE = "Knowledge curation cursors were removed: observation-time curate is the only Knowledge writer and needs no cursor.";
+const knowledgeV2TableSchemas = /* @__PURE__ */ new Map([
+	[_mastra_core_storage.TABLE_KNOWLEDGE_NODES, KNOWLEDGE_V2_NODES_SCHEMA],
+	[_mastra_core_storage.TABLE_KNOWLEDGE_RECORDS, KNOWLEDGE_V2_RECORDS_SCHEMA],
+	[_mastra_core_storage.TABLE_KNOWLEDGE_MENTIONS, KNOWLEDGE_V2_MENTIONS_SCHEMA],
+	[_mastra_core_storage.TABLE_KNOWLEDGE_ACTIVITY, KNOWLEDGE_V2_ACTIVITY_SCHEMA],
+	[_mastra_core_storage.TABLE_KNOWLEDGE_SEMANTIC_OUTBOX, _mastra_core_storage.KNOWLEDGE_SEMANTIC_OUTBOX_SCHEMA],
+	[TABLE_KNOWLEDGE_NODE_SCOPES, KNOWLEDGE_NODE_SCOPES_SCHEMA],
+	[TABLE_KNOWLEDGE_RECORD_SCOPES, KNOWLEDGE_RECORD_SCOPES_SCHEMA],
+	[TABLE_KNOWLEDGE_SCOPE_GRANTS, KNOWLEDGE_SCOPE_GRANTS_SCHEMA],
+	[TABLE_KNOWLEDGE_ACCESS_STATE, KNOWLEDGE_ACCESS_STATE_SCHEMA],
+	[TABLE_KNOWLEDGE_SCOPE_ADDRESSES, KNOWLEDGE_SCOPE_ADDRESSES_SCHEMA],
+	[TABLE_KNOWLEDGE_NODE_ADDRESSES, KNOWLEDGE_NODE_ADDRESSES_SCHEMA],
+	[TABLE_KNOWLEDGE_IMPORT_STATE, KNOWLEDGE_IMPORT_STATE_SCHEMA],
+	[TABLE_KNOWLEDGE_IMPORT_RUNS, KNOWLEDGE_IMPORT_RUNS_SCHEMA],
+	[TABLE_KNOWLEDGE_PROPOSALS, KNOWLEDGE_PROPOSALS_SCHEMA]
+]);
+function canonicalizeLibSQLUrl(url) {
+	if (url.includes(":memory:")) return /[?&]cache=shared(?:&|$)/.test(url) ? "file::memory:?cache=shared" : void 0;
+	if (url.startsWith("file:")) {
+		const [path$1] = url.slice(5).split("?");
+		if (url.startsWith("file://")) {
+			const parsed = new URL(url);
+			const host = parsed.hostname.toLocaleLowerCase();
+			const filePath = host && host !== "localhost" ? `//${host}${parsed.pathname}` : parsed.pathname;
+			return `file:${(0, path.resolve)(decodeURIComponent(filePath))}`;
+		}
+		return `file:${(0, path.resolve)(decodeURIComponent(path$1))}`;
+	}
+	try {
+		const parsed = new URL(url);
+		const port = parsed.port || (parsed.protocol === "libsql:" || parsed.protocol === "https:" ? "443" : "80");
+		return `${parsed.protocol}//${parsed.hostname.toLocaleLowerCase()}:${port}${parsed.pathname}`;
+	} catch {
+		return url;
+	}
+}
+const unidentifiedClientIsolationKey = {};
+function getLibSQLKnowledgeIsolationKey(config, client) {
+	if (config.storageIsolationKey !== void 0) return config.storageIsolationKey;
+	if (!config.url) return unidentifiedClientIsolationKey;
+	const urlKey = canonicalizeLibSQLUrl(config.url);
+	return urlKey ? `libsql:${urlKey}` : client ?? config.client ?? config;
+}
 var KnowledgeLibSQL = class extends _mastra_core_storage.KnowledgeStorage {
 	#client;
 	#db;
 	constructor(config) {
-		super();
-		this.#client = resolveClient(config);
+		const client = resolveClient(config);
+		const storageIsolationKey = config.storageIsolationKey ?? getLibSQLKnowledgeIsolationKey(config, client);
+		super({ storageIsolationKey });
+		this.#client = client;
 		this.#db = new LibSQLDB({
 			client: this.#client,
 			maxRetries: config.maxRetries,
 			initialBackoffMs: config.initialBackoffMs
 		});
 	}
+	getCapabilities() {
+		return {
+			contractVersion: 2,
+			schemaVersion: 2,
+			supportsV2: true,
+			supportsSchemaInspection: true,
+			supportsExplicitReset: true
+		};
+	}
+	async inspectSchema() {
+		return this.#inspectSchema(this.#client);
+	}
+	async #inspectSchema(executor) {
+		const { inspectKnowledgeSchema } = await loadKnowledgeV2Core();
+		try {
+			const placeholders = KNOWLEDGE_TABLE_NAMES.map(() => "?").join(",");
+			const tableNames = (await executor.execute({
+				sql: `SELECT name FROM sqlite_master WHERE type = 'table' AND name IN (${placeholders})`,
+				args: [...KNOWLEDGE_TABLE_NAMES]
+			})).rows.map((row) => String(row.name));
+			if (tableNames.length === 0) return inspectKnowledgeSchema({
+				available: true,
+				tableNames
+			});
+			const missingTables = KNOWLEDGE_TABLE_NAMES.filter((table) => !tableNames.includes(table));
+			if (missingTables.length > 0) return inspectKnowledgeSchema({
+				available: true,
+				tableNames,
+				reason: `Missing Knowledge v2 tables: ${missingTables.join(", ")}`
+			});
+			for (const [table, schema] of knowledgeV2TableSchemas) {
+				const columns = await executor.execute(`PRAGMA table_info("${table}")`);
+				const actual = new Set(columns.rows.map((row) => String(row.name)));
+				const missing = Object.keys(schema).filter((column) => !actual.has(column));
+				if (missing.length > 0) return inspectKnowledgeSchema({
+					available: true,
+					tableNames,
+					reason: `Knowledge table ${table} is missing v2 columns: ${missing.join(", ")}`
+				});
+			}
+			const accessState = await executor.execute(`SELECT schemaVersion FROM "${TABLE_KNOWLEDGE_ACCESS_STATE}" WHERE id='global'`);
+			if (Number(accessState.rows[0]?.schemaVersion) !== 2) return inspectKnowledgeSchema({
+				available: true,
+				tableNames,
+				reason: "Knowledge schema version marker is missing or incompatible"
+			});
+			return inspectKnowledgeSchema({
+				available: true,
+				tableNames,
+				schemaVersion: 2
+			});
+		} catch (error) {
+			return inspectKnowledgeSchema({
+				available: false,
+				tableNames: [],
+				reason: error instanceof Error ? error.message : String(error)
+			});
+		}
+	}
 	async init() {
-		await this.#db.createTable({
-			tableName: _mastra_core_storage.TABLE_KNOWLEDGE_NODES,
-			schema: _mastra_core_storage.KNOWLEDGE_NODES_SCHEMA
+		await this.#transaction((tx) => this.#initializeSchema(tx));
+	}
+	async #initializeSchema(tx) {
+		const { assertKnowledgeSchemaCompatible } = await loadKnowledgeV2Core();
+		let inspection = await this.#inspectSchema(tx);
+		if (inspection.status === "incompatible-reset-required" && await this.#isPublishedV1Layout(tx)) {
+			for (const table of [...RETIRED_KNOWLEDGE_TABLE_NAMES, ...[...KNOWLEDGE_TABLE_NAMES].reverse()]) await tx.execute(`DROP TABLE IF EXISTS "${table}"`);
+			inspection = await this.#inspectSchema(tx);
+		}
+		assertKnowledgeSchemaCompatible(inspection);
+		const createTable = (input) => this.#db.createTable({
+			...input,
+			executor: tx
 		});
-		await this.#db.alterTable({
+		await createTable({
 			tableName: _mastra_core_storage.TABLE_KNOWLEDGE_NODES,
-			schema: _mastra_core_storage.KNOWLEDGE_NODES_SCHEMA,
-			ifNotExists: ["description"]
+			schema: KNOWLEDGE_V2_NODES_SCHEMA
 		});
-		await this.#db.createTable({
+		await createTable({
 			tableName: _mastra_core_storage.TABLE_KNOWLEDGE_RECORDS,
-			schema: _mastra_core_storage.KNOWLEDGE_RECORDS_SCHEMA
+			schema: KNOWLEDGE_V2_RECORDS_SCHEMA
 		});
-		await this.#db.createTable({
+		await createTable({
 			tableName: _mastra_core_storage.TABLE_KNOWLEDGE_MENTIONS,
-			schema: _mastra_core_storage.KNOWLEDGE_MENTIONS_SCHEMA,
+			schema: KNOWLEDGE_V2_MENTIONS_SCHEMA,
+			compositePrimaryKey: ["recordId", "sourceId"]
+		});
+		await createTable({
+			tableName: TABLE_KNOWLEDGE_NODE_SCOPES,
+			schema: KNOWLEDGE_NODE_SCOPES_SCHEMA,
+			compositePrimaryKey: ["nodeId", "scopeNodeId"]
+		});
+		await createTable({
+			tableName: TABLE_KNOWLEDGE_RECORD_SCOPES,
+			schema: KNOWLEDGE_RECORD_SCOPES_SCHEMA,
+			compositePrimaryKey: ["recordId", "scopeNodeId"]
+		});
+		await createTable({
+			tableName: TABLE_KNOWLEDGE_SCOPE_GRANTS,
+			schema: KNOWLEDGE_SCOPE_GRANTS_SCHEMA,
+			compositePrimaryKey: ["scopeNodeId", "scopeRefId"]
+		});
+		await createTable({
+			tableName: TABLE_KNOWLEDGE_ACCESS_STATE,
+			schema: KNOWLEDGE_ACCESS_STATE_SCHEMA
+		});
+		await createTable({
+			tableName: TABLE_KNOWLEDGE_SCOPE_ADDRESSES,
+			schema: KNOWLEDGE_SCOPE_ADDRESSES_SCHEMA
+		});
+		await createTable({
+			tableName: TABLE_KNOWLEDGE_NODE_ADDRESSES,
+			schema: KNOWLEDGE_NODE_ADDRESSES_SCHEMA,
+			compositePrimaryKey: ["source", "address"]
+		});
+		await createTable({
+			tableName: TABLE_KNOWLEDGE_IMPORT_STATE,
+			schema: KNOWLEDGE_IMPORT_STATE_SCHEMA,
 			compositePrimaryKey: [
-				"sourceType",
-				"sourceId",
-				"recordId"
+				"importerId",
+				"binding",
+				"key"
 			]
 		});
-		await this.#db.createTable({
-			tableName: _mastra_core_storage.TABLE_KNOWLEDGE_CURSORS,
-			schema: _mastra_core_storage.KNOWLEDGE_CURSORS_SCHEMA,
-			compositePrimaryKey: ["sourceThreadId", "agent"]
+		await createTable({
+			tableName: TABLE_KNOWLEDGE_IMPORT_RUNS,
+			schema: KNOWLEDGE_IMPORT_RUNS_SCHEMA
 		});
-		await this.#db.createTable({
+		await createTable({
+			tableName: TABLE_KNOWLEDGE_PROPOSALS,
+			schema: KNOWLEDGE_PROPOSALS_SCHEMA
+		});
+		await createTable({
 			tableName: _mastra_core_storage.TABLE_KNOWLEDGE_ACTIVITY,
-			schema: _mastra_core_storage.KNOWLEDGE_ACTIVITY_SCHEMA
+			schema: KNOWLEDGE_V2_ACTIVITY_SCHEMA
 		});
-		await this.#db.createTable({
+		await createTable({
 			tableName: _mastra_core_storage.TABLE_KNOWLEDGE_SEMANTIC_OUTBOX,
 			schema: _mastra_core_storage.KNOWLEDGE_SEMANTIC_OUTBOX_SCHEMA
 		});
-		await this.#client.batch([
-			{
-				sql: `CREATE UNIQUE INDEX IF NOT EXISTS idx_knowledge_nodes_identity ON "${_mastra_core_storage.TABLE_KNOWLEDGE_NODES}" (type, scopeKey, canonicalName)`,
-				args: []
-			},
-			{
-				sql: `CREATE INDEX IF NOT EXISTS idx_knowledge_nodes_scope ON "${_mastra_core_storage.TABLE_KNOWLEDGE_NODES}" (scopeKey, type)`,
-				args: []
-			},
-			{
-				sql: `CREATE INDEX IF NOT EXISTS idx_knowledge_records_node_latest ON "${_mastra_core_storage.TABLE_KNOWLEDGE_RECORDS}" (node, id DESC)`,
-				args: []
-			},
-			{
-				sql: `CREATE INDEX IF NOT EXISTS idx_knowledge_records_thread_latest ON "${_mastra_core_storage.TABLE_KNOWLEDGE_RECORDS}" (sourceThreadId, id DESC)`,
-				args: []
-			},
-			{
-				sql: `CREATE INDEX IF NOT EXISTS idx_knowledge_mentions_record ON "${_mastra_core_storage.TABLE_KNOWLEDGE_MENTIONS}" (recordId, sourceType, sourceId)`,
-				args: []
-			},
-			{
-				sql: `CREATE INDEX IF NOT EXISTS idx_knowledge_activity_latest ON "${_mastra_core_storage.TABLE_KNOWLEDGE_ACTIVITY}" (id DESC)`,
-				args: []
-			},
-			{
-				sql: `CREATE UNIQUE INDEX IF NOT EXISTS idx_knowledge_outbox_idempotency ON "${_mastra_core_storage.TABLE_KNOWLEDGE_SEMANTIC_OUTBOX}" (idempotencyKey)`,
-				args: []
-			},
-			{
-				sql: `CREATE INDEX IF NOT EXISTS idx_knowledge_outbox_claim ON "${_mastra_core_storage.TABLE_KNOWLEDGE_SEMANTIC_OUTBOX}" (status, availableAt, createdAt)`,
-				args: []
-			}
-		], "write");
+		for (const statement of [
+			`CREATE UNIQUE INDEX IF NOT EXISTS idx_knowledge_nodes_identity ON "${_mastra_core_storage.TABLE_KNOWLEDGE_NODES}" (type, scopeKey, canonicalName)`,
+			`CREATE INDEX IF NOT EXISTS idx_knowledge_nodes_scope ON "${_mastra_core_storage.TABLE_KNOWLEDGE_NODES}" (scopeKey, type)`,
+			`CREATE INDEX IF NOT EXISTS idx_knowledge_nodes_name ON "${_mastra_core_storage.TABLE_KNOWLEDGE_NODES}" (type, canonicalName)`,
+			`CREATE INDEX IF NOT EXISTS idx_knowledge_records_node_latest ON "${_mastra_core_storage.TABLE_KNOWLEDGE_RECORDS}" (node, id DESC)`,
+			`CREATE INDEX IF NOT EXISTS idx_knowledge_records_thread_latest ON "${_mastra_core_storage.TABLE_KNOWLEDGE_RECORDS}" (sourceThreadId, id DESC)`,
+			`CREATE INDEX IF NOT EXISTS idx_knowledge_mentions_record ON "${_mastra_core_storage.TABLE_KNOWLEDGE_MENTIONS}" (recordId, sourceType, sourceId)`,
+			`CREATE INDEX IF NOT EXISTS idx_knowledge_activity_latest ON "${_mastra_core_storage.TABLE_KNOWLEDGE_ACTIVITY}" (id DESC)`,
+			`CREATE INDEX IF NOT EXISTS idx_knowledge_records_scope ON "${_mastra_core_storage.TABLE_KNOWLEDGE_RECORDS}" (scopeKey, id)`,
+			`CREATE INDEX IF NOT EXISTS idx_knowledge_activity_scope ON "${_mastra_core_storage.TABLE_KNOWLEDGE_ACTIVITY}" (scopeKey, id DESC)`,
+			`CREATE UNIQUE INDEX IF NOT EXISTS idx_knowledge_outbox_idempotency ON "${_mastra_core_storage.TABLE_KNOWLEDGE_SEMANTIC_OUTBOX}" (idempotencyKey)`,
+			`CREATE INDEX IF NOT EXISTS idx_knowledge_outbox_claim ON "${_mastra_core_storage.TABLE_KNOWLEDGE_SEMANTIC_OUTBOX}" (status, availableAt, createdAt)`,
+			`CREATE INDEX IF NOT EXISTS idx_knowledge_node_scopes_scope ON "${TABLE_KNOWLEDGE_NODE_SCOPES}" (scopeNodeId, nodeId)`,
+			`CREATE INDEX IF NOT EXISTS idx_knowledge_record_scopes_scope ON "${TABLE_KNOWLEDGE_RECORD_SCOPES}" (scopeNodeId, recordId)`,
+			`CREATE INDEX IF NOT EXISTS idx_knowledge_scope_grants_ref ON "${TABLE_KNOWLEDGE_SCOPE_GRANTS}" (scopeRefId, scopeNodeId)`,
+			`CREATE INDEX IF NOT EXISTS idx_knowledge_node_addresses_node ON "${TABLE_KNOWLEDGE_NODE_ADDRESSES}" (nodeId)`,
+			`CREATE INDEX IF NOT EXISTS idx_knowledge_import_runs_lookup ON "${TABLE_KNOWLEDGE_IMPORT_RUNS}" (importerId, binding, queuedAt DESC)`,
+			`CREATE INDEX IF NOT EXISTS idx_knowledge_activity_import_run ON "${_mastra_core_storage.TABLE_KNOWLEDGE_ACTIVITY}" (importRunId, id DESC)`
+		]) await tx.execute(statement);
+		await tx.execute({
+			sql: `INSERT OR IGNORE INTO "${TABLE_KNOWLEDGE_ACCESS_STATE}" (id, epoch, schemaVersion) VALUES ('global', 0, ?)`,
+			args: [2]
+		});
+	}
+	/**
+	* True when the only Knowledge objects are the tables and indexes published v1 adapters created,
+	* with or without rows. Anything else (v2 tables, unknown tables, views, triggers) needs an
+	* explicit reset.
+	*/
+	async #isPublishedV1Layout(executor) {
+		const objects = await executor.execute("SELECT type, name FROM sqlite_master WHERE name LIKE 'mastra\\_knowledge\\_%' ESCAPE '\\' OR tbl_name LIKE 'mastra\\_knowledge\\_%' ESCAPE '\\' OR sql LIKE '%mastra\\_knowledge\\_%' ESCAPE '\\'");
+		for (const row of objects.rows) {
+			const type = String(row.type);
+			const name = String(row.name);
+			if (type === "table" && PUBLISHED_KNOWLEDGE_V1_TABLE_NAMES.has(name)) continue;
+			const knownIndex = PUBLISHED_KNOWLEDGE_V1_INDEX_NAMES.has(name) || name.startsWith("sqlite_autoindex_");
+			if (type !== "index" || !knownIndex) return false;
+		}
+		return true;
 	}
 	async dangerouslyClearAll() {
 		await this.#transaction(async (tx) => {
 			for (const table of [
+				TABLE_KNOWLEDGE_RECORD_SCOPES,
+				TABLE_KNOWLEDGE_NODE_SCOPES,
+				TABLE_KNOWLEDGE_SCOPE_GRANTS,
+				TABLE_KNOWLEDGE_SCOPE_ADDRESSES,
+				TABLE_KNOWLEDGE_NODE_ADDRESSES,
 				_mastra_core_storage.TABLE_KNOWLEDGE_MENTIONS,
-				_mastra_core_storage.TABLE_KNOWLEDGE_RECORDS,
-				_mastra_core_storage.TABLE_KNOWLEDGE_NODES,
-				_mastra_core_storage.TABLE_KNOWLEDGE_CURSORS,
+				TABLE_KNOWLEDGE_PROPOSALS,
 				_mastra_core_storage.TABLE_KNOWLEDGE_ACTIVITY,
-				_mastra_core_storage.TABLE_KNOWLEDGE_SEMANTIC_OUTBOX
+				TABLE_KNOWLEDGE_IMPORT_STATE,
+				TABLE_KNOWLEDGE_IMPORT_RUNS,
+				_mastra_core_storage.TABLE_KNOWLEDGE_SEMANTIC_OUTBOX,
+				_mastra_core_storage.TABLE_KNOWLEDGE_RECORDS,
+				_mastra_core_storage.TABLE_KNOWLEDGE_NODES
 			]) await tx.execute(`DELETE FROM "${table}"`);
+			await tx.execute(`UPDATE "${TABLE_KNOWLEDGE_ACCESS_STATE}" SET epoch = 0 WHERE id = 'global'`);
+		});
+	}
+	async dangerouslyReset() {
+		await withClientWriteLock(this.#client, async () => {
+			await this.#client.batch([...RETIRED_KNOWLEDGE_TABLE_NAMES, ...[...KNOWLEDGE_TABLE_NAMES].reverse()].map((table) => ({
+				sql: `DROP TABLE IF EXISTS "${table}"`,
+				args: []
+			})), "write");
 		});
+		await this.init();
+	}
+	async reconcileStructure(plan) {
+		return withReconcileLock(this.getStorageIsolationKey(), () => this.#transaction(async (tx) => {
+			await tx.execute(`UPDATE "${TABLE_KNOWLEDGE_ACCESS_STATE}" SET epoch=epoch WHERE id='global'`);
+			const scopes = {};
+			const createdScopeIds = [];
+			const createdAddresses = /* @__PURE__ */ new Set();
+			const retrofit = plan.retrofit ?? true;
+			let structureChanged = false;
+			const deletedScopeAddresses = /* @__PURE__ */ new Set();
+			const resolveAddress = async (address) => {
+				if (scopes[address]) return scopes[address];
+				const row = (await tx.execute({
+					sql: `SELECT a.scopeNodeId,n.isScope,n.deletedAt FROM "${TABLE_KNOWLEDGE_SCOPE_ADDRESSES}" a JOIN "${_mastra_core_storage.TABLE_KNOWLEDGE_NODES}" n ON n.id=a.scopeNodeId WHERE a.address=?`,
+					args: [address]
+				})).rows[0];
+				if (!row) return void 0;
+				if (!row.isScope) throw new Error(`Knowledge address ${address} does not reference a scope`);
+				if (row.deletedAt) deletedScopeAddresses.add(address);
+				scopes[address] = String(row.scopeNodeId);
+				return scopes[address];
+			};
+			for (const scope of plan.scopes) {
+				if (await resolveAddress(scope.address)) continue;
+				const id = (0, crypto$1.randomUUID)();
+				const now = (/* @__PURE__ */ new Date()).toISOString();
+				await tx.execute({
+					sql: `INSERT INTO "${_mastra_core_storage.TABLE_KNOWLEDGE_NODES}" (id,type,name,canonicalName,kind,description,isScope,metadata,version,createdAt,updatedAt) VALUES (?,'node',?,?,?,?,TRUE,jsonb(?),1,?,?)`,
+					args: [
+						id,
+						scope.name,
+						canonicalName(scope.name),
+						scope.kind ?? null,
+						scope.description ?? null,
+						scope.metadata ? JSON.stringify(scope.metadata) : null,
+						now,
+						now
+					]
+				});
+				await tx.execute({
+					sql: `INSERT INTO "${TABLE_KNOWLEDGE_SCOPE_ADDRESSES}" (address,scopeNodeId) VALUES (?,?)`,
+					args: [scope.address, id]
+				});
+				scopes[scope.address] = id;
+				createdAddresses.add(scope.address);
+				createdScopeIds.push(id);
+				structureChanged = true;
+			}
+			for (const scope of plan.scopes) {
+				if (!createdAddresses.has(scope.address) && (!retrofit || deletedScopeAddresses.has(scope.address))) continue;
+				const scopeNodeId = scopes[scope.address];
+				for (const parentAddress of scope.parentAddresses ?? []) {
+					const parentId = await resolveAddress(parentAddress);
+					if (!parentId || deletedScopeAddresses.has(parentAddress)) {
+						const deletedParentId = scopes[parentAddress];
+						if ((deletedParentId ? await tx.execute({
+							sql: `SELECT 1 FROM "mastra_knowledge_node_scopes" WHERE nodeId=? AND scopeNodeId=?`,
+							args: [scopeNodeId, deletedParentId]
+						}) : void 0)?.rows.length) continue;
+						throw new Error(`Knowledge parent scope does not exist: ${parentAddress}`);
+					}
+					if ((await tx.execute({
+						sql: `SELECT 1 FROM "mastra_knowledge_node_scopes" WHERE nodeId=? AND scopeNodeId=?`,
+						args: [scopeNodeId, parentId]
+					})).rows.length) continue;
+					if ((await tx.execute({
+						sql: `SELECT n.id FROM "mastra_knowledge_node_scopes" ns JOIN "${_mastra_core_storage.TABLE_KNOWLEDGE_NODES}" n ON n.id=ns.nodeId WHERE ns.scopeNodeId=? AND n.isScope AND n.canonicalName=? AND n.deletedAt IS NULL AND n.id<>? LIMIT 1`,
+						args: [
+							parentId,
+							canonicalName(scope.name),
+							scopeNodeId
+						]
+					})).rows.length) throw new Error(`Knowledge scope name ${scope.name} already exists under ${parentAddress}`);
+					const inserted = await tx.execute({
+						sql: `INSERT OR IGNORE INTO "${TABLE_KNOWLEDGE_NODE_SCOPES}" (nodeId,scopeNodeId,addedAt) VALUES (?,?,?)`,
+						args: [
+							scopeNodeId,
+							parentId,
+							(/* @__PURE__ */ new Date()).toISOString()
+						]
+					});
+					structureChanged ||= inserted.rowsAffected > 0;
+				}
+				for (const grant of scope.grants ?? []) {
+					const scopeRefId = await resolveAddress(grant.scopeRefAddress);
+					if (!scopeRefId || deletedScopeAddresses.has(grant.scopeRefAddress)) {
+						const deletedScopeRefId = scopes[grant.scopeRefAddress];
+						if ((deletedScopeRefId ? await tx.execute({
+							sql: `SELECT 1 FROM "mastra_knowledge_scope_grants" WHERE scopeNodeId=? AND scopeRefId=?`,
+							args: [scopeNodeId, deletedScopeRefId]
+						}) : void 0)?.rows.length) continue;
+						throw new Error(`Knowledge grant scope does not exist: ${grant.scopeRefAddress}`);
+					}
+					const inserted = await tx.execute({
+						sql: `INSERT OR IGNORE INTO "${TABLE_KNOWLEDGE_SCOPE_GRANTS}" (scopeNodeId,scopeRefId,role,canSuggest) VALUES (?,?,?,?)`,
+						args: [
+							scopeNodeId,
+							scopeRefId,
+							grant.role,
+							grant.canSuggest ?? null
+						]
+					});
+					structureChanged ||= inserted.rowsAffected > 0;
+				}
+			}
+			if (structureChanged) await tx.execute(`UPDATE "${TABLE_KNOWLEDGE_ACCESS_STATE}" SET epoch=epoch+1 WHERE id='global'`);
+			const state = await tx.execute(`SELECT epoch FROM "${TABLE_KNOWLEDGE_ACCESS_STATE}" WHERE id='global'`);
+			return {
+				scopes,
+				createdScopeIds,
+				deletedScopeAddresses: [...deletedScopeAddresses],
+				changed: structureChanged,
+				accessEpoch: Number(state.rows[0]?.epoch ?? 0)
+			};
+		}));
+	}
+	async listScopeNodes(input = {}) {
+		const { limit, after } = parseListKnowledgeScopeNodesInput(input);
+		if (input.addresses?.length === 0 || input.ids?.length === 0) return {
+			scopes: [],
+			nextCursor: null
+		};
+		const args = [];
+		const where = [`n.isScope`, `n.deletedAt IS NULL`];
+		let within = "";
+		if (input.withinAddress !== void 0) {
+			within = `WITH RECURSIVE within_scope(id) AS (SELECT r.id FROM "${_mastra_core_storage.TABLE_KNOWLEDGE_NODES}" r JOIN "${TABLE_KNOWLEDGE_SCOPE_ADDRESSES}" ra ON ra.scopeNodeId=r.id WHERE ra.address=? AND r.isScope AND r.deletedAt IS NULL UNION SELECT ns.nodeId FROM "${TABLE_KNOWLEDGE_NODE_SCOPES}" ns JOIN within_scope w ON ns.scopeNodeId=w.id JOIN "${_mastra_core_storage.TABLE_KNOWLEDGE_NODES}" c ON c.id=ns.nodeId WHERE c.isScope AND c.deletedAt IS NULL) `;
+			args.push(input.withinAddress);
+			where.push("n.id IN (SELECT id FROM within_scope)");
+		}
+		if (input.addresses) {
+			where.push(`a.address IN (${input.addresses.map(() => "?").join(",")})`);
+			args.push(...input.addresses);
+		}
+		if (input.ids) {
+			where.push(`n.id IN (${input.ids.map(() => "?").join(",")})`);
+			args.push(...input.ids);
+		}
+		if (after) {
+			where.push("(n.name > ? OR (n.name = ? AND n.id > ?))");
+			args.push(after.name, after.name, after.id);
+		}
+		args.push(limit + 1);
+		const rows = (await this.#client.execute({
+			sql: `${within}SELECT n.id,n.name,n.kind,n.description,a.address FROM "${_mastra_core_storage.TABLE_KNOWLEDGE_NODES}" n LEFT JOIN "${TABLE_KNOWLEDGE_SCOPE_ADDRESSES}" a ON a.scopeNodeId=n.id WHERE ${where.join(" AND ")} ORDER BY n.name, n.id LIMIT ?`,
+			args
+		})).rows;
+		if (rows.length === 0) return {
+			scopes: [],
+			nextCursor: null
+		};
+		const parents = await this.#client.execute({
+			sql: `SELECT ns.nodeId,ns.scopeNodeId FROM "${TABLE_KNOWLEDGE_NODE_SCOPES}" ns WHERE ns.nodeId IN (${rows.map(() => "?").join(",")}) ORDER BY ns.scopeNodeId`,
+			args: rows.map((row) => String(row.id))
+		});
+		const parentsByScopeId = /* @__PURE__ */ new Map();
+		for (const row of parents.rows) {
+			const scopeId = String(row.nodeId);
+			const parentId = String(row.scopeNodeId);
+			const existing = parentsByScopeId.get(scopeId);
+			if (existing) existing.push(parentId);
+			else parentsByScopeId.set(scopeId, [parentId]);
+		}
+		return pageKnowledgeScopeNodes(rows.map((row) => ({
+			id: String(row.id),
+			address: String(row.address),
+			name: String(row.name),
+			...row.kind == null ? {} : { kind: String(row.kind) },
+			...row.description == null ? {} : { description: String(row.description) },
+			parentIds: parentsByScopeId.get(String(row.id)) ?? []
+		})), limit, input);
+	}
+	async listScopeMembers(input) {
+		const { limit, after } = parseListKnowledgeScopeMembersInput(input);
+		const args = [input.scopeNodeId];
+		let keyset = "";
+		if (after) {
+			const updatedAt = after.updatedAt.toISOString();
+			keyset = ` AND (n.updatedAt < ? OR (n.updatedAt = ? AND (n.name > ? OR (n.name = ? AND n.id > ?))))`;
+			args.push(updatedAt, updatedAt, after.name, after.name, after.id);
+		}
+		args.push(limit + 1);
+		return pageKnowledgeScopeMembers((await this.#client.execute({
+			sql: `SELECT *, json(scope) AS scopeJson FROM "${_mastra_core_storage.TABLE_KNOWLEDGE_NODES}" n WHERE EXISTS (SELECT 1 FROM "${TABLE_KNOWLEDGE_NODE_SCOPES}" ns WHERE ns.nodeId=n.id AND ns.scopeNodeId=?) AND n.deletedAt IS NULL AND n.mergedInto IS NULL${keyset} ORDER BY n.updatedAt DESC, n.name ASC, n.id ASC LIMIT ?`,
+			args
+		})).rows.map(parseNode), limit, input);
 	}
 	async createNode(input) {
 		await assertKnowledgeDescriptionWithinBoundCompat(input.description);
@@ -6233,6 +7251,7 @@ var KnowledgeLibSQL = class extends _mastra_core_storage.KnowledgeStorage {
 			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}`);
+				await this.#placeNodeInScopes(tx, terminal.id, input.scopeAddresses, /* @__PURE__ */ new Date());
 				return terminal;
 			}
 			const now = /* @__PURE__ */ new Date();
@@ -6249,7 +7268,7 @@ var KnowledgeLibSQL = class extends _mastra_core_storage.KnowledgeStorage {
 				updatedAt: now
 			};
 			await tx.execute({
-				sql: `INSERT INTO "${_mastra_core_storage.TABLE_KNOWLEDGE_NODES}" (id,type,name,canonicalName,kind,content,description,scope,scopeKey,version,mergedInto,createdAt,updatedAt) VALUES (?,?,?,?,?,?,?,jsonb(?),?,?,NULL,?,?)`,
+				sql: `INSERT INTO "${_mastra_core_storage.TABLE_KNOWLEDGE_NODES}" (id,type,name,canonicalName,kind,content,description,isScope,scope,scopeKey,version,mergedInto,createdAt,updatedAt) VALUES (?,?,?,?,?,?,?,FALSE,jsonb(?),?,?,NULL,?,?)`,
 				args: [
 					node.id,
 					"node",
@@ -6265,6 +7284,8 @@ var KnowledgeLibSQL = class extends _mastra_core_storage.KnowledgeStorage {
 					now.toISOString()
 				]
 			});
+			await this.#replaceNodeScopes(tx, node.id, scope, now);
+			await this.#placeNodeInScopes(tx, node.id, input.scopeAddresses, now);
 			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);
@@ -6281,13 +7302,13 @@ var KnowledgeLibSQL = class extends _mastra_core_storage.KnowledgeStorage {
 		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 keys = visibleScopeKeys((0, _mastra_core_storage.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))}%`);
@@ -6339,6 +7360,7 @@ var KnowledgeLibSQL = class extends _mastra_core_storage.KnowledgeStorage {
 					input.version
 				]
 			})).rowsAffected === 0) throw new _mastra_core_storage.KnowledgeConflictError(input.id);
+			if ((0, _mastra_core_storage.knowledgeScopeKey)(existing.scope) !== (0, _mastra_core_storage.knowledgeScopeKey)(scope)) await this.#swapIdentityScopes(tx, input.id, existing.scope, scope, now);
 			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)) {
@@ -6393,8 +7415,12 @@ var KnowledgeLibSQL = class extends _mastra_core_storage.KnowledgeStorage {
 				]
 			})).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]
+				sql: `UPDATE "${_mastra_core_storage.TABLE_KNOWLEDGE_RECORDS}" SET node=?,version=version+1,updatedAt=? WHERE node=?`,
+				args: [
+					target.id,
+					(/* @__PURE__ */ new Date()).toISOString(),
+					source.id
+				]
 			});
 			await tx.execute({
 				sql: `DELETE FROM "${_mastra_core_storage.TABLE_KNOWLEDGE_MENTIONS}" WHERE recordId=? AND EXISTS (SELECT 1 FROM "${_mastra_core_storage.TABLE_KNOWLEDGE_MENTIONS}" target WHERE target.sourceType="${_mastra_core_storage.TABLE_KNOWLEDGE_MENTIONS}".sourceType AND target.sourceId="${_mastra_core_storage.TABLE_KNOWLEDGE_MENTIONS}".sourceId AND target.recordId=?)`,
@@ -6434,10 +7460,10 @@ var KnowledgeLibSQL = class extends _mastra_core_storage.KnowledgeStorage {
 		});
 	}
 	async appendKnowledge(input) {
+		await assertKnowledgeRecordTextWithinBoundCompat(input.text);
 		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 node = nodeReferenceId(input.node);
 			const parent = await this.#resolveTerminalNode(tx, node);
@@ -6450,11 +7476,10 @@ var KnowledgeLibSQL = class extends _mastra_core_storage.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 "${_mastra_core_storage.TABLE_KNOWLEDGE_RECORDS}" (id,node,text,scope,scopeKey,sourceThreadId,capturedAt,"when",maxScope,metadata,deletedAt,deletedBy) VALUES (?,?,?,jsonb(?),?,?,?,?,?,jsonb(?),NULL,NULL)`,
+				sql: `INSERT INTO "${_mastra_core_storage.TABLE_KNOWLEDGE_RECORDS}" (id,node,text,scope,scopeKey,sourceThreadId,capturedAt,"when",metadata,version,updatedAt,deletedAt,deletedBy) VALUES (?,?,?,jsonb(?),?,?,?,?,jsonb(?),?,?,NULL,NULL)`,
 				args: [
 					record.id,
 					record.node,
@@ -6464,10 +7489,12 @@ var KnowledgeLibSQL = class extends _mastra_core_storage.KnowledgeStorage {
 					record.sourceThreadId,
 					record.capturedAt.toISOString(),
 					record.when?.toISOString() ?? null,
-					record.maxScope ?? null,
-					record.metadata ? JSON.stringify(record.metadata) : null
+					record.metadata ? JSON.stringify(record.metadata) : null,
+					1,
+					record.capturedAt.toISOString()
 				]
 			});
+			await this.#replaceRecordScopes(tx, record.id, scope, record.capturedAt);
 			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);
@@ -6491,17 +7518,13 @@ var KnowledgeLibSQL = class extends _mastra_core_storage.KnowledgeStorage {
 		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
-		];
+		const keys = visibleScopeKeys((0, _mastra_core_storage.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 *,json(scope) AS scopeJson,json(metadata) AS metadataJson 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 ?`,
+			sql: `SELECT *,json(scope) AS scopeJson,json(metadata) AS metadataJson FROM "${_mastra_core_storage.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 {
@@ -6516,10 +7539,11 @@ var KnowledgeLibSQL = class extends _mastra_core_storage.KnowledgeStorage {
 			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`,
+				sql: `UPDATE "${_mastra_core_storage.TABLE_KNOWLEDGE_RECORDS}" SET deletedAt=?,deletedBy=?,version=version+1,updatedAt=? WHERE id=? AND deletedAt IS NULL`,
 				args: [
 					deletedAt.toISOString(),
 					input.deletedBy,
+					deletedAt.toISOString(),
 					input.id
 				]
 			});
@@ -6538,8 +7562,8 @@ var KnowledgeLibSQL = class extends _mastra_core_storage.KnowledgeStorage {
 			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]
+				sql: `UPDATE "${_mastra_core_storage.TABLE_KNOWLEDGE_RECORDS}" SET deletedAt=NULL,deletedBy=NULL,version=version+1,updatedAt=? WHERE id=?`,
+				args: [(/* @__PURE__ */ new Date()).toISOString(), 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);
@@ -6555,15 +7579,17 @@ var KnowledgeLibSQL = class extends _mastra_core_storage.KnowledgeStorage {
 		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);
+			const updatedAt = /* @__PURE__ */ new Date();
 			await tx.execute({
-				sql: `UPDATE "${_mastra_core_storage.TABLE_KNOWLEDGE_RECORDS}" SET scope=jsonb(?),scopeKey=? WHERE id=?`,
+				sql: `UPDATE "${_mastra_core_storage.TABLE_KNOWLEDGE_RECORDS}" SET scope=jsonb(?),scopeKey=?,version=version+1,updatedAt=? WHERE id=?`,
 				args: [
 					JSON.stringify(scope),
 					(0, _mastra_core_storage.knowledgeScopeKey)(scope),
+					updatedAt.toISOString(),
 					input.id
 				]
 			});
+			await this.#replaceRecordScopes(tx, input.id, scope, updatedAt);
 			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);
@@ -6573,32 +7599,16 @@ var KnowledgeLibSQL = class extends _mastra_core_storage.KnowledgeStorage {
 			};
 		});
 	}
-	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 key = (0, _mastra_core_storage.knowledgeScopeKey)((0, _mastra_core_storage.canonicalizeKnowledgeScope)(input.scope));
+		const scope = (0, _mastra_core_storage.canonicalizeKnowledgeScope)(input.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 *,json(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 '=' OR lower(COALESCE(description,'')) LIKE ? ESCAPE '=') ORDER BY updatedAt DESC LIMIT ?`,
+			sql: `SELECT *,json(scope) AS scopeJson FROM "${_mastra_core_storage.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,
@@ -6619,60 +7629,47 @@ var KnowledgeLibSQL = class extends _mastra_core_storage.KnowledgeStorage {
 		}));
 		if (results.length < (input.limit ?? 20)) {
 			const knowledge = await this.#client.execute({
-				sql: `SELECT k.*,json(k.scope) AS scopeJson,json(k.metadata) AS metadataJson,n.name FROM "${_mastra_core_storage.TABLE_KNOWLEDGE_RECORDS}" k JOIN "${_mastra_core_storage.TABLE_KNOWLEDGE_NODES}" n ON n.id=k.node AND n.type='node' AND n.mergedInto IS NULL WHERE k.deletedAt IS NULL AND ${visibleSql.replaceAll("scopeKey", "k.scopeKey")} AND lower(k.text) LIKE ? ESCAPE '=' ORDER BY k.id DESC LIMIT ?`,
+				sql: `SELECT k.*,json(k.scope) AS scopeJson,json(k.metadata) AS metadataJson,n.name,json(n.scope) AS parentScopeJson FROM "${_mastra_core_storage.TABLE_KNOWLEDGE_RECORDS}" k CROSS JOIN "${_mastra_core_storage.TABLE_KNOWLEDGE_NODES}" n ON n.id=k.node AND n.type='node' AND n.mergedInto IS NULL WHERE k.deletedAt IS NULL AND ${visibleSql(keys, "k.scopeKey")} AND lower(k.text) LIKE ? ESCAPE '=' ORDER BY k.id DESC LIMIT ?`,
 				args: [
-					key,
-					key,
+					...keys,
 					query,
 					(input.limit ?? 20) - results.length
 				]
 			});
-			results.push(...knowledge.rows.map((row) => ({
-				type: "record",
-				id: String(row.id),
-				recordId: String(row.node),
-				name: String(row.name),
-				text: String(row.text),
-				scope: parseJson$3(row.scopeJson)
-			})));
+			results.push(...knowledge.rows.map((row) => {
+				const parentVisible = (0, _mastra_core_storage.isKnowledgeScopeVisible)(parseJson$3(row.parentScopeJson), scope);
+				return {
+					type: "record",
+					id: String(row.id),
+					recordId: parentVisible ? String(row.node) : String(row.id),
+					name: parentVisible ? String(row.name) : "(private node)",
+					text: String(row.text),
+					scope: parseJson$3(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.#db.executeWriteOperationWithRetry(() => withClientWriteLock(this.#client, () => this.#client.execute({
-			sql: `INSERT INTO "${_mastra_core_storage.TABLE_KNOWLEDGE_CURSORS}" (sourceThreadId,agent,lastKnowledgeId,updatedAt) VALUES (?,?,?,?) ON CONFLICT(sourceThreadId,agent) DO UPDATE SET lastKnowledgeId=excluded.lastKnowledgeId,updatedAt=excluded.updatedAt WHERE excluded.lastKnowledgeId >= "${_mastra_core_storage.TABLE_KNOWLEDGE_CURSORS}".lastKnowledgeId`,
-			args: [
-				input.sourceThreadId,
-				input.agent,
-				input.lastKnowledgeId,
-				updatedAt.toISOString()
-			]
-		})), "advance knowledge curation cursor")).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 = (0, _mastra_core_storage.knowledgeScopeKey)((0, _mastra_core_storage.canonicalizeKnowledgeScope)(input.scope));
+		const keys = visibleScopeKeys((0, _mastra_core_storage.canonicalizeKnowledgeScope)(input.scope));
 		return (await this.#client.execute({
-			sql: `SELECT *,json(scope) AS scopeJson FROM "${_mastra_core_storage.TABLE_KNOWLEDGE_ACTIVITY}" WHERE ${visibleSql}${input.after ? " AND id < ?" : ""} ORDER BY id DESC LIMIT ?`,
+			sql: `SELECT *,json(scope) AS scopeJson FROM "${_mastra_core_storage.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
 			]
@@ -6694,9 +7691,9 @@ var KnowledgeLibSQL = class extends _mastra_core_storage.KnowledgeStorage {
 			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);
+			const keys = visibleScopeKeys(input.scope);
+			clauses.push(visibleSql(keys));
+			args.push(...keys);
 		}
 		args.push(input.limit ?? 100);
 		return (await this.#client.execute({
@@ -6715,9 +7712,9 @@ var KnowledgeLibSQL = class extends _mastra_core_storage.KnowledgeStorage {
 			];
 			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);
+				const keys = visibleScopeKeys(input.scope);
+				clauses.push(visibleSql(keys));
+				args.push(...keys);
 			}
 			args.push(input.limit ?? 100);
 			const ids = (await tx.execute({
@@ -6794,12 +7791,14 @@ var KnowledgeLibSQL = class extends _mastra_core_storage.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 && (0, _mastra_core_storage.isKnowledgeScopeVisible)(terminal.scope, scope)) return terminal;
-			}
+		const keys = visibleScopeKeys(scope);
+		const candidates = (await executor.execute({
+			sql: `SELECT *,json(scope) AS scopeJson FROM "${_mastra_core_storage.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 && (0, _mastra_core_storage.isKnowledgeScopeVisible)(terminal.scope, scope)) return terminal;
 		}
 		return null;
 	}
@@ -6824,19 +7823,18 @@ var KnowledgeLibSQL = class extends _mastra_core_storage.KnowledgeStorage {
 		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 keys = visibleScopeKeys(scope);
 		const includesMentions = relationship !== "about";
 		const relationSql = relationship === "about" ? "k.node=?" : relationship === "mentioning" ? "m.recordId=?" : "(k.node=? OR m.recordId=?)";
 		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 result = await this.#client.execute({
-			sql: `SELECT DISTINCT k.*,json(k.scope) AS scopeJson,json(k.metadata) AS metadataJson FROM "${_mastra_core_storage.TABLE_KNOWLEDGE_RECORDS}" k${includesMentions ? ` LEFT JOIN "${_mastra_core_storage.TABLE_KNOWLEDGE_MENTIONS}" m ON m.sourceType='record' AND m.sourceId=k.id` : ""} WHERE ${relationSql} AND ${visibleSql.replaceAll("scopeKey", "k.scopeKey")}${input.includeDeleted ? "" : " AND k.deletedAt IS NULL"}${input.after ? " AND k.id < ?" : ""} ORDER BY k.id DESC LIMIT ?`,
+			sql: `SELECT DISTINCT k.*,json(k.scope) AS scopeJson,json(k.metadata) AS metadataJson FROM "${_mastra_core_storage.TABLE_KNOWLEDGE_RECORDS}" k${includesMentions ? ` LEFT JOIN "${_mastra_core_storage.TABLE_KNOWLEDGE_MENTIONS}" m ON m.sourceType='record' AND m.sourceId=k.id` : ""} WHERE ${relationSql} AND ${visibleSql(keys, "k.scopeKey")}${input.includeDeleted ? "" : " AND k.deletedAt IS NULL"}${input.after ? " AND k.id < ?" : ""} ORDER BY k.id DESC LIMIT ?`,
 			args
 		});
 		const limit = input.limit ?? 100;
@@ -6846,6 +7844,90 @@ var KnowledgeLibSQL = class extends _mastra_core_storage.KnowledgeStorage {
 			nextCursor: result.rows.length > limit ? String(rows.at(-1)?.id) : void 0
 		};
 	}
+	async #resolveScopeNodeIds(executor, addresses) {
+		const scopeNodeIds = /* @__PURE__ */ new Set();
+		for (const address of addresses) {
+			const result = await executor.execute({
+				sql: `SELECT scopeNodeId FROM "${TABLE_KNOWLEDGE_SCOPE_ADDRESSES}" WHERE address=?`,
+				args: [address]
+			});
+			if (result.rows[0]?.scopeNodeId != null) scopeNodeIds.add(String(result.rows[0].scopeNodeId));
+		}
+		return [...scopeNodeIds];
+	}
+	async #replaceNodeScopes(executor, nodeId, addresses, addedAt) {
+		await executor.execute({
+			sql: `DELETE FROM "${TABLE_KNOWLEDGE_NODE_SCOPES}" WHERE nodeId=?`,
+			args: [nodeId]
+		});
+		for (const scopeNodeId of await this.#resolveScopeNodeIds(executor, addresses)) await executor.execute({
+			sql: `INSERT OR IGNORE INTO "${TABLE_KNOWLEDGE_NODE_SCOPES}" (nodeId,scopeNodeId,addedAt) VALUES (?,?,?)`,
+			args: [
+				nodeId,
+				scopeNodeId,
+				addedAt.toISOString()
+			]
+		});
+	}
+	/**
+	* Move a node's identity memberships from `from` to `to` without touching structural
+	* placements added by `#placeNodeInScopes`, which a scope change must not erase.
+	*/
+	async #swapIdentityScopes(executor, nodeId, from, to, addedAt) {
+		const next = await this.#resolveScopeNodeIds(executor, to);
+		for (const scopeNodeId of await this.#resolveScopeNodeIds(executor, from)) {
+			if (next.includes(scopeNodeId)) continue;
+			await executor.execute({
+				sql: `DELETE FROM "${TABLE_KNOWLEDGE_NODE_SCOPES}" WHERE nodeId=? AND scopeNodeId=?`,
+				args: [nodeId, scopeNodeId]
+			});
+		}
+		for (const scopeNodeId of next) await executor.execute({
+			sql: `INSERT OR IGNORE INTO "${TABLE_KNOWLEDGE_NODE_SCOPES}" (nodeId,scopeNodeId,addedAt) VALUES (?,?,?)`,
+			args: [
+				nodeId,
+				scopeNodeId,
+				addedAt.toISOString()
+			]
+		});
+	}
+	/**
+	* Additive structural placement: every address must resolve to a live scope node
+	* (unlike identity membership, an unknown address is a caller error, not a lazy
+	* materialization miss). Runs inside the caller's transaction, so a throw aborts
+	* the whole mutation.
+	*/
+	async #placeNodeInScopes(executor, nodeId, addresses, addedAt) {
+		for (const address of addresses ?? []) {
+			const scopeNodeId = (await executor.execute({
+				sql: `SELECT sa.scopeNodeId AS scopeNodeId FROM "${TABLE_KNOWLEDGE_SCOPE_ADDRESSES}" sa JOIN "${_mastra_core_storage.TABLE_KNOWLEDGE_NODES}" n ON n.id=sa.scopeNodeId WHERE sa.address=? AND n.isScope AND n.deletedAt IS NULL`,
+				args: [address]
+			})).rows[0]?.scopeNodeId;
+			if (scopeNodeId == null) throw new _mastra_core_storage.KnowledgeNotFoundError("scope", address);
+			await executor.execute({
+				sql: `INSERT OR IGNORE INTO "${TABLE_KNOWLEDGE_NODE_SCOPES}" (nodeId,scopeNodeId,addedAt) VALUES (?,?,?)`,
+				args: [
+					nodeId,
+					String(scopeNodeId),
+					addedAt.toISOString()
+				]
+			});
+		}
+	}
+	async #replaceRecordScopes(executor, recordId, addresses, addedAt) {
+		await executor.execute({
+			sql: `DELETE FROM "${TABLE_KNOWLEDGE_RECORD_SCOPES}" WHERE recordId=?`,
+			args: [recordId]
+		});
+		for (const scopeNodeId of await this.#resolveScopeNodeIds(executor, addresses)) await executor.execute({
+			sql: `INSERT OR IGNORE INTO "${TABLE_KNOWLEDGE_RECORD_SCOPES}" (recordId,scopeNodeId,addedAt) VALUES (?,?,?)`,
+			args: [
+				recordId,
+				scopeNodeId,
+				addedAt.toISOString()
+			]
+		});
+	}
 	async #replaceMentions(tx, sourceType, sourceId, text, resolutionScope, defaultScope) {
 		await tx.execute({
 			sql: `DELETE FROM "${_mastra_core_storage.TABLE_KNOWLEDGE_MENTIONS}" WHERE sourceType=? AND sourceId=?`,
@@ -6869,7 +7951,7 @@ var KnowledgeLibSQL = class extends _mastra_core_storage.KnowledgeStorage {
 						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,?,?)`,
+						sql: `INSERT INTO "${_mastra_core_storage.TABLE_KNOWLEDGE_NODES}" (id,type,name,canonicalName,kind,content,isScope,scope,scopeKey,version,mergedInto,createdAt,updatedAt) VALUES (?,?,?,?,?,NULL,FALSE,jsonb(?),?,?,NULL,?,?)`,
 						args: [
 							node.id,
 							"node",
@@ -6883,6 +7965,7 @@ var KnowledgeLibSQL = class extends _mastra_core_storage.KnowledgeStorage {
 							now.toISOString()
 						]
 					});
+					await this.#replaceNodeScopes(tx, node.id, defaultScope, now);
 					await this.#activity(tx, "node-created", "node", node.id, defaultScope);
 					await this.#outbox(tx, "node", node.id, "upsert", 1, defaultScope);
 				}
@@ -6899,13 +7982,17 @@ var KnowledgeLibSQL = class extends _mastra_core_storage.KnowledgeStorage {
 	}
 	async #activity(executor, action, recordType, recordId, scope, sourceThreadId) {
 		const now = /* @__PURE__ */ new Date();
+		const [contextScopeId] = await this.#resolveScopeNodeIds(executor, scope);
 		await executor.execute({
-			sql: `INSERT INTO "${_mastra_core_storage.TABLE_KNOWLEDGE_ACTIVITY}" (id,action,recordType,recordId,scope,scopeKey,sourceThreadId,createdAt) VALUES (?,?,?,?,jsonb(?),?,?,?)`,
+			sql: `INSERT INTO "${_mastra_core_storage.TABLE_KNOWLEDGE_ACTIVITY}" (id,action,targetType,targetId,contextScopeId,recordType,recordId,scope,scopeKey,sourceThreadId,createdAt) VALUES (?,?,?,?,?,?,?,jsonb(?),?,?,?)`,
 			args: [
 				(0, _mastra_core_storage.createKnowledgeUlid)(),
 				action,
 				recordType,
 				recordId,
+				contextScopeId ?? null,
+				recordType,
+				recordId,
 				JSON.stringify(scope),
 				(0, _mastra_core_storage.knowledgeScopeKey)(scope),
 				sourceThreadId ?? null,
@@ -14683,7 +15770,10 @@ var LibSQLStore = class extends _mastra_core_storage.MastraCompositeStore {
 		const workflows = new WorkflowsLibSQL(domainConfig);
 		const workflowDefinitions = new WorkflowDefinitionsLibSQL(domainConfig);
 		const memory = new MemoryLibSQL(domainConfig);
-		const knowledge = new KnowledgeLibSQL(domainConfig);
+		const knowledge = new KnowledgeLibSQL({
+			...domainConfig,
+			storageIsolationKey: config.storageIsolationKey ?? getLibSQLKnowledgeIsolationKey(config, this.client)
+		});
 		const observability = new ObservabilityLibSQL(domainConfig);
 		const agents = new AgentsLibSQL(domainConfig);
 		const channels = new ChannelsLibSQL(domainConfig);
@@ -14747,7 +15837,7 @@ var LibSQLStore = class extends _mastra_core_storage.MastraCompositeStore {
 		}
 	}
 	getStoresToInit() {
-		return Object.values(this.stores).filter(Boolean);
+		return Object.entries(this.stores).filter(([name]) => name !== "knowledge").map(([, store]) => store).filter(Boolean);
 	}
 	async initDomainsSequentially() {
 		for (const store of this.getStoresToInit()) await store.init();