@graphorin/memory 0.6.0 → 0.7.0

package/dist/tiers/semantic-memory.js

@@ -1,12 +1,12 @@
 import { withMemorySpan } from "../internal/spans.js";
 import { DEFAULT_SALIENCE_WEIGHTS } from "../consolidator/decay.js";
 import { QuarantinePromotionRefusedError } from "../errors/index.js";
+import { detectMemoryInjection } from "../internal/injection-heuristics.js";
 import { contextualize } from "../internal/contextualize.js";
 import { newMemoryId } from "../internal/id.js";
 import { normalizeEntityName } from "../graph/entity-resolver.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 { pprActivation } from "../search/graph-ppr.js";
 import { trustDiscount } from "../search/trust.js";
@@ -37,8 +37,10 @@ var SemanticMemory = class {
 	#entityResolver;
 	#grader;
 	#iterativeMaxIterations;
+	#iterativeDifficultyThreshold;
 	#reranker;
 	#trustWeights;
+	#searchDefaults;
 	constructor(args) {
 		this.#store = args.store;
 		this.#tracer = args.tracer;
@@ -51,7 +53,9 @@ var SemanticMemory = class {
 		this.#entityResolver = args.entityResolver ?? null;
 		this.#grader = args.grader ?? null;
 		this.#iterativeMaxIterations = args.iterativeMaxIterations ?? DEFAULT_MAX_ITERATIONS;
+		this.#iterativeDifficultyThreshold = args.iterativeDifficultyThreshold;
 		this.#trustWeights = args.trustWeights ?? DEFAULT_SALIENCE_WEIGHTS;
+		this.#searchDefaults = args.searchDefaults ?? {};
 	}
 	/** Replace the active reranker. Returns the previous instance. */
 	setReranker(reranker) {
@@ -230,7 +234,11 @@ var SemanticMemory = class {
 		} catch {}
 	}
 	/** Hybrid (vector + FTS5) search merged through the configured reranker. */
-	async search(scope, query, opts = {}) {
+	async search(scope, query, callOpts = {}) {
+		const opts = {
+			...this.#searchDefaults,
+			...callOpts
+		};
 		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;
@@ -240,6 +248,8 @@ var SemanticMemory = class {
 			const wGraph = weighted?.weights.graph ?? 1;
 			const wEntity = weighted?.weights.entity ?? 1;
 			const queries = await this.#expandQueries(query, opts);
+			const variantVectors = await this.#tryBatchEmbedQueries(queries);
+			const hydeHitsPromise = this.#tryHyde(scope, query, opts, candidateTopK);
 			const lists = [];
 			const listWeights = [];
 			const listLabels = [];
@@ -260,7 +270,8 @@ var SemanticMemory = class {
 				lists.push(ftsHits);
 				listWeights.push(wFts);
 				listLabels.push(`fts_${queries.indexOf(q)}`);
-				const vectorHits = await this.#tryVectorSearch(scope, q, candidateTopK, opts.asOf, opts.includeQuarantined, opts.includeSuperseded, opts.owner);
+				const preVector = variantVectors?.get(q);
+				const vectorHits = preVector !== void 0 ? await this.#vectorSearchWithVector(scope, preVector, candidateTopK, opts.asOf, opts.includeQuarantined, opts.includeSuperseded, opts.owner) : await this.#tryVectorSearch(scope, q, candidateTopK, opts.asOf, opts.includeQuarantined, opts.includeSuperseded, opts.owner);
 				if (vectorHits.length > 0) {
 					lists.push(vectorHits);
 					listWeights.push(wVector);
@@ -272,7 +283,7 @@ var SemanticMemory = class {
 					isPrimary = false;
 				}
 			}
-			const hydeHits = await this.#tryHyde(scope, query, opts, candidateTopK);
+			const hydeHits = await hydeHitsPromise;
 			if (hydeHits.length > 0) {
 				lists.push(hydeHits);
 				listWeights.push(wVector);
@@ -294,7 +305,7 @@ var SemanticMemory = class {
 				weights: listWeights,
 				...weighted.k !== void 0 ? { k: weighted.k } : {}
 			}) : this.#reranker;
-			const fusedTopK = opts.decay !== void 0 || (opts.tags?.length ?? 0) > 0 || opts.owner !== void 0 || (opts.expandHops ?? 0) > 0 || opts.entityMatch === true ? Math.max(finalTopK, lists.reduce((n, l) => n + l.length, 0)) : finalTopK;
+			const fusedTopK = opts.decay !== void 0 || (opts.tags?.length ?? 0) > 0 || opts.owner !== void 0 || (opts.expandHops ?? 0) > 0 || opts.entityMatch === true || opts.trustWeighting !== "off" || opts.includeQuarantined === true ? Math.max(finalTopK, lists.reduce((n, l) => n + l.length, 0)) : finalTopK;
 			const fused = await reranker.rerank(query, lists, {
 				topK: fusedTopK,
 				labels: listLabels,
@@ -310,7 +321,7 @@ var SemanticMemory = class {
 			const ownerFiltered = wantedOwners !== null ? filtered.filter((h) => wantedOwners.includes(h.record.owner ?? "user")) : filtered;
 			const ranked = (opts.trustWeighting === "off" ? ownerFiltered : this.#applyTrustDiscount(ownerFiltered)).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));
+				await this.#store.semantic.markAccessed(ranked.map((h) => h.record.id), void 0, scope);
 			} catch {}
 			const explanation = explainRecall(ranked, {
 				query,
@@ -364,12 +375,16 @@ var SemanticMemory = class {
 				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 } : {}
-			});
+			}, (() => {
+				const difficultyThreshold = opts.difficultyThreshold ?? this.#iterativeDifficultyThreshold;
+				return {
+					maxIterations: opts.maxIterations ?? this.#iterativeMaxIterations,
+					maxResults: opts.topK ?? 10,
+					...opts.forceHard !== void 0 ? { forceHard: opts.forceHard } : {},
+					...opts.signal !== void 0 ? { signal: opts.signal } : {},
+					...difficultyThreshold !== void 0 ? { difficulty: { threshold: difficultyThreshold } } : {}
+				};
+			})());
 			span.setAttributes({
 				"memory.search.semantic.iterative.gate_hard": result.gateHard,
 				"memory.search.semantic.iterative.iterations": result.iterations,
@@ -465,16 +480,51 @@ var SemanticMemory = class {
 				}
 			}
 			span.setAttributes({ "memory.semantic.validate.forced": force });
-			await this.#store.semantic.setStatus(factId, "active", reason);
+			await this.#store.semantic.setStatus(factId, "active", reason, scope);
+			if (existing !== null && existing.supersedes !== void 0) {
+				const oldFact = await this.#fetchExisting(existing.supersedes);
+				if (oldFact !== null && oldFact.supersededBy === void 0 && oldFact.validTo === void 0) {
+					span.setAttributes({ "memory.semantic.validate.completed_supersede": true });
+					await this.#store.semantic.supersede(existing.supersedes, {
+						...existing,
+						status: "active"
+					}, reason ?? "validated-supersede");
+				}
+			}
 		});
 	}
-	/** 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 () => {
+	/**
+	* Mark `oldId` superseded by a new fact. Returns the new record.
+	*
+	* W-019 (security-first, knowledge-preserving): when the successor
+	* lands QUARANTINED (the default for `extraction`/synthesized
+	* provenance), the old ACTIVE fact's validity interval is NOT closed
+	* - default recall keeps returning the old knowledge until the
+	* successor passes {@link validate}, which completes the closure.
+	* The link is recorded on the successor's `supersedes` field. With
+	* `autoPromoteSynthesized` (threaded from the consolidator's
+	* `autoPromoteExtraction` escape hatch) an injection-clean successor
+	* is active immediately and the interval closes right away - the
+	* pre-W-019 behaviour. Inverting the default (auto-activating the
+	* successor) would hand a MINJA attacker instant active memory via
+	* any text the reconciler classifies as an 'update'.
+	*/
+	async supersede(scope, oldId, newInput, reason, options) {
+		return withMemorySpan(this.#tracer, "memory.write.semantic", scope, { "memory.semantic.action": "supersede" }, async (span) => {
 			const newFact = await this.remember(scope, {
 				...newInput,
 				supersedes: oldId
-			}, { pipeline: "off" });
+			}, {
+				pipeline: "off",
+				...options?.autoPromoteSynthesized === true ? { autoPromoteSynthesized: true } : {}
+			});
+			if (newFact.status === "quarantined") {
+				span.setAttributes({ "memory.semantic.supersede.pending": true });
+				return {
+					old: oldId,
+					new: newFact
+				};
+			}
 			await this.#store.semantic.supersede(oldId, newFact, reason);
 			return {
 				old: oldId,
@@ -488,7 +538,7 @@ var SemanticMemory = class {
 			"memory.semantic.action": "forget",
 			"memory.semantic.fact_id": factId
 		}, async () => {
-			await this.#store.semantic.forget(factId, reason);
+			await this.#store.semantic.forget(factId, reason, scope);
 		});
 	}
 	/**
@@ -504,7 +554,7 @@ var SemanticMemory = class {
 			"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);
+			await this.#store.semantic.purge(factId, reason, scope);
 		});
 	}
 	/** Fuse multiple ranked lists outside of a `search()` call. */
@@ -565,7 +615,7 @@ var SemanticMemory = class {
 		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);
+			return this.#tryVectorSearch(scope, pseudo, topK, opts.asOf, opts.includeQuarantined, opts.includeSuperseded, opts.owner);
 		} catch {
 			return [];
 		}
@@ -661,9 +711,42 @@ var SemanticMemory = class {
 		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.#vectorSearchWithVector(scope, vector, topK, asOf, includeQuarantined, includeSuperseded, owner);
+	}
+	/**
+	* W-087: the store half of {@link SemanticMemory.#tryVectorSearch} -
+	* runs the KNN read against an ALREADY-COMPUTED query vector so the
+	* multi-query fan-out can batch its N variant embeddings into one
+	* `embed([q1..qN])` call instead of N provider round-trips.
+	*/
+	async #vectorSearchWithVector(scope, vector, topK, asOf, includeQuarantined, includeSuperseded, owner) {
+		const embedderId = this.#embedderIdProvider();
+		if (embedderId === null || typeof this.#store.semantic.searchVector !== "function") return [];
 		return this.#store.semantic.searchVector(scope, vector, embedderId, topK, asOf, includeQuarantined, includeSuperseded, owner);
 	}
 	/**
+	* W-087: embed every fan-out variant in ONE embedder call. Returns
+	* `null` - and the caller degrades to the per-variant path - when
+	* there is no fan-out, no vector surface, or the batch call fails; a
+	* batching failure must never fail the search.
+	*/
+	async #tryBatchEmbedQueries(queries) {
+		if (queries.length <= 1) return null;
+		if (this.#embedder === null || this.#embedderIdProvider() === null || typeof this.#store.semantic.searchVector !== "function") return null;
+		try {
+			const vectors = await this.#embedder.embed([...queries], { taskType: "query" });
+			if (vectors.length !== queries.length) return null;
+			const byQuery = /* @__PURE__ */ new Map();
+			queries.forEach((q, i) => {
+				const v = vectors[i];
+				if (v !== void 0) byQuery.set(q, v);
+			});
+			return byQuery;
+		} catch {
+			return null;
+		}
+	}
+	/**
 	* C5: multiply each hit's fused score by its trust factor and re-sort.
 	* No-ops (returns the same array) when every factor is 1.
 	*/