@framers/agentos 0.2.5 → 0.2.7

package/dist/memory-router/MemoryRouter.d.ts

@@ -0,0 +1,195 @@
+/**
+ * @file MemoryRouter.ts
+ * @description Top-level orchestrator that composes the LLM-as-judge
+ * classifier and the pure `selectBackend` decision function into a single
+ * per-query routing call.
+ *
+ * MemoryRouter is deliberately a THIN composition layer. It:
+ *   1. Runs the classifier on the incoming query → category + token counts.
+ *   2. Resolves the routing table from (preset | custom table | custom mapping).
+ *   3. Calls the pure selectBackend to get the routing decision.
+ *   4. Returns a {@link MemoryRouterDecision} bundling both.
+ *
+ * It does NOT execute the recall — backend execution is the job of
+ * {@link IMemoryDispatcher}. This split keeps the router pure-enough to
+ * be used in both "decide only" flows (benchmarks, dashboards, dry-runs)
+ * and "decide + execute" flows (production queries).
+ *
+ * @module @framers/agentos/memory-router/MemoryRouter
+ */
+import type { IMemoryClassifier, MemoryClassifierResult } from './classifier.js';
+import { type MemoryBackendCostPoint } from './backend-costs.js';
+import { type MemoryBackendId, type MemoryQueryCategory, type MemoryRouterPreset, type RoutingTable } from './routing-tables.js';
+import { type MemoryBudgetMode, type MemoryRoutingDecision } from './select-backend.js';
+import type { IMemoryDispatcher } from './dispatcher.js';
+/**
+ * Per-query USD budget policy. Combined into a single nested object so
+ * consumers can enable budget enforcement without flat-argument sprawl.
+ */
+export interface MemoryBudgetPolicy {
+    /**
+     * Budget ceiling per query in USD. When omitted, routing passes
+     * through the table's pick regardless of cost.
+     */
+    readonly perQueryUsd?: number;
+    /**
+     * How to handle budget overrun. Default `cheapest-fallback` for
+     * production safety (silently downgrades rather than throwing).
+     * See {@link MemoryBudgetMode}.
+     */
+    readonly mode?: MemoryBudgetMode;
+}
+/**
+ * Constructor options for {@link MemoryRouter}.
+ */
+export interface MemoryRouterOptions {
+    /** LLM-as-judge classifier. Usually {@link LLMMemoryClassifier}. */
+    readonly classifier: IMemoryClassifier;
+    /**
+     * Shipping preset to use. Defaults to `minimize-cost` — the same
+     * Pareto-best-for-cost preset we use on LongMemEval-S Phase B.
+     */
+    readonly preset?: MemoryRouterPreset;
+    /**
+     * Optional custom routing table override. When provided, replaces the
+     * preset's default table. The `preset` field is still used for
+     * telemetry labeling and must match.
+     */
+    readonly routingTable?: RoutingTable;
+    /**
+     * Optional per-category routing override that patches the resolved
+     * routing table. Useful when a workload needs to change a single
+     * category's dispatch without rewriting the whole table.
+     */
+    readonly mapping?: Partial<Record<MemoryQueryCategory, MemoryBackendId>>;
+    /**
+     * Optional budget policy. When omitted, no budget is enforced.
+     */
+    readonly budget?: MemoryBudgetPolicy;
+    /**
+     * Optional custom backend cost-points (for workloads whose cost /
+     * accuracy profile diverges from LongMemEval-S Phase B). When omitted,
+     * uses {@link DEFAULT_MEMORY_BACKEND_COSTS}.
+     */
+    readonly backendCosts?: Readonly<Record<MemoryBackendId, MemoryBackendCostPoint>>;
+    /**
+     * Default for {@link MemoryClassifierClassifyOptions.useFewShotPrompt}
+     * on every `decide()` call. Callers can still override per-call.
+     */
+    readonly useFewShotPrompt?: boolean;
+    /**
+     * Optional dispatcher. When supplied, {@link MemoryRouter.decideAndDispatch}
+     * is usable; otherwise callers must use {@link MemoryRouter.decide} and
+     * execute the chosen backend themselves.
+     */
+    readonly dispatcher?: IMemoryDispatcher<unknown, unknown>;
+}
+/**
+ * Per-call options for {@link MemoryRouter.decide}.
+ */
+export interface MemoryRouterDecideOptions {
+    /**
+     * Ground-truth category, passed through to the routing decision for
+     * telemetry. Not used in production. Benchmark adapters pass this when
+     * the gold label is available so downstream analysis can distinguish
+     * classifier misroutes from architectural misses.
+     */
+    readonly groundTruthCategory?: MemoryQueryCategory | null;
+    /**
+     * Per-call override of the few-shot prompt variant. When omitted,
+     * inherits the router's constructor-scoped default.
+     */
+    readonly useFewShotPrompt?: boolean;
+}
+/**
+ * Bundled result of a `decide()` call. Carries the classifier result
+ * (for cost tracking + debugging) alongside the routing decision.
+ */
+export interface MemoryRouterDecision {
+    readonly classifier: MemoryClassifierResult;
+    readonly routing: MemoryRoutingDecision;
+}
+/**
+ * Bundled result of a `decideAndDispatch()` call. Combines the full
+ * {@link MemoryRouterDecision} with the dispatched traces so telemetry
+ * and answer-generation can consume both in one step.
+ */
+export interface MemoryRouterDispatchedDecision<TTrace> {
+    readonly decision: MemoryRouterDecision;
+    readonly traces: TTrace[];
+    readonly backend: MemoryBackendId;
+}
+/**
+ * Thrown when `decideAndDispatch` is called on a router that was
+ * constructed without a dispatcher.
+ */
+export declare class MemoryRouterDispatcherMissingError extends Error {
+    constructor();
+}
+/**
+ * The public MemoryRouter primitive. One instance per memory-recall
+ * endpoint; construct once at app startup with the chosen preset and
+ * reuse across queries.
+ *
+ * @example Basic min-cost routing
+ * ```ts
+ * import { LLMMemoryClassifier, MemoryRouter } from '../memory-router';
+ *
+ * const router = new MemoryRouter({
+ *   classifier: new LLMMemoryClassifier({ llm: myOpenAIAdapter }),
+ *   preset: 'minimize-cost',
+ * });
+ *
+ * const decision = await router.decide("What's my current job title?");
+ * console.log(decision.classifier.category); // 'knowledge-update'
+ * console.log(decision.routing.chosenBackend); // 'canonical-hybrid'
+ * console.log(decision.routing.estimatedCostUsd); // 0.0189
+ * ```
+ *
+ * @example With a strict budget
+ * ```ts
+ * const router = new MemoryRouter({
+ *   classifier: myClassifier,
+ *   preset: 'maximize-accuracy',
+ *   budget: { perQueryUsd: 0.025, mode: 'cheapest-fallback' },
+ * });
+ * ```
+ */
+export declare class MemoryRouter {
+    private readonly classifier;
+    private readonly preset;
+    private readonly routingTable;
+    private readonly budgetPerQuery;
+    private readonly budgetMode;
+    private readonly backendCosts;
+    private readonly defaultUseFewShotPrompt;
+    private readonly dispatcher;
+    constructor(options: MemoryRouterOptions);
+    /**
+     * Decide-only routing. Classifies the query, picks a backend, returns
+     * both pieces. Does NOT execute the recall — pair with an
+     * {@link IMemoryDispatcher} for the end-to-end flow, or call
+     * {@link MemoryRouter.decideAndDispatch} if a dispatcher is wired.
+     *
+     * @param query - The user's memory-recall query text.
+     * @param options - Per-call overrides (ground-truth telemetry, prompt variant).
+     * @returns A {@link MemoryRouterDecision} bundling classifier + routing results.
+     */
+    decide(query: string, options?: MemoryRouterDecideOptions): Promise<MemoryRouterDecision>;
+    /**
+     * Decide + dispatch in one call. Requires the router to have been
+     * constructed with a {@link IMemoryDispatcher}.
+     *
+     * @typeParam TTrace - Caller's trace shape (passed through verbatim).
+     * @typeParam TPayload - Caller's payload shape for the dispatcher.
+     * @param query - User memory-recall query.
+     * @param dispatchPayload - Optional payload forwarded to the dispatcher's
+     *   per-backend executor (e.g. topK, retrieval policy).
+     * @param options - Per-call overrides (ground-truth telemetry, prompt variant).
+     *
+     * @throws {@link MemoryRouterDispatcherMissingError} when no dispatcher
+     *   was supplied at construction.
+     */
+    decideAndDispatch<TTrace, TPayload = undefined>(query: string, dispatchPayload?: TPayload, options?: MemoryRouterDecideOptions): Promise<MemoryRouterDispatchedDecision<TTrace>>;
+}
+//# sourceMappingURL=MemoryRouter.d.ts.map

package/dist/memory-router/MemoryRouter.d.ts.map

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

package/dist/memory-router/MemoryRouter.js

@@ -0,0 +1,155 @@
+/**
+ * @file MemoryRouter.ts
+ * @description Top-level orchestrator that composes the LLM-as-judge
+ * classifier and the pure `selectBackend` decision function into a single
+ * per-query routing call.
+ *
+ * MemoryRouter is deliberately a THIN composition layer. It:
+ *   1. Runs the classifier on the incoming query → category + token counts.
+ *   2. Resolves the routing table from (preset | custom table | custom mapping).
+ *   3. Calls the pure selectBackend to get the routing decision.
+ *   4. Returns a {@link MemoryRouterDecision} bundling both.
+ *
+ * It does NOT execute the recall — backend execution is the job of
+ * {@link IMemoryDispatcher}. This split keeps the router pure-enough to
+ * be used in both "decide only" flows (benchmarks, dashboards, dry-runs)
+ * and "decide + execute" flows (production queries).
+ *
+ * @module @framers/agentos/memory-router/MemoryRouter
+ */
+import { DEFAULT_MEMORY_BACKEND_COSTS, } from './backend-costs.js';
+import { PRESET_TABLES, } from './routing-tables.js';
+import { selectBackend, } from './select-backend.js';
+/**
+ * Thrown when `decideAndDispatch` is called on a router that was
+ * constructed without a dispatcher.
+ */
+export class MemoryRouterDispatcherMissingError extends Error {
+    constructor() {
+        super('MemoryRouter.decideAndDispatch requires a dispatcher. ' +
+            'Either pass a dispatcher in options, or call `decide` and dispatch yourself.');
+        this.name = 'MemoryRouterDispatcherMissingError';
+    }
+}
+// ============================================================================
+// Class
+// ============================================================================
+/**
+ * The public MemoryRouter primitive. One instance per memory-recall
+ * endpoint; construct once at app startup with the chosen preset and
+ * reuse across queries.
+ *
+ * @example Basic min-cost routing
+ * ```ts
+ * import { LLMMemoryClassifier, MemoryRouter } from '../memory-router/index.js';
+ *
+ * const router = new MemoryRouter({
+ *   classifier: new LLMMemoryClassifier({ llm: myOpenAIAdapter }),
+ *   preset: 'minimize-cost',
+ * });
+ *
+ * const decision = await router.decide("What's my current job title?");
+ * console.log(decision.classifier.category); // 'knowledge-update'
+ * console.log(decision.routing.chosenBackend); // 'canonical-hybrid'
+ * console.log(decision.routing.estimatedCostUsd); // 0.0189
+ * ```
+ *
+ * @example With a strict budget
+ * ```ts
+ * const router = new MemoryRouter({
+ *   classifier: myClassifier,
+ *   preset: 'maximize-accuracy',
+ *   budget: { perQueryUsd: 0.025, mode: 'cheapest-fallback' },
+ * });
+ * ```
+ */
+export class MemoryRouter {
+    constructor(options) {
+        this.classifier = options.classifier;
+        this.preset = options.preset ?? 'minimize-cost';
+        this.dispatcher = options.dispatcher ?? null;
+        // Resolve routing table: explicit > preset's default.
+        const baseTable = options.routingTable ?? PRESET_TABLES[this.preset];
+        // Apply optional per-category mapping override.
+        if (options.mapping) {
+            const patched = {
+                ...baseTable.defaultMapping,
+            };
+            for (const key of Object.keys(options.mapping)) {
+                const override = options.mapping[key];
+                if (override)
+                    patched[key] = override;
+            }
+            this.routingTable = Object.freeze({
+                preset: baseTable.preset,
+                defaultMapping: Object.freeze(patched),
+            });
+        }
+        else {
+            this.routingTable = baseTable;
+        }
+        this.budgetPerQuery = options.budget?.perQueryUsd ?? null;
+        this.budgetMode = options.budget?.mode ?? 'cheapest-fallback';
+        this.backendCosts = options.backendCosts ?? DEFAULT_MEMORY_BACKEND_COSTS;
+        this.defaultUseFewShotPrompt = options.useFewShotPrompt ?? false;
+    }
+    /**
+     * Decide-only routing. Classifies the query, picks a backend, returns
+     * both pieces. Does NOT execute the recall — pair with an
+     * {@link IMemoryDispatcher} for the end-to-end flow, or call
+     * {@link MemoryRouter.decideAndDispatch} if a dispatcher is wired.
+     *
+     * @param query - The user's memory-recall query text.
+     * @param options - Per-call overrides (ground-truth telemetry, prompt variant).
+     * @returns A {@link MemoryRouterDecision} bundling classifier + routing results.
+     */
+    async decide(query, options) {
+        const useFewShot = options?.useFewShotPrompt ?? this.defaultUseFewShotPrompt;
+        const classifierOptions = useFewShot
+            ? { useFewShotPrompt: true }
+            : undefined;
+        const classifier = await this.classifier.classify(query, classifierOptions);
+        const routing = selectBackend({
+            predictedCategory: classifier.category,
+            groundTruthCategory: options?.groundTruthCategory ?? null,
+            config: {
+                table: this.routingTable,
+                budgetPerQuery: this.budgetPerQuery,
+                budgetMode: this.budgetMode,
+                backendCosts: this.backendCosts,
+            },
+        });
+        return { classifier, routing };
+    }
+    /**
+     * Decide + dispatch in one call. Requires the router to have been
+     * constructed with a {@link IMemoryDispatcher}.
+     *
+     * @typeParam TTrace - Caller's trace shape (passed through verbatim).
+     * @typeParam TPayload - Caller's payload shape for the dispatcher.
+     * @param query - User memory-recall query.
+     * @param dispatchPayload - Optional payload forwarded to the dispatcher's
+     *   per-backend executor (e.g. topK, retrieval policy).
+     * @param options - Per-call overrides (ground-truth telemetry, prompt variant).
+     *
+     * @throws {@link MemoryRouterDispatcherMissingError} when no dispatcher
+     *   was supplied at construction.
+     */
+    async decideAndDispatch(query, dispatchPayload, options) {
+        if (!this.dispatcher) {
+            throw new MemoryRouterDispatcherMissingError();
+        }
+        const decision = await this.decide(query, options);
+        const dispatched = (await this.dispatcher.dispatch({
+            backend: decision.routing.chosenBackend,
+            query,
+            payload: dispatchPayload,
+        }));
+        return {
+            decision,
+            traces: dispatched.traces,
+            backend: dispatched.backend,
+        };
+    }
+}
+//# sourceMappingURL=MemoryRouter.js.map

package/dist/memory-router/MemoryRouter.js.map

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

package/dist/memory-router/backend-costs.d.ts

@@ -0,0 +1,67 @@
+/**
+ * @file backend-costs.ts
+ * @description Per-backend per-category cost-accuracy-latency points
+ * measured on LongMemEval-S Phase B (N=500). The {@link MemoryRouter} uses
+ * these to:
+ *   - estimate the per-query USD cost of a routing decision before executing,
+ *   - apply budget constraints (`hard` / `soft` / `cheapest-fallback`),
+ *   - pick the cheapest backend that fits a budget when downgrading.
+ *
+ * Numbers come from the canonical Phase B run JSONs:
+ *   - canonical-hybrid: results/runs/2026-04-20T20-03-14-675 (Tier 1)
+ *   - observational-memory-v10: results/runs/2026-04-23T04-14-40-609 (Tier 2a v10)
+ *   - observational-memory-v11: results/runs/2026-04-23T17-27-28-793 (Tier 2b v11)
+ *
+ * The per-tier `avgCostPerQuery` is the totalUsd-divided-by-n_cases
+ * average; on routed configurations the actual per-call cost depends on
+ * which backend the dispatcher picked and which category the call hit, so
+ * the per-category breakdown below is what the router actually consumes.
+ *
+ * @module @framers/agentos/memory-router/backend-costs
+ */
+import type { MemoryBackendId, MemoryQueryCategory } from './routing-tables.js';
+/**
+ * Cost-accuracy-latency point for one backend across the six categories.
+ * The router compares these to make budget-aware decisions.
+ */
+export interface MemoryBackendCostPoint {
+    readonly backend: MemoryBackendId;
+    /** Average USD per query across all categories (Phase B aggregate). */
+    readonly avgCostPerQuery: number;
+    /** Per-category accuracy at this backend (Phase B N=500). */
+    readonly perCategoryAccuracy: Readonly<Record<MemoryQueryCategory, number>>;
+    /** Per-category USD per query at this backend (Phase B N=500). */
+    readonly perCategoryCostPerQuery: Readonly<Record<MemoryQueryCategory, number>>;
+    /** Per-category average latency in ms at this backend (Phase B N=500). */
+    readonly perCategoryLatencyMs: Readonly<Record<MemoryQueryCategory, number>>;
+}
+/**
+ * canonical-hybrid: BM25 + dense + RRF + Cohere rerank-v3.5 over raw
+ * memory traces. Phase B measured 73.2% [69.2, 77.0] aggregate at
+ * $0.0213/correct.
+ */
+export declare const TIER_1_CANONICAL_COSTS: MemoryBackendCostPoint;
+/**
+ * observational-memory-v10: synthesized observation log + classifier-driven
+ * dispatch inside the OM pipeline (no verbatim citation). Phase B measured
+ * 74.6% [70.8, 78.4] aggregate at $0.3265/correct, 12s avg latency.
+ */
+export declare const TIER_2A_V10_COSTS: MemoryBackendCostPoint;
+/**
+ * observational-memory-v11: v10 + conditional verbatim citation rule for
+ * knowledge-update and single-session-user categories. Phase B measured
+ * 75.4% [71.6, 79.0] aggregate at $0.4362/correct, 14s avg latency.
+ */
+export declare const TIER_2B_V11_COSTS: MemoryBackendCostPoint;
+/**
+ * Default cost-points registry. Indexed by {@link MemoryBackendId} so the
+ * router can look up the picked backend's cost on any category.
+ *
+ * Custom deployments can substitute their own cost-points by passing a
+ * different `backendCosts` map into the {@link MemoryRouter} config —
+ * useful when a workload diverges from the LongMemEval-S Phase B
+ * distribution and the calibrator wants to plug in measurements from
+ * their own benchmark.
+ */
+export declare const DEFAULT_MEMORY_BACKEND_COSTS: Readonly<Record<MemoryBackendId, MemoryBackendCostPoint>>;
+//# sourceMappingURL=backend-costs.d.ts.map

package/dist/memory-router/backend-costs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"backend-costs.d.ts","sourceRoot":"","sources":["../../src/memory-router/backend-costs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAEhF;;;GAGG;AACH,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAC;IAClC,uEAAuE;IACvE,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,6DAA6D;IAC7D,QAAQ,CAAC,mBAAmB,EAAE,QAAQ,CAAC,MAAM,CAAC,mBAAmB,EAAE,MAAM,CAAC,CAAC,CAAC;IAC5E,kEAAkE;IAClE,QAAQ,CAAC,uBAAuB,EAAE,QAAQ,CAAC,MAAM,CAAC,mBAAmB,EAAE,MAAM,CAAC,CAAC,CAAC;IAChF,0EAA0E;IAC1E,QAAQ,CAAC,oBAAoB,EAAE,QAAQ,CAAC,MAAM,CAAC,mBAAmB,EAAE,MAAM,CAAC,CAAC,CAAC;CAC9E;AAED;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,EAAE,sBA2BT,CAAC;AAE7B;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,EAAE,sBA2BJ,CAAC;AAE7B;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,EAAE,sBA2BJ,CAAC;AAE7B;;;;;;;;;GASG;AACH,eAAO,MAAM,4BAA4B,EAAE,QAAQ,CACjD,MAAM,CAAC,eAAe,EAAE,sBAAsB,CAAC,CAK/C,CAAC"}

package/dist/memory-router/backend-costs.js

@@ -0,0 +1,136 @@
+/**
+ * @file backend-costs.ts
+ * @description Per-backend per-category cost-accuracy-latency points
+ * measured on LongMemEval-S Phase B (N=500). The {@link MemoryRouter} uses
+ * these to:
+ *   - estimate the per-query USD cost of a routing decision before executing,
+ *   - apply budget constraints (`hard` / `soft` / `cheapest-fallback`),
+ *   - pick the cheapest backend that fits a budget when downgrading.
+ *
+ * Numbers come from the canonical Phase B run JSONs:
+ *   - canonical-hybrid: results/runs/2026-04-20T20-03-14-675 (Tier 1)
+ *   - observational-memory-v10: results/runs/2026-04-23T04-14-40-609 (Tier 2a v10)
+ *   - observational-memory-v11: results/runs/2026-04-23T17-27-28-793 (Tier 2b v11)
+ *
+ * The per-tier `avgCostPerQuery` is the totalUsd-divided-by-n_cases
+ * average; on routed configurations the actual per-call cost depends on
+ * which backend the dispatcher picked and which category the call hit, so
+ * the per-category breakdown below is what the router actually consumes.
+ *
+ * @module @framers/agentos/memory-router/backend-costs
+ */
+/**
+ * canonical-hybrid: BM25 + dense + RRF + Cohere rerank-v3.5 over raw
+ * memory traces. Phase B measured 73.2% [69.2, 77.0] aggregate at
+ * $0.0213/correct.
+ */
+export const TIER_1_CANONICAL_COSTS = Object.freeze({
+    backend: 'canonical-hybrid',
+    avgCostPerQuery: 0.0156,
+    perCategoryAccuracy: Object.freeze({
+        'single-session-user': 0.971,
+        'single-session-assistant': 0.893,
+        'single-session-preference': 0.600,
+        'knowledge-update': 0.868,
+        'multi-session': 0.549,
+        'temporal-reasoning': 0.702,
+    }),
+    perCategoryCostPerQuery: Object.freeze({
+        'single-session-user': 0.0191,
+        'single-session-assistant': 0.0175,
+        'single-session-preference': 0.0206,
+        'knowledge-update': 0.0189,
+        'multi-session': 0.0196,
+        'temporal-reasoning': 0.0202,
+    }),
+    perCategoryLatencyMs: Object.freeze({
+        'single-session-user': 104837,
+        'single-session-assistant': 55252,
+        'single-session-preference': 58373,
+        'knowledge-update': 82807,
+        'multi-session': 131188,
+        'temporal-reasoning': 100881,
+    }),
+});
+/**
+ * observational-memory-v10: synthesized observation log + classifier-driven
+ * dispatch inside the OM pipeline (no verbatim citation). Phase B measured
+ * 74.6% [70.8, 78.4] aggregate at $0.3265/correct, 12s avg latency.
+ */
+export const TIER_2A_V10_COSTS = Object.freeze({
+    backend: 'observational-memory-v10',
+    avgCostPerQuery: 0.2436,
+    perCategoryAccuracy: Object.freeze({
+        'single-session-user': 0.971,
+        'single-session-assistant': 0.839,
+        'single-session-preference': 0.600,
+        'knowledge-update': 0.859,
+        'multi-session': 0.602,
+        'temporal-reasoning': 0.710,
+    }),
+    perCategoryCostPerQuery: Object.freeze({
+        'single-session-user': 0.0214,
+        'single-session-assistant': 0.0195,
+        'single-session-preference': 0.0206,
+        'knowledge-update': 0.0306,
+        'multi-session': 0.0308,
+        'temporal-reasoning': 0.0206,
+    }),
+    perCategoryLatencyMs: Object.freeze({
+        'single-session-user': 7649,
+        'single-session-assistant': 5668,
+        'single-session-preference': 4469,
+        'knowledge-update': 19569,
+        'multi-session': 21360,
+        'temporal-reasoning': 4236,
+    }),
+});
+/**
+ * observational-memory-v11: v10 + conditional verbatim citation rule for
+ * knowledge-update and single-session-user categories. Phase B measured
+ * 75.4% [71.6, 79.0] aggregate at $0.4362/correct, 14s avg latency.
+ */
+export const TIER_2B_V11_COSTS = Object.freeze({
+    backend: 'observational-memory-v11',
+    avgCostPerQuery: 0.3289,
+    perCategoryAccuracy: Object.freeze({
+        'single-session-user': 0.986,
+        'single-session-assistant': 0.839,
+        'single-session-preference': 0.633,
+        'knowledge-update': 0.872,
+        'multi-session': 0.617,
+        'temporal-reasoning': 0.692,
+    }),
+    perCategoryCostPerQuery: Object.freeze({
+        'single-session-user': 0.0212,
+        'single-session-assistant': 0.0192,
+        'single-session-preference': 0.0206,
+        'knowledge-update': 0.0307,
+        'multi-session': 0.0336,
+        'temporal-reasoning': 0.0209,
+    }),
+    perCategoryLatencyMs: Object.freeze({
+        'single-session-user': 6676,
+        'single-session-assistant': 6879,
+        'single-session-preference': 8822,
+        'knowledge-update': 21085,
+        'multi-session': 27423,
+        'temporal-reasoning': 5025,
+    }),
+});
+/**
+ * Default cost-points registry. Indexed by {@link MemoryBackendId} so the
+ * router can look up the picked backend's cost on any category.
+ *
+ * Custom deployments can substitute their own cost-points by passing a
+ * different `backendCosts` map into the {@link MemoryRouter} config —
+ * useful when a workload diverges from the LongMemEval-S Phase B
+ * distribution and the calibrator wants to plug in measurements from
+ * their own benchmark.
+ */
+export const DEFAULT_MEMORY_BACKEND_COSTS = Object.freeze({
+    'canonical-hybrid': TIER_1_CANONICAL_COSTS,
+    'observational-memory-v10': TIER_2A_V10_COSTS,
+    'observational-memory-v11': TIER_2B_V11_COSTS,
+});
+//# sourceMappingURL=backend-costs.js.map

package/dist/memory-router/backend-costs.js.map

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