@slorenzot/memento-core 0.7.0 → 1.0.0

package/dist/MemoryEngine.d.ts

@@ -1,4 +1,4 @@
-import type { Observation, Session, Prompt } from './types.js';
+import type { Observation, Session, Prompt, SearchParams, SearchResult, MergeParams, MergeResult, MergeCandidates, ExportParams, ExportResult } from './types.js';
 export declare class MemoryEngine {
     private db;
     private dbPath;
@@ -28,19 +28,35 @@ export declare class MemoryEngine {
         topicKey?: string | null;
         metadata?: Record<string, unknown>;
     }): Promise<Observation>;
-    deleteObservation(id: number): Promise<void>;
-    getObservation(id: number): Promise<Observation | null>;
-    search(params: {
-        query?: string;
-        type?: Observation['type'];
+    deleteObservation(id: number, reason?: string): Promise<void>;
+    restoreObservation(id: number): Promise<Observation>;
+    purgeObservations(params: {
+        projectId?: string;
+        observationIds?: number[];
+    }): Promise<{
+        purgedCount: number;
+        purgedIds: number[];
+    }>;
+    listDeleted(params: {
         projectId?: string;
-        topicKey?: string;
         limit?: number;
-        offset?: number;
     }): Promise<{
         observations: Observation[];
         total: number;
     }>;
+    findMergeCandidates(params: {
+        projectId: string;
+        strategy: 'by_topic' | 'by_similarity';
+        similarityThreshold?: number;
+    }): Promise<MergeCandidates>;
+    mergeObservations(params: MergeParams): Promise<MergeResult[]>;
+    jaccardSimilarity(text1: string, text2: string): number;
+    exportObservations(params: ExportParams): Promise<ExportResult>;
+    private exportToJSON;
+    private exportToXML;
+    private exportToTXT;
+    getObservation(id: number): Promise<Observation | null>;
+    search(params: SearchParams): Promise<SearchResult>;
     createSession(data: {
         projectId: string;
         endedAt: Date | null;

package/dist/MemoryEngine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"MemoryEngine.d.ts","sourceRoot":"","sources":["../src/MemoryEngine.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAM/D,qBAAa,YAAY;IACvB,OAAO,CAAC,EAAE,CAAM;IAChB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,SAAS,CAAsB;gBAE3B,MAAM,GAAE,MAA4B;IA0BhD,OAAO,CAAC,kBAAkB;IAY1B,SAAS,IAAI,OAAO;IAIpB,YAAY,IAAI,KAAK,GAAG,IAAI;IAI5B,eAAe,IAAI,MAAM;IAIzB,OAAO,CAAC,kBAAkB;IAoE1B,OAAO,CAAC,SAAS;IAIjB,OAAO,CAAC,WAAW;IASnB,OAAO,CAAC,WAAW;IAMb,iBAAiB,CAAC,IAAI,EAAE;QAC5B,SAAS,EAAE,MAAM,CAAC;QAClB,KAAK,EAAE,MAAM,CAAC;QACd,OAAO,EAAE,MAAM,CAAC;QAChB,IAAI,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;QAC1B,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;QACxB,SAAS,EAAE,MAAM,CAAC;QAClB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KACnC,GAAG,OAAO,CAAC,WAAW,CAAC;IA+BlB,iBAAiB,CACrB,EAAE,EAAE,MAAM,EACV,OAAO,EAAE;QACP,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,IAAI,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;QAC3B,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QACzB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KACpC,GACA,OAAO,CAAC,WAAW,CAAC;IAsCjB,iBAAiB,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI5C,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC;IAIvD,MAAM,CAAC,MAAM,EAAE;QACnB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,IAAI,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;QAC3B,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB,GAAG,OAAO,CAAC;QAAE,YAAY,EAAE,WAAW,EAAE,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IAgDrD,aAAa,CAAC,IAAI,EAAE;QACxB,SAAS,EAAE,MAAM,CAAC;QAClB,OAAO,EAAE,IAAI,GAAG,IAAI,CAAC;QACrB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KACnC,GAAG,OAAO,CAAC,OAAO,CAAC;IAoBd,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAUxC,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC;IAI/C,UAAU,CAAC,IAAI,EAAE;QACrB,SAAS,EAAE,MAAM,CAAC;QAClB,OAAO,EAAE,MAAM,CAAC;QAChB,SAAS,EAAE,MAAM,CAAC;QAClB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KACnC,GAAG,OAAO,CAAC,MAAM,CAAC;YAoBL,kBAAkB;YAMlB,cAAc;YAMd,aAAa;IAM3B,OAAO,CAAC,cAAc;IA2BtB,OAAO,CAAC,UAAU;IAmBlB,OAAO,CAAC,SAAS;IAqBjB,KAAK,IAAI,IAAI;CAGd"}
+{"version":3,"file":"MemoryEngine.d.ts","sourceRoot":"","sources":["../src/MemoryEngine.ts"],"names":[],"mappings":"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"}

package/dist/MemoryEngine.js

@@ -46,9 +46,7 @@ class MemoryEngine {
         this.dbPath = dbPath;
         try {
             const dbDir = (0, path_1.dirname)(dbPath);
-            // Create directory structure if it doesn't exist
             (0, fs_1.mkdirSync)(dbDir, { recursive: true });
-            // Create database connection
             this.db = new bun_sqlite_1.Database(dbPath, { create: true });
             this.initializeDatabase();
             console.error(`✓ Database initialized successfully at: ${dbPath}`);
@@ -57,7 +55,6 @@ class MemoryEngine {
             this.initError = error;
             console.error(`✗ Failed to initialize database at ${dbPath}:`, error.message);
             console.error('  The server will start but database operations will fail until this is resolved.');
-            // Create a mock database object to prevent null reference errors
             this.db = this.createMockDatabase();
         }
     }
@@ -65,11 +62,7 @@ class MemoryEngine {
         const throwError = () => {
             throw new Error(`Database not initialized: ${this.initError?.message || 'Unknown error'}`);
         };
-        return {
-            prepare: throwError,
-            exec: throwError,
-            close: () => { },
-        };
+        return { prepare: throwError, exec: throwError, close: () => { }, transaction: throwError };
     }
     isHealthy() {
         return this.initError === null;
@@ -103,6 +96,7 @@ class MemoryEngine {
         topic_key TEXT,
         project_id TEXT NOT NULL,
         created_at INTEGER NOT NULL,
+        deleted_at INTEGER DEFAULT NULL,
         metadata TEXT,
         FOREIGN KEY (session_id) REFERENCES sessions(id)
       );
@@ -124,26 +118,72 @@ class MemoryEngine {
         created_at INTEGER NOT NULL,
         metadata TEXT
       );
-
+    `);
+        // Migrate: add deleted_at column if missing
+        try {
+            this.db.exec('SELECT deleted_at FROM observations LIMIT 0');
+        }
+        catch {
+            try {
+                this.db.exec('ALTER TABLE observations ADD COLUMN deleted_at INTEGER DEFAULT NULL');
+                console.error('✓ Migration: added deleted_at column to observations');
+            }
+            catch {
+                // Column may already exist in a concurrent scenario
+            }
+        }
+        // Create index for deleted_at if not exists
+        this.db.exec('CREATE INDEX IF NOT EXISTS idx_observations_deleted ON observations(deleted_at)');
+        this.db.exec('CREATE INDEX IF NOT EXISTS idx_observations_created ON observations(created_at)');
+        this.db.exec('CREATE INDEX IF NOT EXISTS idx_observations_type ON observations(type)');
+        this.db.exec('CREATE INDEX IF NOT EXISTS idx_observations_project ON observations(project_id)');
+        this.db.exec('CREATE INDEX IF NOT EXISTS idx_observations_topic ON observations(topic_key)');
+        // FTS5
+        this.db.exec(`
       CREATE VIRTUAL TABLE IF NOT EXISTS observations_fts USING fts5(
         title, content, topic_key, project_id,
-        content='observations'
+        content='observations',
+        tokenize='porter unicode61'
       );
-
-      CREATE TRIGGER IF NOT EXISTS observations_ai AFTER INSERT ON observations BEGIN
+    `);
+        // FTS triggers — drop and recreate to ensure latest version
+        this.db.exec('DROP TRIGGER IF EXISTS observations_ai');
+        this.db.exec('DROP TRIGGER IF EXISTS observations_ad');
+        this.db.exec('DROP TRIGGER IF EXISTS observations_au');
+        this.db.exec('DROP TRIGGER IF EXISTS observations_soft_delete');
+        this.db.exec('DROP TRIGGER IF EXISTS observations_undelete');
+        this.db.exec(`
+      CREATE TRIGGER observations_ai AFTER INSERT ON observations BEGIN
         INSERT INTO observations_fts(rowid, title, content, topic_key, project_id)
         VALUES (new.id, new.title, new.content, new.topic_key, new.project_id);
       END;
 
-      CREATE TRIGGER IF NOT EXISTS observations_ad AFTER DELETE ON observations BEGIN
+      CREATE TRIGGER observations_ad AFTER DELETE ON observations BEGIN
         DELETE FROM observations_fts WHERE rowid = old.id;
       END;
 
-      CREATE TRIGGER IF NOT EXISTS observations_au AFTER UPDATE ON observations BEGIN
+      CREATE TRIGGER observations_au AFTER UPDATE ON observations
+        WHEN NEW.deleted_at IS NULL AND OLD.deleted_at IS NULL
+      BEGIN
         DELETE FROM observations_fts WHERE rowid = old.id;
         INSERT INTO observations_fts(rowid, title, content, topic_key, project_id)
         VALUES (new.id, new.title, new.content, new.topic_key, new.project_id);
       END;
+
+      CREATE TRIGGER observations_soft_delete
+        AFTER UPDATE OF deleted_at ON observations
+        WHEN NEW.deleted_at IS NOT NULL AND OLD.deleted_at IS NULL
+      BEGIN
+        DELETE FROM observations_fts WHERE rowid = OLD.id;
+      END;
+
+      CREATE TRIGGER observations_undelete
+        AFTER UPDATE OF deleted_at ON observations
+        WHEN NEW.deleted_at IS NULL AND OLD.deleted_at IS NOT NULL
+      BEGIN
+        INSERT INTO observations_fts(rowid, title, content, topic_key, project_id)
+        VALUES (NEW.id, NEW.title, NEW.content, NEW.topic_key, NEW.project_id);
+      END;
     `);
     }
     serialize(value) {
@@ -164,18 +204,19 @@ class MemoryEngine {
             throw this.initError || new Error('Database not initialized');
         }
     }
+    // ─── Observations CRUD ─────────────────────────────────────
     async createObservation(data) {
         this.checkHealth();
         const uuid = crypto.randomUUID();
         const createdAt = new Date();
         const metadata = this.serialize(data.metadata);
         const result = this.db
-            .prepare(`INSERT INTO observations (uuid, session_id, title, content, type, topic_key, project_id, created_at, metadata) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+            .prepare(`INSERT INTO observations (uuid, session_id, title, content, type, topic_key, project_id, created_at, deleted_at, metadata) VALUES (?, ?, ?, ?, ?, ?, ?, ?, NULL, ?)`)
             .run(uuid, data.sessionId, data.title, data.content, data.type, data.topicKey ?? null, data.projectId, createdAt.getTime(), metadata);
         const id = typeof result.lastInsertRowid === 'bigint'
             ? Number(result.lastInsertRowid)
             : result.lastInsertRowid;
-        const observation = await this.getObservationById(id);
+        const observation = await this.getObservationById(id, true);
         if (!observation)
             throw new Error('Failed to retrieve created observation');
         return observation;
@@ -184,6 +225,8 @@ class MemoryEngine {
         const current = await this.getObservationById(id);
         if (!current)
             throw new Error('Observation not found');
+        if (current.deletedAt)
+            throw new Error('Cannot update a soft-deleted observation');
         const fields = [];
         const values = [];
         if (updates.title !== undefined) {
@@ -210,25 +253,388 @@ class MemoryEngine {
             return current;
         values.push(id);
         this.db.prepare(`UPDATE observations SET ${fields.join(', ')} WHERE id = ?`).run(...values);
-        const updated = await this.getObservationById(id);
+        const updated = await this.getObservationById(id, true);
         if (!updated)
             throw new Error('Failed to update observation');
         return updated;
     }
-    async deleteObservation(id) {
-        this.db.prepare('DELETE FROM observations WHERE id = ?').run(id);
+    // ─── Soft Delete / Restore / Purge ─────────────────────────
+    async deleteObservation(id, reason) {
+        this.checkHealth();
+        const obs = await this.getObservationById(id, true);
+        if (!obs)
+            throw new Error('Observation not found');
+        if (obs.deletedAt)
+            throw new Error('Observation already deleted');
+        const now = Date.now();
+        // If there's a reason, store it in metadata
+        if (reason) {
+            const meta = { ...obs.metadata, deleteReason: reason };
+            this.db
+                .prepare('UPDATE observations SET deleted_at = ?, metadata = ? WHERE id = ?')
+                .run(now, this.serialize(meta), id);
+        }
+        else {
+            this.db.prepare('UPDATE observations SET deleted_at = ? WHERE id = ?').run(now, id);
+        }
+    }
+    async restoreObservation(id) {
+        this.checkHealth();
+        const obs = await this.getObservationById(id, true);
+        if (!obs)
+            throw new Error('Observation not found');
+        if (!obs.deletedAt)
+            throw new Error('Observation is not deleted');
+        this.db.prepare('UPDATE observations SET deleted_at = NULL WHERE id = ?').run(id);
+        const restored = await this.getObservationById(id, true);
+        if (!restored)
+            throw new Error('Failed to restore observation');
+        return restored;
+    }
+    async purgeObservations(params) {
+        this.checkHealth();
+        let sql = 'SELECT id FROM observations WHERE deleted_at IS NOT NULL';
+        const values = [];
+        if (params.observationIds && params.observationIds.length > 0) {
+            const placeholders = params.observationIds.map(() => '?').join(',');
+            sql += ` AND id IN (${placeholders})`;
+            values.push(...params.observationIds);
+        }
+        if (params.projectId) {
+            sql += ' AND project_id = ?';
+            values.push(params.projectId);
+        }
+        const rows = this.db.prepare(sql).all(...values);
+        const ids = rows.map((r) => r.id);
+        if (ids.length === 0)
+            return { purgedCount: 0, purgedIds: [] };
+        const placeholders = ids.map(() => '?').join(',');
+        this.db.prepare(`DELETE FROM observations WHERE id IN (${placeholders})`).run(...ids);
+        return { purgedCount: ids.length, purgedIds: ids };
+    }
+    async listDeleted(params) {
+        this.checkHealth();
+        const { projectId, limit = 20 } = params;
+        let countSql = 'SELECT COUNT(*) as count FROM observations WHERE deleted_at IS NOT NULL';
+        let sql = 'SELECT * FROM observations WHERE deleted_at IS NOT NULL';
+        const values = [];
+        if (projectId) {
+            countSql += ' AND project_id = ?';
+            sql += ' AND project_id = ?';
+            values.push(projectId);
+        }
+        const countResult = this.db.prepare(countSql).get(...values);
+        const total = countResult ? countResult.count : 0;
+        sql += ' ORDER BY deleted_at DESC LIMIT ?';
+        const rows = this.db.prepare(sql).all(...values, limit);
+        const observations = rows.map((row) => this.mapObservation(row));
+        return { observations, total };
+    }
+    // ─── Merge ─────────────────────────────────────────────────
+    async findMergeCandidates(params) {
+        this.checkHealth();
+        const { projectId, strategy, similarityThreshold = 0.85 } = params;
+        const groups = [];
+        if (strategy === 'by_topic') {
+            const rows = this.db
+                .prepare(`SELECT topic_key, COUNT(*) as cnt FROM observations
+           WHERE project_id = ? AND deleted_at IS NULL AND topic_key IS NOT NULL AND topic_key != ''
+           GROUP BY topic_key HAVING cnt >= 2
+           ORDER BY cnt DESC`)
+                .all(projectId);
+            for (const row of rows) {
+                const obs = this.db
+                    .prepare('SELECT * FROM observations WHERE project_id = ? AND topic_key = ? AND deleted_at IS NULL ORDER BY created_at ASC')
+                    .all(projectId, row.topic_key);
+                groups.push({
+                    reason: `topic_key: ${row.topic_key}`,
+                    observations: obs.map((o) => this.mapObservation(o)),
+                    estimatedReduction: obs.length - 1,
+                });
+            }
+        }
+        else {
+            // by_similarity — compare recent observations pairwise
+            const allObs = this.db
+                .prepare('SELECT * FROM observations WHERE project_id = ? AND deleted_at IS NULL ORDER BY created_at DESC LIMIT 200')
+                .all(projectId);
+            const mapped = allObs.map((o) => this.mapObservation(o));
+            const visited = new Set();
+            for (let i = 0; i < mapped.length; i++) {
+                if (visited.has(mapped[i].id))
+                    continue;
+                const group = [mapped[i]];
+                for (let j = i + 1; j < mapped.length; j++) {
+                    if (visited.has(mapped[j].id))
+                        continue;
+                    const sim = this.jaccardSimilarity(mapped[i].content, mapped[j].content);
+                    if (sim >= similarityThreshold) {
+                        group.push(mapped[j]);
+                        visited.add(mapped[j].id);
+                    }
+                }
+                if (group.length >= 2) {
+                    visited.add(mapped[i].id);
+                    groups.push({
+                        reason: `similarity >= ${similarityThreshold}`,
+                        observations: group,
+                        estimatedReduction: group.length - 1,
+                    });
+                }
+            }
+        }
+        const totalCandidates = groups.reduce((acc, g) => acc + g.observations.length, 0);
+        const estimatedReduction = groups.reduce((acc, g) => acc + g.estimatedReduction, 0);
+        return { groups, totalCandidates, estimatedReduction };
+    }
+    async mergeObservations(params) {
+        this.checkHealth();
+        const { projectId, topicKey, observationIds, strategy, dryRun = false } = params;
+        let groups = [];
+        if (strategy === 'by_ids' && observationIds && observationIds.length >= 2) {
+            const obs = [];
+            for (const id of observationIds) {
+                const o = await this.getObservationById(id);
+                if (!o)
+                    throw new Error(`Observation ${id} not found`);
+                if (o.deletedAt)
+                    throw new Error(`Observation ${id} is soft-deleted`);
+                if (o.projectId !== projectId) {
+                    throw new Error(`Observation ${id} belongs to project '${o.projectId}', not '${projectId}'`);
+                }
+                obs.push(o);
+            }
+            groups = [{ observations: obs }];
+        }
+        else if (strategy === 'by_topic') {
+            const candidates = await this.findMergeCandidates({
+                projectId,
+                strategy: 'by_topic',
+            });
+            if (topicKey) {
+                groups = candidates.groups.filter((g) => g.reason === `topic_key: ${topicKey}`);
+            }
+            else {
+                groups = candidates.groups;
+            }
+        }
+        else {
+            const candidates = await this.findMergeCandidates({
+                projectId,
+                strategy: 'by_similarity',
+            });
+            groups = candidates.groups;
+        }
+        if (groups.length === 0)
+            return [];
+        if (dryRun) {
+            return groups.map((g) => ({
+                mergedObservation: g.observations[0], // placeholder
+                deletedIds: g.observations.map((o) => o.id),
+                originalCount: g.observations.length,
+                strategy,
+            }));
+        }
+        const results = [];
+        const doMerge = this.db.transaction(() => {
+            for (const group of groups) {
+                const obs = group.observations.sort((a, b) => a.createdAt.getTime() - b.createdAt.getTime());
+                // Synthesize content
+                const synthTitle = obs[obs.length - 1].title; // most recent title
+                const synthContent = obs
+                    .map((o) => `--- [${o.createdAt.toISOString()}] ${o.title} ---\n${o.content}`)
+                    .join('\n\n');
+                // Most frequent type
+                const typeCounts = {};
+                for (const o of obs) {
+                    typeCounts[o.type] = (typeCounts[o.type] || 0) + 1;
+                }
+                const synthType = Object.entries(typeCounts).sort((a, b) => b[1] - a[1])[0][0];
+                const synthTopicKey = obs.find((o) => o.topicKey)?.topicKey ?? null;
+                const sourceIds = obs.map((o) => o.id);
+                const synthMetadata = this.serialize({
+                    merged: true,
+                    sourceIds,
+                    mergedAt: new Date().toISOString(),
+                    originalCount: obs.length,
+                });
+                const uuid = crypto.randomUUID();
+                const createdAt = Date.now();
+                const sessionId = obs[obs.length - 1].sessionId;
+                const insertResult = this.db
+                    .prepare(`INSERT INTO observations (uuid, session_id, title, content, type, topic_key, project_id, created_at, deleted_at, metadata)
+             VALUES (?, ?, ?, ?, ?, ?, ?, ?, NULL, ?)`)
+                    .run(uuid, sessionId, synthTitle, synthContent, synthType, synthTopicKey, projectId, createdAt, synthMetadata);
+                const newId = typeof insertResult.lastInsertRowid === 'bigint'
+                    ? Number(insertResult.lastInsertRowid)
+                    : insertResult.lastInsertRowid;
+                // Delete originals
+                const placeholders = sourceIds.map(() => '?').join(',');
+                this.db.prepare(`DELETE FROM observations WHERE id IN (${placeholders})`).run(...sourceIds);
+                // Fetch the newly created merged observation
+                const merged = this.db.prepare('SELECT * FROM observations WHERE id = ?').get(newId);
+                results.push({
+                    mergedObservation: this.mapObservation(merged),
+                    deletedIds: sourceIds,
+                    originalCount: obs.length,
+                    strategy,
+                });
+            }
+        });
+        doMerge();
+        return results;
+    }
+    jaccardSimilarity(text1, text2) {
+        const tokenize = (t) => new Set(t
+            .toLowerCase()
+            .split(/\s+/)
+            .filter((w) => w.length > 2));
+        const set1 = tokenize(text1);
+        const set2 = tokenize(text2);
+        const intersection = [...set1].filter((x) => set2.has(x)).length;
+        const union = new Set([...set1, ...set2]).size;
+        return union === 0 ? 0 : intersection / union;
     }
+    // ─── Export ────────────────────────────────────────────────
+    async exportObservations(params) {
+        this.checkHealth();
+        const { format, projectId, type, topicKey, dateFrom, dateTo, includeDeleted = false } = params;
+        let sql = 'SELECT * FROM observations WHERE 1=1';
+        const values = [];
+        if (!includeDeleted) {
+            sql += ' AND deleted_at IS NULL';
+        }
+        if (projectId) {
+            sql += ' AND project_id = ?';
+            values.push(projectId);
+        }
+        if (type) {
+            sql += ' AND type = ?';
+            values.push(type);
+        }
+        if (topicKey) {
+            sql += ' AND topic_key = ?';
+            values.push(topicKey);
+        }
+        if (dateFrom) {
+            sql += ' AND created_at >= ?';
+            values.push(dateFrom.getTime());
+        }
+        if (dateTo) {
+            sql += ' AND created_at <= ?';
+            values.push(dateTo.getTime());
+        }
+        sql += ' ORDER BY created_at ASC';
+        const rows = this.db.prepare(sql).all(...values);
+        const observations = rows.map((row) => this.mapObservation(row));
+        const exportedAt = new Date();
+        let content;
+        switch (format) {
+            case 'json':
+                content = this.exportToJSON(observations, exportedAt, params);
+                break;
+            case 'xml':
+                content = this.exportToXML(observations, exportedAt, params);
+                break;
+            case 'txt':
+                content = this.exportToTXT(observations, exportedAt, params);
+                break;
+            default:
+                throw new Error(`Unsupported export format: ${format}`);
+        }
+        return {
+            content,
+            format,
+            recordCount: observations.length,
+            exportedAt,
+        };
+    }
+    exportToJSON(observations, exportedAt, params) {
+        const data = {
+            exportedAt: exportedAt.toISOString(),
+            version: '1.0',
+            project: params.projectId || 'all',
+            filters: {
+                ...(params.type && { type: params.type }),
+                ...(params.topicKey && { topicKey: params.topicKey }),
+                ...(params.dateFrom && { dateFrom: params.dateFrom.toISOString() }),
+                ...(params.dateTo && { dateTo: params.dateTo.toISOString() }),
+                ...(params.includeDeleted && { includeDeleted: true }),
+            },
+            totalRecords: observations.length,
+            observations: observations.map((o) => ({
+                id: o.id,
+                uuid: o.uuid,
+                title: o.title,
+                content: o.content,
+                type: o.type,
+                topicKey: o.topicKey,
+                projectId: o.projectId,
+                createdAt: o.createdAt.toISOString(),
+                ...(o.deletedAt && { deletedAt: o.deletedAt.toISOString() }),
+                metadata: o.metadata,
+            })),
+        };
+        return JSON.stringify(data, null, 2);
+    }
+    exportToXML(observations, exportedAt, params) {
+        const escapeXml = (s) => s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+        let xml = `<?xml version="1.0" encoding="UTF-8"?>\n`;
+        xml += `<memento-export version="1.0" exportedAt="${exportedAt.toISOString()}">\n`;
+        xml += `  <project>${escapeXml(params.projectId || 'all')}</project>\n`;
+        xml += `  <observations count="${observations.length}">\n`;
+        for (const o of observations) {
+            xml += `    <observation id="${o.id}" uuid="${escapeXml(o.uuid)}">\n`;
+            xml += `      <title>${escapeXml(o.title)}</title>\n`;
+            xml += `      <content><![CDATA[${o.content}]]></content>\n`;
+            xml += `      <type>${escapeXml(o.type)}</type>\n`;
+            if (o.topicKey)
+                xml += `      <topicKey>${escapeXml(o.topicKey)}</topicKey>\n`;
+            xml += `      <projectId>${escapeXml(o.projectId)}</projectId>\n`;
+            xml += `      <createdAt>${o.createdAt.toISOString()}</createdAt>\n`;
+            if (o.deletedAt)
+                xml += `      <deletedAt>${o.deletedAt.toISOString()}</deletedAt>\n`;
+            xml += `    </observation>\n`;
+        }
+        xml += `  </observations>\n`;
+        xml += `</memento-export>\n`;
+        return xml;
+    }
+    exportToTXT(observations, exportedAt, params) {
+        const sep = '═'.repeat(50);
+        const thinSep = '─'.repeat(50);
+        const dateStr = exportedAt.toISOString().split('T')[0];
+        let txt = `${sep}\n`;
+        txt += `MEMENTO EXPORT — Project: ${params.projectId || 'all'}\n`;
+        txt += `Exported: ${dateStr} | Records: ${observations.length}\n`;
+        txt += `${sep}\n\n`;
+        for (const o of observations) {
+            txt += `[#${o.id}] ${o.title}\n`;
+            txt += `Type: ${o.type}`;
+            if (o.topicKey)
+                txt += ` | Topic: ${o.topicKey}`;
+            txt += `\nDate: ${o.createdAt.toISOString().split('T')[0]}`;
+            if (o.deletedAt)
+                txt += ` | DELETED: ${o.deletedAt.toISOString().split('T')[0]}`;
+            txt += `\n\n  ${o.content}\n\n${thinSep}\n\n`;
+        }
+        return txt;
+    }
+    // ─── Search ────────────────────────────────────────────────
     async getObservation(id) {
         return await this.getObservationById(id);
     }
     async search(params) {
-        const { query, type, projectId, topicKey, limit = 100, offset = 0 } = params;
-        let sql = 'SELECT * FROM observations WHERE 1=1';
+        const { query, type, projectId, topicKey, limit = 100, offset = 0, includeDeleted = false, } = params;
+        let sql;
         const values = [];
         if (query) {
             sql =
                 'SELECT observations.* FROM observations JOIN observations_fts ON observations.id = observations_fts.rowid WHERE observations_fts MATCH ?';
             values.push(query);
+            if (!includeDeleted) {
+                sql += ' AND observations.deleted_at IS NULL';
+            }
             if (type) {
                 sql += ' AND observations.type = ?';
                 values.push(type);
@@ -243,6 +649,10 @@ class MemoryEngine {
             }
         }
         else {
+            sql = 'SELECT * FROM observations WHERE 1=1';
+            if (!includeDeleted) {
+                sql += ' AND deleted_at IS NULL';
+            }
             if (type) {
                 sql += ' AND type = ?';
                 values.push(type);
@@ -265,6 +675,7 @@ class MemoryEngine {
         const observations = rows.map((row) => this.mapObservation(row));
         return { observations, total };
     }
+    // ─── Sessions ──────────────────────────────────────────────
     async createSession(data) {
         const uuid = crypto.randomUUID();
         const startedAt = new Date();
@@ -294,6 +705,7 @@ class MemoryEngine {
     async getSession(id) {
         return await this.getSessionById(id);
     }
+    // ─── Prompts ───────────────────────────────────────────────
     async savePrompt(data) {
         const uuid = crypto.randomUUID();
         const createdAt = new Date();
@@ -309,8 +721,13 @@ class MemoryEngine {
             throw new Error('Failed to retrieve saved prompt');
         return prompt;
     }
-    async getObservationById(id) {
-        const row = this.db.prepare('SELECT * FROM observations WHERE id = ?').get(id);
+    // ─── Private helpers ───────────────────────────────────────
+    async getObservationById(id, includeDeleted = false) {
+        let sql = 'SELECT * FROM observations WHERE id = ?';
+        if (!includeDeleted) {
+            sql += ' AND deleted_at IS NULL';
+        }
+        const row = this.db.prepare(sql).get(id);
         if (!row)
             return null;
         return this.mapObservation(row);
@@ -339,6 +756,7 @@ class MemoryEngine {
             topicKey: r.topic_key,
             projectId: r.project_id,
             createdAt: new Date(r.created_at),
+            deletedAt: r.deleted_at ? new Date(r.deleted_at) : null,
             metadata: this.deserialize(r.metadata),
         };
     }