@oscharko-dev/keiko-memory-retrieval 0.2.0

package/dist/ranking.js

@@ -0,0 +1,266 @@
+// Ranking orchestration.
+//
+// Hybrid ranker over (relevance, recency, confidence, pinned, correction, graph). Two
+// passes:
+//   Pass 1 — baseline subscores per memory (graph contribution = 0). Sort. The top-N of
+//            this pass become the "high-rank set" for the graph pass; the graph signal
+//            cannot reference itself recursively because the high-rank set is fixed
+//            BEFORE the graph contribution is computed.
+//   Pass 2 — graph proximity is computed for each memory against the high-rank set, and
+//            the entry is rebuilt with the layered subscore. Re-sort and return.
+//
+// Tiebreak order: score desc, updatedAt desc, id asc. Stable across equal-score sets so
+// the same input always produces the same output (determinism is an explicit AC).
+//
+// Inclusion reason names the top contributing WEIGHTED subscore. The threshold for
+// "primarily because of X" is "X contributes more than any other dimension" — no
+// arbitrary cutoff — so the reason text always tracks the actual top contributor.
+import { graphProximityScore } from "./graph.js";
+import { recencyScore } from "./recency.js";
+import { lexicalRelevance } from "./relevance.js";
+const DEFAULT_GRAPH_HIGH_RANK_COUNT = 8;
+// Internal invariant guard. The subscore / rank maps below are built with exactly one entry per
+// memory in `memories`, so a lookup keyed by a memory from that same list is always present. This
+// makes the invariant explicit instead of asserting it away with `!` — a miss is a programmer error,
+// not a recoverable input, so it fails loud rather than silently scoring against a wrong value.
+function requireEntry(map, key) {
+    const value = map.get(key);
+    if (value === undefined) {
+        throw new Error("ranking invariant violated: missing map entry for a known memory");
+    }
+    return value;
+}
+// Frozen source-authority importance (#204, O-F5). A deterministic function of the immutable capture
+// provenance: a fact the user stated outright outranks one passively inferred by the system, at equal
+// relevance. Reproducible and caller-input-free.
+const SOURCE_IMPORTANCE = {
+    "explicit-user-instruction": 1,
+    "accepted-correction": 0.85,
+    "workflow-outcome": 0.6,
+    consolidation: 0.5,
+    "system-default": 0.4,
+};
+export function sourceImportance(record) {
+    // SOURCE_IMPORTANCE is total over MemorySourceKind, so a new source kind in contracts surfaces here
+    // as a compile error rather than silently defaulting.
+    return SOURCE_IMPORTANCE[record.provenance.sourceKind];
+}
+function baselineSubscores(record, query) {
+    return {
+        relevance: lexicalRelevance(query.queryText, record),
+        recency: recencyScore(record.updatedAt, query.nowMs),
+        confidence: record.provenance.confidence,
+        pinned: record.pinned ? 1 : 0,
+        correction: record.type === "correction" || record.provenance.sourceKind === "accepted-correction"
+            ? 1
+            : 0,
+        graph: 0,
+        semantic: query.semanticById?.get(record.id) ?? 0,
+        strength: query.strengthById?.get(record.id) ?? 0,
+        importance: sourceImportance(record),
+    };
+}
+function weightedScore(s, w) {
+    const raw = s.relevance * w.relevance +
+        s.recency * w.recency +
+        s.confidence * w.confidence +
+        s.pinned * w.pinned +
+        s.correction * w.correction +
+        s.graph * w.graph +
+        s.semantic * w.semantic +
+        s.strength * w.strength +
+        s.importance * w.importance;
+    const totalWeight = w.relevance +
+        w.recency +
+        w.confidence +
+        w.pinned +
+        w.correction +
+        w.graph +
+        w.semantic +
+        w.strength +
+        w.importance;
+    if (totalWeight <= 0)
+        return 0;
+    return raw / totalWeight;
+}
+function topContributor(s, w) {
+    const parts = [
+        { key: "pinned", value: s.pinned * w.pinned },
+        { key: "correction", value: s.correction * w.correction },
+        // Semantic before relevance/recency/confidence so the stronger embedding signal wins a tie
+        // against the lexical signals; pinned/correction stay above it as today.
+        { key: "semantic", value: s.semantic * w.semantic },
+        // Reinforcement sits just below semantic: a heavily-reused memory wins a tie against the lexical
+        // signals but not against an explicit pin, a fresh correction, or a strong embedding match.
+        { key: "strength", value: s.strength * w.strength },
+        { key: "relevance", value: s.relevance * w.relevance },
+        { key: "recency", value: s.recency * w.recency },
+        { key: "confidence", value: s.confidence * w.confidence },
+        { key: "importance", value: s.importance * w.importance },
+        { key: "graph", value: s.graph * w.graph },
+    ];
+    let bestKey = "recency";
+    let bestValue = -1;
+    for (const p of parts) {
+        if (p.value > bestValue) {
+            bestKey = p.key;
+            bestValue = p.value;
+        }
+    }
+    return inclusionReasonText(bestKey, bestValue);
+}
+function inclusionReasonText(key, value) {
+    if (value <= 0)
+        return "included by default ranking";
+    const label = {
+        relevance: "lexical relevance to query",
+        recency: "recent update",
+        confidence: "high provenance confidence",
+        pinned: "pinned memory",
+        correction: "recent correction overrides older facts",
+        graph: "graph proximity to other top memories",
+        semantic: "semantic similarity to query",
+        strength: "frequently recalled (reinforced)",
+        importance: "authoritative source",
+    };
+    return `top signal: ${label[key]}`;
+}
+function entryFor(record, subscores, weights) {
+    const score = weightedScore(subscores, weights);
+    return {
+        memoryId: record.id,
+        score,
+        subscores,
+        inclusionReason: topContributor(subscores, weights),
+    };
+}
+function compareEntries(aEntry, bEntry, aRecord, bRecord) {
+    if (aEntry.score !== bEntry.score)
+        return bEntry.score - aEntry.score;
+    if (aRecord.updatedAt !== bRecord.updatedAt)
+        return bRecord.updatedAt - aRecord.updatedAt;
+    if (aEntry.memoryId < bEntry.memoryId)
+        return -1;
+    if (aEntry.memoryId > bEntry.memoryId)
+        return 1;
+    return 0;
+}
+function sortByRank(entries, recordById) {
+    return [...entries].sort((a, b) => {
+        const aRecord = recordById.get(a.memoryId);
+        const bRecord = recordById.get(b.memoryId);
+        if (aRecord === undefined || bRecord === undefined)
+            return 0;
+        return compareEntries(a, b, aRecord, bRecord);
+    });
+}
+// Byte-identity guarantee (#204): when the caller supplied NO per-memory semantic scores, the
+// semantic weight is forced to 0 so it leaves the weighted sum AND its denominator untouched —
+// every score, reason, and ordering is identical to the pre-semantic lexical ranker. Only when
+// `semanticById` is present does the configured semantic weight participate.
+function effectiveWeights(query) {
+    // Each optional signal zeroes its own weight when the caller supplied no scores for it, so the
+    // weighted sum AND its denominator are untouched and the output is byte-identical to the behaviour
+    // before that signal existed. The two conditions are independent.
+    let weights = query.weights;
+    if (query.semanticById === undefined) {
+        weights = { ...weights, semantic: 0 };
+    }
+    if (query.strengthById === undefined) {
+        weights = { ...weights, strength: 0 };
+    }
+    return weights;
+}
+// Reciprocal Rank Fusion constant (Cormack et al. 2009). 60 is the field-standard k; larger flattens
+// the rank advantage, smaller sharpens it.
+export const RRF_K = 60;
+const SUBSCORE_KEYS = [
+    "relevance",
+    "recency",
+    "confidence",
+    "pinned",
+    "correction",
+    "graph",
+    "semantic",
+    "strength",
+    "importance",
+];
+// Final subscores per memory: baseline + (when edges are supplied) the graph layer. The graph
+// high-rank set is the WEIGHTED-SUM baseline top-N, so graph proximity is computed identically
+// regardless of the final fusion mode (and the weighted-sum path stays byte-identical to before).
+function computeFinalSubscores(memories, query, weights, options, recordById) {
+    const map = new Map();
+    for (const m of memories)
+        map.set(m.id, baselineSubscores(m, query));
+    if (options.edgesByMemory === undefined)
+        return map;
+    const baselineSorted = sortByRank(memories.map((m) => entryFor(m, requireEntry(map, m.id), weights)), recordById);
+    const highRankCount = options.graphHighRankCount ?? DEFAULT_GRAPH_HIGH_RANK_COUNT;
+    const highRankIds = new Set(baselineSorted.slice(0, highRankCount).map((e) => e.memoryId));
+    const edges = options.edgesByMemory;
+    for (const m of memories) {
+        const base = requireEntry(map, m.id);
+        map.set(m.id, { ...base, graph: graphProximityScore(m.id, edges, highRankIds) });
+    }
+    return map;
+}
+// Reciprocal Rank Fusion (#204, O-F2): for each positive-weight signal, rank the memories by that
+// subscore (desc, id tiebreak) and fuse score = Σ w/(RRF_K + rank). Rank-based, so heterogeneous
+// score scales (Jaccard ~[0,0.3] vs cosine [0,1]) need no normalization, and agreement across signals
+// compounds. The fused value is normalized to [0,1] (best possible = rank 1 in every signal) to
+// honour the documented score range; ordering uses the shared (score desc, updatedAt desc, id asc) sort.
+function rrfRank(memories, subscoresById, weights, recordById) {
+    const signals = SUBSCORE_KEYS.filter((k) => weights[k] > 0);
+    const firstSignal = signals[0];
+    if (firstSignal === undefined) {
+        return sortByRank(memories.map((m) => entryFor(m, requireEntry(subscoresById, m.id), weights)), recordById);
+    }
+    const rankBySignal = new Map();
+    for (const sig of signals) {
+        const ordered = [...memories].sort((a, b) => {
+            const av = requireEntry(subscoresById, a.id)[sig];
+            const bv = requireEntry(subscoresById, b.id)[sig];
+            if (av !== bv)
+                return bv - av;
+            return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
+        });
+        const ranks = new Map();
+        ordered.forEach((m, i) => ranks.set(m.id, i + 1));
+        rankBySignal.set(sig, ranks);
+    }
+    const maxFused = signals.reduce((sum, sig) => sum + weights[sig] / (RRF_K + 1), 0);
+    const entries = memories.map((m) => {
+        let fused = 0;
+        let bestSig = firstSignal;
+        let bestContrib = -1;
+        for (const sig of signals) {
+            const rank = requireEntry(requireEntry(rankBySignal, sig), m.id);
+            const contrib = weights[sig] / (RRF_K + rank);
+            fused += contrib;
+            if (contrib > bestContrib) {
+                bestContrib = contrib;
+                bestSig = sig;
+            }
+        }
+        return {
+            memoryId: m.id,
+            score: maxFused > 0 ? fused / maxFused : 0,
+            subscores: requireEntry(subscoresById, m.id),
+            inclusionReason: inclusionReasonText(bestSig, bestContrib),
+        };
+    });
+    return sortByRank(entries, recordById);
+}
+export function rankMemories(memories, query, options = {}) {
+    if (memories.length === 0)
+        return [];
+    const recordById = new Map();
+    for (const m of memories)
+        recordById.set(m.id, m);
+    const weights = effectiveWeights(query);
+    const subscoresById = computeFinalSubscores(memories, query, weights, options, recordById);
+    if (query.fusion === "rrf") {
+        return rrfRank(memories, subscoresById, weights, recordById);
+    }
+    return sortByRank(memories.map((m) => entryFor(m, requireEntry(subscoresById, m.id), weights)), recordById);
+}

package/dist/recency.d.ts

@@ -0,0 +1,3 @@
+export declare const RECENCY_HALF_LIFE_MS: number;
+export declare function recencyScore(updatedAt: number, nowMs: number): number;
+//# sourceMappingURL=recency.d.ts.map

package/dist/recency.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recency.d.ts","sourceRoot":"","sources":["../src/recency.ts"],"names":[],"mappings":"AAaA,eAAO,MAAM,oBAAoB,QAAiB,CAAC;AAEnD,wBAAgB,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAIrE"}

package/dist/recency.js

@@ -0,0 +1,17 @@
+// Recency-decay primitive. Exponential half-life model: a memory is worth 1.0 at
+// updatedAt = nowMs, 0.5 at one half-life of age, 0.25 at two half-lives, etc. Future-dated
+// records are clamped to 1.0 so a clock-skew or capture-source-ahead-of-orchestrator does
+// not produce a negative or super-unit score that would poison the weighted sum.
+//
+// Half-life is 7 days. This matches the conversational-memory expectation that "recent"
+// runs the previous week; consolidation (#208) will collapse older records into semantic
+// facts whose recency continues to refresh on every update. The constant is exported so
+// callers (e.g. an audit dashboard) can reproduce the score deterministically.
+import { exponentialDecay } from "./decay.js";
+const MS_PER_DAY = 86_400_000;
+export const RECENCY_HALF_LIFE_MS = 7 * MS_PER_DAY;
+export function recencyScore(updatedAt, nowMs) {
+    // Edit-recency: decays since the record was last UPDATED. (Reuse-recency, which decays since last
+    // ACCESS at a different half-life, lives in strength.ts — both share the kernel in decay.ts.)
+    return exponentialDecay(nowMs - updatedAt, RECENCY_HALF_LIFE_MS);
+}

package/dist/relevance.d.ts

@@ -0,0 +1,8 @@
+import type { MemoryRecord } from "@oscharko-dev/keiko-contracts/memory";
+export declare function tokenize(text: string): readonly string[];
+/**
+ * Jaccard similarity between the query token set and the record token set (body + tags).
+ * Returns 0 for empty/undefined queries; returns 1 when the two sets are equal.
+ */
+export declare function lexicalRelevance(queryText: string | undefined, record: MemoryRecord): number;
+//# sourceMappingURL=relevance.d.ts.map

package/dist/relevance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relevance.d.ts","sourceRoot":"","sources":["../src/relevance.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sCAAsC,CAAC;AAOzE,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAaxD;AAWD;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,EAAE,MAAM,EAAE,YAAY,GAAG,MAAM,CAc5F"}

package/dist/relevance.js

@@ -0,0 +1,60 @@
+// Lexical-relevance primitive. Deterministic Jaccard over (body + tags) tokens.
+// No IDF, no document-frequency state — keeps the function pure and the score reproducible
+// across runs without a corpus dependency. The brief explicitly permits "normalized token
+// Jaccard or simple BM25-lite without IDF — keep deterministic"; Jaccard is the simplest
+// fully-deterministic choice and the cheapest to reason about for explainability.
+// Word boundary uses a Unicode-aware non-word matcher: any character that is not a letter,
+// digit, or underscore (in any script) becomes a separator. This is a fixed-length pattern
+// with no alternation or backreferences — not ReDoS-prone.
+const NON_WORD = /[^\p{L}\p{N}_]+/u;
+export function tokenize(text) {
+    if (text === "")
+        return [];
+    const lowered = text.toLowerCase();
+    const split = lowered.split(NON_WORD);
+    const seen = new Set();
+    const out = [];
+    for (const piece of split) {
+        if (piece === "")
+            continue;
+        if (seen.has(piece))
+            continue;
+        seen.add(piece);
+        out.push(piece);
+    }
+    return out;
+}
+function recordTokens(record) {
+    const tokens = new Set();
+    for (const t of tokenize(record.body))
+        tokens.add(t);
+    for (const tag of record.tags) {
+        for (const t of tokenize(tag))
+            tokens.add(t);
+    }
+    return tokens;
+}
+/**
+ * Jaccard similarity between the query token set and the record token set (body + tags).
+ * Returns 0 for empty/undefined queries; returns 1 when the two sets are equal.
+ */
+export function lexicalRelevance(queryText, record) {
+    if (queryText === undefined || queryText === "")
+        return 0;
+    const queryTokens = new Set(tokenize(queryText));
+    if (queryTokens.size === 0)
+        return 0;
+    const docTokens = recordTokens(record);
+    if (docTokens.size === 0)
+        return 0;
+    let intersection = 0;
+    for (const t of queryTokens) {
+        if (docTokens.has(t))
+            intersection += 1;
+    }
+    // Union = |A| + |B| - |A ∩ B|
+    const union = queryTokens.size + docTokens.size - intersection;
+    if (union === 0)
+        return 0;
+    return intersection / union;
+}

package/dist/retrieve.d.ts

@@ -0,0 +1,3 @@
+import { type MemoryQueryPort, type MemoryRetrievalRequest, type MemoryRetrievalResult } from "./types.js";
+export declare function retrieveMemoryContext(request: MemoryRetrievalRequest, port: MemoryQueryPort): MemoryRetrievalResult;
+//# sourceMappingURL=retrieve.d.ts.map

package/dist/retrieve.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retrieve.d.ts","sourceRoot":"","sources":["../src/retrieve.ts"],"names":[],"mappings":"AAoCA,OAAO,EAOL,KAAK,eAAe,EACpB,KAAK,sBAAsB,EAC3B,KAAK,qBAAqB,EAG3B,MAAM,YAAY,CAAC;AA0PpB,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,sBAAsB,EAC/B,IAAI,EAAE,eAAe,GACpB,qBAAqB,CA0CvB"}

package/dist/retrieve.js

@@ -0,0 +1,256 @@
+// Top-level scoped-memory retrieval orchestrator.
+//
+// Cross-scope isolation is structural: the function ONLY iterates `request.scopes` when
+// calling port.listByScope. A caller cannot trick this layer into surfacing records from
+// a scope it did not authorise because no other code path reaches the port.
+//
+// Pipeline:
+//   1. Validate request (non-empty scopes, finite non-negative weights, finite integer
+//      budget/maxIncluded).
+//   2. For each scope in request.scopes -> port.listByScope(scope, {maxResults, include*}).
+//      Wrap any port throw as RetrievalError('port-failure', cause: original).
+//   3. Dedupe by memoryId (a record reachable from multiple scopes appears once).
+//   4. Apply suppression (status / validity / confidence) -> "suppressed-by-status".
+//      Apply type filter when request.types is set -> "type-filtered".
+//   5. Build an edges-by-memory map for the candidate set if the port exposes
+//      listOutgoingEdges/listIncomingEdges (bounded fetch — only candidates we still hold).
+//   6. Rank with the hybrid ranker; assemble with the token-budgeted greedy assembler.
+//   7. Attach request to the assembler's result and return.
+//
+// Determinism: every step is pure given the port's return values, so identical port
+// responses + identical request -> identical output. The cross-scope isolation test pins
+// this with a spy port that records every listByScope call.
+import { assembleContextBlock } from "./context.js";
+import { DEFAULT_MMR_LAMBDA, reorderByMmr } from "./diversity.js";
+import { RetrievalError } from "./errors.js";
+import { tokenize } from "./relevance.js";
+import { rankMemories } from "./ranking.js";
+import { isMemorySuppressed } from "./suppression.js";
+import { DEFAULT_BUDGET_TOKENS, DEFAULT_LIST_BY_SCOPE_MAX_RESULTS, DEFAULT_MAX_INCLUDED, DEFAULT_RANKING_WEIGHTS, DEFAULT_STALE_CONFIDENCE_THRESHOLD, } from "./types.js";
+function emptyResult(request, budgetTokens) {
+    return {
+        contextBlock: {
+            text: "",
+            memories: [],
+        },
+        included: [],
+        omitted: [],
+        budget: {
+            tokens: budgetTokens,
+            used: 0,
+        },
+        request,
+    };
+}
+function resolveWeights(request) {
+    return {
+        relevance: request.relevanceWeight ?? DEFAULT_RANKING_WEIGHTS.relevance,
+        recency: request.recencyWeight ?? DEFAULT_RANKING_WEIGHTS.recency,
+        confidence: request.confidenceWeight ?? DEFAULT_RANKING_WEIGHTS.confidence,
+        pinned: request.pinnedBoost ?? DEFAULT_RANKING_WEIGHTS.pinned,
+        correction: request.correctionBoost ?? DEFAULT_RANKING_WEIGHTS.correction,
+        graph: request.graphProximityBoost ?? DEFAULT_RANKING_WEIGHTS.graph,
+        semantic: request.semanticWeight ?? DEFAULT_RANKING_WEIGHTS.semantic,
+        strength: request.strengthWeight ?? DEFAULT_RANKING_WEIGHTS.strength,
+        importance: request.importanceWeight ?? DEFAULT_RANKING_WEIGHTS.importance,
+    };
+}
+function assertNonNegativeWeights(weights) {
+    for (const [name, value] of Object.entries(weights)) {
+        if (!Number.isFinite(value) || value < 0) {
+            throw new RetrievalError("invalid-weight", `weight ${name} must be a finite number >= 0 (got ${String(value)})`);
+        }
+    }
+}
+function assertNonNegativeBudget(budgetTokens, maxIncluded) {
+    if (!Number.isFinite(budgetTokens) || !Number.isInteger(budgetTokens) || budgetTokens < 0) {
+        throw new RetrievalError("invalid-budget", `budgetTokens must be a finite integer >= 0 (got ${String(budgetTokens)})`);
+    }
+    if (!Number.isFinite(maxIncluded) || !Number.isInteger(maxIncluded) || maxIncluded < 0) {
+        throw new RetrievalError("invalid-budget", `maxIncluded must be a finite integer >= 0 (got ${String(maxIncluded)})`);
+    }
+}
+function assertValidThreshold(staleConfidenceThreshold) {
+    if (Number.isFinite(staleConfidenceThreshold) &&
+        staleConfidenceThreshold >= 0 &&
+        staleConfidenceThreshold <= 1) {
+        return;
+    }
+    throw new RetrievalError("invalid-threshold", `staleConfidenceThreshold must be a finite number in [0, 1] (got ${String(staleConfidenceThreshold)})`);
+}
+function validateAndResolve(request) {
+    if (request.scopes.length === 0) {
+        throw new RetrievalError("empty-scopes", "request.scopes must contain at least one scope");
+    }
+    const budgetTokens = request.budgetTokens ?? DEFAULT_BUDGET_TOKENS;
+    const maxIncluded = request.maxIncluded ?? DEFAULT_MAX_INCLUDED;
+    assertNonNegativeBudget(budgetTokens, maxIncluded);
+    const weights = resolveWeights(request);
+    assertNonNegativeWeights(weights);
+    const staleConfidenceThreshold = request.staleConfidenceThreshold ?? DEFAULT_STALE_CONFIDENCE_THRESHOLD;
+    assertValidThreshold(staleConfidenceThreshold);
+    return {
+        budgetTokens,
+        maxIncluded,
+        weights,
+        staleConfidenceThreshold,
+    };
+}
+function fetchScoped(port, scopes) {
+    const all = [];
+    for (const scope of scopes) {
+        try {
+            const batch = port.listByScope(scope, {
+                includeForgotten: true,
+                includeArchived: true,
+                includeExpired: true,
+                maxResults: DEFAULT_LIST_BY_SCOPE_MAX_RESULTS,
+            });
+            for (const r of batch)
+                all.push(r);
+        }
+        catch (cause) {
+            throw new RetrievalError("port-failure", `listByScope threw for scope.kind=${scope.kind}`, {
+                cause,
+            });
+        }
+    }
+    return all;
+}
+function dedupeById(records) {
+    const seen = new Set();
+    const out = [];
+    for (const r of records) {
+        if (seen.has(r.id))
+            continue;
+        seen.add(r.id);
+        out.push(r);
+    }
+    return out;
+}
+function applyFilters(records, request, resolved) {
+    const typeFilter = request.types;
+    const candidates = [];
+    const omitted = [];
+    for (const r of records) {
+        if (typeFilter !== undefined && !typeFilter.includes(r.type)) {
+            omitted.push({ memoryId: r.id, reason: "type-filtered" });
+            continue;
+        }
+        if (r.status === "superseded" && request.includeSuperseded !== true) {
+            omitted.push({
+                memoryId: r.id,
+                reason: "suppressed-by-status",
+                suppressionDetail: "superseded",
+            });
+            continue;
+        }
+        const sup = isMemorySuppressed(r, request.nowMs, resolved.staleConfidenceThreshold);
+        if (sup.suppressed) {
+            // sup.reason is optional on SuppressionResult; under exactOptionalPropertyTypes we
+            // must conditionally add the field so we never write `suppressionDetail: undefined`.
+            omitted.push(sup.reason === undefined
+                ? { memoryId: r.id, reason: "suppressed-by-status" }
+                : { memoryId: r.id, reason: "suppressed-by-status", suppressionDetail: sup.reason });
+            continue;
+        }
+        candidates.push(r);
+    }
+    return { candidates, omitted };
+}
+function buildEdgesIndex(port, candidates) {
+    if (port.listOutgoingEdges === undefined && port.listIncomingEdges === undefined)
+        return undefined;
+    const map = new Map();
+    for (const c of candidates) {
+        try {
+            // Call through the port object directly so `this` binds correctly on a class-based
+            // port implementation (avoids the @typescript-eslint/unbound-method trap).
+            const edges = dedupeEdges([
+                ...(port.listOutgoingEdges?.(c.id) ?? []),
+                ...(port.listIncomingEdges?.(c.id) ?? []),
+            ]);
+            if (edges.length > 0)
+                map.set(c.id, edges);
+        }
+        catch (cause) {
+            throw new RetrievalError("port-failure", `listEdges threw for ${c.id}`, { cause });
+        }
+    }
+    return map;
+}
+function dedupeEdges(edges) {
+    const seen = new Set();
+    const out = [];
+    for (const edge of edges) {
+        if (seen.has(edge.id))
+            continue;
+        seen.add(edge.id);
+        out.push(edge);
+    }
+    return out;
+}
+function hasPositiveSemanticSignal(semanticById) {
+    if (semanticById === undefined)
+        return false;
+    for (const score of semanticById.values()) {
+        if (score > 0)
+            return true;
+    }
+    return false;
+}
+function hasQuerySignal(request) {
+    const lexicalSignal = request.queryText !== undefined && tokenize(request.queryText).length > 0;
+    return lexicalSignal || hasPositiveSemanticSignal(request.semanticById);
+}
+function applyRelevanceFloor(ranked, request) {
+    if (!hasQuerySignal(request)) {
+        return { ranked, omitted: [] };
+    }
+    const kept = [];
+    const omitted = [];
+    for (const entry of ranked) {
+        if (entry.subscores.relevance === 0 &&
+            entry.subscores.semantic === 0 &&
+            entry.subscores.graph === 0) {
+            omitted.push({ memoryId: entry.memoryId, reason: "below-threshold" });
+            continue;
+        }
+        kept.push(entry);
+    }
+    return { ranked: kept, omitted };
+}
+export function retrieveMemoryContext(request, port) {
+    const resolved = validateAndResolve(request);
+    if (resolved.maxIncluded === 0 || resolved.budgetTokens === 0) {
+        return emptyResult(request, resolved.budgetTokens);
+    }
+    const fetched = fetchScoped(port, request.scopes);
+    const deduped = dedupeById(fetched);
+    const filtered = applyFilters(deduped, request, resolved);
+    const edgesByMemory = buildEdgesIndex(port, filtered.candidates);
+    const rankQuery = {
+        nowMs: request.nowMs,
+        weights: resolved.weights,
+        ...(request.queryText === undefined ? {} : { queryText: request.queryText }),
+        ...(request.semanticById === undefined ? {} : { semanticById: request.semanticById }),
+        ...(request.strengthById === undefined ? {} : { strengthById: request.strengthById }),
+        ...(request.fusion === undefined ? {} : { fusion: request.fusion }),
+    };
+    const ranked = rankMemories(filtered.candidates, rankQuery, edgesByMemory === undefined ? {} : { edgesByMemory });
+    const thresholded = applyRelevanceFloor(ranked, request);
+    // MMR diversity (#204, O-F3): re-order the ranked candidates so near-duplicates do not all consume
+    // the token budget. Inert (byte-identical greedy-by-rank) when the caller supplies no embeddings.
+    const selectionOrder = request.embeddingById === undefined
+        ? thresholded.ranked
+        : reorderByMmr(thresholded.ranked, request.embeddingById, request.mmrLambda ?? DEFAULT_MMR_LAMBDA);
+    const assembled = assembleContextBlock(selectionOrder, filtered.candidates, {
+        budgetTokens: resolved.budgetTokens,
+        maxIncluded: resolved.maxIncluded,
+    });
+    return {
+        ...assembled,
+        omitted: [...filtered.omitted, ...thresholded.omitted, ...assembled.omitted],
+        request,
+    };
+}

package/dist/strength.d.ts

@@ -0,0 +1,9 @@
+export declare const STRENGTH_HALF_LIFE_MS: number;
+export declare const STRENGTH_FREQUENCY_SATURATION = 8;
+export interface MemoryAccessStat {
+    readonly accessCount: number;
+    readonly lastAccessedAt: number;
+}
+export declare function reinforcementStrength(stat: MemoryAccessStat | undefined, nowMs: number): number;
+export declare function buildStrengthById<K>(statsById: ReadonlyMap<K, MemoryAccessStat>, nowMs: number): ReadonlyMap<K, number>;
+//# sourceMappingURL=strength.d.ts.map

package/dist/strength.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"strength.d.ts","sourceRoot":"","sources":["../src/strength.ts"],"names":[],"mappings":"AAsBA,eAAO,MAAM,qBAAqB,QAAkB,CAAC;AAKrD,eAAO,MAAM,6BAA6B,IAAI,CAAC;AAI/C,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACjC;AAGD,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,gBAAgB,GAAG,SAAS,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAW/F;AAID,wBAAgB,iBAAiB,CAAC,CAAC,EACjC,SAAS,EAAE,WAAW,CAAC,CAAC,EAAE,gBAAgB,CAAC,EAC3C,KAAK,EAAE,MAAM,GACZ,WAAW,CAAC,CAAC,EAAE,MAAM,CAAC,CAOxB"}