@rudderjs/ai 1.4.0 → 1.6.0

package/dist/mcp/types.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Public types for `@rudderjs/ai/mcp`. Kept in a separate module so the
+ * client + server connectors can share them without circular imports.
+ */
+/**
+ * Configuration for spawning a local MCP server as a stdio subprocess.
+ * Mirrors `StdioServerParameters` from `@modelcontextprotocol/sdk` but is
+ * re-exported here so consumers don't need a direct SDK import for the
+ * common case.
+ */
+export interface StdioServerSpawn {
+    command: string;
+    args?: readonly string[];
+    /** Inherited from the parent process when omitted. */
+    env?: Readonly<Record<string, string>>;
+    /** Working directory for the spawned process. */
+    cwd?: string;
+}
+/**
+ * Anything `mcpClientTools()` accepts as the connection target.
+ *
+ * - `string` / `URL` — connects via the Streamable HTTP transport
+ * - `StdioServerSpawn` — spawns a subprocess and connects over stdio
+ * - existing `Client` instance — used as-is, lifecycle remains the caller's
+ *
+ * Implementation note: keeping `Client` as `unknown` here so the type union
+ * doesn't force a hard dep on `@modelcontextprotocol/sdk` at module load.
+ * The runtime code uses an instanceof check via dynamic import.
+ */
+export type McpClientTransport = string | URL | StdioServerSpawn | object;
+export interface McpClientToolsOptions {
+    /** Filter exposed tools — return `false` to drop a remote tool from the result. Defaults to all. */
+    filter?: (toolName: string) => boolean;
+    /** Prefix tool names to avoid collisions when wiring multiple remote servers. */
+    namePrefix?: string;
+    /**
+     * Forward MCP `notifications/progress` from the remote server as `tool-update`
+     * chunks during agent execution. Defaults to `true`.
+     */
+    streaming?: boolean;
+}
+export interface McpServerFromAgentOptions {
+    /** Server name advertised over MCP. Default: `${AgentClass.name}Server`. */
+    name?: string;
+    /** Server version. Default: `'1.0.0'`. */
+    version?: string;
+    /**
+     * Server instructions advertised over MCP — typically the agent's own
+     * system prompt. Default: tries `agent.instructions()`, falls back to undefined.
+     */
+    instructions?: string;
+    /**
+     * What to expose:
+     * - `'tools'` (default): one MCP tool per `agent.tools()` entry — external
+     *   MCP clients call them as if they were the server's own.
+     * - `'agent'`: one MCP tool `prompt(text: string)` that runs the whole agent
+     *   and returns the response text. Ship one agent, callable from any MCP client.
+     * - `'both'`: both of the above.
+     */
+    expose?: 'tools' | 'agent' | 'both';
+    /** Name of the synthetic prompt-tool when `expose: 'agent' | 'both'`. Default: agent class name. */
+    agentToolName?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/mcp/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/mcp/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,MAAM,CAAA;IACf,IAAI,CAAC,EAAI,SAAS,MAAM,EAAE,CAAA;IAC1B,sDAAsD;IACtD,GAAG,CAAC,EAAK,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;IACzC,iDAAiD;IACjD,GAAG,CAAC,EAAK,MAAM,CAAA;CAChB;AAED;;;;;;;;;;GAUG;AACH,MAAM,MAAM,kBAAkB,GAC1B,MAAM,GACN,GAAG,GACH,gBAAgB,GAChB,MAAM,CAAA;AAEV,MAAM,WAAW,qBAAqB;IACpC,oGAAoG;IACpG,MAAM,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAA;IACtC,iFAAiF;IACjF,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,CAAA;CACpB;AAED,MAAM,WAAW,yBAAyB;IACxC,4EAA4E;IAC5E,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,0CAA0C;IAC1C,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,OAAO,GAAG,OAAO,GAAG,MAAM,CAAA;IACnC,oGAAoG;IACpG,aAAa,CAAC,EAAE,MAAM,CAAA;CACvB"}

package/dist/mcp/types.js

@@ -0,0 +1,6 @@
+/**
+ * Public types for `@rudderjs/ai/mcp`. Kept in a separate module so the
+ * client + server connectors can share them without circular imports.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/mcp/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/mcp/types.ts"],"names":[],"mappings":"AAAA;;;GAGG"}

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

@@ -0,0 +1,121 @@
+/**
+ * `@rudderjs/ai/memory-embedding` — embedding-backed {@link UserMemory}
+ * for #A4 Phase 5.
+ *
+ * Composes Phase 4's {@link OrmUserMemory} with the embedding
+ * provider registered on {@link AiRegistry}: `remember()` embeds the
+ * fact and writes the Float32-packed vector into the row's
+ * `embedding` column; `recall()` embeds the query and ranks by
+ * cosine similarity. `forget()` / `forgetAll()` delegate to the
+ * inner store — the embedding lives in the same row, so deleting
+ * the row deletes the vector. GDPR right-to-be-forgotten cascades
+ * automatically.
+ *
+ * v1 is **pure-JS cosine over the user's full set** — fine up to
+ * a few thousand facts per user. For larger workloads, B7 lands a
+ * pgvector-backed `EmbeddingUserMemory` that pushes the dot-product
+ * into the database.
+ *
+ * @example
+ * ```ts
+ * import { OrmUserMemory } from '@rudderjs/ai/memory-orm'
+ * import { EmbeddingUserMemory } from '@rudderjs/ai/memory-embedding'
+ *
+ * const memory = new EmbeddingUserMemory({
+ *   inner: new OrmUserMemory(),
+ *   model: 'openai/text-embedding-3-small',
+ *   threshold: 0.5,    // cosine floor; matches below are dropped
+ * })
+ * ```
+ *
+ * **Pre-Phase-5 facts** (rows with `embedding === null`) fall back to
+ * token-overlap matching against the `fact` column — same shape as
+ * `MemoryUserMemory.recall()`. So upgrading from `OrmUserMemory` to
+ * `EmbeddingUserMemory` doesn't lose recall on existing rows; new
+ * `remember()` calls populate the embedding column going forward.
+ */
+import { OrmUserMemory } from '../memory-orm/index.js';
+import type { MemoryEntry, UserMemory } from '../types.js';
+export interface EmbeddingUserMemoryOptions {
+    /**
+     * The composed inner store. Must be {@link OrmUserMemory} for v1
+     * — the composer reads/writes the `embedding Bytes?` column on
+     * the same row. Other backends (Pinecone, Weaviate) implement
+     * their own.
+     */
+    inner: OrmUserMemory;
+    /**
+     * Embedding model id (`'<provider>/<model>'`). Used for both
+     * fact embedding on `remember()` and query embedding on
+     * `recall()`. Default: whatever `AI.embed()` picks (`AiRegistry`
+     * default).
+     */
+    model?: string;
+    /**
+     * Cosine-similarity floor in `[-1, 1]`. Matches below the
+     * threshold are dropped before sorting. Default `0` — return
+     * everything ranked. Tighten for higher precision; loosen for
+     * higher recall.
+     */
+    threshold?: number;
+    /**
+     * Optional fallback for rows whose `embedding` column is `null`
+     * (rows persisted without the embedding composer wired in).
+     *
+     * - `'token-overlap'` (default) — score 0 if any ≥3-char token
+     *   from the query appears in the row's `fact`. Lets you
+     *   upgrade `OrmUserMemory` → `EmbeddingUserMemory` without
+     *   losing recall on existing rows.
+     * - `'skip'` — drop null-embedding rows entirely.
+     */
+    nullEmbeddingFallback?: 'token-overlap' | 'skip';
+}
+export declare class EmbeddingUserMemory implements UserMemory {
+    private readonly inner;
+    private readonly model;
+    private readonly threshold;
+    private readonly fallback;
+    constructor(opts: EmbeddingUserMemoryOptions);
+    remember(userId: string, fact: string, opts?: {
+        tags?: string[];
+        score?: number;
+    }): Promise<MemoryEntry>;
+    recall(userId: string, query: string, opts?: {
+        limit?: number;
+        tags?: string[];
+    }): Promise<MemoryEntry[]>;
+    forget(userId: string, factId: string): Promise<void>;
+    list(userId: string, opts?: {
+        tags?: string[];
+        limit?: number;
+    }): Promise<MemoryEntry[]>;
+    forgetAll(userId: string): Promise<void>;
+    /**
+     * Single-string embedding via the {@link AI} facade. Returns the
+     * first (and only) embedding vector. Throws on provider/network
+     * failure; callers route through try/catch and degrade.
+     */
+    private embed;
+}
+/**
+ * Pack a `number[]` into a Float32 byte buffer. 4 bytes per dim;
+ * a 1536-dim OpenAI embedding compresses to 6144 bytes.
+ *
+ * Uses `ArrayBuffer` + `Float32Array` so the output is a portable
+ * `Uint8Array` (works in Node, browser, RN). Prisma's `Bytes`
+ * column accepts both `Uint8Array` and `Buffer`.
+ */
+export declare function serializeVector(v: number[]): Uint8Array;
+/**
+ * Reverse of {@link serializeVector}. Reads the underlying byte
+ * buffer as Float32 and returns a fresh `number[]` so callers can
+ * mutate without affecting the source row.
+ */
+export declare function deserializeVector(bytes: Uint8Array): number[];
+/**
+ * Cosine similarity in `[-1, 1]`. Returns `0` when either vector
+ * has zero magnitude, or when lengths don't match (defensive — should
+ * never happen if remember/recall use the same embedding model).
+ */
+export declare function cosineSimilarity(a: number[], b: number[]): number;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/memory-embedding/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAGH,OAAO,EAAE,aAAa,EAAoB,MAAM,wBAAwB,CAAA;AACxE,OAAO,KAAK,EACV,WAAW,EACX,UAAU,EACX,MAAM,aAAa,CAAA;AAEpB,MAAM,WAAW,0BAA0B;IACzC;;;;;OAKG;IACH,KAAK,EAAE,aAAa,CAAA;IACpB;;;;;OAKG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;IACd;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB;;;;;;;;;OASG;IACH,qBAAqB,CAAC,EAAE,eAAe,GAAG,MAAM,CAAA;CACjD;AAED,qBAAa,mBAAoB,YAAW,UAAU;IACpD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAkB;IACxC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAuB;IAC7C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAQ;IAClC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA0B;gBAEvC,IAAI,EAAE,0BAA0B;IAOtC,QAAQ,CACZ,MAAM,EAAE,MAAM,EACd,IAAI,EAAI,MAAM,EACd,IAAI,CAAC,EAAG;QAAE,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,GAC1C,OAAO,CAAC,WAAW,CAAC;IAkBjB,MAAM,CACV,MAAM,EAAE,MAAM,EACd,KAAK,EAAG,MAAM,EACd,IAAI,CAAC,EAAG;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE,GAC1C,OAAO,CAAC,WAAW,EAAE,CAAC;IA4CnB,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAMrD,IAAI,CACR,MAAM,EAAE,MAAM,EACd,IAAI,CAAC,EAAG;QAAE,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,GAC1C,OAAO,CAAC,WAAW,EAAE,CAAC;IAInB,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAK9C;;;;OAIG;YACW,KAAK;CAMpB;AAID;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,MAAM,EAAE,GAAG,UAAU,CAKvD;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,EAAE,CAK7D;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,EAAE,GAAG,MAAM,CAcjE"}

package/dist/memory-embedding/index.js

@@ -0,0 +1,229 @@
+/**
+ * `@rudderjs/ai/memory-embedding` — embedding-backed {@link UserMemory}
+ * for #A4 Phase 5.
+ *
+ * Composes Phase 4's {@link OrmUserMemory} with the embedding
+ * provider registered on {@link AiRegistry}: `remember()` embeds the
+ * fact and writes the Float32-packed vector into the row's
+ * `embedding` column; `recall()` embeds the query and ranks by
+ * cosine similarity. `forget()` / `forgetAll()` delegate to the
+ * inner store — the embedding lives in the same row, so deleting
+ * the row deletes the vector. GDPR right-to-be-forgotten cascades
+ * automatically.
+ *
+ * v1 is **pure-JS cosine over the user's full set** — fine up to
+ * a few thousand facts per user. For larger workloads, B7 lands a
+ * pgvector-backed `EmbeddingUserMemory` that pushes the dot-product
+ * into the database.
+ *
+ * @example
+ * ```ts
+ * import { OrmUserMemory } from '@rudderjs/ai/memory-orm'
+ * import { EmbeddingUserMemory } from '@rudderjs/ai/memory-embedding'
+ *
+ * const memory = new EmbeddingUserMemory({
+ *   inner: new OrmUserMemory(),
+ *   model: 'openai/text-embedding-3-small',
+ *   threshold: 0.5,    // cosine floor; matches below are dropped
+ * })
+ * ```
+ *
+ * **Pre-Phase-5 facts** (rows with `embedding === null`) fall back to
+ * token-overlap matching against the `fact` column — same shape as
+ * `MemoryUserMemory.recall()`. So upgrading from `OrmUserMemory` to
+ * `EmbeddingUserMemory` doesn't lose recall on existing rows; new
+ * `remember()` calls populate the embedding column going forward.
+ */
+import { AI } from '../facade.js';
+import { UserMemoryRecord } from '../memory-orm/index.js';
+export class EmbeddingUserMemory {
+    inner;
+    model;
+    threshold;
+    fallback;
+    constructor(opts) {
+        this.inner = opts.inner;
+        if (opts.model !== undefined)
+            this.model = opts.model;
+        this.threshold = opts.threshold ?? 0;
+        this.fallback = opts.nullEmbeddingFallback ?? 'token-overlap';
+    }
+    async remember(userId, fact, opts) {
+        const entry = await this.inner.remember(userId, fact, opts);
+        // Best-effort embed + persist. Failures are logged via the inner
+        // store still having the entry; we don't break the caller.
+        try {
+            const vector = await this.embed(fact);
+            await UserMemoryRecord.update(entry.id, {
+                embedding: serializeVector(vector),
+            });
+        }
+        catch {
+            // Embedding failed (network, missing peer SDK). The row is
+            // already in the store; recall will fall back to
+            // token-overlap if the column stays null. No-op.
+        }
+        return entry;
+    }
+    async recall(userId, query, opts) {
+        let queryVector = null;
+        try {
+            queryVector = await this.embed(query);
+        }
+        catch {
+            // Embed failed — fall through to token-overlap on every row.
+        }
+        const rows = await UserMemoryRecord.where('userId', userId).get();
+        const wanted = opts?.tags;
+        const queryTokens = tokenize(query);
+        const scored = [];
+        for (const row of rows) {
+            const entry = rowToEntry(row);
+            if (!matchesTags(entry, wanted))
+                continue;
+            let score;
+            if (queryVector !== null && row.embedding !== null && row.embedding !== undefined) {
+                const factVector = deserializeVector(row.embedding);
+                score = cosineSimilarity(queryVector, factVector);
+            }
+            else if (this.fallback === 'skip') {
+                continue;
+            }
+            else {
+                // token-overlap fallback — score 0 (mid-range) if any
+                // token matches, otherwise drop.
+                if (factHasAnyToken(entry.fact, queryTokens)) {
+                    score = 0;
+                }
+                else {
+                    continue;
+                }
+            }
+            if (score >= this.threshold) {
+                scored.push({ entry, score });
+            }
+        }
+        scored.sort((a, b) => b.score - a.score);
+        const capped = capLimit(scored, opts?.limit);
+        return capped.map(s => ({ ...s.entry, score: s.score }));
+    }
+    async forget(userId, factId) {
+        // The embedding lives in the same row — deleting via the inner
+        // store deletes the vector too. GDPR cascade is automatic.
+        return this.inner.forget(userId, factId);
+    }
+    async list(userId, opts) {
+        return this.inner.list(userId, opts);
+    }
+    async forgetAll(userId) {
+        if (!this.inner.forgetAll)
+            return;
+        return this.inner.forgetAll(userId);
+    }
+    /**
+     * Single-string embedding via the {@link AI} facade. Returns the
+     * first (and only) embedding vector. Throws on provider/network
+     * failure; callers route through try/catch and degrade.
+     */
+    async embed(text) {
+        const result = await AI.embed(text, this.model ? { model: this.model } : undefined);
+        const vec = result.embeddings[0];
+        if (!vec)
+            throw new Error('[RudderJS AI] embed() returned no vectors');
+        return vec;
+    }
+}
+// ─── Vector + similarity helpers (exported for tests + B7) ─────
+/**
+ * Pack a `number[]` into a Float32 byte buffer. 4 bytes per dim;
+ * a 1536-dim OpenAI embedding compresses to 6144 bytes.
+ *
+ * Uses `ArrayBuffer` + `Float32Array` so the output is a portable
+ * `Uint8Array` (works in Node, browser, RN). Prisma's `Bytes`
+ * column accepts both `Uint8Array` and `Buffer`.
+ */
+export function serializeVector(v) {
+    const buf = new ArrayBuffer(v.length * 4);
+    const view = new Float32Array(buf);
+    for (let i = 0; i < v.length; i++)
+        view[i] = v[i];
+    return new Uint8Array(buf);
+}
+/**
+ * Reverse of {@link serializeVector}. Reads the underlying byte
+ * buffer as Float32 and returns a fresh `number[]` so callers can
+ * mutate without affecting the source row.
+ */
+export function deserializeVector(bytes) {
+    // The `bytes.buffer` may be a slice; honor byteOffset + byteLength
+    // so we don't read into adjacent memory.
+    const view = new Float32Array(bytes.buffer, bytes.byteOffset, bytes.byteLength / 4);
+    return Array.from(view);
+}
+/**
+ * Cosine similarity in `[-1, 1]`. Returns `0` when either vector
+ * has zero magnitude, or when lengths don't match (defensive — should
+ * never happen if remember/recall use the same embedding model).
+ */
+export function cosineSimilarity(a, b) {
+    if (a.length !== b.length)
+        return 0;
+    let dot = 0;
+    let magA = 0;
+    let magB = 0;
+    for (let i = 0; i < a.length; i++) {
+        const ai = a[i];
+        const bi = b[i];
+        dot += ai * bi;
+        magA += ai * ai;
+        magB += bi * bi;
+    }
+    if (magA === 0 || magB === 0)
+        return 0;
+    return dot / (Math.sqrt(magA) * Math.sqrt(magB));
+}
+// ─── Internal helpers ─────────────────────────────────────
+function rowToEntry(row) {
+    const tags = row.getTags();
+    const out = {
+        id: row.id,
+        userId: row.userId,
+        fact: row.fact,
+        createdAt: row.createdAt,
+    };
+    if (tags.length > 0)
+        out.tags = tags;
+    if (row.score != null)
+        out.score = row.score;
+    if (row.updatedAt != null)
+        out.updatedAt = row.updatedAt;
+    return out;
+}
+function tokenize(s) {
+    const out = new Set();
+    for (const tok of s.toLowerCase().split(/[^a-z0-9]+/)) {
+        if (tok.length >= 3)
+            out.add(tok);
+    }
+    return out;
+}
+function factHasAnyToken(fact, queryTokens) {
+    if (queryTokens.size === 0)
+        return true;
+    const factTokens = tokenize(fact);
+    for (const t of factTokens)
+        if (queryTokens.has(t))
+            return true;
+    return false;
+}
+function matchesTags(entry, wanted) {
+    if (!wanted || wanted.length === 0)
+        return true;
+    if (!entry.tags || entry.tags.length === 0)
+        return false;
+    return wanted.every(t => entry.tags.includes(t));
+}
+function capLimit(items, limit) {
+    return limit !== undefined && limit > 0 ? items.slice(0, limit) : items;
+}
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/memory-embedding/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH,OAAO,EAAE,EAAE,EAAE,MAAM,cAAc,CAAA;AACjC,OAAO,EAAiB,gBAAgB,EAAE,MAAM,wBAAwB,CAAA;AAyCxE,MAAM,OAAO,mBAAmB;IACb,KAAK,CAAkB;IACvB,KAAK,CAAuB;IAC5B,SAAS,CAAQ;IACjB,QAAQ,CAA0B;IAEnD,YAAY,IAAgC;QAC1C,IAAI,CAAC,KAAK,GAAO,IAAI,CAAC,KAAK,CAAA;QAC3B,IAAI,IAAI,CAAC,KAAK,KAAK,SAAS;YAAE,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAA;QACrD,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,SAAS,IAAI,CAAC,CAAA;QACpC,IAAI,CAAC,QAAQ,GAAI,IAAI,CAAC,qBAAqB,IAAI,eAAe,CAAA;IAChE,CAAC;IAED,KAAK,CAAC,QAAQ,CACZ,MAAc,EACd,IAAc,EACd,IAA2C;QAE3C,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,CAAA;QAE3D,iEAAiE;QACjE,2DAA2D;QAC3D,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAA;YACrC,MAAM,gBAAgB,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,EAAE;gBACtC,SAAS,EAAE,eAAe,CAAC,MAAM,CAAC;aACnC,CAAC,CAAA;QACJ,CAAC;QAAC,MAAM,CAAC;YACP,2DAA2D;YAC3D,iDAAiD;YACjD,iDAAiD;QACnD,CAAC;QACD,OAAO,KAAK,CAAA;IACd,CAAC;IAED,KAAK,CAAC,MAAM,CACV,MAAc,EACd,KAAc,EACd,IAA2C;QAE3C,IAAI,WAAW,GAAoB,IAAI,CAAA;QACvC,IAAI,CAAC;YACH,WAAW,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAA;QACvC,CAAC;QAAC,MAAM,CAAC;YACP,6DAA6D;QAC/D,CAAC;QAED,MAAM,IAAI,GAAI,MAAM,gBAAgB,CAAC,KAAK,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC,GAAG,EAAmC,CAAA;QACnG,MAAM,MAAM,GAAG,IAAI,EAAE,IAAI,CAAA;QAEzB,MAAM,WAAW,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAA;QAEnC,MAAM,MAAM,GAAiD,EAAE,CAAA;QAC/D,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;YACvB,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,CAAC,CAAA;YAC7B,IAAI,CAAC,WAAW,CAAC,KAAK,EAAE,MAAM,CAAC;gBAAE,SAAQ;YAEzC,IAAI,KAAa,CAAA;YACjB,IAAI,WAAW,KAAK,IAAI,IAAI,GAAG,CAAC,SAAS,KAAK,IAAI,IAAI,GAAG,CAAC,SAAS,KAAK,SAAS,EAAE,CAAC;gBAClF,MAAM,UAAU,GAAG,iBAAiB,CAAC,GAAG,CAAC,SAAS,CAAC,CAAA;gBACnD,KAAK,GAAG,gBAAgB,CAAC,WAAW,EAAE,UAAU,CAAC,CAAA;YACnD,CAAC;iBAAM,IAAI,IAAI,CAAC,QAAQ,KAAK,MAAM,EAAE,CAAC;gBACpC,SAAQ;YACV,CAAC;iBAAM,CAAC;gBACN,sDAAsD;gBACtD,iCAAiC;gBACjC,IAAI,eAAe,CAAC,KAAK,CAAC,IAAI,EAAE,WAAW,CAAC,EAAE,CAAC;oBAC7C,KAAK,GAAG,CAAC,CAAA;gBACX,CAAC;qBAAM,CAAC;oBACN,SAAQ;gBACV,CAAC;YACH,CAAC;YAED,IAAI,KAAK,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;gBAC5B,MAAM,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAA;YAC/B,CAAC;QACH,CAAC;QAED,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,CAAA;QACxC,MAAM,MAAM,GAAG,QAAQ,CAAC,MAAM,EAAE,IAAI,EAAE,KAAK,CAAC,CAAA;QAC5C,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,CAAA;IAC1D,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,MAAc,EAAE,MAAc;QACzC,+DAA+D;QAC/D,2DAA2D;QAC3D,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC1C,CAAC;IAED,KAAK,CAAC,IAAI,CACR,MAAc,EACd,IAA2C;QAE3C,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,CAAA;IACtC,CAAC;IAED,KAAK,CAAC,SAAS,CAAC,MAAc;QAC5B,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,SAAS;YAAE,OAAM;QACjC,OAAO,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,MAAM,CAAC,CAAA;IACrC,CAAC;IAED;;;;OAIG;IACK,KAAK,CAAC,KAAK,CAAC,IAAY;QAC9B,MAAM,MAAM,GAAG,MAAM,EAAE,CAAC,KAAK,CAAC,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAA;QACnF,MAAM,GAAG,GAAG,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC,CAAA;QAChC,IAAI,CAAC,GAAG;YAAE,MAAM,IAAI,KAAK,CAAC,2CAA2C,CAAC,CAAA;QACtE,OAAO,GAAG,CAAA;IACZ,CAAC;CACF;AAED,kEAAkE;AAElE;;;;;;;GAOG;AACH,MAAM,UAAU,eAAe,CAAC,CAAW;IACzC,MAAM,GAAG,GAAI,IAAI,WAAW,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAA;IAC1C,MAAM,IAAI,GAAG,IAAI,YAAY,CAAC,GAAG,CAAC,CAAA;IAClC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,EAAE;QAAE,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAE,CAAA;IAClD,OAAO,IAAI,UAAU,CAAC,GAAG,CAAC,CAAA;AAC5B,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAAiB;IACjD,mEAAmE;IACnE,yCAAyC;IACzC,MAAM,IAAI,GAAG,IAAI,YAAY,CAAC,KAAK,CAAC,MAAM,EAAE,KAAK,CAAC,UAAU,EAAE,KAAK,CAAC,UAAU,GAAG,CAAC,CAAC,CAAA;IACnF,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;AACzB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAAC,CAAW,EAAE,CAAW;IACvD,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,MAAM;QAAE,OAAO,CAAC,CAAA;IACnC,IAAI,GAAG,GAAG,CAAC,CAAA;IACX,IAAI,IAAI,GAAG,CAAC,CAAA;IACZ,IAAI,IAAI,GAAG,CAAC,CAAA;IACZ,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QAClC,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC,CAAE,CAAA;QAChB,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC,CAAE,CAAA;QAChB,GAAG,IAAK,EAAE,GAAG,EAAE,CAAA;QACf,IAAI,IAAI,EAAE,GAAG,EAAE,CAAA;QACf,IAAI,IAAI,EAAE,GAAG,EAAE,CAAA;IACjB,CAAC;IACD,IAAI,IAAI,KAAK,CAAC,IAAI,IAAI,KAAK,CAAC;QAAE,OAAO,CAAC,CAAA;IACtC,OAAO,GAAG,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAA;AAClD,CAAC;AAED,6DAA6D;AAE7D,SAAS,UAAU,CAAC,GAAqB;IACvC,MAAM,IAAI,GAAG,GAAG,CAAC,OAAO,EAAE,CAAA;IAC1B,MAAM,GAAG,GAAgB;QACvB,EAAE,EAAS,GAAG,CAAC,EAAE;QACjB,MAAM,EAAK,GAAG,CAAC,MAAM;QACrB,IAAI,EAAO,GAAG,CAAC,IAAI;QACnB,SAAS,EAAE,GAAG,CAAC,SAAS;KACzB,CAAA;IACD,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC;QAAS,GAAG,CAAC,IAAI,GAAQ,IAAI,CAAA;IAChD,IAAI,GAAG,CAAC,KAAK,IAAI,IAAI;QAAO,GAAG,CAAC,KAAK,GAAO,GAAG,CAAC,KAAK,CAAA;IACrD,IAAI,GAAG,CAAC,SAAS,IAAI,IAAI;QAAG,GAAG,CAAC,SAAS,GAAG,GAAG,CAAC,SAAS,CAAA;IACzD,OAAO,GAAG,CAAA;AACZ,CAAC;AAED,SAAS,QAAQ,CAAC,CAAS;IACzB,MAAM,GAAG,GAAG,IAAI,GAAG,EAAU,CAAA;IAC7B,KAAK,MAAM,GAAG,IAAI,CAAC,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,YAAY,CAAC,EAAE,CAAC;QACtD,IAAI,GAAG,CAAC,MAAM,IAAI,CAAC;YAAE,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;IACnC,CAAC;IACD,OAAO,GAAG,CAAA;AACZ,CAAC;AAED,SAAS,eAAe,CAAC,IAAY,EAAE,WAAwB;IAC7D,IAAI,WAAW,CAAC,IAAI,KAAK,CAAC;QAAE,OAAO,IAAI,CAAA;IACvC,MAAM,UAAU,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAA;IACjC,KAAK,MAAM,CAAC,IAAI,UAAU;QAAE,IAAI,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC;YAAE,OAAO,IAAI,CAAA;IAC/D,OAAO,KAAK,CAAA;AACd,CAAC;AAED,SAAS,WAAW,CAAC,KAAkB,EAAE,MAA4B;IACnE,IAAI,CAAC,MAAM,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAA;IAC/C,IAAI,CAAC,KAAK,CAAC,IAAI,IAAI,KAAK,CAAC,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,KAAK,CAAA;IACxD,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,IAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAA;AACnD,CAAC;AAED,SAAS,QAAQ,CAAI,KAAU,EAAE,KAAyB;IACxD,OAAO,KAAK,KAAK,SAAS,IAAI,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAA;AACzE,CAAC"}

package/dist/memory-extract.d.ts

@@ -0,0 +1,60 @@
+import type { AiMiddleware, MemoryEntry, RemembersSpec } from './types.js';
+import type { UserMemoryLookup } from './memory.js';
+export interface MemoryExtractOptions {
+    /**
+     * Override the {@link UserMemory} lookup. Defaults to the module-level
+     * `resolveUserMemory()` registry that `AiProvider` writes to from
+     * `AiConfig.memory`. Tests pass a closure to inject a fake.
+     */
+    lookup?: UserMemoryLookup;
+    /**
+     * Confidence floor for the small model's self-rated `score`. Facts
+     * with a score < threshold are dropped before any `remember()` call.
+     * Default `0.7`.
+     *
+     * **Tuning note (poisoning mitigation):** the threshold is the v1
+     * defense against a malicious user planting adversarial "facts." A
+     * low threshold accepts more spam; a high threshold filters useful
+     * signal. Pair with `MemoryExtractOptions.onExtracted` for an audit
+     * log when you ship extract to production.
+     */
+    threshold?: number;
+    /**
+     * Called after a successful extract with the entries that survived
+     * the threshold filter and were written to the store. Use this to
+     * stream entries into telescope, an audit log, or test assertions.
+     */
+    onExtracted?: (entries: MemoryEntry[]) => void;
+    /**
+     * Called when extract fails — small-model network error, JSON parse
+     * failure, schema-validation rejection, or `mem.remember()` throw.
+     * Errors are otherwise swallowed; the parent run never breaks.
+     */
+    onError?: (err: unknown) => void;
+}
+/**
+ * Post-conversation {@link AiMiddleware} that asks a small model to
+ * distill the latest `[user, assistant]` turn into durable facts and
+ * writes the survivors (above `threshold`) to the registered
+ * {@link UserMemory}. Auto-installed by `Agent.prompt` /
+ * `Agent.stream` when `Agent.remembers().extract === 'auto'` and
+ * `extractWith` is set; can also be dropped into `Agent.middleware()`
+ * manually.
+ *
+ * Runs in `onFinish` — only fires on a successful loop, so failed
+ * runs don't pollute memory. Failures inside the extract path
+ * (network, JSON parse, zod validation, `remember()` throw) are
+ * routed through `MemoryExtractOptions.onError` and otherwise
+ * swallowed; the parent prompt never breaks because of memory work.
+ *
+ * **Auto-installed extracts skip continuation calls** (`options.messages`
+ * set) at the host level — the same way auto-inject does. Manually
+ * installed extracts always run.
+ *
+ * **Pitfall — memory poisoning:** auto-extraction lets a malicious
+ * user plant adversarial "facts." The threshold (default 0.7) is the
+ * baseline defense; pair with `onExtracted` for an audit log when you
+ * ship to production. A content-filter middleware is a follow-up.
+ */
+export declare function withMemoryExtract(spec: RemembersSpec, opts?: MemoryExtractOptions): AiMiddleware;
+//# sourceMappingURL=memory-extract.d.ts.map

package/dist/memory-extract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-extract.d.ts","sourceRoot":"","sources":["../src/memory-extract.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAEV,YAAY,EAEZ,WAAW,EACX,aAAa,EACd,MAAM,YAAY,CAAA;AACnB,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA;AAEnD,MAAM,WAAW,oBAAoB;IACnC;;;;OAIG;IACH,MAAM,CAAC,EAAO,gBAAgB,CAAA;IAC9B;;;;;;;;;;OAUG;IACH,SAAS,CAAC,EAAI,MAAM,CAAA;IACpB;;;;OAIG;IACH,WAAW,CAAC,EAAE,CAAC,OAAO,EAAE,WAAW,EAAE,KAAK,IAAI,CAAA;IAC9C;;;;OAIG;IACH,OAAO,CAAC,EAAM,CAAC,GAAG,EAAE,OAAO,KAAK,IAAI,CAAA;CACrC;AAuBD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,aAAa,EACnB,IAAI,GAAE,oBAAyB,GAC9B,YAAY,CAwDd"}

package/dist/memory-extract.js

@@ -0,0 +1,163 @@
+import { z } from 'zod';
+import { agent, resolveUserMemory } from './agent.js';
+import { Output } from './output.js';
+/**
+ * The shape we ask the small model to fill in when distilling facts.
+ * `score` is the model's self-rated confidence in [0, 1]; tags are
+ * additive — the spec's `tags` are unioned in regardless.
+ */
+const ExtractedFactsSchema = z.object({
+    facts: z.array(z.object({
+        fact: z.string().min(1),
+        score: z.number().min(0).max(1),
+        tags: z.array(z.string()).optional(),
+    })),
+});
+const EXTRACT_INSTRUCTIONS = [
+    'You distill durable facts about a USER from a single conversation turn.',
+    'A "durable fact" is something true about the user that future conversations would benefit from knowing — preferences, identifying details, ongoing projects, persistent constraints.',
+    'Skip anything specific to this conversation, ephemeral state, or already-obvious context.',
+    'Self-rate each fact\'s confidence in [0, 1]; the host filters out anything below the threshold.',
+    'If nothing is worth remembering, return {"facts": []}.',
+].join(' ');
+/**
+ * Post-conversation {@link AiMiddleware} that asks a small model to
+ * distill the latest `[user, assistant]` turn into durable facts and
+ * writes the survivors (above `threshold`) to the registered
+ * {@link UserMemory}. Auto-installed by `Agent.prompt` /
+ * `Agent.stream` when `Agent.remembers().extract === 'auto'` and
+ * `extractWith` is set; can also be dropped into `Agent.middleware()`
+ * manually.
+ *
+ * Runs in `onFinish` — only fires on a successful loop, so failed
+ * runs don't pollute memory. Failures inside the extract path
+ * (network, JSON parse, zod validation, `remember()` throw) are
+ * routed through `MemoryExtractOptions.onError` and otherwise
+ * swallowed; the parent prompt never breaks because of memory work.
+ *
+ * **Auto-installed extracts skip continuation calls** (`options.messages`
+ * set) at the host level — the same way auto-inject does. Manually
+ * installed extracts always run.
+ *
+ * **Pitfall — memory poisoning:** auto-extraction lets a malicious
+ * user plant adversarial "facts." The threshold (default 0.7) is the
+ * baseline defense; pair with `onExtracted` for an audit log when you
+ * ship to production. A content-filter middleware is a follow-up.
+ */
+export function withMemoryExtract(spec, opts = {}) {
+    const lookup = opts.lookup ?? resolveUserMemory;
+    const threshold = opts.threshold ?? 0.7;
+    const wrapper = Output.object({ schema: ExtractedFactsSchema });
+    return {
+        name: 'memory-extract',
+        async onFinish(ctx) {
+            try {
+                if (spec.extract !== 'auto')
+                    return;
+                if (!spec.extractWith)
+                    return;
+                const mem = lookup();
+                if (!mem)
+                    return;
+                const turn = extractLatestTurn(ctx.messages);
+                if (!turn)
+                    return;
+                const extractor = agent({
+                    instructions: `${EXTRACT_INSTRUCTIONS}\n\n${wrapper.toSystemPrompt()}`,
+                    model: spec.extractWith,
+                });
+                const prompt = [
+                    `User said: ${JSON.stringify(turn.user)}`,
+                    `Assistant replied: ${JSON.stringify(turn.assistant)}`,
+                    '',
+                    'Extract durable facts about the USER from the above. Return strictly valid JSON.',
+                ].join('\n');
+                const response = await extractor.prompt(prompt);
+                const parsed = wrapper.parse(response.text);
+                const surviving = parsed.facts.filter(f => f.score >= threshold);
+                if (surviving.length === 0) {
+                    opts.onExtracted?.([]);
+                    return;
+                }
+                const tagsFromSpec = spec.tags ?? [];
+                const written = [];
+                for (const f of surviving) {
+                    const merged = mergeTags(f.tags, tagsFromSpec);
+                    const entry = await mem.remember(spec.user, f.fact, {
+                        score: f.score,
+                        ...(merged.length > 0 ? { tags: merged } : {}),
+                    });
+                    written.push(entry);
+                }
+                opts.onExtracted?.(written);
+            }
+            catch (err) {
+                opts.onError?.(err);
+                // Never break the parent run.
+            }
+        },
+    };
+}
+// ─── Helpers ──────────────────────────────────────────────
+/**
+ * Walk `messages` from the end and return the most recent
+ * `(user, assistant)` pair where the assistant message follows the
+ * user message. Skips trailing `tool` messages so multi-step tool
+ * loops still surface the original user request and the model's
+ * final synthesis.
+ *
+ * Returns `null` when:
+ * - the loop didn't reach a final assistant message (stopped on a
+ *   client-tool pause, approval gate, or handoff), or
+ * - the assistant message has no extractable text content.
+ */
+function extractLatestTurn(messages) {
+    let assistantText = null;
+    let lastAssistantIdx = -1;
+    // Walk backwards looking for the LAST assistant message that's a
+    // text reply (not a tool-calls message).
+    for (let i = messages.length - 1; i >= 0; i--) {
+        const m = messages[i];
+        if (!m || m.role !== 'assistant')
+            continue;
+        if (m.toolCalls && m.toolCalls.length > 0)
+            continue; // tool-call step, not a final reply
+        const text = contentToString(m.content);
+        if (text.length === 0)
+            continue;
+        assistantText = text;
+        lastAssistantIdx = i;
+        break;
+    }
+    if (assistantText === null || lastAssistantIdx === -1)
+        return null;
+    // Find the most recent user message before that assistant message.
+    for (let i = lastAssistantIdx - 1; i >= 0; i--) {
+        const m = messages[i];
+        if (!m || m.role !== 'user')
+            continue;
+        const text = contentToString(m.content);
+        if (text.length === 0)
+            continue;
+        return { user: text, assistant: assistantText };
+    }
+    return null;
+}
+function contentToString(content) {
+    if (typeof content === 'string')
+        return content;
+    const out = [];
+    for (const p of content) {
+        if (p.type === 'text' && typeof p.text === 'string')
+            out.push(p.text);
+    }
+    return out.join('\n');
+}
+function mergeTags(modelTags, specTags) {
+    if (!modelTags || modelTags.length === 0)
+        return [...specTags];
+    if (specTags.length === 0)
+        return [...modelTags];
+    return Array.from(new Set([...modelTags, ...specTags]));
+}
+//# sourceMappingURL=memory-extract.js.map