@mastra/mongodb 1.17.1-alpha.0 → 1.18.0

package/dist/index.cjs

@@ -10,7 +10,7 @@ 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");
 //#region package.json
-var version = "1.17.1-alpha.0";
+var version = "1.18.0";
 //#endregion
 //#region src/vector/filter.ts
 /**
@@ -4293,6 +4293,809 @@ var MongoDBExperimentsStorage = class MongoDBExperimentsStorage extends _mastra_
 	}
 };
 //#endregion
+//#region src/storage/domains/knowledge/index.ts
+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);
+	return canonical.map((_, index) => (0, _mastra_core_storage.knowledgeScopeKey)(canonical.slice(0, index + 1)));
+}
+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 }
+		}]
+	}] };
+}
+function nodeFromDocument(row) {
+	return {
+		id: String(row.id),
+		type: "node",
+		name: String(row.name),
+		kind: String(row.kind),
+		content: row.content == null ? void 0 : String(row.content),
+		scope: cloneScope(row.scope),
+		version: Number(row.version),
+		mergedInto: row.mergedInto ?? void 0,
+		createdAt: new Date(row.createdAt),
+		updatedAt: new Date(row.updatedAt)
+	};
+}
+function recordFromDocument(row) {
+	return {
+		id: String(row.id),
+		node: String(row.node),
+		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,
+		maxScope: row.maxScope ?? void 0,
+		metadata: row.metadata ?? void 0,
+		deletedAt: row.deletedAt ? new Date(row.deletedAt) : void 0,
+		deletedBy: row.deletedBy ?? void 0
+	};
+}
+function outboxFromDocument(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,
+		createdAt: new Date(row.createdAt),
+		completedAt: row.completedAt ? new Date(row.completedAt) : void 0
+	};
+}
+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_CURSORS,
+		_mastra_core_storage.TABLE_KNOWLEDGE_ACTIVITY,
+		_mastra_core_storage.TABLE_KNOWLEDGE_SEMANTIC_OUTBOX
+	];
+	#connector;
+	constructor(config) {
+		super();
+		this.#connector = resolveMongoDBConfig(config);
+	}
+	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 cursors = await this.#collection(_mastra_core_storage.TABLE_KNOWLEDGE_CURSORS);
+		const activity = await this.#collection(_mastra_core_storage.TABLE_KNOWLEDGE_ACTIVITY);
+		const outbox = await this.#collection(_mastra_core_storage.TABLE_KNOWLEDGE_SEMANTIC_OUTBOX);
+		await Promise.all([
+			nodes.createIndex({
+				type: 1,
+				scopeKey: 1,
+				canonicalName: 1
+			}, { unique: true }),
+			nodes.createIndex({
+				scopeKey: 1,
+				type: 1
+			}),
+			knowledge.createIndex({
+				node: 1,
+				id: -1
+			}),
+			knowledge.createIndex({
+				sourceThreadId: 1,
+				id: -1
+			}),
+			mentions.createIndex({
+				sourceType: 1,
+				sourceId: 1,
+				recordId: 1
+			}, { unique: true }),
+			mentions.createIndex({
+				recordId: 1,
+				sourceType: 1,
+				sourceId: 1
+			}),
+			cursors.createIndex({
+				sourceThreadId: 1,
+				agent: 1
+			}, { unique: true }),
+			activity.createIndex({ id: -1 }),
+			outbox.createIndex({ idempotencyKey: 1 }, { unique: true }),
+			outbox.createIndex({
+				status: 1,
+				availableAt: 1,
+				createdAt: 1
+			})
+		]);
+	}
+	async dangerouslyClearAll() {
+		await this.#connector.withTransaction(async (session) => {
+			for (const name of KnowledgeMongoDB.MANAGED_COLLECTIONS) await (await this.#collection(name)).deleteMany({}, sessionOptions(session));
+		});
+	}
+	async createNode(input) {
+		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;
+			}
+			const now = /* @__PURE__ */ new Date();
+			const node = {
+				id: input.id ?? crypto.randomUUID(),
+				type: "node",
+				name: input.name.trim(),
+				kind: input.kind,
+				content: input.content,
+				scope,
+				version: 1,
+				createdAt: now,
+				updatedAt: now
+			};
+			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 getNodeByName(input) {
+		return this.#getNodeByName(input.name, (0, _mastra_core_storage.canonicalizeKnowledgeScope)(input.scope));
+	}
+	async resolveNode(input) {
+		return this.#resolveNode(input.name, (0, _mastra_core_storage.canonicalizeKnowledgeScope)(input.scope));
+	}
+	async listNodes(input) {
+		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
+			}) : {}
+		};
+		return (await (await this.#nodes()).find(filter).sort({
+			updatedAt: -1,
+			name: 1,
+			id: 1
+		}).limit(input.limit ?? 100).toArray()).map(nodeFromDocument);
+	}
+	async updateNode(input) {
+		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 now = /* @__PURE__ */ new Date();
+			const result = await (await this.#nodes()).findOneAndUpdate({
+				id: input.id,
+				type: "node",
+				version: input.version
+			}, {
+				$set: {
+					name,
+					canonicalName: canonicalName(name),
+					kind: input.kind ?? existing.kind,
+					content: content ?? null,
+					scope,
+					scopeKey: (0, _mastra_core_storage.knowledgeScopeKey)(scope),
+					updatedAt: now
+				},
+				$inc: { version: 1 }
+			}, {
+				...sessionOptions(session),
+				returnDocument: "after"
+			});
+			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);
+				}
+			}
+			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);
+		});
+	}
+	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({
+				id: source.id,
+				type: "node",
+				version: input.sourceVersion,
+				mergedInto: null
+			}, {
+				$set: {
+					mergedInto: target.id,
+					updatedAt: /* @__PURE__ */ new Date()
+				},
+				$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);
+			}
+			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)(), target.scope, session);
+			return target;
+		});
+	}
+	async appendKnowledge(input) {
+		const scope = (0, _mastra_core_storage.canonicalizeKnowledgeScope)(input.scope);
+		const defaultScope = (0, _mastra_core_storage.canonicalizeKnowledgeScope)(input.defaultScope);
+		(0, _mastra_core_storage.assertKnowledgeScopeWithinCeiling)(scope, input.maxScope);
+		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,
+				maxScope: input.maxScope,
+				metadata: input.metadata
+			};
+			await (await this.#knowledge()).insertOne({
+				...record,
+				scopeKey: (0, _mastra_core_storage.knowledgeScopeKey)(scope),
+				when: record.when ?? null,
+				maxScope: record.maxScope ?? 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 getKnowledge(input) {
+		const row = await (await this.#knowledge()).findOne({
+			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();
+		return {
+			records: rows.slice(0, limit).map(recordFromDocument),
+			nextCursor: rows.length > limit ? rows[limit - 1]?.id : void 0
+		};
+	}
+	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 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 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);
+			(0, _mastra_core_storage.assertKnowledgeScopeWithinCeiling)(scope, record.maxScope);
+			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 raiseKnowledgeCeiling(input) {
+		const record = await this.#getKnowledge(input.id, true);
+		if (!record) throw new _mastra_core_storage.KnowledgeNotFoundError("record", input.id);
+		(0, _mastra_core_storage.assertKnowledgeScopeWithinCeiling)(record.scope, input.maxScope);
+		(0, _mastra_core_storage.assertKnowledgeCeilingRaised)(record.maxScope, input.maxScope);
+		await (await this.#knowledge()).updateOne({ id: input.id }, { $set: { maxScope: input.maxScope ?? null } });
+		return {
+			...record,
+			maxScope: input.maxScope
+		};
+	}
+	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 }
+			]
+		}).sort({ updatedAt: -1 }).limit(limit).toArray()).map((row) => ({
+			type: "node",
+			id: row.id,
+			recordId: row.id,
+			name: row.name,
+			text: row.content ? `${row.name}\n${row.content}` : row.name,
+			scope: cloneScope(row.scope)
+		}));
+		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: record.node,
+					name: parentVisible ? parent.name : "(private node)",
+					text: record.text,
+					scope: cloneScope(record.scope)
+				});
+			}
+		}
+		return results.slice(0, limit);
+	}
+	async getCurationCursor(input) {
+		const row = await (await this.#cursors()).findOne(input);
+		return row ? {
+			sourceThreadId: row.sourceThreadId,
+			agent: row.agent,
+			lastKnowledgeId: row.lastKnowledgeId,
+			updatedAt: new Date(row.updatedAt)
+		} : null;
+	}
+	async advanceCurationCursor(input) {
+		const row = await (await this.#cursors()).findOneAndUpdate({
+			sourceThreadId: input.sourceThreadId,
+			agent: input.agent
+		}, {
+			$max: { lastKnowledgeId: input.lastKnowledgeId },
+			$set: { updatedAt: /* @__PURE__ */ new Date() },
+			$setOnInsert: {
+				sourceThreadId: input.sourceThreadId,
+				agent: input.agent
+			}
+		}, {
+			upsert: true,
+			returnDocument: "after"
+		});
+		return {
+			sourceThreadId: row.sourceThreadId,
+			agent: row.agent,
+			lastKnowledgeId: row.lastKnowledgeId,
+			updatedAt: new Date(row.updatedAt)
+		};
+	}
+	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,
+			createdAt: new Date(row.createdAt)
+		}));
+	}
+	async listSemanticOutbox(input = {}) {
+		const filter = {
+			...input.status ? { status: input.status } : {},
+			...input.scope ? { scopeKey: { $in: visibleScopeKeys(input.scope) } } : {}
+		};
+		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) } } : {}
+			};
+			const limit = input.limit ?? 100;
+			const candidates = await collection.find(filter, sessionOptions(session)).sort({
+				createdAt: 1,
+				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);
+			}
+			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
+		} });
+	}
+	async #collection(name) {
+		return this.#connector.getCollection(name);
+	}
+	#nodes() {
+		return this.#collection(_mastra_core_storage.TABLE_KNOWLEDGE_NODES);
+	}
+	#knowledge() {
+		return this.#collection(_mastra_core_storage.TABLE_KNOWLEDGE_RECORDS);
+	}
+	#mentions() {
+		return this.#collection(_mastra_core_storage.TABLE_KNOWLEDGE_MENTIONS);
+	}
+	#cursors() {
+		return this.#collection(_mastra_core_storage.TABLE_KNOWLEDGE_CURSORS);
+	}
+	#activityCollection() {
+		return this.#collection(_mastra_core_storage.TABLE_KNOWLEDGE_ACTIVITY);
+	}
+	#outboxCollection() {
+		return this.#collection(_mastra_core_storage.TABLE_KNOWLEDGE_SEMANTIC_OUTBOX);
+	}
+	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) {
+		for (let length = scope.length; length > 0; length--) {
+			const node = await this.#getNodeByName(name, scope.slice(0, length), session);
+			if (node) {
+				const terminal = await this.#resolveTerminalNode(node.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;
+	}
+	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;
+	}
+	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
+		};
+	}
+	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
+			});
+		}
+	}
+	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;
+		}
+	}
+	#escapeRegex(value) {
+		return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+	}
+};
+//#endregion
 //#region src/storage/domains/mcp-clients/index.ts
 /**
 * Snapshot config fields that live on MCP client version documents.
@@ -10977,6 +11780,7 @@ var MongoDBStore = class extends _mastra_core_storage.MastraCompositeStore {
 			indexes: config.indexes
 		};
 		const memory = new MemoryStorageMongoDB(domainConfig);
+		const knowledge = new KnowledgeMongoDB(domainConfig);
 		const notifications = new NotificationsMongoDB(domainConfig);
 		const scores = new ScoresStorageMongoDB(domainConfig);
 		const workflows = new WorkflowsStorageMongoDB(domainConfig);
@@ -10996,6 +11800,7 @@ var MongoDBStore = class extends _mastra_core_storage.MastraCompositeStore {
 		const workflowDefinitions = new MongoDBWorkflowDefinitionsStore(domainConfig);
 		this.stores = {
 			memory,
+			knowledge,
 			notifications,
 			scores,
 			workflows,
@@ -11133,6 +11938,7 @@ Example Complex Query:
 }`;
 //#endregion
 exports.BackgroundTasksStorageMongoDB = BackgroundTasksStorageMongoDB;
+exports.KnowledgeMongoDB = KnowledgeMongoDB;
 exports.MONGODB_PROMPT = MONGODB_PROMPT;
 exports.MemoryStorageMongoDB = MemoryStorageMongoDB;
 exports.MongoDBAgentsStorage = MongoDBAgentsStorage;