@graphorin/memory 0.5.0

package/dist/tiers/semantic-memory.js

@@ -0,0 +1,631 @@
+import { withMemorySpan } from "../internal/spans.js";
+import { QuarantinePromotionRefusedError } from "../errors/index.js";
+import { contextualize } from "../internal/contextualize.js";
+import { newMemoryId } from "../internal/id.js";
+import { DEFAULT_MAX_ITERATIONS, runIterativeRetrieval } from "../search/iterative.js";
+import { WeightedRRFReranker, fuseRrf, fuseWeighted } from "../search/rrf.js";
+import { detectMemoryInjection } from "../internal/injection-heuristics.js";
+import { explainRecall } from "../search/explain.js";
+import { md5 } from "@graphorin/core";
+
+//#region src/tiers/semantic-memory.ts
+/**
+* `SemanticMemory` — long-term factual store. Hybrid (vector + FTS5)
+* search merges the two ranked lists through the configured
+* {@link ReRanker} (default {@link RRFReranker} with `k = 60`).
+*
+* Phase 10a wrote facts straight through with MD5 deduplication;
+* Phase 10b routes every `remember(...)` call through the multi-stage
+* conflict resolution pipeline (DEC-117 / ADR-018 ext / RB-02). The
+* pipeline can be disabled per-call (`pipeline: 'off'`) or per-`Memory`
+* instance (`createMemory({ conflictPipeline: { mode: 'off' } })`).
+*
+* @stable
+*/
+var SemanticMemory = class {
+	#store;
+	#tracer;
+	#embedder;
+	#embedderIdProvider;
+	#pipeline;
+	#contextualMode;
+	#queryTransformer;
+	#entityResolver;
+	#grader;
+	#iterativeMaxIterations;
+	#reranker;
+	constructor(args) {
+		this.#store = args.store;
+		this.#tracer = args.tracer;
+		this.#embedder = args.embedder;
+		this.#embedderIdProvider = args.embedderIdProvider;
+		this.#reranker = args.reranker;
+		this.#pipeline = args.conflictPipeline ?? null;
+		this.#contextualMode = args.contextualRetrieval ?? "late-chunk";
+		this.#queryTransformer = args.queryTransformer ?? null;
+		this.#entityResolver = args.entityResolver ?? null;
+		this.#grader = args.grader ?? null;
+		this.#iterativeMaxIterations = args.iterativeMaxIterations ?? DEFAULT_MAX_ITERATIONS;
+	}
+	/** Replace the active reranker. Returns the previous instance. */
+	setReranker(reranker) {
+		const previous = this.#reranker;
+		this.#reranker = reranker;
+		return previous;
+	}
+	/** Currently active reranker. */
+	reranker() {
+		return this.#reranker;
+	}
+	/**
+	* Persist a fact. Returns the stored record. Phase 10b routes every
+	* call through the multi-stage conflict resolution pipeline; the
+	* legacy straight-through path is reachable per-call via
+	* `{ pipeline: 'off' }` (operators may disable the pipeline globally
+	* via `createMemory({ conflictPipeline: { mode: 'off' } })`).
+	*/
+	async remember(scope, input, options = {}) {
+		const { fact } = await this.rememberWithDecision(scope, input, options);
+		return fact;
+	}
+	/**
+	* Like {@link remember} but returns the pipeline `decision` alongside
+	* the stored fact. Useful for callers that need to distinguish
+	* silent dedups (`decision.kind === 'dedup'`) from fresh inserts.
+	*
+	* @stable
+	*/
+	async rememberWithDecision(scope, input, options = {}) {
+		return withMemorySpan(this.#tracer, "memory.write.semantic", scope, {}, async (span) => {
+			const now = (/* @__PURE__ */ new Date()).toISOString();
+			const text = input.text;
+			const provenance = input.provenance;
+			const synthesized = provenance === "extraction" || provenance === "reflection" || provenance === "induction";
+			const injection = detectMemoryInjection(text);
+			const autoPromote = options.autoPromoteSynthesized === true;
+			const status = injection.flagged ? "quarantined" : synthesized && !autoPromote ? "quarantined" : "active";
+			const quarantineReason = status === "quarantined" ? injection.flagged ? "injection" : "synthesized" : void 0;
+			const fact = {
+				id: newMemoryId("fact"),
+				kind: "semantic",
+				userId: scope.userId,
+				...scope.sessionId !== void 0 ? { sessionId: scope.sessionId } : {},
+				...scope.agentId !== void 0 ? { agentId: scope.agentId } : {},
+				sensitivity: input.sensitivity ?? "internal",
+				text,
+				...input.subject !== void 0 ? { subject: input.subject } : {},
+				...input.predicate !== void 0 ? { predicate: input.predicate } : {},
+				...input.object !== void 0 ? { object: input.object } : {},
+				...input.confidence !== void 0 ? { confidence: input.confidence } : {},
+				...typeof input.importance === "number" && Number.isFinite(input.importance) ? { importance: Math.min(1, Math.max(0, input.importance)) } : {},
+				...input.tags !== void 0 ? { tags: Object.freeze([...input.tags]) } : {},
+				...input.validFrom !== void 0 ? { validFrom: input.validFrom } : { validFrom: now },
+				...input.validTo !== void 0 ? { validTo: input.validTo } : {},
+				...input.supersedes !== void 0 ? { supersedes: input.supersedes } : {},
+				...provenance !== void 0 ? { provenance } : {},
+				status,
+				createdAt: now,
+				updatedAt: now
+			};
+			const embedderId = this.#embedderIdProvider();
+			const embedder = this.#embedder;
+			const indexText = this.#resolveIndexText(input, fact.text, options.indexText);
+			const pipelineEnabled = this.#pipeline !== null && (options.pipeline ?? "on") === "on";
+			const decision = pipelineEnabled && this.#pipeline !== null ? await this.#pipeline.run({
+				store: this.#store,
+				tracer: this.#tracer,
+				embedder,
+				embedderId,
+				...options.signal !== void 0 ? { signal: options.signal } : {}
+			}, fact) : {
+				kind: "admit",
+				stage: "exact-dedup",
+				reason: "pipeline-skipped"
+			};
+			span.setAttributes({
+				"memory.semantic.text_length": text.length,
+				"memory.semantic.hash": md5(text),
+				"memory.semantic.pipeline.decision": decision.kind,
+				"memory.semantic.pipeline.stage": decision.stage,
+				"memory.semantic.pipeline.enabled": pipelineEnabled,
+				"memory.semantic.status": status,
+				"memory.semantic.contextualized": indexText !== text,
+				...provenance !== void 0 ? { "memory.semantic.provenance": provenance } : {},
+				"memory.semantic.injection_flagged": injection.flagged,
+				...injection.flagged ? { "memory.semantic.injection_markers": injection.markers.join(",") } : {}
+			});
+			const reasonField = quarantineReason !== void 0 ? { quarantineReason } : {};
+			switch (decision.kind) {
+				case "admit":
+				case "pending":
+					await this.#commitFact(fact, embedder, embedderId, indexText);
+					await this.#linkEntities(scope, fact, options.signal);
+					return {
+						fact,
+						decision,
+						...reasonField
+					};
+				case "dedup": return {
+					fact: await this.#fetchExisting(decision.existingId) ?? fact,
+					decision
+				};
+				case "supersede":
+					await this.#commitFact(fact, embedder, embedderId, indexText);
+					await this.#store.semantic.supersede(decision.existingId, fact, decision.reason);
+					await this.#linkEntities(scope, fact, options.signal);
+					return {
+						fact,
+						decision,
+						...reasonField
+					};
+			}
+		});
+	}
+	/**
+	* Resolve the contextual-retrieval index text (P1-3). A caller
+	* override (the consolidator's `'llm'` mode) takes precedence; then
+	* the instance mode decides. Late-chunk derives the situating context
+	* from the *author-supplied* signals on `input` (so an extraction's
+	* subject/predicate/object survive even though the persisted `Fact`
+	* drops them) and never from framework-defaulted fields, so a plain
+	* `remember({ text })` write returns the canonical text unchanged.
+	*/
+	#resolveIndexText(input, canonicalText, override) {
+		if (override !== void 0) return override;
+		if (this.#contextualMode === "off") return canonicalText;
+		return contextualize({
+			text: canonicalText,
+			...input.subject !== void 0 ? { subject: input.subject } : {},
+			...input.predicate !== void 0 ? { predicate: input.predicate } : {},
+			...input.object !== void 0 ? { object: input.object } : {},
+			...input.tags !== void 0 ? { tags: input.tags } : {},
+			...input.validFrom !== void 0 ? { validFrom: input.validFrom } : {}
+		});
+	}
+	async #commitFact(fact, embedder, embedderId, indexText) {
+		const adapterSupportsEmbeddedWrite = typeof this.#store.semantic.rememberWithEmbedding === "function";
+		const contextualized = indexText !== fact.text;
+		if (embedder !== null && embedderId !== null && adapterSupportsEmbeddedWrite) {
+			const [vector] = await embedder.embed([indexText], { taskType: "passage" });
+			if (vector !== void 0 && this.#store.semantic.rememberWithEmbedding !== void 0) {
+				await this.#store.semantic.rememberWithEmbedding(fact, {
+					embedding: {
+						embedderId,
+						vector
+					},
+					...contextualized ? { indexText } : {}
+				});
+				return;
+			}
+		}
+		if (contextualized && adapterSupportsEmbeddedWrite && this.#store.semantic.rememberWithEmbedding !== void 0) {
+			await this.#store.semantic.rememberWithEmbedding(fact, { indexText });
+			return;
+		}
+		await this.#store.semantic.remember(fact);
+	}
+	async #fetchExisting(factId) {
+		if (typeof this.#store.semantic.get !== "function") return null;
+		return this.#store.semantic.get(factId);
+	}
+	/**
+	* P2-1: resolve the fact's subject / object to canonical entities and
+	* link them so one-hop expansion can traverse this fact. A no-op when
+	* no resolver is configured (the default) or the fact has no s/p/o, and
+	* resilient — a resolution failure never breaks the write that just
+	* committed.
+	*/
+	async #linkEntities(scope, fact, signal) {
+		if (this.#entityResolver === null) return;
+		if (fact.subject === void 0 && fact.object === void 0) return;
+		try {
+			await this.#entityResolver.linkFact(scope, fact, { ...signal !== void 0 ? { signal } : {} });
+		} catch {}
+	}
+	/** Hybrid (vector + FTS5) search merged through the configured reranker. */
+	async search(scope, query, opts = {}) {
+		return withMemorySpan(this.#tracer, "memory.search.semantic", scope, { "memory.search.query_length": query.length }, async (span) => {
+			const candidateTopK = opts.candidateTopK ?? 60;
+			const finalTopK = opts.topK ?? 10;
+			const weighted = opts.fusion !== void 0 && opts.fusion.strategy === "weighted" ? opts.fusion : null;
+			const wFts = weighted?.weights.fts ?? 1;
+			const wVector = weighted?.weights.vector ?? 1;
+			const queries = await this.#expandQueries(query, opts);
+			const lists = [];
+			const listWeights = [];
+			const listLabels = [];
+			let primaryFtsCount = 0;
+			let primaryVectorCount = 0;
+			let isPrimary = true;
+			for (const q of queries) {
+				const ftsHits = await this.#store.semantic.search(scope, {
+					query: q,
+					topK: candidateTopK,
+					...opts.asOf !== void 0 ? { asOf: opts.asOf } : {},
+					...opts.tags !== void 0 && opts.tags.length > 0 ? { tags: opts.tags } : {},
+					...opts.includeQuarantined === true ? { includeQuarantined: true } : {},
+					...opts.signal !== void 0 ? { signal: opts.signal } : {}
+				});
+				lists.push(ftsHits);
+				listWeights.push(wFts);
+				listLabels.push(`fts_${queries.indexOf(q)}`);
+				const vectorHits = await this.#tryVectorSearch(scope, q, candidateTopK, opts.asOf, opts.includeQuarantined);
+				if (vectorHits.length > 0) {
+					lists.push(vectorHits);
+					listWeights.push(wVector);
+					listLabels.push(`vector_${queries.indexOf(q)}`);
+				}
+				if (isPrimary) {
+					primaryFtsCount = ftsHits.length;
+					primaryVectorCount = vectorHits.length;
+					isPrimary = false;
+				}
+			}
+			const hydeHits = await this.#tryHyde(scope, query, opts, candidateTopK);
+			if (hydeHits.length > 0) {
+				lists.push(hydeHits);
+				listWeights.push(wVector);
+				listLabels.push("hyde");
+			}
+			const graphHits = await this.#tryExpandHops(scope, lists, opts, candidateTopK);
+			if (graphHits.length > 0) {
+				lists.push(graphHits);
+				listWeights.push(1);
+				listLabels.push("graph");
+			}
+			const reranker = weighted !== null ? new WeightedRRFReranker({
+				weights: listWeights,
+				...weighted.k !== void 0 ? { k: weighted.k } : {}
+			}) : this.#reranker;
+			const fusedTopK = opts.decay !== void 0 ? Math.max(finalTopK, lists.reduce((n, l) => n + l.length, 0)) : finalTopK;
+			const fused = await reranker.rerank(query, lists, {
+				topK: fusedTopK,
+				labels: listLabels,
+				...opts.signal !== void 0 ? { signal: opts.signal } : {}
+			});
+			const decayed = await this.#applyDecay(scope, fused, opts.decay);
+			const ranked = (opts.tags !== void 0 && opts.tags.length > 0 ? decayed.filter((h) => {
+				const recordTags = h.record.tags;
+				if (recordTags === void 0 || recordTags.length === 0) return false;
+				return opts.tags?.some((t) => recordTags.includes(t)) === true;
+			}) : decayed).slice(0, finalTopK);
+			if (ranked.length > 0 && typeof this.#store.semantic.markAccessed === "function") try {
+				await this.#store.semantic.markAccessed(ranked.map((h) => h.record.id));
+			} catch {}
+			const explanation = explainRecall(ranked, {
+				query,
+				rerankerId: reranker.id
+			});
+			span.setAttributes({
+				"memory.search.semantic.fts_count": primaryFtsCount,
+				"memory.search.semantic.vector_count": primaryVectorCount,
+				"memory.search.semantic.final_count": ranked.length,
+				"memory.search.semantic.reranker_id": reranker.id,
+				"memory.search.semantic.decay_applied": opts.decay !== void 0,
+				"memory.search.semantic.query_count": queries.length,
+				"memory.search.semantic.hyde_applied": hydeHits.length > 0,
+				"memory.search.semantic.expand_hops": opts.expandHops ?? 0,
+				"memory.search.semantic.graph_count": graphHits.length,
+				"memory.search.semantic.explain": JSON.stringify(explanation.results),
+				...opts.asOf !== void 0 ? { "memory.search.semantic.as_of": opts.asOf } : {},
+				...opts.includeQuarantined === true ? { "memory.search.semantic.include_quarantined": true } : {}
+			});
+			return ranked;
+		});
+	}
+	/**
+	* Gated, iterative ("deep") recall for hard queries (P2-4). A cheap
+	* local heuristic ({@link assessQueryDifficulty}) decides whether the
+	* query is even a loop candidate; simple lookups take exactly one
+	* {@link search} pass and make no provider call. For a query judged
+	* hard *and* with a grader configured
+	* (`createMemory({ iterativeRetrieval })`), the retrieved set is graded
+	* for sufficiency and, when weak, the query is reformulated and
+	* retrieved again — **widening to one-hop graph expansion**
+	* (`expandHops: 1`) on each reformulation pass — up to `maxIterations`
+	* (hard-capped at 5). When still insufficient it returns
+	* `abstained: true` so the caller can decline to answer instead of
+	* confabulating.
+	*
+	* Without a grader (the offline default) this degrades to a single,
+	* difficulty-gated `search` and never calls a provider.
+	*
+	* @stable
+	*/
+	async searchIterative(scope, query, opts = {}) {
+		return withMemorySpan(this.#tracer, "memory.search.semantic", scope, { "memory.search.query_length": query.length }, async (span) => {
+			const result = await runIterativeRetrieval(query, {
+				retrieve: (q, widen, signal) => this.search(scope, q, {
+					...opts,
+					...widen ? { expandHops: 1 } : {},
+					...signal !== void 0 ? { signal } : {}
+				}),
+				snippetOf: (hit) => hit.record.text,
+				idOf: (hit) => hit.record.id,
+				grader: this.#grader,
+				fuse: (lists) => fuseRrf(lists, 60)
+			}, {
+				maxIterations: opts.maxIterations ?? this.#iterativeMaxIterations,
+				maxResults: opts.topK ?? 10,
+				...opts.forceHard !== void 0 ? { forceHard: opts.forceHard } : {},
+				...opts.signal !== void 0 ? { signal: opts.signal } : {}
+			});
+			span.setAttributes({
+				"memory.search.semantic.iterative.gate_hard": result.gateHard,
+				"memory.search.semantic.iterative.iterations": result.iterations,
+				"memory.search.semantic.iterative.sufficient": result.sufficient,
+				"memory.search.semantic.iterative.abstained": result.abstained,
+				"memory.search.semantic.iterative.query_count": result.queries.length,
+				"memory.search.semantic.iterative.final_count": result.hits.length
+			});
+			return result;
+		});
+	}
+	/**
+	* Raw vector KNN neighbours for the consolidator's reconcile
+	* pre-filter (P0-3). Unlike {@link search} this skips FTS, reranking,
+	* and decay so the cosine scores survive intact (the conflict-pipeline
+	* zone thresholds are calibrated against them), and it **includes
+	* quarantined facts** so prior synthesized memories are visible to
+	* reconciliation. Returns `[]` when no embedder / vector adapter is
+	* configured — the consolidator then treats every candidate as a
+	* fresh `add`, degrading gracefully to the pre-reconcile behaviour.
+	*
+	* @stable
+	*/
+	async neighbors(scope, text, opts = {}) {
+		return this.#tryVectorSearch(scope, text, opts.topK ?? 10, void 0, true);
+	}
+	/** Lookup a single fact by id. Returns `null` for soft-deleted / missing. */
+	async get(scope, factId) {
+		return withMemorySpan(this.#tracer, "memory.read.semantic", scope, { "memory.semantic.fact_id": factId }, async (span) => {
+			if (typeof this.#store.semantic.get !== "function") throw new TypeError("[graphorin/memory] SemanticMemory.get(...) requires a storage adapter that implements `semantic.get(id)`. The default `@graphorin/store-sqlite` adapter implements it; custom adapters can opt in via SemanticMemoryStoreExt.");
+			const fact = await this.#store.semantic.get(factId);
+			span.setAttributes({ "memory.read.semantic.found": fact !== null });
+			return fact;
+		});
+	}
+	/**
+	* Return the full bi-temporal supersede chain that `factId` belongs
+	* to, oldest → newest, including superseded / soft-deleted rows so
+	* callers can answer "how did this fact change over time". Requires
+	* a storage adapter that implements
+	* `SemanticMemoryStoreExt.historyOf(...)` — the default
+	* `@graphorin/store-sqlite` adapter wires this through. P0-2.
+	*
+	* @stable
+	*/
+	async history(scope, factId) {
+		return withMemorySpan(this.#tracer, "memory.read.semantic", scope, {
+			"memory.semantic.action": "history",
+			"memory.semantic.fact_id": factId
+		}, async (span) => {
+			if (typeof this.#store.semantic.historyOf !== "function") throw new TypeError("[graphorin/memory] SemanticMemory.history(...) requires a storage adapter that implements `semantic.historyOf(scope, id)`. The default `@graphorin/store-sqlite` adapter implements it; custom adapters can opt in via SemanticMemoryStoreExt.");
+			const chain = await this.#store.semantic.historyOf(scope, factId);
+			span.setAttributes({ "memory.read.semantic.history_length": chain.length });
+			return chain;
+		});
+	}
+	/**
+	* Promote a quarantined fact to `active` (P1-4). The validation path
+	* that admits a synthesized memory into action-driving recall once a
+	* human (or trusted non-agent caller) has reviewed it. Writes a
+	* `memory_history` audit row. Requires a storage adapter that
+	* implements `SemanticMemoryStoreExt.setStatus(...)` — the default
+	* `@graphorin/store-sqlite` adapter wires this through.
+	*
+	* MRET-3 / MST-1: promotion of a fact whose text still trips the
+	* offline injection heuristics is **refused** with
+	* {@link QuarantinePromotionRefusedError} — the model-facing
+	* `fact_validate` tool calls this with no `force`, so a poisoned
+	* memory can never be promoted by the agent itself (the one-turn
+	* `fact_remember(poison)` → `fact_validate(id)` chain is closed). An
+	* operator can override after review by passing `{ force: true }`
+	* from a trusted (non-agent) context. Synthesized-but-clean writes
+	* (consolidator / reflection) promote normally.
+	*
+	* @stable
+	*/
+	async validate(scope, factId, reason, options) {
+		await withMemorySpan(this.#tracer, "memory.write.semantic", scope, {
+			"memory.semantic.action": "validate",
+			"memory.semantic.fact_id": factId
+		}, async (span) => {
+			if (typeof this.#store.semantic.setStatus !== "function") throw new TypeError("[graphorin/memory] SemanticMemory.validate(...) requires a storage adapter that implements `semantic.setStatus(id, status)`. The default `@graphorin/store-sqlite` adapter implements it; custom adapters can opt in via SemanticMemoryStoreExt.");
+			const force = options?.force === true;
+			const existing = await this.#fetchExisting(factId);
+			if (existing !== null && !force) {
+				const injection = detectMemoryInjection(existing.text);
+				if (injection.flagged) {
+					span.setAttributes({
+						"memory.semantic.validate.refused": true,
+						"memory.semantic.injection_markers": injection.markers.join(",")
+					});
+					throw new QuarantinePromotionRefusedError(factId, injection.markers);
+				}
+			}
+			span.setAttributes({ "memory.semantic.validate.forced": force });
+			await this.#store.semantic.setStatus(factId, "active", reason);
+		});
+	}
+	/** Mark `oldId` superseded by a new fact. Returns the new record. */
+	async supersede(scope, oldId, newInput, reason) {
+		return withMemorySpan(this.#tracer, "memory.write.semantic", scope, { "memory.semantic.action": "supersede" }, async () => {
+			const newFact = await this.remember(scope, {
+				...newInput,
+				supersedes: oldId
+			}, { pipeline: "off" });
+			await this.#store.semantic.supersede(oldId, newFact, reason);
+			return {
+				old: oldId,
+				new: newFact
+			};
+		});
+	}
+	/** Soft-delete a fact (kept for replay; never hard-deleted). */
+	async forget(scope, factId, reason) {
+		await withMemorySpan(this.#tracer, "memory.write.semantic", scope, {
+			"memory.semantic.action": "forget",
+			"memory.semantic.fact_id": factId
+		}, async () => {
+			await this.#store.semantic.forget(factId, reason);
+		});
+	}
+	/**
+	* Hard-delete a fact (GDPR path). Distinct from {@link forget}: the
+	* record is removed from storage entirely instead of soft-archived.
+	* Requires a storage adapter that implements
+	* `SemanticMemoryStoreExt.purge(...)` — the default
+	* `@graphorin/store-sqlite` adapter wires this through.
+	*/
+	async purge(scope, factId, reason) {
+		await withMemorySpan(this.#tracer, "memory.write.semantic", scope, {
+			"memory.semantic.action": "purge",
+			"memory.semantic.fact_id": factId
+		}, async () => {
+			if (typeof this.#store.semantic.purge !== "function") throw new TypeError("[graphorin/memory] SemanticMemory.purge(...) requires a storage adapter that implements `semantic.purge(id)`. For storage adapters without GDPR-grade hard-delete, prefer `SemanticMemory.forget(...)`.");
+			await this.#store.semantic.purge(factId, reason);
+		});
+	}
+	/** Fuse multiple ranked lists outside of a `search()` call. */
+	async fuse(query, lists, options = {}) {
+		return this.#reranker.rerank(query, lists, options);
+	}
+	/** Pure-fusion helper — exposed for callers that already collected results. */
+	static fuseRrf(lists, k = 60) {
+		return fuseRrf(lists, k);
+	}
+	/**
+	* Pure weighted-fusion helper (X-2) — like {@link SemanticMemory.fuseRrf}
+	* but scales each list `i`'s reciprocal-rank contribution by
+	* `weights[i]`. A missing / invalid entry defaults to `1`, so equal or
+	* absent weights reproduce RRF.
+	*/
+	static fuseWeighted(lists, weights, k = 60) {
+		return fuseWeighted(lists, weights, k);
+	}
+	/**
+	* Multi-query expansion (P2-3). Returns the original query followed by
+	* up to `multiQuery - 1` deduped reworded variants. A no-op (`[query]`)
+	* when `multiQuery` is unset / `<= 1` or no transformer is configured —
+	* so the default path makes no provider call. A transformer failure
+	* degrades to `[query]` rather than breaking recall.
+	*/
+	async #expandQueries(query, opts) {
+		const n = opts.multiQuery;
+		if (n === void 0 || n <= 1 || this.#queryTransformer === null) return [query];
+		try {
+			const variants = await this.#queryTransformer.expand(query, n - 1, { ...opts.signal !== void 0 ? { signal: opts.signal } : {} });
+			const seen = new Set([query.trim().toLowerCase()]);
+			const out = [query];
+			for (const variant of variants) {
+				const trimmed = variant.trim();
+				const key = trimmed.toLowerCase();
+				if (trimmed.length === 0 || seen.has(key)) continue;
+				seen.add(key);
+				out.push(trimmed);
+				if (out.length >= n) break;
+			}
+			return out;
+		} catch {
+			return [query];
+		}
+	}
+	/**
+	* HyDE retrieval (P2-3). Generates a hypothetical answer, embeds it,
+	* and returns its vector neighbours to fuse into the result. A no-op
+	* (`[]`) unless `hyde` is set, a transformer is configured, **and** an
+	* embedder + vector surface exist — the embedder guard is checked
+	* *first* so a missing embedder skips the LLM call entirely rather than
+	* generating a passage that can never be embedded.
+	*/
+	async #tryHyde(scope, query, opts, topK) {
+		if (opts.hyde !== true || this.#queryTransformer === null) return [];
+		if (this.#embedder === null || this.#embedderIdProvider() === null || typeof this.#store.semantic.searchVector !== "function") return [];
+		try {
+			const pseudo = await this.#queryTransformer.hypothetical(query, { ...opts.signal !== void 0 ? { signal: opts.signal } : {} });
+			if (pseudo === null || pseudo.trim().length === 0) return [];
+			return this.#tryVectorSearch(scope, pseudo, topK, opts.asOf, opts.includeQuarantined);
+		} catch {
+			return [];
+		}
+	}
+	/**
+	* One-hop graph expansion (P2-1). Seeds on the unique fact ids already
+	* gathered into `lists` and fuses in facts sharing a canonical entity,
+	* via the adapter's recursive-CTE `graph.expandOneHop`. A no-op (`[]`)
+	* unless `expandHops >= 1` and the adapter exposes `graph` — and
+	* resilient: a traversal error degrades to no expansion rather than
+	* breaking recall. Neighbours carry a `graph` signal so explanations
+	* (X-3) can attribute a hit to the hop.
+	*/
+	async #tryExpandHops(scope, lists, opts, limit) {
+		const hops = opts.expandHops ?? 0;
+		const graphStore = this.#store.graph;
+		if (hops < 1 || graphStore === void 0 || typeof graphStore.expandOneHop !== "function") return [];
+		const seedIds = [];
+		const seen = /* @__PURE__ */ new Set();
+		for (const list of lists) for (const hit of list) if (!seen.has(hit.record.id)) {
+			seen.add(hit.record.id);
+			seedIds.push(hit.record.id);
+		}
+		if (seedIds.length === 0) return [];
+		try {
+			return (await graphStore.expandOneHop(scope, seedIds, {
+				maxHops: hops,
+				limit,
+				...opts.includeQuarantined === true ? { includeQuarantined: true } : {},
+				...opts.asOf !== void 0 ? { asOf: opts.asOf } : {}
+			})).map((fact) => ({
+				record: fact,
+				score: 1,
+				signals: Object.freeze({ graph: 1 })
+			}));
+		} catch {
+			return [];
+		}
+	}
+	async #tryVectorSearch(scope, query, topK, asOf, includeQuarantined) {
+		const embedderId = this.#embedderIdProvider();
+		if (this.#embedder === null || embedderId === null || typeof this.#store.semantic.searchVector !== "function") return [];
+		const [vector] = await this.#embedder.embed([query], { taskType: "query" });
+		if (vector === void 0) return [];
+		return this.#store.semantic.searchVector(scope, vector, embedderId, topK, asOf, includeQuarantined);
+	}
+	async #applyDecay(scope, hits, decay) {
+		if (decay === void 0 || hits.length === 0) return hits;
+		const semantic = this.#store.semantic;
+		let rows;
+		if (typeof semantic.listDecaySignals === "function") rows = await semantic.listDecaySignals(hits.map((h) => h.record.id));
+		else if (typeof semantic.listForDecay === "function") rows = await semantic.listForDecay(scope, 1e3);
+		else return hits;
+		if (rows.length === 0) return hits;
+		const signals = new Map(rows.map((row) => [row.id, {
+			strength: row.strength,
+			lastAccessedAt: row.lastAccessedAt,
+			createdAt: row.createdAt
+		}]));
+		const now = (decay.now ?? Date.now)();
+		const tauMs = Math.max(1, decay.tauDays) * 24 * 60 * 60 * 1e3;
+		const sorted = [...hits.map((hit) => {
+			const sig = signals.get(hit.record.id);
+			if (sig === void 0) return hit;
+			const reference = sig.lastAccessedAt ?? sig.createdAt;
+			const elapsed = Math.max(0, now - reference);
+			const retention = Math.exp(-elapsed / (tauMs * Math.max(.5, sig.strength)));
+			return {
+				...hit,
+				score: hit.score * retention,
+				signals: Object.freeze({
+					...hit.signals ?? {},
+					decay: retention
+				})
+			};
+		})].sort((a, b) => b.score - a.score);
+		return Object.freeze(sorted);
+	}
+};
+
+//#endregion
+export { SemanticMemory };
+//# sourceMappingURL=semantic-memory.js.map