@romiluz/clawmongo 2026.3.31 → 2026.3.32

package/dist/{mongodb-manager-BV_j5Yce.js → mongodb-manager--Zs-oIkk.js}

@@ -2,13 +2,13 @@ import { n as redactSensitiveText } from "./redact-BDinS1q9.js";
 import { o as createSubsystemLogger, yi as resolveAgentWorkspaceDir } from "./env-DSps_l9i.js";
 import { c as resolveSessionTranscriptsDirForAgent } from "./paths-Cl8Vw1Jj.js";
 import { a as listMemoryFiles, n as chunkMarkdown, o as normalizeExtraMemoryPaths, r as hashText, t as buildFileEntry } from "./internal-CQyd3YZq.js";
-import { C as relationsCollection, D as structuredMemCollection, E as relevanceRunsCollection, S as queryCacheCollection, _ as metaCollection, a as ensureCollections, b as proceduresCollection, c as ensureStandardIndexes, d as episodesCollection, f as eventsCollection, g as kbCollection, h as kbChunksCollection, k as telemetryCollection, l as entitiesCollection, m as ingestRunsCollection, n as chunksCollection, p as filesCollection, r as detectCapabilities, s as ensureSearchIndexes, u as entityLinksCollection, x as projectionRunsCollection } from "./mongodb-schema-GMwMn5aY.js";
+import { C as relationsCollection, D as structuredMemCollection, E as relevanceRunsCollection, S as queryCacheCollection, _ as metaCollection, a as ensureCollections, b as proceduresCollection, c as ensureStandardIndexes, d as episodesCollection, f as eventsCollection, g as kbCollection, h as kbChunksCollection, k as telemetryCollection, l as entitiesCollection, m as ingestRunsCollection, n as chunksCollection, p as filesCollection, r as detectCapabilities, s as ensureSearchIndexes, u as entityLinksCollection, x as projectionRunsCollection } from "./mongodb-schema-CJHFxfrx.js";
 import { t as resolveScopeRef } from "./mongodb-scope-BgB-USEx.js";
-import { n as writeStructuredMemory, t as searchStructuredMemory } from "./mongodb-structured-memory-B-kVmcth.js";
-import { a as normalizeSearchResults, n as buildVectorSearchStage, o as rrfScore, r as mongoSearch, s as MongoDBRelevanceRuntime } from "./mongodb-search-DLeKW4uS.js";
-import { n as writeProcedure, t as searchProcedures } from "./mongodb-procedures-DnwLD-cO.js";
-import { t as getMemoryStats } from "./mongodb-analytics-DrEyw-zF.js";
-import { t as searchKB } from "./mongodb-kb-search-Cgkz-lmv.js";
+import { n as writeStructuredMemory, t as searchStructuredMemory } from "./mongodb-structured-memory-BlYP5KWD.js";
+import { a as normalizeSearchResults, n as buildVectorSearchStage, o as rrfScore, r as mongoSearch, s as MongoDBRelevanceRuntime } from "./mongodb-search-BHRn7dF1.js";
+import { n as writeProcedure, t as searchProcedures } from "./mongodb-procedures-CobuqpD2.js";
+import { t as getMemoryStats } from "./mongodb-analytics-qg8zwvek.js";
+import { t as searchKB } from "./mongodb-kb-search-CeBKQO-B.js";
 import path from "node:path";
 import { createHash, randomUUID } from "node:crypto";
 import fs from "node:fs/promises";
@@ -167,6 +167,16 @@ async function getEventsByTimeRange(params) {
 		_id: 1
 	}).limit(limit ?? 1e3).toArray();
 }
+async function getEventsBySession(params) {
+	const { db, prefix, agentId, sessionId, limit } = params;
+	return await eventsCollection(db, prefix).find({
+		agentId,
+		sessionId
+	}).sort({
+		timestamp: 1,
+		_id: 1
+	}).limit(limit ?? 1e3).toArray();
+}
 async function markEventsProjected(params) {
 	const { db, prefix, eventIds } = params;
 	if (eventIds.length === 0) return 0;
@@ -1275,6 +1285,16 @@ async function checkAutoEpisodeTriggers(params) {
 //#endregion
 //#region src/memory/mongodb-retrieval-planner.ts
 const log$10 = createSubsystemLogger("memory:mongodb:planner");
+function classifyRetrievalQuery(params) {
+	const query = params.query.trim().toLowerCase();
+	if (!query) return "direct";
+	if (params.hasTimeRange || TIME_REGEXES.some((re) => re.test(query))) return "temporal";
+	if (params.hasScopes) return "scoped";
+	if (/\b(compare|comparison|difference|different|vs|versus|better than)\b/i.test(query)) return "comparison";
+	if (/\b(family|alternatives?|similar|related tools|ecosystem|what else|options|which tools|all the tools|all tools)\b/i.test(query) || /כל המשפחה|עוד כלים|חלופות|מה עוד/u.test(query)) return "family";
+	if (/\b(because|why did|how did|lead to|after that|before that|then what)\b/i.test(query)) return "multi-hop";
+	return "direct";
+}
 function buildKeywordRegexes(keywords) {
 	return keywords.map((kw) => new RegExp(`\\b${kw.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\b`, "i"));
 }
@@ -1359,6 +1379,31 @@ const PROCEDURAL_REGEXES = buildKeywordRegexes([
 	"steps",
 	"checklist"
 ]);
+const FAMILY_REGEXES = buildKeywordRegexes([
+	"family",
+	"alternatives",
+	"alternative",
+	"similar",
+	"related",
+	"what else",
+	"ecosystem",
+	"other tools"
+]);
+const COMPARISON_REGEXES = buildKeywordRegexes([
+	"compare",
+	"comparison",
+	"difference",
+	"versus",
+	"vs"
+]);
+const MULTI_HOP_REGEXES = buildKeywordRegexes([
+	"and then",
+	"after that",
+	"followed by",
+	"step by step",
+	"how did",
+	"why did"
+]);
 const PATH_PRIORITY = {
 	"active-critical": 0,
 	procedural: 1,
@@ -1594,6 +1639,7 @@ function planRetrieval(query, context) {
 	try {
 		if (!query.trim()) return {
 			paths: context.availablePaths.has("hybrid") ? ["hybrid"] : [],
+			classification: "direct",
 			confidence: "low",
 			reasoning: "empty query"
 		};
@@ -1656,9 +1702,18 @@ function planRetrieval(query, context) {
 		}
 		scores.hybrid += 1;
 		const finalPaths = Object.entries(scores).filter(([path]) => context.availablePaths.has(path)).toSorted((a, b) => b[1] - a[1] || PATH_PRIORITY[a[0]] - PATH_PRIORITY[b[0]]).map(([path]) => path);
+		const classification = (() => {
+			if (COMPARISON_REGEXES.some((re) => re.test(query))) return "comparison";
+			if (FAMILY_REGEXES.some((re) => re.test(query))) return "family";
+			if (timeConstraint) return "temporal";
+			if (structuredConstraint?.hard === true || kbConstraint?.hard === true || !!entityConstraint) return "scoped";
+			if (MULTI_HOP_REGEXES.some((re) => re.test(query)) || /\b(and|then)\b/i.test(query) || (query.match(/\?/g)?.length ?? 0) > 1) return "multi-hop";
+			return "direct";
+		})();
 		const topScore = scores[finalPaths[0]] ?? 0;
 		return {
 			paths: finalPaths,
+			classification,
 			confidence: topScore >= 3 ? "high" : topScore >= 2 ? "medium" : "low",
 			reasoning: reasons.length > 0 ? reasons.join("; ") : "no strong signals, defaulting to hybrid",
 			...Object.keys(constraints).length > 0 ? { constraints } : {}
@@ -2609,10 +2664,12 @@ async function checkCache(params) {
 	const cacheStart = Date.now();
 	const col = queryCacheCollection(db, prefix);
 	const qHash = hashQuery(normalized);
+	const requestSignature = params.requestSignature ?? "default";
 	const now = /* @__PURE__ */ new Date();
 	try {
 		const exact = await col.findOne({
 			queryHash: qHash,
+			requestSignature,
 			agentId,
 			scope,
 			scopeRef,
@@ -2670,7 +2727,8 @@ async function checkCache(params) {
 			filter: {
 				agentId,
 				scope,
-				scopeRef
+				scopeRef,
+				requestSignature
 			},
 			textFieldPath: "queryNorm"
 		});
@@ -2698,6 +2756,7 @@ async function checkCache(params) {
 				results: 1,
 				pathUsed: 1,
 				sourceScope: 1,
+				requestSignature: 1,
 				expiresAt: 1,
 				score: { $meta: "vectorSearchScore" }
 			} }
@@ -2757,14 +2816,17 @@ function writeCache(params) {
 	const now = /* @__PURE__ */ new Date();
 	const expiresAt = new Date(now.getTime() + ttlSec * 1e3);
 	const qHash = hashQuery(normalized);
+	const requestSignature = params.requestSignature ?? "default";
 	queryCacheCollection(db, prefix).updateOne({
 		queryHash: qHash,
+		requestSignature,
 		agentId,
 		scope,
 		scopeRef
 	}, {
 		$setOnInsert: {
 			queryNorm: normalized,
+			requestSignature,
 			createdAt: now,
 			hitCount: 0
 		},
@@ -3064,6 +3126,334 @@ async function crossEncoderRerank(params) {
 	}
 }
 //#endregion
+//#region src/memory/mongodb-search-executor.ts
+function sourcePreferencePaths(source) {
+	switch (source) {
+		case "conversation": return ["hybrid", "raw-window"];
+		case "reference": return ["kb"];
+		case "structured": return ["active-critical", "structured"];
+		case "procedural": return ["procedural"];
+		case "episodic": return ["episodic"];
+		case "graph": return ["graph"];
+	}
+}
+function selectPassPaths(params) {
+	const allowed = new Set(params.availablePaths);
+	if (params.timeRange) {
+		for (const path of allowed) if (![
+			"raw-window",
+			"hybrid",
+			"episodic"
+		].includes(path)) allowed.delete(path);
+	}
+	if (params.sourcePreference.length === 0) return allowed;
+	const preferredAllowed = new Set(params.sourcePreference.flatMap((source) => sourcePreferencePaths(source)));
+	const effectiveAllowed = new Set(Array.from(allowed).filter((path) => preferredAllowed.has(path)));
+	const preferredSource = params.sourcePreference[Math.min(params.pass - 1, params.sourcePreference.length - 1)];
+	const preferredPaths = sourcePreferencePaths(preferredSource).filter((path) => effectiveAllowed.has(path));
+	if (preferredPaths.length === 0 || params.pass > params.sourcePreference.length) return effectiveAllowed;
+	return new Set(preferredPaths);
+}
+function sortObject(value) {
+	if (Array.isArray(value)) return value.map(sortObject);
+	if (!value || typeof value !== "object") return value;
+	return Object.fromEntries(Object.entries(value).toSorted(([left], [right]) => left.localeCompare(right)).map(([key, entry]) => [key, sortObject(entry)]));
+}
+function buildMemorySearchRequestSignature(request) {
+	return JSON.stringify(sortObject({
+		query: request.query,
+		maxResults: request.maxResults,
+		minScore: request.minScore,
+		searchMode: request.searchMode,
+		sourcePreference: request.sourcePreference,
+		timeRange: request.timeRange,
+		needExactEvidence: request.needExactEvidence,
+		maxPasses: request.maxPasses,
+		conversationScope: request.conversationScope,
+		structuredScope: request.structuredScope,
+		referenceScope: request.referenceScope,
+		proceduralScope: request.proceduralScope
+	}));
+}
+function normalizeMemorySearchRequest(request) {
+	const requestedMode = request.searchMode ?? "auto";
+	const maxPasses = Math.max(1, Math.min(3, Math.trunc(request.maxPasses ?? {
+		direct: 1,
+		auto: 2,
+		agentic: 3
+	}[requestedMode])));
+	return {
+		...request,
+		searchMode: requestedMode,
+		maxPasses,
+		sourcePreference: request.sourcePreference ?? [
+			"conversation",
+			"structured",
+			"procedural",
+			"reference",
+			"episodic",
+			"graph"
+		]
+	};
+}
+function resolveExecutorTimeRange(request) {
+	const raw = request.timeRange;
+	if (!raw) return;
+	if (raw.preset) return resolveTimeRangePreset(raw.preset);
+	const start = raw.start ? new Date(raw.start) : void 0;
+	const end = raw.end ? new Date(raw.end) : void 0;
+	if (start && Number.isNaN(start.getTime()) || end && Number.isNaN(end.getTime()) || !start || !end) return;
+	return {
+		start,
+		end
+	};
+}
+function classifyExecutorSearch(request) {
+	return classifyRetrievalQuery({
+		query: request.query,
+		hasTimeRange: Boolean(request.timeRange),
+		hasScopes: Boolean(request.conversationScope || request.structuredScope || request.referenceScope || request.proceduralScope)
+	});
+}
+function uniqueQueries(values) {
+	const seen = /* @__PURE__ */ new Set();
+	const ordered = [];
+	for (const value of values) {
+		const trimmed = value.trim();
+		if (!trimmed) continue;
+		const normalized = trimmed.toLowerCase();
+		if (seen.has(normalized)) continue;
+		seen.add(normalized);
+		ordered.push(trimmed);
+	}
+	return ordered;
+}
+function buildExecutorPasses(request, classification) {
+	const passes = [{
+		pass: 1,
+		query: request.query,
+		reason: "original query",
+		variant: "original"
+	}];
+	if (!(request.searchMode === "agentic" || request.searchMode === "auto" && classification !== "direct") || request.maxPasses <= 1) return passes;
+	const expansionQueries = [];
+	switch (classification) {
+		case "family":
+			expansionQueries.push(`${request.query} alternatives`);
+			expansionQueries.push(`${request.query} related tools`);
+			break;
+		case "comparison":
+			expansionQueries.push(`${request.query} differences`);
+			expansionQueries.push(`${request.query} tradeoffs`);
+			break;
+		case "temporal":
+			expansionQueries.push(`${request.query} exact evidence`);
+			break;
+		case "scoped":
+			expansionQueries.push(`${request.query} exact match`);
+			break;
+		case "multi-hop":
+			expansionQueries.push(`${request.query} cause`);
+			expansionQueries.push(`${request.query} consequence`);
+			break;
+		case "direct":
+			if (request.needExactEvidence) expansionQueries.push(`${request.query} exact evidence`);
+			break;
+	}
+	const deduped = uniqueQueries(expansionQueries);
+	for (const query of deduped.slice(0, Math.max(0, request.maxPasses - 1))) passes.push({
+		pass: passes.length + 1,
+		query,
+		reason: classification === "family" ? "family expansion" : "agentic follow-up",
+		variant: classification === "multi-hop" ? "decomposition" : "family-expansion"
+	});
+	return passes;
+}
+function resultHasExactEvidence(result) {
+	if (result.canonicalId?.trim()) return true;
+	if (result.path.trim()) return true;
+	return false;
+}
+function searchResultIdentity(result) {
+	return result.canonicalId ?? `${result.path}:${result.startLine}:${result.endLine}`;
+}
+function computeEvidenceCoverage(results) {
+	if (results.length === 0) return "none";
+	const exactCount = results.filter(resultHasExactEvidence).length;
+	if (exactCount === results.length) return "direct";
+	if (exactCount > 0) return "partial";
+	return "indirect";
+}
+function applyHardConstraintRejections(params) {
+	const accepted = [];
+	const rejected = [];
+	for (const result of params.results) {
+		if (params.timeRange) {
+			if (!(result.timestamp instanceof Date)) {
+				rejected.push({
+					canonicalId: result.canonicalId,
+					path: result.path,
+					source: result.source,
+					reason: "missing timestamp for requested time range"
+				});
+				continue;
+			}
+			const ts = result.timestamp.getTime();
+			if (ts < params.timeRange.start.getTime() || ts > params.timeRange.end.getTime()) {
+				rejected.push({
+					canonicalId: result.canonicalId,
+					path: result.path,
+					source: result.source,
+					reason: "outside requested time range"
+				});
+				continue;
+			}
+		}
+		if (params.request.needExactEvidence && !resultHasExactEvidence(result)) {
+			rejected.push({
+				canonicalId: result.canonicalId,
+				path: result.path,
+				source: result.source,
+				reason: "missing exact evidence locator"
+			});
+			continue;
+		}
+		accepted.push(result);
+	}
+	return {
+		accepted,
+		rejected
+	};
+}
+function canUseLegacyFallback(request) {
+	return !(request.needExactEvidence || request.timeRange || request.conversationScope || request.structuredScope || request.referenceScope || request.proceduralScope);
+}
+function requestHasHardConstraints(request) {
+	return !canUseLegacyFallback(request);
+}
+function buildConstraintSummaries(request) {
+	const applied = [];
+	if (request.timeRange) {
+		if (request.timeRange.preset) applied.push(`timeRange:${request.timeRange.preset}`);
+		else if (request.timeRange.start && request.timeRange.end) applied.push(`timeRange:${request.timeRange.start}..${request.timeRange.end}`);
+	}
+	if (request.needExactEvidence) applied.push("needExactEvidence");
+	if (request.conversationScope?.sessionKey) applied.push(`conversationScope.sessionKey:${request.conversationScope.sessionKey}`);
+	if (request.structuredScope?.type) applied.push(`structuredScope.type:${request.structuredScope.type}`);
+	if (request.referenceScope?.category) applied.push(`referenceScope.category:${request.referenceScope.category}`);
+	if (request.referenceScope?.source) applied.push(`referenceScope.source:${request.referenceScope.source}`);
+	if (request.proceduralScope?.state) applied.push(`proceduralScope.state:${request.proceduralScope.state}`);
+	return applied;
+}
+function mergeMetadata(params) {
+	const pathsExecuted = Array.from(new Set(params.passes.flatMap((pass) => pass.metadata.pathsExecuted)));
+	const resultsByPath = params.passes.reduce((acc, pass) => {
+		for (const [path, count] of Object.entries(pass.metadata.resultsByPath)) acc[path] = (acc[path] ?? 0) + count;
+		return acc;
+	}, {});
+	return {
+		mode: params.request.searchMode,
+		classification: params.classification,
+		sourceOrder: params.request.sourcePreference,
+		passes: params.passes.map(({ metadata: _metadata, ...pass }) => pass),
+		queriesTried: params.passes.map((pass) => pass.query),
+		constraintsApplied: buildConstraintSummaries(params.request),
+		resultsRejected: params.resultsRejected,
+		evidenceCoverage: computeEvidenceCoverage(params.results),
+		pathsExecuted,
+		resultsByPath,
+		queryRewritten: params.passes.some((pass) => pass.metadata.queryRewritten),
+		reranked: params.passes.some((pass) => pass.metadata.reranked),
+		...params.noDirectEvidenceReason ? { noDirectEvidenceReason: params.noDirectEvidenceReason } : {},
+		...params.request.returnPlan && params.passes[0]?.metadata.plan ? { plan: params.passes[0].metadata.plan } : {}
+	};
+}
+function buildNoDirectEvidenceResponse(params) {
+	return {
+		results: [],
+		metadata: mergeMetadata({
+			request: params.request,
+			classification: params.classification,
+			passes: params.passes,
+			resultsRejected: params.resultsRejected,
+			results: [],
+			noDirectEvidenceReason: params.reason
+		})
+	};
+}
+async function executeMongoSearchPlan(params) {
+	const normalized = normalizeMemorySearchRequest(params.request);
+	const classification = classifyExecutorSearch(normalized);
+	const timeRange = resolveExecutorTimeRange(normalized);
+	const passPlans = buildExecutorPasses(normalized, classification);
+	const passes = [];
+	const allRejected = [];
+	const acceptedById = /* @__PURE__ */ new Map();
+	for (const passPlan of passPlans) {
+		const passPaths = selectPassPaths({
+			availablePaths: params.availablePaths,
+			sourcePreference: normalized.sourcePreference,
+			pass: passPlan.pass,
+			...timeRange ? { timeRange } : {}
+		});
+		const executed = await params.executePass({
+			pass: passPlan.pass,
+			query: passPlan.query,
+			availablePaths: passPaths,
+			...timeRange ? { timeRange } : {}
+		});
+		const filtered = applyHardConstraintRejections({
+			results: executed.results,
+			request: normalized,
+			...timeRange ? { timeRange } : {}
+		});
+		allRejected.push(...filtered.rejected);
+		for (const result of filtered.accepted) acceptedById.set(searchResultIdentity(result), result);
+		passes.push({
+			pass: passPlan.pass,
+			query: passPlan.query,
+			reason: passPlan.reason,
+			pathsExecuted: executed.metadata.pathsExecuted,
+			resultCount: filtered.accepted.length,
+			queryRewritten: executed.metadata.queryRewritten === true,
+			reranked: executed.metadata.reranked === true,
+			metadata: {
+				pathsExecuted: executed.metadata.pathsExecuted,
+				resultsByPath: executed.metadata.resultsByPath,
+				queryRewritten: executed.metadata.queryRewritten === true,
+				reranked: executed.metadata.reranked === true,
+				plan: {
+					paths: executed.metadata.plan.paths,
+					confidence: executed.metadata.plan.confidence,
+					reasoning: executed.metadata.plan.reasoning,
+					...executed.metadata.plan.constraints ? { constraints: executed.metadata.plan.constraints } : {}
+				}
+			}
+		});
+		const acceptedResults = Array.from(acceptedById.values());
+		const evidenceCoverage = computeEvidenceCoverage(acceptedResults);
+		if (acceptedResults.length > 0 && (classification === "direct" ? !normalized.needExactEvidence || evidenceCoverage === "direct" || evidenceCoverage === "partial" : classification === "family" || classification === "comparison" ? acceptedResults.length >= Math.min(normalized.maxResults ?? 10, 3) : !normalized.needExactEvidence || evidenceCoverage === "direct" || evidenceCoverage === "partial")) break;
+	}
+	const acceptedResults = Array.from(acceptedById.values());
+	if (normalized.needExactEvidence && acceptedResults.length === 0) return buildNoDirectEvidenceResponse({
+		request: normalized,
+		classification,
+		passes,
+		resultsRejected: allRejected,
+		reason: "No exact-evidence results survived the active constraints."
+	});
+	return {
+		results: acceptedResults,
+		metadata: mergeMetadata({
+			request: normalized,
+			classification,
+			passes,
+			resultsRejected: allRejected,
+			results: acceptedResults
+		})
+	};
+}
+//#endregion
 //#region src/memory/session-files.ts
 const log$2 = createSubsystemLogger("memory");
 async function listSessionFilesForAgent(agentId) {
@@ -3627,6 +4017,39 @@ function classifyQueryCacheSourceScope(results) {
 function resolveQueryCacheTtlSec(results, config) {
 	return collectSearchResultSources(results).has("reference") ? config.kbTtlSec : config.conversationTtlSec;
 }
+function normalizeSearchRequest(request) {
+	const query = request.query.trim();
+	return {
+		...request,
+		query,
+		searchMode: request.searchMode ?? "auto",
+		maxResults: request.maxResults ?? 10,
+		minScore: request.minScore ?? .1,
+		needExactEvidence: request.needExactEvidence === true,
+		returnPlan: request.returnPlan === true,
+		...request.maxPasses != null ? { maxPasses: Math.max(1, Math.min(3, request.maxPasses)) } : {}
+	};
+}
+function emptySearchMetadata(request) {
+	return {
+		mode: request.searchMode ?? "auto",
+		classification: "direct",
+		sourceOrder: request.sourcePreference ?? [
+			"conversation",
+			"structured",
+			"reference"
+		],
+		passes: [],
+		queriesTried: [],
+		constraintsApplied: [],
+		resultsRejected: [],
+		evidenceCoverage: "none",
+		pathsExecuted: [],
+		resultsByPath: {},
+		queryRewritten: false,
+		reranked: false
+	};
+}
 /**
 * Heuristic reranker for v2 search results.
 * - Source diversity penalty: no more than 2 results from the same source at the top
@@ -3839,21 +4262,32 @@ var MongoDBMemoryManager = class MongoDBMemoryManager {
 		log.info(`ready: profile=${mongoCfg.deploymentProfile} embedding=${mongoCfg.embeddingMode} fusion=${mongoCfg.fusionMethod} caps=${JSON.stringify(capabilities)}`);
 		return manager;
 	}
-	buildConversationChunkFilter() {
-		return {
+	buildConversationChunkFilter(params) {
+		const filter = {
 			source: { $in: ["conversation", "sessions"] },
 			agentId: this.agentId,
 			status: { $ne: "deleted" }
 		};
+		if (params?.sessionKey) filter.sessionId = params.sessionKey;
+		if (params?.timeRange) filter.timestamp = {
+			$gte: params.timeRange.start,
+			$lte: params.timeRange.end
+		};
+		return filter;
 	}
-	buildBridgeChunkFilter() {
-		return {
+	buildBridgeChunkFilter(params) {
+		const filter = {
 			source: { $in: ["conversation", "memory"] },
 			agentId: this.agentId,
 			scope: "workspace",
 			scopeRef: this.workspaceScopeRef,
 			status: { $ne: "deleted" }
 		};
+		if (params?.timeRange) filter.updatedAt = {
+			$gte: params.timeRange.start,
+			$lte: params.timeRange.end
+		};
+		return filter;
 	}
 	getBridgeChunkBudget(maxResults) {
 		return Math.max(2, Math.ceil(maxResults / 3));
@@ -4017,21 +4451,33 @@ var MongoDBMemoryManager = class MongoDBMemoryManager {
 		return finalResults;
 	}
 	async search(query, opts) {
-		const cleaned = query.trim();
-		if (!cleaned) {
+		return (await this.searchDetailed({
+			query,
+			maxResults: opts?.maxResults,
+			minScore: opts?.minScore,
+			...opts?.sessionKey ? { conversationScope: { sessionKey: opts.sessionKey } } : {}
+		})).results;
+	}
+	async searchDetailed(request) {
+		const normalized = normalizeSearchRequest(request);
+		if (!normalized.query) {
 			this.setLastSearchMode("v2:empty-query");
-			return [];
+			return {
+				results: [],
+				metadata: emptySearchMetadata(normalized)
+			};
 		}
 		const mongoCfg = this.config.mongodb;
-		const maxResults = opts?.maxResults ?? 10;
-		const minScore = opts?.minScore ?? .1;
 		const activeSources = getActiveSources(mongoCfg.sources, mongoCfg.kb.enabled);
 		const availablePaths = this.buildV2AvailablePaths(activeSources);
+		const cacheQuery = normalized.query;
+		const requestSignature = buildMemorySearchRequestSignature(normalized);
 		if (mongoCfg.cache.enabled) {
 			const cacheResult = await checkCache({
 				db: this.db,
 				prefix: this.prefix,
-				query: cleaned,
+				query: cacheQuery,
+				requestSignature,
 				agentId: this.agentId,
 				scope: "agent",
 				scopeRef: this.agentScopeRef,
@@ -4042,89 +4488,129 @@ var MongoDBMemoryManager = class MongoDBMemoryManager {
 					pathUsed: cacheResult.pathUsed,
 					sourceScope: cacheResult.sourceScope
 				});
-				return cacheResult.results;
+				const executorRequest = normalizeMemorySearchRequest(normalized);
+				const classification = classifyExecutorSearch(executorRequest);
+				const cachedPaths = cacheResult.pathUsed ? cacheResult.pathUsed.split(",").filter(Boolean) : [];
+				const plannedPasses = buildExecutorPasses(executorRequest, classification).map((pass, index) => ({
+					pass: pass.pass,
+					query: pass.query,
+					reason: index === 0 ? `${pass.reason} (cache hit)` : pass.reason,
+					pathsExecuted: index === 0 ? cachedPaths : [],
+					resultCount: index === 0 ? cacheResult.results.length : 0,
+					queryRewritten: false,
+					reranked: false
+				}));
+				return {
+					results: cacheResult.results,
+					metadata: {
+						...emptySearchMetadata(normalized),
+						classification,
+						passes: plannedPasses,
+						queriesTried: plannedPasses.map((pass) => pass.query),
+						constraintsApplied: [...buildConstraintSummaries(executorRequest), ...requestHasHardConstraints(normalized) ? ["cache-hit-constrained"] : []],
+						evidenceCoverage: computeEvidenceCoverage(cacheResult.results),
+						pathsExecuted: cachedPaths
+					}
+				};
 			}
 		}
 		const searchStart = Date.now();
-		try {
-			const v2 = await searchV2(this.db, this.prefix, cleaned, this.agentId, {
-				availablePaths,
+		const response = await executeMongoSearchPlan({
+			request: normalized,
+			availablePaths,
+			executePass: async ({ query: passQuery, availablePaths: passPaths, timeRange }) => searchV2(this.db, this.prefix, passQuery, this.agentId, {
+				availablePaths: passPaths,
 				hasEpisodes: mongoCfg.episodes.enabled,
 				hasGraphData: mongoCfg.graph.enabled,
-				maxResults,
+				maxResults: normalized.maxResults,
 				searchOptions: {
-					minScore,
-					sessionKey: opts?.sessionKey,
+					minScore: normalized.minScore,
+					sessionKey: normalized.conversationScope?.sessionKey,
 					numCandidates: mongoCfg.numCandidates,
 					capabilities: this.capabilities,
 					fusionMethod: mongoCfg.fusionMethod,
 					embeddingMode: mongoCfg.embeddingMode,
-					conversationFilter: this.buildConversationChunkFilter(),
-					bridgeFilter: activeSources.conversation ? this.buildBridgeChunkFilter() : void 0,
-					bridgeMaxResults: this.getBridgeChunkBudget(maxResults),
+					conversationFilter: this.buildConversationChunkFilter({
+						sessionKey: normalized.conversationScope?.sessionKey,
+						...timeRange ? { timeRange } : {}
+					}),
+					bridgeFilter: activeSources.conversation ? this.buildBridgeChunkFilter(timeRange ? { timeRange } : void 0) : void 0,
+					bridgeMaxResults: this.getBridgeChunkBudget(normalized.maxResults ?? 10),
 					scope: "agent",
 					scopeRef: this.agentScopeRef,
 					rerankConfig: mongoCfg.reranking,
 					queryRewriteConfig: mongoCfg.queryRewriting,
 					enableContiguousMerge: mongoCfg.enableContiguousMerge,
-					enableContextExpansion: mongoCfg.enableContextExpansion
+					enableContextExpansion: mongoCfg.enableContextExpansion,
+					...normalized.sourcePreference ? { sourcePreference: normalized.sourcePreference } : {},
+					...timeRange ? { explicitTimeRange: timeRange } : {},
+					...normalized.structuredScope ? { structuredScope: normalized.structuredScope } : {},
+					...normalized.referenceScope ? { referenceScope: normalized.referenceScope } : {},
+					...normalized.proceduralScope ? { proceduralScope: normalized.proceduralScope } : {}
 				}
-			});
-			emitTelemetry(this.db, this.prefix, {
-				meta: {
+			})
+		});
+		emitTelemetry(this.db, this.prefix, {
+			meta: {
+				agentId: this.agentId,
+				operation: "search"
+			},
+			durationMs: Date.now() - searchStart,
+			ok: response.results.length > 0,
+			pathUsed: response.metadata.pathsExecuted.join(","),
+			resultCount: response.results.length,
+			topScore: response.results[0]?.score ?? 0,
+			fusionMethod: mongoCfg.fusionMethod
+		});
+		const v2Details = {
+			classification: response.metadata.classification,
+			sourceOrder: response.metadata.sourceOrder,
+			constraintsApplied: response.metadata.constraintsApplied,
+			pathsExecuted: response.metadata.pathsExecuted,
+			resultsByPath: response.metadata.resultsByPath,
+			evidenceCoverage: response.metadata.evidenceCoverage
+		};
+		if (response.results.length > 0) {
+			this.setLastSearchMode("v2", v2Details);
+			if (mongoCfg.cache.enabled) {
+				const sourceScope = classifyQueryCacheSourceScope(response.results);
+				const ttlSec = resolveQueryCacheTtlSec(response.results, mongoCfg.cache);
+				writeCache({
+					db: this.db,
+					prefix: this.prefix,
+					query: cacheQuery,
+					requestSignature,
 					agentId: this.agentId,
-					operation: "search"
-				},
-				durationMs: Date.now() - searchStart,
-				ok: v2.results.length > 0,
-				pathUsed: v2.metadata.pathsExecuted.join(","),
-				resultCount: v2.results.length,
-				topScore: v2.results[0]?.score ?? 0,
-				fusionMethod: mongoCfg.fusionMethod
-			});
-			const v2Details = {
-				plan: v2.metadata.plan.paths,
-				confidence: v2.metadata.plan.confidence,
-				constraints: v2.metadata.plan.constraints,
-				pathsExecuted: v2.metadata.pathsExecuted,
-				resultsByPath: v2.metadata.resultsByPath
-			};
-			if (v2.results.length > 0) {
-				this.setLastSearchMode("v2", v2Details);
-				if (mongoCfg.cache.enabled) {
-					const sourceScope = classifyQueryCacheSourceScope(v2.results);
-					const ttlSec = resolveQueryCacheTtlSec(v2.results, mongoCfg.cache);
-					writeCache({
-						db: this.db,
-						prefix: this.prefix,
-						query: cleaned,
-						agentId: this.agentId,
-						scope: "agent",
-						scopeRef: this.agentScopeRef,
-						results: v2.results,
-						pathUsed: v2.metadata.pathsExecuted.join(","),
-						sourceScope,
-						ttlSec
-					});
-				}
-				return v2.results;
+					scope: "agent",
+					scopeRef: this.agentScopeRef,
+					results: response.results,
+					pathUsed: response.metadata.pathsExecuted.join(","),
+					sourceScope,
+					ttlSec
+				});
 			}
-			const fallbackResults = await this.legacySearch(cleaned, opts);
-			this.setLastSearchMode("v2->legacy-empty", {
-				...v2Details,
-				fallbackResults: fallbackResults.length
-			});
-			return fallbackResults;
-		} catch (err) {
-			const message = err instanceof Error ? err.message : String(err);
-			log.warn(`planner search failed, falling back to legacy search: ${message}`);
-			const fallbackResults = await this.legacySearch(cleaned, opts);
-			this.setLastSearchMode("v2->legacy-error", {
-				error: message,
-				fallbackResults: fallbackResults.length
-			});
-			return fallbackResults;
+			return response;
+		}
+		if (requestHasHardConstraints(normalized)) {
+			this.setLastSearchMode("v2:constrained-empty", v2Details);
+			return response;
 		}
+		const fallbackResults = await this.legacySearch(normalized.query, {
+			maxResults: normalized.maxResults,
+			minScore: normalized.minScore,
+			sessionKey: normalized.conversationScope?.sessionKey
+		});
+		this.setLastSearchMode("v2->legacy-empty", {
+			...v2Details,
+			fallbackResults: fallbackResults.length
+		});
+		return {
+			results: fallbackResults,
+			metadata: {
+				...response.metadata,
+				pathsExecuted: response.metadata.pathsExecuted.length ? response.metadata.pathsExecuted : ["legacy"]
+			}
+		};
 	}
 	async relevanceExplain(params) {
 		if (!this.relevance) throw new Error("relevance runtime is unavailable");
@@ -4904,7 +5390,7 @@ var MongoDBMemoryManager = class MongoDBMemoryManager {
 		if (hoursSinceRefresh < autoRefreshHours) return;
 		log.info(`KB auto-refresh: ${hoursSinceRefresh.toFixed(1)}h since last import, refreshing ${paths.length} paths`);
 		try {
-			const { ingestFilesToKB } = await import("./mongodb-kb-DUUWKxNi.js");
+			const { ingestFilesToKB } = await import("./mongodb-kb-CumfgJ4z.js");
 			const result = await ingestFilesToKB({
 				db: this.db,
 				prefix: this.prefix,
@@ -4979,7 +5465,7 @@ var MongoDBMemoryManager = class MongoDBMemoryManager {
 	}
 	async writeStructuredMemory(entry) {
 		const mongoCfg = this.config.mongodb;
-		const { writeStructuredMemory: writeFn } = await import("./mongodb-structured-memory-0q2ekhJA.js");
+		const { writeStructuredMemory: writeFn } = await import("./mongodb-structured-memory-D4lNdWB9.js");
 		return writeFn({
 			db: this.db,
 			prefix: this.prefix,
@@ -4993,7 +5479,7 @@ var MongoDBMemoryManager = class MongoDBMemoryManager {
 	}
 	async writeProcedure(entry) {
 		const mongoCfg = this.config.mongodb;
-		const { writeProcedure: writeFn } = await import("./mongodb-procedures-Cw_cRVPq.js");
+		const { writeProcedure: writeFn } = await import("./mongodb-procedures-DAM6zeem.js");
 		return writeFn({
 			db: this.db,
 			prefix: this.prefix,
@@ -5189,6 +5675,25 @@ var MongoDBMemoryManager = class MongoDBMemoryManager {
 		}
 	}
 };
+function pathMatchesSourcePreference(path, source) {
+	switch (source) {
+		case "conversation": return path === "hybrid" || path === "raw-window";
+		case "reference": return path === "kb";
+		case "structured": return path === "structured" || path === "active-critical";
+		case "procedural": return path === "procedural";
+		case "episodic": return path === "episodic";
+		case "graph": return path === "graph";
+		default: return false;
+	}
+}
+function reorderPathsBySourcePreference(paths, sourcePreference) {
+	if (!sourcePreference || sourcePreference.length === 0) return paths;
+	return [...paths].toSorted((left, right) => {
+		const leftRank = sourcePreference.findIndex((source) => pathMatchesSourcePreference(left, source));
+		const rightRank = sourcePreference.findIndex((source) => pathMatchesSourcePreference(right, source));
+		return (leftRank === -1 ? sourcePreference.length : leftRank) - (rightRank === -1 ? sourcePreference.length : rightRank);
+	});
+}
 function graphRelationPriority(type) {
 	switch (type) {
 		case "works_on":
@@ -5260,22 +5765,21 @@ async function searchV2(db, prefix, query, agentId, context) {
 		const maxResults = context.maxResults ?? 20;
 		const minScore = context.searchOptions?.minScore ?? .1;
 		const numCandidates = context.searchOptions?.numCandidates ?? 200;
-		const capabilities = context.searchOptions?.capabilities ?? {
-			vectorSearch: true,
-			textSearch: true,
-			scoreFusion: true,
-			rankFusion: false
-		};
+		const capabilities = context.searchOptions?.capabilities ?? await detectCapabilities(db, `${prefix}chunks`);
 		const fusionMethod = context.searchOptions?.fusionMethod ?? "scoreFusion";
 		const embeddingMode = context.searchOptions?.embeddingMode ?? "automated";
 		const bridgeMaxResults = context.searchOptions?.bridgeMaxResults ?? Math.max(2, Math.ceil(maxResults / 3));
 		const allowHybridBackstop = context.searchOptions?.allowHybridBackstop ?? true;
-		const plan = planRetrieval(query, {
+		const rawPlan = planRetrieval(query, {
 			availablePaths: context.availablePaths,
 			knownEntityNames: graphQueryCandidates,
 			hasEpisodes: context.hasEpisodes,
 			hasGraphData: context.hasGraphData
 		});
+		const plan = {
+			...rawPlan,
+			paths: reorderPathsBySourcePreference(rawPlan.paths, context.searchOptions?.sourcePreference)
+		};
 		const qrConfig = context.searchOptions?.queryRewriteConfig;
 		let searchQuery = query;
 		let wasQueryRewritten = false;
@@ -5293,22 +5797,37 @@ async function searchV2(db, prefix, query, agentId, context) {
 			}
 		}
 		const constrainedGraphCandidates = plan.constraints?.entities?.names && plan.constraints.entities.names.length > 0 ? plan.constraints.entities.names : graphQueryCandidates;
-		const timeRange = plan.constraints?.timeRange ? resolveTimeRangePreset(plan.constraints.timeRange.preset) : void 0;
+		const timeRange = context.searchOptions?.explicitTimeRange ?? (plan.constraints?.timeRange ? resolveTimeRangePreset(plan.constraints.timeRange.preset) : void 0);
 		const structuredFilter = {
 			agentId,
-			...plan.constraints?.structured?.type ? { type: plan.constraints.structured.type } : {}
+			scope,
+			scopeRef: agentScopeRef,
+			...plan.constraints?.structured?.type ? { type: plan.constraints.structured.type } : {},
+			...context.searchOptions?.structuredScope?.type ? { type: context.searchOptions.structuredScope.type } : {},
+			...context.searchOptions?.structuredScope?.state ? { state: Array.isArray(context.searchOptions.structuredScope.state) ? context.searchOptions.structuredScope.state : context.searchOptions.structuredScope.state } : {},
+			...context.searchOptions?.structuredScope?.salience?.length ? { salience: context.searchOptions.structuredScope.salience } : {}
 		};
 		const activeCriticalFilter = {
 			agentId,
+			scope,
+			scopeRef: agentScopeRef,
 			state: "active",
 			salience: plan.constraints?.activeCritical?.salience ?? ["critical", "high"],
 			currentOnly: true
 		};
 		const proceduralFilter = {
 			agentId,
-			state: "active"
+			scope,
+			scopeRef: agentScopeRef,
+			state: context.searchOptions?.proceduralScope?.state ?? "active",
+			...context.searchOptions?.proceduralScope?.intentTags?.length ? { intentTags: context.searchOptions.proceduralScope.intentTags } : {}
+		};
+		const kbFilter = {
+			...plan.constraints?.kb?.source ? { source: plan.constraints.kb.source } : {},
+			...context.searchOptions?.referenceScope?.source ? { source: context.searchOptions.referenceScope.source } : {},
+			...context.searchOptions?.referenceScope?.category ? { category: context.searchOptions.referenceScope.category } : {},
+			...context.searchOptions?.referenceScope?.tags?.length ? { tags: context.searchOptions.referenceScope.tags } : {}
 		};
-		const kbFilter = plan.constraints?.kb ? plan.constraints.kb.source ? { source: plan.constraints.kb.source } : {} : void 0;
 		const results = [];
 		const pathsExecuted = [];
 		const resultsByPath = {};
@@ -5345,8 +5864,15 @@ async function searchV2(db, prefix, query, agentId, context) {
 						return [];
 					});
 					break;
-				case "raw-window":
-					pathResults = [...await getEventsByTimeRange({
+				case "raw-window": {
+					const rawWindowLimit = 50;
+					pathResults = [...context.searchOptions?.sessionKey ? await getEventsBySession({
+						db,
+						prefix,
+						agentId,
+						sessionId: context.searchOptions.sessionKey,
+						limit: rawWindowLimit
+					}) : await getEventsByTimeRange({
 						db,
 						prefix,
 						agentId,
@@ -5354,7 +5880,7 @@ async function searchV2(db, prefix, query, agentId, context) {
 						end: timeRange?.end ?? /* @__PURE__ */ new Date(),
 						scope,
 						scopeRef: agentScopeRef,
-						limit: 50
+						limit: rawWindowLimit
 					})].toSorted((a, b) => b.timestamp.getTime() - a.timestamp.getTime()).map((e, i) => ({
 						canonicalId: e.eventId,
 						path: `events/${e.eventId}`,
@@ -5369,6 +5895,7 @@ async function searchV2(db, prefix, query, agentId, context) {
 						timestamp: e.timestamp
 					}));
 					break;
+				}
 				case "graph":
 					if (constrainedGraphCandidates.length > 0) {
 						const entity = pickBestEntityMatch((await Promise.all(constrainedGraphCandidates.slice(0, 4).map((name) => findEntitiesByName({
@@ -5479,7 +6006,7 @@ async function searchV2(db, prefix, query, agentId, context) {
 					pathResults = await searchKB(kbChunksCollection(db, prefix), searchQuery, null, {
 						maxResults: Math.max(3, Math.floor((context.maxResults ?? 10) / 3)),
 						minScore,
-						...kbFilter ? { filter: kbFilter } : {},
+						...Object.keys(kbFilter).length > 0 ? { filter: kbFilter } : {},
 						numCandidates,
 						vectorIndexName: `${prefix}kb_chunks_vector`,
 						textIndexName: `${prefix}kb_chunks_text`,