@molroo-io/sdk 0.5.2

package/dist/cjs/memory/supabase/memory-adapter.js

@@ -0,0 +1,335 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SupabaseMemoryAdapter = void 0;
+const supabase_js_1 = require("@supabase/supabase-js");
+/**
+ * Supabase-backed MemoryAdapter with optional pgvector semantic search.
+ *
+ * Combines episode/reflection RDB storage with optional pgvector embeddings
+ * into a single unified MemoryAdapter interface.
+ *
+ * @example
+ * ```typescript
+ * // RDB only (no vector search)
+ * const adapter = new SupabaseMemoryAdapter({
+ *   supabaseUrl: process.env.SUPABASE_URL!,
+ *   supabaseKey: process.env.SUPABASE_KEY!,
+ *   personaId: 'world-123',
+ * });
+ *
+ * // With vector search
+ * const adapter = new SupabaseMemoryAdapter({
+ *   supabaseUrl: process.env.SUPABASE_URL!,
+ *   supabaseKey: process.env.SUPABASE_KEY!,
+ *   personaId: 'world-123',
+ *   vector: {
+ *     embedding: openaiEmbedding({ apiKey: '...' }),
+ *     matchThreshold: 0.75,
+ *   },
+ * });
+ * ```
+ */
+class SupabaseMemoryAdapter {
+    constructor(options) {
+        this.client = (0, supabase_js_1.createClient)(options.supabaseUrl, options.supabaseKey);
+        this.personaId = options.personaId;
+        this.rlsStrategy = options.rlsStrategy ?? 'application';
+        this.vectorEnabled = !!options.vector;
+        this.embedding = options.vector?.embedding;
+        this.matchThreshold = options.vector?.matchThreshold ?? 0.7;
+    }
+    async setPersonaContext() {
+        if (this.rlsStrategy === 'application') {
+            await this.client
+                .rpc('set_config', {
+                setting: 'app.current_persona_id',
+                value: this.personaId,
+            })
+                .throwOnError();
+        }
+    }
+    // ── Required methods ──
+    async saveEpisode(episode) {
+        await this.setPersonaContext();
+        const { error } = await this.client.from('episodes').upsert({
+            id: episode.id,
+            persona_id: this.personaId,
+            source_entity: episode.sourceEntity ?? null,
+            context: episode.context ?? null,
+            timestamp: episode.timestamp,
+            importance: episode.importance,
+            intensity: episode.intensity,
+            vad_v: episode.emotionSnapshot.V,
+            vad_a: episode.emotionSnapshot.A,
+            vad_d: episode.emotionSnapshot.D,
+            appraisal: episode.appraisal,
+        });
+        if (error)
+            throw new Error(`saveEpisode failed: ${error.message}`);
+        // Auto-index embedding when vector is enabled
+        if (this.vectorEnabled && this.embedding) {
+            try {
+                const text = episode.context ?? episode.sourceEntity ?? '';
+                if (text) {
+                    const embedding = await this.embedding.embed(text);
+                    await this.indexEmbedding(episode.id, embedding, {
+                        type: 'episode',
+                        sourceEntity: episode.sourceEntity,
+                        timestamp: episode.timestamp,
+                        importance: episode.importance,
+                    });
+                }
+            }
+            catch {
+                // Best-effort: vector indexing failure doesn't block episode save.
+            }
+        }
+    }
+    async recall(query) {
+        await this.setPersonaContext();
+        const limit = query.limit ?? 10;
+        let q = this.client
+            .from('episodes')
+            .select('*')
+            .eq('persona_id', this.personaId);
+        if (query.sourceEntity)
+            q = q.eq('source_entity', query.sourceEntity);
+        if (query.context)
+            q = q.ilike('context', `%${query.context}%`);
+        if (query.minImportance !== undefined)
+            q = q.gte('importance', query.minImportance);
+        if (query.valenceRange) {
+            q = q
+                .gte('vad_v', query.valenceRange[0])
+                .lte('vad_v', query.valenceRange[1]);
+        }
+        if (query.timeRange) {
+            q = q
+                .gte('timestamp', query.timeRange[0])
+                .lte('timestamp', query.timeRange[1]);
+        }
+        const { data, error } = await q
+            .order('timestamp', { ascending: false })
+            .limit(limit);
+        if (error)
+            throw new Error(`recall failed: ${error.message}`);
+        return (data ?? []).map(rowToEpisode);
+    }
+    async saveReflection(reflection) {
+        await this.setPersonaContext();
+        const { error } = await this.client.from('reflections').upsert({
+            id: reflection.id,
+            persona_id: this.personaId,
+            source_entity: reflection.sourceEntity ?? null,
+            content: reflection.content,
+            trigger: reflection.trigger,
+            timestamp: reflection.timestamp,
+            vad_v: reflection.emotionSnapshot.V,
+            vad_a: reflection.emotionSnapshot.A,
+            vad_d: reflection.emotionSnapshot.D,
+        });
+        if (error)
+            throw new Error(`saveReflection failed: ${error.message}`);
+    }
+    async getReflections(sourceEntity) {
+        await this.setPersonaContext();
+        const maxRows = 100;
+        let q = this.client
+            .from('reflections')
+            .select('*')
+            .eq('persona_id', this.personaId)
+            .order('timestamp', { ascending: false });
+        if (sourceEntity)
+            q = q.eq('source_entity', sourceEntity);
+        const { data, error } = await q.limit(maxRows);
+        if (error)
+            throw new Error(`getReflections failed: ${error.message}`);
+        return (data ?? []).map(rowToReflection);
+    }
+    // ── Optional methods ──
+    async semanticRecall(query, options) {
+        if (!this.vectorEnabled || !this.embedding) {
+            // Fallback to text-based recall
+            return this.recall({ context: query, limit: options?.topK ?? 10 });
+        }
+        await this.setPersonaContext();
+        const embedding = await this.embedding.embed(query);
+        const topK = options?.topK ?? 5;
+        const { data, error } = await this.client.rpc('match_embeddings', {
+            query_embedding: embedding,
+            match_threshold: this.matchThreshold,
+            match_count: topK,
+            filter_persona_id: this.personaId,
+            filter_type: 'episode',
+            filter_source_entity: options?.filter?.sourceEntity ?? null,
+            filter_min_importance: options?.filter?.minImportance ?? null,
+        });
+        if (error)
+            throw new Error(`semanticRecall failed: ${error.message}`);
+        const matchedIds = (data ?? []).map((row) => row.id);
+        if (matchedIds.length === 0)
+            return [];
+        // Fetch full episodes for matched IDs
+        return this.getByIds(matchedIds);
+    }
+    async getByIds(ids) {
+        if (ids.length === 0)
+            return [];
+        await this.setPersonaContext();
+        const { data, error } = await this.client
+            .from('episodes')
+            .select('*')
+            .eq('persona_id', this.personaId)
+            .in('id', ids);
+        if (error)
+            throw new Error(`getByIds failed: ${error.message}`);
+        return (data ?? []).map(rowToEpisode);
+    }
+    async countEpisodes(query) {
+        await this.setPersonaContext();
+        let q = this.client
+            .from('episodes')
+            .select('*', { count: 'exact', head: true })
+            .eq('persona_id', this.personaId);
+        if (query.sourceEntity)
+            q = q.eq('source_entity', query.sourceEntity);
+        if (query.context)
+            q = q.ilike('context', `%${query.context}%`);
+        if (query.timeRange) {
+            q = q
+                .gte('timestamp', query.timeRange[0])
+                .lte('timestamp', query.timeRange[1]);
+        }
+        const { count, error } = await q;
+        if (error)
+            throw new Error(`countEpisodes failed: ${error.message}`);
+        return count ?? 0;
+    }
+    async updateEpisode(id, patch) {
+        await this.setPersonaContext();
+        const updates = {};
+        if (patch.importance !== undefined)
+            updates.importance = patch.importance;
+        if (patch.intensity !== undefined)
+            updates.intensity = patch.intensity;
+        if (patch.emotionSnapshot !== undefined) {
+            updates.vad_v = patch.emotionSnapshot.V;
+            updates.vad_a = patch.emotionSnapshot.A;
+            updates.vad_d = patch.emotionSnapshot.D;
+        }
+        if (Object.keys(updates).length === 0)
+            return;
+        const { error } = await this.client
+            .from('episodes')
+            .update(updates)
+            .eq('id', id)
+            .eq('persona_id', this.personaId);
+        if (error)
+            throw new Error(`updateEpisode failed: ${error.message}`);
+    }
+    async deleteEpisode(id) {
+        await this.setPersonaContext();
+        const { error } = await this.client
+            .from('episodes')
+            .delete()
+            .eq('id', id)
+            .eq('persona_id', this.personaId);
+        if (error)
+            throw new Error(`deleteEpisode failed: ${error.message}`);
+        // Best-effort: clean up embedding
+        if (this.vectorEnabled) {
+            try {
+                await this.client
+                    .from('memory_embeddings')
+                    .delete()
+                    .eq('id', id)
+                    .eq('persona_id', this.personaId);
+            }
+            catch {
+                // Non-fatal: vector cleanup failure is acceptable.
+            }
+        }
+    }
+    async expireEpisodes(before, minImportance) {
+        await this.setPersonaContext();
+        const threshold = minImportance ?? 0;
+        // Count first, then delete (Supabase delete doesn't return count reliably)
+        const { count, error: countErr } = await this.client
+            .from('episodes')
+            .select('*', { count: 'exact', head: true })
+            .eq('persona_id', this.personaId)
+            .lt('timestamp', before)
+            .lt('importance', threshold);
+        if (countErr)
+            throw new Error(`expireEpisodes count failed: ${countErr.message}`);
+        const expired = count ?? 0;
+        if (expired === 0)
+            return 0;
+        const { error } = await this.client
+            .from('episodes')
+            .delete()
+            .eq('persona_id', this.personaId)
+            .lt('timestamp', before)
+            .lt('importance', threshold);
+        if (error)
+            throw new Error(`expireEpisodes failed: ${error.message}`);
+        // Best-effort: clean up orphaned embeddings
+        if (this.vectorEnabled) {
+            try {
+                await this.client.rpc('cleanup_orphaned_embeddings', {
+                    filter_persona_id: this.personaId,
+                });
+            }
+            catch {
+                // Non-fatal: orphan cleanup failure is acceptable.
+            }
+        }
+        return expired;
+    }
+    // ── Utility ──
+    async indexEmbedding(id, embedding, metadata) {
+        const { error } = await this.client.from('memory_embeddings').upsert({
+            id,
+            persona_id: this.personaId,
+            type: metadata.type,
+            source_entity: metadata.sourceEntity ?? null,
+            timestamp: metadata.timestamp,
+            importance: metadata.importance ?? 0,
+            embedding,
+        });
+        if (error)
+            throw new Error(`indexEmbedding failed: ${error.message}`);
+    }
+}
+exports.SupabaseMemoryAdapter = SupabaseMemoryAdapter;
+// ── Row mappers ──
+function rowToEpisode(row) {
+    return {
+        id: row.id,
+        timestamp: row.timestamp,
+        sourceEntity: row.source_entity || undefined,
+        context: row.context || undefined,
+        appraisal: row.appraisal,
+        emotionSnapshot: {
+            V: row.vad_v,
+            A: row.vad_a,
+            D: row.vad_d,
+        },
+        intensity: row.intensity,
+        importance: row.importance,
+    };
+}
+function rowToReflection(row) {
+    return {
+        id: row.id,
+        timestamp: row.timestamp,
+        sourceEntity: row.source_entity || undefined,
+        content: row.content,
+        trigger: row.trigger,
+        emotionSnapshot: {
+            V: row.vad_v,
+            A: row.vad_a,
+            D: row.vad_d,
+        },
+    };
+}

package/dist/cjs/memory/supabase/semantic.d.ts

@@ -0,0 +1,44 @@
+import type { EmbeddingAdapter } from '../types';
+import type { SemanticMemory, SearchOptions, SearchResult } from '../semantic';
+export interface SupabaseSemanticMemoryOptions {
+    /** Supabase project URL. */
+    supabaseUrl: string;
+    /** Supabase anon or service-role key. */
+    supabaseKey: string;
+    /** Embedding provider (embed function + dimension). */
+    embedding: EmbeddingAdapter;
+    /** Match threshold for pgvector similarity. Default: 0.7. */
+    matchThreshold?: number;
+    /** Table name for embeddings. Default: 'memory_embeddings'. */
+    tableName?: string;
+    /** RPC function name for similarity search. Default: 'match_semantic_memory'. */
+    matchFunction?: string;
+}
+/**
+ * Supabase pgvector-backed SemanticMemory.
+ *
+ * Requires a table with columns: id (text PK), text (text), embedding (vector),
+ * metadata (jsonb), and an RPC function for similarity search.
+ *
+ * @example
+ * ```typescript
+ * const memory = new SupabaseSemanticMemory({
+ *   supabaseUrl: process.env.SUPABASE_URL!,
+ *   supabaseKey: process.env.SUPABASE_KEY!,
+ *   embedding: openaiEmbedding({ apiKey: '...' }),
+ * });
+ * await memory.store('user likes coffee', { userId: '123' });
+ * ```
+ */
+export declare class SupabaseSemanticMemory implements SemanticMemory {
+    private client;
+    private embedding;
+    private matchThreshold;
+    private tableName;
+    private matchFunction;
+    constructor(options: SupabaseSemanticMemoryOptions);
+    store(text: string, metadata?: Record<string, unknown>): Promise<string>;
+    search(query: string, options?: SearchOptions): Promise<SearchResult[]>;
+    delete(ids: string[]): Promise<void>;
+}
+//# sourceMappingURL=semantic.d.ts.map

package/dist/cjs/memory/supabase/semantic.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"semantic.d.ts","sourceRoot":"","sources":["../../../../src/memory/supabase/semantic.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AACjD,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE/E,MAAM,WAAW,6BAA6B;IAC5C,4BAA4B;IAC5B,WAAW,EAAE,MAAM,CAAC;IACpB,yCAAyC;IACzC,WAAW,EAAE,MAAM,CAAC;IACpB,uDAAuD;IACvD,SAAS,EAAE,gBAAgB,CAAC;IAC5B,6DAA6D;IAC7D,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,+DAA+D;IAC/D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iFAAiF;IACjF,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,sBAAuB,YAAW,cAAc;IAC3D,OAAO,CAAC,MAAM,CAAiB;IAC/B,OAAO,CAAC,SAAS,CAAmB;IACpC,OAAO,CAAC,cAAc,CAAS;IAC/B,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,aAAa,CAAS;gBAElB,OAAO,EAAE,6BAA6B;IAQ5C,KAAK,CACT,IAAI,EAAE,MAAM,EACZ,QAAQ,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GACrC,OAAO,CAAC,MAAM,CAAC;IAcZ,MAAM,CACV,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,aAAkB,GAC1B,OAAO,CAAC,YAAY,EAAE,CAAC;IAwBpB,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;CAQ3C"}

package/dist/cjs/memory/supabase/semantic.js

@@ -0,0 +1,72 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SupabaseSemanticMemory = void 0;
+const supabase_js_1 = require("@supabase/supabase-js");
+/**
+ * Supabase pgvector-backed SemanticMemory.
+ *
+ * Requires a table with columns: id (text PK), text (text), embedding (vector),
+ * metadata (jsonb), and an RPC function for similarity search.
+ *
+ * @example
+ * ```typescript
+ * const memory = new SupabaseSemanticMemory({
+ *   supabaseUrl: process.env.SUPABASE_URL!,
+ *   supabaseKey: process.env.SUPABASE_KEY!,
+ *   embedding: openaiEmbedding({ apiKey: '...' }),
+ * });
+ * await memory.store('user likes coffee', { userId: '123' });
+ * ```
+ */
+class SupabaseSemanticMemory {
+    constructor(options) {
+        this.client = (0, supabase_js_1.createClient)(options.supabaseUrl, options.supabaseKey);
+        this.embedding = options.embedding;
+        this.matchThreshold = options.matchThreshold ?? 0.7;
+        this.tableName = options.tableName ?? 'memory_embeddings';
+        this.matchFunction = options.matchFunction ?? 'match_semantic_memory';
+    }
+    async store(text, metadata = {}) {
+        const id = crypto.randomUUID();
+        const vector = await this.embedding.embed(text);
+        const { error } = await this.client.from(this.tableName).upsert({
+            id,
+            text,
+            embedding: vector,
+            metadata,
+        });
+        if (error)
+            throw new Error(`store failed: ${error.message}`);
+        return id;
+    }
+    async search(query, options = {}) {
+        const topK = options.topK ?? 5;
+        const threshold = options.scoreThreshold ?? this.matchThreshold;
+        const vector = await this.embedding.embed(query);
+        const { data, error } = await this.client.rpc(this.matchFunction, {
+            query_embedding: vector,
+            match_threshold: threshold,
+            match_count: topK,
+            filter_metadata: options.filter ?? null,
+        });
+        if (error)
+            throw new Error(`search failed: ${error.message}`);
+        return (data ?? []).map((row) => ({
+            id: row.id,
+            text: row.text,
+            score: row.similarity,
+            metadata: row.metadata ?? {},
+        }));
+    }
+    async delete(ids) {
+        if (ids.length === 0)
+            return;
+        const { error } = await this.client
+            .from(this.tableName)
+            .delete()
+            .in('id', ids);
+        if (error)
+            throw new Error(`delete failed: ${error.message}`);
+    }
+}
+exports.SupabaseSemanticMemory = SupabaseSemanticMemory;

package/dist/cjs/memory/types.d.ts

@@ -0,0 +1,231 @@
+import type { Episode, VAD } from '../types';
+export type { Episode, VAD };
+/**
+ * Single-interface memory adapter for the SDK.
+ *
+ * Duck-type compatible with `@molroo-io/persona`'s `MemoryAdapter`.
+ * Implementations (SqliteMemoryAdapter, SupabaseMemoryAdapter, etc.) provide
+ * a single object that handles episode storage, recall, and optionally
+ * semantic/vector search internally.
+ *
+ * @example
+ * ```typescript
+ * import { MolrooPersona } from '@molroo-io/sdk';
+ *
+ * const persona = await MolrooPersona.create({
+ *   baseUrl: 'https://api.molroo.io',
+ *   apiKey: 'key',
+ *   llm,
+ *   memory: myMemoryAdapter,
+ * });
+ * ```
+ */
+export interface MemoryAdapter {
+    /** Save an episode returned by the API's AgentResponse. */
+    saveEpisode(episode: Episode): Promise<void>;
+    /**
+     * Recall relevant episodes by structured query.
+     * Accepts both SDK `RecallQuery` and `EpisodeQuery` shapes.
+     */
+    recall(query: RecallQuery): Promise<Episode[]>;
+    /** Save a reflection generated by LLM. Optional — omit for episode-only storage. */
+    saveReflection?(reflection: Reflection): Promise<void>;
+    /** Retrieve reflections for a source entity. Optional. */
+    getReflections?(sourceEntity?: string): Promise<Reflection[]>;
+    /**
+     * Vector/semantic similarity search. Optional.
+     * When provided, the adapter handles embedding internally — no separate
+     * EmbeddingAdapter needed.
+     */
+    semanticRecall?(query: string, options?: SemanticRecallOptions): Promise<Episode[]>;
+    /** Retrieve episodes by IDs. Optional — used for hydrating search results. */
+    getByIds?(ids: string[]): Promise<Episode[]>;
+}
+/**
+ * Query for recalling episodes from a MemoryAdapter.
+ *
+ * Compatible with both persona engine's `RecallQuery` (`context` field)
+ * and the SDK's `EpisodeQuery` (`contextContains` field).
+ */
+export interface RecallQuery {
+    /** Filter by source entity name. */
+    sourceEntity?: string;
+    /** Search keyword or vector query text (persona engine compatibility). */
+    context?: string;
+    /** Max episodes to return. Default: implementation-specific. */
+    limit?: number;
+    /** Minimum importance score to include. */
+    minImportance?: number;
+    /** Epoch ms range [from, to]. */
+    timeRange?: [number, number];
+    /** Filter by episode type. Single string or array (OR match). */
+    type?: string | string[];
+    /** Valence range [min, max]. */
+    valenceRange?: [number, number];
+}
+/** Options for semantic/vector recall. */
+export interface SemanticRecallOptions {
+    /** Number of results to return. Default: 5. */
+    topK?: number;
+    /** Minimum similarity score to include. */
+    minScore?: number;
+    /** Additional structured filters. */
+    filter?: Partial<RecallQuery>;
+}
+/** Recall limit configuration, extracted for reuse. */
+export interface RecallLimits {
+    /** Max episodic memories per recall. Default: 5. */
+    episodicLimit?: number;
+    /** Max semantic results per recall. Default: 3. */
+    semanticLimit?: number;
+    /** Max reflections per recall. Default: 3. */
+    reflectionLimit?: number;
+    /** Minimum importance threshold. Default: 0. */
+    minImportance?: number;
+}
+/**
+ * Type guard: returns true if the memory config is a `MemoryConfig` (split adapters),
+ * false if it's a `MemoryAdapter` (single adapter).
+ *
+ * Discriminates by checking for `saveEpisode` — present on MemoryAdapter, absent on MemoryConfig.
+ */
+export declare function isMemoryConfig(m: MemoryAdapter | MemoryConfig): m is MemoryConfig;
+/**
+ * EpisodeAdapter — RDB-backed structured episode storage.
+ *
+ * Required adapter for the split `MemoryConfig` approach. Handles saving and
+ * recalling episodic memories (conversation episodes + reflections).
+ *
+ * Implementations: InMemoryEpisodeAdapter (built-in), or consumer-provided
+ * (SQLite, PostgreSQL, Supabase, etc.).
+ */
+export interface EpisodeAdapter {
+    /** Save an episode returned by the API's AgentResponse. */
+    saveEpisode(episode: Episode): Promise<void>;
+    /** Recall relevant episodes by structured query (time-ordered). */
+    recall(query: EpisodeQuery): Promise<Episode[]>;
+    /** Retrieve episodes by IDs — used for hydrating SemanticStore results. */
+    getByIds?(ids: string[]): Promise<Episode[]>;
+    /** Save a reflection generated by LLM. */
+    saveReflection(reflection: Reflection): Promise<void>;
+    /** Retrieve reflections for a source entity. */
+    getReflections(sourceEntity?: string, limit?: number): Promise<Reflection[]>;
+}
+/** Structured query for episodic recall (RDB-style filtering). */
+export interface EpisodeQuery {
+    /** Filter by source entity name. */
+    sourceEntity?: string;
+    /** LIKE search on episode context (not semantic). */
+    contextContains?: string;
+    /** Filter by episode type. Single string or array (OR match). */
+    type?: string | string[];
+    /** Max episodes to return. Default: 10. */
+    limit?: number;
+    /** Minimum importance score to include. */
+    minImportance?: number;
+    /** Epoch ms range [from, to]. */
+    timeRange?: [number, number];
+    /** Valence range [min, max]. */
+    valenceRange?: [number, number];
+}
+/**
+ * SemanticAdapter — Vector DB-backed semantic search.
+ *
+ * Optional adapter for similarity-based memory recall.
+ * Requires an EmbeddingAdapter to be configured alongside.
+ *
+ * Implementations: consumer-provided (Pinecone, pgvector, ChromaDB, etc.).
+ */
+export interface SemanticAdapter {
+    /** Index a semantic entry (episode or reflection embedding). */
+    index(entry: SemanticEntry): Promise<void>;
+    /** Search for semantically similar entries. */
+    search(query: SemanticQuery): Promise<SemanticResult[]>;
+}
+/** Entry to index in the vector store. */
+export interface SemanticEntry {
+    id: string;
+    embedding: number[];
+    metadata: {
+        type: 'episode' | 'reflection';
+        sourceEntity?: string;
+        timestamp: number;
+        importance?: number;
+        /** Episode type tag (e.g. 'chat_message', 'attack', 'gift'). */
+        episodeType?: string;
+    };
+}
+/** Query for semantic similarity search. */
+export interface SemanticQuery {
+    embedding: number[];
+    /** Number of results to return. Default: 5. */
+    topK?: number;
+    filter?: {
+        type?: 'episode' | 'reflection';
+        sourceEntity?: string;
+        minImportance?: number;
+        /** Filter by episode type tag. */
+        episodeType?: string;
+    };
+}
+/** Result from semantic similarity search. */
+export interface SemanticResult {
+    id: string;
+    score: number;
+    metadata: SemanticEntry['metadata'];
+}
+/**
+ * EmbeddingAdapter — generates vector embeddings from text.
+ *
+ * Required when using SemanticAdapter. Consumer provides their own
+ * embedding model (OpenAI, Cohere, local, etc.).
+ */
+export interface EmbeddingAdapter {
+    /** Generate an embedding vector from text. */
+    embed(text: string): Promise<number[]>;
+    /** Dimensionality of the embedding vectors. */
+    readonly dimension: number;
+}
+/**
+ * MemoryConfig — split-adapter configuration for the SDK memory system.
+ *
+ * At minimum, provide an `episodes` adapter. Optionally add `semantic`
+ * + `embedding` for similarity-based recall.
+ *
+ * For simpler setup, pass a single `MemoryAdapter` instead of `MemoryConfig`.
+ */
+export interface MemoryConfig {
+    /** Required: structured episode storage (RDB-backed). */
+    episodes: EpisodeAdapter;
+    /** Optional: vector similarity search. Requires `embedding` to be set. */
+    semantic?: SemanticAdapter;
+    /** Optional: embedding adapter. Required when `semantic` is set. */
+    embedding?: EmbeddingAdapter;
+    /** Optional: recall tuning parameters. */
+    recall?: RecallLimits;
+}
+export interface Reflection {
+    id: string;
+    timestamp: number;
+    sourceEntity?: string;
+    content: string;
+    trigger: string;
+    emotionSnapshot: VAD;
+}
+/** @deprecated Use EpisodeAdapter */
+export type EpisodeStore = EpisodeAdapter;
+/** @deprecated Use SemanticAdapter */
+export type SemanticStore = SemanticAdapter;
+/** @deprecated Use EmbeddingAdapter */
+export type EmbeddingProvider = EmbeddingAdapter;
+export interface EpisodePatch {
+    importance?: number;
+    intensity?: number;
+    emotionSnapshot?: VAD;
+}
+export interface CountQuery {
+    sourceEntity?: string;
+    context?: string;
+    timeRange?: [number, number];
+}
+//# sourceMappingURL=types.d.ts.map