@agentmemory/agentmemory 0.9.31 → 0.9.32

package/dist/index.mjs

@@ -80,53 +80,120 @@ function warnIfPremiumModel(env, envName, model) {
 	warnPremiumModelShown = true;
 	process.stderr.write(`[agentmemory] ${envName}=${model} is in the premium tier. Background compression on this model can cost $5+/day under active use. Cheaper alternatives with comparable quality for memory compression: deepseek/deepseek-v4-flash-0731, deepseek/deepseek-v4-pro, qwen/qwen3-coder. See README "Cost-aware model selection" for the full table. Set AGENTMEMORY_SUPPRESS_COST_WARNING=1 to silence.\n`);
 }
+const LLM_PROVIDER_NAMES = [
+	"anthropic",
+	"openai",
+	"gemini",
+	"openrouter",
+	"minimax"
+];
+const LLM_PROVIDER_KEYS = {
+	anthropic: ["ANTHROPIC_API_KEY"],
+	openai: ["OPENAI_API_KEY"],
+	gemini: ["GEMINI_API_KEY", "GOOGLE_API_KEY"],
+	openrouter: ["OPENROUTER_API_KEY"],
+	minimax: ["MINIMAX_API_KEY"]
+};
+const REMOTE_EMBEDDING_PROVIDER_KEYS = {
+	gemini: ["GEMINI_API_KEY"],
+	openai: ["OPENAI_API_KEY", "OPENAI_EMBEDDING_API_KEY"],
+	voyage: ["VOYAGE_API_KEY"],
+	cohere: ["COHERE_API_KEY"],
+	openrouter: ["OPENROUTER_API_KEY"]
+};
+function isLlmProviderName(value) {
+	return LLM_PROVIDER_NAMES.includes(value);
+}
+function selectedLlmProviderValue(env) {
+	return (env["AGENTMEMORY_LLM_PROVIDER"] || "").trim().toLowerCase();
+}
+function llmProviderHasKey(env, name) {
+	return LLM_PROVIDER_KEYS[name].some((k) => hasRealValue(env[k]));
+}
+function envFileLabel(path = ENV_FILE) {
+	const home = homedir();
+	return path.startsWith(`${home}/`) ? `~${path.slice(home.length)}` : path;
+}
+function llmOptInHint(env = getMergedEnv()) {
+	const selected = selectedLlmProviderValue(env);
+	if (selected) {
+		if (!isLlmProviderName(selected)) return `AGENTMEMORY_LLM_PROVIDER=${selected} is not a known provider. Use one of: ${LLM_PROVIDER_NAMES.join(", ")}.`;
+		if (!llmProviderHasKey(env, selected)) return `AGENTMEMORY_LLM_PROVIDER=${selected} is set, but ${LLM_PROVIDER_KEYS[selected].join(" or ")} is not. Add the key to ${envFileLabel()}.`;
+		return null;
+	}
+	if (env["AGENTMEMORY_ALLOW_AGENT_SDK"] === "true") return null;
+	const withKey = LLM_PROVIDER_NAMES.filter((name) => llmProviderHasKey(env, name));
+	if (withKey.length === 0) return null;
+	return `Found ${withKey.flatMap((name) => LLM_PROVIDER_KEYS[name].filter((k) => hasRealValue(env[k]))).join(", ")}, but agentmemory sends nothing to an LLM provider until you choose one for it. To turn on LLM summaries and compression, add AGENTMEMORY_LLM_PROVIDER=${withKey[0]} to ${envFileLabel()}.`;
+}
+function embeddingOptInHint(env = getMergedEnv()) {
+	const chosen = (env["EMBEDDING_PROVIDER"] || "").trim().toLowerCase();
+	if (chosen) {
+		const keys = REMOTE_EMBEDDING_PROVIDER_KEYS[chosen];
+		if (keys && !keys.some((k) => hasRealValue(env[k]))) return `EMBEDDING_PROVIDER=${chosen} is set, but ${keys.join(" or ")} is not. Add the key to ${envFileLabel()}, or set EMBEDDING_PROVIDER=local for on-device embeddings.`;
+		return null;
+	}
+	const withKey = Object.keys(REMOTE_EMBEDDING_PROVIDER_KEYS).filter((name) => REMOTE_EMBEDDING_PROVIDER_KEYS[name].some((k) => hasRealValue(env[k])));
+	if (withKey.length === 0) return null;
+	return `A ${withKey.join("/")} key is present, but cloud embeddings stay off until you choose them. Add EMBEDDING_PROVIDER=${withKey[0]} to ${envFileLabel()}, or EMBEDDING_PROVIDER=local for on-device embeddings.`;
+}
 function detectProvider(env) {
 	const maxTokens = parseInt(env["MAX_TOKENS"] || "4096", 10);
-	if (hasRealValue(env["OPENAI_API_KEY"]) && env["OPENAI_API_KEY_FOR_LLM"] !== "false") {
-		const model = env["OPENAI_MODEL"] || "gpt-5.6-luna";
-		warnIfPremiumModel(env, "OPENAI_MODEL", model);
-		return {
-			provider: "openai",
-			model,
-			maxTokens,
-			baseURL: env["OPENAI_BASE_URL"]
-		};
-	}
-	if (hasRealValue(env["MINIMAX_API_KEY"])) return {
-		provider: "minimax",
-		model: env["MINIMAX_MODEL"] || "MiniMax-M3",
+	const noop = {
+		provider: "noop",
+		model: "noop",
 		maxTokens
 	};
-	if (hasRealValue(env["ANTHROPIC_API_KEY"])) return {
-		provider: "anthropic",
-		model: env["ANTHROPIC_MODEL"] || "claude-sonnet-5",
-		maxTokens,
-		baseURL: env["ANTHROPIC_BASE_URL"]
-	};
-	if (hasRealValue(env["GEMINI_API_KEY"]) || hasRealValue(env["GOOGLE_API_KEY"])) {
-		if (!hasRealValue(env["GEMINI_API_KEY"]) && hasRealValue(env["GOOGLE_API_KEY"])) process.stderr.write("[agentmemory] GOOGLE_API_KEY detected — treating as GEMINI_API_KEY. Set GEMINI_API_KEY in ~/.agentmemory/.env to silence this warning.\n");
-		return {
-			provider: "gemini",
-			model: env["GEMINI_MODEL"] || "gemini-3.7-flash",
-			maxTokens
-		};
-	}
-	if (hasRealValue(env["OPENROUTER_API_KEY"])) {
-		const model = env["OPENROUTER_MODEL"] || "anthropic/claude-sonnet-5";
-		warnIfPremiumModel(env, "OPENROUTER_MODEL", model);
-		return {
-			provider: "openrouter",
-			model,
-			maxTokens
-		};
+	const selected = selectedLlmProviderValue(env);
+	if (selected) {
+		if (!isLlmProviderName(selected) || !llmProviderHasKey(env, selected)) {
+			writeProviderNoticeOnce(`[agentmemory] ${llmOptInHint(env)} Running zero-LLM.\n`);
+			return noop;
+		}
+		switch (selected) {
+			case "openai": {
+				const model = env["OPENAI_MODEL"] || "gpt-5.6-luna";
+				warnIfPremiumModel(env, "OPENAI_MODEL", model);
+				return {
+					provider: "openai",
+					model,
+					maxTokens,
+					baseURL: env["OPENAI_BASE_URL"]
+				};
+			}
+			case "minimax": return {
+				provider: "minimax",
+				model: env["MINIMAX_MODEL"] || "MiniMax-M3",
+				maxTokens
+			};
+			case "anthropic": return {
+				provider: "anthropic",
+				model: env["ANTHROPIC_MODEL"] || "claude-sonnet-5",
+				maxTokens,
+				baseURL: env["ANTHROPIC_BASE_URL"]
+			};
+			case "gemini":
+				if (!hasRealValue(env["GEMINI_API_KEY"])) process.stderr.write("[agentmemory] GOOGLE_API_KEY detected — treating as GEMINI_API_KEY. Set GEMINI_API_KEY in ~/.agentmemory/.env to silence this warning.\n");
+				return {
+					provider: "gemini",
+					model: env["GEMINI_MODEL"] || "gemini-3.7-flash",
+					maxTokens
+				};
+			case "openrouter": {
+				const model = env["OPENROUTER_MODEL"] || "anthropic/claude-sonnet-5";
+				warnIfPremiumModel(env, "OPENROUTER_MODEL", model);
+				return {
+					provider: "openrouter",
+					model,
+					maxTokens
+				};
+			}
+		}
 	}
 	if (!(env["AGENTMEMORY_ALLOW_AGENT_SDK"] === "true")) {
-		writeProviderNoticeOnce(pc.dim("[agentmemory] No LLM provider key set — running zero-LLM: no LLM compression or summaries; search uses BM25 plus any configured embedding provider. Set EMBEDDING_PROVIDER=local for on-device semantic embeddings if none is configured. Set ANTHROPIC_API_KEY (or GEMINI/OPENAI/OPENROUTER/MINIMAX) in ~/.agentmemory/.env for LLM compression and summaries. Agent-SDK fallback stays off by default to avoid a Stop-hook recursion loop; opt in with AGENTMEMORY_AUTO_COMPRESS=true + AGENTMEMORY_ALLOW_AGENT_SDK=true.\n"));
-		return {
-			provider: "noop",
-			model: "noop",
-			maxTokens
-		};
+		const hint = llmOptInHint(env);
+		writeProviderNoticeOnce(hint ? `[agentmemory] ${hint}\n` : pc.dim("[agentmemory] No LLM provider chosen, so agentmemory runs zero-LLM: no LLM compression or summaries, and no session content leaves this machine for an LLM. Search uses BM25 plus any embedding provider you set with EMBEDDING_PROVIDER (EMBEDDING_PROVIDER=local runs on-device). To turn on LLM summaries, set AGENTMEMORY_LLM_PROVIDER (anthropic, openai, gemini, openrouter or minimax) and that provider's key in ~/.agentmemory/.env.\n"));
+		return noop;
 	}
 	writeProviderNoticeOnce("[agentmemory] WARNING: agent-sdk fallback enabled via AGENTMEMORY_ALLOW_AGENT_SDK=true. This spawns @anthropic-ai/claude-agent-sdk child sessions that can trigger the Stop-hook recursion loop. A SDK-child env marker is set to block re-entry, but prefer setting a real API key in ~/.agentmemory/.env instead.\n");
 	return {
@@ -202,7 +269,9 @@ function getAuditMigrateMaxBytes() {
 	return safeParseInt(getMergedEnv()["AGENTMEMORY_AUDIT_MIGRATE_MAX_BYTES"], 32 * 1024 * 1024);
 }
 function detectLlmProviderKind(env = getMergedEnv()) {
-	if (hasRealValue(env["ANTHROPIC_API_KEY"]) || hasRealValue(env["GEMINI_API_KEY"]) || hasRealValue(env["GOOGLE_API_KEY"]) || hasRealValue(env["OPENROUTER_API_KEY"]) || hasRealValue(env["MINIMAX_API_KEY"]) || hasRealValue(env["OPENAI_API_KEY"]) && env["OPENAI_API_KEY_FOR_LLM"] !== "false" || env["AGENTMEMORY_ALLOW_AGENT_SDK"] === "true") return "llm";
+	const selected = selectedLlmProviderValue(env);
+	if (selected && isLlmProviderName(selected) && llmProviderHasKey(env, selected)) return "llm";
+	if (!selected && env["AGENTMEMORY_ALLOW_AGENT_SDK"] === "true") return "llm";
 	return "noop";
 }
 function describeLlmRoute(provider) {
@@ -228,15 +297,8 @@ function loadEmbeddingConfig() {
 	};
 }
 function detectEmbeddingProvider(env) {
-	const source = env ?? getMergedEnv();
-	const forced = source["EMBEDDING_PROVIDER"];
-	if (forced) return forced;
-	if (source["GEMINI_API_KEY"]) return "gemini";
-	if (source["OPENAI_API_KEY"] || source["OPENAI_EMBEDDING_API_KEY"]) return "openai";
-	if (source["VOYAGE_API_KEY"]) return "voyage";
-	if (source["COHERE_API_KEY"]) return "cohere";
-	if (source["OPENROUTER_API_KEY"]) return "openrouter";
-	return null;
+	const forced = ((env ?? getMergedEnv())["EMBEDDING_PROVIDER"] || "").trim();
+	return forced ? forced : null;
 }
 function loadClaudeBridgeConfig() {
 	const env = getMergedEnv();
@@ -754,9 +816,11 @@ var OpenAIProvider = class {
 				throw new Error(`OpenAI API error (${response.status}): ${text}`);
 			}
 			const data = await response.json();
-			const message = data.choices?.[0]?.message;
+			const choice = data.choices?.[0];
+			const message = choice?.message;
 			const content = message?.content;
-			if (content) return content;
+			if (content?.trim()) return content;
+			if (choice?.finish_reason === "length") throw new Error(`OpenAI response hit max_tokens (${this.maxTokens}) before any content. Raise MAX_TOKENS or lower OPENAI_REASONING_EFFORT.`);
 			const reasoning = message?.reasoning ?? message?.reasoning_content;
 			if (reasoning) return reasoning;
 			throw new Error(`OpenAI returned unexpected response: ${JSON.stringify(data).slice(0, 200)}`);
@@ -2699,8 +2763,84 @@ var StateKV = class {
 		if (this.backend !== "redis" || !Array.isArray(values)) return values;
 		return orderLikeInsertion(values);
 	}
+	async listGroups() {
+		const groups = (await this.sdk.trigger({
+			function_id: "state::list_groups",
+			payload: {}
+		}))?.groups;
+		if (!Array.isArray(groups) || !groups.every((group) => typeof group === "string")) throw new Error("state::list_groups returned an unexpected shape");
+		return groups;
+	}
 };
 //#endregion
+//#region src/state/state-readiness.ts
+const STATE_READY_TIMEOUT_MS = 12e4;
+const STATE_READY_INTERVAL_MS = 100;
+const PROBE_TIMEOUT_MS = 1e4;
+const READINESS_PROBE_KEY = "__agentmemory_state_readiness__";
+function errorMessage$3(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+function isRetryableProbeError(error) {
+	const code = error?.code;
+	if (code === "function_not_found" || code === "invocation_timeout" || code === "timeout") return true;
+	return /Function state::(?:get|list) not found|timed out|timeout|ETIMEDOUT/i.test(errorMessage$3(error));
+}
+async function waitForStateReady(sdk, options = {}) {
+	const scope = options.scope ?? KV.config;
+	const timeoutMs = options.timeoutMs ?? STATE_READY_TIMEOUT_MS;
+	const intervalMs = options.intervalMs ?? STATE_READY_INTERVAL_MS;
+	const now = options.now ?? (() => performance.now());
+	const sleep = options.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+	const startedAt = now();
+	let attempts = 0;
+	let lastError;
+	const probeTimeoutMs = () => Math.min(PROBE_TIMEOUT_MS, Math.max(1, timeoutMs - (now() - startedAt)));
+	for (;;) {
+		attempts += 1;
+		try {
+			await sdk.trigger({
+				function_id: "state::list",
+				payload: { scope },
+				timeoutMs: probeTimeoutMs()
+			});
+			await sdk.trigger({
+				function_id: "state::get",
+				payload: {
+					scope,
+					key: READINESS_PROBE_KEY
+				},
+				timeoutMs: probeTimeoutMs()
+			});
+			return {
+				ready: true,
+				waitedMs: Math.round(now() - startedAt),
+				attempts
+			};
+		} catch (error) {
+			lastError = errorMessage$3(error);
+			if (!isRetryableProbeError(error)) return {
+				ready: false,
+				waitedMs: Math.round(now() - startedAt),
+				attempts,
+				error: lastError
+			};
+			if (attempts === 1) options.onWaiting?.(lastError);
+		}
+		const elapsed = now() - startedAt;
+		if (elapsed >= timeoutMs) return {
+			ready: false,
+			waitedMs: Math.round(elapsed),
+			attempts,
+			error: lastError
+		};
+		await sleep(Math.min(intervalMs, timeoutMs - elapsed));
+	}
+}
+function assertStateReady(readiness) {
+	if (!readiness.ready) throw new Error(`State worker did not become ready within ${readiness.waitedMs}ms: ${readiness.error ?? "timeout"}`);
+}
+//#endregion
 //#region src/state/search-layer.ts
 function isSearchLayer(value) {
 	return value === "all" || value === "memory" || value === "observation";
@@ -2889,12 +3029,20 @@ var VectorIndex = class VectorIndex {
 };
 //#endregion
 //#region src/state/memory-utils.ts
+const MAX_DATE_MS = 864e13;
+function supersededAt(previous, now) {
+	const prior = previous ? Date.parse(previous) : NaN;
+	const current = Date.parse(now);
+	if (Number.isNaN(prior) || current > prior) return now;
+	return new Date(Math.min(prior + 1, MAX_DATE_MS)).toISOString();
+}
 function memoryToObservation(memory) {
 	return {
 		id: memory.id,
 		sessionId: memory.sessionIds?.[0] ?? "memory",
 		timestamp: memory.createdAt,
 		type: "decision",
+		memoryType: memory.type,
 		title: memory.title,
 		facts: [memory.content],
 		narrative: memory.content,
@@ -2918,6 +3066,13 @@ function lessonToObservation(l) {
 		importance: l.confidence
 	};
 }
+function observationEmbedText(record) {
+	return [
+		record.title,
+		...record.concepts || [],
+		record.narrative || ""
+	].filter((part) => part && part.trim()).join(" ").trim();
+}
 //#endregion
 //#region src/state/obs-index.ts
 const OBS_INDEX_SHARDS = 64;
@@ -3555,10 +3710,12 @@ function registerQueryExpansionFunction(sdk, provider) {
 		}
 	});
 }
+const CJK_RUN = /[\p{Script=Han}\p{Script=Hiragana}\p{Script=Katakana}\p{Script=Hangul}]+/gu;
 function extractEntitiesFromQuery(query) {
 	const entities = [];
 	const quoted = query.match(/"([^"]+)"/g);
 	if (quoted) for (const q of quoted) entities.push(q.replace(/"/g, ""));
+	for (const run of query.matchAll(CJK_RUN)) for (const seg of segmentCjk(run[0])) if (seg.trim().length >= 2) entities.push(seg.trim());
 	const capitalized = query.match(/\b[A-Z][a-zA-Z0-9_.-]+\b/g);
 	if (capitalized) {
 		const stopWords = new Set([
@@ -3701,8 +3858,8 @@ var HybridSearch = class {
 		this.rerankEnabled = rerankEnabled;
 		this.graphRetrieval = new GraphRetrieval(kv, (id) => this.bm25.layerOf(id), (id) => this.bm25.sessionOf(id));
 	}
-	async search(query, limit = 20, targetLayer = "all", authorizeGraph) {
-		return this.tripleStreamSearch(query, limit, targetLayer, this.graphRetrieval.createQuery(authorizeGraph));
+	async search(query, limit = 20, targetLayer = "all", authorizeGraph, request) {
+		return this.tripleStreamSearch(query, limit, targetLayer, this.graphRetrieval.createQuery(authorizeGraph), void 0, true, request);
 	}
 	async searchWithExpansion(query, limit, expansion, targetLayer = "all", authorizeGraph) {
 		const allQueries = [
@@ -3722,13 +3879,25 @@ var HybridSearch = class {
 		const combined = Array.from(merged.values()).sort((a, b) => b.combinedScore - a.combinedScore || (a.observation.id < b.observation.id ? -1 : a.observation.id > b.observation.id ? 1 : 0));
 		return this.rerankResults(query, combined, limit);
 	}
-	async tripleStreamSearch(query, limit, targetLayer, graphQuery, entityHints, applyReranking = true) {
+	async tripleStreamSearch(query, limit, targetLayer, graphQuery, entityHints, applyReranking = true, request) {
 		const retrievalLimit = this.rerankEnabled ? Math.max(limit, 20) : limit;
 		const bm25Results = this.bm25.search(query, retrievalLimit * 2, targetLayer);
 		let vectorResults = [];
 		let queryEmbedding = null;
 		if (this.vector && this.embeddingProvider && this.vector.size > 0) try {
-			queryEmbedding = await this.embeddingProvider.embed(query);
+			if (request) {
+				if (!request.embedding || request.embedding.query !== query) request.embedding = {
+					query,
+					value: this.embeddingProvider.embed(query)
+				};
+				const embedding = request.embedding;
+				try {
+					queryEmbedding = await embedding.value;
+				} catch (error) {
+					if (request.embedding === embedding) request.embedding = void 0;
+					throw error;
+				}
+			} else queryEmbedding = await this.embeddingProvider.embed(query);
 			vectorResults = this.vector.search(queryEmbedding, retrievalLimit * 2, targetLayer, (id) => this.bm25.layerOf(id));
 		} catch {}
 		const entities = entityHints && entityHints.length > 0 ? entityHints : extractEntitiesFromQuery(query);
@@ -3803,6 +3972,7 @@ var HybridSearch = class {
 			graphContext: s.graphContext,
 			combinedScore
 		}));
+		if (request) request.candidateCount = combined.length;
 		const retrievalDepth = Math.max(limit, 20);
 		const diversified = this.diversifyBySession(combined, retrievalDepth);
 		const enriched = await this.enrichResults(diversified, retrievalDepth);
@@ -4332,6 +4502,10 @@ const PENDING_LOG_SAVE_THRESHOLD = 500;
 const EARLY_SAVE_MIN_GAP_MS = 5e3;
 const BACKFILL_MARKER_KEY = "vectors:backfill";
 const MEMORY_ID_PREFIX = "mem_";
+const LEGACY_SHARD_SCOPE_PREFIXES = [`${KV.bm25Index}:bm25:`, `${KV.bm25Index}:vectors:`];
+const LEGACY_SHARD_KEY = "data";
+const LEGACY_SHARD_SUFFIX = /^((?:[0-9a-z]+-[0-9a-f]{32})|(?:idx_[0-9a-z]+_[0-9a-f]{12})):\d{5}$/;
+const ORPHAN_SWEEP_KEY = "legacy:sweep";
 function auditIndexPersistEnabled() {
 	const raw = process.env.AGENTMEMORY_AUDIT_INDEX_PERSIST;
 	if (!raw) return false;
@@ -4366,6 +4540,11 @@ function isValidShardDescriptor(shard) {
 	const candidate = shard;
 	return typeof candidate.scope === "string" && candidate.scope.length > 0 && typeof candidate.key === "string" && candidate.key.length > 0 && Number.isInteger(candidate.chars) && candidate.chars >= 0;
 }
+function legacyShardGeneration(scope) {
+	const prefix = LEGACY_SHARD_SCOPE_PREFIXES.find((candidate) => scope.startsWith(candidate));
+	if (!prefix) return void 0;
+	return LEGACY_SHARD_SUFFIX.exec(scope.slice(prefix.length))?.[1] ?? null;
+}
 function isPersistedVector(row) {
 	if (!row || typeof row !== "object") return false;
 	const candidate = row;
@@ -4736,7 +4915,7 @@ var IndexPersistence = class {
 	}
 	async load() {
 		if (!this.vector) {
-			await this.removeLegacyBm25Snapshot();
+			await this.finishLegacyCleanup();
 			return {
 				vector: null,
 				state: "none",
@@ -4764,7 +4943,7 @@ var IndexPersistence = class {
 			this.hasVectorCheckpoint = loaded.size > 0;
 			this.checkpointBackfillSince = meta.backfillSince;
 			await this.removeLegacyVectorSnapshotIfPresent();
-			await this.removeLegacyBm25Snapshot();
+			await this.finishLegacyCleanup();
 			const expectedCount = Number.isInteger(meta.count) ? meta.count : void 0;
 			this.vectorCountShortfall = expectedCount !== void 0 && loaded.size < expectedCount ? {
 				expected: expectedCount,
@@ -4950,7 +5129,7 @@ var IndexPersistence = class {
 			savedAt: null
 		};
 		if (!(manifest.value != null || typeof legacyKey.value === "string" && legacyKey.value.length > 0)) {
-			await this.removeLegacyBm25Snapshot();
+			await this.finishLegacyCleanup();
 			return {
 				vector: null,
 				state: "none",
@@ -4983,7 +5162,7 @@ var IndexPersistence = class {
 			};
 		}
 		await this.removeLegacyVectorSnapshot(manifest.value);
-		await this.removeLegacyBm25Snapshot();
+		await this.finishLegacyCleanup();
 		await this.auditIndexPersistence("migrate", [statePath(KV.bm25Index, VECTOR_META_KEY)], {
 			vectors: legacy.size,
 			buckets: this.bucketCountInUse()
@@ -5023,6 +5202,71 @@ var IndexPersistence = class {
 		if (manifest != null) await this.deleteKey(KV.bm25Index, LEGACY_BM25_MANIFEST_KEY, "legacy_bm25_cleanup");
 		if (legacy != null) await this.deleteKey(KV.bm25Index, LEGACY_BM25_KEY, "legacy_bm25_cleanup");
 	}
+	async finishLegacyCleanup() {
+		await this.removeLegacyBm25Snapshot();
+		await this.sweepOrphanedGenerations();
+	}
+	async sweepOrphanedGenerations() {
+		try {
+			if (await this.kv.get(KV.bm25Index, ORPHAN_SWEEP_KEY) != null) return;
+			const candidates = /* @__PURE__ */ new Map();
+			for (const scope of await this.kv.listGroups()) {
+				const generation = legacyShardGeneration(scope);
+				if (generation === void 0) continue;
+				if (generation === null) {
+					logger.warn("index persistence: orphan sweep skipped, unrecognized legacy shard scope", { scope });
+					return;
+				}
+				candidates.set(scope, generation);
+			}
+			const named = await this.namedLegacyGenerations();
+			if (!named) return;
+			const orphans = [...candidates].filter(([, generation]) => !named.has(generation));
+			const failures = await inBatches(orphans, WRITE_CONCURRENCY, async ([scope]) => {
+				if (!await this.deleteKey(scope, LEGACY_SHARD_KEY, "orphan_generation_sweep")) throw new Error(scope);
+			});
+			const summary = {
+				generations: new Set(orphans.map(([, generation]) => generation)).size,
+				shards: orphans.length,
+				failed: failures.length
+			};
+			if (failures.length > 0) {
+				logger.warn("index persistence: orphan sweep left shards behind; the next boot retries", summary);
+				return;
+			}
+			if (candidates.size > orphans.length) {
+				if (orphans.length > 0) logger.info("index persistence: swept orphaned legacy index generations", summary);
+				return;
+			}
+			await this.kv.set(KV.bm25Index, ORPHAN_SWEEP_KEY, {
+				v: 1,
+				at: new Date(this.now()).toISOString(),
+				...summary
+			});
+			await this.auditIndexPersistence("sweep", [statePath(KV.bm25Index, ORPHAN_SWEEP_KEY)], summary);
+			logger.info("index persistence: swept orphaned legacy index generations", summary);
+		} catch (err) {
+			logger.warn("index persistence: orphan sweep failed; the next boot retries", { message: errorMessage$2(err) });
+		}
+	}
+	async namedLegacyGenerations() {
+		const named = /* @__PURE__ */ new Set();
+		for (const [key, label] of [[LEGACY_BM25_MANIFEST_KEY, "bm25"], [LEGACY_VECTOR_MANIFEST_KEY, "vector"]]) {
+			const read = await this.readIndexValue(KV.bm25Index, key, label, "manifest");
+			if (!read.ok) return null;
+			const manifest = read.value;
+			if (manifest == null) continue;
+			const generations = typeof manifest === "object" && Array.isArray(manifest.shards) ? manifest.shards.filter((shard) => typeof shard?.scope === "string" && shard.scope.length > 0).map((shard) => legacyShardGeneration(shard.scope)) : [];
+			if (typeof manifest === "object" && typeof manifest.generation === "string") generations.push(manifest.generation);
+			const usable = generations.filter((generation) => !!generation);
+			for (const generation of usable) named.add(generation);
+			if (usable.length === 0) {
+				logger.warn("index persistence: orphan sweep skipped, a legacy manifest names no generation", { key });
+				return null;
+			}
+		}
+		return named;
+	}
 	logFailure(err) {
 		const now = this.now();
 		if (now - this.lastFailureLogAt < FAILURE_LOG_THROTTLE_MS) return;
@@ -5057,9 +5301,12 @@ var IndexPersistence = class {
 			result,
 			error
 		});
+		return error === void 0;
 	}
 	async deleteShards(shards, reason) {
-		await inBatches(shards, WRITE_CONCURRENCY, (shard) => this.deleteKey(shard.scope, shard.key, reason));
+		await inBatches(shards, WRITE_CONCURRENCY, async (shard) => {
+			await this.deleteKey(shard.scope, shard.key, reason);
+		});
 	}
 	async loadShardedData(legacyKey, manifestKey, label) {
 		const manifest = await this.readIndexValue(KV.bm25Index, manifestKey, label, "manifest");
@@ -5157,7 +5404,29 @@ async function settleWithin(work, ms) {
 }
 //#endregion
 //#region src/functions/privacy.ts
-const PRIVATE_TAG_RE = /<private>[\s\S]*?<\/private>/gi;
+const PRIVATE_TAG_TOKEN_RE = /<private(?=\s|>)[^>]*>|<\/private\s*>/gi;
+function redactPrivateBlocks(input) {
+	const tokens = new RegExp(PRIVATE_TAG_TOKEN_RE.source, PRIVATE_TAG_TOKEN_RE.flags);
+	let out = "";
+	let cursor = 0;
+	let depth = 0;
+	for (let match = tokens.exec(input); match; match = tokens.exec(input)) {
+		const closing = match[0].startsWith("</");
+		if (depth === 0) {
+			if (closing) continue;
+			out += input.slice(cursor, match.index);
+			depth = 1;
+		} else if (closing) {
+			depth -= 1;
+			if (depth === 0) {
+				out += "[REDACTED]";
+				cursor = match.index + match[0].length;
+			}
+		} else depth += 1;
+	}
+	if (depth > 0) return `${out}[REDACTED]`;
+	return out + input.slice(cursor);
+}
 const SECRET_PATTERN_SOURCES = [
 	/(?:api[_-]?key|secret|token|password|credential|auth)[\s]*[=:]\s*["']?[A-Za-z0-9_\-/.+]{20,}["']?/gi,
 	/Bearer\s+[A-Za-z0-9._\-+/=]{20,}/gi,
@@ -5177,7 +5446,7 @@ const SECRET_PATTERN_SOURCES = [
 const PRIVATE_KEY_BLOCK_RE = /-----BEGIN [A-Z0-9 ]*PRIVATE KEY(?: BLOCK)?-----[\s\S]*?(?:-----END [A-Z0-9 ]*PRIVATE KEY(?: BLOCK)?-----|$)/g;
 const URL_CREDENTIALS_RE = /\b([a-z][a-z0-9+.-]*:\/\/)[^\s/?#@:"'<>]*:[^\s/?#@"'<>]+@/gi;
 function stripPrivateData(input) {
-	let result = input.replace(PRIVATE_TAG_RE, "[REDACTED]");
+	let result = redactPrivateBlocks(input);
 	result = result.replace(new RegExp(PRIVATE_KEY_BLOCK_RE.source, PRIVATE_KEY_BLOCK_RE.flags), "[REDACTED_SECRET]");
 	result = result.replace(new RegExp(URL_CREDENTIALS_RE.source, URL_CREDENTIALS_RE.flags), "$1[REDACTED_SECRET]@");
 	for (const source of SECRET_PATTERN_SOURCES) {
@@ -6151,6 +6420,9 @@ function getSynonyms(stemmedTerm) {
 }
 //#endregion
 //#region src/state/search-index.ts
+const USER_PROMPT_TERM_CAP = 2e3;
+const ASSISTANT_RESPONSE_TERM_CAP = 1e3;
+const TOOL_OUTPUT_TERM_CAP = 1e3;
 var SearchIndex = class SearchIndex {
 	entries = /* @__PURE__ */ new Map();
 	invertedIndex = /* @__PURE__ */ new Map();
@@ -6409,6 +6681,9 @@ var SearchIndex = class SearchIndex {
 			...obs.files,
 			obs.type
 		];
+		if (obs.source?.userPrompt) parts.push(obs.source.userPrompt.slice(0, USER_PROMPT_TERM_CAP));
+		if (obs.source?.assistantResponse) parts.push(obs.source.assistantResponse.slice(0, ASSISTANT_RESPONSE_TERM_CAP));
+		if (obs.source?.toolName === "conversation" && typeof obs.source.toolOutput === "string") parts.push(obs.source.toolOutput.slice(0, TOOL_OUTPUT_TERM_CAP));
 		return this.tokenize(parts.join(" ").toLowerCase());
 	}
 	tokenize(text) {
@@ -6465,6 +6740,7 @@ function formatResult(result, format) {
 		sessionId: result.sessionId,
 		title: observation.title,
 		type: observation.type,
+		...observation.memoryType !== void 0 && { memoryType: observation.memoryType },
 		score: result.score,
 		timestamp: observation.timestamp,
 		...result.layer !== void 0 && { layer: result.layer }
@@ -6485,6 +6761,7 @@ function clipResult(result, format, budget) {
 			sessionId: result.sessionId,
 			title: "",
 			type: observation.type,
+			...observation.memoryType !== void 0 && { memoryType: observation.memoryType },
 			score: result.score,
 			timestamp: observation.timestamp,
 			...layer,
@@ -6506,6 +6783,7 @@ function clipResult(result, format, budget) {
 			sessionId: result.sessionId,
 			title,
 			narrative,
+			...observation.memoryType !== void 0 && { memoryType: observation.memoryType },
 			score: result.score,
 			timestamp: observation.timestamp,
 			...layer,
@@ -6517,6 +6795,7 @@ function clipResult(result, format, budget) {
 				sessionId: observation.sessionId,
 				timestamp: observation.timestamp,
 				type: observation.type,
+				...observation.memoryType !== void 0 && { memoryType: observation.memoryType },
 				title,
 				facts: [],
 				narrative,
@@ -6967,7 +7246,11 @@ async function indexRecords(observations, memories) {
 				id: memory.id,
 				revision,
 				sessionId: memory.sessionIds?.[0] ?? "memory",
-				text: memory.title + " " + memory.content,
+				text: observationEmbedText({
+					title: memory.title,
+					narrative: memory.content,
+					concepts: memory.concepts
+				}),
 				context: {
 					kind: "memory",
 					logId: memory.id
@@ -6981,7 +7264,7 @@ async function indexRecords(observations, memories) {
 				id: obs.id,
 				revision,
 				sessionId: obs.sessionId,
-				text: obs.title + " " + obs.narrative,
+				text: observationEmbedText(obs),
 				context: {
 					kind: "observation",
 					logId: obs.id
@@ -7014,21 +7297,36 @@ async function findUnindexedObservations(kv) {
 		missing
 	};
 }
-const SESSIONS_LIST_RETRY_ATTEMPTS = 3;
-const SESSIONS_LIST_RETRY_BASE_MS = 250;
+const LIST_RETRY_ATTEMPTS = 8;
+const LIST_RETRY_BASE_MS = 2500;
+const LIST_RETRY_BUDGET_MS = 7e4;
 function delay(ms) {
 	return new Promise((resolve) => setTimeout(resolve, ms));
 }
-async function listSessionsWithRetry(kv) {
+function isStateNotReadyError(err) {
+	const code = err?.code;
+	if (code === "function_not_found" || code === "invocation_timeout" || code === "timeout" || code === "ECONNRESET" || code === "ECONNREFUSED" || code === "EPIPE") return true;
+	const message = err instanceof Error ? err.message : String(err);
+	return /function_not_found|Function state::\w+ not found|timed out|timeout|ETIMEDOUT|ECONNRESET|ECONNREFUSED|EPIPE|socket hang up|connection (?:closed|reset)/i.test(message);
+}
+async function listWithRetry(kv, scope, label, deadline) {
 	let lastErr;
-	for (let attempt = 0; attempt < SESSIONS_LIST_RETRY_ATTEMPTS; attempt++) try {
-		return await kv.list(KV.sessions);
-	} catch (err) {
-		lastErr = err;
-		if (attempt < SESSIONS_LIST_RETRY_ATTEMPTS - 1) await delay(SESSIONS_LIST_RETRY_BASE_MS * (attempt + 1));
+	let attempts = 0;
+	while (attempts < LIST_RETRY_ATTEMPTS) {
+		attempts++;
+		try {
+			return await kv.list(scope);
+		} catch (err) {
+			lastErr = err;
+			if (!isStateNotReadyError(err)) break;
+			const remaining = deadline - performance.now();
+			const wait = LIST_RETRY_BASE_MS * attempts;
+			if (attempts >= LIST_RETRY_ATTEMPTS || wait >= remaining) break;
+			await delay(wait);
+		}
 	}
-	logger.warn("rebuildKeywordIndex: failed to load sessions after retries", {
-		attempts: SESSIONS_LIST_RETRY_ATTEMPTS,
+	logger.warn(`${label}: failed to load`, {
+		attempts,
 		error: lastErr instanceof Error ? lastErr.message : String(lastErr)
 	});
 	return null;
@@ -7078,20 +7376,24 @@ async function runKeywordRebuild(kv, vectorBackfillSince) {
 	};
 	let documents = 0;
 	let memoriesLoaded = false;
-	try {
-		const memories = await kv.list(KV.memories);
+	const listDeadline = performance.now() + LIST_RETRY_BUDGET_MS;
+	const memories = await listWithRetry(kv, KV.memories, "rebuildKeywordIndex: memories", listDeadline);
+	const sessions = await listWithRetry(kv, KV.sessions, "rebuildKeywordIndex: sessions", listDeadline);
+	if (memories === null) bm25RebuildIncomplete = true;
+	else {
 		memoriesLoaded = true;
 		for (const memory of memories) {
 			if (memory.isLatest === false) continue;
 			if (!memory.title || !memory.content) continue;
 			idx.add(memoryToObservation(memory), "memory");
-			consider(memory.id, memory.sessionIds?.[0] ?? "memory", memory.title + " " + memory.content, memory.createdAt, "memory");
+			consider(memory.id, memory.sessionIds?.[0] ?? "memory", observationEmbedText({
+				title: memory.title,
+				narrative: memory.content,
+				concepts: memory.concepts
+			}), memory.createdAt, "memory");
 			documents++;
 		}
-	} catch (err) {
-		logger.warn("rebuildKeywordIndex: failed to load memories", { error: err instanceof Error ? err.message : String(err) });
 	}
-	const sessions = await listSessionsWithRetry(kv);
 	if (sessions === null) {
 		bm25RebuildIncomplete = true;
 		if (memoriesLoaded) memoryIndexReady = true;
@@ -7115,7 +7417,7 @@ async function runKeywordRebuild(kv, vectorBackfillSince) {
 		for (const obs of results.flat()) {
 			if (!obs.title || !obs.narrative) continue;
 			idx.add(obs);
-			consider(obs.id, obs.sessionId, obs.title + " " + obs.narrative, obs.timestamp, "observation");
+			consider(obs.id, obs.sessionId, observationEmbedText(obs), obs.timestamp, "observation");
 			documents++;
 		}
 	}
@@ -7222,6 +7524,7 @@ function registerSearchFunction(sdk, kv) {
 		if (data.targetLayer !== void 0 && !isSearchLayer(data.targetLayer)) throw new Error("mem::search: targetLayer must be one of 'all', 'memory', or 'observation'");
 		const targetLayer = data.targetLayer ?? "all";
 		const MAX_LIMIT = 100;
+		const MAX_CANDIDATES = 1e3;
 		let effectiveLimit = 20;
 		if (data.limit !== void 0) {
 			if (!Number.isInteger(data.limit) || data.limit < 1) throw new Error("mem::search: limit must be a positive integer");
@@ -7259,7 +7562,7 @@ function registerSearchFunction(sdk, kv) {
 			await rebuildPromise;
 		}
 		const filtering = !!(projectFilter || cwdFilter || filterAgentId);
-		const fetchLimit = filtering ? Math.max(effectiveLimit * 10, 100) : effectiveLimit;
+		let fetchLimit = filtering ? Math.max(effectiveLimit * 10, 100) : effectiveLimit;
 		let results;
 		const authorizeGraph = async (record, sessionId, read) => {
 			if (filterAgentId !== void 0 && record.agentId !== filterAgentId) return false;
@@ -7273,25 +7576,12 @@ function registerSearchFunction(sdk, kv) {
 			}
 			return true;
 		};
-		if (hybridRanker) try {
-			results = (await hybridRanker(query, fetchLimit, targetLayer, authorizeGraph)).map((r) => ({
-				obsId: r.observation.id,
-				sessionId: r.sessionId,
-				score: r.combinedScore,
-				observation: r.observation,
-				layer: r.layer
-			}));
-		} catch (err) {
-			logger.warn("hybrid ranking failed, falling back to keyword search", { error: err instanceof Error ? err.message : String(err) });
-			results = idx.search(query, fetchLimit, targetLayer);
-		}
-		else results = idx.search(query, fetchLimit, targetLayer);
 		const sessionCache = /* @__PURE__ */ new Map();
 		const loadSession = async (sessionId) => {
 			if (sessionCache.has(sessionId)) return sessionCache.get(sessionId);
-			const s = await kv.get(KV.sessions, sessionId);
-			sessionCache.set(sessionId, s ?? null);
-			return s ?? null;
+			const pending = kv.get(KV.sessions, sessionId).then((session) => session ?? null);
+			sessionCache.set(sessionId, pending);
+			return pending;
 		};
 		const memoryProjectCache = /* @__PURE__ */ new Map();
 		const loadMemoryProject = async (obsId) => {
@@ -7300,53 +7590,88 @@ function registerSearchFunction(sdk, kv) {
 			memoryProjectCache.set(obsId, proj);
 			return proj;
 		};
-		const earlyCap = filterAgentId ? fetchLimit : effectiveLimit;
-		const candidates = [];
-		for (const r of results) {
-			if (candidates.length >= earlyCap) break;
-			const layer = r.layer ?? idx.layerOf(r.obsId) ?? getSearchResultLayer(r.obsId, r.sessionId);
-			if (!matchesSearchLayer(r.obsId, r.sessionId, targetLayer, layer)) continue;
-			if (filtering) {
-				const memoryProject = projectFilter && layer === "memory" ? await loadMemoryProject(r.obsId) : null;
-				if (projectFilter && memoryProject !== null && memoryProject !== projectFilter) continue;
-				const session = await loadSession(r.sessionId);
-				if (session) {
-					if (projectFilter && memoryProject === null && session.project !== projectFilter) continue;
-					if (cwdFilter && session.cwd !== cwdFilter) continue;
-				}
-			}
-			candidates.push(r);
-		}
-		const obsResults = await Promise.all(candidates.map(async (r) => {
-			if (r.observation) return {
-				observation: r.observation,
-				layer: r.layer ?? idx.layerOf(r.obsId) ?? getSearchResultLayer(r.obsId, r.sessionId)
-			};
-			const obs = await kv.get(KV.observations(r.sessionId), r.obsId).catch(() => null);
-			if (obs) return {
-				observation: obs,
-				layer: "observation"
-			};
-			const mem = await kv.get(KV.memories, r.obsId).catch(() => null);
-			return mem ? {
-				observation: memoryToObservation(mem),
-				layer: "memory"
-			} : null;
-		}));
-		const enriched = [];
-		for (let i = 0; i < candidates.length; i++) {
-			const resolved = obsResults[i];
-			if (!resolved) continue;
-			const obs = resolved.observation;
-			if (!matchesSearchLayer(obs.id, obs.sessionId, targetLayer, resolved.layer)) continue;
-			if (filterAgentId !== void 0 && obs.agentId !== filterAgentId) continue;
-			if (enriched.length >= effectiveLimit) break;
-			enriched.push({
-				observation: withoutObservationSource(obs),
-				layer: resolved.layer,
-				score: candidates[i].score,
-				sessionId: candidates[i].sessionId
-			});
+		const observationCache = /* @__PURE__ */ new Map();
+		const hybridRequest = {};
+		let enriched = [];
+		let useHybridRanker = hybridRanker !== null;
+		while (true) {
+			hybridRequest.candidateCount = void 0;
+			if (useHybridRanker && hybridRanker) try {
+				results = (await hybridRanker(query, fetchLimit, targetLayer, authorizeGraph, hybridRequest)).map((r) => ({
+					obsId: r.observation.id,
+					sessionId: r.sessionId,
+					score: r.combinedScore,
+					observation: r.observation,
+					layer: r.layer
+				}));
+			} catch (err) {
+				hybridRequest.candidateCount = void 0;
+				logger.warn("hybrid ranking failed", { error: err instanceof Error ? err.message : String(err) });
+				if (enriched.length > 0) break;
+				useHybridRanker = false;
+				results = idx.search(query, fetchLimit, targetLayer);
+			}
+			else results = idx.search(query, fetchLimit, targetLayer);
+			enriched = [];
+			let batchSize = Math.min(10, effectiveLimit);
+			for (let offset = 0; offset < Math.min(results.length, fetchLimit) && enriched.length < effectiveLimit;) {
+				const batch = results.slice(offset, Math.min(offset + batchSize, fetchLimit));
+				offset += batch.length;
+				const obsResults = await Promise.all(batch.map(async (r) => {
+					const layer = r.layer ?? idx.layerOf(r.obsId) ?? getSearchResultLayer(r.obsId, r.sessionId);
+					if (!matchesSearchLayer(r.obsId, r.sessionId, targetLayer, layer)) return null;
+					if (filtering) {
+						const memoryProject = projectFilter && layer === "memory" ? await loadMemoryProject(r.obsId) : null;
+						if (projectFilter && memoryProject !== null && memoryProject !== projectFilter) return null;
+						const session = projectFilter || cwdFilter ? await loadSession(r.sessionId) : null;
+						if (projectFilter && memoryProject === null && !session) return null;
+						if (cwdFilter && layer === "observation" && !session) return null;
+						if (session) {
+							if (projectFilter && memoryProject === null && session.project !== projectFilter) return null;
+							if (cwdFilter && session.cwd !== cwdFilter) return null;
+						}
+					}
+					const key = JSON.stringify([r.obsId, r.sessionId]);
+					let pending = observationCache.get(key);
+					if (!pending) {
+						pending = (async () => {
+							if (r.observation) return {
+								observation: r.observation,
+								layer: r.layer ?? idx.layerOf(r.obsId) ?? getSearchResultLayer(r.obsId, r.sessionId)
+							};
+							const obs = await kv.get(KV.observations(r.sessionId), r.obsId).catch(() => null);
+							if (obs) return {
+								observation: obs,
+								layer: "observation"
+							};
+							const mem = await kv.get(KV.memories, r.obsId).catch(() => null);
+							return mem ? {
+								observation: memoryToObservation(mem),
+								layer: "memory"
+							} : null;
+						})();
+						observationCache.set(key, pending);
+					}
+					return pending;
+				}));
+				for (let i = 0; i < batch.length; i++) {
+					const resolved = obsResults[i];
+					if (!resolved) continue;
+					const obs = resolved.observation;
+					if (!matchesSearchLayer(obs.id, obs.sessionId, targetLayer, resolved.layer)) continue;
+					if (filterAgentId !== void 0 && obs.agentId !== filterAgentId) continue;
+					if (enriched.length >= effectiveLimit) break;
+					enriched.push({
+						observation: withoutObservationSource(obs),
+						layer: resolved.layer,
+						score: batch[i].score,
+						sessionId: batch[i].sessionId
+					});
+				}
+				batchSize = Math.min(10, Math.max(effectiveLimit - enriched.length, batchSize * 2));
+			}
+			if (!filtering || enriched.length >= effectiveLimit || (hybridRequest.candidateCount ?? results.length) < fetchLimit || fetchLimit >= MAX_CANDIDATES) break;
+			fetchLimit = Math.min(fetchLimit * 2, MAX_CANDIDATES);
 		}
 		const response = buildRecallResponse(enriched, format, tokenBudget);
 		recordAccessBatch(kv, enriched.slice(0, response.results.length).map((result) => result.observation.id));
@@ -7747,7 +8072,7 @@ async function restoreIndexEntries(obs) {
 		scheduleIndexSave();
 	}
 	const vectors = getVectorIndex();
-	if (vectors && !vectors.has(obs.id)) await vectorIndexAddGuarded(obs.id, obs.sessionId, obs.title + " " + (obs.narrative || ""), {
+	if (vectors && !vectors.has(obs.id)) await vectorIndexAddGuarded(obs.id, obs.sessionId, observationEmbedText(obs), {
 		kind: "synthetic",
 		logId: obs.id
 	});
@@ -7969,7 +8294,7 @@ function registerObserveFunction(sdk, kv, dedupMap, maxObservationsPerSession) {
 			}
 			getSearchIndex().add(synthetic);
 			scheduleIndexSave();
-			await vectorIndexAddGuarded(synthetic.id, synthetic.sessionId, synthetic.title + " " + (synthetic.narrative || ""), {
+			await vectorIndexAddGuarded(synthetic.id, synthetic.sessionId, observationEmbedText(synthetic), {
 				kind: "synthetic",
 				logId: synthetic.id
 			});
@@ -9848,7 +10173,7 @@ Rules:
 - Be concise but preserve ALL technically relevant details
 - File paths must be exact
 - Importance: 1-3 for routine reads, 4-6 for edits/commands, 7-9 for architectural decisions, 10 for breaking changes
-- Concepts should be reusable search terms (e.g., "React hooks", "SQL migration", "auth middleware")
+- Concepts should be reusable search terms (e.g., "React hooks", "SQL migration", "auth middleware"); keep them in the user's language: when the source content is not English, include at least one concept in that original language, and when the observation mixes languages include both the original-language and English terms so search works in either
 - Strip any secrets, tokens, or credentials from the output`;
 function buildCompressionPrompt(observation) {
 	const parts = [`Timestamp: ${observation.timestamp}`, `Hook: ${observation.hookType}`];
@@ -10572,7 +10897,7 @@ function registerCompressFunction(sdk, kv, provider, metricsStore) {
 				retryable: false
 			};
 			const committedRevision = observationRevision(compressed);
-			await bounded(() => vectorIndexAddGuarded(observationId, sessionId, compressed.title + " " + compressed.narrative, {
+			await bounded(() => vectorIndexAddGuarded(observationId, sessionId, observationEmbedText(compressed), {
 				kind: "observation",
 				logId: observationId
 			}, (embedding, isCurrent) => withKeyedLock(`obs:${sessionId}`, async () => {
@@ -11192,7 +11517,7 @@ function registerSummarizeFunction(sdk, kv, provider, metricsStore) {
 			return {
 				success: false,
 				error: "no_provider",
-				reason: "No LLM provider key set; Summarize is a no-op. Set ANTHROPIC_API_KEY (or GEMINI/OPENROUTER/MINIMAX) in ~/.agentmemory/.env to enable."
+				reason: "No LLM provider chosen; Summarize is a no-op. Set AGENTMEMORY_LLM_PROVIDER and that provider's key in ~/.agentmemory/.env to enable."
 			};
 		}
 		const boundedProvider = {
@@ -11803,6 +12128,7 @@ function registerConsolidateFunction(sdk, kv, provider) {
 				const existingMatch = existingMemories.find((m) => m.title.toLowerCase() === parsed.title.toLowerCase() && (!scopedProject || !m.project || m.project === scopedProject));
 				if (existingMatch) {
 					existingMatch.isLatest = false;
+					existingMatch.updatedAt = supersededAt(existingMatch.updatedAt, now);
 					await kv.set(KV.memories, existingMatch.id, existingMatch);
 					await recordAudit(kv, "evolve", "mem::consolidate", [existingMatch.id], {
 						action: "mark_non_latest",
@@ -12001,25 +12327,52 @@ function registerPatternsFunction(sdk, kv) {
 }
 //#endregion
 //#region src/functions/facets.ts
-async function deleteFacetsForTargets(kv, targetIds) {
+async function targetLiveness(kv, id) {
+	let observation = false;
+	if (id.startsWith("obs_")) {
+		const sessionId = await lookupObservationSession(kv, id);
+		observation = !!sessionId && !!await kv.get(KV.observations(sessionId), id);
+	}
+	if (id.startsWith("lsn_") || id.startsWith("lesson_")) {
+		const lesson = await kv.get(KV.lessons, id);
+		if (lesson && !lesson.deleted) return {
+			observation,
+			record: true
+		};
+	}
+	const [mem, sem] = await Promise.all([kv.get(KV.memories, id), kv.get(KV.semantic, id)]);
+	return {
+		observation,
+		record: !!(mem || sem)
+	};
+}
+function facetTargetLive(facet, liveness) {
+	if (!liveness) return false;
+	if (facet.targetType === "observation") return liveness.observation;
+	return liveness.record || liveness.observation;
+}
+async function deleteFacetsForTargets(kv, targetIds, options) {
 	const ids = new Set(targetIds);
 	ids.delete("");
 	if (ids.size === 0) return;
+	const targetTypes = new Set(options?.targetTypes ?? ["memory"]);
 	try {
-		const live = /* @__PURE__ */ new Set();
+		const live = /* @__PURE__ */ new Map();
 		await Promise.all([...ids].map(async (id) => {
 			for (let attempt = 0; attempt < 2; attempt++) try {
-				const [mem, sem] = await Promise.all([kv.get(KV.memories, id), kv.get(KV.semantic, id)]);
-				if (mem || sem) live.add(id);
+				live.set(id, await targetLiveness(kv, id));
 				return;
 			} catch {
 				if (attempt === 1) {
-					live.add(id);
+					live.set(id, {
+						observation: true,
+						record: true
+					});
 					logger.warn("Facet cleanup skipped unverifiable target", { targetId: id });
 				}
 			}
 		}));
-		const matches = (await kv.list(KV.facets)).filter((f) => ids.has(f.targetId) && !live.has(f.targetId) && f.targetType === "memory");
+		const matches = (await kv.list(KV.facets)).filter((f) => ids.has(f.targetId) && targetTypes.has(f.targetType) && !facetTargetLive(f, live.get(f.targetId)));
 		await Promise.all(matches.map((f) => kv.delete(KV.facets, f.id)));
 	} catch (err) {
 		logger.warn("Facet cleanup failed", {
@@ -12295,6 +12648,7 @@ function registerRememberFunction(sdk, kv) {
 			if (data.ttlDays && typeof data.ttlDays === "number" && data.ttlDays > 0) memory.forgetAfter = new Date(Date.now() + data.ttlDays * 864e5).toISOString();
 			if (supersededMemory) {
 				supersededMemory.isLatest = false;
+				supersededMemory.updatedAt = supersededAt(supersededMemory.updatedAt, now);
 				await kv.set(KV.memories, supersededMemory.id, supersededMemory);
 				try {
 					getSearchIndex().remove(supersededMemory.id);
@@ -12317,7 +12671,11 @@ function registerRememberFunction(sdk, kv) {
 				nearMatch
 			};
 		});
-		await vectorIndexAddGuarded(memory.id, memory.sessionIds?.[0] ?? "memory", memory.title + " " + memory.content, {
+		await vectorIndexAddGuarded(memory.id, memory.sessionIds?.[0] ?? "memory", observationEmbedText({
+			title: memory.title,
+			narrative: memory.content,
+			concepts: memory.concepts
+		}), {
 			kind: "memory",
 			logId: memory.id
 		}, (embedding, isCurrent) => withKeyedLock("mem:remember", async () => {
@@ -12459,6 +12817,7 @@ function registerRememberFunction(sdk, kv) {
 				}
 			});
 		}
+		if (deletedObservationIds.length > 0) await deleteFacetsForTargets(kv, deletedObservationIds, { targetTypes: ["memory", "observation"] });
 		if (deleted > 0 || indexCleaned) await flushIndexSave();
 		if (deleted > 0 || failures.length > 0) await recordAudit(kv, "forget", "mem::forget", [...deletedMemoryIds, ...deletedObservationIds], {
 			sessionId: data.sessionId,
@@ -12899,6 +13258,7 @@ function registerRelationsFunction(sdk, kv) {
 				isLatest: true
 			};
 			existing.isLatest = false;
+			existing.updatedAt = supersededAt(existing.updatedAt, now);
 			await kv.set(KV.memories, existing.id, existing);
 			try {
 				getSearchIndex().remove(existing.id);
@@ -12919,7 +13279,11 @@ function registerRelationsFunction(sdk, kv) {
 					error: err instanceof Error ? err.message : String(err)
 				});
 			}
-			await vectorIndexAddGuarded(evolved.id, evolved.sessionIds?.[0] ?? "memory", evolved.title + " " + evolved.content, {
+			await vectorIndexAddGuarded(evolved.id, evolved.sessionIds?.[0] ?? "memory", observationEmbedText({
+				title: evolved.title,
+				narrative: evolved.content,
+				concepts: evolved.concepts
+			}), {
 				kind: "memory",
 				logId: evolved.id
 			});
@@ -13094,7 +13458,7 @@ async function findByKeyword(kv, keyword, project) {
 }
 //#endregion
 //#region src/version.ts
-const VERSION = "0.9.31";
+const VERSION = "0.9.32";
 const III_PINNED_VERSION = "0.25.0";
 //#endregion
 //#region src/telemetry/setup.ts
@@ -13166,6 +13530,7 @@ function getFollowupStats() {
 	};
 }
 const LESSON_CONTENT_PREVIEW_CHARS = 240;
+const SCOPED_RETRY_CANDIDATES = 1e3;
 function registerSmartSearchFunction(sdk, kv, searchFn) {
 	sdk.registerFunction("mem::smart-search", async (data) => {
 		if (data.targetLayer !== void 0 && !isSearchLayer(data.targetLayer)) throw new Error("mem::smart-search: targetLayer must be one of 'all', 'memory', or 'observation'");
@@ -13242,16 +13607,32 @@ function registerSmartSearchFunction(sdk, kv, searchFn) {
 			return (await read(KV.sessions, sessionId))?.project === project;
 		};
 		const [hybridResults, lessons] = await Promise.all([searchFn(data.query, overFetchLimit, targetLayer, authorizeGraph), includeLessons ? recallLessons(sdk, data.query, lessonLimit, project) : Promise.resolve([])]);
-		const layerResults = hybridResults.filter((result) => matchesSearchLayer(result.observation.id, result.sessionId, targetLayer, result.layer ?? getSearchIndex().layerOf(result.observation.id)));
-		const projectResults = matchesProject ? await filterProjectResults(layerResults, (result) => matchesProject(result.observation.id, result.sessionId)) : layerResults;
-		const compact = (filterAgentId ? projectResults.filter((r) => r.observation.agentId === filterAgentId).slice(0, limit) : projectResults.slice(0, limit)).map((r) => ({
-			obsId: r.observation.id,
-			layer: r.layer ?? getSearchIndex().layerOf(r.observation.id) ?? getSearchResultLayer(r.observation.id, r.sessionId),
-			sessionId: r.sessionId,
-			title: r.observation.title,
-			type: r.observation.type,
-			score: r.combinedScore,
-			timestamp: r.observation.timestamp
+		const scopeResults = async (results) => {
+			const layerResults = results.filter((result) => matchesSearchLayer(result.observation.id, result.sessionId, targetLayer, result.layer ?? getSearchIndex().layerOf(result.observation.id)));
+			const projectResults = matchesProject ? await filterProjectResults(layerResults, (result) => matchesProject(result.observation.id, result.sessionId)) : layerResults;
+			return filterAgentId ? projectResults.filter((r) => r.observation.agentId === filterAgentId).slice(0, limit) : projectResults.slice(0, limit);
+		};
+		let filteredHybrid = await scopeResults(hybridResults);
+		if ((filterAgentId || project) && filteredHybrid.length < limit && getSearchIndex().size > overFetchLimit) try {
+			const deeper = await scopeResults(await searchFn(data.query, SCOPED_RETRY_CANDIDATES, targetLayer, authorizeGraph));
+			const seen = new Set(deeper.map((result) => result.observation.id));
+			filteredHybrid = [...deeper, ...filteredHybrid.filter((result) => !seen.has(result.observation.id))].slice(0, limit);
+		} catch (err) {
+			logger.warn("Smart search deeper scoped ranking failed; keeping first-pass results", { error: err instanceof Error ? err.message : String(err) });
+		}
+		const compact = await Promise.all(filteredHybrid.map(async (r) => {
+			const layer = r.layer ?? getSearchIndex().layerOf(r.observation.id) ?? getSearchResultLayer(r.observation.id, r.sessionId);
+			const memoryType = layer === "memory" ? (await kv.get(KV.memories, r.observation.id).catch(() => null))?.type ?? r.observation.memoryType : void 0;
+			return {
+				obsId: r.observation.id,
+				layer,
+				sessionId: r.sessionId,
+				title: r.observation.title,
+				type: r.observation.type,
+				...memoryType !== void 0 && { memoryType },
+				score: r.combinedScore,
+				timestamp: r.observation.timestamp
+			};
 		}));
 		recordAccessBatch(kv, compact.map((r) => r.obsId));
 		if (data.sessionId && typeof data.sessionId === "string" && data.source !== "viewer" && compact.length > 0) {
@@ -13452,6 +13833,7 @@ function registerRecentSearchesSweepFunction(sdk, kv) {
 const HOUR_MS = 3600 * 1e3;
 function isStaleActive(session, cutoff) {
 	if (!session || session.status !== "active") return false;
+	if (typeof session.id !== "string" || session.id.length === 0) return false;
 	const freshness = session.updatedAt ?? session.startedAt;
 	if (!freshness) return false;
 	const ts = new Date(freshness).getTime();
@@ -13747,6 +14129,7 @@ function registerAutoForgetFunction(sdk, kv) {
 				if (!dryRun) {
 					const older = new Date(memA.createdAt).getTime() < new Date(memB.createdAt).getTime() ? memA : memB;
 					older.isLatest = false;
+					older.updatedAt = supersededAt(older.updatedAt, (/* @__PURE__ */ new Date()).toISOString());
 					await kv.set(KV.memories, older.id, older);
 					await recordAudit(kv, "forget", "mem::auto-forget", [older.id], {
 						resource: "memory",
@@ -14269,6 +14652,7 @@ function registerLessonsFunctions(sdk, kv) {
 		lessonRecords.delete(lesson.id);
 		if (lessonIndex) lessonIndex.remove(lesson.id);
 		noteLessonMutation();
+		await deleteFacetsForTargets(kv, [lesson.id]);
 		try {
 			await recordAudit(kv, "lesson_delete", "mem::lesson-delete", [lesson.id]);
 		} catch {}
@@ -14314,11 +14698,14 @@ function registerLessonsFunctions(sdk, kv) {
 			}
 		}
 		await Promise.all(dirty.map((l) => kv.set(KV.lessons, l.id, l)));
+		const softDeletedIds = [];
 		for (const l of dirty) if (l.deleted) {
+			softDeletedIds.push(l.id);
 			lessonRecords.delete(l.id);
 			if (lessonIndex) lessonIndex.remove(l.id);
 		} else lessonRecords.set(l.id, l);
 		if (dirty.length > 0) noteLessonMutation();
+		if (softDeletedIds.length > 0) await deleteFacetsForTargets(kv, softDeletedIds);
 		await Promise.all(auditEvents.map((event) => recordAudit(kv, "lesson_strengthen", "mem::lesson-decay-sweep", [event.id], {
 			action: event.action,
 			actor: "system",
@@ -14567,7 +14954,8 @@ function registerExportImportFunction(sdk, state) {
 			"0.9.28",
 			"0.9.29",
 			"0.9.30",
-			"0.9.31"
+			"0.9.31",
+			"0.9.32"
 		]).has(importData.version)) return {
 			success: false,
 			error: `Unsupported export version: ${importData.version}`
@@ -17034,7 +17422,7 @@ function registerConsolidationPipelineFunction(sdk, kv, provider) {
 		if (!data?.force && !isConsolidationEnabled()) return {
 			success: false,
 			skipped: true,
-			reason: "Consolidation disabled: set CONSOLIDATION_ENABLED=true or configure an LLM provider (ANTHROPIC_API_KEY / OPENAI_API_KEY / OPENROUTER_API_KEY / GEMINI_API_KEY / GOOGLE_API_KEY / MINIMAX_API_KEY, or AGENTMEMORY_ALLOW_AGENT_SDK=true). OPENAI_BASE_URL alone only points an OpenAI key at another server; it is not a provider."
+			reason: "Consolidation disabled: set CONSOLIDATION_ENABLED=true or choose an LLM provider (AGENTMEMORY_LLM_PROVIDER=anthropic, openai, gemini, openrouter or minimax with that provider's key, or AGENTMEMORY_ALLOW_AGENT_SDK=true). A provider key alone does not turn on LLM use."
 		};
 		const tier = data?.tier || "all";
 		const decayDays = getConsolidationDecayDays();
@@ -24106,7 +24494,7 @@ const FUNCTION_FIXES = {
 	"mem::compress": "Compression calls your LLM provider. Check the provider key and model, or set AGENTMEMORY_AUTO_COMPRESS=false to use zero-LLM compression.",
 	"mem::graph-extract": "Graph extraction calls your LLM provider. Check the provider key and model, or set GRAPH_EXTRACTION_ENABLED=false."
 };
-const LLM_KEY_FIX = "Add one LLM provider key (for example ANTHROPIC_API_KEY or OPENAI_API_KEY) to ~/.agentmemory/.env and restart.";
+const LLM_KEY_FIX = "Set AGENTMEMORY_LLM_PROVIDER and that provider's key (for example AGENTMEMORY_LLM_PROVIDER=anthropic and ANTHROPIC_API_KEY) in ~/.agentmemory/.env and restart.";
 const OFF_WITHOUT_LLM = [
 	"session summaries",
 	"consolidation into semantic facts and procedures",
@@ -24215,8 +24603,17 @@ function evaluateStatus(input) {
 		level: "info",
 		code: "no-llm-provider",
 		message: "No LLM provider is configured, so summaries, consolidation and graph extraction stay off. Search still works.",
-		fix: LLM_KEY_FIX
+		fix: input.providerHint || "Set AGENTMEMORY_LLM_PROVIDER and that provider's key (for example AGENTMEMORY_LLM_PROVIDER=anthropic and ANTHROPIC_API_KEY) in ~/.agentmemory/.env and restart."
 	});
+	if (input.embeddingHint) {
+		const keyMissing = input.embeddingHint.startsWith("EMBEDDING_PROVIDER=");
+		problems.push({
+			level: "info",
+			code: keyMissing ? "embedding-provider-key-missing" : "embedding-provider-not-chosen",
+			message: keyMissing ? "EMBEDDING_PROVIDER names a cloud provider whose key is missing, so search is keyword and graph only." : "A cloud embedding key is present, but no embedding provider is chosen, so search is keyword and graph only.",
+			fix: input.embeddingHint
+		});
+	}
 	const noLlm = input.provider === "noop";
 	const functions = markLlmFunctions(input.functionMetrics, input.provider).map((m) => ({
 		...m,
@@ -24397,7 +24794,9 @@ function evaluateStatus(input) {
 		provider: {
 			llm: input.provider,
 			route: input.provider === "noop" ? null : input.llmRoute ?? null,
+			hint: input.providerHint ?? null,
 			embeddings: input.embeddingProvider,
+			embeddingHint: input.embeddingHint ?? null,
 			circuitBreaker: input.circuitBreaker,
 			offWithoutLlm: noLlm ? OFF_WITHOUT_LLM : []
 		},
@@ -25694,7 +26093,9 @@ function createStatusReporter(sdk, kv, deps) {
 			llmRoute: describeLlmRoute(config.provider),
 			functionMetrics: functionMetrics ?? [],
 			provider: detectLlmProviderKind(),
+			providerHint: llmOptInHint(),
 			embeddingProvider: describeEmbeddingProvider(),
+			embeddingHint: embeddingOptInHint(),
 			flags: buildConfigFlags(),
 			index: {
 				bm25Documents: idx.size,
@@ -25839,13 +26240,18 @@ function registerApiTriggers(sdk, kv, secret, metricsStore, provider) {
 	sdk.registerFunction("api::config-flags", async (req) => {
 		const authErr = checkAuth(req, secret);
 		if (authErr) return authErr;
+		const providerKind = detectLlmProviderKind();
+		const embeddingProvider = describeEmbeddingProvider();
+		const flags = buildConfigFlags();
 		return {
 			status_code: 200,
 			body: {
 				version: VERSION,
-				provider: detectLlmProviderKind(),
-				embeddingProvider: describeEmbeddingProvider(),
-				flags: buildConfigFlags()
+				provider: providerKind,
+				providerHint: llmOptInHint(),
+				embeddingProvider,
+				embeddingHint: embeddingOptInHint(),
+				flags
 			}
 		};
 	});
@@ -29696,6 +30102,45 @@ function registerApiTriggers(sdk, kv, secret, metricsStore, provider) {
 			http_method: "POST"
 		}
 	});
+	sdk.registerFunction("api::lesson-get", async (req) => {
+		const denied = checkAuth(req, secret);
+		if (denied) return denied;
+		const body = req.body;
+		const lessonId = typeof body?.lessonId === "string" ? body.lessonId.trim() : "";
+		if (!lessonId) return {
+			status_code: 400,
+			body: { error: "lessonId is required" }
+		};
+		if (body.project !== void 0 && typeof body.project !== "string") return {
+			status_code: 400,
+			body: { error: "project must be a string" }
+		};
+		const project = typeof body.project === "string" ? body.project.trim() : "";
+		const lesson = await kv.get(KV.lessons, lessonId);
+		if (!lesson || lesson.deleted) return {
+			status_code: 404,
+			body: { error: "lesson not found" }
+		};
+		if (lesson.project !== void 0 && lesson.project !== project) return {
+			status_code: 404,
+			body: { error: "lesson not found" }
+		};
+		return {
+			status_code: 200,
+			body: {
+				success: true,
+				lesson
+			}
+		};
+	});
+	sdk.registerTrigger({
+		type: "http",
+		function_id: "api::lesson-get",
+		config: {
+			api_path: "/agentmemory/lessons/get",
+			http_method: "POST"
+		}
+	});
 	sdk.registerFunction("api::lesson-strengthen", async (req) => {
 		const denied = checkAuth(req, secret);
 		if (denied) return denied;
@@ -30461,6 +30906,59 @@ function registerViewerSse(sdk) {
 }
 //#endregion
 //#region src/mcp/tools-registry.ts
+const READ_ONLY_TOOLS = new Set([
+	"memory_recall",
+	"memory_file_history",
+	"memory_patterns",
+	"memory_sessions",
+	"memory_smart_search",
+	"memory_vision_search",
+	"memory_timeline",
+	"memory_export",
+	"memory_relations",
+	"memory_commit_lookup",
+	"memory_commits",
+	"memory_graph_query",
+	"memory_team_feed",
+	"memory_audit",
+	"memory_frontier",
+	"memory_next",
+	"memory_diagnose",
+	"memory_facet_query",
+	"memory_verify",
+	"memory_lesson_recall",
+	"memory_insight_list",
+	"memory_slot_list",
+	"memory_slot_get"
+]);
+const DESTRUCTIVE_TOOLS = new Set([
+	"memory_action_update",
+	"memory_compress_file",
+	"memory_claude_bridge_sync",
+	"memory_governance_delete",
+	"memory_heal",
+	"memory_lesson_delete",
+	"memory_obsidian_export",
+	"memory_slot_replace",
+	"memory_slot_delete"
+]);
+const IDEMPOTENT_WRITE_TOOLS = new Set([
+	"memory_governance_delete",
+	"memory_lesson_delete",
+	"memory_slot_replace",
+	"memory_slot_delete",
+	"memory_claude_bridge_sync"
+]);
+const OPEN_WORLD_TOOLS = new Set(["memory_mesh_sync"]);
+function toolAnnotations(name) {
+	const readOnly = READ_ONLY_TOOLS.has(name);
+	return {
+		readOnlyHint: readOnly,
+		destructiveHint: !readOnly && DESTRUCTIVE_TOOLS.has(name),
+		idempotentHint: readOnly || IDEMPOTENT_WRITE_TOOLS.has(name),
+		openWorldHint: OPEN_WORLD_TOOLS.has(name)
+	};
+}
 const CORE_TOOLS = [
 	{
 		name: "memory_recall",
@@ -31441,6 +31939,11 @@ const V070_TOOLS = [
 				tags: {
 					type: "string",
 					description: "Comma-separated tags"
+				},
+				sourceIds: {
+					type: "array",
+					items: { type: "string" },
+					description: "Ids of the session, memory, observation or crystal this lesson came from (max 50)"
 				}
 			},
 			required: ["content"]
@@ -31663,7 +32166,10 @@ function getAllTools() {
 		...V070_TOOLS,
 		...V073_TOOLS,
 		...V010_SLOTS_TOOLS
-	];
+	].map((tool) => ({
+		...tool,
+		annotations: toolAnnotations(tool.name)
+	}));
 }
 function getVisibleTools() {
 	if ((process.env["AGENTMEMORY_TOOLS"] || "all") === "core") return getAllTools().filter((t) => ESSENTIAL_TOOLS.has(t.name));
@@ -31719,13 +32225,18 @@ function parseCsvList(value) {
 	if (Array.isArray(value)) return value.map((v) => typeof v === "string" ? v.trim() : "").filter(Boolean);
 	return [];
 }
+const SLOT_TOOL_NAMES = new Set(getAllTools().filter((t) => t.name.startsWith("memory_slot_")).map((t) => t.name));
+function isSlotTool(name) {
+	return SLOT_TOOL_NAMES.has(name);
+}
 function registerMcpEndpoints(sdk, kv, secret) {
+	const slotsEnabled = isSlotsEnabled();
 	sdk.registerFunction("mcp::tools::list", async (req) => {
 		const authErr = checkAuth(req, secret);
 		if (authErr) return authErr;
 		return {
 			status_code: 200,
-			body: { tools: getVisibleTools() }
+			body: { tools: getVisibleTools().filter((t) => slotsEnabled || !isSlotTool(t.name)) }
 		};
 	});
 	sdk.registerTrigger({
@@ -31744,6 +32255,7 @@ function registerMcpEndpoints(sdk, kv, secret) {
 			body: { error: "name is required" }
 		};
 		const { name, arguments: args = {} } = req.body;
+		if (isSlotTool(name) && !slotsEnabled) return slotsDisabledResponse();
 		try {
 			switch (name) {
 				case "memory_recall": {
@@ -32765,6 +33277,11 @@ function registerMcpEndpoints(sdk, kv, secret) {
 						body: { error: "content is required" }
 					};
 					const lessonTags = typeof args.tags === "string" && args.tags.trim() ? args.tags.split(",").map((t) => t.trim()).filter(Boolean) : [];
+					const lessonSourceIds = normalizeLessonSourceIds(args.sourceIds);
+					if (!lessonSourceIds) return {
+						status_code: 400,
+						body: { error: `sourceIds must be an array of at most 50 ids (session, memory, observation or crystal ids) without spaces` }
+					};
 					const lessonSaveResult = await sdk.trigger({
 						function_id: "mem::lesson-save",
 						payload: {
@@ -32773,7 +33290,8 @@ function registerMcpEndpoints(sdk, kv, secret) {
 							confidence: args.confidence,
 							project: args.project,
 							tags: lessonTags,
-							source: "manual"
+							source: "manual",
+							sourceIds: lessonSourceIds
 						}
 					});
 					return {
@@ -33195,24 +33713,16 @@ function registerMcpEndpoints(sdk, kv, secret) {
 				};
 			}
 			if (uri === "agentmemory://graph/stats") try {
-				const graphState = await pinGraphState(kv);
-				const nodes = await graphState.list(KV.graphNodes);
-				const edges = await graphState.list(KV.graphEdges);
-				const nodesByType = {};
-				for (const n of nodes) nodesByType[n.type] = (nodesByType[n.type] || 0) + 1;
-				const edgesByType = {};
-				for (const e of edges) edgesByType[e.type] = (edgesByType[e.type] || 0) + 1;
+				const stats = await sdk.trigger({
+					function_id: "mem::graph-stats",
+					payload: {}
+				});
 				return {
 					status_code: 200,
 					body: { contents: [{
 						uri,
 						mimeType: "application/json",
-						text: JSON.stringify({
-							totalNodes: nodes.length,
-							totalEdges: edges.length,
-							nodesByType,
-							edgesByType
-						})
+						text: JSON.stringify(stats)
 					}] }
 				};
 			} catch {
@@ -33222,8 +33732,15 @@ function registerMcpEndpoints(sdk, kv, secret) {
 						uri,
 						mimeType: "application/json",
 						text: JSON.stringify({
-							totalNodes: 0,
-							totalEdges: 0
+							totalNodes: null,
+							totalEdges: null,
+							nodesByType: {},
+							edgesByType: {},
+							fromSnapshot: false,
+							fromIndex: false,
+							available: false,
+							coverage: "unknown",
+							warning: "Graph stats are unavailable. Check agentmemory graph-index status."
 						})
 					}] }
 				};
@@ -33652,14 +34169,18 @@ async function main() {
 	const config = loadConfig();
 	const embeddingConfig = loadEmbeddingConfig();
 	const fallbackConfig = loadFallbackConfig();
-	const provider = fallbackConfig.providers.length > 0 ? createFallbackProvider(config.provider, fallbackConfig) : createProvider(config.provider);
+	const provider = fallbackConfig.providers.length > 0 && config.provider.provider !== "noop" ? createFallbackProvider(config.provider, fallbackConfig) : createProvider(config.provider);
 	const embeddingProvider = createEmbeddingProvider();
 	const imageEmbeddingProvider = createImageEmbeddingProvider();
 	bootLog(`Starting worker v${VERSION}...`);
 	bootLog(`Engine: ${config.engineUrl}`);
 	bootLog(`Provider: ${config.provider.provider} (${config.provider.model})`);
 	if (embeddingProvider) bootLog(`Embedding provider: ${embeddingProvider.name} (${embeddingProvider.dimensions} dims)`);
-	else bootLog(`Embedding provider: none (BM25-only mode)`);
+	else {
+		bootLog(`Embedding provider: none (BM25-only mode)`);
+		const embeddingHint = embeddingOptInHint();
+		if (embeddingHint) bootLog(embeddingHint);
+	}
 	if (imageEmbeddingProvider) bootLog(`Image embedding provider: ${imageEmbeddingProvider.name} (${imageEmbeddingProvider.dimensions} dims) — vision-search active`);
 	bootLog(`REST API: http://localhost:${config.restPort}/agentmemory/*`);
 	const sdk = withWriteScrubbing(registerWorker(config.engineUrl, {
@@ -33682,6 +34203,9 @@ async function main() {
 		stateBackend = getStateBackend();
 	} catch {}
 	const kv = new StateKV(sdk, { backend: stateBackend });
+	const stateReadiness = await waitForStateReady(sdk, { onWaiting: (error) => bootWarn(`Waiting for the state worker to register state::get and state::list (${error})`) });
+	assertStateReady(stateReadiness);
+	if (stateReadiness.attempts > 1) bootLog(`State worker ready after ${stateReadiness.waitedMs}ms (${stateReadiness.attempts} attempts)`);
 	const secret = resolveWorkerSecret();
 	const metricsStore = new MetricsStore(kv);
 	const dedupMap = new DedupMap();
@@ -33786,7 +34310,7 @@ async function main() {
 	const bm25Index = getSearchIndex();
 	const graphWeight = parseFloat(getEnvVar("AGENTMEMORY_GRAPH_WEIGHT") || "0.3");
 	const hybridSearch = new HybridSearch(bm25Index, vectorIndex, embeddingProvider, kv, embeddingConfig.bm25Weight, embeddingConfig.vectorWeight, graphWeight);
-	const hybridRanker = (query, limit, targetLayer, authorizeGraph) => hybridSearch.search(query, limit, targetLayer, authorizeGraph);
+	const hybridRanker = (query, limit, targetLayer, authorizeGraph, request) => hybridSearch.search(query, limit, targetLayer, authorizeGraph, request);
 	registerSmartSearchFunction(sdk, kv, hybridRanker);
 	setHybridRanker(hybridRanker);
 	registerRecentSearchesSweepFunction(sdk, kv);
@@ -33884,7 +34408,7 @@ async function main() {
 		console.warn(`[agentmemory] Failed to rebuild the BM25 index:`, err);
 	}
 	bootLog(`Ready. ${embeddingProvider ? "Triple-stream (BM25+Vector+Graph)" : "BM25+Graph"} search active.`);
-	bootLog(`REST API: 146 endpoints at http://localhost:${config.restPort}/agentmemory/*`);
+	bootLog(`REST API: 147 endpoints at http://localhost:${config.restPort}/agentmemory/*`);
 	bootLog(`MCP surface (opt-in via \`npx @agentmemory/mcp\`): ${getAllTools().length} tools · 6 resources · 3 prompts`);
 	(async () => {
 		try {