@rudderjs/ai 1.5.0 → 1.6.0

package/dist/memory-inject.js

@@ -0,0 +1,135 @@
+import { resolveUserMemory } from './agent.js';
+/**
+ * Pre-prompt {@link AiMiddleware} that consults a {@link UserMemory}, picks
+ * facts relevant to the latest user input, and prepends them to the
+ * agent's system message as a fenced `<user-memory>…</user-memory>`
+ * block. Auto-installed by `Agent.prompt` / `Agent.stream` when
+ * `Agent.remembers()` returns `{ inject: 'auto', … }`; can also be
+ * dropped into `Agent.middleware()` manually.
+ *
+ * Runs in `onStart` (async) — `onConfig` is sync and `recall()` is not.
+ * Mutates `ctx.messages[0]` (the system message) in place; the agent
+ * loop's `messages` array is the same reference, so the model sees the
+ * augmented prompt on the very next provider call.
+ *
+ * Skips silently when:
+ * - no `UserMemory` is registered (lookup returns `undefined`)
+ * - no user message exists in `ctx.messages` (continuation flow where
+ *   the trailing message is `tool` / `assistant`)
+ * - `recall()` returns no facts
+ * - the rendered block doesn't fit even one fact under
+ *   `spec.injectTokenBudget`
+ */
+export function withMemoryInject(spec, opts = {}) {
+    const lookup = opts.lookup ?? resolveUserMemory;
+    const estimate = opts.estimateTokens ?? defaultEstimateTokens;
+    return {
+        name: 'memory-inject',
+        async onStart(ctx) {
+            const userText = findLatestUserText(ctx.messages);
+            if (!userText)
+                return;
+            const mem = lookup();
+            if (!mem)
+                return;
+            const recallOpts = {};
+            if (spec.injectLimit !== undefined)
+                recallOpts.limit = spec.injectLimit;
+            if (spec.tags !== undefined)
+                recallOpts.tags = spec.tags;
+            const facts = await mem.recall(spec.user, userText, recallOpts);
+            if (facts.length === 0)
+                return;
+            const trimmed = applyTokenBudget(facts, spec.injectTokenBudget, estimate);
+            if (trimmed.length === 0)
+                return;
+            const block = renderMemoryBlock(trimmed);
+            const sys = ctx.messages[0];
+            if (!sys || sys.role !== 'system')
+                return;
+            const original = systemContentToString(sys);
+            ctx.messages[0] = { role: 'system', content: `${original}\n\n${block}` };
+        },
+    };
+}
+// ─── Helpers ──────────────────────────────────────────────
+function defaultEstimateTokens(text) {
+    // ~4 chars/token works for English; gpt-tokenizer adds a runtime dep
+    // we don't want to make mandatory just for a budget approximation.
+    return Math.ceil(text.length / 4);
+}
+/**
+ * Walk `messages` from the end and return the text of the most recent
+ * `role: 'user'` entry. Returns `null` when:
+ * - no user message exists (the loop is in a continuation flow where
+ *   `options.messages` was passed and ends with `tool`/`assistant`), or
+ * - the user message has only non-text content parts.
+ *
+ * The rationale for "latest user" rather than "all user history": the
+ * search query that maps best to recall accuracy is the user's current
+ * request. Earlier turns already shaped the loaded conversation
+ * history, which the persistence layer handles separately.
+ */
+function findLatestUserText(messages) {
+    for (let i = messages.length - 1; i >= 0; i--) {
+        const m = messages[i];
+        if (m && m.role === 'user') {
+            const text = userContentToString(m);
+            return text.length > 0 ? text : null;
+        }
+    }
+    return null;
+}
+function userContentToString(m) {
+    if (typeof m.content === 'string')
+        return m.content;
+    return contentPartsToString(m.content);
+}
+function systemContentToString(m) {
+    if (typeof m.content === 'string')
+        return m.content;
+    return contentPartsToString(m.content);
+}
+function contentPartsToString(parts) {
+    const out = [];
+    for (const p of parts) {
+        if (p.type === 'text' && typeof p.text === 'string')
+            out.push(p.text);
+    }
+    return out.join('\n');
+}
+/**
+ * If `budget` is set, sort facts by score descending (undefined scores
+ * treated as 0.5 — neutral) and accumulate until the rendered block's
+ * estimated tokens would exceed `budget`. Returns the accepted prefix.
+ *
+ * If `budget` is unset, returns `facts` unchanged.
+ */
+function applyTokenBudget(facts, budget, estimate) {
+    if (budget === undefined || budget <= 0)
+        return facts;
+    // Sort by score desc; undefined → 0.5 so user-asserted facts (no
+    // score) tie with mid-confidence model-extracted facts.
+    const sorted = [...facts].sort((a, b) => (b.score ?? 0.5) - (a.score ?? 0.5));
+    // Render incrementally to account for the wrapper overhead.
+    const accepted = [];
+    for (const f of sorted) {
+        const candidate = renderMemoryBlock([...accepted, f]);
+        if (estimate(candidate) > budget)
+            break;
+        accepted.push(f);
+    }
+    return accepted;
+}
+/**
+ * Render the prepended block. The fenced `<user-memory>` tag gives
+ * downstream systems (telescope, evals, screenshots) a stable hook to
+ * detect / strip injected memory, and signals the model that the
+ * content is provided by the framework rather than written into the
+ * agent's instructions.
+ */
+function renderMemoryBlock(facts) {
+    const lines = facts.map(f => `- ${f.fact}`);
+    return `<user-memory>\n${lines.join('\n')}\n</user-memory>`;
+}
+//# sourceMappingURL=memory-inject.js.map

package/dist/memory-inject.js.map

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

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

@@ -0,0 +1,118 @@
+/**
+ * `@rudderjs/ai/memory-orm` — ORM-backed {@link UserMemory} for #A4 Phase 4.
+ *
+ * Stores per-user facts in a `UserMemory` table via the registered
+ * `@rudderjs/orm` adapter (Prisma today; Drizzle as well once the user's
+ * tables are wired). Drop-in alongside Phase 1's in-process
+ * `MemoryUserMemory`.
+ *
+ * Wire it from your AI config:
+ *
+ * ```ts
+ * // config/ai.ts
+ * import type { AiConfig } from '@rudderjs/ai'
+ * import { OrmUserMemory } from '@rudderjs/ai/memory-orm'
+ *
+ * export default {
+ *   default: 'anthropic/claude-sonnet-4-5',
+ *   providers: { ... },
+ *   memory: new OrmUserMemory(),
+ * } satisfies AiConfig
+ * ```
+ *
+ * The schema lives at `@rudderjs/ai/memory-orm`'s {@link userMemoryPrismaSchema}
+ * — copy it into your Prisma schema. The optional `embedding Bytes?`
+ * column is shipped here in Phase 4 (intentionally nullable) so Phase 5's
+ * `EmbeddingUserMemory` can populate it without forcing an additive
+ * migration.
+ */
+import { Model } from '@rudderjs/orm';
+import type { MemoryEntry, UserMemory } from '../types.js';
+/**
+ * The Model row backing {@link OrmUserMemory}. Exposed so apps that
+ * want their own queries (admin views, audit dumps) can use the
+ * familiar `UserMemoryRecord.where(...).get()` instead of routing
+ * everything through the {@link UserMemory} interface.
+ *
+ * Tags persist as a JSON-encoded string in the `tags` column — both
+ * Prisma's portable `String?` and Drizzle's `text` work without
+ * needing native array columns. The {@link UserMemory.recall} path
+ * filters tags in JavaScript for the same reason.
+ *
+ * The `embedding Bytes?` column is in the schema as of Phase 4
+ * (nullable) so `@rudderjs/ai/memory-embedding`'s `EmbeddingUserMemory`
+ * (Phase 5) writes the Float32-packed vector here on `remember()` and
+ * reads it for cosine recall. `OrmUserMemory` ignores it — the
+ * column stays `null` for any row stored without the embedding
+ * composer.
+ */
+export declare class UserMemoryRecord extends Model {
+    static table: string;
+    static fillable: string[];
+    id: string;
+    userId: string;
+    fact: string;
+    /** JSON-encoded `string[]` or null. Use `getTags()` for the parsed shape. */
+    tags: string | null;
+    score: number | null;
+    /**
+     * Float32-packed vector serialized via
+     * `@rudderjs/ai/memory-embedding`'s `serializeVector` /
+     * `deserializeVector`. `null` when the row was stored without the
+     * embedding composer (Phase 4-only setups).
+     */
+    embedding: Uint8Array | null;
+    createdAt: Date;
+    updatedAt: Date | null;
+    /** Parsed tags array; empty when nothing was stored. */
+    getTags(): string[];
+}
+/**
+ * `UserMemory` implementation that persists rows to the registered
+ * ORM adapter. Designed for production use — the in-process
+ * `MemoryUserMemory` is for tests and dev.
+ *
+ * Adapter coverage:
+ * - Prisma — works out of the box; copy {@link userMemoryPrismaSchema}
+ *   into your schema.
+ * - Drizzle — works once you define a table matching the schema's
+ *   columns and register it via `tables: { userMemory: <table> }` on
+ *   the `drizzle()` config.
+ *
+ * Recall semantics: case-insensitive **token-OR-LIKE** matching against
+ * the `fact` column. The query is tokenized on non-alphanumeric
+ * boundaries (≥3-char tokens) and any row whose `fact` matches at
+ * least one token via `LIKE %tok%` is returned. Mirrors Phase 1's
+ * `MemoryUserMemory.recall()` behavior so the two backends are
+ * swap-compatible. Tag scope is applied JS-side after fetch — pushing
+ * tag-array filtering into the WHERE is adapter-specific and lands in a
+ * follow-up.
+ */
+export declare class OrmUserMemory implements UserMemory {
+    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>;
+}
+/**
+ * Reference Prisma schema for `OrmUserMemory`. Copy into your
+ * `prisma/schema/<file>.prisma` (or paste alongside an existing
+ * model). The `embedding Bytes?` column is intentionally nullable so
+ * Phase 5's `EmbeddingUserMemory` becomes additive — no schema
+ * migration when you upgrade.
+ *
+ * SQLite stores `Bytes` as `BLOB`; Postgres stores it as `bytea`.
+ * Both work for the dot-product implementation Phase 5 will use.
+ */
+export declare const userMemoryPrismaSchema = "model UserMemory {\n  id        String   @id @default(cuid())\n  userId    String\n  fact      String\n  /// JSON-encoded `string[]` of tags, or null\n  tags      String?\n  /// Confidence score in [0, 1] \u2014 extract sets this from the model's self-rating\n  score     Float?\n  /// Phase 5 \u2014 vector embedding for cosine recall (nullable so Phase 4 ignores it)\n  embedding Bytes?\n  createdAt DateTime @default(now())\n  updatedAt DateTime @updatedAt\n\n  @@index([userId])\n}\n";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/memory-orm/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,EAAE,KAAK,EAAE,MAAM,eAAe,CAAA;AACrC,OAAO,KAAK,EACV,WAAW,EACX,UAAU,EACX,MAAM,aAAa,CAAA;AAIpB;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,OAAgB,KAAK,SAAe;IAEpC,OAAgB,QAAQ,WAAmD;IAEnE,EAAE,EAAS,MAAM,CAAA;IACjB,MAAM,EAAK,MAAM,CAAA;IACjB,IAAI,EAAO,MAAM,CAAA;IACzB,6EAA6E;IACrE,IAAI,EAAO,MAAM,GAAG,IAAI,CAAA;IACxB,KAAK,EAAM,MAAM,GAAG,IAAI,CAAA;IAChC;;;;;OAKG;IACK,SAAS,EAAE,UAAU,GAAG,IAAI,CAAA;IAC5B,SAAS,EAAE,IAAI,CAAA;IACf,SAAS,EAAE,IAAI,GAAG,IAAI,CAAA;IAE9B,wDAAwD;IACxD,OAAO,IAAI,MAAM,EAAE;CASpB;AAID;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,aAAc,YAAW,UAAU;IACxC,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;IASjB,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;IAgBnB,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAKrD,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;IAMnB,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAG/C;AAID;;;;;;;;;GASG;AACH,eAAO,MAAM,sBAAsB,4eAelC,CAAA"}

package/dist/memory-orm/index.js

@@ -0,0 +1,187 @@
+/**
+ * `@rudderjs/ai/memory-orm` — ORM-backed {@link UserMemory} for #A4 Phase 4.
+ *
+ * Stores per-user facts in a `UserMemory` table via the registered
+ * `@rudderjs/orm` adapter (Prisma today; Drizzle as well once the user's
+ * tables are wired). Drop-in alongside Phase 1's in-process
+ * `MemoryUserMemory`.
+ *
+ * Wire it from your AI config:
+ *
+ * ```ts
+ * // config/ai.ts
+ * import type { AiConfig } from '@rudderjs/ai'
+ * import { OrmUserMemory } from '@rudderjs/ai/memory-orm'
+ *
+ * export default {
+ *   default: 'anthropic/claude-sonnet-4-5',
+ *   providers: { ... },
+ *   memory: new OrmUserMemory(),
+ * } satisfies AiConfig
+ * ```
+ *
+ * The schema lives at `@rudderjs/ai/memory-orm`'s {@link userMemoryPrismaSchema}
+ * — copy it into your Prisma schema. The optional `embedding Bytes?`
+ * column is shipped here in Phase 4 (intentionally nullable) so Phase 5's
+ * `EmbeddingUserMemory` can populate it without forcing an additive
+ * migration.
+ */
+import { Model } from '@rudderjs/orm';
+// ─── ORM Model ────────────────────────────────────────────
+/**
+ * The Model row backing {@link OrmUserMemory}. Exposed so apps that
+ * want their own queries (admin views, audit dumps) can use the
+ * familiar `UserMemoryRecord.where(...).get()` instead of routing
+ * everything through the {@link UserMemory} interface.
+ *
+ * Tags persist as a JSON-encoded string in the `tags` column — both
+ * Prisma's portable `String?` and Drizzle's `text` work without
+ * needing native array columns. The {@link UserMemory.recall} path
+ * filters tags in JavaScript for the same reason.
+ *
+ * The `embedding Bytes?` column is in the schema as of Phase 4
+ * (nullable) so `@rudderjs/ai/memory-embedding`'s `EmbeddingUserMemory`
+ * (Phase 5) writes the Float32-packed vector here on `remember()` and
+ * reads it for cosine recall. `OrmUserMemory` ignores it — the
+ * column stays `null` for any row stored without the embedding
+ * composer.
+ */
+export class UserMemoryRecord extends Model {
+    static table = 'userMemory';
+    static fillable = ['userId', 'fact', 'tags', 'score', 'embedding'];
+    /** Parsed tags array; empty when nothing was stored. */
+    getTags() {
+        if (this.tags == null || this.tags === '')
+            return [];
+        try {
+            const parsed = JSON.parse(this.tags);
+            return Array.isArray(parsed) ? parsed.filter(t => typeof t === 'string') : [];
+        }
+        catch {
+            return [];
+        }
+    }
+}
+// ─── UserMemory adapter ───────────────────────────────────
+/**
+ * `UserMemory` implementation that persists rows to the registered
+ * ORM adapter. Designed for production use — the in-process
+ * `MemoryUserMemory` is for tests and dev.
+ *
+ * Adapter coverage:
+ * - Prisma — works out of the box; copy {@link userMemoryPrismaSchema}
+ *   into your schema.
+ * - Drizzle — works once you define a table matching the schema's
+ *   columns and register it via `tables: { userMemory: <table> }` on
+ *   the `drizzle()` config.
+ *
+ * Recall semantics: case-insensitive **token-OR-LIKE** matching against
+ * the `fact` column. The query is tokenized on non-alphanumeric
+ * boundaries (≥3-char tokens) and any row whose `fact` matches at
+ * least one token via `LIKE %tok%` is returned. Mirrors Phase 1's
+ * `MemoryUserMemory.recall()` behavior so the two backends are
+ * swap-compatible. Tag scope is applied JS-side after fetch — pushing
+ * tag-array filtering into the WHERE is adapter-specific and lands in a
+ * follow-up.
+ */
+export class OrmUserMemory {
+    async remember(userId, fact, opts) {
+        const data = { userId, fact };
+        if (opts?.tags !== undefined)
+            data['tags'] = JSON.stringify(opts.tags);
+        if (opts?.score !== undefined)
+            data['score'] = opts.score;
+        const created = await UserMemoryRecord.create(data);
+        return rowToEntry(created);
+    }
+    async recall(userId, query, opts) {
+        const tokens = tokenize(query);
+        let q = UserMemoryRecord.where('userId', userId);
+        if (tokens.size > 0) {
+            const tokenList = [...tokens];
+            q = q.whereGroup(g => {
+                for (const tok of tokenList)
+                    g.orWhere('fact', 'LIKE', `%${tok}%`);
+            });
+        }
+        const rows = await q.orderBy('createdAt', 'ASC').get();
+        const entries = rows.map(rowToEntry).filter(e => matchesTags(e, opts?.tags));
+        return capLimit(entries, opts?.limit);
+    }
+    async forget(userId, factId) {
+        const row = await UserMemoryRecord.where('id', factId).where('userId', userId).first();
+        if (row)
+            await row.delete();
+    }
+    async list(userId, opts) {
+        const rows = await UserMemoryRecord.where('userId', userId).orderBy('createdAt', 'ASC').get();
+        const entries = rows.map(rowToEntry).filter(e => matchesTags(e, opts?.tags));
+        return capLimit(entries, opts?.limit);
+    }
+    async forgetAll(userId) {
+        await UserMemoryRecord.where('userId', userId).deleteAll();
+    }
+}
+// ─── Schema reference ─────────────────────────────────────
+/**
+ * Reference Prisma schema for `OrmUserMemory`. Copy into your
+ * `prisma/schema/<file>.prisma` (or paste alongside an existing
+ * model). The `embedding Bytes?` column is intentionally nullable so
+ * Phase 5's `EmbeddingUserMemory` becomes additive — no schema
+ * migration when you upgrade.
+ *
+ * SQLite stores `Bytes` as `BLOB`; Postgres stores it as `bytea`.
+ * Both work for the dot-product implementation Phase 5 will use.
+ */
+export const userMemoryPrismaSchema = `model UserMemory {
+  id        String   @id @default(cuid())
+  userId    String
+  fact      String
+  /// JSON-encoded \`string[]\` of tags, or null
+  tags      String?
+  /// Confidence score in [0, 1] — extract sets this from the model's self-rating
+  score     Float?
+  /// Phase 5 — vector embedding for cosine recall (nullable so Phase 4 ignores it)
+  embedding Bytes?
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  @@index([userId])
+}
+`;
+// ─── 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 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-orm/index.js.map

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

package/dist/memory.d.ts

@@ -0,0 +1,55 @@
+import type { MemoryEntry, RemembersOverride, RemembersSpec, UserMemory } from './types.js';
+/**
+ * In-process, Map-backed {@link UserMemory}. Ships in the runtime-agnostic
+ * main entry — same pattern as {@link MemoryConversationStore}. Suitable
+ * for tests and dev; production apps configure an ORM- or
+ * embedding-backed store via `AiConfig.memory`.
+ *
+ * `recall()` uses case-insensitive **token-overlap** matching against
+ * `fact + tags`: the query is tokenized on non-alphanumeric boundaries
+ * and any fact sharing at least one token (≥3 chars) is returned. This
+ * lets natural-language queries like "what is my project?" pull facts
+ * containing "project" without forcing the caller to extract keywords.
+ * Matches return in insertion order with no scoring (binary yes/no).
+ * Tag filters apply before the token check — they intersect with the
+ * entry's own tags.
+ */
+export declare class MemoryUserMemory implements UserMemory {
+    private readonly entries;
+    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>;
+    private allForUser;
+}
+/**
+ * Resolves the effective {@link RemembersSpec} for a single
+ * `prompt()` / `stream()` call. Returns `null` when memory should be
+ * skipped for this call.
+ *
+ * Precedence (high → low):
+ * 1. Per-call `options.memory` — `false` opts out, a spec replaces the
+ *    agent's declaration.
+ * 2. Agent's `remembers()` — supports sync OR async returns.
+ *
+ * Mirrors {@link resolveAutoPersistSpec} so Phase 2's auto-inject
+ * middleware can drop in alongside the conversation-persistence flow.
+ */
+export declare function resolveRemembersSpec(agentDecl: () => false | RemembersSpec | Promise<false | RemembersSpec>, perCall: RemembersOverride | undefined): Promise<RemembersSpec | null>;
+/**
+ * Lookup signature used by Phase 2/3 middleware to find the registered
+ * {@link UserMemory} without taking a hard dep on `agent.ts`. Wired to
+ * `setUserMemory()` / `AiProvider`'s `ai.memory` DI binding.
+ */
+export type UserMemoryLookup = () => UserMemory | null | undefined;
+//# sourceMappingURL=memory.d.ts.map

package/dist/memory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory.d.ts","sourceRoot":"","sources":["../src/memory.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,WAAW,EACX,iBAAiB,EACjB,aAAa,EACb,UAAU,EACX,MAAM,YAAY,CAAA;AAOnB;;;;;;;;;;;;;;GAcG;AACH,qBAAa,gBAAiB,YAAW,UAAU;IACjD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAiC;IAEnD,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;IAajB,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;IAcnB,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAKrD,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;IAMnB,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAM9C,OAAO,CAAC,UAAU;CAOnB;AA8BD;;;;;;;;;;;;GAYG;AACH,wBAAsB,oBAAoB,CACxC,SAAS,EAAE,MAAM,KAAK,GAAG,aAAa,GAAG,OAAO,CAAC,KAAK,GAAG,aAAa,CAAC,EACvE,OAAO,EAAI,iBAAiB,GAAG,SAAS,GACvC,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CAW/B;AAED;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,GAAG,MAAM,UAAU,GAAG,IAAI,GAAG,SAAS,CAAA"}

package/dist/memory.js

@@ -0,0 +1,132 @@
+function generateId() {
+    if (typeof globalThis.crypto?.randomUUID === 'function')
+        return globalThis.crypto.randomUUID();
+    return `${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 10)}`;
+}
+/**
+ * In-process, Map-backed {@link UserMemory}. Ships in the runtime-agnostic
+ * main entry — same pattern as {@link MemoryConversationStore}. Suitable
+ * for tests and dev; production apps configure an ORM- or
+ * embedding-backed store via `AiConfig.memory`.
+ *
+ * `recall()` uses case-insensitive **token-overlap** matching against
+ * `fact + tags`: the query is tokenized on non-alphanumeric boundaries
+ * and any fact sharing at least one token (≥3 chars) is returned. This
+ * lets natural-language queries like "what is my project?" pull facts
+ * containing "project" without forcing the caller to extract keywords.
+ * Matches return in insertion order with no scoring (binary yes/no).
+ * Tag filters apply before the token check — they intersect with the
+ * entry's own tags.
+ */
+export class MemoryUserMemory {
+    entries = new Map();
+    async remember(userId, fact, opts) {
+        const entry = {
+            id: generateId(),
+            userId,
+            fact,
+            createdAt: new Date(),
+            ...(opts?.tags !== undefined ? { tags: opts.tags } : {}),
+            ...(opts?.score !== undefined ? { score: opts.score } : {}),
+        };
+        this.entries.set(entry.id, entry);
+        return entry;
+    }
+    async recall(userId, query, opts) {
+        const queryTokens = tokenize(query);
+        const wanted = opts?.tags;
+        const matches = this.allForUser(userId)
+            .filter(e => matchesTags(e, wanted))
+            .filter(e => {
+            if (queryTokens.size === 0)
+                return true;
+            const factTokens = tokenize(`${e.fact} ${(e.tags ?? []).join(' ')}`);
+            for (const t of factTokens)
+                if (queryTokens.has(t))
+                    return true;
+            return false;
+        });
+        return capLimit(matches, opts?.limit);
+    }
+    async forget(userId, factId) {
+        const entry = this.entries.get(factId);
+        if (entry && entry.userId === userId)
+            this.entries.delete(factId);
+    }
+    async list(userId, opts) {
+        const wanted = opts?.tags;
+        const matches = this.allForUser(userId).filter(e => matchesTags(e, wanted));
+        return capLimit(matches, opts?.limit);
+    }
+    async forgetAll(userId) {
+        for (const [id, entry] of this.entries) {
+            if (entry.userId === userId)
+                this.entries.delete(id);
+        }
+    }
+    allForUser(userId) {
+        const out = [];
+        for (const entry of this.entries.values()) {
+            if (entry.userId === userId)
+                out.push(entry);
+        }
+        return out;
+    }
+}
+/**
+ * Lowercase + split on non-alphanumeric, drop tokens shorter than 3
+ * characters. Returns a Set so callers can do O(1) lookups when
+ * intersecting query tokens against fact tokens.
+ *
+ * Stopword filtering deliberately omitted — the 3-char floor already
+ * removes "is", "a", "to", "the", "we", etc. and a real stopword list
+ * is locale-dependent. The token-overlap recall is meant as a
+ * "smarter than substring" baseline, not a search engine.
+ */
+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 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;
+}
+/**
+ * Resolves the effective {@link RemembersSpec} for a single
+ * `prompt()` / `stream()` call. Returns `null` when memory should be
+ * skipped for this call.
+ *
+ * Precedence (high → low):
+ * 1. Per-call `options.memory` — `false` opts out, a spec replaces the
+ *    agent's declaration.
+ * 2. Agent's `remembers()` — supports sync OR async returns.
+ *
+ * Mirrors {@link resolveAutoPersistSpec} so Phase 2's auto-inject
+ * middleware can drop in alongside the conversation-persistence flow.
+ */
+export async function resolveRemembersSpec(agentDecl, perCall) {
+    if (perCall === false)
+        return null;
+    if (perCall && typeof perCall === 'object') {
+        if (!perCall.user)
+            return null;
+        return perCall;
+    }
+    const declared = await agentDecl();
+    if (declared === false || !declared)
+        return null;
+    if (!declared.user)
+        return null;
+    return declared;
+}
+//# sourceMappingURL=memory.js.map

package/dist/memory.js.map

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