@oscharko-dev/keiko-memory-retrieval 0.2.0

package/dist/strength.js

@@ -0,0 +1,51 @@
+// Reinforcement-strength primitive (#204 plasticity). Turns a memory's access history — how OFTEN
+// and how RECENTLY it has been recalled — into a [0,1] re-ranking signal so a frequently-reused
+// memory is surfaced ahead of a never-touched one. This realises the core plasticity promise ("a
+// memory gets stronger when reused") at retrieval time; the maintenance pass already strengthens on
+// a slower cadence, but ranking is where reuse must change what the user actually sees.
+//
+// Cognitive basis (ACT-R base-level activation, simplified): activation rises with practice
+// frequency and decays with disuse. Two bounded, deterministic factors, multiplied:
+//   accessRecency = exp(-ln2 * (now - lastAccessedAt) / HALF_LIFE)   disuse decay, 45-day half-life
+//   frequency     = 1 - exp(-accessCount / SATURATION)              saturating practice gain
+// A NEVER-accessed memory scores 0 (no reinforcement yet) so this subscore only ever ADDS signal for
+// genuine reuse and never perturbs a fresh memory's existing relevance/recency/confidence ranking.
+//
+// Pure: no clock (now is passed in), no IO, no randomness. Same inputs => same output, so the
+// retrieval layer stays replay-stable and the deterministic eval can pin it.
+import { exponentialDecay } from "./decay.js";
+const MS_PER_DAY = 86_400_000;
+// Disuse half-life. Matches the maintenance strength curve (keiko-memory-governance maintenance.ts)
+// so "recency of use" decays at one consistent rate across ranking and the decay/forget cycle.
+export const STRENGTH_HALF_LIFE_MS = 45 * MS_PER_DAY;
+// Access count at which the frequency factor reaches ~0.63 of its ceiling. Logarithmic-feeling
+// saturation: 1 recall ≈ 0.12, 8 ≈ 0.63, 24 ≈ 0.95 — heavy reuse keeps mattering with diminishing
+// returns, matching the practice-curve intuition without an unbounded count term.
+export const STRENGTH_FREQUENCY_SATURATION = 8;
+// Reinforcement strength in [0,1]. `undefined` stat (memory never accessed) => 0.
+export function reinforcementStrength(stat, nowMs) {
+    if (stat === undefined)
+        return 0;
+    // Reuse-recency: decays since last ACCESS (future-dated clamps to full recency). Shares the kernel
+    // in decay.ts with edit-recency (recency.ts), which decays since last UPDATE at a different half-life.
+    const accessRecency = exponentialDecay(nowMs - stat.lastAccessedAt, STRENGTH_HALF_LIFE_MS);
+    const count = stat.accessCount > 0 ? stat.accessCount : 0;
+    const frequency = 1 - Math.exp(-count / STRENGTH_FREQUENCY_SATURATION);
+    const strength = frequency * accessRecency;
+    if (strength < 0)
+        return 0;
+    if (strength > 1)
+        return 1;
+    return strength;
+}
+// Convenience: build the per-memory strength map the ranker consumes from a map of access stats.
+// Lives here (next to the formula) so callers cannot drift from the canonical computation.
+export function buildStrengthById(statsById, nowMs) {
+    const out = new Map();
+    for (const [id, stat] of statsById) {
+        const strength = reinforcementStrength(stat, nowMs);
+        if (strength > 0)
+            out.set(id, strength);
+    }
+    return out;
+}

package/dist/suppression.d.ts

@@ -0,0 +1,8 @@
+import type { MemoryRecord } from "@oscharko-dev/keiko-contracts/memory";
+export type SuppressionReason = "archived" | "forgotten" | "conflicted" | "expired" | "proposed" | "rejected" | "stale-low-confidence";
+export interface SuppressionResult {
+    readonly suppressed: boolean;
+    readonly reason?: SuppressionReason;
+}
+export declare function isMemorySuppressed(memory: MemoryRecord, nowMs: number, staleConfidenceThreshold: number): SuppressionResult;
+//# sourceMappingURL=suppression.d.ts.map

package/dist/suppression.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"suppression.d.ts","sourceRoot":"","sources":["../src/suppression.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAE,YAAY,EAAgB,MAAM,sCAAsC,CAAC;AAIvF,MAAM,MAAM,iBAAiB,GACzB,UAAU,GACV,WAAW,GACX,YAAY,GACZ,SAAS,GACT,UAAU,GACV,UAAU,GACV,sBAAsB,CAAC;AAE3B,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B,QAAQ,CAAC,MAAM,CAAC,EAAE,iBAAiB,CAAC;CACrC;AAuDD,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,YAAY,EACpB,KAAK,EAAE,MAAM,EACb,wBAAwB,EAAE,MAAM,GAC/B,iBAAiB,CASnB"}

package/dist/suppression.js

@@ -0,0 +1,82 @@
+// Retrieval-suppression predicate.
+//
+// MUST stay in sync with @oscharko-dev/keiko-memory-governance/src/suppression.ts.
+// Duplicated by design (per Issue #210 brief) so this package depends ONLY on
+// keiko-contracts and keiko-security — see ADR-0019 direction rule 3j. A future refactor
+// MAY extract a shared helper into a fourth "contracts-adjacent" package; until then a
+// drift between the two implementations is a correctness bug and any change here must be
+// mirrored there.
+//
+// The semantics map the discriminated MemoryStatus enum to a suppression reason and
+// additionally apply two derived rules:
+//   - validity.validUntil <= nowMs                              => "expired"
+//   - provenance.confidence <= staleConfidenceThreshold         => "stale-low-confidence"
+//
+// The threshold default of 0.3 matches consolidation (#208) and governance (#209) so the
+// three layers agree on what counts as low-confidence. The comparison is `<=` so a record
+// exactly at the threshold is suppressed.
+//
+// A future widening of MemoryStatus surfaces as an exhaustiveness compile error here
+// (the `never` branch in statusSuppression).
+import { RetrievalError } from "./errors.js";
+const NOT_SUPPRESSED = { suppressed: false };
+function isFiniteInRange(value, min, max) {
+    return Number.isFinite(value) && value >= min && value <= max;
+}
+function assertValidThreshold(staleConfidenceThreshold) {
+    if (isFiniteInRange(staleConfidenceThreshold, 0, 1))
+        return;
+    throw new RetrievalError("invalid-threshold", `staleConfidenceThreshold must be a finite number in [0, 1] (got ${String(staleConfidenceThreshold)})`);
+}
+function statusSuppression(status) {
+    switch (status) {
+        case "archived":
+            return { suppressed: true, reason: "archived" };
+        case "forgotten":
+            return { suppressed: true, reason: "forgotten" };
+        case "conflicted":
+            return { suppressed: true, reason: "conflicted" };
+        case "rejected":
+            return { suppressed: true, reason: "rejected" };
+        case "expired":
+            // Validity-based "expired" is checked separately so an explicit `expired` status
+            // carries the same surface reason whether the retrieval index pinned it via status
+            // or derived it from the validity window.
+            return { suppressed: true, reason: "expired" };
+        case "proposed":
+            return { suppressed: true, reason: "proposed" };
+        case "accepted":
+        case "superseded":
+            return null;
+        default: {
+            const _exhaustive = status;
+            void _exhaustive;
+            return null;
+        }
+    }
+}
+function validitySuppression(memory, nowMs) {
+    if (memory.validity.validUntil === undefined)
+        return null;
+    if (memory.validity.validUntil > nowMs)
+        return null;
+    return { suppressed: true, reason: "expired" };
+}
+function confidenceSuppression(memory, threshold) {
+    if (memory.provenance.confidence > threshold)
+        return null;
+    return { suppressed: true, reason: "stale-low-confidence" };
+}
+export function isMemorySuppressed(memory, nowMs, staleConfidenceThreshold) {
+    assertValidThreshold(staleConfidenceThreshold);
+    const byStatus = statusSuppression(memory.status);
+    if (byStatus !== null)
+        return byStatus;
+    const byValidity = validitySuppression(memory, nowMs);
+    if (byValidity !== null)
+        return byValidity;
+    const byConfidence = confidenceSuppression(memory, staleConfidenceThreshold);
+    if (byConfidence !== null)
+        return byConfidence;
+    return NOT_SUPPRESSED;
+}

package/dist/types.d.ts

@@ -0,0 +1,118 @@
+import type { MemoryEdge, MemoryId, MemoryRecord, MemoryScope, MemorySensitivity, MemorySourceKind, MemoryStatus, MemoryType } from "@oscharko-dev/keiko-contracts/memory";
+export interface MemoryQueryPort {
+    /** Fetch memories visible at the given scope. Cross-scope queries forbidden. */
+    listByScope(scope: MemoryScope, options?: ListByScopeOptions): readonly MemoryRecord[];
+    /** Fetch outgoing edges for graph-proximity scoring. */
+    listOutgoingEdges?(memoryId: MemoryId): readonly MemoryEdge[];
+    /** Fetch incoming edges. */
+    listIncomingEdges?(memoryId: MemoryId): readonly MemoryEdge[];
+}
+export interface ListByScopeOptions {
+    readonly includeForgotten?: boolean;
+    readonly includeArchived?: boolean;
+    readonly includeExpired?: boolean;
+    readonly maxResults?: number;
+}
+export interface RankingWeights {
+    readonly relevance: number;
+    readonly recency: number;
+    readonly confidence: number;
+    readonly pinned: number;
+    readonly correction: number;
+    readonly graph: number;
+    readonly semantic: number;
+    readonly strength: number;
+    readonly importance: number;
+}
+export declare const DEFAULT_RANKING_WEIGHTS: RankingWeights;
+export declare const DEFAULT_BUDGET_TOKENS = 1500;
+export declare const DEFAULT_MAX_INCLUDED = 12;
+export declare const DEFAULT_STALE_CONFIDENCE_THRESHOLD = 0.3;
+export declare const DEFAULT_LIST_BY_SCOPE_MAX_RESULTS = 500;
+export type RankingFusionMode = "weighted-sum" | "rrf";
+export interface MemoryRetrievalRequest {
+    readonly scopes: readonly MemoryScope[];
+    readonly queryText?: string;
+    readonly types?: readonly MemoryType[];
+    readonly nowMs: number;
+    readonly budgetTokens?: number;
+    readonly maxIncluded?: number;
+    readonly recencyWeight?: number;
+    readonly confidenceWeight?: number;
+    readonly pinnedBoost?: number;
+    readonly correctionBoost?: number;
+    readonly graphProximityBoost?: number;
+    readonly relevanceWeight?: number;
+    readonly semanticWeight?: number;
+    readonly staleConfidenceThreshold?: number;
+    /** Audit/debug opt-in. Active context retrieval suppresses superseded memories by default. */
+    readonly includeSuperseded?: boolean;
+    readonly semanticById?: ReadonlyMap<MemoryId, number>;
+    readonly strengthById?: ReadonlyMap<MemoryId, number>;
+    readonly strengthWeight?: number;
+    readonly importanceWeight?: number;
+    readonly embeddingById?: ReadonlyMap<MemoryId, Float32Array>;
+    readonly mmrLambda?: number;
+    readonly fusion?: RankingFusionMode;
+}
+export interface MemoryContextBlockEntry {
+    readonly memoryId: MemoryId;
+    readonly bodyExcerpt: string;
+    readonly inclusionReason: string;
+    readonly sourceKind: MemorySourceKind;
+    readonly captureRationale?: string | undefined;
+    readonly sensitivity: MemorySensitivity;
+    readonly confidence: number;
+    readonly status: MemoryStatus;
+    readonly capturedAt: number;
+}
+export interface MemoryContextBlock {
+    /** Compact text rendering for prompt assembly. */
+    readonly text: string;
+    /** Structured payload for UI/audit consumers. */
+    readonly memories: readonly MemoryContextBlockEntry[];
+}
+export interface IncludedSubscores {
+    readonly relevance: number;
+    readonly recency: number;
+    readonly confidence: number;
+    readonly pinned: number;
+    readonly correction: number;
+    readonly graph: number;
+    readonly semantic: number;
+    readonly strength: number;
+    readonly importance: number;
+}
+export interface IncludedMemory {
+    readonly memoryId: MemoryId;
+    readonly score: number;
+    readonly subscores: IncludedSubscores;
+    readonly inclusionReason: string;
+}
+export type OmittedReason = "suppressed-by-status" | "below-threshold" | "budget-exceeded" | "out-of-scope" | "type-filtered";
+export interface OmittedMemory {
+    readonly memoryId: MemoryId;
+    readonly reason: OmittedReason;
+    readonly suppressionDetail?: string;
+}
+export interface MemoryBudget {
+    readonly tokens: number;
+    readonly used: number;
+}
+export interface MemoryRetrievalResult {
+    readonly contextBlock: MemoryContextBlock;
+    readonly included: readonly IncludedMemory[];
+    readonly omitted: readonly OmittedMemory[];
+    readonly budget: MemoryBudget;
+    readonly request: MemoryRetrievalRequest;
+}
+/**
+ * Internal result type used by `assembleContextBlock`. Mirrors `MemoryRetrievalResult`
+ * minus the `request` field, which is attached by `retrieveMemoryContext` after assembly.
+ * The brief lists `assembleContextBlock(ranked, memories, options): MemoryRetrievalResult`
+ * but the assembler has no need for the request envelope to compose its output — keeping
+ * the function pure on its (ranked, memories, options) inputs is cleaner than threading
+ * the request through a layer that does not read it.
+ */
+export type AssembledContext = Omit<MemoryRetrievalResult, "request">;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,40 @@
+// Public type surface for the memory-retrieval layer (Epic #204 / Issue #210).
+//
+// Pure types + a handful of `Object.freeze`d default-weight tables. No IO, no clock, no
+// randomness. All durable timestamps are epoch milliseconds; the caller supplies `nowMs`.
+//
+// Cross-cutting invariants encoded structurally:
+//  1. MemoryQueryPort.listByScope is the SINGLE seam through which records enter this
+//     layer. There is no "list all" surface — the port is scope-addressed, so cross-scope
+//     leakage requires an explicit second call to a second scope. The orchestrator
+//     (retrieve.ts) is the one place that decides which scopes to ask for, and it ONLY
+//     iterates `request.scopes`.
+//  2. ListByScopeOptions.maxResults bounds the upstream fetch so a misbehaving port can
+//     never flood this layer; the orchestrator passes its own bound regardless of caller.
+//  3. Every IncludedMemory carries the full subscore breakdown so audit and UI can
+//     reconstruct WHY a memory was chosen without re-running the ranker.
+//  4. Every OmittedMemory carries one of a closed-set of reasons so audit dashboards can
+//     bucket suppressions without parsing free-form strings.
+// Defaults are documented at the request-type boundary; this table is the single source of
+// truth the orchestrator reads when a field is `undefined` on the request. Frozen so a
+// downstream consumer cannot mutate the global default.
+export const DEFAULT_RANKING_WEIGHTS = Object.freeze({
+    relevance: 0.2,
+    recency: 0.2,
+    confidence: 0.2,
+    pinned: 0.3,
+    correction: 0.1,
+    graph: 0.15,
+    semantic: 0.25,
+    // Reinforcement weight (#204). Sits between recency and semantic: reuse is a strong signal but must
+    // not override an explicit pin or a fresh correction. Only participates when the caller supplies
+    // per-memory strength scores; otherwise the ranker forces it to 0 (byte-identical legacy behaviour).
+    strength: 0.2,
+    // Source-authority importance weight (#204, O-F5). Default 0 (opt-in): always computed but inert
+    // until an operator sets a non-zero weight, so legacy ranking is byte-identical.
+    importance: 0,
+});
+export const DEFAULT_BUDGET_TOKENS = 1500;
+export const DEFAULT_MAX_INCLUDED = 12;
+export const DEFAULT_STALE_CONFIDENCE_THRESHOLD = 0.3;
+export const DEFAULT_LIST_BY_SCOPE_MAX_RESULTS = 500;

package/dist/version.d.ts

@@ -0,0 +1,2 @@
+export declare const KEIKO_MEMORY_RETRIEVAL_VERSION: "0.1.0";
+//# sourceMappingURL=version.d.ts.map

package/dist/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,8BAA8B,EAAG,OAAgB,CAAC"}

package/dist/version.js

@@ -0,0 +1,4 @@
+// Single source of truth for the package version. Pinned as a literal so consumers can
+// import it for telemetry or evidence persistence without parsing package.json at runtime.
+// Bump in lockstep with package.json on every release.
+export const KEIKO_MEMORY_RETRIEVAL_VERSION = "0.1.0";

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@oscharko-dev/keiko-memory-retrieval",
+  "version": "0.2.0",
+  "type": "module",
+  "license": "Apache-2.0",
+  "description": "MemoriaViva — Internal memory-retrieval package (Epic #204 child #210): pure-function scoped retrieval + hybrid ranking + token-budgeted context assembly over Governed Enterprise Memory Vault records. Caller supplies a MemoryQueryPort (no keiko-memory-vault import) so the vault remains injectable and this layer stays pure (no IO, no clock, no randomness; caller supplies nowMs). Ranking combines deterministic lexical relevance, recency decay, provenance confidence, pinned boost, correction boost, and graph proximity into a weighted sum. The context block carries inclusion/omission reasons per memory so downstream callers (Conversation Center #212, workflow agents #213) and audit (#214) can render fully explainable surfaces. Suppression check is duplicated inline (synced with @oscharko-dev/keiko-memory-governance/suppression.ts) to keep the dep graph on contracts+security only. ADR-0019 direction rule 3j enforces this scope. Not published independently.",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -b tsconfig.json",
+    "typecheck": "tsc -b tsconfig.json",
+    "test": "vitest run"
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22"
+  },
+  "dependencies": {
+    "@oscharko-dev/keiko-contracts": "0.2.0",
+    "@oscharko-dev/keiko-security": "0.2.0"
+  }
+}