@framers/agentos 0.2.6 → 0.2.8

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"}

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

@@ -0,0 +1,126 @@
+/**
+ * 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';
+export type { CalibrationSample, CalibrationCell, AggregatedCalibration, AdaptivePresetRule, SelectByPresetArgs, BuildAdaptiveRoutingTableArgs, AdaptiveMemoryRouterOptions, } from './adaptive.js';
+export { aggregateCalibration, selectByPreset, buildAdaptiveRoutingTable, AdaptiveMemoryRouter, } from './adaptive.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;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"}

package/dist/memory-router/index.js

@@ -0,0 +1,122 @@
+/**
+ * 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';
+export { aggregateCalibration, selectByPreset, buildAdaptiveRoutingTable, AdaptiveMemoryRouter, } from './adaptive.js';
+//# sourceMappingURL=index.js.map