@graphorin/memory 0.5.0 → 0.6.0

package/dist/tiers/semantic-memory.js

@@ -1,16 +1,20 @@
 import { withMemorySpan } from "../internal/spans.js";
+import { DEFAULT_SALIENCE_WEIGHTS } from "../consolidator/decay.js";
 import { QuarantinePromotionRefusedError } from "../errors/index.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";
 import { md5 } from "@graphorin/core";
 
 //#region src/tiers/semantic-memory.ts
 /**
-* `SemanticMemory` — long-term factual store. Hybrid (vector + FTS5)
+* `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`).
 *
@@ -34,6 +38,7 @@ var SemanticMemory = class {
 	#grader;
 	#iterativeMaxIterations;
 	#reranker;
+	#trustWeights;
 	constructor(args) {
 		this.#store = args.store;
 		this.#tracer = args.tracer;
@@ -46,6 +51,7 @@ var SemanticMemory = class {
 		this.#entityResolver = args.entityResolver ?? null;
 		this.#grader = args.grader ?? null;
 		this.#iterativeMaxIterations = args.iterativeMaxIterations ?? DEFAULT_MAX_ITERATIONS;
+		this.#trustWeights = args.trustWeights ?? DEFAULT_SALIENCE_WEIGHTS;
 	}
 	/** Replace the active reranker. Returns the previous instance. */
 	setReranker(reranker) {
@@ -104,6 +110,7 @@ var SemanticMemory = class {
 				...input.supersedes !== void 0 ? { supersedes: input.supersedes } : {},
 				...provenance !== void 0 ? { provenance } : {},
 				status,
+				...input.owner !== void 0 ? { owner: input.owner } : {},
 				createdAt: now,
 				updatedAt: now
 			};
@@ -212,7 +219,7 @@ var SemanticMemory = class {
 	* 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
+	* resilient - a resolution failure never breaks the write that just
 	* committed.
 	*/
 	async #linkEntities(scope, fact, signal) {
@@ -230,6 +237,8 @@ var SemanticMemory = class {
 			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 wGraph = weighted?.weights.graph ?? 1;
+			const wEntity = weighted?.weights.entity ?? 1;
 			const queries = await this.#expandQueries(query, opts);
 			const lists = [];
 			const listWeights = [];
@@ -244,12 +253,14 @@ var SemanticMemory = class {
 					...opts.asOf !== void 0 ? { asOf: opts.asOf } : {},
 					...opts.tags !== void 0 && opts.tags.length > 0 ? { tags: opts.tags } : {},
 					...opts.includeQuarantined === true ? { includeQuarantined: true } : {},
+					...opts.includeSuperseded === true ? { includeSuperseded: true } : {},
+					...opts.owner !== void 0 ? { owner: opts.owner } : {},
 					...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);
+				const vectorHits = await this.#tryVectorSearch(scope, q, candidateTopK, opts.asOf, opts.includeQuarantined, opts.includeSuperseded, opts.owner);
 				if (vectorHits.length > 0) {
 					lists.push(vectorHits);
 					listWeights.push(wVector);
@@ -270,25 +281,34 @@ var SemanticMemory = class {
 			const graphHits = await this.#tryExpandHops(scope, lists, opts, candidateTopK);
 			if (graphHits.length > 0) {
 				lists.push(graphHits);
-				listWeights.push(1);
+				listWeights.push(wGraph);
 				listLabels.push("graph");
 			}
+			const entityHits = await this.#tryEntityMatch(scope, query, opts, candidateTopK);
+			if (entityHits.length > 0) {
+				lists.push(entityHits);
+				listWeights.push(wEntity);
+				listLabels.push("entity");
+			}
 			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 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 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 filtered = 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);
+			}) : decayed;
+			const wantedOwners = opts.owner === void 0 ? null : typeof opts.owner === "string" ? [opts.owner] : opts.owner;
+			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));
 			} catch {}
@@ -321,8 +341,8 @@ var SemanticMemory = class {
 	* 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`
+	* 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.
@@ -368,7 +388,7 @@ var SemanticMemory = class {
 	* 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
+	* configured - the consolidator then treats every candidate as a
 	* fresh `add`, degrading gracefully to the pre-reconcile behaviour.
 	*
 	* @stable
@@ -390,7 +410,7 @@ var SemanticMemory = class {
 	* 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
+	* `SemanticMemoryStoreExt.historyOf(...)` - the default
 	* `@graphorin/store-sqlite` adapter wires this through. P0-2.
 	*
 	* @stable
@@ -411,12 +431,12 @@ var SemanticMemory = class {
 	* 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
+	* 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
+	* {@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
@@ -475,7 +495,7 @@ var SemanticMemory = class {
 	* 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
+	* `SemanticMemoryStoreExt.purge(...)` - the default
 	* `@graphorin/store-sqlite` adapter wires this through.
 	*/
 	async purge(scope, factId, reason) {
@@ -491,12 +511,12 @@ var SemanticMemory = class {
 	async fuse(query, lists, options = {}) {
 		return this.#reranker.rerank(query, lists, options);
 	}
-	/** Pure-fusion helper — exposed for callers that already collected results. */
+	/** 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}
+	* 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.
@@ -507,7 +527,7 @@ var SemanticMemory = class {
 	/**
 	* 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 —
+	* 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.
 	*/
@@ -535,7 +555,7 @@ var SemanticMemory = class {
 	* 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
+	* 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.
 	*/
@@ -554,7 +574,7 @@ var SemanticMemory = class {
 	* 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
+	* 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.
@@ -570,13 +590,24 @@ var SemanticMemory = class {
 			seedIds.push(hit.record.id);
 		}
 		if (seedIds.length === 0) return [];
+		const expandOpts = {
+			maxHops: hops,
+			limit,
+			...opts.includeQuarantined === true ? { includeQuarantined: true } : {},
+			...opts.includeSuperseded === true ? { includeSuperseded: true } : {},
+			...opts.asOf !== void 0 ? { asOf: opts.asOf } : {}
+		};
 		try {
-			return (await graphStore.expandOneHop(scope, seedIds, {
-				maxHops: hops,
-				limit,
-				...opts.includeQuarantined === true ? { includeQuarantined: true } : {},
-				...opts.asOf !== void 0 ? { asOf: opts.asOf } : {}
-			})).map((fact) => ({
+			if (opts.graphScoring === "ppr" && typeof graphStore.expandActivation === "function") {
+				const graded = await graphStore.expandActivation(scope, seedIds, expandOpts);
+				const scores = pprActivation(graded);
+				return graded.map((entry, i) => ({
+					record: entry.fact,
+					score: scores[i] ?? 0,
+					signals: Object.freeze({ graph: scores[i] ?? 0 })
+				}));
+			}
+			return (await graphStore.expandOneHop(scope, seedIds, expandOpts)).map((fact) => ({
 				record: fact,
 				score: 1,
 				signals: Object.freeze({ graph: 1 })
@@ -585,12 +616,74 @@ var SemanticMemory = class {
 			return [];
 		}
 	}
-	async #tryVectorSearch(scope, query, topK, asOf, includeQuarantined) {
+	/**
+	* D5 exact entity-match leg. Normalizes the query into candidate
+	* entity names and fetches facts linked to a matching canonical
+	* entity. A no-op without `entityMatch`, a graph adapter, or the
+	* `factsForEntityName` store method.
+	*/
+	async #tryEntityMatch(scope, query, opts, limit) {
+		if (opts.entityMatch !== true) return [];
+		const graphStore = this.#store.graph;
+		if (graphStore === void 0 || typeof graphStore.factsForEntityName !== "function") return [];
+		const normalized = normalizeEntityName(query);
+		if (normalized.length === 0) return [];
+		const candidates = new Set([normalized]);
+		const words = normalized.split(" ").filter((w) => w.length > 2);
+		for (const w of words) candidates.add(w);
+		const out = [];
+		const seen = /* @__PURE__ */ new Set();
+		try {
+			for (const name of candidates) {
+				const facts = await graphStore.factsForEntityName(scope, name, {
+					limit,
+					...opts.includeQuarantined === true ? { includeQuarantined: true } : {},
+					...opts.includeSuperseded === true ? { includeSuperseded: true } : {},
+					...opts.asOf !== void 0 ? { asOf: opts.asOf } : {}
+				});
+				for (const fact of facts) {
+					if (seen.has(fact.id)) continue;
+					seen.add(fact.id);
+					out.push({
+						record: fact,
+						score: 1,
+						signals: Object.freeze({ entity: 1 })
+					});
+				}
+			}
+		} catch {
+			return [];
+		}
+		return out;
+	}
+	async #tryVectorSearch(scope, query, topK, asOf, includeQuarantined, includeSuperseded, owner) {
 		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);
+		return this.#store.semantic.searchVector(scope, vector, embedderId, topK, asOf, includeQuarantined, includeSuperseded, owner);
+	}
+	/**
+	* 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.
+	*/
+	#applyTrustDiscount(hits) {
+		let changed = false;
+		const discounted = hits.map((hit) => {
+			const factor = trustDiscount(hit.record, this.#trustWeights);
+			if (factor >= 1) return hit;
+			changed = true;
+			return {
+				record: hit.record,
+				score: hit.score * factor,
+				signals: Object.freeze({
+					...hit.signals ?? {},
+					trust: factor
+				})
+			};
+		});
+		if (!changed) return hits;
+		return [...discounted].sort((a, b) => b.score - a.score);
 	}
 	async #applyDecay(scope, hits, decay) {
 		if (decay === void 0 || hits.length === 0) return hits;