@oscharko-dev/keiko-server 0.2.0

package/dist/memory-maintenance-handlers.d.ts

@@ -0,0 +1,35 @@
+import { type ReviewItem } from "@oscharko-dev/keiko-memory-consolidation";
+import type { MemoryVaultStore } from "@oscharko-dev/keiko-memory-vault";
+import type { EvidenceStore } from "@oscharko-dev/keiko-evidence";
+import type { UiHandlerDeps } from "./deps.js";
+import type { RouteContext, RouteResult } from "./routes.js";
+export interface MaintenanceCounts {
+    promoted: number;
+    archived: number;
+    forgotten: number;
+    superseded: number;
+    edgesCreated: number;
+    clustersInspected: number;
+    reviewItemsCreated: number;
+}
+export interface MaintenanceResult extends MaintenanceCounts {
+    readonly reviewItems: readonly ReviewItem[];
+}
+export interface RunMaintenanceOptions {
+    /** Injected clock. Defaults to Date.now(). Pass a fixed value to make the pass replay-stable. */
+    readonly nowMs?: number;
+}
+export declare function runMemoryMaintenance(vault: MemoryVaultStore, evidenceStore?: EvidenceStore, options?: RunMaintenanceOptions): MaintenanceResult;
+export declare const MEMORY_AUTO_MAINTENANCE_MIN_INTERVAL_MS: number;
+export declare function isMaintenanceDue(lastRunAtMs: number | undefined, nowMs: number, minIntervalMs?: number): boolean;
+export interface AutoMaintenanceState {
+    lastRunAtMs?: number;
+}
+export interface MaybeRunAutoMaintenanceOptions {
+    readonly nowMs: number;
+    readonly enabled: boolean;
+    readonly minIntervalMs?: number;
+}
+export declare function maybeRunAutoMaintenance(vault: MemoryVaultStore, evidenceStore: EvidenceStore | undefined, state: AutoMaintenanceState, options: MaybeRunAutoMaintenanceOptions): MaintenanceResult | null;
+export declare function handleRunMaintenance(ctx: RouteContext, deps: UiHandlerDeps): RouteResult;
+//# sourceMappingURL=memory-maintenance-handlers.d.ts.map

package/dist/memory-maintenance-handlers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-maintenance-handlers.d.ts","sourceRoot":"","sources":["../src/memory-maintenance-handlers.ts"],"names":[],"mappings":"AAmBA,OAAO,EAAoB,KAAK,UAAU,EAAE,MAAM,0CAA0C,CAAC;AAc7F,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kCAAkC,CAAC;AACzE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAClE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAC/C,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAI7D,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,kBAAkB,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,iBAAkB,SAAQ,iBAAiB;IAC1D,QAAQ,CAAC,WAAW,EAAE,SAAS,UAAU,EAAE,CAAC;CAC7C;AAuMD,MAAM,WAAW,qBAAqB;IACpC,iGAAiG;IACjG,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,gBAAgB,EACvB,aAAa,CAAC,EAAE,aAAa,EAC7B,OAAO,CAAC,EAAE,qBAAqB,GAC9B,iBAAiB,CAkCnB;AAQD,eAAO,MAAM,uCAAuC,QAAqB,CAAC;AAI1E,wBAAgB,gBAAgB,CAC9B,WAAW,EAAE,MAAM,GAAG,SAAS,EAC/B,KAAK,EAAE,MAAM,EACb,aAAa,GAAE,MAAgD,GAC9D,OAAO,CAIT;AAGD,MAAM,WAAW,oBAAoB;IACnC,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,8BAA8B;IAC7C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;CACjC;AAMD,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,gBAAgB,EACvB,aAAa,EAAE,aAAa,GAAG,SAAS,EACxC,KAAK,EAAE,oBAAoB,EAC3B,OAAO,EAAE,8BAA8B,GACtC,iBAAiB,GAAG,IAAI,CAS1B;AAED,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,YAAY,EAAE,IAAI,EAAE,aAAa,GAAG,WAAW,CAWxF"}

package/dist/memory-maintenance-handlers.js

@@ -0,0 +1,219 @@
+// Memory maintenance orchestrator (Epic #204) — the impure caller that drives the pure
+// consolidation engine (#208) + maintenance planner (governance #209) against the vault (#206).
+//
+// POST /api/memory/maintenance runs a bounded, synchronous pass:
+//   1. Load every memory (all scopes) + the access stats.
+//   2. Run consolidation on the accepted subset; persist auto-applicable relationship edges and
+//      return unresolved review items for MemoriaViva or CLI operators. Conflict and merge review
+//      items are NEVER auto-applied here.
+//   3. Compute the maintenance plan and apply it: promote (-> accepted), archive (-> archived),
+//      forget (vault delete + tombstone + reason). Confidence is immutable provenance and is never
+//      patched here (O-V2): reuse strengthens memories live in retrieval ranking, and disuse-decay
+//      is computed on the fly via the strength curve that gates archive/forget.
+//   4. Emit one audit event per applied effect and return the counts.
+//
+// CSRF: the server dispatch layer enforces x-keiko-csrf for POST, so this route is guarded without
+// any per-handler check. External faults (a vault write that throws) are wrapped into a typed 500
+// rather than crashing the loopback server.
+import { randomUUID } from "node:crypto";
+import { runConsolidation } from "@oscharko-dev/keiko-memory-consolidation";
+import { planMemoryMaintenance, } from "@oscharko-dev/keiko-memory-governance";
+import { errorBody } from "./routes.js";
+import { recordMemoryAudit } from "./memory-audit-handler.js";
+function emptyCounts() {
+    return {
+        promoted: 0,
+        archived: 0,
+        forgotten: 0,
+        superseded: 0,
+        edgesCreated: 0,
+        clustersInspected: 0,
+        reviewItemsCreated: 0,
+        reviewItems: [],
+    };
+}
+function isRouteResult(value) {
+    return (typeof value === "object" && value !== null && typeof value.status === "number");
+}
+function resolveVault(deps) {
+    if (deps.memoryVault === undefined) {
+        return {
+            status: 503,
+            body: errorBody("MEMORY_UNAVAILABLE", "Memory vault is not configured."),
+        };
+    }
+    return deps.memoryVault;
+}
+function emitAudit(evidenceStore, nowMs, kind, surface, summary, extra) {
+    if (evidenceStore === undefined)
+        return;
+    const event = {
+        schemaVersion: "1",
+        kind,
+        eventId: randomUUID(),
+        occurredAt: nowMs,
+        initiatorSurface: surface,
+        summary,
+        ...extra,
+    };
+    recordMemoryAudit({ evidenceStore }, event);
+}
+function recordsById(records) {
+    const map = new Map();
+    for (const record of records)
+        map.set(record.id, record);
+    return map;
+}
+// ─── Consolidation effects ───────────────────────────────────────────────────
+function isAutoApplicableConsolidationEdge(edge) {
+    return (edge.kind === "derived-from" || edge.kind === "related" || edge.kind === "temporal-precedes");
+}
+function applyEdges(vault, edges) {
+    let created = 0;
+    for (const edge of edges) {
+        if (!isAutoApplicableConsolidationEdge(edge))
+            continue;
+        vault.insertEdge(edge);
+        created += 1;
+    }
+    return created;
+}
+function runConsolidationPass(vault, nowMs, records, counts) {
+    const result = runConsolidation(records, {
+        nowMs,
+        newEdgeId: () => randomUUID(),
+        newReviewItemId: () => randomUUID(),
+    });
+    counts.edgesCreated += applyEdges(vault, result.edgesProposed);
+    counts.clustersInspected += result.clustersInspected;
+    counts.reviewItemsCreated += result.reviewItems.length;
+    counts.reviewItems.push(...result.reviewItems);
+}
+// ─── Plan application ──────────────────────────────────────────────────────────
+// Applies the archive / forget effects on the post-consolidation snapshot. Promotions are applied
+// SEPARATELY and BEFORE consolidation (see runMemoryMaintenance) so that freshly-accepted memories
+// are visible to conflict detection within the same maintenance pass.
+//
+// Confidence is NEVER mutated here (#204, O-V2): reinforcement-on-reuse is realised live in
+// retrieval ranking, and disuse-decay is computed on the fly via the strength curve that already
+// gates archive/forget — so provenance stays intact and every run is idempotent.
+function applyFadeEffects(vault, evidenceStore, nowMs, plan, byId, counts) {
+    applyArchives(vault, evidenceStore, nowMs, plan.archive, byId, counts);
+    applyForgets(vault, evidenceStore, nowMs, plan.forget, byId, counts);
+}
+function applyPromotions(vault, evidenceStore, nowMs, ids, byId, counts) {
+    for (const id of ids) {
+        const record = byId.get(id);
+        if (record === undefined)
+            continue;
+        vault.updateMemory(id, { status: "accepted" }, nowMs);
+        counts.promoted += 1;
+        emitAudit(evidenceStore, nowMs, "memory:accepted", "memory-center", "Promoted a strong proposed memory.", { memoryId: id, scope: record.scope });
+    }
+}
+function applyArchives(vault, evidenceStore, nowMs, ids, byId, counts) {
+    for (const id of ids) {
+        const record = byId.get(id);
+        if (record === undefined)
+            continue;
+        vault.updateMemory(id, { status: "archived" }, nowMs);
+        counts.archived += 1;
+        emitAudit(evidenceStore, nowMs, "memory:archived", "retention", "Archived a faded memory.", {
+            memoryId: id,
+            scope: record.scope,
+        });
+    }
+}
+function applyForgets(vault, evidenceStore, nowMs, forgets, byId, counts) {
+    for (const forget of forgets) {
+        const record = byId.get(forget.id);
+        if (record === undefined)
+            continue;
+        vault.deleteMemory(forget.id, {
+            tombstone: true,
+            forgetterSurface: "memory-maintenance",
+            reason: forget.reason,
+            nowMs,
+        });
+        counts.forgotten += 1;
+        emitAudit(evidenceStore, nowMs, "memory:forgotten", "retention", `Forgot a memory (${forget.reason}).`, {
+            memoryId: forget.id,
+            scope: record.scope,
+            tombstoned: true,
+        });
+    }
+}
+export function runMemoryMaintenance(vault, evidenceStore, options) {
+    // ONE clock for the whole pass: both plan phases and every vault write / audit timestamp use the
+    // same nowMs, so selection is consistent within a run and fully replay-stable when nowMs is
+    // injected (the deterministic-verification invariant the rest of the stack honours).
+    const nowMs = options?.nowMs ?? Date.now();
+    const counts = emptyCounts();
+    // Phase 1 — promote strong `proposed` memories FIRST. Consolidation and conflict detection only
+    // inspect `accepted` records, so without this a vault full of freshly-captured `proposed`
+    // memories would need a SECOND maintenance run before any near-duplicate or polarity conflict is
+    // resolved. Promoting up front makes a single "Run maintenance" fully effective.
+    const beforePromote = vault.listMemories({ includeExpired: true });
+    const promoteStats = vault.getAccessStats();
+    const promotePlan = planMemoryMaintenance(beforePromote, promoteStats, { nowMs });
+    applyPromotions(vault, evidenceStore, nowMs, promotePlan.promote, recordsById(beforePromote), counts);
+    // Phase 2 — consolidate the now-accepted set: link safe near-duplicate metadata and surface
+    // conflicts / merges as explicit review items. Status mutations require a later governed review.
+    const accepted = vault
+        .listMemories({ includeExpired: true })
+        .filter((record) => record.status === "accepted");
+    runConsolidationPass(vault, nowMs, accepted, counts);
+    // Phase 3 — archive / forget on the post-consolidation snapshot. The access stats feed the
+    // strength model; confidence itself is never mutated (O-V2).
+    const all = vault.listMemories({ includeExpired: true });
+    const accessStats = vault.getAccessStats();
+    const plan = planMemoryMaintenance(all, accessStats, { nowMs });
+    applyFadeEffects(vault, evidenceStore, nowMs, plan, recordsById(all), counts);
+    return counts;
+}
+// ─── Bounded autonomous maintenance (#204, O-V4) ───────────────────────────────
+// The strength/decay/forget pass only "lives" if it actually runs. Rather than a free-running
+// background loop (forbidden by the no-unbounded-hidden-activity invariant), maintenance is fired
+// opportunistically — once memory is used — and rate-limited to at most once per interval. The pass
+// itself is already bounded (maxForgetPerRun) and audited, so an autonomous fire is governed.
+export const MEMORY_AUTO_MAINTENANCE_MIN_INTERVAL_MS = 6 * 60 * 60 * 1000; // 6 hours
+// Pure: due iff never run, or the interval has elapsed. A non-finite/negative interval is treated as
+// "never auto-run" so a misconfiguration can only DISABLE, never spin.
+export function isMaintenanceDue(lastRunAtMs, nowMs, minIntervalMs = MEMORY_AUTO_MAINTENANCE_MIN_INTERVAL_MS) {
+    if (!Number.isFinite(minIntervalMs) || minIntervalMs <= 0)
+        return false;
+    if (lastRunAtMs === undefined)
+        return true;
+    return nowMs - lastRunAtMs >= minIntervalMs;
+}
+// Runs ONE bounded maintenance pass iff enabled AND due, advancing the cursor BEFORE running so a
+// re-entrant call within the same tick cannot double-fire. Returns the result, or null when skipped.
+// Never throws: a maintenance fault must not break the caller (e.g. a chat turn); it is swallowed
+// after advancing the cursor so a persistently-failing pass cannot hot-loop.
+export function maybeRunAutoMaintenance(vault, evidenceStore, state, options) {
+    if (!options.enabled)
+        return null;
+    if (!isMaintenanceDue(state.lastRunAtMs, options.nowMs, options.minIntervalMs))
+        return null;
+    state.lastRunAtMs = options.nowMs;
+    try {
+        return runMemoryMaintenance(vault, evidenceStore, { nowMs: options.nowMs });
+    }
+    catch {
+        return null;
+    }
+}
+export function handleRunMaintenance(ctx, deps) {
+    void ctx;
+    const vault = resolveVault(deps);
+    if (isRouteResult(vault))
+        return vault;
+    try {
+        const counts = runMemoryMaintenance(vault, deps.evidenceStore);
+        return { status: 200, body: counts };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : "Memory maintenance failed.";
+        return { status: 500, body: errorBody("MEMORY_MAINTENANCE_FAILED", message) };
+    }
+}

package/dist/memory-record-builders.d.ts

@@ -0,0 +1,4 @@
+import type { CaptureOutcome } from "@oscharko-dev/keiko-memory-capture";
+import type { MemoryId, MemoryRecord } from "@oscharko-dev/keiko-contracts/memory";
+export declare function buildMemoryRecordFromProposal(proposalId: MemoryId, outcome: CaptureOutcome): MemoryRecord | null;
+//# sourceMappingURL=memory-record-builders.d.ts.map

package/dist/memory-record-builders.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-record-builders.d.ts","sourceRoot":"","sources":["../src/memory-record-builders.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AACzE,OAAO,KAAK,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,sCAAsC,CAAC;AAEnF,wBAAgB,6BAA6B,CAC3C,UAAU,EAAE,QAAQ,EACpB,OAAO,EAAE,cAAc,GACtB,YAAY,GAAG,IAAI,CAiBrB"}

package/dist/memory-record-builders.js

@@ -0,0 +1,19 @@
+export function buildMemoryRecordFromProposal(proposalId, outcome) {
+    if (outcome.kind !== "candidate")
+        return null;
+    const { proposal } = outcome;
+    return {
+        id: proposalId,
+        schemaVersion: proposal.schemaVersion,
+        scope: proposal.scope,
+        type: proposal.type,
+        body: proposal.body,
+        tags: proposal.tags,
+        provenance: proposal.provenance,
+        validity: proposal.validity,
+        status: proposal.initialStatus,
+        pinned: false,
+        createdAt: proposal.proposedAt,
+        updatedAt: proposal.proposedAt,
+    };
+}

package/dist/memory-retention.d.ts

@@ -0,0 +1,31 @@
+import type { MemoryId, MemoryScope, MemoryStatus } from "@oscharko-dev/keiko-contracts";
+import type { MemoryVaultStore } from "@oscharko-dev/keiko-memory-vault";
+export interface MemoryRetentionPolicy {
+    readonly maxAgeMs?: number;
+    readonly maxRecordsPerScope?: number;
+    readonly expireProposalsAfterMs?: number;
+    readonly purgeForgottenAfterMs?: number;
+}
+export type MemoryRetentionReason = "expire-age" | "expire-proposal" | "evict-overflow";
+export interface MemoryRetentionDecision {
+    readonly memoryId: MemoryId;
+    readonly scope: MemoryScope;
+    readonly reason: MemoryRetentionReason;
+    readonly updatedAt: number;
+    readonly status: MemoryStatus;
+}
+export interface MemoryRetentionResult {
+    readonly evaluated: number;
+    readonly forgotten: readonly MemoryRetentionDecision[];
+    readonly kept: number;
+    readonly byReason: Readonly<Record<MemoryRetentionReason, number>>;
+    readonly forgottenPurgeBacklog: number;
+}
+export interface ApplyMemoryRetentionOptions {
+    readonly vault: MemoryVaultStore;
+    readonly scopes: readonly MemoryScope[];
+    readonly policy: MemoryRetentionPolicy;
+    readonly nowMs: number;
+}
+export declare function applyMemoryRetention(options: ApplyMemoryRetentionOptions): MemoryRetentionResult;
+//# sourceMappingURL=memory-retention.d.ts.map

package/dist/memory-retention.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-retention.d.ts","sourceRoot":"","sources":["../src/memory-retention.ts"],"names":[],"mappings":"AAwBA,OAAO,KAAK,EACV,QAAQ,EAER,WAAW,EACX,YAAY,EACb,MAAM,+BAA+B,CAAC;AACvC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kCAAkC,CAAC;AAKzE,MAAM,WAAW,qBAAqB;IAGpC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAI3B,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAIrC,QAAQ,CAAC,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAGzC,QAAQ,CAAC,qBAAqB,CAAC,EAAE,MAAM,CAAC;CACzC;AAED,MAAM,MAAM,qBAAqB,GAAG,YAAY,GAAG,iBAAiB,GAAG,gBAAgB,CAAC;AAExF,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,qBAAqB,CAAC;IACvC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;CAC/B;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,EAAE,SAAS,uBAAuB,EAAE,CAAC;IACvD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,qBAAqB,EAAE,MAAM,CAAC,CAAC,CAAC;IAGnE,QAAQ,CAAC,qBAAqB,EAAE,MAAM,CAAC;CACxC;AA2GD,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,KAAK,EAAE,gBAAgB,CAAC;IACjC,QAAQ,CAAC,MAAM,EAAE,SAAS,WAAW,EAAE,CAAC;IACxC,QAAQ,CAAC,MAAM,EAAE,qBAAqB,CAAC;IACvC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,2BAA2B,GAAG,qBAAqB,CA8BhG"}

package/dist/memory-retention.js

@@ -0,0 +1,151 @@
+// Memory retention policy enforcer (Epic #204, Issue #214).
+//
+// Pure-ish function over the public MemoryVaultStore port. For each caller-supplied scope
+// it lists every memory, classifies each as `keep` / `expire-age` / `expire-proposal` /
+// `evict-overflow`, and issues `vault.deleteMemory(id, { tombstone: true, ... })` for
+// every non-keep classification. The audit handler (#214 bridge) observes the resulting
+// `memory:tombstoned` events and appends `memory:forgotten` records to the audit ledger
+// — retention enforcement is therefore self-audited through the existing seam.
+//
+// Hard invariants:
+//
+//   - Pinned records are NEVER eligible for retention. The pin flag overrides every other
+//     classification reason; tested explicitly.
+//   - Retention iterates the scopes the caller passes. The public MemoryVaultStore has no
+//     `listAllScopes()` capability, so a global enumeration would require an internal
+//     port extension. Out of scope here.
+//   - Forgotten-purge (purgeForgottenAfterMs) uses the public vault port to delete only
+//     tombstones in the caller-supplied scopes whose forgottenAt is older than the
+//     deterministic cutoff.
+//
+// Why the operations are issued in a sequence of one-by-one deletes: the vault's delete
+// is already wrapped in a SQLite transaction (#206), and emitting a batch API here would
+// hide the per-event audit signal that the handler depends on.
+import { memoryScopeKey } from "./memory-scope-sanitizer.js";
+// ─── Pure classification ──────────────────────────────────────────────────────
+function isAgeExpired(record, nowMs, policy) {
+    if (policy.maxAgeMs === undefined) {
+        return false;
+    }
+    return nowMs - record.updatedAt > policy.maxAgeMs;
+}
+function isProposalExpired(record, nowMs, policy) {
+    if (policy.expireProposalsAfterMs === undefined) {
+        return false;
+    }
+    if (record.status !== "proposed") {
+        return false;
+    }
+    return nowMs - record.updatedAt > policy.expireProposalsAfterMs;
+}
+// Returns the records that should be evicted by `maxRecordsPerScope`. Pinned records are
+// excluded from the count entirely so the cap applies to the non-pinned working set.
+function selectOverflowEvictions(records, policy) {
+    if (policy.maxRecordsPerScope === undefined) {
+        return [];
+    }
+    const nonPinned = records.filter((r) => !r.pinned);
+    if (nonPinned.length <= policy.maxRecordsPerScope) {
+        return [];
+    }
+    // Oldest-first by updatedAt, then by id so same-timestamp retention is deterministic
+    // across vault implementations and insertion orders.
+    const sorted = [...nonPinned].sort((a, b) => a.updatedAt - b.updatedAt || String(a.id).localeCompare(String(b.id)));
+    const overflowCount = nonPinned.length - policy.maxRecordsPerScope;
+    return sorted.slice(0, overflowCount);
+}
+// Returns either the reason a single record should be forgotten, or undefined to keep it.
+// Pinned records always return undefined. The age check takes precedence over the
+// proposal-expiry check so the reported reason is the most descriptive applicable kind.
+function classifyAgeOrProposal(record, nowMs, policy) {
+    if (record.pinned) {
+        return undefined;
+    }
+    if (isAgeExpired(record, nowMs, policy)) {
+        return "expire-age";
+    }
+    if (isProposalExpired(record, nowMs, policy)) {
+        return "expire-proposal";
+    }
+    return undefined;
+}
+// Combines per-record age/proposal classification with the per-scope overflow eviction
+// pass. Returns the deduplicated set of decisions; if a record qualifies under both an
+// age rule and an overflow rule, the age rule wins (more descriptive).
+function classifyScope(scope, records, nowMs, policy) {
+    const decisions = new Map();
+    for (const record of records) {
+        const reason = classifyAgeOrProposal(record, nowMs, policy);
+        if (reason === undefined) {
+            continue;
+        }
+        decisions.set(record.id, {
+            memoryId: record.id,
+            scope,
+            reason,
+            updatedAt: record.updatedAt,
+            status: record.status,
+        });
+    }
+    for (const record of selectOverflowEvictions(records, policy)) {
+        if (decisions.has(record.id)) {
+            continue;
+        }
+        decisions.set(record.id, {
+            memoryId: record.id,
+            scope,
+            reason: "evict-overflow",
+            updatedAt: record.updatedAt,
+            status: record.status,
+        });
+    }
+    return [...decisions.values()];
+}
+export function applyMemoryRetention(options) {
+    const { vault, scopes, policy, nowMs } = options;
+    const decisions = new Map();
+    let evaluated = 0;
+    let forgottenPurgeBacklog = 0;
+    const uniqueScopes = [...new Map(scopes.map((scope) => [memoryScopeKey(scope), scope])).values()];
+    for (const scope of uniqueScopes) {
+        const records = vault.listMemoriesByScope(scope, { includeExpired: true });
+        evaluated += records.length;
+        for (const decision of classifyScope(scope, records, nowMs, policy)) {
+            decisions.set(decision.memoryId, decision);
+        }
+        forgottenPurgeBacklog += countPurgeBacklog(vault, scope, policy, nowMs);
+    }
+    const forgotten = [...decisions.values()];
+    for (const decision of forgotten) {
+        vault.deleteMemory(decision.memoryId, {
+            tombstone: true,
+            forgetterSurface: "retention",
+            reason: decision.reason,
+            nowMs,
+        });
+    }
+    return {
+        evaluated,
+        forgotten,
+        kept: evaluated - forgotten.length,
+        byReason: countByReason(forgotten),
+        forgottenPurgeBacklog,
+    };
+}
+function countByReason(decisions) {
+    const counts = {
+        "expire-age": 0,
+        "expire-proposal": 0,
+        "evict-overflow": 0,
+    };
+    for (const d of decisions) {
+        counts[d.reason] += 1;
+    }
+    return counts;
+}
+function countPurgeBacklog(vault, scope, policy, nowMs) {
+    if (policy.purgeForgottenAfterMs === undefined) {
+        return 0;
+    }
+    return vault.purgeTombstonesByScopeBefore(scope, nowMs - policy.purgeForgottenAfterMs);
+}

package/dist/memory-retrieval-signals.d.ts

@@ -0,0 +1,12 @@
+import type { MemoryId, MemoryScope } from "@oscharko-dev/keiko-contracts/memory";
+import { type RankingFusionMode } from "@oscharko-dev/keiko-memory-retrieval";
+import type { MemoryVaultStore } from "@oscharko-dev/keiko-memory-vault";
+import type { UiHandlerDeps } from "./deps.js";
+export declare function conversationFusionMode(deps: UiHandlerDeps): RankingFusionMode;
+export interface ConversationRetrievalSignals {
+    readonly semanticById?: ReadonlyMap<MemoryId, number> | undefined;
+    readonly strengthById: ReadonlyMap<MemoryId, number>;
+    readonly embeddingById: ReadonlyMap<MemoryId, Float32Array>;
+}
+export declare function buildConversationRetrievalSignals(deps: UiHandlerDeps, vault: MemoryVaultStore, queryText: string | undefined, scopes: readonly MemoryScope[], nowMs: number, safeForSecondaryModel: boolean, signal?: AbortSignal): Promise<ConversationRetrievalSignals>;
+//# sourceMappingURL=memory-retrieval-signals.d.ts.map

package/dist/memory-retrieval-signals.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-retrieval-signals.d.ts","sourceRoot":"","sources":["../src/memory-retrieval-signals.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAE,QAAQ,EAAgB,WAAW,EAAE,MAAM,sCAAsC,CAAC;AAChG,OAAO,EAKL,KAAK,iBAAiB,EACvB,MAAM,sCAAsC,CAAC;AAC9C,OAAO,KAAK,EAAsB,gBAAgB,EAAE,MAAM,kCAAkC,CAAC;AAE7F,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AA+D/C,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,aAAa,GAAG,iBAAiB,CAE7E;AAED,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,CAAC,YAAY,CAAC,EAAE,WAAW,CAAC,QAAQ,EAAE,MAAM,CAAC,GAAG,SAAS,CAAC;IAClE,QAAQ,CAAC,YAAY,EAAE,WAAW,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;IAIrD,QAAQ,CAAC,aAAa,EAAE,WAAW,CAAC,QAAQ,EAAE,YAAY,CAAC,CAAC;CAC7D;AAQD,wBAAsB,iCAAiC,CACrD,IAAI,EAAE,aAAa,EACnB,KAAK,EAAE,gBAAgB,EACvB,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,MAAM,EAAE,SAAS,WAAW,EAAE,EAC9B,KAAK,EAAE,MAAM,EACb,qBAAqB,EAAE,OAAO,EAC9B,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,4BAA4B,CAAC,CAyBvC"}

package/dist/memory-retrieval-signals.js

@@ -0,0 +1,100 @@
+// Shared conversation-retrieval signal builder (#204, O-F4).
+//
+// Both conversation retrieval surfaces — the desktop chat path (chat-handlers) and the BFF
+// /api/memory/context route (memory-conv-handlers) — need the same two model/usage-derived ranking
+// signals on top of the pure lexical ranker:
+//   - semanticById: per-memory cosine of the query embedding to each candidate's stored vector
+//     (embedding-based recall), gated by the secondary-model egress check.
+//   - strengthById: per-memory reinforcement strength from the vault's access counters (O-P1).
+// Previously only the chat path built them; the BFF route silently ran lexical-only. Centralising
+// them here keeps the two surfaces from drifting (the same class of duplication C3 guards for
+// suppression) and gives any future consumer of the route the stronger embedding signal by default.
+//
+// Pure of policy: the caller decides whether the query is egress-safe and passes that in. Graceful:
+// no embedding model => semanticById undefined (byte-identical lexical fallback); empty access
+// history => strengthById empty (the ranker zeroes its weight).
+import { buildStrengthById, DEFAULT_LIST_BY_SCOPE_MAX_RESULTS, DEFAULT_STALE_CONFIDENCE_THRESHOLD, isMemorySuppressed, } from "@oscharko-dev/keiko-memory-retrieval";
+import { cosineSimilarity, embedMemoryText } from "./memory-embedding.js";
+// A candidate is worth scoring iff the ranker could surface it. A superset of the ranked set is
+// harmless: ids the ranker filters out simply never read their semantic score.
+function isSemanticRetrievalCandidate(record, nowMs) {
+    if (record.status === "superseded")
+        return false;
+    return !isMemorySuppressed(record, nowMs, DEFAULT_STALE_CONFIDENCE_THRESHOLD).suppressed;
+}
+function gatherCandidateIds(vault, scopes, nowMs, signal) {
+    const ids = [];
+    const seen = new Set();
+    for (const scope of scopes) {
+        throwIfAborted(signal);
+        for (const record of vault.listMemoriesByScope(scope, {
+            includeExpired: true,
+            limit: DEFAULT_LIST_BY_SCOPE_MAX_RESULTS,
+        })) {
+            throwIfAborted(signal);
+            if (!isSemanticRetrievalCandidate(record, nowMs))
+                continue;
+            if (seen.has(record.id))
+                continue;
+            seen.add(record.id);
+            ids.push(record.id);
+        }
+    }
+    return ids;
+}
+// Per-memory semantic score map for the candidate set, or undefined when no embedding model is
+// configured (query embedding null) — that undefined drives the byte-identical lexical fallback in
+// the ranker. A candidate whose stored vector is missing is omitted (semantic subscore 0 for it).
+// Query-cosine scores for the candidate set, computed from the already-fetched embeddings. Gated by
+// the egress check (it embeds the query). Returns undefined when no model / no query embedding.
+async function semanticScoresFrom(deps, queryText, candidateIds, embeddings, signal) {
+    throwIfAborted(signal);
+    const queryEmbedding = await embedMemoryText(deps, queryText);
+    if (queryEmbedding === null)
+        return undefined;
+    throwIfAborted(signal);
+    const scores = new Map();
+    for (const id of candidateIds) {
+        throwIfAborted(signal);
+        const stored = embeddings.get(id);
+        if (stored === undefined)
+            continue;
+        scores.set(id, cosineSimilarity(queryEmbedding.vector, stored.vector));
+    }
+    return scores;
+}
+// Signal-fusion mode for the conversation retrieval surfaces (#204, O-F2). Opt-in via env to keep
+// the release on the byte-identical weighted-sum default; set KEIKO_MEMORY_FUSION=rrf to enable
+// rank-based Reciprocal Rank Fusion across both the chat and BFF paths.
+export function conversationFusionMode(deps) {
+    return deps.env.KEIKO_MEMORY_FUSION === "rrf" ? "rrf" : "weighted-sum";
+}
+function throwIfAborted(signal) {
+    if (signal?.aborted === true) {
+        throw new Error("memory retrieval aborted");
+    }
+}
+export async function buildConversationRetrievalSignals(deps, vault, queryText, scopes, nowMs, safeForSecondaryModel, signal) {
+    throwIfAborted(signal);
+    const strengthById = buildStrengthById(vault.getAccessStats(), nowMs);
+    throwIfAborted(signal);
+    const candidateIds = gatherCandidateIds(vault, scopes, nowMs, signal);
+    throwIfAborted(signal);
+    const embeddings = candidateIds.length > 0
+        ? vault.getEmbeddings(candidateIds)
+        : new Map();
+    throwIfAborted(signal);
+    const embeddingById = new Map();
+    for (const [id, row] of embeddings) {
+        throwIfAborted(signal);
+        embeddingById.set(id, row.vector);
+    }
+    const semanticById = safeForSecondaryModel && queryText !== undefined && queryText.length > 0 && embeddings.size > 0
+        ? await semanticScoresFrom(deps, queryText, candidateIds, embeddings, signal)
+        : undefined;
+    return {
+        strengthById,
+        embeddingById,
+        ...(semanticById !== undefined ? { semanticById } : {}),
+    };
+}

package/dist/memory-salience.d.ts

@@ -0,0 +1,12 @@
+import type { ConversationMemoryActionWire } from "@oscharko-dev/keiko-contracts/bff-wire";
+import type { UiHandlerDeps } from "./deps.js";
+import { type ConversationMemoryRuntimeContext } from "./memory-conversation-context.js";
+interface SalienceTurnRequest {
+    readonly content: string;
+    readonly memory: {
+        readonly enabled: boolean;
+    } | undefined;
+}
+export declare function captureSalientFromTurn(deps: UiHandlerDeps, request: SalienceTurnRequest, context: ConversationMemoryRuntimeContext, modelId: string, assistantText: string): Promise<readonly ConversationMemoryActionWire[]>;
+export {};
+//# sourceMappingURL=memory-salience.d.ts.map

package/dist/memory-salience.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-salience.d.ts","sourceRoot":"","sources":["../src/memory-salience.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,wCAAwC,CAAC;AAU3F,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAE/C,OAAO,EAEL,KAAK,gCAAgC,EACtC,MAAM,kCAAkC,CAAC;AA0H1C,UAAU,mBAAmB;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE;QAAE,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;KAAE,GAAG,SAAS,CAAC;CAC5D;AAID,wBAAsB,sBAAsB,CAC1C,IAAI,EAAE,aAAa,EACnB,OAAO,EAAE,mBAAmB,EAC5B,OAAO,EAAE,gCAAgC,EACzC,OAAO,EAAE,MAAM,EACf,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,SAAS,4BAA4B,EAAE,CAAC,CA2ClD"}