@mastra/mongodb 1.25.0-alpha.0 → 1.26.0-alpha.0

package/dist/index.cjs

@@ -5,12 +5,13 @@ let _mastra_core_storage = require("@mastra/core/storage");
 let _mastra_core_vector = require("@mastra/core/vector");
 let mongodb = require("mongodb");
 let _mastra_core_vector_filter = require("@mastra/core/vector/filter");
+let _mastra_core_features = require("@mastra/core/features");
 let crypto$1 = require("crypto");
 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");
 // package.json
-var version = "1.25.0-alpha.0";
+var version = "1.26.0-alpha.0";
 // src/vector/filter.ts
 /**
 * Translator for MongoDB filter queries.
@@ -4769,845 +4770,1953 @@ var MongoDBExperimentsStorage = class MongoDBExperimentsStorage extends _mastra_
 		} catch {}
 	}
 };
-// src/storage/domains/knowledge/index.ts
-let assertDescriptionWithinBound;
-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");
+const KNOWLEDGE_TABLE_NAMES = [
+	"mastra_knowledge_nodes",
+	"mastra_knowledge_records",
+	"mastra_knowledge_mentions",
+	"mastra_knowledge_activity",
+	"mastra_knowledge_semantic_outbox",
+	"mastra_knowledge_node_scopes",
+	"mastra_knowledge_record_scopes",
+	"mastra_knowledge_scope_grants",
+	"mastra_knowledge_access_state",
+	"mastra_knowledge_scope_addresses",
+	"mastra_knowledge_node_addresses",
+	"mastra_knowledge_import_state",
+	"mastra_knowledge_import_runs",
+	"mastra_knowledge_proposals"
+];
+/** Knowledge v1 tables with no v2 equivalent; an explicit schema reset drops them. */
+const RETIRED_KNOWLEDGE_TABLE_NAMES = ["mastra_knowledge_cursors"];
+const KNOWLEDGE_PAGES_CORE_FEATURE = "knowledge-pages";
+const KNOWLEDGE_PAGES_TABLE_NAMES = [
+	"mastra_knowledge_pages",
+	"mastra_knowledge_notes",
+	"mastra_knowledge_note_stamps",
+	"mastra_knowledge_mentions",
+	"mastra_knowledge_pins",
+	"mastra_knowledge_activity",
+	"mastra_knowledge_access_state"
+];
+/** Every Knowledge table any schema version created. Reset drops these and nothing else. */
+const KNOWLEDGE_RESETTABLE_TABLE_NAMES = [.../* @__PURE__ */ new Set([
+	...KNOWLEDGE_PAGES_TABLE_NAMES,
+	...KNOWLEDGE_TABLE_NAMES,
+	...RETIRED_KNOWLEDGE_TABLE_NAMES
+])];
+/** Schema-1/2 tables whose presence means the store needs a reset before schema 4 can run. */
+const LEGACY_KNOWLEDGE_TABLE_NAMES = new Set([...KNOWLEDGE_TABLE_NAMES, ...RETIRED_KNOWLEDGE_TABLE_NAMES].filter((name) => !KNOWLEDGE_PAGES_TABLE_NAMES.includes(name)));
+/**
+* Classifies what an adapter found before creating schema-4 tables. `tableNames` is every
+* `mastra_knowledge_*` table present; `schemaVersion` is the state row's version, if any.
+*/
+function inspectKnowledgePagesSchema(snapshot) {
+	const legacy = snapshot.tableNames.filter((name) => LEGACY_KNOWLEDGE_TABLE_NAMES.has(name));
+	if (legacy.length > 0) return {
+		status: "incompatible-reset-required",
+		schemaVersion: snapshot.schemaVersion ?? null,
+		reason: `found Knowledge tables from an earlier schema (${legacy.join(", ")})`
+	};
+	if (snapshot.schemaVersion === 4) return {
+		status: "compatible",
+		schemaVersion: 4
+	};
+	if (snapshot.schemaVersion === void 0) {
+		const present = snapshot.tableNames.filter((name) => KNOWLEDGE_PAGES_TABLE_NAMES.includes(name));
+		if (present.length === 0) return {
+			status: "uninitialized",
+			schemaVersion: null
+		};
+		return {
+			status: "incompatible-reset-required",
+			schemaVersion: null,
+			reason: `found Knowledge tables (${present.join(", ")}) without a schema version`
+		};
+	}
+	return {
+		status: "incompatible-reset-required",
+		schemaVersion: snapshot.schemaVersion,
+		reason: `Knowledge schema version ${snapshot.schemaVersion} is not 4`
+	};
+}
+/** Schema-2 table names schema 4 reuses with a different shape. */
+const REUSED_KNOWLEDGE_TABLE_NAMES = KNOWLEDGE_TABLE_NAMES.filter((name) => KNOWLEDGE_PAGES_TABLE_NAMES.includes(name));
+/**
+* The old Knowledge tables an adapter drops on init, rows included: Knowledge before schema 4 was an
+* experimental store with no migration. Every schema-1/2-only table present is dropped. The table
+* names schema 4 reuses (mentions, activity, the state table) are dropped too, but only when an old
+* table is present and no schema-4 state row exists, so they are old-shaped. Schema-4-only tables
+* are never listed. On a schema-4 store this lists only tables an older process recreated during a
+* rolling deploy. Drop order is safe for adapters that enforce references.
+*/
+function legacyKnowledgeTablesToDrop(snapshot) {
+	const present = new Set(snapshot.tableNames);
+	const legacy = [...LEGACY_KNOWLEDGE_TABLE_NAMES].filter((name) => present.has(name));
+	if (legacy.length === 0) return [];
+	const reused = snapshot.schemaVersion === 4 ? [] : REUSED_KNOWLEDGE_TABLE_NAMES.filter((name) => present.has(name));
+	const drop = /* @__PURE__ */ new Set([...legacy, ...reused]);
+	return [...RETIRED_KNOWLEDGE_TABLE_NAMES, ...[...KNOWLEDGE_TABLE_NAMES].reverse()].filter((name) => drop.has(name));
+}
+/** Message for the error an adapter throws on `incompatible-reset-required`. */
+function knowledgePagesResetMessage(reason) {
+	return `Knowledge storage needs a reset before this version can use it: ${reason}. Knowledge data has no migration; run \`await storage.stores?.knowledge?.dangerouslyReset()\` to drop the Knowledge tables (Memory tables are untouched).`;
+}
+const KNOWLEDGE_PAGES_CORE_FUNCTIONS = [
+	"assertKnowledgePageDescriptionWithinBound",
+	"assertKnowledgeNoteTextWithinBound",
+	"canonicalKnowledgeName",
+	"knowledgePositionBetween",
+	"KnowledgeMoveTooLargeError",
+	"KnowledgePageDepthError",
+	"KnowledgePageHasChildrenError",
+	"KnowledgePageKeyConflictError"
+];
+const KNOWLEDGE_PAGES_CORE_NUMBERS = [
+	"MAX_KNOWLEDGE_MOVE_PAGES",
+	"MAX_KNOWLEDGE_PAGE_DEPTH",
+	"MAX_KNOWLEDGE_PAGE_LIST_LIMIT"
+];
+function resolveKnowledgePagesCore(storageModule) {
+	const module = typeof storageModule === "object" && storageModule !== null ? storageModule : {};
+	const missing = [...KNOWLEDGE_PAGES_CORE_FUNCTIONS.filter((name) => typeof module[name] !== "function"), ...KNOWLEDGE_PAGES_CORE_NUMBERS.filter((name) => typeof module[name] !== "number")];
+	if (missing.length > 0) throw new Error(`@mastra/core advertises Knowledge pages without the required storage API (missing ${missing.join(", ")})`);
+	return module;
+}
+/** Loads core's page-store runtime once, after checking core advertises `knowledge-pages`. */
+function createKnowledgePagesCoreLoader(features, loadStorageModule) {
+	let core;
+	return async () => {
+		if (!features.has("knowledge-pages")) throw new Error(`Knowledge requires a @mastra/core release with the "${KNOWLEDGE_PAGES_CORE_FEATURE}" feature. Upgrade @mastra/core to use Knowledge; other storage domains keep working on this version.`);
+		core ??= loadStorageModule().then(resolveKnowledgePagesCore).catch((error) => {
+			core = void 0;
+			throw error;
 		});
-		assertDescriptionWithinBound = resolvedAssert;
-		assertWithinBound = resolvedAssert;
+		return core;
+	};
+}
+/**
+* Keyword-search words: the query split on whitespace, lowercased, deduplicated. Every word must
+* appear (as a case-insensitive substring) in a hit; an empty list means the search returns nothing.
+*/
+function knowledgeSearchWords(query) {
+	return [...new Set(query.toLowerCase().split(/\s+/).filter(Boolean))];
+}
+/**
+* Why `key` can't be a Knowledge page key, or undefined when it can. Keys are one path segment:
+* non-empty, with no `/` (path separator), `#` (scope/path separator) or `%` (escape character).
+*/
+function knowledgePageKeyProblem(key) {
+	if (!key) return "Knowledge page key must not be empty";
+	if (/[/#%]/.test(key)) return `Knowledge page key "${key}" must not contain "/", "#" or "%"`;
+}
+// src/storage/domains/knowledge/pages.ts
+const loadPagesCore = createKnowledgePagesCoreLoader(_mastra_core_features.coreFeatures, () => import("@mastra/core/storage"));
+const DEFAULT_LIST_LIMIT = 50;
+const MONGO_DUPLICATE_KEY = 11e3;
+const MONGO_KNOWLEDGE_PAGES_COLLECTIONS = {
+	pages: "mastra_knowledge_pages",
+	notes: "mastra_knowledge_notes",
+	pins: "mastra_knowledge_pins",
+	activity: "mastra_knowledge_activity",
+	state: "mastra_knowledge_access_state"
+};
+/** Thrown when existing Knowledge collections can't be used as schema 4 without a reset. */
+var MongoKnowledgeResetRequiredError = class extends Error {
+	inspection;
+	constructor(inspection) {
+		super(knowledgePagesResetMessage(inspection.reason));
+		this.name = "KnowledgeSchemaResetRequiredError";
+		this.inspection = inspection;
 	}
-	assertWithinBound(description);
+};
+function escapeRegex(value) {
+	return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
-let assertRecordTextWithinBound;
-async function assertKnowledgeRecordTextWithinBoundCompat(text) {
-	if (!assertRecordTextWithinBound) assertRecordTextWithinBound = (await import("@mastra/core/storage")).assertKnowledgeRecordTextWithinBound ?? ((value) => {
-		if (value.length > 1e3) throw new Error("Knowledge record text exceeds the 1000 UTF-16 code unit limit; split it into separate facts or summarize it");
-	});
-	assertRecordTextWithinBound(text);
+function isDuplicateKey(error) {
+	return typeof error === "object" && error !== null && error.code === MONGO_DUPLICATE_KEY;
+}
+function encodeCursor(parts) {
+	return Buffer.from(JSON.stringify(parts)).toString("base64url");
 }
-const cloneScope = (scope) => [...scope];
-const canonicalName = (name) => name.trim().toLocaleLowerCase();
-const nodeReferenceId = (node) => typeof node === "string" ? node : node.id;
-const sessionOptions = (session) => session ? { session } : {};
-function visibleScopeKeys(scope) {
-	const canonical = (0, _mastra_core_storage.canonicalizeKnowledgeScope)(scope);
-	const subsets = [[]];
-	for (const entry of canonical) subsets.push(...subsets.map((subset) => [...subset, entry]));
-	const keys = /* @__PURE__ */ new Set();
-	for (const subset of subsets.slice(1)) try {
-		keys.add((0, _mastra_core_storage.knowledgeScopeKey)(subset));
+function decodeCursor(cursor) {
+	try {
+		const parts = JSON.parse(Buffer.from(cursor, "base64url").toString("utf8"));
+		if (Array.isArray(parts) && parts.length === 2 && parts.every((part) => typeof part === "string")) return parts;
 	} catch {}
-	return [...keys];
+	throw new Error("Invalid Knowledge cursor");
+}
+function clampLimit(limit, max) {
+	const value = limit ?? DEFAULT_LIST_LIMIT;
+	if (!Number.isInteger(value) || value < 1) throw new Error("Knowledge list limit must be a positive integer");
+	return Math.min(value, max);
 }
-function recordCursorFilter(cursor, expected) {
-	const parsed = (0, _mastra_core_storage.parseKnowledgeNodeCursor)(cursor, expected);
-	return { $or: [{ updatedAt: { $lt: parsed.updatedAt } }, {
-		updatedAt: parsed.updatedAt,
-		$or: [{ name: { $gt: parsed.name } }, {
-			name: parsed.name,
-			id: { $gt: parsed.id }
-		}]
-	}] };
+const live = { deletedAt: { $exists: false } };
+const notScope = { isScope: { $ne: true } };
+/** Unique-while-live page key per parent; unset on delete so the key can be reused. */
+function activeKeyOf(parentId, key) {
+	return `${parentId}\u0000${key}`;
 }
-function nodeFromDocument(row) {
+/** Pipeline stage recomputing `activeKey` for pages that have a live key after their parent changed. */
+function recomputeActiveKey(parentId) {
+	return { $set: { activeKey: { $cond: [
+		{ $and: [{ $eq: [{ $type: "$key" }, "string"] }, { $eq: [{ $type: "$deletedAt" }, "missing"] }] },
+		{ $concat: [
+			parentId,
+			"\0",
+			"$key"
+		] },
+		"$$REMOVE"
+	] } } };
+}
+function toPage(row) {
 	return {
 		id: String(row.id),
-		type: "node",
+		scopeId: String(row.scopeId),
+		parentId: row.parentId == null ? null : String(row.parentId),
+		isScope: row.isScope === true,
+		...row.address == null ? {} : { address: String(row.address) },
+		...row.declaration == null ? {} : { declaration: String(row.declaration) },
+		...row.key == null ? {} : { key: String(row.key) },
+		position: String(row.position),
 		name: String(row.name),
-		kind: String(row.kind),
-		content: row.content == null ? void 0 : String(row.content),
-		description: row.description == null ? void 0 : String(row.description),
-		scope: cloneScope(row.scope),
+		...row.description == null ? {} : { description: String(row.description) },
+		...row.body == null ? {} : { body: String(row.body) },
 		version: Number(row.version),
-		mergedInto: row.mergedInto ?? void 0,
+		...row.mergedInto == null ? {} : { mergedInto: String(row.mergedInto) },
+		createdBy: row.createdBy,
+		updatedBy: row.updatedBy,
 		createdAt: new Date(row.createdAt),
-		updatedAt: new Date(row.updatedAt)
+		updatedAt: new Date(row.updatedAt),
+		...row.deletedAt == null ? {} : { deletedAt: new Date(row.deletedAt) },
+		...row.deletedBy == null ? {} : { deletedBy: String(row.deletedBy) }
 	};
 }
-function recordFromDocument(row) {
+function toNote(row) {
 	return {
 		id: String(row.id),
-		node: String(row.node),
+		pageId: String(row.pageId),
 		text: String(row.text),
-		scope: cloneScope(row.scope),
-		sourceThreadId: String(row.sourceThreadId),
-		capturedAt: new Date(row.capturedAt),
-		when: row.when ? new Date(row.when) : void 0,
-		metadata: row.metadata ?? void 0,
-		deletedAt: row.deletedAt ? new Date(row.deletedAt) : void 0,
-		deletedBy: row.deletedBy ?? void 0
+		...row.when == null ? {} : { when: new Date(row.when) },
+		stampScopeIds: [...row.stampScopeIds ?? []].sort(),
+		mentions: [...row.mentions ?? []].sort(),
+		provenance: row.provenance,
+		version: Number(row.version),
+		createdAt: new Date(row.createdAt),
+		updatedAt: new Date(row.updatedAt),
+		...row.deletedAt == null ? {} : { deletedAt: new Date(row.deletedAt) },
+		...row.deletedBy == null ? {} : { deletedBy: String(row.deletedBy) }
 	};
 }
-function outboxFromDocument(row) {
+function toListedPin(row) {
+	return {
+		...toPin(row),
+		pageName: String(row.pageName)
+	};
+}
+function toPin(row) {
 	return {
 		id: String(row.id),
-		idempotencyKey: String(row.idempotencyKey),
-		documentId: String(row.documentId),
-		documentType: row.documentType,
-		operation: row.operation,
-		scope: cloneScope(row.scope),
-		status: row.status,
-		attempts: Number(row.attempts),
-		availableAt: new Date(row.availableAt),
-		claimedAt: row.claimedAt ? new Date(row.claimedAt) : void 0,
-		claimedBy: row.claimedBy ?? void 0,
+		pageId: String(row.pageId),
+		audience: [...row.audience ?? []],
+		createdBy: String(row.createdBy),
 		createdAt: new Date(row.createdAt),
-		completedAt: row.completedAt ? new Date(row.completedAt) : void 0
+		updatedAt: new Date(row.updatedAt)
 	};
 }
-const KNOWLEDGE_CURATION_CURSOR_REMOVED_MESSAGE = "Knowledge curation cursors were removed: observation-time curate is the only Knowledge writer and needs no cursor.";
-var KnowledgeMongoDB = class KnowledgeMongoDB extends _mastra_core_storage.KnowledgeStorage {
-	static MANAGED_COLLECTIONS = [
-		_mastra_core_storage.TABLE_KNOWLEDGE_NODES,
-		_mastra_core_storage.TABLE_KNOWLEDGE_RECORDS,
-		_mastra_core_storage.TABLE_KNOWLEDGE_MENTIONS,
-		_mastra_core_storage.TABLE_KNOWLEDGE_ACTIVITY,
-		_mastra_core_storage.TABLE_KNOWLEDGE_SEMANTIC_OUTBOX
-	];
+const noProjection = { projection: { _id: 0 } };
+/**
+* MongoDB implementation of the schema-4 {@link KnowledgePageStore}.
+*
+* Notes embed their stamps and mentions and carry two denormalized copies of page scope
+* (`pageScopeId`, `mentionScopeIds`); activity events carry `pageScopeId`. Moves and merges rewrite
+* those copies in the same transaction as the page rows, so a read is one indexed filter against the
+* set of readable scope ids resolved from the read scope (never a per-address query).
+*/
+var MongoKnowledgePages = class {
 	#connector;
-	constructor(config) {
-		super();
-		this.#connector = resolveMongoDBConfig(config);
+	#bounds;
+	constructor(options) {
+		this.#connector = options.connector;
+		this.#bounds = options.bounds;
+	}
+	#c(name) {
+		return this.#connector.getCollection(MONGO_KNOWLEDGE_PAGES_COLLECTIONS[name]);
+	}
+	#tx(operation) {
+		return this.#connector.withTransaction(operation);
+	}
+	async inspectSchema() {
+		return inspectKnowledgePagesSchema(await this.#snapshot());
+	}
+	async #snapshot() {
+		const tableNames = [];
+		for (const name of KNOWLEDGE_RESETTABLE_TABLE_NAMES) if (await this.#connector.collectionExists(name)) tableNames.push(name);
+		let schemaVersion;
+		if (tableNames.includes(MONGO_KNOWLEDGE_PAGES_COLLECTIONS.state)) {
+			const state = await (await this.#c("state")).findOne({ id: "knowledge" });
+			schemaVersion = typeof state?.schemaVersion === "number" ? state.schemaVersion : void 0;
+		}
+		return {
+			tableNames,
+			schemaVersion
+		};
+	}
+	async #drop(name) {
+		const collection = await this.#connector.getCollection(name);
+		try {
+			await collection.drop();
+		} catch (error) {
+			if (error.codeName !== "NamespaceNotFound") throw error;
+		}
 	}
 	async init() {
-		const nodes = await this.#collection(_mastra_core_storage.TABLE_KNOWLEDGE_NODES);
-		const knowledge = await this.#collection(_mastra_core_storage.TABLE_KNOWLEDGE_RECORDS);
-		const mentions = await this.#collection(_mastra_core_storage.TABLE_KNOWLEDGE_MENTIONS);
-		const activity = await this.#collection(_mastra_core_storage.TABLE_KNOWLEDGE_ACTIVITY);
-		const outbox = await this.#collection(_mastra_core_storage.TABLE_KNOWLEDGE_SEMANTIC_OUTBOX);
+		const stateName = MONGO_KNOWLEDGE_PAGES_COLLECTIONS.state;
+		for (const name of legacyKnowledgeTablesToDrop(await this.#snapshot())) if (name === stateName) await (await this.#c("state")).deleteMany({ schemaVersion: { $ne: 4 } });
+		else await this.#drop(name);
+		await (await this.#c("state")).updateOne({ id: "knowledge" }, { $setOnInsert: {
+			id: "knowledge",
+			schemaVersion: 4
+		} }, { upsert: true });
+		const inspection = await this.inspectSchema();
+		if (inspection.status === "incompatible-reset-required") throw new MongoKnowledgeResetRequiredError(inspection);
+		const [pages, notes, pins, activity] = await Promise.all([
+			this.#c("pages"),
+			this.#c("notes"),
+			this.#c("pins"),
+			this.#c("activity")
+		]);
 		await Promise.all([
-			nodes.createIndex({
-				type: 1,
-				scopeKey: 1,
-				canonicalName: 1
-			}, { unique: true }),
-			nodes.createIndex({
-				scopeKey: 1,
-				type: 1
+			pages.createIndex({ id: 1 }, { unique: true }),
+			pages.createIndex({ address: 1 }, {
+				unique: true,
+				partialFilterExpression: { isScope: true }
 			}),
-			nodes.createIndex({
-				type: 1,
-				canonicalName: 1
+			pages.createIndex({ activeKey: 1 }, {
+				unique: true,
+				partialFilterExpression: { activeKey: { $type: "string" } }
 			}),
-			knowledge.createIndex({
-				node: 1,
-				id: -1
+			pages.createIndex({
+				parentId: 1,
+				position: 1,
+				id: 1
 			}),
-			knowledge.createIndex({
-				sourceThreadId: 1,
-				id: -1
+			pages.createIndex({
+				scopeId: 1,
+				name: 1,
+				id: 1
 			}),
-			knowledge.createIndex({
-				scopeKey: 1,
-				id: -1
+			pages.createIndex({
+				canonicalName: 1,
+				scopeId: 1
 			}),
-			mentions.createIndex({
-				sourceType: 1,
-				sourceId: 1,
-				recordId: 1
-			}, { unique: true }),
-			mentions.createIndex({
-				recordId: 1,
-				sourceType: 1,
-				sourceId: 1
+			pages.createIndex({
+				isScope: 1,
+				declaration: 1,
+				parentId: 1
 			}),
-			activity.createIndex({ id: -1 }),
+			notes.createIndex({ id: 1 }, { unique: true }),
+			notes.createIndex({
+				pageId: 1,
+				createdAt: 1,
+				id: 1
+			}),
+			notes.createIndex({ mentions: 1 }),
+			notes.createIndex({ pageScopeId: 1 }),
+			notes.createIndex({ stampScopeIds: 1 }),
+			pins.createIndex({ id: 1 }, { unique: true }),
+			pins.createIndex({ pageId: 1 }, { unique: true }),
+			pins.createIndex({ audience: 1 }),
+			activity.createIndex({ id: 1 }, { unique: true }),
 			activity.createIndex({
-				scopeKey: 1,
+				pageScopeId: 1,
+				createdAt: -1,
 				id: -1
 			}),
-			outbox.createIndex({ idempotencyKey: 1 }, { unique: true }),
-			outbox.createIndex({
-				status: 1,
-				availableAt: 1,
-				createdAt: 1
+			activity.createIndex({
+				pageId: 1,
+				createdAt: -1,
+				id: -1
 			})
 		]);
 	}
-	async dangerouslyClearAll() {
-		await this.#connector.withTransaction(async (session) => {
-			for (const name of KnowledgeMongoDB.MANAGED_COLLECTIONS) await (await this.#collection(name)).deleteMany({}, sessionOptions(session));
+	/** Drops exactly the Knowledge collections (never Memory's) and recreates schema 4. */
+	async reset() {
+		for (const name of KNOWLEDGE_RESETTABLE_TABLE_NAMES) await this.#drop(name);
+		await this.init();
+	}
+	/** The ids of every scope page the read scope can see; `null` means everything. */
+	async #readable(read, session) {
+		if (read === "all") return null;
+		const any = this.#readableClauses(read);
+		if (!any.length) return [];
+		return (await (await this.#c("pages")).find({
+			isScope: true,
+			$or: any
+		}, {
+			projection: {
+				_id: 0,
+				id: 1
+			},
+			session
+		}).toArray()).map((row) => String(row.id));
+	}
+	#readableClauses(read) {
+		const any = [];
+		if (read.addresses.length) any.push({ address: { $in: read.addresses } });
+		for (const entry of read.prefixes) any.push({
+			declaration: entry.declaration,
+			address: { $regex: `^${escapeRegex(entry.prefix)}` }
 		});
+		for (const entry of read.children) any.push({
+			declaration: entry.declaration,
+			parentId: entry.parentId
+		});
+		return any;
 	}
-	async createNode(input) {
-		await assertKnowledgeDescriptionWithinBoundCompat(input.description);
-		if (input.scopeAddresses?.length) {
-			const error = /* @__PURE__ */ new Error("This Knowledge storage adapter does not expose structural scope placement.");
-			error.name = "KnowledgeUnsupportedCapabilityError";
-			throw error;
+	/**
+	* Whether one scope page is readable, answered by a single indexed lookup instead of resolving the
+	* whole frontier. Use it when a call targets one scope; the frontier can be thousands of scopes.
+	*/
+	async #scopeReadable(read, scopeId) {
+		if (read === "all") return true;
+		const any = this.#readableClauses(read);
+		if (!any.length) return false;
+		return await (await this.#c("pages")).countDocuments({
+			id: scopeId,
+			isScope: true,
+			$or: any
+		}, { limit: 1 }) > 0;
+	}
+	#inScopes(field, ids) {
+		return ids === null ? {} : { [field]: { $in: ids } };
+	}
+	#visibleNotes(ids) {
+		if (ids === null) return {};
+		return {
+			pageScopeId: { $in: ids },
+			stampScopeIds: { $in: ids },
+			mentionScopeIds: { $not: { $elemMatch: { $nin: ids } } }
+		};
+	}
+	async #page(id, session) {
+		const row = await (await this.#c("pages")).findOne({ id }, {
+			...noProjection,
+			session
+		});
+		return row ? toPage(row) : null;
+	}
+	async #requireLivePage(id, session) {
+		const page = await this.#page(id, session);
+		if (!page || page.deletedAt) throw new _mastra_core_storage.KnowledgeNotFoundError("page", id);
+		return page;
+	}
+	async #log(session, event) {
+		await (await this.#c("activity")).insertOne({
+			id: (0, _mastra_core_storage.createKnowledgeUlid)(),
+			action: event.action,
+			scopeId: event.scopeId,
+			pageScopeId: event.pageScopeId ?? event.scopeId,
+			pageId: event.pageId,
+			...event.noteId ? { noteId: event.noteId } : {},
+			provenance: event.provenance,
+			createdAt: event.at
+		}, { session });
+	}
+	async #lastPosition(parentId, session) {
+		const row = await (await this.#c("pages")).find({
+			parentId,
+			...live
+		}, {
+			projection: {
+				_id: 0,
+				position: 1
+			},
+			session
+		}).sort({ position: -1 }).limit(1).next();
+		return row ? String(row.position) : void 0;
+	}
+	/**
+	* Ordinary descendants of `rootId`, level by level. Stops counting once the live total passes the
+	* move cap, so an oversize subtree is reported without being walked to the end.
+	*/
+	async #subtree(rootId, session, find) {
+		const core = await loadPagesCore();
+		const pages = await this.#c("pages");
+		const ids = [];
+		let liveCount = 0;
+		let maxDepth = 0;
+		let frontier = [rootId];
+		while (frontier.length) {
+			const rows = await pages.find({
+				parentId: { $in: frontier },
+				...notScope
+			}, {
+				projection: {
+					_id: 0,
+					id: 1,
+					depth: 1,
+					deletedAt: 1
+				},
+				session
+			}).toArray();
+			frontier = [];
+			for (const row of rows) {
+				const id = String(row.id);
+				if (find !== void 0 && id === find) return {
+					ids,
+					live: liveCount,
+					maxDepth,
+					found: true,
+					truncated: false
+				};
+				ids.push(id);
+				frontier.push(id);
+				if (row.deletedAt == null) {
+					liveCount++;
+					maxDepth = Math.max(maxDepth, Number(row.depth));
+				}
+			}
+			if (liveCount > core.MAX_KNOWLEDGE_MOVE_PAGES) return {
+				ids,
+				live: liveCount,
+				maxDepth,
+				found: false,
+				truncated: true
+			};
 		}
-		const scope = (0, _mastra_core_storage.canonicalizeKnowledgeScope)(input.scope);
-		return this.#connector.withTransaction(async (session) => {
-			const existing = await this.#getNodeByName(input.name, scope, session);
-			if (existing) {
-				const terminal = await this.#resolveTerminalNode(existing.id, session);
-				if (!(0, _mastra_core_storage.isKnowledgeScopeVisible)(terminal.scope, scope)) throw new Error(`Merged knowledge node is not visible from scope: ${input.name}`);
-				return terminal;
+		return {
+			ids,
+			live: liveCount,
+			maxDepth,
+			found: false,
+			truncated: false
+		};
+	}
+	/** Refuses before any write when a live arriving page's key is already live under `parentId`. */
+	async #assertNoKeyConflicts(keys, parentId, session, exceptId) {
+		const core = await loadPagesCore();
+		if (!keys.length) return;
+		const clash = await (await this.#c("pages")).findOne({
+			...live,
+			parentId,
+			key: { $in: keys },
+			...exceptId ? { id: { $ne: exceptId } } : {}
+		}, {
+			projection: {
+				_id: 0,
+				key: 1
+			},
+			session
+		});
+		if (clash) throw new core.KnowledgePageKeyConflictError(String(clash.key), parentId);
+	}
+	/** Recomputes the denormalized scope of every page a note mentions, for notes touching `pageIds`. */
+	async #refreshMentionScopes(pageIds, session) {
+		if (!pageIds.length) return;
+		const notes = await this.#c("notes");
+		const pages = await this.#c("pages");
+		const affected = await notes.find({ mentions: { $in: pageIds } }, {
+			projection: {
+				_id: 0,
+				id: 1,
+				mentions: 1
+			},
+			session
+		}).toArray();
+		for (const note of affected) {
+			const mentioned = await pages.find({ id: { $in: note.mentions } }, {
+				projection: {
+					_id: 0,
+					scopeId: 1
+				},
+				session
+			}).toArray();
+			await notes.updateOne({ id: note.id }, { $set: { mentionScopeIds: [...new Set(mentioned.map((page) => String(page.scopeId)))] } }, { session });
+		}
+	}
+	async materializeScope(input) {
+		for (let attempt = 0;; attempt++) try {
+			return await this.#materializeScopeOnce(input);
+		} catch (error) {
+			if (!(error instanceof (await loadPagesCore()).KnowledgePageKeyConflictError || error instanceof _mastra_core_storage.KnowledgeConflictError || isDuplicateKey(error) || error?.hasErrorLabel?.("TransientTransactionError")) || attempt >= 4) throw error;
+		}
+	}
+	async #materializeScopeOnce(input) {
+		const bounds = await this.#bounds();
+		bounds.assertKnowledgePageDescriptionWithinBound(input.description);
+		for (const child of input.children ?? []) bounds.assertKnowledgePageDescriptionWithinBound(child.description);
+		const checkTemplates = (templates) => {
+			for (const template of templates) {
+				bounds.assertKnowledgePageDescriptionWithinBound(template.description);
+				checkTemplates(template.pages ?? []);
 			}
+		};
+		checkTemplates(input.pages ?? []);
+		return this.#tx(async (session) => {
 			const now = /* @__PURE__ */ new Date();
-			const node = {
-				id: input.id ?? crypto.randomUUID(),
-				type: "node",
-				name: input.name.trim(),
-				kind: input.kind,
-				content: input.content,
-				description: input.description,
+			let scope = await this.#scopeByAddress(input.address, session);
+			let created = false;
+			let parentConflict;
+			if (!scope) {
+				if (input.parentId) await this.#requireLivePage(input.parentId, session);
+				scope = await this.#insertScope(session, {
+					address: input.address,
+					declaration: input.declaration,
+					name: input.name,
+					description: input.description,
+					parentId: input.parentId ?? null,
+					provenance: input.provenance,
+					at: now
+				});
+				created = true;
+			} else if (input.parentId && scope.parentId === null) {
+				await this.#requireLivePage(input.parentId, session);
+				const linked = await (await this.#c("pages")).findOneAndUpdate({
+					id: scope.id,
+					parentId: null
+				}, { $set: { parentId: input.parentId } }, {
+					returnDocument: "after",
+					projection: { _id: 0 },
+					session
+				});
+				scope = toPage(linked ?? await this.#scopeByAddress(input.address, session));
+				if (!linked && input.parentId !== scope.parentId) parentConflict = {
+					existingParentId: scope.parentId,
+					requestedParentId: input.parentId
+				};
+			} else if (input.parentId !== void 0 && (input.parentId ?? null) !== scope.parentId) parentConflict = {
+				existingParentId: scope.parentId,
+				requestedParentId: input.parentId ?? null
+			};
+			for (const child of input.children ?? []) {
+				if (await this.#scopeByAddress(child.address, session)) continue;
+				await this.#insertScope(session, {
+					address: child.address,
+					declaration: child.declaration,
+					name: child.name,
+					description: child.description,
+					parentId: scope.id,
+					provenance: input.provenance,
+					at: now
+				});
+			}
+			await this.#materializeTemplates(session, scope, input.pages ?? [], input.provenance, now);
+			return {
 				scope,
-				version: 1,
-				createdAt: now,
-				updatedAt: now
+				created,
+				...parentConflict ? { parentConflict } : {}
 			};
-			try {
-				await (await this.#nodes()).insertOne({
-					...node,
-					canonicalName: canonicalName(node.name),
-					scopeKey: (0, _mastra_core_storage.knowledgeScopeKey)(scope),
-					mergedInto: null
-				}, sessionOptions(session));
-			} catch (error) {
-				if (error.code !== 11e3) throw error;
-				const concurrent = await this.#getNodeByName(input.name, scope, session);
-				if (!concurrent) throw error;
-				return await this.#resolveTerminalNode(concurrent.id, session);
-			}
-			await this.#replaceMentions("node", node.id, node.content ?? "", input.resolutionScope ?? scope, scope, session);
-			await this.#activity("node-created", "node", node.id, scope, void 0, session);
-			await this.#outbox("node", node.id, "upsert", 1, scope, session);
-			return node;
 		});
 	}
-	async getNode(id) {
-		return this.#getNode(id);
+	async #materializeTemplates(session, parent, templates, provenance, at) {
+		const pages = await this.#c("pages");
+		for (const template of templates) {
+			const problem = knowledgePageKeyProblem(template.key);
+			if (problem) throw new Error(problem);
+			const existing = await pages.findOne({
+				parentId: parent.id,
+				key: template.key,
+				...live
+			}, {
+				...noProjection,
+				session
+			});
+			const page = existing ? toPage(existing) : await this.#insertPage(session, {
+				parent,
+				key: template.key,
+				name: template.name,
+				description: template.description,
+				provenance,
+				at
+			});
+			if (template.pages?.length) await this.#materializeTemplates(session, page, template.pages, provenance, at);
+		}
+	}
+	async #scopeByAddress(address, session) {
+		const row = await (await this.#c("pages")).findOne({
+			isScope: true,
+			address
+		}, {
+			...noProjection,
+			session
+		});
+		return row ? toPage(row) : null;
+	}
+	async #insertScope(session, input) {
+		const core = await loadPagesCore();
+		const id = (0, _mastra_core_storage.createKnowledgeUlid)();
+		const doc = {
+			id,
+			scopeId: id,
+			parentId: input.parentId,
+			isScope: true,
+			address: input.address,
+			declaration: input.declaration,
+			position: core.knowledgePositionBetween(await this.#lastPosition(input.parentId, session)),
+			name: input.name,
+			canonicalName: core.canonicalKnowledgeName(input.name),
+			...input.description === void 0 ? {} : { description: input.description },
+			depth: 0,
+			version: 1,
+			createdBy: input.provenance,
+			updatedBy: input.provenance,
+			createdAt: input.at,
+			updatedAt: input.at
+		};
+		try {
+			await (await this.#c("pages")).insertOne({ ...doc }, { session });
+		} catch (error) {
+			if (isDuplicateKey(error)) throw new _mastra_core_storage.KnowledgeConflictError(input.address);
+			throw error;
+		}
+		await this.#log(session, {
+			action: "scope-created",
+			scopeId: id,
+			pageId: id,
+			provenance: input.provenance,
+			at: input.at
+		});
+		return toPage(doc);
+	}
+	async getScopesByAddress(addresses) {
+		if (addresses.length === 0) return [];
+		const rows = await (await this.#c("pages")).find({
+			isScope: true,
+			address: { $in: addresses }
+		}, noProjection).toArray();
+		const byAddress = new Map(rows.map((row) => [String(row.address), toPage(row)]));
+		return [...new Set(addresses)].flatMap((address) => byAddress.get(address) ?? []);
+	}
+	async listScopeDeclarations() {
+		return (await (await this.#c("pages")).aggregate([{ $match: {
+			isScope: true,
+			declaration: { $type: "string" }
+		} }, { $group: {
+			_id: "$declaration",
+			scopes: { $sum: 1 }
+		} }]).toArray()).map((row) => ({
+			declaration: String(row._id),
+			scopes: Number(row.scopes)
+		})).sort((a, b) => a.declaration < b.declaration ? -1 : a.declaration > b.declaration ? 1 : 0);
+	}
+	async renameScopeDeclaration(input) {
+		return this.#tx(async (session) => {
+			const pages = await this.#c("pages");
+			const rows = await pages.find({
+				isScope: true,
+				$or: [{ declaration: input.from }, { declaration: { $regex: `^${escapeRegex(`${input.from}/`)}` } }]
+			}, {
+				projection: {
+					_id: 0,
+					id: 1,
+					address: 1,
+					declaration: 1
+				},
+				session
+			}).toArray();
+			if (rows.length === 0) return 0;
+			const renames = rows.map((row) => ({
+				address: String(row.address),
+				from: String(row.declaration),
+				to: input.to + String(row.declaration).slice(input.from.length)
+			}));
+			input.check(renames);
+			if ((await pages.bulkWrite(rows.map((row, index) => ({ updateOne: {
+				filter: {
+					id: row.id,
+					isScope: true
+				},
+				update: { $set: { declaration: renames[index].to } }
+			} })), { session })).matchedCount < rows.length) throw new _mastra_core_storage.KnowledgeConflictError("Knowledge scope declarations changed while renaming; retry the rename");
+			return rows.length;
+		});
+	}
+	async listChildScopes(input) {
+		const core = await loadPagesCore();
+		const limit = clampLimit(input.limit, core.MAX_KNOWLEDGE_PAGE_LIST_LIMIT);
+		const filter = {
+			isScope: true,
+			parentId: input.parentId,
+			...live
+		};
+		if (input.cursor) {
+			const [position, id] = decodeCursor(input.cursor);
+			filter.$or = [{ position: { $gt: position } }, {
+				position,
+				id: { $gt: id }
+			}];
+		}
+		const rows = await (await this.#c("pages")).find(filter, noProjection).sort({
+			position: 1,
+			id: 1
+		}).limit(limit + 1).toArray();
+		return this.#pageOutput(rows, limit, (page) => [page.position, page.id]);
+	}
+	#pageOutput(rows, limit, cursorOf) {
+		const pages = rows.slice(0, limit).map(toPage);
+		const last = pages[pages.length - 1];
+		return {
+			pages,
+			...rows.length > limit && last ? { nextCursor: encodeCursor(cursorOf(last)) } : {}
+		};
+	}
+	async getPage(input) {
+		const row = await (await this.#c("pages")).findOne({ id: input.id }, noProjection);
+		return row && await this.#scopeReadable(input.read, String(row.scopeId)) ? toPage(row) : null;
+	}
+	async getPageByPath(input) {
+		if (!input.path.length) return null;
+		if (!await this.#scopeReadable(input.read, input.scopeId)) return null;
+		const pages = await this.#c("pages");
+		let page;
+		let parentId = input.scopeId;
+		for (const key of input.path) {
+			const row = await pages.findOne({
+				parentId,
+				key,
+				scopeId: input.scopeId,
+				...live,
+				...notScope
+			}, noProjection);
+			if (!row) return null;
+			page = toPage(row);
+			parentId = page.id;
+		}
+		return page ?? null;
+	}
+	async findPagesByName(input) {
+		const core = await loadPagesCore();
+		const limit = clampLimit(input.limit, core.MAX_KNOWLEDGE_PAGE_LIST_LIMIT);
+		const filter = {
+			canonicalName: core.canonicalKnowledgeName(input.name),
+			...live
+		};
+		if (!await this.#scopeFilter(filter, input.read, input.scopeId)) return [];
+		return (await (await this.#c("pages")).find(filter, noProjection).sort({
+			createdAt: -1,
+			id: -1
+		}).limit(limit).toArray()).map(toPage);
 	}
-	async getNodeByName(input) {
-		return this.#getNodeByName(input.name, (0, _mastra_core_storage.canonicalizeKnowledgeScope)(input.scope));
+	/**
+	* Adds the home-scope constraint: the explicit scope when given (one indexed readability check),
+	* otherwise the readable frontier. Returns false when nothing can match.
+	*/
+	async #scopeFilter(filter, read, scopeId) {
+		if (scopeId !== void 0) {
+			if (!await this.#scopeReadable(read, scopeId)) return false;
+			filter.scopeId = scopeId;
+			return true;
+		}
+		const ids = await this.#readable(read);
+		if (ids !== null) filter.scopeId = { $in: ids };
+		return true;
 	}
-	async resolveNode(input) {
-		return this.#resolveNode(input.name, (0, _mastra_core_storage.canonicalizeKnowledgeScope)(input.scope));
+	async listChildPages(input) {
+		const core = await loadPagesCore();
+		const limit = clampLimit(input.limit, core.MAX_KNOWLEDGE_PAGE_LIST_LIMIT);
+		const ids = await this.#readable(input.read);
+		const filter = {
+			parentId: input.parentId,
+			...notScope,
+			...live,
+			...this.#inScopes("scopeId", ids)
+		};
+		if (input.cursor) {
+			const [position, id] = decodeCursor(input.cursor);
+			filter.$or = [{ position: { $gt: position } }, {
+				position,
+				id: { $gt: id }
+			}];
+		}
+		const rows = await (await this.#c("pages")).find(filter, noProjection).sort({
+			position: 1,
+			id: 1
+		}).limit(limit + 1).toArray();
+		return this.#pageOutput(rows, limit, (page) => [page.position, page.id]);
 	}
-	async listNodes(input) {
+	async listPages(input) {
+		const core = await loadPagesCore();
+		const limit = clampLimit(input.limit, core.MAX_KNOWLEDGE_PAGE_LIST_LIMIT);
 		const filter = {
-			type: "node",
-			mergedInto: null,
-			scopeKey: { $in: visibleScopeKeys((0, _mastra_core_storage.canonicalizeKnowledgeScope)(input.scope)) },
-			...input.namePrefix ? { canonicalName: { $regex: `^${this.#escapeRegex(canonicalName(input.namePrefix))}` } } : {},
-			...input.kind ? { kind: input.kind } : {},
-			...input.hasContent === void 0 ? {} : input.hasContent ? { content: {
-				$exists: true,
-				$nin: [null, ""]
-			} } : { $or: [
-				{ content: { $exists: false } },
-				{ content: null },
-				{ content: "" }
-			] },
-			...input.cursor ? recordCursorFilter(input.cursor, {
-				namePrefix: input.namePrefix,
-				kind: input.kind,
-				hasContent: input.hasContent
-			}) : {}
+			...notScope,
+			...live
 		};
-		return (await (await this.#nodes()).find(filter).sort({
-			updatedAt: -1,
+		if (!await this.#scopeFilter(filter, input.read, input.scopeId)) return { pages: [] };
+		if (input.namePrefix) filter.canonicalName = { $regex: `^${escapeRegex(core.canonicalKnowledgeName(input.namePrefix))}` };
+		if (input.cursor) {
+			const [name, id] = decodeCursor(input.cursor);
+			filter.$or = [{ name: { $gt: name } }, {
+				name,
+				id: { $gt: id }
+			}];
+		}
+		const rows = await (await this.#c("pages")).find(filter, noProjection).sort({
 			name: 1,
 			id: 1
-		}).limit(input.limit ?? 100).toArray()).map(nodeFromDocument);
+		}).limit(limit + 1).toArray();
+		return this.#pageOutput(rows, limit, (page) => [page.name, page.id]);
+	}
+	async createPage(input) {
+		(await this.#bounds()).assertKnowledgePageDescriptionWithinBound(input.description);
+		if (input.key !== void 0) {
+			const problem = knowledgePageKeyProblem(input.key);
+			if (problem) throw new Error(problem);
+		}
+		return this.#tx(async (session) => {
+			const parent = await this.#requireLivePage(input.parentId, session);
+			return this.#insertPage(session, {
+				id: input.id,
+				parent,
+				key: input.key,
+				name: input.name,
+				description: input.description,
+				body: input.body,
+				position: input.position,
+				provenance: input.provenance,
+				at: /* @__PURE__ */ new Date()
+			});
+		});
 	}
-	async updateNode(input) {
-		await assertKnowledgeDescriptionWithinBoundCompat(input.description);
-		return this.#connector.withTransaction(async (session) => {
-			const existing = await this.#getNode(input.id, session);
-			if (!existing) throw new _mastra_core_storage.KnowledgeNotFoundError("node", input.id);
-			if (existing.mergedInto) throw new Error(`Cannot update merged knowledge node: ${input.id}`);
-			const scope = input.scope ? (0, _mastra_core_storage.canonicalizeKnowledgeScope)(input.scope) : existing.scope;
-			const name = input.name?.trim() ?? existing.name;
-			const content = input.content ?? existing.content;
-			const description = input.description ?? existing.description;
+	async #insertPage(session, input) {
+		const core = await loadPagesCore();
+		const id = input.id ?? (0, _mastra_core_storage.createKnowledgeUlid)();
+		const scopeId = input.parent.isScope ? input.parent.id : input.parent.scopeId;
+		const depth = input.parent.isScope ? 1 : await this.#depthOf(input.parent.id, session) + 1;
+		if (depth > core.MAX_KNOWLEDGE_PAGE_DEPTH) throw new core.KnowledgePageDepthError(id);
+		const doc = {
+			id,
+			scopeId,
+			parentId: input.parent.id,
+			isScope: false,
+			...input.key === void 0 ? {} : {
+				key: input.key,
+				activeKey: activeKeyOf(input.parent.id, input.key)
+			},
+			position: input.position ?? core.knowledgePositionBetween(await this.#lastPosition(input.parent.id, session)),
+			name: input.name,
+			canonicalName: core.canonicalKnowledgeName(input.name),
+			...input.description === void 0 ? {} : { description: input.description },
+			...input.body === void 0 ? {} : { body: input.body },
+			depth,
+			version: 1,
+			createdBy: input.provenance,
+			updatedBy: input.provenance,
+			createdAt: input.at,
+			updatedAt: input.at
+		};
+		try {
+			await (await this.#c("pages")).insertOne({ ...doc }, { session });
+		} catch (error) {
+			if (isDuplicateKey(error)) {
+				if (input.key) throw new core.KnowledgePageKeyConflictError(input.key, input.parent.id);
+				throw new _mastra_core_storage.KnowledgeConflictError(id);
+			}
+			throw error;
+		}
+		await this.#log(session, {
+			action: "page-created",
+			scopeId,
+			pageId: id,
+			provenance: input.provenance,
+			at: input.at
+		});
+		return toPage(doc);
+	}
+	async #depthOf(id, session) {
+		const row = await (await this.#c("pages")).findOne({ id }, {
+			projection: {
+				_id: 0,
+				depth: 1
+			},
+			session
+		});
+		return Number(row?.depth ?? 0);
+	}
+	async updatePage(input) {
+		const core = await loadPagesCore();
+		(await this.#bounds()).assertKnowledgePageDescriptionWithinBound(input.description);
+		return this.#tx(async (session) => {
+			const page = await this.#requireLivePage(input.id, session);
+			if (page.version !== input.expectedVersion) throw new _mastra_core_storage.KnowledgeConflictError(input.id);
 			const now = /* @__PURE__ */ new Date();
-			const result = await (await this.#nodes()).findOneAndUpdate({
+			const set = {
+				updatedAt: now,
+				updatedBy: input.provenance
+			};
+			const unset = {};
+			if (input.name !== void 0) {
+				set.name = input.name;
+				set.canonicalName = core.canonicalKnowledgeName(input.name);
+			}
+			if (input.description !== void 0) {
+				if (input.description === "") unset.description = "";
+				else set.description = input.description;
+			}
+			if (input.body !== void 0) set.body = input.body;
+			const updated = await (await this.#c("pages")).findOneAndUpdate({
 				id: input.id,
-				type: "node",
-				version: input.version
+				version: input.expectedVersion,
+				...live
 			}, {
-				$set: {
-					name,
-					canonicalName: canonicalName(name),
-					kind: input.kind ?? existing.kind,
-					content: content ?? null,
-					description: description ?? null,
-					scope,
-					scopeKey: (0, _mastra_core_storage.knowledgeScopeKey)(scope),
-					updatedAt: now
-				},
-				$inc: { version: 1 }
+				$set: set,
+				$inc: { version: 1 },
+				...Object.keys(unset).length ? { $unset: unset } : {}
 			}, {
-				...sessionOptions(session),
-				returnDocument: "after"
+				returnDocument: "after",
+				projection: { _id: 0 },
+				session
 			});
-			if (!result) throw new _mastra_core_storage.KnowledgeConflictError(input.id);
-			if (input.content !== void 0 || input.name !== void 0 || input.scope !== void 0) await this.#replaceMentions("node", input.id, content ?? "", input.resolutionScope ?? scope, scope, session);
-			if ((0, _mastra_core_storage.knowledgeScopeKey)(scope) !== (0, _mastra_core_storage.knowledgeScopeKey)(existing.scope)) {
-				await this.#outbox("node", input.id, "delete", (0, _mastra_core_storage.createKnowledgeUlid)(), existing.scope, session);
-				const records = await (await this.#knowledge()).find({ node: input.id }, sessionOptions(session)).toArray();
-				for (const record of records) {
-					await this.#outbox("record", record.id, "delete", (0, _mastra_core_storage.createKnowledgeUlid)(), record.scope, session);
-					if (!record.deletedAt) await this.#outbox("record", record.id, "upsert", (0, _mastra_core_storage.createKnowledgeUlid)(), record.scope, session);
-				}
+			if (!updated) throw new _mastra_core_storage.KnowledgeConflictError(input.id);
+			await this.#log(session, {
+				action: "page-updated",
+				scopeId: page.scopeId,
+				pageId: page.id,
+				provenance: input.provenance,
+				at: now
+			});
+			return toPage(updated);
+		});
+	}
+	/** Rewrites everything that follows a page's home scope to `scopeId`, for the pages in `moved`. */
+	async #rehome(moved, scopeId, depthDelta, session) {
+		const pages = await this.#c("pages");
+		const descendants = moved.slice(1);
+		if (descendants.length) await pages.updateMany({ id: { $in: descendants } }, [{ $set: {
+			scopeId,
+			depth: { $add: ["$depth", depthDelta] }
+		} }], { session });
+		await (await this.#c("notes")).updateMany({ pageId: { $in: moved } }, { $set: { pageScopeId: scopeId } }, { session });
+		await (await this.#c("activity")).updateMany({ pageId: { $in: moved } }, { $set: { pageScopeId: scopeId } }, { session });
+	}
+	async movePage(input) {
+		const core = await loadPagesCore();
+		return this.#tx(async (session) => {
+			const page = await this.#requireLivePage(input.id, session);
+			if (page.version !== input.expectedVersion) throw new _mastra_core_storage.KnowledgeConflictError(input.id);
+			if (page.isScope) throw new Error(`Knowledge scope page ${input.id} can't be moved`);
+			if (input.parentId === input.id) throw new Error(`Knowledge page ${input.id} can't move under itself or its own subtree`);
+			const tree = await this.#subtree(input.id, session, input.parentId);
+			if (tree.found) throw new Error(`Knowledge page ${input.id} can't move under itself or its own subtree`);
+			const parent = await this.#requireLivePage(input.parentId, session);
+			if (tree.live + 1 > core.MAX_KNOWLEDGE_MOVE_PAGES) throw new core.KnowledgeMoveTooLargeError(input.id, tree.live + 1);
+			const newScopeId = parent.isScope ? parent.id : parent.scopeId;
+			const newDepth = parent.isScope ? 1 : await this.#depthOf(parent.id, session) + 1;
+			const delta = newDepth - await this.#depthOf(page.id, session);
+			if (page.key) await this.#assertNoKeyConflicts([page.key], parent.id, session, page.id);
+			if (tree.maxDepth + delta > core.MAX_KNOWLEDGE_PAGE_DEPTH || newDepth > core.MAX_KNOWLEDGE_PAGE_DEPTH) throw new core.KnowledgePageDepthError(input.id);
+			const position = input.position ?? core.knowledgePositionBetween(await this.#lastPosition(parent.id, session));
+			const now = /* @__PURE__ */ new Date();
+			let updated;
+			try {
+				await this.#rehome([page.id, ...tree.ids], newScopeId, delta, session);
+				updated = await (await this.#c("pages")).findOneAndUpdate({
+					id: input.id,
+					version: input.expectedVersion
+				}, {
+					$set: {
+						parentId: parent.id,
+						scopeId: newScopeId,
+						...page.key ? { activeKey: activeKeyOf(parent.id, page.key) } : {},
+						depth: newDepth,
+						position,
+						updatedAt: now,
+						updatedBy: input.provenance
+					},
+					$inc: { version: 1 }
+				}, {
+					returnDocument: "after",
+					projection: { _id: 0 },
+					session
+				});
+			} catch (error) {
+				if (isDuplicateKey(error)) throw new _mastra_core_storage.KnowledgeConflictError(page.key ? `${parent.id}#${page.key}` : input.id);
+				throw error;
 			}
-			await this.#activity("node-updated", "node", input.id, scope, void 0, session);
-			await this.#outbox("node", input.id, "upsert", Number(result.version), scope, session);
-			return nodeFromDocument(result);
+			if (!updated) throw new _mastra_core_storage.KnowledgeConflictError(input.id);
+			await this.#refreshMentionScopes([page.id, ...tree.ids], session);
+			await this.#log(session, {
+				action: "page-moved",
+				scopeId: newScopeId,
+				pageId: input.id,
+				provenance: input.provenance,
+				at: now
+			});
+			return toPage(updated);
 		});
 	}
-	async mergeNodes(input) {
-		if (input.sourceId === input.targetId) throw new Error("Cannot merge a knowledge node into itself");
-		return this.#connector.withTransaction(async (session) => {
-			const source = await this.#getNode(input.sourceId, session);
-			if (!source) throw new _mastra_core_storage.KnowledgeNotFoundError("node", input.sourceId);
-			const target = await this.#resolveTerminalNode(input.targetId, session);
-			if (!target) throw new _mastra_core_storage.KnowledgeNotFoundError("node", input.targetId);
-			if (target.id === source.id) throw new Error("Cannot create a knowledge merge cycle");
-			if (!(0, _mastra_core_storage.isKnowledgeScopeVisible)(target.scope, source.scope)) throw new Error("Cannot merge a knowledge node into a target that is narrower than its source scope");
-			const mentions = await this.#mentions();
-			const affected = await mentions.find({ recordId: source.id }, sessionOptions(session)).toArray();
-			const movedFacts = await (await this.#knowledge()).find({ node: source.id }, sessionOptions(session)).toArray();
-			if ((await (await this.#nodes()).updateOne({
+	async mergePages(input) {
+		const core = await loadPagesCore();
+		return this.#tx(async (session) => {
+			if (input.sourceId === input.targetId) throw new Error(`Knowledge page ${input.sourceId} can't merge into itself or its own subtree`);
+			const source = await this.#requireLivePage(input.sourceId, session);
+			const target = await this.#requireLivePage(input.targetId, session);
+			if (source.version !== input.sourceVersion) throw new _mastra_core_storage.KnowledgeConflictError(input.sourceId);
+			if (source.isScope || target.isScope) throw new Error("Knowledge scope pages can't be merged");
+			const tree = await this.#subtree(source.id, session, target.id);
+			if (tree.found) throw new Error(`Knowledge page ${source.id} can't merge into itself or its own subtree`);
+			if (tree.live > core.MAX_KNOWLEDGE_MOVE_PAGES) throw new core.KnowledgeMoveTooLargeError(source.id, tree.live);
+			const delta = await this.#depthOf(target.id, session) - await this.#depthOf(source.id, session);
+			const arriving = await (await this.#c("pages")).find({
+				parentId: source.id,
+				...live,
+				...notScope,
+				key: { $type: "string" }
+			}, {
+				projection: {
+					_id: 0,
+					key: 1
+				},
+				session
+			}).toArray();
+			await this.#assertNoKeyConflicts(arriving.map((row) => String(row.key)), target.id, session, source.id);
+			if (tree.maxDepth > 0 && tree.maxDepth + delta > core.MAX_KNOWLEDGE_PAGE_DEPTH) throw new core.KnowledgePageDepthError(source.id);
+			const now = /* @__PURE__ */ new Date();
+			const pages = await this.#c("pages");
+			const notes = await this.#c("notes");
+			if ((await pages.updateOne({
 				id: source.id,
-				type: "node",
-				version: input.sourceVersion,
-				mergedInto: null
+				version: input.sourceVersion
 			}, {
 				$set: {
+					deletedAt: now,
+					deletedBy: input.provenance.author,
 					mergedInto: target.id,
-					updatedAt: /* @__PURE__ */ new Date()
+					scopeId: target.scopeId,
+					updatedAt: now,
+					updatedBy: input.provenance
 				},
+				$unset: { activeKey: "" },
 				$inc: { version: 1 }
-			}, sessionOptions(session))).modifiedCount === 0) throw new _mastra_core_storage.KnowledgeConflictError(source.id);
-			await (await this.#knowledge()).updateMany({ node: source.id }, { $set: { node: target.id } }, sessionOptions(session));
-			for (const mention of affected) if (await mentions.findOne({
-				sourceType: mention.sourceType,
-				sourceId: mention.sourceId,
-				recordId: target.id
-			}, sessionOptions(session))) await mentions.deleteOne({ _id: mention._id }, sessionOptions(session));
-			else await mentions.updateOne({ _id: mention._id }, { $set: { recordId: target.id } }, sessionOptions(session));
-			for (const record of movedFacts) if (!record.deletedAt) await this.#outbox("record", record.id, "upsert", (0, _mastra_core_storage.createKnowledgeUlid)(), record.scope, session);
-			for (const mention of affected) {
-				const scope = mention.sourceType === "record" ? (await (await this.#knowledge()).findOne({ id: mention.sourceId }, sessionOptions(session)))?.scope : (await (await this.#nodes()).findOne({
-					id: mention.sourceId,
-					type: "node"
-				}, sessionOptions(session)))?.scope;
-				if (scope) await this.#outbox(mention.sourceType, mention.sourceId, "upsert", (0, _mastra_core_storage.createKnowledgeUlid)(), scope, session);
+			}, { session })).matchedCount === 0) throw new _mastra_core_storage.KnowledgeConflictError(input.sourceId);
+			try {
+				if (tree.ids.length) {
+					await pages.updateMany({ id: { $in: tree.ids } }, [{ $set: {
+						scopeId: target.scopeId,
+						depth: { $add: ["$depth", delta] }
+					} }], { session });
+					await notes.updateMany({ pageId: { $in: tree.ids } }, { $set: { pageScopeId: target.scopeId } }, { session });
+					await (await this.#c("activity")).updateMany({ pageId: { $in: tree.ids } }, { $set: { pageScopeId: target.scopeId } }, { session });
+				}
+				await pages.updateMany({
+					parentId: source.id,
+					...notScope
+				}, [{ $set: { parentId: target.id } }, recomputeActiveKey(target.id)], { session });
+			} catch (error) {
+				if (isDuplicateKey(error)) throw new _mastra_core_storage.KnowledgeConflictError(source.id);
+				throw error;
 			}
-			let mergedTarget = target;
-			if (target.description === void 0 && source.description) {
-				const adoptedAt = /* @__PURE__ */ new Date();
-				if ((await (await this.#nodes()).updateOne({
-					id: target.id,
-					type: "node",
-					version: target.version,
-					description: null
-				}, {
-					$set: {
-						description: source.description,
-						updatedAt: adoptedAt
-					},
-					$inc: { version: 1 }
-				}, sessionOptions(session))).modifiedCount > 0) {
-					mergedTarget = {
-						...target,
-						description: source.description,
-						version: target.version + 1,
-						updatedAt: adoptedAt
-					};
-					await this.#activity("node-updated", "node", target.id, target.scope, void 0, session);
-				}
+			await notes.updateMany({ pageId: source.id }, { $set: {
+				pageId: target.id,
+				pageScopeId: target.scopeId
+			} }, { session });
+			await notes.updateMany({ mentions: source.id }, [{ $set: { mentions: { $setUnion: [{ $map: {
+				input: "$mentions",
+				in: { $cond: [
+					{ $eq: ["$$this", source.id] },
+					target.id,
+					"$$this"
+				] }
+			} }] } } }], { session });
+			await this.#refreshMentionScopes([target.id, ...tree.ids], session);
+			const pins = await this.#c("pins");
+			const sourcePin = await pins.findOne({ pageId: source.id }, {
+				...noProjection,
+				session
+			});
+			if (sourcePin) {
+				await this.#upsertPinAudience(session, target.id, sourcePin.audience ?? [], String(sourcePin.createdBy), now);
+				await pins.deleteOne({ id: sourcePin.id }, { session });
 			}
-			await this.#activity("node-merged", "node", source.id, source.scope, void 0, session);
-			await this.#outbox("node", source.id, "delete", input.sourceVersion + 1, source.scope, session);
-			await this.#outbox("node", target.id, "upsert", (0, _mastra_core_storage.createKnowledgeUlid)(), mergedTarget.scope, session);
-			return mergedTarget;
+			await (await this.#c("activity")).updateMany({ pageId: source.id }, { $set: { pageScopeId: target.scopeId } }, { session });
+			await this.#log(session, {
+				action: "page-merged",
+				scopeId: target.scopeId,
+				pageScopeId: target.scopeId,
+				pageId: source.id,
+				provenance: input.provenance,
+				at: now
+			});
+			return await this.#page(target.id, session);
 		});
 	}
-	async appendKnowledge(input) {
-		await assertKnowledgeRecordTextWithinBoundCompat(input.text);
-		const scope = (0, _mastra_core_storage.canonicalizeKnowledgeScope)(input.scope);
-		const defaultScope = (0, _mastra_core_storage.canonicalizeKnowledgeScope)(input.defaultScope);
-		return this.#connector.withTransaction(async (session) => {
-			const parent = await this.#resolveTerminalNode(nodeReferenceId(input.node), session);
-			if (!parent) throw new _mastra_core_storage.KnowledgeNotFoundError("node", nodeReferenceId(input.node));
-			const id = input.id ?? (0, _mastra_core_storage.createKnowledgeUlid)();
-			const existing = await (await this.#knowledge()).findOne({ id }, sessionOptions(session));
-			if (existing) return recordFromDocument(existing);
-			const record = {
-				id,
-				node: parent.id,
-				text: input.text,
-				scope,
-				sourceThreadId: input.sourceThreadId,
-				capturedAt: /* @__PURE__ */ new Date(),
-				when: input.when,
-				metadata: input.metadata
-			};
-			await (await this.#knowledge()).insertOne({
-				...record,
-				scopeKey: (0, _mastra_core_storage.knowledgeScopeKey)(scope),
-				when: record.when ?? null,
-				deletedAt: null,
-				deletedBy: null
-			}, sessionOptions(session));
-			await this.#replaceMentions("record", id, record.text, input.resolutionScope, defaultScope, session);
-			await this.#activity("record-created", "record", id, scope, input.sourceThreadId, session);
-			await this.#outbox("record", id, "upsert", (0, _mastra_core_storage.createKnowledgeUlid)(), scope, session);
-			return record;
+	async deletePage(input) {
+		const core = await loadPagesCore();
+		return this.#tx(async (session) => {
+			const page = await this.#requireLivePage(input.id, session);
+			if (page.version !== input.expectedVersion) throw new _mastra_core_storage.KnowledgeConflictError(input.id);
+			if (page.isScope) throw new Error(`Knowledge scope page ${input.id} can't be deleted`);
+			const pages = await this.#c("pages");
+			if (await pages.findOne({
+				parentId: input.id,
+				...live
+			}, {
+				projection: { id: 1 },
+				session
+			})) throw new core.KnowledgePageHasChildrenError(input.id);
+			const now = /* @__PURE__ */ new Date();
+			const updated = await pages.findOneAndUpdate({
+				id: input.id,
+				version: input.expectedVersion,
+				...live
+			}, {
+				$set: {
+					deletedAt: now,
+					deletedBy: input.deletedBy,
+					updatedAt: now,
+					updatedBy: { author: input.deletedBy }
+				},
+				$unset: { activeKey: "" },
+				$inc: { version: 1 }
+			}, {
+				returnDocument: "after",
+				projection: { _id: 0 },
+				session
+			});
+			if (!updated) throw new _mastra_core_storage.KnowledgeConflictError(input.id);
+			await (await this.#c("pins")).deleteOne({ pageId: input.id }, { session });
+			await this.#log(session, {
+				action: "page-deleted",
+				scopeId: page.scopeId,
+				pageId: page.id,
+				provenance: { author: input.deletedBy },
+				at: now
+			});
+			return toPage(updated);
 		});
 	}
-	async getKnowledge(input) {
-		const row = await (await this.#knowledge()).findOne({
+	async getNote(input) {
+		const ids = await this.#readable(input.read);
+		const filter = {
 			id: input.id,
-			...input.includeDeleted ? {} : { deletedAt: null }
-		});
-		return row ? recordFromDocument(row) : null;
-	}
-	async listKnowledgeAbout(input) {
-		return this.#queryKnowledge(input, "about");
-	}
-	async listKnowledgeMentioning(input) {
-		return this.#queryKnowledge(input, "mentioning");
-	}
-	async listKnowledgeRelatedTo(input) {
-		return this.#queryKnowledge(input, "related");
-	}
-	async knowledgeBySource(input) {
-		const scope = (0, _mastra_core_storage.canonicalizeKnowledgeScope)(input.scope);
-		const limit = input.limit ?? 100;
-		const rows = await (await this.#knowledge()).find({
-			sourceThreadId: input.sourceThreadId,
-			scopeKey: { $in: visibleScopeKeys(scope) },
-			...input.includeDeleted ? {} : { deletedAt: null },
-			...input.after ? { id: { $gt: input.after } } : {}
-		}).sort({ id: 1 }).limit(limit + 1).toArray();
+			...this.#visibleNotes(ids)
+		};
+		if (!input.includeDeleted) Object.assign(filter, live);
+		const row = await (await this.#c("notes")).findOne(filter, noProjection);
+		return row ? toNote(row) : null;
+	}
+	async listNotes(input) {
+		const core = await loadPagesCore();
+		const limit = clampLimit(input.limit, core.MAX_KNOWLEDGE_PAGE_LIST_LIMIT);
+		const ids = await this.#readable(input.read);
+		const filter = {
+			pageId: input.pageId,
+			...this.#visibleNotes(ids)
+		};
+		if (!input.includeDeleted) Object.assign(filter, live);
+		if (input.cursor) {
+			const [createdAt, id] = decodeCursor(input.cursor);
+			const at = new Date(createdAt);
+			filter.$or = [{ createdAt: { $gt: at } }, {
+				createdAt: at,
+				id: { $gt: id }
+			}];
+		}
+		const rows = await (await this.#c("notes")).find(filter, noProjection).sort({
+			createdAt: 1,
+			id: 1
+		}).limit(limit + 1).toArray();
+		return this.#noteOutput(rows, limit);
+	}
+	async countNotes(input) {
+		const ids = [...new Set(input.pageIds)];
+		const counts = Object.fromEntries(ids.map((id) => [id, 0]));
+		if (!ids.length) return counts;
+		const readable = await this.#readable(input.read);
+		const rows = await (await this.#c("notes")).aggregate([{ $match: {
+			pageId: { $in: ids },
+			...live,
+			...this.#visibleNotes(readable)
+		} }, { $group: {
+			_id: "$pageId",
+			count: { $sum: 1 }
+		} }]).toArray();
+		for (const row of rows) counts[row._id] = row.count;
+		return counts;
+	}
+	async listNotesMentioning(input) {
+		const core = await loadPagesCore();
+		const limit = clampLimit(input.limit, core.MAX_KNOWLEDGE_PAGE_LIST_LIMIT);
+		const ids = await this.#readable(input.read);
+		const match = {
+			mentions: input.pageId,
+			pageId: { $ne: input.pageId },
+			...live,
+			...this.#visibleNotes(ids)
+		};
+		if (input.cursor) {
+			const [createdAt, id] = decodeCursor(input.cursor);
+			const at = new Date(createdAt);
+			match.$or = [{ createdAt: { $lt: at } }, {
+				createdAt: at,
+				id: { $lt: id }
+			}];
+		}
+		const rows = await (await this.#c("notes")).aggregate([
+			{ $match: match },
+			{ $lookup: {
+				from: MONGO_KNOWLEDGE_PAGES_COLLECTIONS.pages,
+				localField: "pageId",
+				foreignField: "id",
+				as: "page"
+			} },
+			{ $match: { "page.deletedAt": { $exists: false } } },
+			{ $project: {
+				_id: 0,
+				page: 0
+			} },
+			{ $sort: {
+				createdAt: -1,
+				id: -1
+			} },
+			{ $limit: limit + 1 }
+		]).toArray();
+		return this.#noteOutput(rows, limit);
+	}
+	#noteOutput(rows, limit) {
+		const notes = rows.slice(0, limit).map(toNote);
+		const last = notes[notes.length - 1];
 		return {
-			records: rows.slice(0, limit).map(recordFromDocument),
-			nextCursor: rows.length > limit ? rows[limit - 1]?.id : void 0
+			notes,
+			...rows.length > limit && last ? { nextCursor: encodeCursor([last.createdAt.toISOString(), last.id]) } : {}
 		};
 	}
-	async removeKnowledge(input) {
-		return this.#connector.withTransaction(async (session) => {
-			const record = await this.#getKnowledge(input.id, true, session);
-			if (!record) throw new _mastra_core_storage.KnowledgeNotFoundError("record", input.id);
-			if (record.deletedAt) return record;
-			const deletedAt = /* @__PURE__ */ new Date();
-			await (await this.#knowledge()).updateOne({
-				id: input.id,
-				deletedAt: null
-			}, { $set: {
-				deletedAt,
-				deletedBy: input.deletedBy
-			} }, sessionOptions(session));
-			await this.#activity("record-deleted", "record", input.id, record.scope, record.sourceThreadId, session);
-			await this.#outbox("record", input.id, "delete", (0, _mastra_core_storage.createKnowledgeUlid)(), record.scope, session);
-			return {
-				...record,
-				deletedAt,
-				deletedBy: input.deletedBy
+	async #assertScopePages(ids, session) {
+		const rows = await (await this.#c("pages")).find({
+			id: { $in: ids },
+			isScope: true
+		}, {
+			projection: {
+				_id: 0,
+				id: 1
+			},
+			session
+		}).toArray();
+		const found = new Set(rows.map((row) => String(row.id)));
+		const missing = ids.find((id) => !found.has(id));
+		if (missing) throw new Error(`Knowledge note stamp ${missing} is not a scope page`);
+	}
+	async addNote(input) {
+		(await this.#bounds()).assertKnowledgeNoteTextWithinBound(input.text);
+		if (input.stampScopeIds.length === 0) throw new Error("A Knowledge note needs at least one stamp scope");
+		return this.#tx(async (session) => {
+			const page = await this.#requireLivePage(input.pageId, session);
+			const stampIds = [...new Set(input.stampScopeIds)];
+			await this.#assertScopePages(stampIds, session);
+			const mentionIds = [...new Set(input.mentions)];
+			let mentionScopeIds = [];
+			if (mentionIds.length) {
+				const found = await (await this.#c("pages")).find({ id: { $in: mentionIds } }, {
+					projection: {
+						_id: 0,
+						id: 1,
+						scopeId: 1
+					},
+					session
+				}).toArray();
+				const known = new Set(found.map((row) => String(row.id)));
+				const missing = mentionIds.find((id) => !known.has(id));
+				if (missing) throw new _mastra_core_storage.KnowledgeNotFoundError("page", missing);
+				mentionScopeIds = [...new Set(found.map((row) => String(row.scopeId)))];
+			}
+			const id = input.id ?? (0, _mastra_core_storage.createKnowledgeUlid)();
+			const now = /* @__PURE__ */ new Date();
+			const doc = {
+				id,
+				pageId: page.id,
+				pageScopeId: page.scopeId,
+				text: input.text,
+				...input.when ? { when: input.when } : {},
+				stampScopeIds: stampIds,
+				mentions: mentionIds,
+				mentionScopeIds,
+				provenance: input.provenance,
+				version: 1,
+				createdAt: now,
+				updatedAt: now
 			};
+			try {
+				await (await this.#c("notes")).insertOne({ ...doc }, { session });
+			} catch (error) {
+				if (isDuplicateKey(error)) throw new _mastra_core_storage.KnowledgeConflictError(id);
+				throw error;
+			}
+			await this.#log(session, {
+				action: "note-added",
+				scopeId: page.scopeId,
+				pageId: page.id,
+				noteId: id,
+				provenance: input.provenance,
+				at: now
+			});
+			return toNote(doc);
 		});
 	}
-	async restoreKnowledge(input) {
-		return this.#connector.withTransaction(async (session) => {
-			const record = await this.#getKnowledge(input.id, true, session);
-			if (!record) throw new _mastra_core_storage.KnowledgeNotFoundError("record", input.id);
-			if (!record.deletedAt) return record;
-			await (await this.#knowledge()).updateOne({ id: input.id }, { $set: {
-				deletedAt: null,
-				deletedBy: null
-			} }, sessionOptions(session));
-			await this.#activity("record-restored", "record", input.id, record.scope, record.sourceThreadId, session);
-			await this.#outbox("record", input.id, "upsert", (0, _mastra_core_storage.createKnowledgeUlid)(), record.scope, session);
-			return {
-				...record,
-				deletedAt: void 0,
-				deletedBy: void 0
-			};
+	async #requireNote(id, session) {
+		const row = await (await this.#c("notes")).findOne({ id }, {
+			...noProjection,
+			session
+		});
+		if (!row) throw new _mastra_core_storage.KnowledgeNotFoundError("note", id);
+		return row;
+	}
+	async restampNote(input) {
+		if (input.stampScopeIds.length === 0) throw new Error("A Knowledge note needs at least one stamp scope");
+		return this.#tx(async (session) => {
+			const note = await this.#requireNote(input.id, session);
+			if (note.deletedAt) throw new _mastra_core_storage.KnowledgeNotFoundError("note", input.id);
+			if (Number(note.version) !== input.expectedVersion) throw new _mastra_core_storage.KnowledgeConflictError(input.id);
+			const stampIds = [...new Set(input.stampScopeIds)];
+			await this.#assertScopePages(stampIds, session);
+			const now = /* @__PURE__ */ new Date();
+			const updated = await (await this.#c("notes")).findOneAndUpdate({
+				id: input.id,
+				version: input.expectedVersion
+			}, {
+				$set: {
+					stampScopeIds: stampIds,
+					updatedAt: now
+				},
+				$inc: { version: 1 }
+			}, {
+				returnDocument: "after",
+				projection: { _id: 0 },
+				session
+			});
+			if (!updated) throw new _mastra_core_storage.KnowledgeConflictError(input.id);
+			await this.#log(session, {
+				action: "note-restamped",
+				scopeId: String(note.pageScopeId),
+				pageId: String(note.pageId),
+				noteId: input.id,
+				provenance: input.provenance,
+				at: now
+			});
+			return toNote(updated);
 		});
 	}
-	async rescopeKnowledge(input) {
-		const scope = (0, _mastra_core_storage.canonicalizeKnowledgeScope)(input.scope);
-		return this.#connector.withTransaction(async (session) => {
-			const record = await this.#getKnowledge(input.id, true, session);
-			if (!record) throw new _mastra_core_storage.KnowledgeNotFoundError("record", input.id);
-			await (await this.#knowledge()).updateOne({ id: input.id }, { $set: {
-				scope,
-				scopeKey: (0, _mastra_core_storage.knowledgeScopeKey)(scope)
-			} }, sessionOptions(session));
-			await this.#activity("record-rescoped", "record", input.id, scope, record.sourceThreadId, session);
-			await this.#outbox("record", input.id, "delete", (0, _mastra_core_storage.createKnowledgeUlid)(), record.scope, session);
-			if (!record.deletedAt) await this.#outbox("record", input.id, "upsert", (0, _mastra_core_storage.createKnowledgeUlid)(), scope, session);
-			return {
-				...record,
-				scope
-			};
+	async removeNote(input) {
+		return this.#tx(async (session) => {
+			const note = await this.#requireNote(input.id, session);
+			if (note.deletedAt) return toNote(note);
+			const now = /* @__PURE__ */ new Date();
+			const updated = await (await this.#c("notes")).findOneAndUpdate({ id: input.id }, {
+				$set: {
+					deletedAt: now,
+					deletedBy: input.deletedBy,
+					updatedAt: now
+				},
+				$inc: { version: 1 }
+			}, {
+				returnDocument: "after",
+				projection: { _id: 0 },
+				session
+			});
+			await this.#log(session, {
+				action: "note-removed",
+				scopeId: String(note.pageScopeId),
+				pageId: String(note.pageId),
+				noteId: input.id,
+				provenance: input.provenance,
+				at: now
+			});
+			return toNote(updated);
 		});
 	}
-	async search(input) {
-		const scope = (0, _mastra_core_storage.canonicalizeKnowledgeScope)(input.scope);
-		const query = input.query.trim();
-		if (!query) return [];
-		const regex = new RegExp(this.#escapeRegex(query), "i");
-		const limit = input.limit ?? 20;
-		const results = (await (await this.#nodes()).find({
-			mergedInto: null,
-			scopeKey: { $in: visibleScopeKeys(scope) },
-			$or: [
-				{ name: regex },
-				{ kind: regex },
-				{ content: regex },
-				{ description: regex }
-			]
-		}).sort({ updatedAt: -1 }).limit(limit).toArray()).map((row) => ({
-			type: "node",
-			id: row.id,
-			recordId: row.id,
-			name: row.name,
-			text: [
-				row.name,
-				...row.description ? [row.description] : [],
-				...row.content ? [row.content] : []
-			].join("\n"),
-			scope: cloneScope(row.scope)
+	async restoreNote(input) {
+		return this.#tx(async (session) => {
+			const note = await this.#requireNote(input.id, session);
+			if (!note.deletedAt) return toNote(note);
+			const now = /* @__PURE__ */ new Date();
+			const updated = await (await this.#c("notes")).findOneAndUpdate({ id: input.id }, {
+				$set: { updatedAt: now },
+				$unset: {
+					deletedAt: "",
+					deletedBy: ""
+				},
+				$inc: { version: 1 }
+			}, {
+				returnDocument: "after",
+				projection: { _id: 0 },
+				session
+			});
+			await this.#log(session, {
+				action: "note-restored",
+				scopeId: String(note.pageScopeId),
+				pageId: String(note.pageId),
+				noteId: input.id,
+				provenance: input.provenance,
+				at: now
+			});
+			return toNote(updated);
+		});
+	}
+	async searchPages(input) {
+		const core = await loadPagesCore();
+		const limit = clampLimit(input.limit, core.MAX_KNOWLEDGE_PAGE_LIST_LIMIT);
+		const words = knowledgeSearchWords(input.query);
+		if (!words.length) return [];
+		const phrase = input.query.trim().toLowerCase().replace(/\s+/g, " ");
+		const ids = await this.#readable(input.read);
+		const scopes = input.scopeIds?.length ? input.scopeIds : void 0;
+		const inScope = (field) => {
+			if (ids === null) return scopes ? { [field]: { $in: scopes } } : {};
+			const allowed = scopes ? scopes.filter((id) => ids.includes(id)) : ids;
+			return { [field]: { $in: allowed } };
+		};
+		const matcher = (word) => ({
+			$regex: escapeRegex(word),
+			$options: "i"
+		});
+		const pages = await this.#c("pages");
+		const pageFilter = {
+			...live,
+			...notScope,
+			...inScope("scopeId"),
+			$and: words.map((word) => ({ $or: [
+				{ name: matcher(word) },
+				{ description: matcher(word) },
+				{ body: matcher(word) }
+			] }))
+		};
+		const hits = (await pages.aggregate([
+			{ $match: pageFilter },
+			{ $addFields: { searchTier: { $cond: [
+				{ $regexMatch: {
+					input: "$canonicalName",
+					regex: escapeRegex(phrase)
+				} },
+				0,
+				{ $cond: [
+					{ $and: words.map((word) => ({ $regexMatch: {
+						input: "$name",
+						regex: escapeRegex(word),
+						options: "i"
+					} })) },
+					1,
+					2
+				] }
+			] } } },
+			{ $sort: {
+				searchTier: 1,
+				updatedAt: -1,
+				id: 1
+			} },
+			{ $limit: limit },
+			{ $project: {
+				searchTier: 0,
+				_id: 0
+			} }
+		]).toArray()).map((row) => ({
+			type: "page",
+			page: toPage(row)
 		}));
-		if (results.length < limit) {
-			const records = await (await this.#knowledge()).find({
-				deletedAt: null,
-				scopeKey: { $in: visibleScopeKeys(scope) },
-				text: regex
-			}).sort({ id: -1 }).limit(limit - results.length).toArray();
-			for (const record of records) {
-				const parent = await this.#resolveTerminalNode(record.node);
-				const parentVisible = parent && (0, _mastra_core_storage.isKnowledgeScopeVisible)(parent.scope, scope);
-				results.push({
-					type: "record",
-					id: record.id,
-					recordId: parentVisible ? record.node : record.id,
-					name: parentVisible ? parent.name : "(private node)",
-					text: record.text,
-					scope: cloneScope(record.scope)
-				});
-			}
+		if (hits.length >= limit) return hits;
+		const noteRows = await (await this.#c("notes")).find({
+			...live,
+			...this.#visibleNotes(ids),
+			...scopes ? { pageScopeId: { $in: ids === null ? scopes : scopes.filter((id) => ids.includes(id)) } } : {},
+			$and: words.map((word) => ({ text: matcher(word) }))
+		}, noProjection).sort({
+			updatedAt: -1,
+			id: -1
+		}).limit(limit - hits.length).toArray();
+		const notePages = new Map((await pages.find({
+			id: { $in: [...new Set(noteRows.map((row) => String(row.pageId)))] },
+			...live
+		}, noProjection).toArray()).map((row) => [String(row.id), toPage(row)]));
+		for (const row of noteRows) {
+			const page = notePages.get(String(row.pageId));
+			if (page) hits.push({
+				type: "note",
+				note: toNote(row),
+				page
+			});
 		}
-		return results.slice(0, limit);
-	}
-	/**
-	* @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);
+		return hits;
 	}
-	/**
-	* @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 scope = (0, _mastra_core_storage.canonicalizeKnowledgeScope)(input.scope);
-		return (await (await this.#activityCollection()).find({
-			scopeKey: { $in: visibleScopeKeys(scope) },
-			...input.after ? { id: { $lt: input.after } } : {}
-		}).sort({ id: -1 }).limit(input.limit ?? 100).toArray()).map((row) => ({
-			id: row.id,
-			action: row.action,
-			recordType: row.recordType,
-			recordId: row.recordId,
-			scope: cloneScope(row.scope),
-			sourceThreadId: row.sourceThreadId ?? void 0,
+	async listPageActivity(input) {
+		const core = await loadPagesCore();
+		const limit = clampLimit(input.limit, core.MAX_KNOWLEDGE_PAGE_LIST_LIMIT);
+		const ids = await this.#readable(input.read);
+		const activity = await this.#c("activity");
+		const notes = await this.#c("notes");
+		const filter = {};
+		if (ids !== null) filter.pageScopeId = { $in: ids };
+		delete filter.scopeId;
+		if (input.scopeId) {
+			if (ids !== null && !ids.includes(input.scopeId)) filter.pageScopeId = { $in: [] };
+			else filter.pageScopeId = input.scopeId;
+		}
+		if (input.pageId) filter.pageId = input.pageId;
+		if (input.cursor) {
+			const [createdAt, id] = decodeCursor(input.cursor);
+			const at = new Date(createdAt);
+			filter.$or = [{ createdAt: { $lt: at } }, {
+				createdAt: at,
+				id: { $lt: id }
+			}];
+		}
+		const events = [];
+		let cursorFilter = filter;
+		for (;;) {
+			const batch = await activity.find(cursorFilter, noProjection).sort({
+				createdAt: -1,
+				id: -1
+			}).limit(limit * 4 + 1).toArray();
+			const noteIds = [...new Set(batch.flatMap((row) => row.noteId ? [String(row.noteId)] : []))];
+			const visible = new Set(noteIds.length ? (await notes.find({
+				id: { $in: noteIds },
+				...this.#visibleNotes(ids)
+			}, { projection: {
+				_id: 0,
+				id: 1
+			} }).toArray()).map((row) => String(row.id)) : []);
+			for (const row of batch) {
+				if (row.noteId && !visible.has(String(row.noteId))) continue;
+				events.push(row);
+				if (events.length > limit) break;
+			}
+			if (events.length > limit || batch.length <= limit * 4) break;
+			const last = batch[batch.length - 1];
+			cursorFilter = {
+				...filter,
+				$or: [{ createdAt: { $lt: last.createdAt } }, {
+					createdAt: last.createdAt,
+					id: { $lt: last.id }
+				}]
+			};
+		}
+		const page = events.slice(0, limit).map((row) => ({
+			id: String(row.id),
+			action: String(row.action),
+			scopeId: String(row.scopeId),
+			pageId: String(row.pageId),
+			...row.noteId == null ? {} : { noteId: String(row.noteId) },
+			provenance: row.provenance,
 			createdAt: new Date(row.createdAt)
 		}));
-	}
-	async listSemanticOutbox(input = {}) {
-		const filter = {
-			...input.status ? { status: input.status } : {},
-			...input.scope ? { scopeKey: { $in: visibleScopeKeys(input.scope) } } : {}
+		const last = page[page.length - 1];
+		return {
+			events: page,
+			...events.length > limit && last ? { nextCursor: encodeCursor([last.createdAt.toISOString(), last.id]) } : {}
 		};
-		return (await (await this.#outboxCollection()).find(filter).sort({
-			createdAt: 1,
-			id: 1
-		}).limit(input.limit ?? 100).toArray()).map(outboxFromDocument);
 	}
-	async claimSemanticOutbox(input) {
-		return this.#connector.withTransaction(async (session) => {
-			const collection = await this.#outboxCollection();
-			const now = input.now ?? /* @__PURE__ */ new Date();
-			const staleBefore = new Date(now.getTime() - (input.claimTimeoutMs ?? 6e4));
-			const filter = {
-				$or: [{
-					status: "pending",
-					availableAt: { $lte: now }
-				}, {
-					status: "processing",
-					claimedAt: { $lte: staleBefore }
-				}],
-				...input.scope ? { scopeKey: { $in: visibleScopeKeys(input.scope) } } : {}
+	/** Deletes every document but keeps the collections, indexes and schema-version marker. */
+	async clearAll() {
+		await this.#tx(async (session) => {
+			for (const name of [
+				"activity",
+				"pins",
+				"notes",
+				"pages"
+			]) await (await this.#c(name)).deleteMany({}, { session });
+		});
+	}
+	async addPinAudience(input) {
+		return this.#tx(async (session) => {
+			const page = await this.#requireLivePage(input.pageId, session);
+			const now = /* @__PURE__ */ new Date();
+			const { pin, changed } = await this.#upsertPinAudience(session, page.id, input.audience, input.createdBy, now);
+			if (changed) await this.#log(session, {
+				action: "pin-added",
+				scopeId: page.scopeId,
+				pageId: page.id,
+				provenance: { author: input.createdBy },
+				at: now
+			});
+			return pin;
+		});
+	}
+	async #upsertPinAudience(session, pageId, audience, createdBy, now) {
+		const pins = await this.#c("pins");
+		const existing = await pins.findOne({ pageId }, {
+			...noProjection,
+			session
+		});
+		if (!existing) {
+			const doc = {
+				id: (0, _mastra_core_storage.createKnowledgeUlid)(),
+				pageId,
+				audience: [...new Set(audience)],
+				createdBy,
+				createdAt: now,
+				updatedAt: now
 			};
-			const limit = input.limit ?? 100;
-			const candidates = await collection.find(filter, sessionOptions(session)).sort({
-				createdAt: 1,
+			try {
+				await pins.insertOne({ ...doc }, { session });
+			} catch (error) {
+				if (isDuplicateKey(error)) throw new _mastra_core_storage.KnowledgeConflictError(pageId);
+				throw error;
+			}
+			return {
+				pin: toPin(doc),
+				changed: true
+			};
+		}
+		const current = existing.audience ?? [];
+		const merged = [.../* @__PURE__ */ new Set([...current, ...audience])];
+		if (merged.length === current.length) return {
+			pin: toPin(existing),
+			changed: false
+		};
+		return {
+			pin: toPin(await pins.findOneAndUpdate({ id: existing.id }, { $set: {
+				audience: merged,
+				updatedAt: now
+			} }, {
+				returnDocument: "after",
+				projection: { _id: 0 },
+				session
+			})),
+			changed: true
+		};
+	}
+	async removePinAudience(input) {
+		return this.#tx(async (session) => {
+			const pins = await this.#c("pins");
+			const existing = await pins.findOne({ pageId: input.pageId }, {
+				...noProjection,
+				session
+			});
+			if (!existing) return null;
+			const current = existing.audience ?? [];
+			const remaining = current.filter((entry) => !input.audience.includes(entry));
+			if (remaining.length === current.length) return toPin(existing);
+			const now = /* @__PURE__ */ new Date();
+			let pin = null;
+			if (remaining.length === 0) await pins.deleteOne({ id: existing.id }, { session });
+			else pin = toPin(await pins.findOneAndUpdate({ id: existing.id }, { $set: {
+				audience: remaining,
+				updatedAt: now
+			} }, {
+				returnDocument: "after",
+				projection: { _id: 0 },
+				session
+			}));
+			const page = await this.#page(input.pageId, session);
+			await this.#log(session, {
+				action: "pin-removed",
+				scopeId: page?.scopeId ?? input.pageId,
+				pageId: input.pageId,
+				provenance: { author: input.removedBy },
+				at: now
+			});
+			return pin;
+		});
+	}
+	async getPages(input) {
+		if (!input.ids.length) return [];
+		const rows = await (await this.#c("pages")).find({
+			id: { $in: [...new Set(input.ids)] },
+			...live
+		}, noProjection).toArray();
+		if (input.read === "all") return rows.map(toPage);
+		const read = input.read;
+		const scopeIds = [...new Set(rows.map((row) => String(row.scopeId)))];
+		const readable = /* @__PURE__ */ new Set();
+		const any = this.#readableClauses(read);
+		if (scopeIds.length && any.length) {
+			const scopes = await (await this.#c("pages")).find({
+				id: { $in: scopeIds },
+				isScope: true,
+				$or: any
+			}, { projection: {
+				_id: 0,
 				id: 1
-			}).limit(Math.max(limit * 10, 100)).toArray();
-			const claimed = [];
-			for (const candidate of candidates) {
-				if (claimed.length >= limit) break;
-				if (await collection.findOne({
-					documentId: candidate.documentId,
-					status: { $ne: "completed" },
-					$or: [{ createdAt: { $lt: candidate.createdAt } }, {
-						createdAt: candidate.createdAt,
-						id: { $lt: candidate.id }
-					}]
-				}, sessionOptions(session))) continue;
-				const result = await collection.findOneAndUpdate({
-					id: candidate.id,
-					$or: [{
-						status: "pending",
-						availableAt: { $lte: now }
-					}, {
-						status: "processing",
-						claimedAt: { $lte: staleBefore }
-					}]
-				}, {
-					$set: {
-						status: "processing",
-						claimedAt: now,
-						claimedBy: input.workerId
-					},
-					$inc: { attempts: 1 }
-				}, {
-					...sessionOptions(session),
-					returnDocument: "after"
-				});
-				if (result) claimed.push(result);
+			} }).toArray();
+			for (const scope of scopes) readable.add(String(scope.id));
+		}
+		return rows.filter((row) => readable.has(String(row.scopeId))).map(toPage);
+	}
+	async listPins(input) {
+		const core = await loadPagesCore();
+		const limit = clampLimit(input.limit, core.MAX_KNOWLEDGE_PAGE_LIST_LIMIT);
+		const ids = await this.#readable(input.read);
+		const match = {};
+		if (input.audience !== "all") match.audience = { $in: input.audience };
+		const pageId = {};
+		if (input.pageIds) pageId.$in = input.pageIds;
+		if (input.excludePageIds?.length) pageId.$nin = input.excludePageIds;
+		if (Object.keys(pageId).length) match.pageId = pageId;
+		const pins = await this.#c("pins");
+		const base = [
+			{ $match: match },
+			{ $lookup: {
+				from: MONGO_KNOWLEDGE_PAGES_COLLECTIONS.pages,
+				localField: "pageId",
+				foreignField: "id",
+				as: "page"
+			} },
+			{ $match: {
+				"page.deletedAt": { $exists: false },
+				...ids === null ? {} : { "page.scopeId": { $in: ids } },
+				...input.withBody ? { "page.body": { $regex: "\\S" } } : {}
+			} }
+		];
+		const pageMatch = [];
+		if (input.cursor) {
+			const [createdAt, id] = decodeCursor(input.cursor);
+			const at = new Date(createdAt);
+			pageMatch.push({ $match: { $or: [{ createdAt: { $lt: at } }, {
+				createdAt: at,
+				id: { $lt: id }
+			}] } });
+		}
+		const rows = await pins.aggregate([
+			...base,
+			...pageMatch,
+			{ $addFields: { pageName: { $arrayElemAt: ["$page.name", 0] } } },
+			{ $project: {
+				_id: 0,
+				page: 0
+			} },
+			{ $sort: {
+				createdAt: -1,
+				id: -1
+			} },
+			{ $limit: limit + 1 }
+		]).toArray();
+		let total;
+		if (input.count) {
+			const counted = await pins.aggregate([...base, { $count: "total" }]).toArray();
+			total = Number(counted[0]?.total ?? 0);
+		}
+		const listed = rows.slice(0, limit).map(toListedPin);
+		const last = listed[listed.length - 1];
+		return {
+			pins: listed,
+			...rows.length > limit && last ? { nextCursor: encodeCursor([last.createdAt.toISOString(), last.id]) } : {},
+			...total === void 0 ? {} : { total }
+		};
+	}
+};
+// src/storage/domains/knowledge/index.ts
+const loadKnowledgePagesCore = createKnowledgePagesCoreLoader(_mastra_core_features.coreFeatures, () => import("@mastra/core/storage"));
+/** @experimental Knowledge APIs are experimental and may change without notice. */
+var KnowledgeMongoDB = class extends _mastra_core_storage.KnowledgeStorage {
+	static MANAGED_COLLECTIONS = Object.values(MONGO_KNOWLEDGE_PAGES_COLLECTIONS);
+	#connector;
+	#pages;
+	constructor(config) {
+		super();
+		this.#connector = resolveMongoDBConfig(config);
+		this.#pages = new MongoKnowledgePages({
+			connector: this.#connector,
+			bounds: async () => {
+				const core = await loadKnowledgePagesCore();
+				return {
+					assertKnowledgePageDescriptionWithinBound: core.assertKnowledgePageDescriptionWithinBound,
+					assertKnowledgeNoteTextWithinBound: core.assertKnowledgeNoteTextWithinBound
+				};
 			}
-			return claimed.map(outboxFromDocument);
 		});
 	}
-	async completeSemanticOutbox(input) {
-		if (!input.ids.length) return;
-		await (await this.#outboxCollection()).updateMany({
-			id: { $in: input.ids },
-			status: "processing",
-			claimedBy: input.workerId
-		}, { $set: {
-			status: "completed",
-			completedAt: /* @__PURE__ */ new Date(),
-			claimedAt: null,
-			claimedBy: null
-		} });
-	}
-	async releaseSemanticOutbox(input) {
-		if (!input.ids.length) return;
-		await (await this.#outboxCollection()).updateMany({
-			id: { $in: input.ids },
-			status: "processing",
-			claimedBy: input.workerId
-		}, { $set: {
-			status: "pending",
-			availableAt: input.retryAt ?? /* @__PURE__ */ new Date(),
-			claimedAt: null,
-			claimedBy: null
-		} });
+	getCapabilities() {
+		return {
+			...super.getCapabilities(),
+			schemaVersion: 4,
+			supportsSchemaInspection: true,
+			supportsExplicitReset: true
+		};
 	}
-	async #collection(name) {
-		return this.#connector.getCollection(name);
+	async init() {
+		await this.#pages.init();
 	}
-	#nodes() {
-		return this.#collection(_mastra_core_storage.TABLE_KNOWLEDGE_NODES);
+	async inspectSchema() {
+		return this.#pages.inspectSchema();
 	}
-	#knowledge() {
-		return this.#collection(_mastra_core_storage.TABLE_KNOWLEDGE_RECORDS);
+	async dangerouslyReset() {
+		await this.#pages.reset();
 	}
-	#mentions() {
-		return this.#collection(_mastra_core_storage.TABLE_KNOWLEDGE_MENTIONS);
+	async dangerouslyClearAll() {
+		await this.#pages.clearAll();
 	}
-	#activityCollection() {
-		return this.#collection(_mastra_core_storage.TABLE_KNOWLEDGE_ACTIVITY);
+	materializeScope(input) {
+		return this.#pages.materializeScope(input);
 	}
-	#outboxCollection() {
-		return this.#collection(_mastra_core_storage.TABLE_KNOWLEDGE_SEMANTIC_OUTBOX);
+	getScopesByAddress(input) {
+		return this.#pages.getScopesByAddress(input);
 	}
-	async #getNode(id, session) {
-		const row = await (await this.#nodes()).findOne({
-			id,
-			type: "node"
-		}, sessionOptions(session));
-		return row ? nodeFromDocument(row) : null;
-	}
-	async #getNodeByName(name, scope, session) {
-		const row = await (await this.#nodes()).findOne({
-			type: "node",
-			scopeKey: (0, _mastra_core_storage.knowledgeScopeKey)(scope),
-			canonicalName: canonicalName(name)
-		}, sessionOptions(session));
-		return row ? nodeFromDocument(row) : null;
-	}
-	async #resolveNode(name, scope, session) {
-		const candidates = (await (await this.#nodes()).find({
-			type: "node",
-			canonicalName: canonicalName(name),
-			$or: [{ scopeKey: { $in: visibleScopeKeys(scope) } }, { mergedInto: { $ne: null } }]
-		}, sessionOptions(session)).toArray()).map(nodeFromDocument).sort((left, right) => right.scope.length - left.scope.length);
-		for (const candidate of candidates) {
-			const terminal = await this.#resolveTerminalNode(candidate.id, session);
-			if (terminal && (0, _mastra_core_storage.isKnowledgeScopeVisible)(terminal.scope, scope)) return terminal;
-		}
-		return null;
-	}
-	async #resolveTerminalNode(id, session) {
-		let node = await this.#getNode(id, session);
-		const seen = /* @__PURE__ */ new Set();
-		while (node?.mergedInto) {
-			if (seen.has(node.id)) throw new Error(`Knowledge merge cycle detected at ${node.id}`);
-			seen.add(node.id);
-			node = await this.#getNode(node.mergedInto, session);
-		}
-		return node;
+	listScopeDeclarations() {
+		return this.#pages.listScopeDeclarations();
 	}
-	async #getPageByExactName(name, scope, session) {
-		const row = await (await this.#nodes()).findOne({
-			type: "page",
-			scopeKey: (0, _mastra_core_storage.knowledgeScopeKey)(scope),
-			canonicalName: canonicalName(name)
-		}, sessionOptions(session));
-		return row ? nodeFromDocument(row) : null;
+	renameScopeDeclaration(input) {
+		return this.#pages.renameScopeDeclaration(input);
 	}
-	async #getKnowledge(id, includeDeleted, session) {
-		const row = await (await this.#knowledge()).findOne({
-			id,
-			...includeDeleted ? {} : { deletedAt: null }
-		}, sessionOptions(session));
-		return row ? recordFromDocument(row) : null;
-	}
-	async #queryKnowledge(input, relationship) {
-		const scope = (0, _mastra_core_storage.canonicalizeKnowledgeScope)(input.scope);
-		const node = await this.#resolveTerminalNode(nodeReferenceId(input.node));
-		if (!node) return { records: [] };
-		const nodeIds = [node.id];
-		if (relationship !== "about") {
-			const mentions = await (await this.#mentions()).find({
-				recordId: node.id,
-				sourceType: "record"
-			}).toArray();
-			nodeIds.push(...mentions.map((row) => row.sourceId));
-		}
-		const limit = input.limit ?? 100;
-		const filter = relationship === "about" ? { node: node.id } : relationship === "mentioning" ? { id: { $in: nodeIds.slice(1) } } : { $or: [{ node: node.id }, { id: { $in: nodeIds.slice(1) } }] };
-		Object.assign(filter, {
-			scopeKey: { $in: visibleScopeKeys(scope) },
-			...input.includeDeleted ? {} : { deletedAt: null },
-			...input.after ? { id: { $lt: input.after } } : {}
-		});
-		const rows = await (await this.#knowledge()).find(filter).sort({ id: -1 }).limit(limit + 1).toArray();
-		return {
-			records: rows.slice(0, limit).map(recordFromDocument),
-			nextCursor: rows.length > limit ? rows[limit - 1]?.id : void 0
-		};
+	listChildScopes(input) {
+		return this.#pages.listChildScopes(input);
 	}
-	async #replaceMentions(sourceType, sourceId, text, resolutionScope, defaultScope, session) {
-		const mentions = await this.#mentions();
-		await mentions.deleteMany({
-			sourceType,
-			sourceId
-		}, sessionOptions(session));
-		for (const name of (0, _mastra_core_storage.parseKnowledgeWikilinks)(text)) {
-			let node = await this.#resolveNode(name, resolutionScope, session);
-			if (!node) {
-				const existing = await this.#getNodeByName(name, defaultScope, session);
-				node = existing ? await this.#resolveTerminalNode(existing.id, session) : null;
-			}
-			if (!node) {
-				const now = /* @__PURE__ */ new Date();
-				node = {
-					id: crypto.randomUUID(),
-					type: "node",
-					name,
-					kind: "node",
-					scope: defaultScope,
-					version: 1,
-					createdAt: now,
-					updatedAt: now
-				};
-				try {
-					await (await this.#nodes()).insertOne({
-						...node,
-						canonicalName: canonicalName(name),
-						scopeKey: (0, _mastra_core_storage.knowledgeScopeKey)(defaultScope),
-						mergedInto: null
-					}, sessionOptions(session));
-					await this.#activity("node-created", "node", node.id, defaultScope, void 0, session);
-					await this.#outbox("node", node.id, "upsert", 1, defaultScope, session);
-				} catch (error) {
-					if (error.code !== 11e3) throw error;
-					node = await this.#getNodeByName(name, defaultScope, session);
-					if (!node) throw error;
-				}
-			}
-			await mentions.updateOne({
-				sourceType,
-				sourceId,
-				recordId: node.id
-			}, { $setOnInsert: {
-				sourceType,
-				sourceId,
-				recordId: node.id
-			} }, {
-				...sessionOptions(session),
-				upsert: true
-			});
-		}
+	getPages(input) {
+		return this.#pages.getPages(input);
 	}
-	async #activity(action, recordType, recordId, scope, sourceThreadId, session) {
-		await (await this.#activityCollection()).insertOne({
-			id: (0, _mastra_core_storage.createKnowledgeUlid)(),
-			action,
-			recordType,
-			recordId,
-			scope,
-			scopeKey: (0, _mastra_core_storage.knowledgeScopeKey)(scope),
-			sourceThreadId: sourceThreadId ?? null,
-			createdAt: /* @__PURE__ */ new Date()
-		}, sessionOptions(session));
-	}
-	async #outbox(documentType, id, operation, version, scope, session) {
-		const documentId = (0, _mastra_core_storage.knowledgeSemanticDocumentId)(documentType, id);
-		const idempotencyKey = (0, _mastra_core_storage.knowledgeSemanticIdempotencyKey)(documentId, operation, version);
-		const now = /* @__PURE__ */ new Date();
-		try {
-			await (await this.#outboxCollection()).insertOne({
-				id: (0, _mastra_core_storage.createKnowledgeUlid)(),
-				idempotencyKey,
-				documentId,
-				documentType,
-				operation,
-				scope,
-				scopeKey: (0, _mastra_core_storage.knowledgeScopeKey)(scope),
-				status: "pending",
-				attempts: 0,
-				availableAt: now,
-				claimedAt: null,
-				claimedBy: null,
-				createdAt: now,
-				completedAt: null
-			}, sessionOptions(session));
-		} catch (error) {
-			if (error.code !== 11e3) throw error;
-		}
+	getPage(input) {
+		return this.#pages.getPage(input);
+	}
+	getPageByPath(input) {
+		return this.#pages.getPageByPath(input);
+	}
+	findPagesByName(input) {
+		return this.#pages.findPagesByName(input);
+	}
+	listChildPages(input) {
+		return this.#pages.listChildPages(input);
+	}
+	listPages(input) {
+		return this.#pages.listPages(input);
+	}
+	createPage(input) {
+		return this.#pages.createPage(input);
+	}
+	updatePage(input) {
+		return this.#pages.updatePage(input);
+	}
+	movePage(input) {
+		return this.#pages.movePage(input);
+	}
+	mergePages(input) {
+		return this.#pages.mergePages(input);
+	}
+	deletePage(input) {
+		return this.#pages.deletePage(input);
+	}
+	getNote(input) {
+		return this.#pages.getNote(input);
+	}
+	listNotes(input) {
+		return this.#pages.listNotes(input);
+	}
+	countNotes(input) {
+		return this.#pages.countNotes(input);
+	}
+	listNotesMentioning(input) {
+		return this.#pages.listNotesMentioning(input);
+	}
+	addNote(input) {
+		return this.#pages.addNote(input);
+	}
+	restampNote(input) {
+		return this.#pages.restampNote(input);
+	}
+	removeNote(input) {
+		return this.#pages.removeNote(input);
+	}
+	restoreNote(input) {
+		return this.#pages.restoreNote(input);
+	}
+	searchPages(input) {
+		return this.#pages.searchPages(input);
+	}
+	listPageActivity(input) {
+		return this.#pages.listPageActivity(input);
+	}
+	addPinAudience(input) {
+		return this.#pages.addPinAudience(input);
+	}
+	removePinAudience(input) {
+		return this.#pages.removePinAudience(input);
 	}
-	#escapeRegex(value) {
-		return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+	listPins(input) {
+		return this.#pages.listPins(input);
 	}
 };
 // src/storage/domains/mcp-clients/index.ts