@molroo-io/sdk 0.5.2

package/dist/esm/memory/in-memory.js

@@ -0,0 +1,111 @@
+/**
+ * In-memory implementation of both EpisodeAdapter and MemoryAdapter.
+ *
+ * Useful for demos, testing, and prototyping. Data is lost on process exit
+ * unless explicitly serialized via `toJSON()` / `fromJSON()`.
+ *
+ * Can be used as:
+ * - `memory: { episodes: new InMemoryEpisodeAdapter() }` (split config)
+ * - `memory: new InMemoryEpisodeAdapter()` (single adapter)
+ */
+export class InMemoryEpisodeAdapter {
+    constructor() {
+        this.episodes = [];
+        this.reflections = [];
+    }
+    async saveEpisode(episode) {
+        const idx = this.episodes.findIndex(e => e.id === episode.id);
+        if (idx >= 0) {
+            this.episodes[idx] = episode;
+        }
+        else {
+            this.episodes.push(episode);
+        }
+    }
+    /**
+     * Recall episodes by query.
+     * Accepts both `EpisodeQuery` (with `contextContains`) and `RecallQuery` (with `context`).
+     */
+    async recall(query) {
+        let results = [...this.episodes];
+        if (query.sourceEntity) {
+            results = results.filter(e => e.sourceEntity === query.sourceEntity);
+        }
+        // Support both EpisodeQuery.contextContains and RecallQuery.context
+        const contextSearch = ('contextContains' in query ? query.contextContains : undefined)
+            ?? ('context' in query ? query.context : undefined);
+        if (contextSearch) {
+            const lower = contextSearch.toLowerCase();
+            results = results.filter(e => e.context?.toLowerCase().includes(lower));
+        }
+        if (query.type !== undefined) {
+            const types = Array.isArray(query.type) ? query.type : [query.type];
+            results = results.filter(e => e.type !== undefined && types.includes(e.type));
+        }
+        if (query.minImportance !== undefined) {
+            results = results.filter(e => e.importance >= query.minImportance);
+        }
+        if (query.timeRange) {
+            const [from, to] = query.timeRange;
+            results = results.filter(e => e.timestamp >= from && e.timestamp <= to);
+        }
+        if ('valenceRange' in query && query.valenceRange) {
+            const [min, max] = query.valenceRange;
+            results = results.filter(e => e.emotionSnapshot.V >= min && e.emotionSnapshot.V <= max);
+        }
+        // Sort by timestamp descending (most recent first)
+        results.sort((a, b) => b.timestamp - a.timestamp);
+        const limit = query.limit ?? 10;
+        return results.slice(0, limit);
+    }
+    async getByIds(ids) {
+        const idSet = new Set(ids);
+        return this.episodes.filter(e => idSet.has(e.id));
+    }
+    async saveReflection(reflection) {
+        const idx = this.reflections.findIndex(r => r.id === reflection.id);
+        if (idx >= 0) {
+            this.reflections[idx] = reflection;
+        }
+        else {
+            this.reflections.push(reflection);
+        }
+    }
+    async getReflections(sourceEntity, limit) {
+        let results = [...this.reflections];
+        if (sourceEntity) {
+            results = results.filter(r => r.sourceEntity === sourceEntity);
+        }
+        // Sort by timestamp descending
+        results.sort((a, b) => b.timestamp - a.timestamp);
+        return results.slice(0, limit ?? 10);
+    }
+    // ── Serialization helpers ──
+    /** Export all data for persistence (save slots, etc.). */
+    toJSON() {
+        return {
+            episodes: [...this.episodes],
+            reflections: [...this.reflections],
+        };
+    }
+    /** Restore data from a previous export. */
+    fromJSON(data) {
+        this.episodes = data.episodes ? [...data.episodes] : [];
+        this.reflections = data.reflections ? [...data.reflections] : [];
+    }
+    /** Number of stored episodes. */
+    get episodeCount() {
+        return this.episodes.length;
+    }
+    /** Number of stored reflections. */
+    get reflectionCount() {
+        return this.reflections.length;
+    }
+    /** Clear all data. */
+    clear() {
+        this.episodes = [];
+        this.reflections = [];
+    }
+}
+/** @deprecated Use InMemoryEpisodeAdapter */
+export const InMemoryEpisodeStore = InMemoryEpisodeAdapter;

package/dist/esm/memory/pinecone/index.d.ts

@@ -0,0 +1,7 @@
+export { PineconeSemanticMemory } from './semantic';
+export type { PineconeSemanticMemoryOptions } from './semantic';
+/** @deprecated Use PineconeSemanticMemory */
+export { PineconeMemoryAdapter } from './memory-adapter';
+/** @deprecated Use PineconeSemanticMemoryOptions */
+export type { PineconeMemoryAdapterOptions } from './memory-adapter';
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/memory/pinecone/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/memory/pinecone/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AACpD,YAAY,EAAE,6BAA6B,EAAE,MAAM,YAAY,CAAC;AAEhE,6CAA6C;AAC7C,OAAO,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAC;AACzD,oDAAoD;AACpD,YAAY,EAAE,4BAA4B,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/esm/memory/pinecone/index.js

@@ -0,0 +1,3 @@
+export { PineconeSemanticMemory } from './semantic';
+/** @deprecated Use PineconeSemanticMemory */
+export { PineconeMemoryAdapter } from './memory-adapter';

package/dist/esm/memory/pinecone/memory-adapter.d.ts

@@ -0,0 +1,62 @@
+import type { MemoryAdapter, Episode, Reflection, RecallQuery, SemanticRecallOptions, EpisodePatch, CountQuery, EmbeddingAdapter } from '../types';
+export interface PineconeMemoryAdapterOptions {
+    /** 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 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();
+ * ```
+ */
+export declare class PineconeMemoryAdapter implements MemoryAdapter {
+    private client;
+    private pcIndex;
+    private namespace;
+    private indexName;
+    private embedding;
+    private initialized;
+    private episodes;
+    private reflections;
+    constructor(options: PineconeMemoryAdapterOptions);
+    /**
+     * Initialize the adapter. Must be called before use.
+     * Validates embedding dimension against Pinecone index.
+     */
+    init(): Promise<void>;
+    private ensureInitialized;
+    private ns;
+    saveEpisode(episode: Episode): Promise<void>;
+    recall(query: RecallQuery): Promise<Episode[]>;
+    saveReflection(reflection: Reflection): Promise<void>;
+    getReflections(sourceEntity?: string): Promise<Reflection[]>;
+    semanticRecall(query: string, options?: SemanticRecallOptions): Promise<Episode[]>;
+    getByIds(ids: string[]): Promise<Episode[]>;
+    countEpisodes(query: CountQuery): Promise<number>;
+    updateEpisode(id: string, patch: EpisodePatch): Promise<void>;
+    deleteEpisode(id: string): Promise<void>;
+    expireEpisodes(before: number, minImportance?: number): Promise<number>;
+}
+//# sourceMappingURL=memory-adapter.d.ts.map

package/dist/esm/memory/pinecone/memory-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-adapter.d.ts","sourceRoot":"","sources":["../../../../src/memory/pinecone/memory-adapter.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,aAAa,EACb,OAAO,EACP,UAAU,EACV,WAAW,EACX,qBAAqB,EACrB,YAAY,EACZ,UAAU,EACV,gBAAgB,EACjB,MAAM,UAAU,CAAC;AAElB,MAAM,WAAW,4BAA4B;IAC3C,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;AASD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBAAa,qBAAsB,YAAW,aAAa;IACzD,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;IAE5B,OAAO,CAAC,QAAQ,CAAiB;IACjC,OAAO,CAAC,WAAW,CAAoB;gBAE3B,OAAO,EAAE,4BAA4B;IAOjD;;;OAGG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAc3B,OAAO,CAAC,iBAAiB;IAMzB,OAAO,CAAC,EAAE;IAMJ,WAAW,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAyB5C,MAAM,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;IAuC9C,cAAc,CAAC,UAAU,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAKrD,cAAc,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;IAU5D,cAAc,CAClB,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,qBAAqB,GAC9B,OAAO,CAAC,OAAO,EAAE,CAAC;IAqCf,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;IAM3C,aAAa,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC;IAuBjD,aAAa,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAU7D,aAAa,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAYxC,cAAc,CAClB,MAAM,EAAE,MAAM,EACd,aAAa,CAAC,EAAE,MAAM,GACrB,OAAO,CAAC,MAAM,CAAC;CA2BnB"}

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

@@ -0,0 +1,216 @@
+import { Pinecone } from '@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();
+ * ```
+ */
+export class PineconeMemoryAdapter {
+    constructor(options) {
+        this.initialized = false;
+        this.episodes = [];
+        this.reflections = [];
+        this.client = new 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;
+    }
+}

package/dist/esm/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/esm/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/esm/memory/pinecone/semantic.js

@@ -0,0 +1,86 @@
+import { Pinecone } from '@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');
+ * ```
+ */
+export class PineconeSemanticMemory {
+    constructor(options) {
+        this.initialized = false;
+        this.client = new 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 });
+        }
+    }
+}

package/dist/esm/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/esm/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"}