@framers/agentos 0.5.1 → 0.5.3

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

@@ -19,7 +19,7 @@
  */
 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 AugmentedRoutingTable, type MemoryBackendId, type MemoryDispatchKey, 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';
 /**
@@ -83,6 +83,17 @@ export interface MemoryRouterOptions {
      * execute the chosen backend themselves.
      */
     readonly dispatcher?: IMemoryDispatcher<unknown, unknown>;
+    /**
+     * Optional augmented routing table. When supplied,
+     * {@link MemoryRouter.decideAugmented} and
+     * {@link MemoryRouter.decideAndDispatchAugmented} resolve each query
+     * to a composite {@link MemoryDispatchKey} (backend × retrieval-config)
+     * instead of the legacy single-axis backend pick.
+     *
+     * Existing consumers see no behavioral change unless they call the
+     * new augmented methods.
+     */
+    readonly augmentedTable?: AugmentedRoutingTable;
 }
 /**
  * Per-call options for {@link MemoryRouter.decide}.
@@ -119,6 +130,24 @@ export interface MemoryRouterDispatchedDecision<TTrace> {
     readonly traces: TTrace[];
     readonly backend: MemoryBackendId;
 }
+/**
+ * Bundled result of a `decideAugmented()` call. Carries the classifier
+ * result and the composite {@link MemoryDispatchKey} (backend ×
+ * retrieval-config) the augmented router resolved.
+ */
+export interface MemoryRouterAugmentedDecision {
+    readonly classifier: MemoryClassifierResult;
+    readonly dispatch: MemoryDispatchKey;
+}
+/**
+ * Bundled result of a `decideAndDispatchAugmented()` call. Combines
+ * the augmented decision with the dispatched traces.
+ */
+export interface MemoryRouterAugmentedDispatchedDecision<TTrace> {
+    readonly decision: MemoryRouterAugmentedDecision;
+    readonly traces: TTrace[];
+    readonly dispatch: MemoryDispatchKey;
+}
 /**
  * Thrown when `decideAndDispatch` is called on a router that was
  * constructed without a dispatcher.
@@ -126,6 +155,14 @@ export interface MemoryRouterDispatchedDecision<TTrace> {
 export declare class MemoryRouterDispatcherMissingError extends Error {
     constructor();
 }
+/**
+ * Thrown when `decideAugmented` or `decideAndDispatchAugmented` is
+ * called on a router that was constructed without an
+ * {@link AugmentedRoutingTable}.
+ */
+export declare class MemoryRouterAugmentedTableMissingError extends Error {
+    constructor();
+}
 /**
  * The public MemoryRouter primitive. One instance per memory-recall
  * endpoint; construct once at app startup with the chosen preset and
@@ -159,6 +196,7 @@ export declare class MemoryRouter {
     private readonly classifier;
     private readonly preset;
     private readonly routingTable;
+    private readonly augmentedTable;
     private readonly budgetPerQuery;
     private readonly budgetMode;
     private readonly backendCosts;
@@ -191,5 +229,51 @@ export declare class MemoryRouter {
      *   was supplied at construction.
      */
     decideAndDispatch<TTrace, TPayload = undefined>(query: string, dispatchPayload?: TPayload, options?: MemoryRouterDecideOptions): Promise<MemoryRouterDispatchedDecision<TTrace>>;
+    /**
+     * Decide-only routing using the augmented table. Classifies the
+     * query, resolves a composite {@link MemoryDispatchKey} (backend ×
+     * retrieval-config) from the configured
+     * {@link AugmentedRoutingTable}, and returns both pieces.
+     *
+     * Does NOT execute the recall — pair with {@link IMemoryDispatcher}
+     * for the end-to-end flow, or call
+     * {@link MemoryRouter.decideAndDispatchAugmented} when both an
+     * augmented table and a dispatcher are wired.
+     *
+     * @param query - The user's memory-recall query text.
+     * @param options - Per-call overrides (ground-truth telemetry,
+     *   prompt variant). The `groundTruthCategory` field is unused on
+     *   this path because augmented routing has no `selectBackend`-style
+     *   telemetry surface; tests pass it through anyway for parity.
+     * @returns The classifier result + composite dispatch key.
+     *
+     * @throws {@link MemoryRouterAugmentedTableMissingError} when no
+     *   augmented table was supplied at construction.
+     */
+    decideAugmented(query: string, options?: MemoryRouterDecideOptions): Promise<MemoryRouterAugmentedDecision>;
+    /**
+     * Decide + dispatch in one call, using the augmented table.
+     * Requires the router to have been constructed with both an
+     * {@link AugmentedRoutingTable} and a {@link IMemoryDispatcher}.
+     *
+     * The selected {@link RetrievalConfigId} is forwarded to the
+     * dispatcher's `retrievalConfig` arg; consumer-defined executors
+     * read it via the third-arg
+     * {@link MemoryBackendExecutorContext} parameter.
+     *
+     * @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
+     *   per-backend executor (e.g. topK, retrieval policy).
+     * @param options - Per-call overrides (ground-truth telemetry,
+     *   prompt variant).
+     *
+     * @throws {@link MemoryRouterAugmentedTableMissingError} when no
+     *   augmented table was supplied at construction.
+     * @throws {@link MemoryRouterDispatcherMissingError} when no
+     *   dispatcher was supplied at construction.
+     */
+    decideAndDispatchAugmented<TTrace, TPayload = undefined>(query: string, dispatchPayload?: TPayload, options?: MemoryRouterDecideOptions): Promise<MemoryRouterAugmentedDispatchedDecision<TTrace>>;
 }
 //# sourceMappingURL=MemoryRouter.d.ts.map

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

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

@@ -18,7 +18,7 @@
  * @module @framers/agentos/memory-router/MemoryRouter
  */
 import { DEFAULT_MEMORY_BACKEND_COSTS, } from './backend-costs.js';
-import { PRESET_TABLES, } from './routing-tables.js';
+import { PRESET_TABLES, selectAugmentedDispatch, } from './routing-tables.js';
 import { selectBackend, } from './select-backend.js';
 /**
  * Thrown when `decideAndDispatch` is called on a router that was
@@ -31,6 +31,19 @@ export class MemoryRouterDispatcherMissingError extends Error {
         this.name = 'MemoryRouterDispatcherMissingError';
     }
 }
+/**
+ * Thrown when `decideAugmented` or `decideAndDispatchAugmented` is
+ * called on a router that was constructed without an
+ * {@link AugmentedRoutingTable}.
+ */
+export class MemoryRouterAugmentedTableMissingError extends Error {
+    constructor() {
+        super('MemoryRouter.decideAugmented requires an augmentedTable. ' +
+            'Pass one in MemoryRouterOptions (e.g. MINIMIZE_COST_AUGMENTED_TABLE), ' +
+            'or use the legacy `decide` / `decideAndDispatch` methods.');
+        this.name = 'MemoryRouterAugmentedTableMissingError';
+    }
+}
 // ============================================================================
 // Class
 // ============================================================================
@@ -68,6 +81,7 @@ export class MemoryRouter {
         this.classifier = options.classifier;
         this.preset = options.preset ?? 'minimize-cost';
         this.dispatcher = options.dispatcher ?? null;
+        this.augmentedTable = options.augmentedTable ?? null;
         // Resolve routing table: explicit > preset's default.
         const baseTable = options.routingTable ?? PRESET_TABLES[this.preset];
         // Apply optional per-category mapping override.
@@ -151,5 +165,78 @@ export class MemoryRouter {
             backend: dispatched.backend,
         };
     }
+    /**
+     * Decide-only routing using the augmented table. Classifies the
+     * query, resolves a composite {@link MemoryDispatchKey} (backend ×
+     * retrieval-config) from the configured
+     * {@link AugmentedRoutingTable}, and returns both pieces.
+     *
+     * Does NOT execute the recall — pair with {@link IMemoryDispatcher}
+     * for the end-to-end flow, or call
+     * {@link MemoryRouter.decideAndDispatchAugmented} when both an
+     * augmented table and a dispatcher are wired.
+     *
+     * @param query - The user's memory-recall query text.
+     * @param options - Per-call overrides (ground-truth telemetry,
+     *   prompt variant). The `groundTruthCategory` field is unused on
+     *   this path because augmented routing has no `selectBackend`-style
+     *   telemetry surface; tests pass it through anyway for parity.
+     * @returns The classifier result + composite dispatch key.
+     *
+     * @throws {@link MemoryRouterAugmentedTableMissingError} when no
+     *   augmented table was supplied at construction.
+     */
+    async decideAugmented(query, options) {
+        if (!this.augmentedTable) {
+            throw new MemoryRouterAugmentedTableMissingError();
+        }
+        const useFewShot = options?.useFewShotPrompt ?? this.defaultUseFewShotPrompt;
+        const classifierOptions = useFewShot
+            ? { useFewShotPrompt: true }
+            : undefined;
+        const classifier = await this.classifier.classify(query, classifierOptions);
+        const dispatch = selectAugmentedDispatch(classifier.category, this.augmentedTable);
+        return { classifier, dispatch };
+    }
+    /**
+     * Decide + dispatch in one call, using the augmented table.
+     * Requires the router to have been constructed with both an
+     * {@link AugmentedRoutingTable} and a {@link IMemoryDispatcher}.
+     *
+     * The selected {@link RetrievalConfigId} is forwarded to the
+     * dispatcher's `retrievalConfig` arg; consumer-defined executors
+     * read it via the third-arg
+     * {@link MemoryBackendExecutorContext} parameter.
+     *
+     * @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
+     *   per-backend executor (e.g. topK, retrieval policy).
+     * @param options - Per-call overrides (ground-truth telemetry,
+     *   prompt variant).
+     *
+     * @throws {@link MemoryRouterAugmentedTableMissingError} when no
+     *   augmented table was supplied at construction.
+     * @throws {@link MemoryRouterDispatcherMissingError} when no
+     *   dispatcher was supplied at construction.
+     */
+    async decideAndDispatchAugmented(query, dispatchPayload, options) {
+        if (!this.dispatcher) {
+            throw new MemoryRouterDispatcherMissingError();
+        }
+        const decision = await this.decideAugmented(query, options);
+        const dispatched = (await this.dispatcher.dispatch({
+            backend: decision.dispatch.backend,
+            retrievalConfig: decision.dispatch.retrievalConfig,
+            query,
+            payload: dispatchPayload,
+        }));
+        return {
+            decision,
+            traces: dispatched.traces,
+            dispatch: decision.dispatch,
+        };
+    }
 }
 //# sourceMappingURL=MemoryRouter.js.map

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

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

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

@@ -29,17 +29,47 @@
  * @module @framers/agentos/memory-router/dispatcher
  */
 import type { MemoryBackendId } from './routing-tables.js';
+import type { RetrievalConfigId } from './retrieval-config.js';
+/**
+ * Optional execution context passed as the third argument to a
+ * {@link MemoryBackendExecutor}. Carries cross-cutting per-call hints
+ * the dispatcher knows about but the user-defined payload should not
+ * have to encode (e.g. the {@link RetrievalConfigId} chosen by the
+ * augmented router).
+ *
+ * Existing executors with the older two-argument signature
+ * `(query, payload) => traces` remain assignable to
+ * {@link MemoryBackendExecutor} because the context arg is optional —
+ * functions are contravariant in their parameters and JavaScript
+ * silently ignores unused trailing arguments.
+ */
+export interface MemoryBackendExecutorContext {
+    /**
+     * Augmented router's per-query retrieval-config pick. When set, the
+     * executor SHOULD apply the corresponding flags
+     * (see `RETRIEVAL_CONFIG_SPECS`) to its retrieval pipeline.
+     * Undefined when the dispatcher was called via the legacy backend-
+     * only path.
+     */
+    readonly retrievalConfig?: RetrievalConfigId;
+}
 /**
  * Per-backend execution function. Takes the query string + an optional
  * caller-defined payload (e.g. topK, retrieval policy, session filter),
  * returns the trace array.
  *
+ * The optional third arg, {@link MemoryBackendExecutorContext}, carries
+ * cross-cutting hints the dispatcher routes through — currently the
+ * augmented router's per-query {@link RetrievalConfigId}. Executors
+ * written before augmented routing existed remain assignable because
+ * the third arg is optional.
+ *
  * @typeParam TTrace - Shape of the trace the caller's memory layer emits.
  *   Defaults to the {@link ScoredTrace} shape from `@framers/agentos/memory`
  *   but any shape is accepted since the dispatcher is a pass-through.
  * @typeParam TPayload - Shape of the optional payload argument.
  */
-export type MemoryBackendExecutor<TTrace, TPayload = undefined> = (query: string, payload: TPayload) => Promise<TTrace[]>;
+export type MemoryBackendExecutor<TTrace, TPayload = undefined> = (query: string, payload: TPayload, context?: MemoryBackendExecutorContext) => Promise<TTrace[]>;
 /**
  * Args passed to {@link IMemoryDispatcher.dispatch}.
  */
@@ -48,6 +78,14 @@ export interface MemoryDispatchArgs<TPayload = undefined> {
     readonly query: string;
     /** Optional payload forwarded to the per-backend executor verbatim. */
     readonly payload?: TPayload;
+    /**
+     * Optional augmented-router pick. When supplied, the dispatcher
+     * forwards it as the third executor arg
+     * ({@link MemoryBackendExecutorContext.retrievalConfig}). Existing
+     * legacy callers omit this field; existing executors ignore the
+     * third arg unless they opt in.
+     */
+    readonly retrievalConfig?: RetrievalConfigId;
 }
 /**
  * Result of a dispatch call. Carries the traces plus the backend that

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

@@ -1 +1 @@
-{"version":3,"file":"dispatcher.d.ts","sourceRoot":"","sources":["../../src/memory-router/dispatcher.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAM3D;;;;;;;;;GASG;AACH,MAAM,MAAM,qBAAqB,CAAC,MAAM,EAAE,QAAQ,GAAG,SAAS,IAAI,CAChE,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,QAAQ,KACd,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;AAEvB;;GAEG;AACH,MAAM,WAAW,kBAAkB,CAAC,QAAQ,GAAG,SAAS;IACtD,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAC;IAClC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,uEAAuE;IACvE,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC;CAC7B;AAED;;;GAGG;AACH,MAAM,WAAW,oBAAoB,CAAC,MAAM;IAC1C,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAC;CACnC;AAED;;;;GAIG;AACH,MAAM,WAAW,iBAAiB,CAAC,MAAM,GAAG,OAAO,EAAE,QAAQ,GAAG,OAAO;IACrE,QAAQ,CACN,IAAI,EAAE,kBAAkB,CAAC,QAAQ,CAAC,GACjC,OAAO,CAAC,oBAAoB,CAAC,MAAM,CAAC,CAAC,CAAC;CAC1C;AAED;;;;GAIG;AACH,qBAAa,6BAA8B,SAAQ,KAAK;aAC1B,OAAO,EAAE,eAAe;gBAAxB,OAAO,EAAE,eAAe;CAOrD;AAMD;;;;GAIG;AACH,MAAM,MAAM,qBAAqB,CAAC,MAAM,EAAE,QAAQ,IAAI,OAAO,CAC3D,MAAM,CAAC,eAAe,EAAE,qBAAqB,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC,CACjE,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,qBAAa,wBAAwB,CAAC,MAAM,EAAE,QAAQ,GAAG,SAAS,CAChE,YAAW,iBAAiB,CAAC,MAAM,EAAE,QAAQ,CAAC;IAE9C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA0C;gBAEvD,QAAQ,EAAE,qBAAqB,CAAC,MAAM,EAAE,QAAQ,CAAC;IAIvD,QAAQ,CACZ,IAAI,EAAE,kBAAkB,CAAC,QAAQ,CAAC,GACjC,OAAO,CAAC,oBAAoB,CAAC,MAAM,CAAC,CAAC;CAQzC"}
+{"version":3,"file":"dispatcher.d.ts","sourceRoot":"","sources":["../../src/memory-router/dispatcher.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAM/D;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,4BAA4B;IAC3C;;;;;;OAMG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,iBAAiB,CAAC;CAC9C;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,qBAAqB,CAAC,MAAM,EAAE,QAAQ,GAAG,SAAS,IAAI,CAChE,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,QAAQ,EACjB,OAAO,CAAC,EAAE,4BAA4B,KACnC,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;AAEvB;;GAEG;AACH,MAAM,WAAW,kBAAkB,CAAC,QAAQ,GAAG,SAAS;IACtD,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAC;IAClC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,uEAAuE;IACvE,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC;IAC5B;;;;;;OAMG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,iBAAiB,CAAC;CAC9C;AAED;;;GAGG;AACH,MAAM,WAAW,oBAAoB,CAAC,MAAM;IAC1C,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAC;CACnC;AAED;;;;GAIG;AACH,MAAM,WAAW,iBAAiB,CAAC,MAAM,GAAG,OAAO,EAAE,QAAQ,GAAG,OAAO;IACrE,QAAQ,CACN,IAAI,EAAE,kBAAkB,CAAC,QAAQ,CAAC,GACjC,OAAO,CAAC,oBAAoB,CAAC,MAAM,CAAC,CAAC,CAAC;CAC1C;AAED;;;;GAIG;AACH,qBAAa,6BAA8B,SAAQ,KAAK;aAC1B,OAAO,EAAE,eAAe;gBAAxB,OAAO,EAAE,eAAe;CAOrD;AAMD;;;;GAIG;AACH,MAAM,MAAM,qBAAqB,CAAC,MAAM,EAAE,QAAQ,IAAI,OAAO,CAC3D,MAAM,CAAC,eAAe,EAAE,qBAAqB,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC,CACjE,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,qBAAa,wBAAwB,CAAC,MAAM,EAAE,QAAQ,GAAG,SAAS,CAChE,YAAW,iBAAiB,CAAC,MAAM,EAAE,QAAQ,CAAC;IAE9C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA0C;gBAEvD,QAAQ,EAAE,qBAAqB,CAAC,MAAM,EAAE,QAAQ,CAAC;IAIvD,QAAQ,CACZ,IAAI,EAAE,kBAAkB,CAAC,QAAQ,CAAC,GACjC,OAAO,CAAC,oBAAoB,CAAC,MAAM,CAAC,CAAC;CAiBzC"}

package/dist/memory-router/dispatcher.js

@@ -77,7 +77,15 @@ export class FunctionMemoryDispatcher {
         if (!executor) {
             throw new UnsupportedMemoryBackendError(args.backend);
         }
-        const traces = await executor(args.query, args.payload);
+        // Preserve the legacy two-argument call shape on legacy dispatch
+        // calls (no retrievalConfig). Only pass the context arg when the
+        // augmented router has supplied a retrievalConfig — keeps existing
+        // mocks asserting `executor(query, payload)` working unchanged.
+        const traces = args.retrievalConfig !== undefined
+            ? await executor(args.query, args.payload, {
+                retrievalConfig: args.retrievalConfig,
+            })
+            : await executor(args.query, args.payload);
         return { traces, backend: args.backend };
     }
 }

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

@@ -1 +1 @@
-{"version":3,"file":"dispatcher.js","sourceRoot":"","sources":["../../src/memory-router/dispatcher.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAqDH;;;;GAIG;AACH,MAAM,OAAO,6BAA8B,SAAQ,KAAK;IACtD,YAA4B,OAAwB;QAClD,KAAK,CACH,8BAA8B,OAAO,uBAAuB;YAC1D,2DAA2D,CAC9D,CAAC;QAJwB,YAAO,GAAP,OAAO,CAAiB;QAKlD,IAAI,CAAC,IAAI,GAAG,+BAA+B,CAAC;IAC9C,CAAC;CACF;AAeD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,OAAO,wBAAwB;IAKnC,YAAY,QAAiD;QAC3D,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAC3B,CAAC;IAED,KAAK,CAAC,QAAQ,CACZ,IAAkC;QAElC,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAC7C,IAAI,CAAC,QAAQ,EAAE,CAAC;YACd,MAAM,IAAI,6BAA6B,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACxD,CAAC;QACD,MAAM,MAAM,GAAG,MAAM,QAAQ,CAAC,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,OAAmB,CAAC,CAAC;QACpE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC;IAC3C,CAAC;CACF"}
+{"version":3,"file":"dispatcher.js","sourceRoot":"","sources":["../../src/memory-router/dispatcher.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AA6FH;;;;GAIG;AACH,MAAM,OAAO,6BAA8B,SAAQ,KAAK;IACtD,YAA4B,OAAwB;QAClD,KAAK,CACH,8BAA8B,OAAO,uBAAuB;YAC1D,2DAA2D,CAC9D,CAAC;QAJwB,YAAO,GAAP,OAAO,CAAiB;QAKlD,IAAI,CAAC,IAAI,GAAG,+BAA+B,CAAC;IAC9C,CAAC;CACF;AAeD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,OAAO,wBAAwB;IAKnC,YAAY,QAAiD;QAC3D,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAC3B,CAAC;IAED,KAAK,CAAC,QAAQ,CACZ,IAAkC;QAElC,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAC7C,IAAI,CAAC,QAAQ,EAAE,CAAC;YACd,MAAM,IAAI,6BAA6B,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACxD,CAAC;QACD,iEAAiE;QACjE,iEAAiE;QACjE,mEAAmE;QACnE,gEAAgE;QAChE,MAAM,MAAM,GACV,IAAI,CAAC,eAAe,KAAK,SAAS;YAChC,CAAC,CAAC,MAAM,QAAQ,CAAC,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,OAAmB,EAAE;gBACnD,eAAe,EAAE,IAAI,CAAC,eAAe;aACtC,CAAC;YACJ,CAAC,CAAC,MAAM,QAAQ,CAAC,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,OAAmB,CAAC,CAAC;QAC3D,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC;IAC3C,CAAC;CACF"}

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

@@ -108,21 +108,23 @@
  * );
  * ```
  */
-export type { MemoryQueryCategory, MemoryBackendId, MemoryRouterPreset, RoutingTable, } from './routing-tables.js';
+export type { MemoryQueryCategory, MemoryBackendId, MemoryRouterPreset, RoutingTable, AugmentedMemoryRouterPreset, AugmentedRoutingTable, MemoryDispatchKey, } 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 type { IMemoryDispatcher, MemoryDispatchArgs, MemoryDispatchResult, MemoryBackendExecutor, MemoryBackendExecutorContext, MemoryBackendRegistry, } from './dispatcher.js';
+export type { MemoryBudgetPolicy, MemoryRouterOptions, MemoryRouterDecideOptions, MemoryRouterDecision, MemoryRouterDispatchedDecision, MemoryRouterAugmentedDecision, MemoryRouterAugmentedDispatchedDecision, } from './MemoryRouter.js';
+export { MINIMIZE_COST_TABLE, BALANCED_TABLE, MAXIMIZE_ACCURACY_TABLE, PRESET_TABLES, MINIMIZE_COST_AUGMENTED_TABLE, AUGMENTED_PRESET_TABLES, SAFE_FALLBACK_BACKEND, SAFE_FALLBACK_DISPATCH_KEY, selectAugmentedDispatch, } 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';
+export { MemoryRouter, MemoryRouterDispatcherMissingError, MemoryRouterAugmentedTableMissingError, } from './MemoryRouter.js';
 export type { CalibrationSample, CalibrationCell, AggregatedCalibration, AdaptivePresetRule, SelectByPresetArgs, BuildAdaptiveRoutingTableArgs, AdaptiveMemoryRouterOptions, } from './adaptive.js';
 export { aggregateCalibration, selectByPreset, buildAdaptiveRoutingTable, AdaptiveMemoryRouter, } from './adaptive.js';
 export { EntityRetrievalRanker, createEntityRetrievalRanker, } from './backends/index.js';
 export type { RankedCandidate, RankedCandidateWithBoost, EntityRetrievalRankerOptions, } from './backends/index.js';
+export { RETRIEVAL_CONFIG_IDS, RETRIEVAL_CONFIG_SPECS, M_PHASE_A_PER_CATEGORY_ACCURACY, M_PHASE_A_COST_PER_CORRECT, M_TUNED_PER_CATEGORY_TABLE, selectBestRetrievalConfig, computeOracleAggregate, computeOracleCostPerCorrect, } from './retrieval-config.js';
+export type { RetrievalConfigId, RetrievalConfigSpec, } from './retrieval-config.js';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +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;AAM3B,YAAY,EACV,iBAAiB,EACjB,eAAe,EACf,qBAAqB,EACrB,kBAAkB,EAClB,kBAAkB,EAClB,6BAA6B,EAC7B,2BAA2B,GAC5B,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,oBAAoB,EACpB,cAAc,EACd,yBAAyB,EACzB,oBAAoB,GACrB,MAAM,eAAe,CAAC;AAMvB,OAAO,EACL,qBAAqB,EACrB,2BAA2B,GAC5B,MAAM,qBAAqB,CAAC;AAC7B,YAAY,EACV,eAAe,EACf,wBAAwB,EACxB,4BAA4B,GAC7B,MAAM,qBAAqB,CAAC"}
+{"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,EACZ,2BAA2B,EAC3B,qBAAqB,EACrB,iBAAiB,GAClB,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,4BAA4B,EAC5B,qBAAqB,GACtB,MAAM,iBAAiB,CAAC;AAEzB,YAAY,EACV,kBAAkB,EAClB,mBAAmB,EACnB,yBAAyB,EACzB,oBAAoB,EACpB,8BAA8B,EAC9B,6BAA6B,EAC7B,uCAAuC,GACxC,MAAM,mBAAmB,CAAC;AAM3B,OAAO,EACL,mBAAmB,EACnB,cAAc,EACd,uBAAuB,EACvB,aAAa,EACb,6BAA6B,EAC7B,uBAAuB,EACvB,qBAAqB,EACrB,0BAA0B,EAC1B,uBAAuB,GACxB,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,EAClC,sCAAsC,GACvC,MAAM,mBAAmB,CAAC;AAM3B,YAAY,EACV,iBAAiB,EACjB,eAAe,EACf,qBAAqB,EACrB,kBAAkB,EAClB,kBAAkB,EAClB,6BAA6B,EAC7B,2BAA2B,GAC5B,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,oBAAoB,EACpB,cAAc,EACd,yBAAyB,EACzB,oBAAoB,GACrB,MAAM,eAAe,CAAC;AAMvB,OAAO,EACL,qBAAqB,EACrB,2BAA2B,GAC5B,MAAM,qBAAqB,CAAC;AAC7B,YAAY,EACV,eAAe,EACf,wBAAwB,EACxB,4BAA4B,GAC7B,MAAM,qBAAqB,CAAC;AAO7B,OAAO,EACL,oBAAoB,EACpB,sBAAsB,EACtB,+BAA+B,EAC/B,0BAA0B,EAC1B,0BAA0B,EAC1B,yBAAyB,EACzB,sBAAsB,EACtB,2BAA2B,GAC5B,MAAM,uBAAuB,CAAC;AAE/B,YAAY,EACV,iBAAiB,EACjB,mBAAmB,GACpB,MAAM,uBAAuB,CAAC"}

package/dist/memory-router/index.js

@@ -112,15 +112,20 @@ 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 { MINIMIZE_COST_TABLE, BALANCED_TABLE, MAXIMIZE_ACCURACY_TABLE, PRESET_TABLES, MINIMIZE_COST_AUGMENTED_TABLE, AUGMENTED_PRESET_TABLES, SAFE_FALLBACK_BACKEND, SAFE_FALLBACK_DISPATCH_KEY, selectAugmentedDispatch, } 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';
+export { MemoryRouter, MemoryRouterDispatcherMissingError, MemoryRouterAugmentedTableMissingError, } from './MemoryRouter.js';
 export { aggregateCalibration, selectByPreset, buildAdaptiveRoutingTable, AdaptiveMemoryRouter, } from './adaptive.js';
 // ============================================================================
 // Reference recall-stage backends (Stage I: Mem0-v3-style entity-linking)
 // ============================================================================
 export { EntityRetrievalRanker, createEntityRetrievalRanker, } from './backends/index.js';
+// ============================================================================
+// RetrievalConfigRouter (per-query retrieval-config dispatch, calibrated
+// from 2026-04-26 LongMemEval-M Phase A N=54 ablation matrix)
+// ============================================================================
+export { RETRIEVAL_CONFIG_IDS, RETRIEVAL_CONFIG_SPECS, M_PHASE_A_PER_CATEGORY_ACCURACY, M_PHASE_A_COST_PER_CORRECT, M_TUNED_PER_CATEGORY_TABLE, selectBestRetrievalConfig, computeOracleAggregate, computeOracleCostPerCorrect, } from './retrieval-config.js';
 //# sourceMappingURL=index.js.map

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

@@ -1 +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;AAgB3B,OAAO,EACL,oBAAoB,EACpB,cAAc,EACd,yBAAyB,EACzB,oBAAoB,GACrB,MAAM,eAAe,CAAC;AAEvB,+EAA+E;AAC/E,0EAA0E;AAC1E,+EAA+E;AAE/E,OAAO,EACL,qBAAqB,EACrB,2BAA2B,GAC5B,MAAM,qBAAqB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/memory-router/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6GG;AAeH,OAAO,EAAE,uBAAuB,EAAE,MAAM,qBAAqB,CAAC;AAuC9D,+EAA+E;AAC/E,SAAS;AACT,+EAA+E;AAE/E,OAAO,EACL,mBAAmB,EACnB,cAAc,EACd,uBAAuB,EACvB,aAAa,EACb,6BAA6B,EAC7B,uBAAuB,EACvB,qBAAqB,EACrB,0BAA0B,EAC1B,uBAAuB,GACxB,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,EAClC,sCAAsC,GACvC,MAAM,mBAAmB,CAAC;AAgB3B,OAAO,EACL,oBAAoB,EACpB,cAAc,EACd,yBAAyB,EACzB,oBAAoB,GACrB,MAAM,eAAe,CAAC;AAEvB,+EAA+E;AAC/E,0EAA0E;AAC1E,+EAA+E;AAE/E,OAAO,EACL,qBAAqB,EACrB,2BAA2B,GAC5B,MAAM,qBAAqB,CAAC;AAO7B,+EAA+E;AAC/E,yEAAyE;AACzE,8DAA8D;AAC9D,+EAA+E;AAE/E,OAAO,EACL,oBAAoB,EACpB,sBAAsB,EACtB,+BAA+B,EAC/B,0BAA0B,EAC1B,0BAA0B,EAC1B,yBAAyB,EACzB,sBAAsB,EACtB,2BAA2B,GAC5B,MAAM,uBAAuB,CAAC"}

package/dist/memory-router/retrieval-config.d.ts

@@ -0,0 +1,147 @@
+/**
+ * @file retrieval-config.ts
+ * @description RetrievalConfigRouter primitive — extends the
+ * MemoryRouter pattern with per-query retrieval-config dispatch.
+ *
+ * **What this primitive does:**
+ *
+ * The shipping {@link MemoryRouter} dispatches among recall BACKENDS
+ * (canonical-hybrid, OM-v10, OM-v11) per query. This module adds an
+ * orthogonal axis: per-query retrieval-CONFIG dispatch — picking
+ * among `(canonical, hyde, topk50, topk50-mult5, hyde-topk50, hyde-
+ * topk50-mult5)` based on the LLM classifier's predicted query
+ * category. Each variant configures different retrieval-precision
+ * knobs that lift different categories at different cost points.
+ *
+ * **Why this exists:**
+ *
+ * The 2026-04-26 ablation matrix on LongMemEval-M (Phase A N=54)
+ * showed dramatic per-category variance across retrieval-config
+ * combinations. Some categories (multi-session) only lift with the
+ * full combined config; others (temporal-reasoning) are best served
+ * by HyDE alone; cost-per-correct varies 4x across configs. A static
+ * always-on combined config leaves ~9 pp of accuracy on the table
+ * vs per-category-oracle dispatch.
+ *
+ * **Calibration source:**
+ *
+ * `M_TUNED_PER_CATEGORY_TABLE` is calibrated from the LongMemEval-M
+ * Phase A N=54 ablation runs documented in
+ * `apps/agentos-live-docs/blog/2026-04-26-longmemeval-m-30-to-57.md`
+ * §"Ablation matrix". Each category's pick is the ablation config
+ * that maximized accuracy for that category on M; ties broken by
+ * lower $/correct.
+ *
+ * **Opt-in by registration:**
+ *
+ * Consumers register only the {@link RetrievalConfigId} values they
+ * support in their dispatcher. The selector falls back to `canonical`
+ * if a registered config is not in the consumer's executor map.
+ *
+ * @module @framers/agentos/memory-router/retrieval-config
+ */
+import type { MemoryQueryCategory } from './routing-tables.js';
+/**
+ * Retrieval-config variants. Each maps to a flag combination on the
+ * agentos-bench CLI; consumers building outside the bench wire each
+ * variant to a different retrieval pipeline.
+ *
+ * - `canonical`: BM25 + dense + Cohere rerank-v3.5 + reader-top-k 20
+ *   (baseline; matches the existing MemoryRouter `canonical-hybrid`
+ *   backend's default config).
+ * - `hyde`: canonical + HyDE hypothetical-document embedding.
+ * - `topk50`: canonical + reader-top-k 50.
+ * - `topk50-mult5`: canonical + reader-top-k 50 +
+ *   rerank-candidate-multiplier 5 (250-chunk pool).
+ * - `hyde-topk50`: hyde + reader-top-k 50.
+ * - `hyde-topk50-mult5`: hyde + reader-top-k 50 + rerank-candidate-
+ *   multiplier 5 (the 2026-04-26 M-tuned combined config).
+ */
+export declare const RETRIEVAL_CONFIG_IDS: readonly ["canonical", "hyde", "topk50", "topk50-mult5", "hyde-topk50", "hyde-topk50-mult5"];
+/** {@link RETRIEVAL_CONFIG_IDS} as a TypeScript literal type. */
+export type RetrievalConfigId = (typeof RETRIEVAL_CONFIG_IDS)[number];
+/**
+ * Per-flag breakdown of a {@link RetrievalConfigId}. The fields
+ * correspond directly to the agentos-bench CLI flags so consumers
+ * can apply the config to their own retrieval pipeline.
+ */
+export interface RetrievalConfigSpec {
+    /** Stable identifier. */
+    id: RetrievalConfigId;
+    /** Enable HyDE (hypothetical-document embedding). Default false. */
+    hyde: boolean;
+    /** Cohere rerank candidate multiplier. Default 3 (matches `--rerank-candidate-multiplier 3`). */
+    rerankCandidateMultiplier: number;
+    /** Reader-side top-K cutoff after rerank. Default 20 (matches `--reader-top-k 20`). */
+    readerTopK: number;
+}
+/**
+ * Frozen registry of {@link RetrievalConfigSpec} by id. Consumers
+ * read this to find the per-flag values for a given config id.
+ *
+ * Mutating returned spec objects is undefined behavior — they are
+ * frozen at module load.
+ */
+export declare const RETRIEVAL_CONFIG_SPECS: Readonly<Record<RetrievalConfigId, Readonly<RetrievalConfigSpec>>>;
+/**
+ * Per-category accuracy at each retrieval config on LongMemEval-M
+ * Phase A N=54 stratified, seed=42, gpt-4o reader, gpt-4o-2024-08-06
+ * judge. Source: ablation runs in
+ * `packages/agentos-bench/results/runs/2026-04-26T01-40-34-904--*`
+ * through `2026-04-26T03-22-06-857--*`.
+ *
+ * Numbers in the (0, 1) range. Use {@link selectBestRetrievalConfig}
+ * to pick the highest-accuracy config for a category.
+ */
+export declare const M_PHASE_A_PER_CATEGORY_ACCURACY: Readonly<Record<MemoryQueryCategory, Readonly<Record<RetrievalConfigId, number>>>>;
+/**
+ * Approximate $/correct for each retrieval config on LongMemEval-M
+ * Phase A N=54 (full pipeline cost / correct cases). Source: same
+ * run JSONs as {@link M_PHASE_A_PER_CATEGORY_ACCURACY}. Used to
+ * break ties when multiple configs achieve the same per-category
+ * accuracy.
+ */
+export declare const M_PHASE_A_COST_PER_CORRECT: Readonly<Record<RetrievalConfigId, number>>;
+/**
+ * Calibrated dispatch table: per-category, the
+ * {@link RetrievalConfigId} that maximizes accuracy on LongMemEval-M
+ * Phase A. Ties broken by lower $/correct.
+ *
+ * **Calibration validity:** N=54 stratified, single seed, single
+ * benchmark variant. Phase B at N=500 will tighten the per-category
+ * confidence intervals; the table here is the directional best-
+ * guess for v2 and should be re-derived from any future Phase B run.
+ */
+export declare const M_TUNED_PER_CATEGORY_TABLE: Readonly<Record<MemoryQueryCategory, RetrievalConfigId>>;
+/**
+ * Pure-function selector: given a category and an optional set of
+ * registered configs, return the {@link RetrievalConfigId} that
+ * maximizes accuracy on LongMemEval-M Phase A. Falls back to
+ * `canonical` if the calibrated pick is not in the registered set.
+ *
+ * @param category - Predicted query category from the classifier.
+ * @param registered - Optional set of config IDs the consumer's
+ *   dispatcher supports. When omitted, all configs are considered
+ *   registered.
+ */
+export declare function selectBestRetrievalConfig(category: MemoryQueryCategory, registered?: readonly RetrievalConfigId[]): RetrievalConfigId;
+/**
+ * Compute the calibrated per-category-oracle aggregate accuracy for
+ * a hypothetical workload distribution. Useful for forecasting the
+ * lift a per-query dispatcher would produce vs a static config.
+ *
+ * @param categoryWeights - Distribution over categories summing to
+ *   1.0 (e.g. LongMemEval-M's roughly 27% MS / 27% TR / 16% KU /
+ *   14% SSU / 11% SSA / 6% SSP).
+ * @param registered - Optional registered config subset.
+ * @returns Expected aggregate accuracy when each category is routed
+ *   to its calibrated best config.
+ */
+export declare function computeOracleAggregate(categoryWeights: Readonly<Record<MemoryQueryCategory, number>>, registered?: readonly RetrievalConfigId[]): number;
+/**
+ * Compute the corresponding $/correct for the per-category-oracle
+ * dispatch under a category distribution. Useful for forecasting
+ * cost-efficiency under per-query routing.
+ */
+export declare function computeOracleCostPerCorrect(categoryWeights: Readonly<Record<MemoryQueryCategory, number>>, registered?: readonly RetrievalConfigId[]): number;
+//# sourceMappingURL=retrieval-config.d.ts.map

package/dist/memory-router/retrieval-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retrieval-config.d.ts","sourceRoot":"","sources":["../../src/memory-router/retrieval-config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAE/D;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,oBAAoB,8FAOvB,CAAC;AAEX,iEAAiE;AACjE,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,oBAAoB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEtE;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,yBAAyB;IACzB,EAAE,EAAE,iBAAiB,CAAC;IACtB,oEAAoE;IACpE,IAAI,EAAE,OAAO,CAAC;IACd,iGAAiG;IACjG,yBAAyB,EAAE,MAAM,CAAC;IAClC,uFAAuF;IACvF,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;GAMG;AACH,eAAO,MAAM,sBAAsB,EAAE,QAAQ,CAC3C,MAAM,CAAC,iBAAiB,EAAE,QAAQ,CAAC,mBAAmB,CAAC,CAAC,CAsCxD,CAAC;AAEH;;;;;;;;;GASG;AACH,eAAO,MAAM,+BAA+B,EAAE,QAAQ,CACpD,MAAM,CAAC,mBAAmB,EAAE,QAAQ,CAAC,MAAM,CAAC,iBAAiB,EAAE,MAAM,CAAC,CAAC,CAAC,CAkDxE,CAAC;AAEH;;;;;;GAMG;AACH,eAAO,MAAM,0BAA0B,EAAE,QAAQ,CAC/C,MAAM,CAAC,iBAAiB,EAAE,MAAM,CAAC,CAQjC,CAAC;AAEH;;;;;;;;;GASG;AACH,eAAO,MAAM,0BAA0B,EAAE,QAAQ,CAC/C,MAAM,CAAC,mBAAmB,EAAE,iBAAiB,CAAC,CAQ9C,CAAC;AAEH;;;;;;;;;;GAUG;AACH,wBAAgB,yBAAyB,CACvC,QAAQ,EAAE,mBAAmB,EAC7B,UAAU,CAAC,EAAE,SAAS,iBAAiB,EAAE,GACxC,iBAAiB,CAenB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,sBAAsB,CACpC,eAAe,EAAE,QAAQ,CAAC,MAAM,CAAC,mBAAmB,EAAE,MAAM,CAAC,CAAC,EAC9D,UAAU,CAAC,EAAE,SAAS,iBAAiB,EAAE,GACxC,MAAM,CAOR;AAED;;;;GAIG;AACH,wBAAgB,2BAA2B,CACzC,eAAe,EAAE,QAAQ,CAAC,MAAM,CAAC,mBAAmB,EAAE,MAAM,CAAC,CAAC,EAC9D,UAAU,CAAC,EAAE,SAAS,iBAAiB,EAAE,GACxC,MAAM,CAOR"}