@framers/agentos 0.2.5 → 0.2.7

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

@@ -0,0 +1,124 @@
+/**
+ * AgentOS MemoryRouter Module
+ *
+ * LLM-as-judge orchestrator that picks the best memory-recall architecture
+ * per query, with budget-aware dispatch across {canonical-hybrid,
+ * observational-memory-v10, observational-memory-v11} backends.
+ *
+ * **Architecture Overview:**
+ * ```
+ * ┌────────────────────────────────────────────────────────────────────┐
+ * │                          MemoryRouter                              │
+ * │   Orchestrates classification + routing-table dispatch + optional  │
+ * │   backend execution (via IMemoryDispatcher)                        │
+ * └────────────────────────────────────────────────────────────────────┘
+ *                                │
+ *         ┌──────────────────────┼────────────────────────┐
+ *         ▼                      ▼                        ▼
+ *  ┌───────────────┐    ┌─────────────────┐    ┌───────────────────┐
+ *  │ IMemoryClassi-│    │ selectBackend   │    │ IMemoryDispatcher │
+ *  │ fier          │    │ (pure, budget-  │    │ (optional exec)   │
+ *  │ (LLM judge)   │    │  aware)         │    │                   │
+ *  └───────────────┘    └─────────────────┘    └───────────────────┘
+ *                                │
+ *          ┌─────────────────────┼─────────────────────┐
+ *          ▼                     ▼                     ▼
+ * ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────────┐
+ * │ canonical-      │  │ observational-  │  │ observational-      │
+ * │ hybrid          │  │ memory-v10      │  │ memory-v11          │
+ * │ (BM25 + dense   │  │ (synth obs log  │  │ (v10 + verbatim     │
+ * │  + Cohere       │  │  + dyn router)  │  │  citation for       │
+ * │  rerank)        │  │                 │  │  KU/SSU)            │
+ * └─────────────────┘  └─────────────────┘  └─────────────────────┘
+ * ```
+ *
+ * **Design principles:**
+ *
+ * 1. **Pure where possible.** `selectBackend` is a pure function: given a
+ *    category + routing table + cost data, it produces a deterministic
+ *    decision with no I/O. Suitable for use inside cache-key construction
+ *    and hot dispatch loops.
+ *
+ * 2. **LLM-provider-agnostic.** The classifier talks to an adapter interface
+ *    ({@link IMemoryClassifierLLM}) — there is NO SDK import inside this
+ *    module. Wire any provider (OpenAI, Anthropic, local, mock) via the
+ *    adapter.
+ *
+ * 3. **Dispatch is injected.** Backend execution depends on how the caller's
+ *    memory state is wired (OM backends need ingest-time setup, canonical
+ *    does not). The router decides; {@link IMemoryDispatcher} executes.
+ *    Callers who only need canonical-hybrid can register one executor and
+ *    ignore the others.
+ *
+ * 4. **Shipping presets.** Three routing tables (minimize-cost, balanced,
+ *    maximize-accuracy) ship with costs calibrated from LongMemEval-S
+ *    Phase B N=500. Consumers can override routing tables, cost-points, or
+ *    per-category mappings for custom workloads.
+ *
+ * 5. **Budget-aware.** Optional per-query USD budget with three modes
+ *    (hard / soft / cheapest-fallback) so production cost ceilings are
+ *    enforceable without bespoke retry logic.
+ *
+ * @module @framers/agentos/memory-router
+ *
+ * @example Minimal usage: just decide, execute yourself.
+ * ```ts
+ * import {
+ *   LLMMemoryClassifier,
+ *   MemoryRouter,
+ * } from '../memory-router';
+ *
+ * const router = new MemoryRouter({
+ *   classifier: new LLMMemoryClassifier({ llm: openaiAdapter }),
+ *   preset: 'minimize-cost',
+ * });
+ *
+ * const { classifier, routing } = await router.decide(query);
+ * if (routing.chosenBackend === 'canonical-hybrid') {
+ *   const traces = await mem.recall(query, { limit: 10 });
+ *   // ...
+ * }
+ * ```
+ *
+ * @example Full pipeline: decide + dispatch.
+ * ```ts
+ * import {
+ *   LLMMemoryClassifier,
+ *   MemoryRouter,
+ *   FunctionMemoryDispatcher,
+ * } from '../memory-router';
+ *
+ * const router = new MemoryRouter({
+ *   classifier: new LLMMemoryClassifier({ llm: openaiAdapter }),
+ *   preset: 'minimize-cost',
+ *   budget: { perQueryUsd: 0.05, mode: 'cheapest-fallback' },
+ *   dispatcher: new FunctionMemoryDispatcher<ScoredTrace, { topK: number }>({
+ *     'canonical-hybrid': async (q, { topK }) =>
+ *       mem.recall(q, { limit: topK }),
+ *     'observational-memory-v10': async (q, p) =>
+ *       await omPipelineV10.recall(q, p),
+ *     'observational-memory-v11': async (q, p) =>
+ *       await omPipelineV11.recall(q, p),
+ *   }),
+ * });
+ *
+ * const { decision, traces, backend } = await router.decideAndDispatch(
+ *   query,
+ *   { topK: 10 },
+ * );
+ * ```
+ */
+export type { MemoryQueryCategory, MemoryBackendId, MemoryRouterPreset, RoutingTable, } from './routing-tables.js';
+export { MEMORY_QUERY_CATEGORIES } from './routing-tables.js';
+export type { MemoryBackendCostPoint } from './backend-costs.js';
+export type { MemoryBudgetMode, MemoryRouterConfig, MemoryRoutingDecision, } from './select-backend.js';
+export type { IMemoryClassifier, IMemoryClassifierLLM, MemoryClassifierLLMRequest, MemoryClassifierLLMResponse, MemoryClassifierClassifyOptions, MemoryClassifierResult, LLMMemoryClassifierOptions, } from './classifier.js';
+export type { IMemoryDispatcher, MemoryDispatchArgs, MemoryDispatchResult, MemoryBackendExecutor, MemoryBackendRegistry, } from './dispatcher.js';
+export type { MemoryBudgetPolicy, MemoryRouterOptions, MemoryRouterDecideOptions, MemoryRouterDecision, MemoryRouterDispatchedDecision, } from './MemoryRouter.js';
+export { MINIMIZE_COST_TABLE, BALANCED_TABLE, MAXIMIZE_ACCURACY_TABLE, PRESET_TABLES, } from './routing-tables.js';
+export { TIER_1_CANONICAL_COSTS, TIER_2A_V10_COSTS, TIER_2B_V11_COSTS, DEFAULT_MEMORY_BACKEND_COSTS, } from './backend-costs.js';
+export { selectBackend, MemoryRouterUnknownCategoryError, MemoryRouterBudgetExceededError, } from './select-backend.js';
+export { CLASSIFIER_SYSTEM_PROMPT, CLASSIFIER_SYSTEM_PROMPT_FEWSHOT, SAFE_FALLBACK_CATEGORY, LLMMemoryClassifier, normalizeClassifierOutput, parseClassifierOutput, } from './classifier.js';
+export { FunctionMemoryDispatcher, UnsupportedMemoryBackendError, } from './dispatcher.js';
+export { MemoryRouter, MemoryRouterDispatcherMissingError, } from './MemoryRouter.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/memory-router/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6GG;AAMH,YAAY,EACV,mBAAmB,EACnB,eAAe,EACf,kBAAkB,EAClB,YAAY,GACb,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,uBAAuB,EAAE,MAAM,qBAAqB,CAAC;AAE9D,YAAY,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AAEjE,YAAY,EACV,gBAAgB,EAChB,kBAAkB,EAClB,qBAAqB,GACtB,MAAM,qBAAqB,CAAC;AAE7B,YAAY,EACV,iBAAiB,EACjB,oBAAoB,EACpB,0BAA0B,EAC1B,2BAA2B,EAC3B,+BAA+B,EAC/B,sBAAsB,EACtB,0BAA0B,GAC3B,MAAM,iBAAiB,CAAC;AAEzB,YAAY,EACV,iBAAiB,EACjB,kBAAkB,EAClB,oBAAoB,EACpB,qBAAqB,EACrB,qBAAqB,GACtB,MAAM,iBAAiB,CAAC;AAEzB,YAAY,EACV,kBAAkB,EAClB,mBAAmB,EACnB,yBAAyB,EACzB,oBAAoB,EACpB,8BAA8B,GAC/B,MAAM,mBAAmB,CAAC;AAM3B,OAAO,EACL,mBAAmB,EACnB,cAAc,EACd,uBAAuB,EACvB,aAAa,GACd,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,sBAAsB,EACtB,iBAAiB,EACjB,iBAAiB,EACjB,4BAA4B,GAC7B,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACL,aAAa,EACb,gCAAgC,EAChC,+BAA+B,GAChC,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,wBAAwB,EACxB,gCAAgC,EAChC,sBAAsB,EACtB,mBAAmB,EACnB,yBAAyB,EACzB,qBAAqB,GACtB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EACL,wBAAwB,EACxB,6BAA6B,GAC9B,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EACL,YAAY,EACZ,kCAAkC,GACnC,MAAM,mBAAmB,CAAC"}

package/dist/memory-router/index.js

@@ -0,0 +1,121 @@
+/**
+ * AgentOS MemoryRouter Module
+ *
+ * LLM-as-judge orchestrator that picks the best memory-recall architecture
+ * per query, with budget-aware dispatch across {canonical-hybrid,
+ * observational-memory-v10, observational-memory-v11} backends.
+ *
+ * **Architecture Overview:**
+ * ```
+ * ┌────────────────────────────────────────────────────────────────────┐
+ * │                          MemoryRouter                              │
+ * │   Orchestrates classification + routing-table dispatch + optional  │
+ * │   backend execution (via IMemoryDispatcher)                        │
+ * └────────────────────────────────────────────────────────────────────┘
+ *                                │
+ *         ┌──────────────────────┼────────────────────────┐
+ *         ▼                      ▼                        ▼
+ *  ┌───────────────┐    ┌─────────────────┐    ┌───────────────────┐
+ *  │ IMemoryClassi-│    │ selectBackend   │    │ IMemoryDispatcher │
+ *  │ fier          │    │ (pure, budget-  │    │ (optional exec)   │
+ *  │ (LLM judge)   │    │  aware)         │    │                   │
+ *  └───────────────┘    └─────────────────┘    └───────────────────┘
+ *                                │
+ *          ┌─────────────────────┼─────────────────────┐
+ *          ▼                     ▼                     ▼
+ * ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────────┐
+ * │ canonical-      │  │ observational-  │  │ observational-      │
+ * │ hybrid          │  │ memory-v10      │  │ memory-v11          │
+ * │ (BM25 + dense   │  │ (synth obs log  │  │ (v10 + verbatim     │
+ * │  + Cohere       │  │  + dyn router)  │  │  citation for       │
+ * │  rerank)        │  │                 │  │  KU/SSU)            │
+ * └─────────────────┘  └─────────────────┘  └─────────────────────┘
+ * ```
+ *
+ * **Design principles:**
+ *
+ * 1. **Pure where possible.** `selectBackend` is a pure function: given a
+ *    category + routing table + cost data, it produces a deterministic
+ *    decision with no I/O. Suitable for use inside cache-key construction
+ *    and hot dispatch loops.
+ *
+ * 2. **LLM-provider-agnostic.** The classifier talks to an adapter interface
+ *    ({@link IMemoryClassifierLLM}) — there is NO SDK import inside this
+ *    module. Wire any provider (OpenAI, Anthropic, local, mock) via the
+ *    adapter.
+ *
+ * 3. **Dispatch is injected.** Backend execution depends on how the caller's
+ *    memory state is wired (OM backends need ingest-time setup, canonical
+ *    does not). The router decides; {@link IMemoryDispatcher} executes.
+ *    Callers who only need canonical-hybrid can register one executor and
+ *    ignore the others.
+ *
+ * 4. **Shipping presets.** Three routing tables (minimize-cost, balanced,
+ *    maximize-accuracy) ship with costs calibrated from LongMemEval-S
+ *    Phase B N=500. Consumers can override routing tables, cost-points, or
+ *    per-category mappings for custom workloads.
+ *
+ * 5. **Budget-aware.** Optional per-query USD budget with three modes
+ *    (hard / soft / cheapest-fallback) so production cost ceilings are
+ *    enforceable without bespoke retry logic.
+ *
+ * @module @framers/agentos/memory-router
+ *
+ * @example Minimal usage: just decide, execute yourself.
+ * ```ts
+ * import {
+ *   LLMMemoryClassifier,
+ *   MemoryRouter,
+ * } from '../memory-router';
+ *
+ * const router = new MemoryRouter({
+ *   classifier: new LLMMemoryClassifier({ llm: openaiAdapter }),
+ *   preset: 'minimize-cost',
+ * });
+ *
+ * const { classifier, routing } = await router.decide(query);
+ * if (routing.chosenBackend === 'canonical-hybrid') {
+ *   const traces = await mem.recall(query, { limit: 10 });
+ *   // ...
+ * }
+ * ```
+ *
+ * @example Full pipeline: decide + dispatch.
+ * ```ts
+ * import {
+ *   LLMMemoryClassifier,
+ *   MemoryRouter,
+ *   FunctionMemoryDispatcher,
+ * } from '../memory-router';
+ *
+ * const router = new MemoryRouter({
+ *   classifier: new LLMMemoryClassifier({ llm: openaiAdapter }),
+ *   preset: 'minimize-cost',
+ *   budget: { perQueryUsd: 0.05, mode: 'cheapest-fallback' },
+ *   dispatcher: new FunctionMemoryDispatcher<ScoredTrace, { topK: number }>({
+ *     'canonical-hybrid': async (q, { topK }) =>
+ *       mem.recall(q, { limit: topK }),
+ *     'observational-memory-v10': async (q, p) =>
+ *       await omPipelineV10.recall(q, p),
+ *     'observational-memory-v11': async (q, p) =>
+ *       await omPipelineV11.recall(q, p),
+ *   }),
+ * });
+ *
+ * const { decision, traces, backend } = await router.decideAndDispatch(
+ *   query,
+ *   { topK: 10 },
+ * );
+ * ```
+ */
+export { MEMORY_QUERY_CATEGORIES } from './routing-tables.js';
+// ============================================================================
+// Values
+// ============================================================================
+export { MINIMIZE_COST_TABLE, BALANCED_TABLE, MAXIMIZE_ACCURACY_TABLE, PRESET_TABLES, } from './routing-tables.js';
+export { TIER_1_CANONICAL_COSTS, TIER_2A_V10_COSTS, TIER_2B_V11_COSTS, DEFAULT_MEMORY_BACKEND_COSTS, } from './backend-costs.js';
+export { selectBackend, MemoryRouterUnknownCategoryError, MemoryRouterBudgetExceededError, } from './select-backend.js';
+export { CLASSIFIER_SYSTEM_PROMPT, CLASSIFIER_SYSTEM_PROMPT_FEWSHOT, SAFE_FALLBACK_CATEGORY, LLMMemoryClassifier, normalizeClassifierOutput, parseClassifierOutput, } from './classifier.js';
+export { FunctionMemoryDispatcher, UnsupportedMemoryBackendError, } from './dispatcher.js';
+export { MemoryRouter, MemoryRouterDispatcherMissingError, } from './MemoryRouter.js';
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/memory-router/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6GG;AAYH,OAAO,EAAE,uBAAuB,EAAE,MAAM,qBAAqB,CAAC;AAoC9D,+EAA+E;AAC/E,SAAS;AACT,+EAA+E;AAE/E,OAAO,EACL,mBAAmB,EACnB,cAAc,EACd,uBAAuB,EACvB,aAAa,GACd,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,sBAAsB,EACtB,iBAAiB,EACjB,iBAAiB,EACjB,4BAA4B,GAC7B,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACL,aAAa,EACb,gCAAgC,EAChC,+BAA+B,GAChC,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,wBAAwB,EACxB,gCAAgC,EAChC,sBAAsB,EACtB,mBAAmB,EACnB,yBAAyB,EACzB,qBAAqB,GACtB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EACL,wBAAwB,EACxB,6BAA6B,GAC9B,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EACL,YAAY,EACZ,kCAAkC,GACnC,MAAM,mBAAmB,CAAC"}

package/dist/memory-router/routing-tables.d.ts

@@ -0,0 +1,125 @@
+/**
+ * @file routing-tables.ts
+ * @description Preset routing tables for {@link MemoryRouter}.
+ *
+ * The MemoryRouter dispatches each query to one of the available
+ * {@link MemoryBackendId} backends based on the classifier-predicted
+ * {@link MemoryQueryCategory}. The mapping from category to backend is a
+ * "routing table" — a frozen object that callers can pass through unchanged
+ * for the shipping defaults, or override per-category for custom workloads.
+ *
+ * Three preset tables ship out of the box, each calibrated from Phase B
+ * N=500 LongMemEval-S measurements:
+ *
+ * - {@link MINIMIZE_COST_TABLE}: cheapest Pareto-dominant backend per
+ *   category. Pays the OM premium only on multi-session and
+ *   single-session-preference (the categories where the architectural lift
+ *   exceeds the cost premium).
+ * - {@link BALANCED_TABLE}: trades modest cost for large latency wins on
+ *   knowledge-update and temporal-reasoning.
+ * - {@link MAXIMIZE_ACCURACY_TABLE}: highest-accuracy backend per category;
+ *   ties broken by cost. v2 (post-Phase-B-2026-04-24) routes
+ *   temporal-reasoning back to canonical-hybrid after Phase B revealed the
+ *   v1 routing's accuracy gain was within CI noise but paid OM ingest cost.
+ *
+ * @module @framers/agentos/memory-router/routing-tables
+ */
+/**
+ * The six question categories the LLM-as-judge classifier produces.
+ * Calibrated from LongMemEval-S categories; mappings to other benchmark
+ * taxonomies (e.g. LOCOMO single-hop / multi-hop / temporal /
+ * open-domain / adversarial) are handled at adapter boundaries.
+ */
+export declare const MEMORY_QUERY_CATEGORIES: readonly ["single-session-user", "single-session-assistant", "single-session-preference", "knowledge-update", "multi-session", "temporal-reasoning"];
+/**
+ * The six question categories the LLM-as-judge classifier produces.
+ */
+export type MemoryQueryCategory = (typeof MEMORY_QUERY_CATEGORIES)[number];
+/**
+ * The retrieval architecture identifiers the router can dispatch to.
+ *
+ * - `canonical-hybrid`: BM25 + dense + RRF fusion + Cohere rerank-v3.5
+ *   over the raw memory traces. The default cheapest-and-fastest path.
+ * - `observational-memory-v10`: synthesized observation log fed to the
+ *   reader, with classifier-driven routing inside the OM pipeline. No
+ *   verbatim citation rule.
+ * - `observational-memory-v11`: same as v10 but with conditional
+ *   verbatim citation appended for knowledge-update and
+ *   single-session-user categories. Wins on multi-session and
+ *   single-session-preference.
+ *
+ * Backend execution itself lives in {@link MemoryDispatcher}; this type
+ * is the contract between the routing decision and the dispatcher.
+ */
+export type MemoryBackendId = 'canonical-hybrid' | 'observational-memory-v10' | 'observational-memory-v11';
+/**
+ * The three shipping presets. Each preset corresponds to a distinct point
+ * on the Phase B-measured cost-accuracy Pareto frontier.
+ */
+export type MemoryRouterPreset = 'minimize-cost' | 'balanced' | 'maximize-accuracy';
+/**
+ * A routing table maps every {@link MemoryQueryCategory} to its preferred
+ * {@link MemoryBackendId} for the given preset. Tables ship frozen so
+ * consumers cannot mutate the routing surface from outside the module.
+ */
+export interface RoutingTable {
+    readonly preset: MemoryRouterPreset;
+    readonly defaultMapping: Readonly<Record<MemoryQueryCategory, MemoryBackendId>>;
+}
+/**
+ * Preset: minimize-cost.
+ *
+ * Pareto-dominant cheapest backend per category. Pays the OM premium only
+ * on the two categories where the architectural lift earns it
+ * (multi-session +6.8pp, single-session-preference +3.3pp). Every other
+ * category routes to canonical-hybrid where Phase B measurements show the
+ * cheaper backend either dominates or matches within CI noise.
+ *
+ * Phase B simulation: 73.9% accuracy at $0.092/correct; oracle ceiling
+ * 76.0% at $0.157/correct. **Pareto-dominates the all-Tier-2b flat
+ * baseline by 4.77x cost reduction at +0.5pp accuracy** on the
+ * LongMemEval-S Phase B distribution.
+ *
+ * Recommended default for cost-sensitive workloads.
+ */
+export declare const MINIMIZE_COST_TABLE: RoutingTable;
+/**
+ * Preset: balanced.
+ *
+ * Trades 1.6x cost for >10x latency reductions on knowledge-update and
+ * temporal-reasoning. Phase B measurements show Tier 2a v10 ties Tier 1
+ * canonical on accuracy for these two categories at much lower latency
+ * (4-19s vs 80-100s) — the latency win comes from skipping per-turn
+ * cognitive replay in favor of synthesized observations.
+ *
+ * Phase B simulation: 74.5% accuracy at $0.205/correct; 2.12x cheaper
+ * than Tier 2b flat with comparable accuracy.
+ *
+ * Recommended for interactive workloads where latency matters and the
+ * cost premium over minimize-cost is acceptable.
+ */
+export declare const BALANCED_TABLE: RoutingTable;
+/**
+ * Preset: maximize-accuracy (v2).
+ *
+ * Highest-accuracy backend per category, ties broken by cost. v2
+ * (2026-04-24, post-Phase-B) routes temporal-reasoning back to
+ * canonical-hybrid after Phase B revealed:
+ *   - v1 routing (TR -> Tier 2a) paid OM ingest cost for a within-CI
+ *     accuracy gain (71.0% Tier 2a vs 70.2% Tier 1) on a hold-out slice;
+ *   - combined with classifier misroutes the aggregate fell below the
+ *     74% acceptance floor at 73.8%.
+ * v2 keeps TR on canonical-hybrid where it's cheapest and
+ * accuracy-equivalent.
+ *
+ * Phase B measured: 75.6% [71.8, 79.2] at $0.2434/correct, 65.6s avg
+ * latency.
+ */
+export declare const MAXIMIZE_ACCURACY_TABLE: RoutingTable;
+/**
+ * Convenience registry of all three preset tables, keyed by preset name.
+ * Useful when surfacing presets through a CLI flag or config field where
+ * the preset name is a string and the consumer needs the table object.
+ */
+export declare const PRESET_TABLES: Readonly<Record<MemoryRouterPreset, RoutingTable>>;
+//# sourceMappingURL=routing-tables.d.ts.map

package/dist/memory-router/routing-tables.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"routing-tables.d.ts","sourceRoot":"","sources":["../../src/memory-router/routing-tables.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAMH;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,sJAO1B,CAAC;AAEX;;GAEG;AACH,MAAM,MAAM,mBAAmB,GAAG,CAAC,OAAO,uBAAuB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE3E;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,eAAe,GACvB,kBAAkB,GAClB,0BAA0B,GAC1B,0BAA0B,CAAC;AAE/B;;;GAGG;AACH,MAAM,MAAM,kBAAkB,GAC1B,eAAe,GACf,UAAU,GACV,mBAAmB,CAAC;AAExB;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,MAAM,EAAE,kBAAkB,CAAC;IACpC,QAAQ,CAAC,cAAc,EAAE,QAAQ,CAAC,MAAM,CAAC,mBAAmB,EAAE,eAAe,CAAC,CAAC,CAAC;CACjF;AAMD;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,mBAAmB,EAAE,YAUhB,CAAC;AAEnB;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,cAAc,EAAE,YAUX,CAAC;AAEnB;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,uBAAuB,EAAE,YAUpB,CAAC;AAEnB;;;;GAIG;AACH,eAAO,MAAM,aAAa,EAAE,QAAQ,CAAC,MAAM,CAAC,kBAAkB,EAAE,YAAY,CAAC,CAKzE,CAAC"}

package/dist/memory-router/routing-tables.js

@@ -0,0 +1,137 @@
+/**
+ * @file routing-tables.ts
+ * @description Preset routing tables for {@link MemoryRouter}.
+ *
+ * The MemoryRouter dispatches each query to one of the available
+ * {@link MemoryBackendId} backends based on the classifier-predicted
+ * {@link MemoryQueryCategory}. The mapping from category to backend is a
+ * "routing table" — a frozen object that callers can pass through unchanged
+ * for the shipping defaults, or override per-category for custom workloads.
+ *
+ * Three preset tables ship out of the box, each calibrated from Phase B
+ * N=500 LongMemEval-S measurements:
+ *
+ * - {@link MINIMIZE_COST_TABLE}: cheapest Pareto-dominant backend per
+ *   category. Pays the OM premium only on multi-session and
+ *   single-session-preference (the categories where the architectural lift
+ *   exceeds the cost premium).
+ * - {@link BALANCED_TABLE}: trades modest cost for large latency wins on
+ *   knowledge-update and temporal-reasoning.
+ * - {@link MAXIMIZE_ACCURACY_TABLE}: highest-accuracy backend per category;
+ *   ties broken by cost. v2 (post-Phase-B-2026-04-24) routes
+ *   temporal-reasoning back to canonical-hybrid after Phase B revealed the
+ *   v1 routing's accuracy gain was within CI noise but paid OM ingest cost.
+ *
+ * @module @framers/agentos/memory-router/routing-tables
+ */
+// ============================================================================
+// Public types
+// ============================================================================
+/**
+ * The six question categories the LLM-as-judge classifier produces.
+ * Calibrated from LongMemEval-S categories; mappings to other benchmark
+ * taxonomies (e.g. LOCOMO single-hop / multi-hop / temporal /
+ * open-domain / adversarial) are handled at adapter boundaries.
+ */
+export const MEMORY_QUERY_CATEGORIES = [
+    'single-session-user',
+    'single-session-assistant',
+    'single-session-preference',
+    'knowledge-update',
+    'multi-session',
+    'temporal-reasoning',
+];
+// ============================================================================
+// Preset tables
+// ============================================================================
+/**
+ * Preset: minimize-cost.
+ *
+ * Pareto-dominant cheapest backend per category. Pays the OM premium only
+ * on the two categories where the architectural lift earns it
+ * (multi-session +6.8pp, single-session-preference +3.3pp). Every other
+ * category routes to canonical-hybrid where Phase B measurements show the
+ * cheaper backend either dominates or matches within CI noise.
+ *
+ * Phase B simulation: 73.9% accuracy at $0.092/correct; oracle ceiling
+ * 76.0% at $0.157/correct. **Pareto-dominates the all-Tier-2b flat
+ * baseline by 4.77x cost reduction at +0.5pp accuracy** on the
+ * LongMemEval-S Phase B distribution.
+ *
+ * Recommended default for cost-sensitive workloads.
+ */
+export const MINIMIZE_COST_TABLE = Object.freeze({
+    preset: 'minimize-cost',
+    defaultMapping: Object.freeze({
+        'single-session-assistant': 'canonical-hybrid',
+        'single-session-user': 'canonical-hybrid',
+        'temporal-reasoning': 'canonical-hybrid',
+        'knowledge-update': 'canonical-hybrid',
+        'multi-session': 'observational-memory-v11',
+        'single-session-preference': 'observational-memory-v11',
+    }),
+});
+/**
+ * Preset: balanced.
+ *
+ * Trades 1.6x cost for >10x latency reductions on knowledge-update and
+ * temporal-reasoning. Phase B measurements show Tier 2a v10 ties Tier 1
+ * canonical on accuracy for these two categories at much lower latency
+ * (4-19s vs 80-100s) — the latency win comes from skipping per-turn
+ * cognitive replay in favor of synthesized observations.
+ *
+ * Phase B simulation: 74.5% accuracy at $0.205/correct; 2.12x cheaper
+ * than Tier 2b flat with comparable accuracy.
+ *
+ * Recommended for interactive workloads where latency matters and the
+ * cost premium over minimize-cost is acceptable.
+ */
+export const BALANCED_TABLE = Object.freeze({
+    preset: 'balanced',
+    defaultMapping: Object.freeze({
+        'single-session-assistant': 'canonical-hybrid',
+        'single-session-user': 'canonical-hybrid',
+        'temporal-reasoning': 'observational-memory-v10',
+        'knowledge-update': 'observational-memory-v10',
+        'multi-session': 'observational-memory-v11',
+        'single-session-preference': 'observational-memory-v11',
+    }),
+});
+/**
+ * Preset: maximize-accuracy (v2).
+ *
+ * Highest-accuracy backend per category, ties broken by cost. v2
+ * (2026-04-24, post-Phase-B) routes temporal-reasoning back to
+ * canonical-hybrid after Phase B revealed:
+ *   - v1 routing (TR -> Tier 2a) paid OM ingest cost for a within-CI
+ *     accuracy gain (71.0% Tier 2a vs 70.2% Tier 1) on a hold-out slice;
+ *   - combined with classifier misroutes the aggregate fell below the
+ *     74% acceptance floor at 73.8%.
+ * v2 keeps TR on canonical-hybrid where it's cheapest and
+ * accuracy-equivalent.
+ *
+ * Phase B measured: 75.6% [71.8, 79.2] at $0.2434/correct, 65.6s avg
+ * latency.
+ */
+export const MAXIMIZE_ACCURACY_TABLE = Object.freeze({
+    preset: 'maximize-accuracy',
+    defaultMapping: Object.freeze({
+        'single-session-assistant': 'canonical-hybrid',
+        'single-session-user': 'observational-memory-v11',
+        'temporal-reasoning': 'canonical-hybrid',
+        'knowledge-update': 'observational-memory-v11',
+        'multi-session': 'observational-memory-v11',
+        'single-session-preference': 'observational-memory-v11',
+    }),
+});
+/**
+ * Convenience registry of all three preset tables, keyed by preset name.
+ * Useful when surfacing presets through a CLI flag or config field where
+ * the preset name is a string and the consumer needs the table object.
+ */
+export const PRESET_TABLES = Object.freeze({
+    'minimize-cost': MINIMIZE_COST_TABLE,
+    'balanced': BALANCED_TABLE,
+    'maximize-accuracy': MAXIMIZE_ACCURACY_TABLE,
+});
+//# sourceMappingURL=routing-tables.js.map

package/dist/memory-router/routing-tables.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"routing-tables.js","sourceRoot":"","sources":["../../src/memory-router/routing-tables.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,+EAA+E;AAC/E,eAAe;AACf,+EAA+E;AAE/E;;;;;GAKG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG;IACrC,qBAAqB;IACrB,0BAA0B;IAC1B,2BAA2B;IAC3B,kBAAkB;IAClB,eAAe;IACf,oBAAoB;CACZ,CAAC;AA+CX,+EAA+E;AAC/E,gBAAgB;AAChB,+EAA+E;AAE/E;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAiB,MAAM,CAAC,MAAM,CAAC;IAC7D,MAAM,EAAE,eAAwB;IAChC,cAAc,EAAE,MAAM,CAAC,MAAM,CAAC;QAC5B,0BAA0B,EAAE,kBAAkB;QAC9C,qBAAqB,EAAE,kBAAkB;QACzC,oBAAoB,EAAE,kBAAkB;QACxC,kBAAkB,EAAE,kBAAkB;QACtC,eAAe,EAAE,0BAA0B;QAC3C,2BAA2B,EAAE,0BAA0B;KACxD,CAAC;CACH,CAAiB,CAAC;AAEnB;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,MAAM,cAAc,GAAiB,MAAM,CAAC,MAAM,CAAC;IACxD,MAAM,EAAE,UAAmB;IAC3B,cAAc,EAAE,MAAM,CAAC,MAAM,CAAC;QAC5B,0BAA0B,EAAE,kBAAkB;QAC9C,qBAAqB,EAAE,kBAAkB;QACzC,oBAAoB,EAAE,0BAA0B;QAChD,kBAAkB,EAAE,0BAA0B;QAC9C,eAAe,EAAE,0BAA0B;QAC3C,2BAA2B,EAAE,0BAA0B;KACxD,CAAC;CACH,CAAiB,CAAC;AAEnB;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAiB,MAAM,CAAC,MAAM,CAAC;IACjE,MAAM,EAAE,mBAA4B;IACpC,cAAc,EAAE,MAAM,CAAC,MAAM,CAAC;QAC5B,0BAA0B,EAAE,kBAAkB;QAC9C,qBAAqB,EAAE,0BAA0B;QACjD,oBAAoB,EAAE,kBAAkB;QACxC,kBAAkB,EAAE,0BAA0B;QAC9C,eAAe,EAAE,0BAA0B;QAC3C,2BAA2B,EAAE,0BAA0B;KACxD,CAAC;CACH,CAAiB,CAAC;AAEnB;;;;GAIG;AACH,MAAM,CAAC,MAAM,aAAa,GACxB,MAAM,CAAC,MAAM,CAAC;IACZ,eAAe,EAAE,mBAAmB;IACpC,UAAU,EAAE,cAAc;IAC1B,mBAAmB,EAAE,uBAAuB;CAC7C,CAAC,CAAC"}

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

@@ -0,0 +1,136 @@
+/**
+ * @file select-backend.ts
+ * @description Pure function that turns a classifier-predicted category
+ * + a {@link MemoryRouterConfig} into a {@link MemoryRoutingDecision}.
+ *
+ * Stateless. Deterministic. No I/O. Suitable for use inside hot dispatch
+ * loops and inside cache-key construction (the function's output is a
+ * pure function of its inputs).
+ *
+ * The decision carries:
+ *   - the chosen {@link MemoryBackendId},
+ *   - the predicted category (and optional ground-truth for telemetry),
+ *   - the estimated USD cost of the routing pick,
+ *   - the budget ceiling (if any) and whether the pick exceeded it,
+ *   - a human-readable reason explaining the routing path taken.
+ *
+ * @module @framers/agentos/memory-router/select-backend
+ */
+import type { MemoryBackendCostPoint } from './backend-costs.js';
+import type { MemoryBackendId, MemoryQueryCategory, MemoryRouterPreset, RoutingTable } from './routing-tables.js';
+/**
+ * Budget enforcement modes:
+ *   - `hard`: throw {@link MemoryRouterBudgetExceededError} if the
+ *     routing-table pick exceeds the per-query USD budget. Lets callers
+ *     escalate at the application layer (e.g. fall back to a reduced
+ *     pipeline or surface a 402-style error).
+ *   - `soft`: exceed the budget only when the picked backend has a
+ *     better USD-per-correct ratio than the cheapest backend that fits.
+ *     Prefers accuracy-economical overflows.
+ *   - `cheapest-fallback`: silently downgrade to the cheapest backend
+ *     that fits the budget. Suitable for cost-strict workloads where
+ *     correctness gracefully degrades.
+ */
+export type MemoryBudgetMode = 'hard' | 'soft' | 'cheapest-fallback';
+/**
+ * Configuration object for {@link selectBackend}. Bundles the routing
+ * table, cost data, and budget policy into a single value the function
+ * can reason about deterministically.
+ */
+export interface MemoryRouterConfig {
+    readonly table: RoutingTable;
+    readonly budgetPerQuery: number | null;
+    readonly budgetMode: MemoryBudgetMode;
+    readonly backendCosts: Readonly<Record<MemoryBackendId, MemoryBackendCostPoint>>;
+}
+/**
+ * Output of {@link selectBackend}. The chosen backend plus full telemetry
+ * about how the routing decision was made.
+ */
+export interface MemoryRoutingDecision {
+    readonly predictedCategory: MemoryQueryCategory;
+    /**
+     * Optional ground-truth category, for telemetry only. When the caller
+     * has access to gold labels (e.g. during benchmarking), passing them
+     * through here lets downstream analysis distinguish classifier
+     * misroutes from architectural misses without needing a second pass.
+     */
+    readonly groundTruthCategory: MemoryQueryCategory | null;
+    readonly chosenBackend: MemoryBackendId;
+    readonly chosenBackendReason: string;
+    readonly estimatedCostUsd: number;
+    readonly budgetCeiling: number | null;
+    readonly budgetExceeded: boolean;
+    readonly preset: MemoryRouterPreset;
+}
+/**
+ * Thrown when the predicted category is not in the routing table. Should
+ * never fire with the three shipping presets (each covers all six
+ * categories) but guards custom-table misuse.
+ */
+export declare class MemoryRouterUnknownCategoryError extends Error {
+    readonly category: string;
+    constructor(category: string);
+}
+/**
+ * Thrown by `hard` budget mode when the routing-table pick exceeds the
+ * per-query USD ceiling. Carries the picked backend + cost + budget so
+ * application-layer fallbacks can decide what to do (fall back to a
+ * different memory architecture, return a typed 402 to the user, etc).
+ */
+export declare class MemoryRouterBudgetExceededError extends Error {
+    readonly backend: MemoryBackendId;
+    readonly cost: number;
+    readonly budget: number;
+    constructor(backend: MemoryBackendId, cost: number, budget: number);
+}
+/**
+ * Pure routing decision: maps a predicted category to a backend choice
+ * given a routing table + budget policy + cost-points data.
+ *
+ * Algorithm:
+ *   1. Look up the table's preferred backend for the predicted category.
+ *      Throw if missing (custom-table misuse).
+ *   2. If no budget is set, return the table's pick.
+ *   3. If the pick fits the budget, return it.
+ *   4. If the pick exceeds:
+ *      - `hard`: throw {@link MemoryRouterBudgetExceededError}.
+ *      - `cheapest-fallback`: pick the cheapest backend that fits;
+ *        if none fits, pick the absolute cheapest and flag exceeded.
+ *      - `soft`: keep the pick if its $/correct beats the cheapest fits;
+ *        otherwise downgrade to the cheapest fits. Globally-no-fit case
+ *        falls through to absolute-cheapest with budgetExceeded=true.
+ *
+ * @param args
+ * @param args.predictedCategory - Category predicted by the LLM-as-judge classifier.
+ * @param args.groundTruthCategory - Gold-label category for telemetry, or null in production.
+ * @param args.config - Routing table + budget policy + cost-points map.
+ *
+ * @returns A {@link MemoryRoutingDecision} describing the chosen backend.
+ *
+ * @throws {@link MemoryRouterUnknownCategoryError} when the table does not
+ *   cover `predictedCategory`.
+ * @throws {@link MemoryRouterBudgetExceededError} when `budgetMode === 'hard'`
+ *   and the routing-table pick exceeds the budget.
+ *
+ * @example
+ * ```ts
+ * const decision = selectBackend({
+ *   predictedCategory: 'multi-session',
+ *   groundTruthCategory: null,
+ *   config: {
+ *     table: MINIMIZE_COST_TABLE,
+ *     budgetPerQuery: 0.05,
+ *     budgetMode: 'cheapest-fallback',
+ *     backendCosts: DEFAULT_MEMORY_BACKEND_COSTS,
+ *   },
+ * });
+ * console.log(decision.chosenBackend); // 'observational-memory-v11' (fits)
+ * ```
+ */
+export declare function selectBackend(args: {
+    predictedCategory: MemoryQueryCategory;
+    groundTruthCategory: MemoryQueryCategory | null;
+    config: MemoryRouterConfig;
+}): MemoryRoutingDecision;
+//# sourceMappingURL=select-backend.d.ts.map