@molroo-io/sdk 0.5.2

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

@@ -0,0 +1,220 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PineconeMemoryAdapter = void 0;
+const pinecone_1 = require("@pinecone-database/pinecone");
+/**
+ * Pinecone-backed MemoryAdapter combining in-memory arrays (RDB) with
+ * Pinecone vector search (semanticRecall).
+ *
+ * RDB operations (saveEpisode, recall, saveReflection, getReflections,
+ * getByIds, countEpisodes, updateEpisode, deleteEpisode, expireEpisodes)
+ * all operate on in-memory arrays, identical to InMemoryAdapter.
+ *
+ * Vector search (semanticRecall) delegates to Pinecone after embedding
+ * the query text via the provided EmbeddingAdapter.
+ *
+ * @example
+ * ```typescript
+ * const memory = new PineconeMemoryAdapter({
+ *   apiKey: process.env.PINECONE_API_KEY!,
+ *   indexName: 'molroo-memory',
+ *   namespace: 'world-123',
+ *   embedding: openaiEmbedding({ apiKey: '...' }),
+ * });
+ * await memory.init();
+ * ```
+ */
+class PineconeMemoryAdapter {
+    constructor(options) {
+        this.initialized = false;
+        this.episodes = [];
+        this.reflections = [];
+        this.client = new pinecone_1.Pinecone({ apiKey: options.apiKey });
+        this.indexName = options.indexName;
+        this.namespace = options.namespace ?? 'default';
+        this.embedding = options.embedding;
+    }
+    /**
+     * Initialize the adapter. Must be called before use.
+     * Validates embedding dimension against Pinecone index.
+     */
+    async init() {
+        this.pcIndex = this.client.index(this.indexName);
+        const stats = await this.pcIndex.describeIndexStats();
+        if (stats.dimension && stats.dimension !== this.embedding.dimension) {
+            throw new Error(`Dimension mismatch: Pinecone index expects ${stats.dimension}d, ` +
+                `but embedding provider has ${this.embedding.dimension}d`);
+        }
+        this.initialized = true;
+    }
+    ensureInitialized() {
+        if (!this.initialized) {
+            throw new Error('PineconeMemoryAdapter not initialized. Call init() first.');
+        }
+    }
+    ns() {
+        return this.pcIndex.namespace(this.namespace);
+    }
+    // ── Required methods (in-memory, identical to InMemoryAdapter) ──
+    async saveEpisode(episode) {
+        this.ensureInitialized();
+        this.episodes.push(episode);
+        // Auto-upsert embedding to Pinecone (best-effort)
+        const text = episode.context ?? episode.sourceEntity ?? '';
+        if (text) {
+            try {
+                const embedding = await this.embedding.embed(text);
+                await this.ns().upsert([{
+                        id: episode.id,
+                        values: embedding,
+                        metadata: {
+                            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) {
+        this.ensureInitialized();
+        let results = this.episodes;
+        if (query.sourceEntity) {
+            results = results.filter((e) => e.sourceEntity === query.sourceEntity);
+        }
+        if (query.context) {
+            const ctx = query.context.toLowerCase();
+            results = results.filter((e) => e.context && e.context.toLowerCase().includes(ctx));
+        }
+        if (query.valenceRange) {
+            const [min, max] = query.valenceRange;
+            results = results.filter((e) => e.emotionSnapshot.V >= min && e.emotionSnapshot.V <= max);
+        }
+        if (query.minImportance !== undefined) {
+            results = results.filter((e) => e.importance >= query.minImportance);
+        }
+        if (query.timeRange) {
+            const [start, end] = query.timeRange;
+            results = results.filter((e) => e.timestamp >= start && e.timestamp <= end);
+        }
+        // Return most recent first
+        results = results.slice().sort((a, b) => b.timestamp - a.timestamp);
+        if (query.limit && query.limit > 0) {
+            results = results.slice(0, query.limit);
+        }
+        return results;
+    }
+    async saveReflection(reflection) {
+        this.ensureInitialized();
+        this.reflections.push(reflection);
+    }
+    async getReflections(sourceEntity) {
+        this.ensureInitialized();
+        if (sourceEntity) {
+            return this.reflections.filter((r) => r.sourceEntity === sourceEntity);
+        }
+        return [...this.reflections];
+    }
+    // ── Optional methods ──
+    async semanticRecall(query, options) {
+        this.ensureInitialized();
+        const embedding = await this.embedding.embed(query);
+        const topK = options?.topK ?? 5;
+        // Build Pinecone filter
+        const filter = {};
+        if (options?.filter?.sourceEntity) {
+            filter.sourceEntity = { $eq: options.filter.sourceEntity };
+        }
+        if (options?.filter?.minImportance !== undefined) {
+            filter.importance = { $gte: options.filter.minImportance };
+        }
+        // Over-fetch to account for in-memory-only episodes that may not be in Pinecone
+        const hasFilter = Object.keys(filter).length > 0;
+        const fetchK = hasFilter ? topK * 4 : topK;
+        const results = await this.ns().query({
+            vector: embedding,
+            topK: fetchK,
+            filter: hasFilter ? filter : undefined,
+            includeMetadata: true,
+        });
+        // Map Pinecone results to episodes via in-memory lookup
+        const matches = results.matches ?? [];
+        const idSet = new Set(matches.map((m) => m.id));
+        const matched = this.episodes.filter((e) => idSet.has(e.id));
+        // Sort by Pinecone score order (highest first), limit to topK
+        const scoreMap = new Map(matches.map((m) => [m.id, m.score ?? 0]));
+        return matched
+            .sort((a, b) => (scoreMap.get(b.id) ?? 0) - (scoreMap.get(a.id) ?? 0))
+            .slice(0, topK);
+    }
+    async getByIds(ids) {
+        this.ensureInitialized();
+        const idSet = new Set(ids);
+        return this.episodes.filter((e) => idSet.has(e.id));
+    }
+    async countEpisodes(query) {
+        this.ensureInitialized();
+        let results = this.episodes;
+        if (query.sourceEntity) {
+            results = results.filter((e) => e.sourceEntity === query.sourceEntity);
+        }
+        if (query.context) {
+            const ctx = query.context.toLowerCase();
+            results = results.filter((e) => e.context && e.context.toLowerCase().includes(ctx));
+        }
+        if (query.timeRange) {
+            const [start, end] = query.timeRange;
+            results = results.filter((e) => e.timestamp >= start && e.timestamp <= end);
+        }
+        return results.length;
+    }
+    async updateEpisode(id, patch) {
+        this.ensureInitialized();
+        const episode = this.episodes.find((e) => e.id === id);
+        if (!episode)
+            return;
+        if (patch.importance !== undefined)
+            episode.importance = patch.importance;
+        if (patch.intensity !== undefined)
+            episode.intensity = patch.intensity;
+        if (patch.emotionSnapshot !== undefined)
+            episode.emotionSnapshot = patch.emotionSnapshot;
+    }
+    async deleteEpisode(id) {
+        this.ensureInitialized();
+        this.episodes = this.episodes.filter((e) => e.id !== id);
+        // Best-effort Pinecone cleanup
+        try {
+            await this.ns().deleteOne(id);
+        }
+        catch {
+            // Non-fatal: Pinecone cleanup failure doesn't affect in-memory state.
+        }
+    }
+    async expireEpisodes(before, minImportance) {
+        this.ensureInitialized();
+        const threshold = minImportance ?? 0;
+        const original = this.episodes.length;
+        // Collect IDs of episodes to expire for Pinecone cleanup
+        const expiredIds = this.episodes
+            .filter((e) => e.timestamp < before && e.importance < threshold)
+            .map((e) => e.id);
+        this.episodes = this.episodes.filter((e) => e.timestamp >= before || e.importance >= threshold);
+        const count = original - this.episodes.length;
+        // Best-effort Pinecone cleanup
+        if (expiredIds.length > 0) {
+            try {
+                await this.ns().deleteMany({ ids: expiredIds });
+            }
+            catch {
+                // Non-fatal: Pinecone cleanup failure doesn't affect in-memory state.
+            }
+        }
+        return count;
+    }
+}
+exports.PineconeMemoryAdapter = PineconeMemoryAdapter;

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

@@ -0,0 +1,44 @@
+import type { EmbeddingAdapter } from '../types';
+import type { SemanticMemory, SearchOptions, SearchResult } from '../semantic';
+export interface PineconeSemanticMemoryOptions {
+    /** Pinecone API key. */
+    apiKey: string;
+    /** Pinecone index name. */
+    indexName: string;
+    /** Pinecone namespace. Default: 'default'. */
+    namespace?: string;
+    /** Embedding provider (embed function + dimension). */
+    embedding: EmbeddingAdapter;
+}
+/**
+ * Pinecone-backed SemanticMemory.
+ *
+ * Call `init()` before use to validate embedding dimension against Pinecone index.
+ *
+ * @example
+ * ```typescript
+ * const memory = new PineconeSemanticMemory({
+ *   apiKey: process.env.PINECONE_API_KEY!,
+ *   indexName: 'my-index',
+ *   embedding: openaiEmbedding({ apiKey: '...' }),
+ * });
+ * await memory.init();
+ * await memory.store('user likes coffee');
+ * ```
+ */
+export declare class PineconeSemanticMemory implements SemanticMemory {
+    private client;
+    private pcIndex;
+    private namespace;
+    private indexName;
+    private embedding;
+    private initialized;
+    constructor(options: PineconeSemanticMemoryOptions);
+    init(): Promise<void>;
+    private ensureInit;
+    private ns;
+    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/pinecone/semantic.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"semantic.d.ts","sourceRoot":"","sources":["../../../../src/memory/pinecone/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,wBAAwB;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,2BAA2B;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,8CAA8C;IAC9C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,uDAAuD;IACvD,SAAS,EAAE,gBAAgB,CAAC;CAC7B;AAOD;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,sBAAuB,YAAW,cAAc;IAC3D,OAAO,CAAC,MAAM,CAAW;IACzB,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,SAAS,CAAmB;IACpC,OAAO,CAAC,WAAW,CAAS;gBAEhB,OAAO,EAAE,6BAA6B;IAO5C,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAY3B,OAAO,CAAC,UAAU;IAMlB,OAAO,CAAC,EAAE;IAIJ,KAAK,CACT,IAAI,EAAE,MAAM,EACZ,QAAQ,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GACrC,OAAO,CAAC,MAAM,CAAC;IAqBZ,MAAM,CACV,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,aAAkB,GAC1B,OAAO,CAAC,YAAY,EAAE,CAAC;IA4BpB,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;CAM3C"}

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

@@ -0,0 +1,90 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PineconeSemanticMemory = void 0;
+const pinecone_1 = require("@pinecone-database/pinecone");
+/**
+ * Pinecone-backed SemanticMemory.
+ *
+ * Call `init()` before use to validate embedding dimension against Pinecone index.
+ *
+ * @example
+ * ```typescript
+ * const memory = new PineconeSemanticMemory({
+ *   apiKey: process.env.PINECONE_API_KEY!,
+ *   indexName: 'my-index',
+ *   embedding: openaiEmbedding({ apiKey: '...' }),
+ * });
+ * await memory.init();
+ * await memory.store('user likes coffee');
+ * ```
+ */
+class PineconeSemanticMemory {
+    constructor(options) {
+        this.initialized = false;
+        this.client = new pinecone_1.Pinecone({ apiKey: options.apiKey });
+        this.indexName = options.indexName;
+        this.namespace = options.namespace ?? 'default';
+        this.embedding = options.embedding;
+    }
+    async init() {
+        this.pcIndex = this.client.index(this.indexName);
+        const stats = await this.pcIndex.describeIndexStats();
+        if (stats.dimension && stats.dimension !== this.embedding.dimension) {
+            throw new Error(`Dimension mismatch: Pinecone index expects ${stats.dimension}d, ` +
+                `but embedding provider has ${this.embedding.dimension}d`);
+        }
+        this.initialized = true;
+    }
+    ensureInit() {
+        if (!this.initialized) {
+            throw new Error('PineconeSemanticMemory not initialized. Call init() first.');
+        }
+    }
+    ns() {
+        return this.pcIndex.namespace(this.namespace);
+    }
+    async store(text, metadata = {}) {
+        this.ensureInit();
+        const id = crypto.randomUUID();
+        const values = await this.embedding.embed(text);
+        const pineconeMetadata = {
+            text,
+            ...Object.fromEntries(Object.entries(metadata).filter(([, v]) => typeof v === 'string' ||
+                typeof v === 'number' ||
+                typeof v === 'boolean' ||
+                Array.isArray(v))),
+        };
+        await this.ns().upsert([{ id, values, metadata: pineconeMetadata }]);
+        return id;
+    }
+    async search(query, options = {}) {
+        this.ensureInit();
+        const topK = options.topK ?? 5;
+        const threshold = options.scoreThreshold ?? 0;
+        const vector = await this.embedding.embed(query);
+        const filter = options.filter;
+        const hasFilter = filter && Object.keys(filter).length > 0;
+        const results = await this.ns().query({
+            vector,
+            topK,
+            filter: hasFilter ? filter : undefined,
+            includeMetadata: true,
+        });
+        const matchList = results.matches ?? [];
+        return matchList
+            .filter((m) => (m.score ?? 0) >= threshold)
+            .map((m) => ({
+            id: m.id,
+            text: m.metadata?.text ?? '',
+            score: m.score ?? 0,
+            metadata: m.metadata ?? {},
+        }));
+    }
+    async delete(ids) {
+        this.ensureInit();
+        if (ids.length > 0) {
+            await this.ns().deleteMany({ ids });
+        }
+    }
+}
+exports.PineconeSemanticMemory = PineconeSemanticMemory;

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

@@ -0,0 +1,58 @@
+/**
+ * Shared memory recall and prompt-building utilities.
+ *
+ * Used by MolrooPersona to recall episodic/semantic memories and
+ * format them for LLM system prompts. Supports both:
+ * - Single MemoryAdapter (new, preferred)
+ * - Split EpisodeAdapter + SemanticAdapter + EmbeddingAdapter (backward compat)
+ */
+import type { Episode } from '../types';
+import type { EpisodeAdapter, SemanticAdapter, EmbeddingAdapter, MemoryAdapter, Reflection } from './types';
+/**
+ * Strip leading `[...]` metadata tags from text before embedding.
+ * These tags (channel info, scene hints, timestamps) add noise to
+ * semantic similarity and should not influence vector search.
+ */
+export declare function stripMetaTags(text: string): string;
+/** Recall tuning parameters. */
+export interface RecallConfig {
+    episodicLimit?: number;
+    semanticLimit?: number;
+    reflectionLimit?: number;
+    minImportance?: number;
+    /** Filter episodic recall to these episode types. Undefined = all types. */
+    types?: string[];
+}
+/** Result of a memory recall operation. */
+export interface RecallResult {
+    episodic: Episode[];
+    semantic: Episode[];
+    reflections: Reflection[];
+}
+/**
+ * Recall episodic + semantic + reflection memories in parallel.
+ *
+ * Supports two paths:
+ * 1. Single MemoryAdapter (`memoryAdapter` param) — adapter handles everything
+ * 2. Split stores (`episodeStore` + `semanticStore` + `embeddingProvider`) — legacy
+ *
+ * @param message - Current user message (used for semantic embedding).
+ * @param opts - Stores, provider, config, and entity filter.
+ * @returns Recalled memories grouped by type.
+ */
+export declare function recallMemories(message: string, opts: {
+    memoryAdapter?: MemoryAdapter | null;
+    episodeStore: EpisodeAdapter | null;
+    semanticStore: SemanticAdapter | null;
+    embeddingProvider: EmbeddingAdapter | null;
+    config?: RecallConfig;
+    sourceEntity?: string;
+    reflectionEntity?: string;
+}): Promise<RecallResult>;
+/**
+ * Format recalled memories into a text block for LLM system prompt injection.
+ * Groups episodic memories by type: conversations vs events.
+ * Deduplicates semantic results that overlap with episodic results.
+ */
+export declare function buildMemoryBlock(episodicMemories?: Episode[], semanticMemories?: Episode[], reflections?: Reflection[]): string;
+//# sourceMappingURL=recall.d.ts.map

package/dist/cjs/memory/recall.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recall.d.ts","sourceRoot":"","sources":["../../../src/memory/recall.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AACxC,OAAO,KAAK,EACV,cAAc,EACd,eAAe,EACf,gBAAgB,EAChB,aAAa,EACb,UAAU,EAEX,MAAM,SAAS,CAAC;AAEjB;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAElD;AAED,gCAAgC;AAChC,MAAM,WAAW,YAAY;IAC3B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,4EAA4E;IAC5E,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,2CAA2C;AAC3C,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,OAAO,EAAE,CAAC;IACpB,QAAQ,EAAE,OAAO,EAAE,CAAC;IACpB,WAAW,EAAE,UAAU,EAAE,CAAC;CAC3B;AAgFD;;;;;;;;;;GAUG;AACH,wBAAsB,cAAc,CAClC,OAAO,EAAE,MAAM,EACf,IAAI,EAAE;IACJ,aAAa,CAAC,EAAE,aAAa,GAAG,IAAI,CAAC;IACrC,YAAY,EAAE,cAAc,GAAG,IAAI,CAAC;IACpC,aAAa,EAAE,eAAe,GAAG,IAAI,CAAC;IACtC,iBAAiB,EAAE,gBAAgB,GAAG,IAAI,CAAC;IAC3C,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B,GACA,OAAO,CAAC,YAAY,CAAC,CA2FvB;AAcD;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,gBAAgB,CAAC,EAAE,OAAO,EAAE,EAC5B,gBAAgB,CAAC,EAAE,OAAO,EAAE,EAC5B,WAAW,CAAC,EAAE,UAAU,EAAE,GACzB,MAAM,CAwCR"}

package/dist/cjs/memory/recall.js

@@ -0,0 +1,220 @@
+"use strict";
+/**
+ * Shared memory recall and prompt-building utilities.
+ *
+ * Used by MolrooPersona to recall episodic/semantic memories and
+ * format them for LLM system prompts. Supports both:
+ * - Single MemoryAdapter (new, preferred)
+ * - Split EpisodeAdapter + SemanticAdapter + EmbeddingAdapter (backward compat)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.stripMetaTags = stripMetaTags;
+exports.recallMemories = recallMemories;
+exports.buildMemoryBlock = buildMemoryBlock;
+/**
+ * Strip leading `[...]` metadata tags from text before embedding.
+ * These tags (channel info, scene hints, timestamps) add noise to
+ * semantic similarity and should not influence vector search.
+ */
+function stripMetaTags(text) {
+    return text.replace(/^\s*(\[.*?\]\s*)+/s, '').trim();
+}
+/**
+ * Recall from a single MemoryAdapter. The adapter handles all storage
+ * and vector search internally.
+ */
+async function recallFromAdapter(message, adapter, config, sourceEntity, reflectionEntity) {
+    const episodicLimit = config.episodicLimit ?? 5;
+    const semanticLimit = config.semanticLimit ?? 3;
+    const reflectionLimit = config.reflectionLimit ?? 3;
+    const minImportance = config.minImportance ?? 0;
+    // Episodic recall — conversations (filtered by sourceEntity)
+    const conversationP = adapter
+        .recall({
+        sourceEntity,
+        limit: episodicLimit,
+        minImportance,
+        ...(config.types ? { type: config.types } : {}),
+    })
+        .catch(() => []);
+    // Episodic recall — non-chat events (no sourceEntity filter)
+    const hasTypeFilter = config.types && config.types.length > 0;
+    const eventP = !hasTypeFilter
+        ? adapter
+            .recall({
+            limit: episodicLimit,
+            minImportance,
+        })
+            .then((all) => all.filter((ep) => ep.type && ep.type !== 'chat_message'))
+            .catch(() => [])
+        : Promise.resolve([]);
+    // Semantic recall (vector) — adapter handles embedding internally
+    const semanticP = adapter.semanticRecall
+        ? adapter
+            .semanticRecall(stripMetaTags(message), {
+            topK: semanticLimit,
+            filter: { minImportance },
+        })
+            .catch(() => [])
+        : Promise.resolve([]);
+    // Reflection recall
+    const reflectionP = adapter.getReflections
+        ? adapter
+            .getReflections(reflectionEntity)
+            .then((refs) => refs.slice(0, reflectionLimit))
+            .catch(() => [])
+        : Promise.resolve([]);
+    const [conversations, events, semantic, reflections] = await Promise.all([
+        conversationP,
+        eventP,
+        semanticP,
+        reflectionP,
+    ]);
+    // Merge conversations + events, deduplicate, and re-sort by recency
+    const seenIds = new Set();
+    const episodic = [];
+    for (const ep of [...conversations, ...events]) {
+        if (!seenIds.has(ep.id)) {
+            seenIds.add(ep.id);
+            episodic.push(ep);
+        }
+    }
+    episodic.sort((a, b) => b.timestamp - a.timestamp);
+    episodic.splice(episodicLimit);
+    return { episodic, semantic, reflections };
+}
+/**
+ * Recall episodic + semantic + reflection memories in parallel.
+ *
+ * Supports two paths:
+ * 1. Single MemoryAdapter (`memoryAdapter` param) — adapter handles everything
+ * 2. Split stores (`episodeStore` + `semanticStore` + `embeddingProvider`) — legacy
+ *
+ * @param message - Current user message (used for semantic embedding).
+ * @param opts - Stores, provider, config, and entity filter.
+ * @returns Recalled memories grouped by type.
+ */
+async function recallMemories(message, opts) {
+    const config = opts.config ?? {};
+    // Path 1: Single MemoryAdapter
+    if (opts.memoryAdapter) {
+        return recallFromAdapter(message, opts.memoryAdapter, config, opts.sourceEntity, opts.reflectionEntity);
+    }
+    // Path 2: Split stores (backward compat)
+    const { episodeStore, semanticStore, embeddingProvider } = opts;
+    const episodicLimit = config.episodicLimit ?? 5;
+    const semanticLimit = config.semanticLimit ?? 3;
+    const reflectionLimit = config.reflectionLimit ?? 3;
+    const minImportance = config.minImportance ?? 0;
+    // Episodic recall — conversations (filtered by sourceEntity)
+    const conversationP = episodeStore
+        ? episodeStore
+            .recall({
+            sourceEntity: opts.sourceEntity,
+            limit: episodicLimit,
+            minImportance,
+            ...(config.types ? { type: config.types } : {}),
+        })
+            .catch(() => [])
+        : Promise.resolve([]);
+    // Episodic recall — non-chat events (no sourceEntity filter).
+    // Events like attacks/gifts come from various entities and must be
+    // recalled regardless of who the persona is currently talking to.
+    const hasTypeFilter = config.types && config.types.length > 0;
+    const eventP = (episodeStore && !hasTypeFilter)
+        ? episodeStore
+            .recall({
+            // No sourceEntity — recall events from all sources
+            limit: episodicLimit,
+            minImportance,
+        })
+            .then((all) => all.filter((ep) => ep.type && ep.type !== 'chat_message'))
+            .catch(() => [])
+        : Promise.resolve([]);
+    // Semantic recall (vector)
+    const semanticP = semanticStore && embeddingProvider && episodeStore?.getByIds
+        ? embeddingProvider
+            .embed(stripMetaTags(message))
+            .then((embedding) => semanticStore.search({ embedding, topK: semanticLimit, filter: { minImportance } }))
+            .then((results) => results.length > 0
+            ? episodeStore.getByIds(results.map((r) => r.id))
+            : [])
+            .catch(() => [])
+        : Promise.resolve([]);
+    // Reflection recall (RDB)
+    const reflectionP = episodeStore
+        ? episodeStore
+            .getReflections(opts.reflectionEntity, reflectionLimit)
+            .catch(() => [])
+        : Promise.resolve([]);
+    const [conversations, events, semantic, reflections] = await Promise.all([
+        conversationP,
+        eventP,
+        semanticP,
+        reflectionP,
+    ]);
+    // Merge conversations + events, deduplicate, and re-sort by recency
+    const seenIds = new Set();
+    const episodic = [];
+    for (const ep of [...conversations, ...events]) {
+        if (!seenIds.has(ep.id)) {
+            seenIds.add(ep.id);
+            episodic.push(ep);
+        }
+    }
+    episodic.sort((a, b) => b.timestamp - a.timestamp);
+    episodic.splice(episodicLimit);
+    return { episodic, semantic, reflections };
+}
+/** Format a single episode into a display line. */
+function formatEpisodeLine(ep) {
+    const v = ep.emotionSnapshot;
+    const isEvent = ep.type && ep.type !== 'chat_message';
+    const prefix = isEvent ? `[${ep.type}] ` : '';
+    return (`- [${new Date(ep.timestamp).toISOString()}] `
+        + `${prefix}${ep.sourceEntity ?? 'unknown'}: ${ep.context ?? 'no context'} `
+        + `(V:${v.V.toFixed(2)} A:${v.A.toFixed(2)} importance:${ep.importance.toFixed(2)})`);
+}
+/**
+ * Format recalled memories into a text block for LLM system prompt injection.
+ * Groups episodic memories by type: conversations vs events.
+ * Deduplicates semantic results that overlap with episodic results.
+ */
+function buildMemoryBlock(episodicMemories, semanticMemories, reflections) {
+    const parts = [];
+    if (episodicMemories && episodicMemories.length > 0) {
+        const conversations = episodicMemories.filter((ep) => !ep.type || ep.type === 'chat_message');
+        const events = episodicMemories.filter((ep) => ep.type && ep.type !== 'chat_message');
+        if (conversations.length > 0) {
+            parts.push('Recent conversations:');
+            for (const ep of conversations)
+                parts.push(formatEpisodeLine(ep));
+        }
+        if (events.length > 0) {
+            if (parts.length > 0)
+                parts.push('');
+            parts.push('Recent events:');
+            for (const ep of events)
+                parts.push(formatEpisodeLine(ep));
+        }
+    }
+    if (semanticMemories && semanticMemories.length > 0) {
+        const episodicIds = new Set(episodicMemories?.map((e) => e.id) ?? []);
+        const unique = semanticMemories.filter((e) => !episodicIds.has(e.id));
+        if (unique.length > 0) {
+            if (parts.length > 0)
+                parts.push('');
+            parts.push('Related past experiences:');
+            for (const ep of unique)
+                parts.push(formatEpisodeLine(ep));
+        }
+    }
+    if (reflections && reflections.length > 0) {
+        if (parts.length > 0)
+            parts.push('');
+        parts.push('Your recent self-reflections:');
+        for (const ref of reflections)
+            parts.push(`- ${ref.content}`);
+    }
+    return parts.join('\n');
+}

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

@@ -0,0 +1,24 @@
+/** Semantic (vector-based) memory interface. */
+export interface SemanticMemory {
+    /** Embed and store text. Returns the stored entry ID. */
+    store(text: string, metadata?: Record<string, unknown>): Promise<string>;
+    /** Embed query and return similar entries by cosine similarity. */
+    search(query: string, options?: SearchOptions): Promise<SearchResult[]>;
+    /** Delete entries by ID. */
+    delete?(ids: string[]): Promise<void>;
+}
+export interface SearchOptions {
+    /** Maximum number of results. Default: 5. */
+    topK?: number;
+    /** Minimum similarity score threshold (0–1). */
+    scoreThreshold?: number;
+    /** Backend-specific metadata filter. */
+    filter?: Record<string, unknown>;
+}
+export interface SearchResult {
+    id: string;
+    text: string;
+    score: number;
+    metadata: Record<string, unknown>;
+}
+//# sourceMappingURL=semantic.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"semantic.d.ts","sourceRoot":"","sources":["../../../src/memory/semantic.ts"],"names":[],"mappings":"AAAA,gDAAgD;AAChD,MAAM,WAAW,cAAc;IAC7B,yDAAyD;IACzD,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACzE,mEAAmE;IACnE,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAAC;IACxE,4BAA4B;IAC5B,MAAM,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACvC;AAED,MAAM,WAAW,aAAa;IAC5B,6CAA6C;IAC7C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,gDAAgD;IAChD,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,wCAAwC;IACxC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAED,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC"}

package/dist/cjs/memory/semantic.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/memory/sqlite/index.d.ts

@@ -0,0 +1,3 @@
+export { SqliteMemoryAdapter } from './memory-adapter';
+export type { SqliteMemoryAdapterOptions } from './memory-adapter';
+//# sourceMappingURL=index.d.ts.map

package/dist/cjs/memory/sqlite/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/memory/sqlite/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AACvD,YAAY,EAAE,0BAA0B,EAAE,MAAM,kBAAkB,CAAC"}