@framers/agentos 0.2.6 → 0.2.7

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

@@ -0,0 +1,169 @@
+/**
+ * @file classifier.ts
+ * @description The LLM-as-judge classifier that the {@link MemoryRouter}
+ * uses to pick a {@link MemoryQueryCategory} for each incoming query.
+ *
+ * The classifier is deliberately abstracted behind {@link IMemoryClassifier}
+ * so callers can swap:
+ *   - the LLM client (any provider — OpenAI, Anthropic, local, mock) via
+ *     the {@link IMemoryClassifierLLM} adapter interface,
+ *   - the prompt variant (base vs few-shot) per-call,
+ *   - the classifier implementation entirely (e.g. a keyword-matcher or a
+ *     small custom ML model) by implementing {@link IMemoryClassifier}.
+ *
+ * The reference implementation, {@link LLMMemoryClassifier}, runs the
+ * gpt-5-mini-style cheap single-shot discriminator prompt and robustly
+ * parses the output, falling back to `multi-session` on unparseable
+ * responses (the safest default — multi-session routes cover cross-session
+ * synthesis which handles most misidentified question types gracefully).
+ *
+ * @module @framers/agentos/memory-router/classifier
+ */
+import { type MemoryQueryCategory } from './routing-tables.js';
+/**
+ * Minimal LLM-call interface the built-in classifier needs. Agentos
+ * consumers wire their preferred provider to this shape via an adapter
+ * — we intentionally do NOT import any provider SDK here so the
+ * memory-router module stays provider-agnostic.
+ */
+export interface MemoryClassifierLLMRequest {
+    /** System prompt. The classifier supplies this based on prompt variant. */
+    readonly system: string;
+    /** User prompt. The classifier renders `Question: {q}\n\nCategory:`. */
+    readonly user: string;
+    /** Max tokens to generate. Classifier passes ≤16 (bare category token). */
+    readonly maxTokens: number;
+    /** Temperature. Classifier passes 0 for determinism. */
+    readonly temperature: number;
+}
+/**
+ * Response shape the built-in classifier expects from the adapter.
+ */
+export interface MemoryClassifierLLMResponse {
+    /** The model's raw text. Whitespace is tolerated; the parser normalizes it. */
+    readonly text: string;
+    /** Input token count, for cost tracking. */
+    readonly tokensIn: number;
+    /** Output token count, for cost tracking. */
+    readonly tokensOut: number;
+    /** Model identifier the LLM reports. */
+    readonly model: string;
+}
+/**
+ * The LLM-client adapter the built-in classifier expects. Adapt any
+ * provider SDK (OpenAI, Anthropic, a provider-router, a mock) to this
+ * shape before passing into {@link LLMMemoryClassifier}.
+ */
+export interface IMemoryClassifierLLM {
+    invoke(request: MemoryClassifierLLMRequest): Promise<MemoryClassifierLLMResponse>;
+}
+/**
+ * Options passed per-call to {@link IMemoryClassifier.classify}. The
+ * classifier reads these to pick a prompt variant; everything else is
+ * constructor-scoped.
+ */
+export interface MemoryClassifierClassifyOptions {
+    /**
+     * Use the few-shot prompt variant instead of the base prompt. The
+     * few-shot prompt includes explicit Question/Category pairs targeting
+     * known confusion patterns (SSU-vs-SSA, SSP-vs-SSA, MS-vs-KU). Default
+     * false — the base prompt is ~2.5x cheaper per-classification-token and
+     * matches the shipping Tier 3 v10 classifier configuration.
+     */
+    readonly useFewShotPrompt?: boolean;
+}
+/**
+ * Result of a classification call. The returned category is always a
+ * valid {@link MemoryQueryCategory}; parse failures map to the safe
+ * fallback 'multi-session'.
+ */
+export interface MemoryClassifierResult {
+    readonly category: MemoryQueryCategory;
+    readonly tokensIn: number;
+    readonly tokensOut: number;
+    readonly model: string;
+}
+/**
+ * The public classifier contract. Implementations decide how to turn a
+ * query into a category — via LLM, keyword heuristic, small ML model, or
+ * mock.
+ */
+export interface IMemoryClassifier {
+    classify(query: string, options?: MemoryClassifierClassifyOptions): Promise<MemoryClassifierResult>;
+}
+/**
+ * Base classifier prompt. Lists the six category tokens with one-sentence
+ * definitions and a few examples per category, then instructs the model
+ * to emit ONLY the bare category token.
+ */
+export declare const CLASSIFIER_SYSTEM_PROMPT = "You are classifying a memory-system question into one of six categories.\n\nReturn ONLY the category token (no explanation, no quotes, no punctuation).\n\nCategories:\n- single-session-user: the question asks about something the USER said, did, or stated in a specific past session. Answer is in one session. Examples: \"What did I tell you about my favorite dessert?\", \"Where did I say I moved to last month?\"\n- single-session-assistant: the question asks about something the ASSISTANT said, generated, or recommended in a specific session. Answer is in one session. Examples: \"What recipe did you suggest for the birthday party?\", \"What books did you recommend to me?\"\n- single-session-preference: the question asks about a preference the user stated in passing. Answer is in one session. Examples: \"Do I prefer tea or coffee?\", \"What's my favorite type of movie?\"\n- knowledge-update: the question asks about current state where the answer EVOLVED across sessions (supersession). Examples: \"What's my current job title?\", \"Where do I live now?\", \"What's my latest project?\"\n- multi-session: the question requires combining information from 2+ separate sessions. Examples: \"How many different languages have I mentioned studying?\", \"Which authors did you recommend across our conversations?\"\n- temporal-reasoning: the question asks about the order, timing, or duration of events across time. Examples: \"In what order did I visit the three countries?\", \"How many months ago did I start the new job?\"";
+/**
+ * Few-shot variant of the classifier prompt. Adds explicit
+ * Question/Category pairs targeting confusion patterns observed in the
+ * gpt-5-mini base-prompt classifier on LongMemEval Tier A:
+ *   - SSA confused as SSU (YOU-said vs I-said distinction)
+ *   - SSP confused as SSA (preferences phrased like recommendations)
+ *   - MS confused as KU (cross-session vs current-state)
+ *
+ * Used when {@link MemoryClassifierClassifyOptions.useFewShotPrompt} is true.
+ */
+export declare const CLASSIFIER_SYSTEM_PROMPT_FEWSHOT = "You are classifying a memory-system question into one of six categories.\n\nReturn ONLY the category token (no explanation, no quotes, no punctuation).\n\nCategories:\n- single-session-user: the question asks about something the USER said, did, or stated in a specific past session. Answer is in one session.\n- single-session-assistant: the question asks about something the ASSISTANT said, generated, or recommended in a specific session. Answer is in one session.\n- single-session-preference: the question asks about a preference the user stated in passing. Answer is in one session.\n- knowledge-update: the question asks about current state where the answer EVOLVED across sessions (supersession). The user wants the LATEST value of an attribute that has changed over time.\n- multi-session: the question requires combining information from 2+ separate sessions. Counting, listing, or aggregating items the user mentioned across sessions.\n- temporal-reasoning: the question asks about the order, timing, or duration of events across time.\n\nExamples:\n\nQuestion: What did I tell you my favorite ice cream flavor was?\nCategory: single-session-user\n\nQuestion: Where did I say I moved to last month?\nCategory: single-session-user\n\nQuestion: What book did you recommend to me last week?\nCategory: single-session-assistant\n\nQuestion: What recipe did you suggest for the birthday party?\nCategory: single-session-assistant\n\nQuestion: Do I prefer working in the morning or evening?\nCategory: single-session-preference\n\nQuestion: What's my favorite type of movie?\nCategory: single-session-preference\n\nQuestion: What's my current job title?\nCategory: knowledge-update\n\nQuestion: Where do I live now?\nCategory: knowledge-update\n\nQuestion: How many different programming languages have I mentioned learning?\nCategory: multi-session\n\nQuestion: Which authors have you recommended to me across our conversations?\nCategory: multi-session\n\nQuestion: In what order did I visit the three European cities?\nCategory: temporal-reasoning\n\nQuestion: How many weeks ago did I start the new job?\nCategory: temporal-reasoning";
+/**
+ * Default fallback category used when the classifier's LLM output cannot
+ * be parsed into a known category token. multi-session is chosen because
+ * its routing target (OM-based cross-session synthesis under max-accuracy,
+ * canonical-hybrid under min-cost) degrades gracefully on most other
+ * question types.
+ */
+export declare const SAFE_FALLBACK_CATEGORY: MemoryQueryCategory;
+/**
+ * Strips common LLM-output decorations so the parser can match the bare
+ * category token:
+ *   - keeps only the first non-empty line,
+ *   - strips common label prefixes ("category:", "type:", "answer:"),
+ *   - strips surrounding quotes / backticks,
+ *   - strips trailing sentence punctuation,
+ *   - lower-cases the result.
+ */
+export declare function normalizeClassifierOutput(raw: string): string;
+/**
+ * Parse a normalized classifier output into a known category token, or
+ * return the safe fallback if no match is found.
+ */
+export declare function parseClassifierOutput(raw: string): MemoryQueryCategory;
+/**
+ * Constructor options for {@link LLMMemoryClassifier}.
+ */
+export interface LLMMemoryClassifierOptions {
+    /** LLM adapter the classifier calls. */
+    readonly llm: IMemoryClassifierLLM;
+    /**
+     * Max output tokens. Default 16 — the classifier only needs to emit
+     * one bare category token. Callers rarely need to change this.
+     */
+    readonly maxTokens?: number;
+}
+/**
+ * The built-in LLM-based classifier. Runs the category-discrimination
+ * prompt on the configured LLM adapter and parses the response robustly.
+ *
+ * @example
+ * ```ts
+ * import { LLMMemoryClassifier } from '../memory-router';
+ *
+ * const classifier = new LLMMemoryClassifier({
+ *   llm: createOpenAIClassifierAdapter('gpt-5-mini'),
+ * });
+ * const { category } = await classifier.classify(
+ *   "What's my current job title?",
+ * );
+ * // => { category: 'knowledge-update', tokensIn: 412, tokensOut: 4, model: 'gpt-5-mini-2025-08-07' }
+ * ```
+ */
+export declare class LLMMemoryClassifier implements IMemoryClassifier {
+    private readonly llm;
+    private readonly maxTokens;
+    constructor(options: LLMMemoryClassifierOptions);
+    classify(query: string, options?: MemoryClassifierClassifyOptions): Promise<MemoryClassifierResult>;
+}
+//# sourceMappingURL=classifier.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"classifier.d.ts","sourceRoot":"","sources":["../../src/memory-router/classifier.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAEL,KAAK,mBAAmB,EACzB,MAAM,qBAAqB,CAAC;AAM7B;;;;;GAKG;AACH,MAAM,WAAW,0BAA0B;IACzC,2EAA2E;IAC3E,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,wEAAwE;IACxE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,2EAA2E;IAC3E,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,wDAAwD;IACxD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED;;GAEG;AACH,MAAM,WAAW,2BAA2B;IAC1C,+EAA+E;IAC/E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,4CAA4C;IAC5C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,6CAA6C;IAC7C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,wCAAwC;IACxC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACnC,MAAM,CACJ,OAAO,EAAE,0BAA0B,GAClC,OAAO,CAAC,2BAA2B,CAAC,CAAC;CACzC;AAMD;;;;GAIG;AACH,MAAM,WAAW,+BAA+B;IAC9C;;;;;;OAMG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,OAAO,CAAC;CACrC;AAED;;;;GAIG;AACH,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,QAAQ,EAAE,mBAAmB,CAAC;IACvC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CACN,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,+BAA+B,GACxC,OAAO,CAAC,sBAAsB,CAAC,CAAC;CACpC;AAMD;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,8/CAU0K,CAAC;AAEhN;;;;;;;;;GASG;AACH,eAAO,MAAM,gCAAgC,kmEAgDhB,CAAC;AAM9B;;;;;;GAMG;AACH,eAAO,MAAM,sBAAsB,EAAE,mBAAqC,CAAC;AAE3E;;;;;;;;GAQG;AACH,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAe7D;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG,mBAAmB,CAYtE;AAMD;;GAEG;AACH,MAAM,WAAW,0BAA0B;IACzC,wCAAwC;IACxC,QAAQ,CAAC,GAAG,EAAE,oBAAoB,CAAC;IACnC;;;OAGG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,mBAAoB,YAAW,iBAAiB;IAC3D,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAuB;IAC3C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;gBAEvB,OAAO,EAAE,0BAA0B;IAKzC,QAAQ,CACZ,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,+BAA+B,GACxC,OAAO,CAAC,sBAAsB,CAAC;CAoBnC"}

package/dist/memory-router/classifier.js

@@ -0,0 +1,193 @@
+/**
+ * @file classifier.ts
+ * @description The LLM-as-judge classifier that the {@link MemoryRouter}
+ * uses to pick a {@link MemoryQueryCategory} for each incoming query.
+ *
+ * The classifier is deliberately abstracted behind {@link IMemoryClassifier}
+ * so callers can swap:
+ *   - the LLM client (any provider — OpenAI, Anthropic, local, mock) via
+ *     the {@link IMemoryClassifierLLM} adapter interface,
+ *   - the prompt variant (base vs few-shot) per-call,
+ *   - the classifier implementation entirely (e.g. a keyword-matcher or a
+ *     small custom ML model) by implementing {@link IMemoryClassifier}.
+ *
+ * The reference implementation, {@link LLMMemoryClassifier}, runs the
+ * gpt-5-mini-style cheap single-shot discriminator prompt and robustly
+ * parses the output, falling back to `multi-session` on unparseable
+ * responses (the safest default — multi-session routes cover cross-session
+ * synthesis which handles most misidentified question types gracefully).
+ *
+ * @module @framers/agentos/memory-router/classifier
+ */
+import { MEMORY_QUERY_CATEGORIES, } from './routing-tables.js';
+// ============================================================================
+// Prompts
+// ============================================================================
+/**
+ * Base classifier prompt. Lists the six category tokens with one-sentence
+ * definitions and a few examples per category, then instructs the model
+ * to emit ONLY the bare category token.
+ */
+export const CLASSIFIER_SYSTEM_PROMPT = `You are classifying a memory-system question into one of six categories.
+
+Return ONLY the category token (no explanation, no quotes, no punctuation).
+
+Categories:
+- single-session-user: the question asks about something the USER said, did, or stated in a specific past session. Answer is in one session. Examples: "What did I tell you about my favorite dessert?", "Where did I say I moved to last month?"
+- single-session-assistant: the question asks about something the ASSISTANT said, generated, or recommended in a specific session. Answer is in one session. Examples: "What recipe did you suggest for the birthday party?", "What books did you recommend to me?"
+- single-session-preference: the question asks about a preference the user stated in passing. Answer is in one session. Examples: "Do I prefer tea or coffee?", "What's my favorite type of movie?"
+- knowledge-update: the question asks about current state where the answer EVOLVED across sessions (supersession). Examples: "What's my current job title?", "Where do I live now?", "What's my latest project?"
+- multi-session: the question requires combining information from 2+ separate sessions. Examples: "How many different languages have I mentioned studying?", "Which authors did you recommend across our conversations?"
+- temporal-reasoning: the question asks about the order, timing, or duration of events across time. Examples: "In what order did I visit the three countries?", "How many months ago did I start the new job?"`;
+/**
+ * Few-shot variant of the classifier prompt. Adds explicit
+ * Question/Category pairs targeting confusion patterns observed in the
+ * gpt-5-mini base-prompt classifier on LongMemEval Tier A:
+ *   - SSA confused as SSU (YOU-said vs I-said distinction)
+ *   - SSP confused as SSA (preferences phrased like recommendations)
+ *   - MS confused as KU (cross-session vs current-state)
+ *
+ * Used when {@link MemoryClassifierClassifyOptions.useFewShotPrompt} is true.
+ */
+export const CLASSIFIER_SYSTEM_PROMPT_FEWSHOT = `You are classifying a memory-system question into one of six categories.
+
+Return ONLY the category token (no explanation, no quotes, no punctuation).
+
+Categories:
+- single-session-user: the question asks about something the USER said, did, or stated in a specific past session. Answer is in one session.
+- single-session-assistant: the question asks about something the ASSISTANT said, generated, or recommended in a specific session. Answer is in one session.
+- single-session-preference: the question asks about a preference the user stated in passing. Answer is in one session.
+- knowledge-update: the question asks about current state where the answer EVOLVED across sessions (supersession). The user wants the LATEST value of an attribute that has changed over time.
+- multi-session: the question requires combining information from 2+ separate sessions. Counting, listing, or aggregating items the user mentioned across sessions.
+- temporal-reasoning: the question asks about the order, timing, or duration of events across time.
+
+Examples:
+
+Question: What did I tell you my favorite ice cream flavor was?
+Category: single-session-user
+
+Question: Where did I say I moved to last month?
+Category: single-session-user
+
+Question: What book did you recommend to me last week?
+Category: single-session-assistant
+
+Question: What recipe did you suggest for the birthday party?
+Category: single-session-assistant
+
+Question: Do I prefer working in the morning or evening?
+Category: single-session-preference
+
+Question: What's my favorite type of movie?
+Category: single-session-preference
+
+Question: What's my current job title?
+Category: knowledge-update
+
+Question: Where do I live now?
+Category: knowledge-update
+
+Question: How many different programming languages have I mentioned learning?
+Category: multi-session
+
+Question: Which authors have you recommended to me across our conversations?
+Category: multi-session
+
+Question: In what order did I visit the three European cities?
+Category: temporal-reasoning
+
+Question: How many weeks ago did I start the new job?
+Category: temporal-reasoning`;
+// ============================================================================
+// Parser
+// ============================================================================
+/**
+ * Default fallback category used when the classifier's LLM output cannot
+ * be parsed into a known category token. multi-session is chosen because
+ * its routing target (OM-based cross-session synthesis under max-accuracy,
+ * canonical-hybrid under min-cost) degrades gracefully on most other
+ * question types.
+ */
+export const SAFE_FALLBACK_CATEGORY = 'multi-session';
+/**
+ * Strips common LLM-output decorations so the parser can match the bare
+ * category token:
+ *   - keeps only the first non-empty line,
+ *   - strips common label prefixes ("category:", "type:", "answer:"),
+ *   - strips surrounding quotes / backticks,
+ *   - strips trailing sentence punctuation,
+ *   - lower-cases the result.
+ */
+export function normalizeClassifierOutput(raw) {
+    // First non-empty line only — models occasionally emit multi-line explanations.
+    const lines = raw.split('\n');
+    let firstLine = '';
+    for (const ln of lines) {
+        if (ln.trim().length > 0) {
+            firstLine = ln;
+            break;
+        }
+    }
+    let cleaned = firstLine.trim().toLowerCase();
+    cleaned = cleaned.replace(/^(category|type|answer|label|class)\s*[:\-=]\s*/, '');
+    cleaned = cleaned.replace(/^["'`]+|["'`]+$/g, '');
+    cleaned = cleaned.replace(/[.,;!?]+$/g, '');
+    return cleaned.trim();
+}
+/**
+ * Parse a normalized classifier output into a known category token, or
+ * return the safe fallback if no match is found.
+ */
+export function parseClassifierOutput(raw) {
+    const cleaned = normalizeClassifierOutput(raw);
+    for (const token of MEMORY_QUERY_CATEGORIES) {
+        if (cleaned === token ||
+            cleaned.startsWith(`${token} `) ||
+            cleaned.startsWith(`${token}\n`)) {
+            return token;
+        }
+    }
+    return SAFE_FALLBACK_CATEGORY;
+}
+/**
+ * The built-in LLM-based classifier. Runs the category-discrimination
+ * prompt on the configured LLM adapter and parses the response robustly.
+ *
+ * @example
+ * ```ts
+ * import { LLMMemoryClassifier } from '../memory-router/index.js';
+ *
+ * const classifier = new LLMMemoryClassifier({
+ *   llm: createOpenAIClassifierAdapter('gpt-5-mini'),
+ * });
+ * const { category } = await classifier.classify(
+ *   "What's my current job title?",
+ * );
+ * // => { category: 'knowledge-update', tokensIn: 412, tokensOut: 4, model: 'gpt-5-mini-2025-08-07' }
+ * ```
+ */
+export class LLMMemoryClassifier {
+    constructor(options) {
+        this.llm = options.llm;
+        this.maxTokens = options.maxTokens ?? 16;
+    }
+    async classify(query, options) {
+        const system = options?.useFewShotPrompt
+            ? CLASSIFIER_SYSTEM_PROMPT_FEWSHOT
+            : CLASSIFIER_SYSTEM_PROMPT;
+        const user = `Question: ${query}\n\nCategory:`;
+        const response = await this.llm.invoke({
+            system,
+            user,
+            maxTokens: this.maxTokens,
+            temperature: 0,
+        });
+        return {
+            category: parseClassifierOutput(response.text),
+            tokensIn: response.tokensIn,
+            tokensOut: response.tokensOut,
+            model: response.model,
+        };
+    }
+}
+//# sourceMappingURL=classifier.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"classifier.js","sourceRoot":"","sources":["../../src/memory-router/classifier.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EACL,uBAAuB,GAExB,MAAM,qBAAqB,CAAC;AA4F7B,+EAA+E;AAC/E,UAAU;AACV,+EAA+E;AAE/E;;;;GAIG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG;;;;;;;;;;+MAUuK,CAAC;AAEhN;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,gCAAgC,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;6BAgDnB,CAAC;AAE9B,+EAA+E;AAC/E,SAAS;AACT,+EAA+E;AAE/E;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAwB,eAAe,CAAC;AAE3E;;;;;;;;GAQG;AACH,MAAM,UAAU,yBAAyB,CAAC,GAAW;IACnD,gFAAgF;IAChF,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC9B,IAAI,SAAS,GAAG,EAAE,CAAC;IACnB,KAAK,MAAM,EAAE,IAAI,KAAK,EAAE,CAAC;QACvB,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACzB,SAAS,GAAG,EAAE,CAAC;YACf,MAAM;QACR,CAAC;IACH,CAAC;IACD,IAAI,OAAO,GAAG,SAAS,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAC7C,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,iDAAiD,EAAE,EAAE,CAAC,CAAC;IACjF,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,kBAAkB,EAAE,EAAE,CAAC,CAAC;IAClD,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,YAAY,EAAE,EAAE,CAAC,CAAC;IAC5C,OAAO,OAAO,CAAC,IAAI,EAAE,CAAC;AACxB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,qBAAqB,CAAC,GAAW;IAC/C,MAAM,OAAO,GAAG,yBAAyB,CAAC,GAAG,CAAC,CAAC;IAC/C,KAAK,MAAM,KAAK,IAAI,uBAAuB,EAAE,CAAC;QAC5C,IACE,OAAO,KAAK,KAAK;YACjB,OAAO,CAAC,UAAU,CAAC,GAAG,KAAK,GAAG,CAAC;YAC/B,OAAO,CAAC,UAAU,CAAC,GAAG,KAAK,IAAI,CAAC,EAChC,CAAC;YACD,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC;IACD,OAAO,sBAAsB,CAAC;AAChC,CAAC;AAmBD;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,OAAO,mBAAmB;IAI9B,YAAY,OAAmC;QAC7C,IAAI,CAAC,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC;QACvB,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,EAAE,CAAC;IAC3C,CAAC;IAED,KAAK,CAAC,QAAQ,CACZ,KAAa,EACb,OAAyC;QAEzC,MAAM,MAAM,GAAG,OAAO,EAAE,gBAAgB;YACtC,CAAC,CAAC,gCAAgC;YAClC,CAAC,CAAC,wBAAwB,CAAC;QAC7B,MAAM,IAAI,GAAG,aAAa,KAAK,eAAe,CAAC;QAE/C,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC;YACrC,MAAM;YACN,IAAI;YACJ,SAAS,EAAE,IAAI,CAAC,SAAS;YACzB,WAAW,EAAE,CAAC;SACf,CAAC,CAAC;QAEH,OAAO;YACL,QAAQ,EAAE,qBAAqB,CAAC,QAAQ,CAAC,IAAI,CAAC;YAC9C,QAAQ,EAAE,QAAQ,CAAC,QAAQ;YAC3B,SAAS,EAAE,QAAQ,CAAC,SAAS;YAC7B,KAAK,EAAE,QAAQ,CAAC,KAAK;SACtB,CAAC;IACJ,CAAC;CACF"}

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

@@ -0,0 +1,115 @@
+/**
+ * @file dispatcher.ts
+ * @description Backend-execution layer for {@link MemoryRouter}.
+ *
+ * A dispatcher turns a {@link MemoryBackendId} + a query into actual
+ * recall results. Because backend execution depends on how the caller's
+ * memory state is wired — `canonical-hybrid` needs only a query against a
+ * standing {@link Memory}, whereas `observational-memory-*` backends need
+ * ingest-time OM setup — the dispatcher is an injection point rather than
+ * a monolithic implementation.
+ *
+ * The shipping dispatcher, {@link FunctionMemoryDispatcher}, uses a
+ * routing-table-of-functions pattern: the caller provides `{ [backend]:
+ * (query, payload?) => Promise<traces> }` at construction, and the
+ * dispatcher picks the right function per call. This gives consumers:
+ *   - full control over per-backend execution (connect to a standing
+ *     HybridRetriever, a live OM ingest pipeline, a remote service, a
+ *     cache, anything),
+ *   - the ability to opt-out of backends they don't need (omitted keys
+ *     raise a typed {@link UnsupportedMemoryBackendError} at dispatch
+ *     time),
+ *   - full type-safety on the per-call `payload` (passed through to the
+ *     per-backend function verbatim).
+ *
+ * Callers who want to ship quickly with just canonical-hybrid can pass
+ * only `{ 'canonical-hybrid': (q) => mem.recall(q, { limit, policy }) }`
+ * and get end-to-end routing without touching the OM backends.
+ *
+ * @module @framers/agentos/memory-router/dispatcher
+ */
+import type { MemoryBackendId } from './routing-tables.js';
+/**
+ * Per-backend execution function. Takes the query string + an optional
+ * caller-defined payload (e.g. topK, retrieval policy, session filter),
+ * returns the trace array.
+ *
+ * @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[]>;
+/**
+ * Args passed to {@link IMemoryDispatcher.dispatch}.
+ */
+export interface MemoryDispatchArgs<TPayload = undefined> {
+    readonly backend: MemoryBackendId;
+    readonly query: string;
+    /** Optional payload forwarded to the per-backend executor verbatim. */
+    readonly payload?: TPayload;
+}
+/**
+ * Result of a dispatch call. Carries the traces plus the backend that
+ * produced them (for telemetry + logging).
+ */
+export interface MemoryDispatchResult<TTrace> {
+    readonly traces: TTrace[];
+    readonly backend: MemoryBackendId;
+}
+/**
+ * The public dispatcher contract. Callers either use the built-in
+ * {@link FunctionMemoryDispatcher} or implement this interface with
+ * their own backend registry.
+ */
+export interface IMemoryDispatcher<TTrace = unknown, TPayload = unknown> {
+    dispatch(args: MemoryDispatchArgs<TPayload>): Promise<MemoryDispatchResult<TTrace>>;
+}
+/**
+ * Thrown when a dispatch call requests a backend that the dispatcher
+ * was not configured to support. Lets callers surface missing-backend
+ * bugs at the point of call rather than silently falling through.
+ */
+export declare class UnsupportedMemoryBackendError extends Error {
+    readonly backend: MemoryBackendId;
+    constructor(backend: MemoryBackendId);
+}
+/**
+ * Map of backend-id to executor function. Any subset of
+ * {@link MemoryBackendId} values may be registered; unregistered
+ * backends throw at dispatch time.
+ */
+export type MemoryBackendRegistry<TTrace, TPayload> = Partial<Record<MemoryBackendId, MemoryBackendExecutor<TTrace, TPayload>>>;
+/**
+ * Built-in dispatcher that looks up a caller-supplied per-backend
+ * executor and invokes it with the query (+ optional payload).
+ *
+ * The generic parameters let each deployment type its trace shape and
+ * payload shape independently — a canonical-hybrid-only deployment can
+ * use `FunctionMemoryDispatcher<ScoredTrace, { topK: number }>`, while a
+ * mixed deployment can use `FunctionMemoryDispatcher<ScoredTrace, { topK:
+ * number; retrievalPolicy: MemoryRetrievalPolicy }>`.
+ *
+ * @example canonical-hybrid-only (simplest case)
+ * ```ts
+ * const dispatcher = new FunctionMemoryDispatcher<ScoredTrace, { topK: number }>({
+ *   'canonical-hybrid': async (query, { topK }) =>
+ *     mem.recall(query, { limit: topK }),
+ * });
+ * ```
+ *
+ * @example Production routing with three backends
+ * ```ts
+ * const dispatcher = new FunctionMemoryDispatcher<ScoredTrace, RetrievalPayload>({
+ *   'canonical-hybrid': async (q, p) => hybridRetriever.retrieve(q, p),
+ *   'observational-memory-v10': async (q, p) => omPipeline.recall(q, p),
+ *   'observational-memory-v11': async (q, p) => omPipelineV11.recall(q, p),
+ * });
+ * ```
+ */
+export declare class FunctionMemoryDispatcher<TTrace, TPayload = undefined> implements IMemoryDispatcher<TTrace, TPayload> {
+    private readonly registry;
+    constructor(registry: MemoryBackendRegistry<TTrace, TPayload>);
+    dispatch(args: MemoryDispatchArgs<TPayload>): Promise<MemoryDispatchResult<TTrace>>;
+}
+//# sourceMappingURL=dispatcher.d.ts.map

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

@@ -0,0 +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"}

package/dist/memory-router/dispatcher.js

@@ -0,0 +1,84 @@
+/**
+ * @file dispatcher.ts
+ * @description Backend-execution layer for {@link MemoryRouter}.
+ *
+ * A dispatcher turns a {@link MemoryBackendId} + a query into actual
+ * recall results. Because backend execution depends on how the caller's
+ * memory state is wired — `canonical-hybrid` needs only a query against a
+ * standing {@link Memory}, whereas `observational-memory-*` backends need
+ * ingest-time OM setup — the dispatcher is an injection point rather than
+ * a monolithic implementation.
+ *
+ * The shipping dispatcher, {@link FunctionMemoryDispatcher}, uses a
+ * routing-table-of-functions pattern: the caller provides `{ [backend]:
+ * (query, payload?) => Promise<traces> }` at construction, and the
+ * dispatcher picks the right function per call. This gives consumers:
+ *   - full control over per-backend execution (connect to a standing
+ *     HybridRetriever, a live OM ingest pipeline, a remote service, a
+ *     cache, anything),
+ *   - the ability to opt-out of backends they don't need (omitted keys
+ *     raise a typed {@link UnsupportedMemoryBackendError} at dispatch
+ *     time),
+ *   - full type-safety on the per-call `payload` (passed through to the
+ *     per-backend function verbatim).
+ *
+ * Callers who want to ship quickly with just canonical-hybrid can pass
+ * only `{ 'canonical-hybrid': (q) => mem.recall(q, { limit, policy }) }`
+ * and get end-to-end routing without touching the OM backends.
+ *
+ * @module @framers/agentos/memory-router/dispatcher
+ */
+/**
+ * Thrown when a dispatch call requests a backend that the dispatcher
+ * was not configured to support. Lets callers surface missing-backend
+ * bugs at the point of call rather than silently falling through.
+ */
+export class UnsupportedMemoryBackendError extends Error {
+    constructor(backend) {
+        super(`MemoryDispatcher: backend '${backend}' is not registered. ` +
+            `Supply an executor for this backend at construction time.`);
+        this.backend = backend;
+        this.name = 'UnsupportedMemoryBackendError';
+    }
+}
+/**
+ * Built-in dispatcher that looks up a caller-supplied per-backend
+ * executor and invokes it with the query (+ optional payload).
+ *
+ * The generic parameters let each deployment type its trace shape and
+ * payload shape independently — a canonical-hybrid-only deployment can
+ * use `FunctionMemoryDispatcher<ScoredTrace, { topK: number }>`, while a
+ * mixed deployment can use `FunctionMemoryDispatcher<ScoredTrace, { topK:
+ * number; retrievalPolicy: MemoryRetrievalPolicy }>`.
+ *
+ * @example canonical-hybrid-only (simplest case)
+ * ```ts
+ * const dispatcher = new FunctionMemoryDispatcher<ScoredTrace, { topK: number }>({
+ *   'canonical-hybrid': async (query, { topK }) =>
+ *     mem.recall(query, { limit: topK }),
+ * });
+ * ```
+ *
+ * @example Production routing with three backends
+ * ```ts
+ * const dispatcher = new FunctionMemoryDispatcher<ScoredTrace, RetrievalPayload>({
+ *   'canonical-hybrid': async (q, p) => hybridRetriever.retrieve(q, p),
+ *   'observational-memory-v10': async (q, p) => omPipeline.recall(q, p),
+ *   'observational-memory-v11': async (q, p) => omPipelineV11.recall(q, p),
+ * });
+ * ```
+ */
+export class FunctionMemoryDispatcher {
+    constructor(registry) {
+        this.registry = registry;
+    }
+    async dispatch(args) {
+        const executor = this.registry[args.backend];
+        if (!executor) {
+            throw new UnsupportedMemoryBackendError(args.backend);
+        }
+        const traces = await executor(args.query, args.payload);
+        return { traces, backend: args.backend };
+    }
+}
+//# sourceMappingURL=dispatcher.js.map

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

@@ -0,0 +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"}