@mastra/pg 1.31.0-alpha.2 → 1.31.0-alpha.3

package/dist/index.cjs

@@ -35,8 +35,8 @@ let pg_connection_string = require("pg-connection-string");
 let _mastra_core_vector_filter = require("@mastra/core/vector/filter");
 let _mastra_core_base = require("@mastra/core/base");
 let crypto$1 = require("crypto");
-let _mastra_core_agent = require("@mastra/core/agent");
 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");
 let util = require("util");
@@ -8301,18 +8301,650 @@ var FavoritesPG = class FavoritesPG extends _mastra_core_storage.FavoritesStorag
 	}
 };
 //#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 camelCaseColumns = [
 	"canonicalName",
@@ -8323,7 +8955,6 @@ const camelCaseColumns = [
 	"node",
 	"sourceThreadId",
 	"capturedAt",
-	"maxScope",
 	"deletedAt",
 	"deletedBy",
 	"sourceType",
@@ -8337,7 +8968,30 @@ const camelCaseColumns = [
 	"availableAt",
 	"claimedAt",
 	"claimedBy",
-	"completedAt"
+	"completedAt",
+	"isScope",
+	"nodeId",
+	"targetNodeId",
+	"scopeNodeId",
+	"scopeRefId",
+	"canSuggest",
+	"schemaVersion",
+	"importerId",
+	"importKind",
+	"triggerKind",
+	"transcriptThreadId",
+	"traceId",
+	"queuedAt",
+	"startedAt",
+	"targetType",
+	"targetId",
+	"contextScopeId",
+	"importRunId",
+	"proposerContextScopeId",
+	"expectedVersion",
+	"reviewerContextScopeId",
+	"reviewedAt",
+	"addedAt"
 ];
 function transformSqlCode(sql, transform) {
 	return sql.split(/('(?:''|[^'])*')/g).map((part, index) => index % 2 === 0 ? transform(part) : part).join("");
@@ -8352,14 +9006,7 @@ function postgresSql(sql, schemaName) {
 		const quotedSchema = `"${parseSchemaName(schemaName)}"`;
 		normalized = transformSqlCode(normalized, (code) => {
 			let transformed = code;
-			for (const table of [
-				_mastra_core_storage.TABLE_KNOWLEDGE_NODES,
-				_mastra_core_storage.TABLE_KNOWLEDGE_RECORDS,
-				_mastra_core_storage.TABLE_KNOWLEDGE_MENTIONS,
-				_mastra_core_storage.TABLE_KNOWLEDGE_CURSORS,
-				_mastra_core_storage.TABLE_KNOWLEDGE_ACTIVITY,
-				_mastra_core_storage.TABLE_KNOWLEDGE_SEMANTIC_OUTBOX
-			]) transformed = transformed.replaceAll(`"${table}"`, `${quotedSchema}."${table}"`);
+			for (const table of [...KNOWLEDGE_TABLE_NAMES, ...RETIRED_KNOWLEDGE_TABLE_NAMES]) transformed = transformed.replaceAll(`"${table}"`, `${quotedSchema}."${table}"`);
 			return transformed;
 		});
 	}
@@ -8367,17 +9014,35 @@ function postgresSql(sql, schemaName) {
 	return transformSqlCode(normalized, (code) => code.replace(/\?/g, () => `$${++index}`));
 }
 function createExecutor(client, schemaName) {
-	return { async execute(statement) {
+	const execute = async (statement, qualifyWithSchema) => {
 		const sql = typeof statement === "string" ? statement : statement.sql;
 		const args = typeof statement === "string" ? [] : statement.args ?? [];
-		const result = await client.query(postgresSql(sql, schemaName), args);
+		const result = await client.query(postgresSql(sql, qualifyWithSchema ? schemaName : void 0), args);
 		return {
 			rows: result.rows,
 			rowsAffected: result.rowCount ?? 0
 		};
-	} };
+	};
+	return {
+		execute: (statement) => execute(statement, true),
+		executeRaw: (statement) => execute(statement, false)
+	};
+}
+/**
+* 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 = `(scopeKey = ? OR LEFT(?, LENGTH(scopeKey) + 1) = scopeKey || chr(31))`;
+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));
@@ -8417,9 +9082,10 @@ function parseNode(row) {
 		id: String(row.id),
 		type: "node",
 		name: String(row.name),
-		kind: String(row.kind),
+		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$1(row.scopeJson ?? row.scope),
 		version: Number(row.version),
 		mergedInto: row.mergedInto == null ? void 0 : String(row.mergedInto),
@@ -8436,7 +9102,6 @@ function parseKnowledge(row) {
 		sourceThreadId: String(row.sourceThreadId),
 		capturedAt: toDate$1(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)
@@ -8473,6 +9138,10 @@ function knowledgeIndexes(schemaName) {
 			name: "idx_knowledge_nodes_scope",
 			sql: `CREATE INDEX IF NOT EXISTS idx_knowledge_nodes_scope ON ${table(_mastra_core_storage.TABLE_KNOWLEDGE_NODES)} ("scopeKey", "type");`
 		},
+		{
+			name: "idx_knowledge_nodes_name",
+			sql: `CREATE INDEX IF NOT EXISTS idx_knowledge_nodes_name ON ${table(_mastra_core_storage.TABLE_KNOWLEDGE_NODES)} ("type", "canonicalName");`
+		},
 		{
 			name: "idx_knowledge_records_node_latest",
 			sql: `CREATE INDEX IF NOT EXISTS idx_knowledge_records_node_latest ON ${table(_mastra_core_storage.TABLE_KNOWLEDGE_RECORDS)} ("node", "id" DESC);`
@@ -8489,6 +9158,14 @@ function knowledgeIndexes(schemaName) {
 			name: "idx_knowledge_activity_latest",
 			sql: `CREATE INDEX IF NOT EXISTS idx_knowledge_activity_latest ON ${table(_mastra_core_storage.TABLE_KNOWLEDGE_ACTIVITY)} ("id" DESC);`
 		},
+		{
+			name: "idx_knowledge_records_scope",
+			sql: `CREATE INDEX IF NOT EXISTS idx_knowledge_records_scope ON ${table(_mastra_core_storage.TABLE_KNOWLEDGE_RECORDS)} ("scopeKey", "id");`
+		},
+		{
+			name: "idx_knowledge_activity_scope",
+			sql: `CREATE INDEX IF NOT EXISTS idx_knowledge_activity_scope ON ${table(_mastra_core_storage.TABLE_KNOWLEDGE_ACTIVITY)} ("scopeKey", "id" DESC);`
+		},
 		{
 			name: "idx_knowledge_outbox_idempotency",
 			sql: `CREATE UNIQUE INDEX IF NOT EXISTS idx_knowledge_outbox_idempotency ON ${table(_mastra_core_storage.TABLE_KNOWLEDGE_SEMANTIC_OUTBOX)} ("idempotencyKey");`
@@ -8496,67 +9173,152 @@ function knowledgeIndexes(schemaName) {
 		{
 			name: "idx_knowledge_outbox_claim",
 			sql: `CREATE INDEX IF NOT EXISTS idx_knowledge_outbox_claim ON ${table(_mastra_core_storage.TABLE_KNOWLEDGE_SEMANTIC_OUTBOX)} ("status", "availableAt", "createdAt");`
+		},
+		{
+			name: "idx_knowledge_node_scopes_scope",
+			sql: `CREATE INDEX IF NOT EXISTS idx_knowledge_node_scopes_scope ON ${table(TABLE_KNOWLEDGE_NODE_SCOPES)} ("scopeNodeId", "nodeId");`
+		},
+		{
+			name: "idx_knowledge_record_scopes_scope",
+			sql: `CREATE INDEX IF NOT EXISTS idx_knowledge_record_scopes_scope ON ${table(TABLE_KNOWLEDGE_RECORD_SCOPES)} ("scopeNodeId", "recordId");`
+		},
+		{
+			name: "idx_knowledge_scope_grants_ref",
+			sql: `CREATE INDEX IF NOT EXISTS idx_knowledge_scope_grants_ref ON ${table(TABLE_KNOWLEDGE_SCOPE_GRANTS)} ("scopeRefId", "scopeNodeId");`
+		},
+		{
+			name: "idx_knowledge_node_addresses_node",
+			sql: `CREATE INDEX IF NOT EXISTS idx_knowledge_node_addresses_node ON ${table(TABLE_KNOWLEDGE_NODE_ADDRESSES)} ("nodeId");`
+		},
+		{
+			name: "idx_knowledge_import_runs_lookup",
+			sql: `CREATE INDEX IF NOT EXISTS idx_knowledge_import_runs_lookup ON ${table(TABLE_KNOWLEDGE_IMPORT_RUNS)} ("importerId", "binding", "queuedAt" DESC);`
+		},
+		{
+			name: "idx_knowledge_activity_import_run",
+			sql: `CREATE INDEX IF NOT EXISTS idx_knowledge_activity_import_run ON ${table(_mastra_core_storage.TABLE_KNOWLEDGE_ACTIVITY)} ("importRunId", "id" DESC);`
 		}
 	];
 }
 function knowledgeIndexDDL(schemaName) {
 	return knowledgeIndexes(schemaName).map((index) => index.sql);
 }
+const KNOWLEDGE_CURATION_CURSOR_REMOVED_MESSAGE = "Knowledge curation cursors were removed: observation-time curate is the only Knowledge writer and needs no cursor.";
+const knowledgeTableDefinitions = [
+	{
+		tableName: _mastra_core_storage.TABLE_KNOWLEDGE_NODES,
+		schema: KNOWLEDGE_V2_NODES_SCHEMA
+	},
+	{
+		tableName: _mastra_core_storage.TABLE_KNOWLEDGE_RECORDS,
+		schema: KNOWLEDGE_V2_RECORDS_SCHEMA
+	},
+	{
+		tableName: _mastra_core_storage.TABLE_KNOWLEDGE_MENTIONS,
+		schema: KNOWLEDGE_V2_MENTIONS_SCHEMA,
+		compositePrimaryKey: ["recordId", "sourceId"]
+	},
+	{
+		tableName: TABLE_KNOWLEDGE_NODE_SCOPES,
+		schema: KNOWLEDGE_NODE_SCOPES_SCHEMA,
+		compositePrimaryKey: ["nodeId", "scopeNodeId"]
+	},
+	{
+		tableName: TABLE_KNOWLEDGE_RECORD_SCOPES,
+		schema: KNOWLEDGE_RECORD_SCOPES_SCHEMA,
+		compositePrimaryKey: ["recordId", "scopeNodeId"]
+	},
+	{
+		tableName: TABLE_KNOWLEDGE_SCOPE_GRANTS,
+		schema: KNOWLEDGE_SCOPE_GRANTS_SCHEMA,
+		compositePrimaryKey: ["scopeNodeId", "scopeRefId"]
+	},
+	{
+		tableName: TABLE_KNOWLEDGE_ACCESS_STATE,
+		schema: KNOWLEDGE_ACCESS_STATE_SCHEMA
+	},
+	{
+		tableName: TABLE_KNOWLEDGE_SCOPE_ADDRESSES,
+		schema: KNOWLEDGE_SCOPE_ADDRESSES_SCHEMA
+	},
+	{
+		tableName: TABLE_KNOWLEDGE_NODE_ADDRESSES,
+		schema: KNOWLEDGE_NODE_ADDRESSES_SCHEMA,
+		compositePrimaryKey: ["source", "address"]
+	},
+	{
+		tableName: TABLE_KNOWLEDGE_IMPORT_STATE,
+		schema: KNOWLEDGE_IMPORT_STATE_SCHEMA,
+		compositePrimaryKey: [
+			"importerId",
+			"binding",
+			"key"
+		]
+	},
+	{
+		tableName: TABLE_KNOWLEDGE_IMPORT_RUNS,
+		schema: KNOWLEDGE_IMPORT_RUNS_SCHEMA
+	},
+	{
+		tableName: TABLE_KNOWLEDGE_PROPOSALS,
+		schema: KNOWLEDGE_PROPOSALS_SCHEMA
+	},
+	{
+		tableName: _mastra_core_storage.TABLE_KNOWLEDGE_ACTIVITY,
+		schema: KNOWLEDGE_V2_ACTIVITY_SCHEMA
+	},
+	{
+		tableName: _mastra_core_storage.TABLE_KNOWLEDGE_SEMANTIC_OUTBOX,
+		schema: _mastra_core_storage.KNOWLEDGE_SEMANTIC_OUTBOX_SCHEMA
+	}
+];
+function pgSetting(config, key) {
+	const value = config[key] || process.env[`PG${key.toUpperCase()}`] || pg.defaults[key];
+	return value === void 0 || value === null || value === "" ? void 0 : String(value);
+}
+function effectivePgTarget(config) {
+	const host = pgSetting(config, "host");
+	const database = pgSetting(config, "database") ?? pgSetting(config, "user");
+	if (!host || !database) return void 0;
+	return `${host.startsWith("/") ? host : host.toLocaleLowerCase()}:${pgSetting(config, "port") ?? "5432"}/${database}`;
+}
+function canonicalPgTarget(config) {
+	if (config.connectionString) try {
+		const parsed = new URL(config.connectionString);
+		return effectivePgTarget({
+			host: decodeURIComponent(parsed.hostname) || config.host,
+			port: parsed.port || config.port,
+			database: decodeURIComponent(parsed.pathname.slice(1)) || config.database,
+			user: decodeURIComponent(parsed.username) || config.user
+		});
+	} catch {
+		return config.connectionString;
+	}
+	return effectivePgTarget(config);
+}
+function pgSourceConfig(source) {
+	if (!source || !("options" in source)) return void 0;
+	return source.options;
+}
+function pgClientPool(client) {
+	if (!client || !("$pool" in client)) return void 0;
+	return client.$pool;
+}
+function getPgKnowledgeIsolationKey(config) {
+	const schema = config.schemaName ?? "public";
+	const poolConfig = pgSourceConfig(config.pool ?? pgClientPool(config.client));
+	const target = Boolean(config.connectionString || config.host || config.database) ? canonicalPgTarget(config) : poolConfig ? canonicalPgTarget(poolConfig) : void 0;
+	if (target) return `pg:${target}:schema:${schema}`;
+	return `pg:unidentified:schema:${schema}`;
+}
 var KnowledgePG = class extends _mastra_core_storage.KnowledgeStorage {
-	static MANAGED_TABLES = [
-		_mastra_core_storage.TABLE_KNOWLEDGE_NODES,
-		_mastra_core_storage.TABLE_KNOWLEDGE_RECORDS,
-		_mastra_core_storage.TABLE_KNOWLEDGE_MENTIONS,
-		_mastra_core_storage.TABLE_KNOWLEDGE_CURSORS,
-		_mastra_core_storage.TABLE_KNOWLEDGE_ACTIVITY,
-		_mastra_core_storage.TABLE_KNOWLEDGE_SEMANTIC_OUTBOX
-	];
+	static MANAGED_TABLES = KNOWLEDGE_TABLE_NAMES;
 	static getExportDDL(schemaName) {
-		return [
-			generateTableSQL({
-				tableName: _mastra_core_storage.TABLE_KNOWLEDGE_NODES,
-				schema: _mastra_core_storage.KNOWLEDGE_NODES_SCHEMA,
-				schemaName,
-				includeAllConstraints: true
-			}),
-			generateTableSQL({
-				tableName: _mastra_core_storage.TABLE_KNOWLEDGE_RECORDS,
-				schema: _mastra_core_storage.KNOWLEDGE_RECORDS_SCHEMA,
-				schemaName,
-				includeAllConstraints: true
-			}),
-			generateTableSQL({
-				tableName: _mastra_core_storage.TABLE_KNOWLEDGE_MENTIONS,
-				schema: _mastra_core_storage.KNOWLEDGE_MENTIONS_SCHEMA,
-				schemaName,
-				compositePrimaryKey: [
-					"sourceType",
-					"sourceId",
-					"recordId"
-				],
-				includeAllConstraints: true
-			}),
-			generateTableSQL({
-				tableName: _mastra_core_storage.TABLE_KNOWLEDGE_CURSORS,
-				schema: _mastra_core_storage.KNOWLEDGE_CURSORS_SCHEMA,
-				schemaName,
-				compositePrimaryKey: ["sourceThreadId", "agent"],
-				includeAllConstraints: true
-			}),
-			generateTableSQL({
-				tableName: _mastra_core_storage.TABLE_KNOWLEDGE_ACTIVITY,
-				schema: _mastra_core_storage.KNOWLEDGE_ACTIVITY_SCHEMA,
-				schemaName,
-				includeAllConstraints: true
-			}),
-			generateTableSQL({
-				tableName: _mastra_core_storage.TABLE_KNOWLEDGE_SEMANTIC_OUTBOX,
-				schema: _mastra_core_storage.KNOWLEDGE_SEMANTIC_OUTBOX_SCHEMA,
-				schemaName,
-				includeAllConstraints: true
-			}),
-			...knowledgeIndexDDL(schemaName)
-		];
+		return [...knowledgeTableDefinitions.map((definition) => generateTableSQL({
+			...definition,
+			schemaName,
+			includeAllConstraints: true
+		})), ...knowledgeIndexDDL(schemaName)];
 	}
 	#client;
 	#executor;
@@ -8565,7 +9327,7 @@ var KnowledgePG = class extends _mastra_core_storage.KnowledgeStorage {
 	#db;
 	#schemaName;
 	constructor(config) {
-		super();
+		super({ storageIsolationKey: config.storageIsolationKey ?? getPgKnowledgeIsolationKey(config) });
 		const { client, readClient, schemaName, skipDefaultIndexes } = resolvePgConfig(config);
 		this.#client = client;
 		this.#schemaName = schemaName;
@@ -8578,56 +9340,359 @@ var KnowledgePG = class extends _mastra_core_storage.KnowledgeStorage {
 			skipDefaultIndexes
 		});
 	}
-	async init() {
-		await this.#db.createTable({
-			tableName: _mastra_core_storage.TABLE_KNOWLEDGE_NODES,
-			schema: _mastra_core_storage.KNOWLEDGE_NODES_SCHEMA
-		});
-		await this.#db.alterTable({
-			tableName: _mastra_core_storage.TABLE_KNOWLEDGE_NODES,
-			schema: _mastra_core_storage.KNOWLEDGE_NODES_SCHEMA,
-			ifNotExists: ["description"]
+	getCapabilities() {
+		return {
+			contractVersion: 2,
+			schemaVersion: 2,
+			supportsV2: true,
+			supportsSchemaInspection: true,
+			supportsExplicitReset: true
+		};
+	}
+	async inspectSchema() {
+		const { inspectKnowledgeSchema } = await loadKnowledgeV2Core();
+		try {
+			const snapshot = getSchemaSnapshot(this.#client, this.#schemaName);
+			if (snapshot) {
+				const tableNames = KNOWLEDGE_TABLE_NAMES.filter((table) => snapshot.tables.has(table));
+				return this.#classifySchema(this.#executor, tableNames, snapshot.columns);
+			}
+			return this.#inspectSchemaWithExecutor(this.#executor);
+		} catch (error) {
+			return inspectKnowledgeSchema({
+				available: false,
+				tableNames: [],
+				reason: error instanceof Error ? error.message : String(error)
+			});
+		}
+	}
+	async #inspectSchemaWithExecutor(executor) {
+		const tableNames = (await executor.execute({
+			sql: `SELECT table_name FROM information_schema.tables WHERE table_schema = COALESCE(?, current_schema()) AND table_name = ANY(?::text[])`,
+			args: [this.#schemaName ?? null, [...KNOWLEDGE_TABLE_NAMES]]
+		})).rows.map((row) => String(row.table_name));
+		const columnResult = await executor.execute({
+			sql: `SELECT table_name, column_name FROM information_schema.columns WHERE table_schema = COALESCE(?, current_schema()) AND table_name = ANY(?::text[])`,
+			args: [this.#schemaName ?? null, [...KNOWLEDGE_TABLE_NAMES]]
+		});
+		const columns = /* @__PURE__ */ new Map();
+		for (const row of columnResult.rows) {
+			const table = String(row.table_name);
+			const names = columns.get(table) ?? /* @__PURE__ */ new Set();
+			names.add(String(row.column_name));
+			columns.set(table, names);
+		}
+		return this.#classifySchema(executor, tableNames, columns);
+	}
+	async #classifySchema(executor, tableNames, columns) {
+		const { inspectKnowledgeSchema } = await loadKnowledgeV2Core();
+		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 { tableName: table, schema } of knowledgeTableDefinitions) {
+			const actual = columns.get(table) ?? /* @__PURE__ */ new Set();
+			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
 		});
-		await this.#db.createTable({
-			tableName: _mastra_core_storage.TABLE_KNOWLEDGE_RECORDS,
-			schema: _mastra_core_storage.KNOWLEDGE_RECORDS_SCHEMA
+	}
+	async init() {
+		await this.#transaction(async (tx) => {
+			await tx.execute({
+				sql: "SELECT pg_advisory_xact_lock(hashtext(?))",
+				args: [`mastra-knowledge-v2:${this.#schemaName ?? "current_schema"}`]
+			});
+			const { assertKnowledgeSchemaCompatible } = await loadKnowledgeV2Core();
+			let inspection = await this.#inspectSchemaWithExecutor(tx);
+			if (inspection.status === "incompatible-reset-required" && await this.#isPublishedV1Layout(tx)) {
+				const tables = [...RETIRED_KNOWLEDGE_TABLE_NAMES, ...[...KNOWLEDGE_TABLE_NAMES].reverse()].map((table) => `"${table}"`).join(", ");
+				await tx.execute(`DROP TABLE IF EXISTS ${tables}`);
+				inspection = await this.#inspectSchemaWithExecutor(tx);
+			}
+			assertKnowledgeSchemaCompatible(inspection);
+			for (const definition of knowledgeTableDefinitions) await tx.executeRaw(generateTableSQL({
+				...definition,
+				schemaName: this.#schemaName,
+				includeAllConstraints: true
+			}));
+			for (const index of knowledgeIndexes(this.#schemaName)) await tx.executeRaw(index.sql);
+			await tx.execute({
+				sql: `INSERT INTO "${TABLE_KNOWLEDGE_ACCESS_STATE}" (id, epoch, schemaVersion) VALUES ('global', 0, ?) ON CONFLICT (id) DO NOTHING`,
+				args: [2]
+			});
 		});
-		await this.#db.createTable({
-			tableName: _mastra_core_storage.TABLE_KNOWLEDGE_MENTIONS,
-			schema: _mastra_core_storage.KNOWLEDGE_MENTIONS_SCHEMA,
-			compositePrimaryKey: [
-				"sourceType",
-				"sourceId",
-				"recordId"
+	}
+	/**
+	* 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, extra indexes)
+	* needs an explicit reset.
+	*/
+	async #isPublishedV1Layout(executor) {
+		const schema = this.#schemaName ?? null;
+		const relations = await executor.execute({
+			sql: `SELECT table_name, table_type FROM information_schema.tables WHERE table_schema = COALESCE(?, current_schema()) AND table_name LIKE 'mastra\\_knowledge\\_%'`,
+			args: [schema]
+		});
+		const tables = [];
+		for (const row of relations.rows) {
+			const name = String(row.table_name);
+			if (row.table_type !== "BASE TABLE" || !PUBLISHED_KNOWLEDGE_V1_TABLE_NAMES.has(name)) return false;
+			tables.push(name);
+		}
+		const indexes = await executor.execute({
+			sql: `SELECT indexname FROM pg_indexes WHERE schemaname = COALESCE(?, current_schema()) AND tablename = ANY(?::text[])`,
+			args: [schema, tables]
+		});
+		for (const row of indexes.rows) {
+			const name = String(row.indexname);
+			if (!PUBLISHED_KNOWLEDGE_V1_INDEX_NAMES.has(name) && !name.endsWith("_pkey")) return false;
+		}
+		if ((await executor.execute({
+			sql: `SELECT 1 FROM information_schema.view_table_usage WHERE table_schema = COALESCE(?, current_schema()) AND table_name = ANY(?::text[]) UNION ALL SELECT 1 FROM information_schema.triggers WHERE event_object_schema = COALESCE(?, current_schema()) AND event_object_table = ANY(?::text[]) LIMIT 1`,
+			args: [
+				schema,
+				tables,
+				schema,
+				tables
 			]
-		});
-		await this.#db.createTable({
-			tableName: _mastra_core_storage.TABLE_KNOWLEDGE_CURSORS,
-			schema: _mastra_core_storage.KNOWLEDGE_CURSORS_SCHEMA,
-			compositePrimaryKey: ["sourceThreadId", "agent"]
-		});
-		await this.#db.createTable({
-			tableName: _mastra_core_storage.TABLE_KNOWLEDGE_ACTIVITY,
-			schema: _mastra_core_storage.KNOWLEDGE_ACTIVITY_SCHEMA
-		});
-		await this.#db.createTable({
-			tableName: _mastra_core_storage.TABLE_KNOWLEDGE_SEMANTIC_OUTBOX,
-			schema: _mastra_core_storage.KNOWLEDGE_SEMANTIC_OUTBOX_SCHEMA
-		});
-		await Promise.all(knowledgeIndexes(this.#schemaName).map((index) => this.#db.createIndexFromStatement(index.name, index.sql)));
+		})).rows.length > 0) 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() {
+		const tables = [...RETIRED_KNOWLEDGE_TABLE_NAMES, ...[...KNOWLEDGE_TABLE_NAMES].reverse()].map((table) => `"${table}"`).join(", ");
+		await this.#executor.execute(`DROP TABLE IF EXISTS ${tables}`);
+		await this.init();
+	}
+	async reconcileStructure(plan) {
+		return this.#transaction(async (tx) => {
+			await tx.execute({
+				sql: `SELECT pg_advisory_xact_lock(hashtext(?))`,
+				args: [`mastra-knowledge-reconcile:${this.#schemaName}`]
+			});
+			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,?,1,?,?)`,
+					args: [
+						id,
+						scope.name,
+						canonicalName(scope.name),
+						scope.kind ?? null,
+						scope.description ?? null,
+						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 INTO "${TABLE_KNOWLEDGE_NODE_SCOPES}" ("nodeId","scopeNodeId","addedAt") VALUES (?,?,?) ON CONFLICT DO NOTHING`,
+						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 INTO "${TABLE_KNOWLEDGE_SCOPE_GRANTS}" ("scopeNodeId","scopeRefId",role,"canSuggest") VALUES (?,?,?,?) ON CONFLICT DO NOTHING`,
+						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 COLLATE \"C\" > ? OR (n.name = ? AND n.id > ?))");
+			args.push(after.name, after.name, after.id);
+		}
+		args.push(limit + 1);
+		const rows = (await this.#readExecutor.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 COLLATE "C", n.id LIMIT ?`,
+			args
+		})).rows;
+		if (rows.length === 0) return {
+			scopes: [],
+			nextCursor: null
+		};
+		const parents = await this.#readExecutor.execute({
+			sql: `SELECT ns."nodeId",ns."scopeNodeId" FROM "${TABLE_KNOWLEDGE_NODE_SCOPES}" ns WHERE ns."nodeId" IN (${rows.map(() => "?").join(",")}) ORDER BY ns."scopeNodeId" COLLATE "C"`,
+			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 = postgresTimestamp(after.updatedAt);
+			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.#readExecutor.execute({
+			sql: `SELECT *, 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);
 		const scope = (0, _mastra_core_storage.canonicalizeKnowledgeScope)(input.scope);
@@ -8636,6 +9701,7 @@ var KnowledgePG = 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();
@@ -8652,7 +9718,7 @@ var KnowledgePG = 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",
@@ -8668,6 +9734,8 @@ var KnowledgePG = 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);
@@ -8684,13 +9752,13 @@ var KnowledgePG = class extends _mastra_core_storage.KnowledgeStorage {
 		return this.#resolveNode(this.#readExecutor, 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))}%`);
@@ -8742,6 +9810,7 @@ var KnowledgePG = 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)) {
@@ -8796,8 +9865,12 @@ var KnowledgePG = 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=?)`,
@@ -8837,10 +9910,10 @@ var KnowledgePG = 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 parent = await this.#resolveTerminalNode(tx, nodeReferenceId(input.node));
 			if (!parent) throw new _mastra_core_storage.KnowledgeNotFoundError("node", nodeReferenceId(input.node));
@@ -8853,11 +9926,10 @@ var KnowledgePG = 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,
@@ -8867,10 +9939,12 @@ var KnowledgePG = class extends _mastra_core_storage.KnowledgeStorage {
 					record.sourceThreadId,
 					record.capturedAt.toISOString(),
 					record.when?.toISOString() ?? null,
-					record.maxScope ?? null,
-					metadataJson
+					metadataJson,
+					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);
@@ -8897,17 +9971,13 @@ var KnowledgePG = 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.#readExecutor.execute({
-			sql: `SELECT *,scope AS "scopeJson" FROM "${_mastra_core_storage.TABLE_KNOWLEDGE_RECORDS}" WHERE sourceThreadId=? AND ${visibleSql}${input.includeDeleted ? "" : " AND deletedAt IS NULL"}${input.after ? " AND id > ?" : ""} ORDER BY id ASC LIMIT ?`,
+			sql: `SELECT *,scope AS "scopeJson" 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 {
@@ -8922,10 +9992,11 @@ var KnowledgePG = 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
 				]
 			});
@@ -8944,8 +10015,8 @@ var KnowledgePG = 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);
@@ -8961,15 +10032,17 @@ var KnowledgePG = 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);
@@ -8979,33 +10052,16 @@ var KnowledgePG = 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 scope = (0, _mastra_core_storage.canonicalizeKnowledgeScope)(input.scope);
-		const key = (0, _mastra_core_storage.knowledgeScopeKey)(scope);
+		const keys = visibleScopeKeys(scope);
 		const normalizedQuery = input.query.trim().toLocaleLowerCase();
 		if (!normalizedQuery) return [];
 		const query = `%${escapeLikePattern(normalizedQuery)}%`;
 		const results = (await this.#readExecutor.execute({
-			sql: `SELECT *,scope AS "scopeJson" FROM "${_mastra_core_storage.TABLE_KNOWLEDGE_NODES}" WHERE mergedInto IS NULL AND ${visibleSql} AND (canonicalName LIKE ? ESCAPE '=' OR lower(COALESCE(kind,'')) LIKE ? ESCAPE '=' OR lower(COALESCE(content,'')) LIKE ? ESCAPE '=' OR lower(COALESCE(description,'')) LIKE ? ESCAPE '=') ORDER BY updatedAt DESC LIMIT ?`,
+			sql: `SELECT *,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,
@@ -9026,10 +10082,9 @@ var KnowledgePG = class extends _mastra_core_storage.KnowledgeStorage {
 		}));
 		if (results.length < (input.limit ?? 20)) {
 			const records = await this.#readExecutor.execute({
-				sql: `SELECT f.*,f.scope AS "scopeJson",r.name,r.scope AS "parentScopeJson" FROM "${_mastra_core_storage.TABLE_KNOWLEDGE_RECORDS}" f JOIN "${_mastra_core_storage.TABLE_KNOWLEDGE_NODES}" r ON r.id=f.node AND r.type='node' AND r.mergedInto IS NULL WHERE f.deletedAt IS NULL AND ${visibleSql.replaceAll("scopeKey", "f.scopeKey")} AND lower(f.text) LIKE ? ESCAPE '=' ORDER BY f.id DESC LIMIT ?`,
+				sql: `SELECT f.*,f.scope AS "scopeJson",r.name,r.scope AS "parentScopeJson" FROM "${_mastra_core_storage.TABLE_KNOWLEDGE_RECORDS}" f JOIN "${_mastra_core_storage.TABLE_KNOWLEDGE_NODES}" r ON r.id=f.node AND r.type='node' AND r.mergedInto IS NULL WHERE f.deletedAt IS NULL AND ${visibleSql(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
 				]
@@ -9039,7 +10094,7 @@ var KnowledgePG = class extends _mastra_core_storage.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)
@@ -9048,41 +10103,26 @@ var KnowledgePG = class extends _mastra_core_storage.KnowledgeStorage {
 		}
 		return results;
 	}
-	async getCurationCursor(input) {
-		const row = (await this.#executor.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$1(row.updatedAt)
-		} : null;
-	}
-	async advanceCurationCursor(input) {
-		const updatedAt = /* @__PURE__ */ new Date();
-		if ((await this.#executor.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()
-			]
-		})).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.#readExecutor.execute({
-			sql: `SELECT *,scope AS "scopeJson" FROM "${_mastra_core_storage.TABLE_KNOWLEDGE_ACTIVITY}" WHERE ${visibleSql}${input.after ? " AND id < ?" : ""} ORDER BY id DESC LIMIT ?`,
+			sql: `SELECT *,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
 			]
@@ -9104,9 +10144,9 @@ var KnowledgePG = 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.#executor.execute({
@@ -9125,9 +10165,9 @@ var KnowledgePG = 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({
@@ -9194,12 +10234,14 @@ var KnowledgePG = 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 *,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;
 	}
@@ -9224,17 +10266,16 @@ var KnowledgePG = class extends _mastra_core_storage.KnowledgeStorage {
 		const scope = (0, _mastra_core_storage.canonicalizeKnowledgeScope)(input.scope);
 		const node = await this.#resolveTerminalNode(this.#readExecutor, nodeReferenceId(input.node));
 		if (!node) return { records: [] };
-		const key = (0, _mastra_core_storage.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.#readExecutor.execute({
-			sql: `SELECT DISTINCT f.*,f.scope AS "scopeJson" FROM "${_mastra_core_storage.TABLE_KNOWLEDGE_RECORDS}" f${relationship === "about" ? "" : ` LEFT JOIN "${_mastra_core_storage.TABLE_KNOWLEDGE_MENTIONS}" m ON m.sourceType='record' AND m.sourceId=f.id`} WHERE ${relationship === "about" ? "f.node=?" : relationship === "mentioning" ? "m.recordId=?" : "(f.node=? OR m.recordId=?)"} AND ${visibleSql.replaceAll("scopeKey", "f.scopeKey")}${input.includeDeleted ? "" : " AND f.deletedAt IS NULL"}${input.after ? " AND f.id < ?" : ""} ORDER BY f.id DESC LIMIT ?`,
+			sql: `SELECT DISTINCT f.*,f.scope AS "scopeJson" FROM "${_mastra_core_storage.TABLE_KNOWLEDGE_RECORDS}" f${relationship === "about" ? "" : ` LEFT JOIN "${_mastra_core_storage.TABLE_KNOWLEDGE_MENTIONS}" m ON m.sourceType='record' AND m.sourceId=f.id`} WHERE ${relationship === "about" ? "f.node=?" : relationship === "mentioning" ? "m.recordId=?" : "(f.node=? OR m.recordId=?)"} AND ${visibleSql(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;
@@ -9243,6 +10284,90 @@ var KnowledgePG = class extends _mastra_core_storage.KnowledgeStorage {
 			nextCursor: records.length > limit ? records[limit - 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 INTO "${TABLE_KNOWLEDGE_NODE_SCOPES}" (nodeId,scopeNodeId,addedAt) VALUES (?,?,?) ON CONFLICT DO NOTHING`,
+			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 INTO "${TABLE_KNOWLEDGE_NODE_SCOPES}" (nodeId,scopeNodeId,addedAt) VALUES (?,?,?) ON CONFLICT DO NOTHING`,
+			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 INTO "${TABLE_KNOWLEDGE_NODE_SCOPES}" ("nodeId","scopeNodeId","addedAt") VALUES (?,?,?) ON CONFLICT DO NOTHING`,
+				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 INTO "${TABLE_KNOWLEDGE_RECORD_SCOPES}" (recordId,scopeNodeId,addedAt) VALUES (?,?,?) ON CONFLICT DO NOTHING`,
+			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=?`,
@@ -9266,7 +10391,7 @@ var KnowledgePG = 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",
@@ -9280,6 +10405,7 @@ var KnowledgePG = 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);
 				}
@@ -9296,13 +10422,17 @@ var KnowledgePG = 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,
@@ -25062,7 +26192,10 @@ var PostgresStore = class extends _mastra_core_storage.MastraCompositeStore {
 				workflows: new WorkflowsPG(domainConfig),
 				workflowDefinitions: new WorkflowDefinitionsPG(domainConfig),
 				memory: new MemoryPG(domainConfig),
-				knowledge: new KnowledgePG(domainConfig),
+				knowledge: new KnowledgePG({
+					...domainConfig,
+					storageIsolationKey: config.storageIsolationKey ?? getPgKnowledgeIsolationKey(config)
+				}),
 				notifications: new NotificationsPG(domainConfig),
 				observability: new ObservabilityPG(domainConfig),
 				agents: new AgentsPG(domainConfig),
@@ -25116,7 +26249,7 @@ var PostgresStore = class extends _mastra_core_storage.MastraCompositeStore {
 			const pinned = new PinnedClientAdapter(this.#writePool, pinnedClient);
 			this.#db.pin(pinned);
 			this.#db.setSchemaSnapshot(await loadSchemaSnapshot(pinned, this.schema));
-			await super.init();
+			await Promise.all(Object.entries(this.stores).filter(([name, store]) => name !== "knowledge" && store).map(([, store]) => store.init()));
 			this.isInitialized = true;
 		} catch (error) {
 			this.#initPromise = null;