@molroo-io/sdk 0.5.2

package/dist/esm/memory/recall.js

@@ -0,0 +1,215 @@
+/**
+ * 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)
+ */
+/**
+ * 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 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.
+ */
+export 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.
+ */
+export 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/esm/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/esm/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/esm/memory/semantic.js

@@ -0,0 +1 @@
+export {};

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

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

@@ -0,0 +1 @@
+export { SqliteMemoryAdapter } from './memory-adapter';

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

@@ -0,0 +1,58 @@
+import Database from 'better-sqlite3';
+import type { MemoryAdapter, Episode, Reflection, RecallQuery, SemanticRecallOptions, EpisodePatch, CountQuery, EmbeddingAdapter } from '../types';
+export interface SqliteMemoryAdapterOptions {
+    /** Path to SQLite database file, or ':memory:' for in-memory. */
+    dbPath: string;
+    /** Enable WAL mode for better concurrent reads. Default: true. */
+    walMode?: boolean;
+    /** Enable vector search. When absent, semanticRecall is not available. */
+    vector?: {
+        /** Embedding provider (embed function + dimension). */
+        embedding: EmbeddingAdapter;
+        /** sqlite-vec load function. Auto-imports if not provided. */
+        loadVec?: (db: Database.Database) => void;
+    };
+}
+/**
+ * SQLite-backed MemoryAdapter with optional vector search.
+ *
+ * @example
+ * ```typescript
+ * // RDB only (no vector search)
+ * const adapter = new SqliteMemoryAdapter({ dbPath: './memory.db' });
+ * await adapter.init();
+ *
+ * // With vector search
+ * const adapter = new SqliteMemoryAdapter({
+ *   dbPath: './memory.db',
+ *   vector: {
+ *     embedding: openaiEmbedding({ apiKey: '...' }),
+ *   },
+ * });
+ * await adapter.init();
+ * ```
+ */
+export declare class SqliteMemoryAdapter implements MemoryAdapter {
+    private db;
+    private opts;
+    private vectorEnabled;
+    private stmts;
+    constructor(options: SqliteMemoryAdapterOptions);
+    /** Initialize the database and create tables. Must be called before use. */
+    init(): Promise<void>;
+    private prepareStatements;
+    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>;
+    private indexEmbedding;
+    /** Close the database connection. */
+    close(): void;
+}
+//# sourceMappingURL=memory-adapter.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"memory-adapter.d.ts","sourceRoot":"","sources":["../../../../src/memory/sqlite/memory-adapter.ts"],"names":[],"mappings":"AAAA,OAAO,QAAQ,MAAM,gBAAgB,CAAC;AACtC,OAAO,KAAK,EACV,aAAa,EACb,OAAO,EACP,UAAU,EACV,WAAW,EACX,qBAAqB,EACrB,YAAY,EACZ,UAAU,EACV,gBAAgB,EACjB,MAAM,UAAU,CAAC;AAGlB,MAAM,WAAW,0BAA0B;IACzC,iEAAiE;IACjE,MAAM,EAAE,MAAM,CAAC;IACf,kEAAkE;IAClE,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,0EAA0E;IAC1E,MAAM,CAAC,EAAE;QACP,uDAAuD;QACvD,SAAS,EAAE,gBAAgB,CAAC;QAC5B,8DAA8D;QAC9D,OAAO,CAAC,EAAE,CAAC,EAAE,EAAE,QAAQ,CAAC,QAAQ,KAAK,IAAI,CAAC;KAC3C,CAAC;CACH;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,mBAAoB,YAAW,aAAa;IACvD,OAAO,CAAC,EAAE,CAAqB;IAC/B,OAAO,CAAC,IAAI,CAA6B;IACzC,OAAO,CAAC,aAAa,CAAS;IAE9B,OAAO,CAAC,KAAK,CAQX;gBAEU,OAAO,EAAE,0BAA0B;IAI/C,4EAA4E;IACtE,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAuB3B,OAAO,CAAC,iBAAiB;IAkCnB,WAAW,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IA2B5C,MAAM,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;IAkC9C,cAAc,CAAC,UAAU,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAarD,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;IAuCf,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;IAe7D,aAAa,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAWxC,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,aAAa,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAqB7E,OAAO,CAAC,cAAc;IAYtB,qCAAqC;IACrC,KAAK,IAAI,IAAI;CAGd"}

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

@@ -0,0 +1,296 @@
+import Database from 'better-sqlite3';
+import { createSchema, createSchemaWithoutVec } from './schema';
+/**
+ * SQLite-backed MemoryAdapter with optional vector search.
+ *
+ * @example
+ * ```typescript
+ * // RDB only (no vector search)
+ * const adapter = new SqliteMemoryAdapter({ dbPath: './memory.db' });
+ * await adapter.init();
+ *
+ * // With vector search
+ * const adapter = new SqliteMemoryAdapter({
+ *   dbPath: './memory.db',
+ *   vector: {
+ *     embedding: openaiEmbedding({ apiKey: '...' }),
+ *   },
+ * });
+ * await adapter.init();
+ * ```
+ */
+export class SqliteMemoryAdapter {
+    constructor(options) {
+        this.vectorEnabled = false;
+        this.opts = options;
+    }
+    /** Initialize the database and create tables. Must be called before use. */
+    async init() {
+        this.db = new Database(this.opts.dbPath);
+        if (this.opts.walMode !== false) {
+            this.db.pragma('journal_mode = WAL');
+        }
+        if (this.opts.vector) {
+            const dim = this.opts.vector.embedding.dimension;
+            if (this.opts.vector.loadVec) {
+                this.opts.vector.loadVec(this.db);
+            }
+            else {
+                const sqliteVec = await import('sqlite-vec');
+                sqliteVec.load(this.db);
+            }
+            this.db.exec(createSchema(dim));
+            this.vectorEnabled = true;
+        }
+        else {
+            this.db.exec(createSchemaWithoutVec());
+        }
+        this.prepareStatements();
+    }
+    prepareStatements() {
+        this.stmts = {
+            insertEpisode: this.db.prepare(`
+        INSERT OR REPLACE INTO episodes
+          (id, timestamp, source_entity, context, appraisal, emotion_v, emotion_a, emotion_d, intensity, importance)
+        VALUES
+          (@id, @timestamp, @sourceEntity, @context, @appraisal, @emotionV, @emotionA, @emotionD, @intensity, @importance)
+      `),
+            insertReflection: this.db.prepare(`
+        INSERT OR REPLACE INTO reflections
+          (id, timestamp, source_entity, content, trigger_type, emotion_v, emotion_a, emotion_d)
+        VALUES
+          (@id, @timestamp, @sourceEntity, @content, @triggerType, @emotionV, @emotionA, @emotionD)
+      `),
+            getReflections: this.db.prepare(`SELECT * FROM reflections WHERE source_entity = ? ORDER BY timestamp DESC LIMIT ?`),
+            getReflectionsAll: this.db.prepare(`SELECT * FROM reflections ORDER BY timestamp DESC LIMIT ?`),
+            getByIds: this.db.prepare(`SELECT * FROM episodes WHERE id IN (SELECT value FROM json_each(?))`),
+            updateEpisode: this.db.prepare(`
+        UPDATE episodes SET importance = @importance, intensity = @intensity,
+          emotion_v = @emotionV, emotion_a = @emotionA, emotion_d = @emotionD
+        WHERE id = @id
+      `),
+            deleteEpisode: this.db.prepare(`DELETE FROM episodes WHERE id = ?`),
+        };
+    }
+    // ── Required methods ──
+    async saveEpisode(episode) {
+        this.stmts.insertEpisode.run({
+            id: episode.id,
+            timestamp: episode.timestamp,
+            sourceEntity: episode.sourceEntity ?? null,
+            context: episode.context ?? null,
+            appraisal: JSON.stringify(episode.appraisal),
+            emotionV: episode.emotionSnapshot.V,
+            emotionA: episode.emotionSnapshot.A,
+            emotionD: episode.emotionSnapshot.D,
+            intensity: episode.intensity,
+            importance: episode.importance,
+        });
+        if (this.vectorEnabled && this.opts.vector) {
+            try {
+                const text = episode.context ?? episode.sourceEntity ?? '';
+                if (text) {
+                    const embedding = await this.opts.vector.embedding.embed(text);
+                    this.indexEmbedding(episode.id, embedding);
+                }
+            }
+            catch {
+                // Best-effort: vector indexing failure doesn't block episode save.
+            }
+        }
+    }
+    async recall(query) {
+        const conditions = [];
+        const params = [];
+        if (query.sourceEntity) {
+            conditions.push('source_entity = ?');
+            params.push(query.sourceEntity);
+        }
+        if (query.context) {
+            conditions.push('context LIKE ?');
+            params.push(`%${query.context}%`);
+        }
+        if (query.minImportance !== undefined) {
+            conditions.push('importance >= ?');
+            params.push(query.minImportance);
+        }
+        if (query.timeRange) {
+            conditions.push('timestamp >= ? AND timestamp <= ?');
+            params.push(query.timeRange[0], query.timeRange[1]);
+        }
+        if (query.valenceRange) {
+            conditions.push('emotion_v >= ? AND emotion_v <= ?');
+            params.push(query.valenceRange[0], query.valenceRange[1]);
+        }
+        const where = conditions.length > 0 ? `WHERE ${conditions.join(' AND ')}` : '';
+        const limit = query.limit ?? 10;
+        params.push(limit);
+        const sql = `SELECT * FROM episodes ${where} ORDER BY timestamp DESC LIMIT ?`;
+        const rows = this.db.prepare(sql).all(...params);
+        return rows.map(rowToEpisode);
+    }
+    async saveReflection(reflection) {
+        this.stmts.insertReflection.run({
+            id: reflection.id,
+            timestamp: reflection.timestamp,
+            sourceEntity: reflection.sourceEntity ?? null,
+            content: reflection.content,
+            triggerType: reflection.trigger,
+            emotionV: reflection.emotionSnapshot.V,
+            emotionA: reflection.emotionSnapshot.A,
+            emotionD: reflection.emotionSnapshot.D,
+        });
+    }
+    async getReflections(sourceEntity) {
+        const maxRows = 100;
+        const rows = sourceEntity
+            ? this.stmts.getReflections.all(sourceEntity, maxRows)
+            : this.stmts.getReflectionsAll.all(maxRows);
+        return rows.map(rowToReflection);
+    }
+    // ── Optional methods ──
+    async semanticRecall(query, options) {
+        if (!this.vectorEnabled || !this.opts.vector || !this.db.open) {
+            return this.recall({ context: query, limit: options?.topK ?? 10 });
+        }
+        const embedding = await this.opts.vector.embedding.embed(query);
+        const topK = options?.topK ?? 5;
+        const hasFilter = options?.filter?.sourceEntity || options?.filter?.minImportance !== undefined;
+        const fetchK = hasFilter ? topK * 4 : topK;
+        const vec = new Float32Array(embedding);
+        const vecRows = this.db.prepare(`SELECT id, distance FROM embeddings WHERE embedding MATCH ? ORDER BY distance LIMIT ?`).all(vec, fetchK);
+        if (vecRows.length === 0)
+            return [];
+        const ids = vecRows.map(r => r.id);
+        const distMap = new Map(vecRows.map(r => [r.id, r.distance]));
+        let sql = `SELECT * FROM episodes WHERE id IN (${ids.map(() => '?').join(',')})`;
+        const params = [...ids];
+        if (options?.filter?.sourceEntity) {
+            sql += ` AND source_entity = ?`;
+            params.push(options.filter.sourceEntity);
+        }
+        if (options?.filter?.minImportance !== undefined) {
+            sql += ` AND importance >= ?`;
+            params.push(options.filter.minImportance);
+        }
+        const rows = this.db.prepare(sql).all(...params);
+        return rows
+            .map(row => rowToEpisode(row))
+            .sort((a, b) => (distMap.get(a.id) ?? 1) - (distMap.get(b.id) ?? 1))
+            .slice(0, topK);
+    }
+    async getByIds(ids) {
+        if (ids.length === 0)
+            return [];
+        const rows = this.stmts.getByIds.all(JSON.stringify(ids));
+        return rows.map(rowToEpisode);
+    }
+    async countEpisodes(query) {
+        const conditions = [];
+        const params = [];
+        if (query.sourceEntity) {
+            conditions.push('source_entity = ?');
+            params.push(query.sourceEntity);
+        }
+        if (query.context) {
+            conditions.push('context LIKE ?');
+            params.push(`%${query.context}%`);
+        }
+        if (query.timeRange) {
+            conditions.push('timestamp >= ? AND timestamp <= ?');
+            params.push(query.timeRange[0], query.timeRange[1]);
+        }
+        const where = conditions.length > 0 ? `WHERE ${conditions.join(' AND ')}` : '';
+        const sql = `SELECT COUNT(*) as cnt FROM episodes ${where}`;
+        const row = this.db.prepare(sql).get(...params);
+        return row.cnt;
+    }
+    async updateEpisode(id, patch) {
+        const existing = this.stmts.getByIds.all(JSON.stringify([id]));
+        if (existing.length === 0)
+            return;
+        const row = existing[0];
+        this.stmts.updateEpisode.run({
+            id,
+            importance: patch.importance ?? row.importance,
+            intensity: patch.intensity ?? row.intensity,
+            emotionV: patch.emotionSnapshot?.V ?? row.emotion_v,
+            emotionA: patch.emotionSnapshot?.A ?? row.emotion_a,
+            emotionD: patch.emotionSnapshot?.D ?? row.emotion_d,
+        });
+    }
+    async deleteEpisode(id) {
+        this.stmts.deleteEpisode.run(id);
+        if (this.vectorEnabled) {
+            try {
+                this.db.prepare(`DELETE FROM embeddings WHERE id = ?`).run(id);
+            }
+            catch {
+                // Best-effort: vector cleanup failure is non-fatal.
+            }
+        }
+    }
+    async expireEpisodes(before, minImportance) {
+        const threshold = minImportance ?? 0;
+        const result = this.db.prepare(`DELETE FROM episodes WHERE timestamp < ? AND importance < ?`).run(before, threshold);
+        if (this.vectorEnabled) {
+            try {
+                this.db.prepare(`DELETE FROM embeddings WHERE id NOT IN (SELECT id FROM episodes)`).run();
+            }
+            catch {
+                // Best-effort cleanup.
+            }
+        }
+        return result.changes;
+    }
+    // ── Utility ──
+    indexEmbedding(id, embedding) {
+        if (!this.db.open)
+            return;
+        try {
+            const vec = new Float32Array(embedding);
+            const exists = this.db.prepare(`SELECT 1 FROM embeddings WHERE id = ?`).get(id);
+            if (exists)
+                return;
+            this.db.prepare(`INSERT INTO embeddings (id, embedding) VALUES (?, ?)`).run(id, vec);
+        }
+        catch {
+            // Silently ignore.
+        }
+    }
+    /** Close the database connection. */
+    close() {
+        this.db.close();
+    }
+}
+// ── Row mappers ──
+function rowToEpisode(row) {
+    return {
+        id: row.id,
+        timestamp: row.timestamp,
+        sourceEntity: row.source_entity ?? undefined,
+        context: row.context ?? undefined,
+        appraisal: JSON.parse(row.appraisal),
+        emotionSnapshot: {
+            V: row.emotion_v,
+            A: row.emotion_a,
+            D: row.emotion_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_type,
+        emotionSnapshot: {
+            V: row.emotion_v,
+            A: row.emotion_a,
+            D: row.emotion_d,
+        },
+    };
+}

package/dist/esm/memory/sqlite/schema.d.ts

@@ -0,0 +1,4 @@
+export declare const SCHEMA_VERSION = 2;
+export declare function createSchema(embeddingDim: number): string;
+export declare function createSchemaWithoutVec(): string;
+//# sourceMappingURL=schema.d.ts.map

package/dist/esm/memory/sqlite/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../../../src/memory/sqlite/schema.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,cAAc,IAAI,CAAC;AAEhC,wBAAgB,YAAY,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CA4CzD;AAED,wBAAgB,sBAAsB,IAAI,MAAM,CAuC/C"}