@slorenzot/memento-core 0.7.0 → 2.0.0

package/dist/MemoryEngine.js

@@ -35,41 +35,36 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MemoryEngine = void 0;
 const crypto = __importStar(require("crypto"));
+const EmbeddingService_js_1 = require("./EmbeddingService.js");
 const bun_sqlite_1 = require("bun:sqlite");
 const fs_1 = require("fs");
 const path_1 = require("path");
 class MemoryEngine {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Bun Database type is incompatible with mock pattern
     db;
     dbPath;
     initError = null;
+    embeddingService;
     constructor(dbPath = './data/memento.db') {
-        this.dbPath = dbPath;
+        this.dbPath = (0, path_1.resolve)(dbPath);
+        this.embeddingService = new EmbeddingService_js_1.EmbeddingService();
         try {
-            const dbDir = (0, path_1.dirname)(dbPath);
-            // Create directory structure if it doesn't exist
+            const dbDir = (0, path_1.dirname)(this.dbPath);
             (0, fs_1.mkdirSync)(dbDir, { recursive: true });
-            // Create database connection
-            this.db = new bun_sqlite_1.Database(dbPath, { create: true });
+            this.db = new bun_sqlite_1.Database(this.dbPath, { create: true });
             this.initializeDatabase();
-            console.error(`✓ Database initialized successfully at: ${dbPath}`);
         }
         catch (error) {
-            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.initError = error instanceof Error ? error : new Error(String(error));
             this.db = this.createMockDatabase();
         }
     }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Mock fallback for failed DB init
     createMockDatabase() {
         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;
@@ -83,6 +78,7 @@ class MemoryEngine {
     initializeDatabase() {
         this.db.exec('PRAGMA journal_mode = WAL');
         this.db.exec('PRAGMA foreign_keys = ON');
+        this.db.exec('PRAGMA busy_timeout = 5000');
         this.db.exec(`
       CREATE TABLE IF NOT EXISTS sessions (
         id INTEGER PRIMARY KEY AUTOINCREMENT,
@@ -103,6 +99,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,27 +121,186 @@ class MemoryEngine {
         created_at INTEGER NOT NULL,
         metadata TEXT
       );
-
+    `);
+        // Migrate: add working_dir and aliases columns to projects table (Issue #177)
+        try {
+            this.db.exec('SELECT working_dir FROM projects LIMIT 0');
+        }
+        catch {
+            try {
+                this.db.exec('ALTER TABLE projects ADD COLUMN working_dir TEXT');
+                console.error('✓ Migration: added working_dir column to projects');
+            }
+            catch {
+                // Column may already exist
+            }
+        }
+        try {
+            this.db.exec('SELECT aliases FROM projects LIMIT 0');
+        }
+        catch {
+            try {
+                this.db.exec("ALTER TABLE projects ADD COLUMN aliases TEXT DEFAULT '[]'");
+                console.error('✓ Migration: added aliases column to projects');
+            }
+            catch {
+                // Column may already exist
+            }
+        }
+        // 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)');
+        // Migrate: add scope column if missing
+        try {
+            this.db.exec('SELECT scope FROM observations LIMIT 0');
+        }
+        catch {
+            try {
+                this.db.exec("ALTER TABLE observations ADD COLUMN scope TEXT NOT NULL DEFAULT 'project'");
+                console.error('✓ Migration: added scope column to observations');
+            }
+            catch {
+                // Column may already exist in a concurrent scenario
+            }
+        }
+        this.db.exec('CREATE INDEX IF NOT EXISTS idx_observations_scope ON observations(scope)');
+        // Migrate: add revision_count column if missing
+        try {
+            this.db.exec('SELECT revision_count FROM observations LIMIT 0');
+        }
+        catch {
+            try {
+                this.db.exec('ALTER TABLE observations ADD COLUMN revision_count INTEGER NOT NULL DEFAULT 0');
+                console.error('✓ Migration: added revision_count column to observations');
+            }
+            catch {
+                // Column may already exist in a concurrent scenario
+            }
+        }
+        // Migrate: add pinned column if missing (Issue #50)
+        try {
+            this.db.exec('SELECT pinned FROM observations LIMIT 0');
+        }
+        catch {
+            try {
+                this.db.exec('ALTER TABLE observations ADD COLUMN pinned INTEGER NOT NULL DEFAULT 0');
+                console.error('✓ Migration: added pinned column to observations');
+            }
+            catch {
+                // Column may already exist in a concurrent scenario
+            }
+        }
+        this.db.exec('CREATE INDEX IF NOT EXISTS idx_observations_pinned ON observations(pinned) WHERE pinned = 1');
+        // Migrate: add read_only column if missing (Issue #54)
+        try {
+            this.db.exec('SELECT read_only FROM observations LIMIT 0');
+        }
+        catch {
+            try {
+                this.db.exec('ALTER TABLE observations ADD COLUMN read_only INTEGER NOT NULL DEFAULT 0');
+                console.error('✓ Migration: added read_only column to observations');
+            }
+            catch {
+                // Column may already exist in a concurrent scenario
+            }
+        }
+        // Migrate: clean up empty string topic_key → NULL (Issue #69)
+        try {
+            const result = this.db.prepare("UPDATE observations SET topic_key = NULL WHERE topic_key = ''").run();
+            if (result.changes > 0) {
+                console.error(`✓ Migration: cleaned up ${result.changes} empty topic_key value(s)`);
+            }
+        }
+        catch {
+            // Table may not have topic_key column yet
+        }
+        // FTS5 — standalone mode (no content= parameter).
+        // FTS5 owns its own data copy, supports full CRUD (INSERT, DELETE, UPDATE),
+        // and avoids SQLITE_CORRUPT_VTAB that occurred with content='observations' mode
+        // under bun:sqlite + WAL + concurrent access. See: GitHub Issue #68.
+        this.db.exec(`
       CREATE VIRTUAL TABLE IF NOT EXISTS observations_fts USING fts5(
         title, content, topic_key, project_id,
-        content='observations'
+        tokenize='porter unicode61'
+      );
+    `);
+        // FTS5 sync is managed at application-level in each CRUD method.
+        // Previous trigger-based approach caused SQLITE_CORRUPT_VTAB under
+        // concurrent access (DELETE+INSERT on FTS5 virtual table within a trigger).
+        // See: GitHub Issue #68
+        // ─── Journal tables (append-only evidence) ────────────────
+        this.db.exec(`
+      CREATE TABLE IF NOT EXISTS journal (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        uuid TEXT UNIQUE NOT NULL,
+        project_id TEXT NOT NULL,
+        session_id INTEGER REFERENCES sessions(id),
+        title TEXT NOT NULL,
+        body TEXT NOT NULL,
+        model TEXT,
+        provider TEXT,
+        agent TEXT,
+        superseded_by INTEGER REFERENCES journal(id),
+        invalidated_at INTEGER,
+        metadata TEXT,
+        created_at INTEGER NOT NULL
       );
 
-      CREATE TRIGGER IF NOT EXISTS 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
-        DELETE FROM observations_fts WHERE rowid = old.id;
-      END;
-
-      CREATE TRIGGER IF NOT EXISTS observations_au AFTER UPDATE ON observations 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);
+      CREATE TABLE IF NOT EXISTS journal_tags (
+        journal_id INTEGER NOT NULL REFERENCES journal(id) ON DELETE CASCADE,
+        tag TEXT NOT NULL,
+        PRIMARY KEY (journal_id, tag)
+      );
+    `);
+        // Journal indexes
+        this.db.exec('CREATE INDEX IF NOT EXISTS idx_journal_project ON journal(project_id)');
+        this.db.exec('CREATE INDEX IF NOT EXISTS idx_journal_session ON journal(session_id)');
+        this.db.exec('CREATE INDEX IF NOT EXISTS idx_journal_created ON journal(created_at)');
+        this.db.exec('CREATE INDEX IF NOT EXISTS idx_journal_superseded ON journal(superseded_by)');
+        this.db.exec('CREATE INDEX IF NOT EXISTS idx_journal_tags_tag ON journal_tags(tag)');
+        // Journal FTS5
+        this.db.exec(`
+      CREATE VIRTUAL TABLE IF NOT EXISTS journal_fts USING fts5(
+        title, body, project_id,
+        content='journal',
+        tokenize='porter unicode61'
+      );
+    `);
+        // Journal FTS trigger — insert only (append-only: no update/delete triggers)
+        this.db.exec('DROP TRIGGER IF EXISTS journal_ai');
+        this.db.exec(`
+      CREATE TRIGGER journal_ai AFTER INSERT ON journal BEGIN
+        INSERT INTO journal_fts(rowid, title, body, project_id)
+        VALUES (new.id, new.title, new.body, new.project_id);
       END;
     `);
+        // ─── Embeddings table (semantic search) ──────────────────────
+        this.db.exec(`
+      CREATE TABLE IF NOT EXISTS embeddings (
+        observation_id INTEGER PRIMARY KEY REFERENCES observations(id) ON DELETE CASCADE,
+        embedding BLOB NOT NULL,
+        model TEXT NOT NULL DEFAULT 'all-MiniLM-L6-v2',
+        dimensions INTEGER NOT NULL DEFAULT 384,
+        generated_at INTEGER NOT NULL
+      );
+    `);
+        this.db.exec('CREATE INDEX IF NOT EXISTS idx_embeddings_obs ON embeddings(observation_id)');
     }
     serialize(value) {
         return JSON.stringify(value);
@@ -164,26 +320,70 @@ class MemoryEngine {
             throw this.initError || new Error('Database not initialized');
         }
     }
+    /**
+     * Retry wrapper with exponential backoff for SQLITE_BUSY errors.
+     * Dual defense: PRAGMA busy_timeout (5s) catches most contention,
+     * this catches the rest with retries.
+     */
+    async withRetry(operation, maxRetries = 3, baseDelay = 100) {
+        for (let attempt = 0; attempt <= maxRetries; attempt++) {
+            try {
+                return operation();
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                const isBusy = message.includes('SQLITE_BUSY') || message.includes('database is locked');
+                if (!isBusy || attempt === maxRetries) {
+                    throw error;
+                }
+                const delay = baseDelay * Math.pow(2, attempt);
+                await new Promise((resolve) => setTimeout(resolve, delay));
+            }
+        }
+        throw new Error('Max retries exceeded');
+    }
+    // ─── 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 (?, ?, ?, ?, ?, ?, ?, ?, ?)`)
-            .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 scope = data.scope || 'project';
+        const pinned = data.pinned ? 1 : 0;
+        const readOnly = data.readOnly ? 1 : 0;
+        const id = await this.withRetry(() => {
+            const result = this.db
+                .prepare(`INSERT INTO observations (uuid, session_id, title, content, type, topic_key, project_id, created_at, deleted_at, metadata, scope, pinned, read_only) VALUES (?, ?, ?, ?, ?, ?, ?, ?, NULL, ?, ?, ?, ?)`)
+                .run(uuid, data.sessionId, data.title, data.content, data.type, data.topicKey ?? null, data.projectId, createdAt.getTime(), metadata, scope, pinned, readOnly);
+            const insertId = typeof result.lastInsertRowid === 'bigint'
+                ? Number(result.lastInsertRowid)
+                : result.lastInsertRowid;
+            // Application-level FTS5 sync (was trigger observations_ai)
+            this.db.prepare('INSERT INTO observations_fts(rowid, title, content, topic_key, project_id) VALUES (?, ?, ?, ?, ?)').run(insertId, data.title, data.content, data.topicKey ?? '', data.projectId);
+            return insertId;
+        });
+        const observation = await this.getObservationById(id, true);
         if (!observation)
             throw new Error('Failed to retrieve created observation');
+        // Generate embedding asynchronously (non-blocking, fire-and-forget)
+        this.generateEmbedding(id).catch(() => {
+            // Silently ignore — embedding generation failure doesn't affect save
+        });
         return observation;
     }
     async updateObservation(id, updates) {
         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');
+        // Read-only protection: only allow changing readOnly itself
+        if (current.readOnly) {
+            const nonReadOnlyFields = Object.keys(updates).filter(k => k !== 'readOnly');
+            if (nonReadOnlyFields.length > 0) {
+                throw new Error(`Observation #${id} is read-only. Only readOnly flag can be changed.`);
+            }
+        }
         const fields = [];
         const values = [];
         if (updates.title !== undefined) {
@@ -200,35 +400,501 @@ class MemoryEngine {
         }
         if (updates.topicKey !== undefined) {
             fields.push('topic_key = ?');
-            values.push(updates.topicKey || '');
+            values.push(updates.topicKey ?? null);
         }
         if (updates.metadata !== undefined) {
             fields.push('metadata = ?');
             values.push(this.serialize(updates.metadata));
         }
+        if (updates.pinned !== undefined) {
+            fields.push('pinned = ?');
+            values.push(updates.pinned ? 1 : 0);
+        }
+        if (updates.readOnly !== undefined) {
+            fields.push('read_only = ?');
+            values.push(updates.readOnly ? 1 : 0);
+        }
         if (fields.length === 0)
             return current;
+        fields.push('revision_count = revision_count + 1');
         values.push(id);
-        this.db.prepare(`UPDATE observations SET ${fields.join(', ')} WHERE id = ?`).run(...values);
-        const updated = await this.getObservationById(id);
+        // Check if any FTS5-indexed fields changed
+        const hasFtsUpdate = updates.title !== undefined ||
+            updates.content !== undefined ||
+            updates.topicKey !== undefined;
+        if (hasFtsUpdate) {
+            // Atomic transaction: UPDATE + FTS5 rebuild
+            // Replaces trigger observations_au that caused SQLITE_CORRUPT_VTAB (#68)
+            await this.withRetry(() => {
+                this.db.transaction(() => {
+                    this.db.prepare(`UPDATE observations SET ${fields.join(', ')} WHERE id = ?`).run(...values);
+                    // Re-read updated row for FTS5 sync
+                    const row = this.db
+                        .prepare('SELECT title, content, topic_key, project_id FROM observations WHERE id = ?')
+                        .get(id);
+                    if (row) {
+                        this.db.prepare('DELETE FROM observations_fts WHERE rowid = ?').run(id);
+                        this.db.prepare('INSERT INTO observations_fts(rowid, title, content, topic_key, project_id) VALUES (?, ?, ?, ?, ?)').run(id, row.title, row.content, row.topic_key, row.project_id);
+                    }
+                })();
+            });
+        }
+        else {
+            // No FTS5 fields changed — just UPDATE
+            await this.withRetry(() => this.db.prepare(`UPDATE observations SET ${fields.join(', ')} WHERE id = ?`).run(...values));
+        }
+        const updated = await this.getObservationById(id, true);
         if (!updated)
             throw new Error('Failed to update observation');
+        // Regenerate embedding if content-affecting fields changed
+        if (hasFtsUpdate) {
+            this.generateEmbedding(id).catch(() => {
+                // Silently ignore — embedding regeneration failure doesn't affect update
+            });
+        }
         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');
+        if (obs.readOnly)
+            throw new Error(`Observation #${id} is read-only. Cannot delete.`);
+        const now = Date.now();
+        // If there's a reason, store it in metadata
+        if (reason) {
+            const meta = { ...obs.metadata, deleteReason: reason };
+            await this.withRetry(() => {
+                this.db
+                    .prepare('UPDATE observations SET deleted_at = ?, metadata = ? WHERE id = ?')
+                    .run(now, this.serialize(meta), id);
+                // Application-level FTS5 sync (was trigger observations_soft_delete)
+                this.db.prepare('DELETE FROM observations_fts WHERE rowid = ?').run(id);
+            });
+        }
+        else {
+            await this.withRetry(() => {
+                this.db.prepare('UPDATE observations SET deleted_at = ? WHERE id = ?').run(now, id);
+                // Application-level FTS5 sync (was trigger observations_soft_delete)
+                this.db.prepare('DELETE FROM observations_fts WHERE rowid = ?').run(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');
+        await this.withRetry(() => {
+            this.db.prepare('UPDATE observations SET deleted_at = NULL WHERE id = ?').run(id);
+            // Application-level FTS5 sync (was trigger observations_undelete)
+            const row = this.db
+                .prepare('SELECT title, content, topic_key, project_id FROM observations WHERE id = ?')
+                .get(id);
+            if (row) {
+                this.db.prepare('INSERT INTO observations_fts(rowid, title, content, topic_key, project_id) VALUES (?, ?, ?, ?, ?)').run(id, row.title, row.content, row.topic_key, row.project_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(',');
+        // Application-level FTS5 sync (was trigger observations_ad)
+        this.db.prepare(`DELETE FROM observations_fts WHERE rowid IN (${placeholders})`).run(...ids);
+        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, id DESC LIMIT ?';
+        const rows = this.db.prepare(sql).all(...values, limit);
+        const observations = rows.map((row) => this.mapObservation(row));
+        return { observations, total };
     }
-    async getObservation(id) {
-        return await this.getObservationById(id);
+    // ─── 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, id 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, id 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 search(params) {
-        const { query, type, projectId, topicKey, limit = 100, offset = 0 } = params;
+    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 [];
+        // Read-only protection: reject merge if any source observation is read-only
+        for (const group of groups) {
+            for (const obs of group.observations) {
+                if (obs.readOnly) {
+                    throw new Error(`Cannot merge: observation #${obs.id} is read-only.`);
+                }
+            }
+        }
+        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;
+                // Application-level FTS5 sync: insert merged, delete originals
+                this.db.prepare('INSERT INTO observations_fts(rowid, title, content, topic_key, project_id) VALUES (?, ?, ?, ?, ?)').run(newId, synthTitle, synthContent, synthTopicKey ?? '', projectId);
+                // Delete originals (from both observations and observations_fts)
+                const placeholders = sourceIds.map(() => '?').join(',');
+                this.db.prepare(`DELETE FROM observations_fts WHERE rowid IN (${placeholders})`).run(...sourceIds);
+                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 (query) {
+        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, id 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 ────────────────────────────────────────────────
+    /**
+     * Sanitize a user query for safe use in FTS5 MATCH.
+     * Strips FTS5 operators and special characters that would cause syntax errors.
+     * Returns empty string if nothing survives sanitization.
+     */
+    sanitizeFTS5Query(input) {
+        return input
+            .replace(/[^a-zA-Z0-9\s]/g, ' ') // Keep only alphanumeric and whitespace
+            .replace(/\s+/g, ' ') // Collapse whitespace
+            .trim();
+    }
+    async getObservation(id, includeDeleted = false) {
+        return await this.getObservationById(id, includeDeleted);
+    }
+    async search(params) {
+        const mode = params.mode || 'keyword';
+        // Semantic and hybrid modes require a query string
+        if ((mode === 'semantic' || mode === 'hybrid') && !params.query) {
+            // Fall back to keyword mode if no query provided
+            return this.searchKeyword(params);
+        }
+        switch (mode) {
+            case 'semantic':
+                return this.searchSemantic(params);
+            case 'hybrid':
+                return this.searchHybrid(params);
+            case 'keyword':
+            default:
+                return this.searchKeyword(params);
+        }
+    }
+    /**
+     * Keyword search using existing FTS5 (unchanged behavior).
+     */
+    async searchKeyword(params) {
+        const { query, type, projectId, topicKey, limit = 100, offset = 0, includeDeleted = false, scope, sessionId, } = params;
+        let sql;
+        const values = [];
+        const sanitizedQuery = query ? this.sanitizeFTS5Query(query) : '';
+        if (sanitizedQuery) {
             sql =
                 'SELECT observations.* FROM observations JOIN observations_fts ON observations.id = observations_fts.rowid WHERE observations_fts MATCH ?';
-            values.push(query);
+            values.push(sanitizedQuery);
+            if (!includeDeleted) {
+                sql += ' AND observations.deleted_at IS NULL';
+            }
             if (type) {
                 sql += ' AND observations.type = ?';
                 values.push(type);
@@ -241,8 +907,20 @@ class MemoryEngine {
                 sql += ' AND observations.topic_key = ?';
                 values.push(topicKey);
             }
+            if (scope) {
+                sql += ' AND observations.scope = ?';
+                values.push(scope);
+            }
+            if (sessionId) {
+                sql += ' AND observations.session_id = ?';
+                values.push(sessionId);
+            }
         }
         else {
+            sql = 'SELECT * FROM observations WHERE 1=1';
+            if (!includeDeleted) {
+                sql += ' AND deleted_at IS NULL';
+            }
             if (type) {
                 sql += ' AND type = ?';
                 values.push(type);
@@ -255,16 +933,196 @@ class MemoryEngine {
                 sql += ' AND topic_key = ?';
                 values.push(topicKey);
             }
+            if (scope) {
+                sql += ' AND scope = ?';
+                values.push(scope);
+            }
+            if (sessionId) {
+                sql += ' AND session_id = ?';
+                values.push(sessionId);
+            }
         }
         const countSql = sql.replace(/SELECT.*?FROM/, 'SELECT COUNT(*) as count FROM');
         const countResult = this.db.prepare(countSql).get(...values);
         const total = countResult ? countResult.count : 0;
-        sql += ' ORDER BY created_at DESC LIMIT ? OFFSET ?';
+        sql += ' ORDER BY created_at DESC, id DESC LIMIT ? OFFSET ?';
         values.push(limit, offset);
         const rows = this.db.prepare(sql).all(...values);
         const observations = rows.map((row) => this.mapObservation(row));
         return { observations, total };
     }
+    /**
+     * Semantic search using cosine similarity on embeddings.
+     * Falls back to keyword search if embeddings are unavailable.
+     */
+    async searchSemantic(params) {
+        this.checkHealth();
+        const { query, type, projectId, topicKey, limit = 10, scope } = params;
+        if (!query)
+            return { observations: [], total: 0 };
+        // Generate query embedding
+        const queryEmbedding = await this.embeddingService.generate(query);
+        if (!queryEmbedding) {
+            // Fall back to keyword search if embedding service unavailable
+            return this.searchKeyword(params);
+        }
+        // Build candidate filter
+        let candidateSql = 'SELECT o.* FROM observations o WHERE o.deleted_at IS NULL';
+        const values = [];
+        if (type) {
+            candidateSql += ' AND o.type = ?';
+            values.push(type);
+        }
+        if (projectId) {
+            candidateSql += ' AND o.project_id = ?';
+            values.push(projectId);
+        }
+        if (topicKey) {
+            candidateSql += ' AND o.topic_key = ?';
+            values.push(topicKey);
+        }
+        if (scope) {
+            candidateSql += ' AND o.scope = ?';
+            values.push(scope);
+        }
+        if (params.sessionId) {
+            candidateSql += ' AND o.session_id = ?';
+            values.push(params.sessionId);
+        }
+        // Only observations that have embeddings
+        candidateSql += ' AND EXISTS (SELECT 1 FROM embeddings e WHERE e.observation_id = o.id)';
+        const rows = this.db.prepare(candidateSql).all(...values);
+        const candidates = rows.map((row) => this.mapObservation(row));
+        // Score each candidate by cosine similarity
+        const scored = [];
+        for (const obs of candidates) {
+            const embeddingRow = this.db
+                .prepare('SELECT embedding, dimensions FROM embeddings WHERE observation_id = ?')
+                .get(obs.id);
+            if (!embeddingRow)
+                continue;
+            const storedEmbedding = EmbeddingService_js_1.EmbeddingService.deserializeEmbedding(embeddingRow.embedding, embeddingRow.dimensions);
+            const score = EmbeddingService_js_1.EmbeddingService.cosineSimilarity(queryEmbedding.embedding, storedEmbedding);
+            scored.push({ observation: obs, score });
+        }
+        // Sort by score descending
+        scored.sort((a, b) => b.score - a.score);
+        const total = scored.length;
+        const results = scored.slice(0, limit);
+        const scores = new Map(results.map((r) => [r.observation.id, r.score]));
+        const observations = results.map((r) => r.observation);
+        return { observations, total, scores };
+    }
+    /**
+     * Hybrid search combining FTS5 BM25 + cosine similarity.
+     * Score = 0.4 * bm25_normalized + 0.6 * cosine_similarity
+     */
+    async searchHybrid(params) {
+        this.checkHealth();
+        const { query, limit = 10 } = params;
+        if (!query)
+            return { observations: [], total: 0 };
+        // Run both searches in parallel
+        const [keywordResult, semanticResult] = await Promise.all([
+            this.searchKeyword({ ...params, limit: limit * 3 }), // Get more candidates for re-ranking
+            this.searchSemantic({ ...params, limit: limit * 3 }),
+        ]);
+        // Normalize BM25 scores (use position-based ranking as proxy)
+        const maxBm25Rank = keywordResult.observations.length;
+        const bm25Scores = new Map();
+        keywordResult.observations.forEach((obs, index) => {
+            // Higher rank (earlier) = higher score
+            bm25Scores.set(obs.id, maxBm25Rank > 0 ? 1 - index / maxBm25Rank : 0);
+        });
+        // Get semantic scores
+        const semanticScores = semanticResult.scores || new Map();
+        // Combine all unique observation IDs
+        const allIds = new Set([...bm25Scores.keys(), ...semanticScores.keys()]);
+        // Calculate hybrid scores
+        const hybridWeight = { bm25: 0.4, cosine: 0.6 };
+        const scored = [];
+        for (const id of allIds) {
+            const bm25 = bm25Scores.get(id) ?? 0;
+            const cosine = semanticScores.get(id) ?? 0;
+            const hybridScore = hybridWeight.bm25 * bm25 + hybridWeight.cosine * cosine;
+            scored.push({ observationId: id, score: hybridScore });
+        }
+        scored.sort((a, b) => b.score - a.score);
+        const topResults = scored.slice(0, limit);
+        // Fetch full observations
+        const observations = [];
+        const scores = new Map();
+        for (const result of topResults) {
+            const obs = await this.getObservation(result.observationId);
+            if (obs) {
+                observations.push(obs);
+                scores.set(obs.id, result.score);
+            }
+        }
+        return { observations, total: scored.length, scores };
+    }
+    // ─── Embedding Management ──────────────────────────────────
+    /**
+     * Generate and store embedding for an observation.
+     * Non-blocking: does not throw on failure.
+     */
+    async generateEmbedding(observationId) {
+        this.checkHealth();
+        const obs = await this.getObservationById(observationId);
+        if (!obs)
+            return false;
+        const text = `${obs.title} ${obs.content}`;
+        const result = await this.embeddingService.generate(text);
+        if (!result)
+            return false;
+        const blob = EmbeddingService_js_1.EmbeddingService.serializeEmbedding(result.embedding);
+        const now = Date.now();
+        await this.withRetry(() => {
+            this.db.prepare(`INSERT OR REPLACE INTO embeddings (observation_id, embedding, model, dimensions, generated_at)
+         VALUES (?, ?, ?, ?, ?)`).run(observationId, blob, result.model, result.dimensions, now);
+        });
+        return true;
+    }
+    /**
+     * Delete embedding for an observation.
+     */
+    async deleteEmbedding(observationId) {
+        this.checkHealth();
+        this.db.prepare('DELETE FROM embeddings WHERE observation_id = ?').run(observationId);
+    }
+    /**
+     * Get embedding status (is the service available?).
+     */
+    async getEmbeddingStatus() {
+        return this.embeddingService.status;
+    }
+    /**
+     * Backfill embeddings for observations that don't have them.
+     * Processes in batches. Returns count of embeddings generated.
+     */
+    async backfillEmbeddings(batchSize = 50) {
+        this.checkHealth();
+        const rows = this.db.prepare(`SELECT o.id FROM observations o
+       WHERE o.deleted_at IS NULL
+       AND NOT EXISTS (SELECT 1 FROM embeddings e WHERE e.observation_id = o.id)
+       ORDER BY o.id ASC`).all();
+        let processed = 0;
+        let failed = 0;
+        for (let i = 0; i < rows.length; i += batchSize) {
+            const batch = rows.slice(i, i + batchSize);
+            for (const row of batch) {
+                const success = await this.generateEmbedding(row.id);
+                if (success) {
+                    processed++;
+                }
+                else {
+                    failed++;
+                }
+            }
+        }
+        return { processed, failed };
+    }
+    // ─── Sessions ──────────────────────────────────────────────
     async createSession(data) {
         const uuid = crypto.randomUUID();
         const startedAt = new Date();
@@ -278,8 +1136,62 @@ class MemoryEngine {
         const session = await this.getSessionById(id);
         if (!session)
             throw new Error('Failed to retrieve created session');
+        // Seed default observations if requested and this is the first session for the project
+        if (data.seedIfEmpty) {
+            await this.seedIfEmpty(data.projectId, id);
+        }
         return session;
     }
+    /**
+     * Seed default observations if project has no observations yet.
+     * Creates 3 seeds: persona (personal scope), human (personal), project (project scope).
+     * Public so that `memento init` can call it directly.
+     */
+    async seedIfEmpty(projectId, sessionId) {
+        // Check if project already has observations
+        const existing = this.db
+            .prepare('SELECT COUNT(*) as count FROM observations WHERE project_id = ? AND deleted_at IS NULL')
+            .get(projectId);
+        if (existing && existing.count > 0)
+            return;
+        // Seed personal-scope observations (only if no personal observations exist)
+        const personalExisting = this.db
+            .prepare("SELECT COUNT(*) as count FROM observations WHERE scope = 'personal' AND deleted_at IS NULL")
+            .get();
+        if (!personalExisting || personalExisting.count === 0) {
+            await this.createObservation({
+                sessionId,
+                title: 'Agent Persona',
+                content: 'Instructions for how the agent should behave and respond. Fill this in with your preferred communication style, tone, and approach.',
+                type: 'preference',
+                topicKey: 'persona',
+                projectId,
+                metadata: { seed: true },
+                scope: 'personal',
+            });
+            await this.createObservation({
+                sessionId,
+                title: 'User Preferences',
+                content: 'Key details about the user: preferred language, frameworks, communication style, constraints, and habits.',
+                type: 'preference',
+                topicKey: 'human',
+                projectId,
+                metadata: { seed: true },
+                scope: 'personal',
+            });
+        }
+        // Seed project-scope observation
+        await this.createObservation({
+            sessionId,
+            title: 'Project Knowledge',
+            content: 'Durable, high-signal information about this codebase: commands, architecture notes, conventions, and gotchas.',
+            type: 'note',
+            topicKey: 'project',
+            projectId,
+            metadata: { seed: true },
+            scope: 'project',
+        });
+    }
     async endSession(id) {
         const session = await this.getSessionById(id);
         if (!session)
@@ -291,9 +1203,69 @@ class MemoryEngine {
             throw new Error('Failed to update session');
         return updated;
     }
+    /**
+     * Close stale (orphaned) sessions for a specific project.
+     * Sessions are considered stale if they have no ended_at AND started_at is older than maxAgeMs.
+     * Auto-closed sessions receive metadata: { auto_closed: true, reason: 'stale', closed_at: <timestamp> }.
+     * Returns the count of closed sessions.
+     */
+    closeStaleSessionsForProject(projectId, maxAgeMs) {
+        this.checkHealth();
+        const maxAge = maxAgeMs ?? 24 * 60 * 60 * 1000; // default 24h
+        const cutoff = Date.now() - maxAge;
+        const now = Date.now();
+        // Get sessions to close (need to update metadata individually)
+        const staleRows = this.db.prepare('SELECT id, metadata FROM sessions WHERE ended_at IS NULL AND project_id = ? AND started_at < ?').all(projectId, cutoff);
+        if (staleRows.length === 0)
+            return { closed: 0 };
+        const updateStmt = this.db.prepare('UPDATE sessions SET ended_at = ?, metadata = ? WHERE id = ?');
+        let closed = 0;
+        for (const row of staleRows) {
+            const existingMeta = this.deserialize(row.metadata);
+            const mergedMeta = {
+                ...existingMeta,
+                auto_closed: true,
+                reason: 'stale',
+                closed_at: now,
+            };
+            updateStmt.run(now, this.serialize(mergedMeta), row.id);
+            closed++;
+        }
+        return { closed };
+    }
+    /**
+     * Close ALL stale (orphaned) sessions across all projects.
+     * Sessions are considered stale if they have no ended_at AND started_at is older than maxAgeMs.
+     * Returns the count of closed sessions.
+     */
+    closeStaleSessions(maxAgeMs) {
+        this.checkHealth();
+        const maxAge = maxAgeMs ?? 24 * 60 * 60 * 1000; // default 24h
+        const cutoff = Date.now() - maxAge;
+        const now = Date.now();
+        // Get sessions to close
+        const staleRows = this.db.prepare('SELECT id, metadata FROM sessions WHERE ended_at IS NULL AND started_at < ?').all(cutoff);
+        if (staleRows.length === 0)
+            return { closed: 0 };
+        const updateStmt = this.db.prepare('UPDATE sessions SET ended_at = ?, metadata = ? WHERE id = ?');
+        let closed = 0;
+        for (const row of staleRows) {
+            const existingMeta = this.deserialize(row.metadata);
+            const mergedMeta = {
+                ...existingMeta,
+                auto_closed: true,
+                reason: 'stale',
+                closed_at: now,
+            };
+            updateStmt.run(now, this.serialize(mergedMeta), row.id);
+            closed++;
+        }
+        return { closed };
+    }
     async getSession(id) {
         return await this.getSessionById(id);
     }
+    // ─── Prompts ───────────────────────────────────────────────
     async savePrompt(data) {
         const uuid = crypto.randomUUID();
         const createdAt = new Date();
@@ -309,11 +1281,140 @@ 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);
+    // ─── Prompt Injection (OpenCode Plugin) ──────────────────────
+    /**
+     * Select observations for prompt injection based on config.
+     * Returns observations sorted deterministically for prompt caching:
+     * 1. Pinned observations (by ID ascending)
+     * 2. Non-pinned observations (by ID ascending)
+     */
+    selectForPrompt(config) {
+        this.checkHealth();
+        const types = config.types.map((t) => `'${t}'`).join(',');
+        const values = [];
+        let sql = `SELECT * FROM observations WHERE deleted_at IS NULL AND type IN (${types})`;
+        if (config.projectId) {
+            sql += ' AND project_id = ?';
+            values.push(config.projectId);
+        }
+        if (config.strategy === 'pinned-only') {
+            sql += ' AND pinned = 1';
+        }
+        // Deterministic sort: pinned first (by ID ASC), then non-pinned (by ID ASC)
+        sql += ' ORDER BY pinned DESC, id ASC';
+        // Fetch more than needed to allow for token budget trimming
+        const rows = this.db.prepare(sql).all(...values);
+        const observations = rows.map((row) => this.mapObservation(row));
+        // Apply maxObservations limit
+        const limited = observations.slice(0, config.maxObservations);
+        // Apply token budget
+        const maxChars = config.maxTokens * 4; // approximate: chars / 4 = tokens
+        let totalChars = 0;
+        const result = [];
+        for (const obs of limited) {
+            const obsChars = this.estimateObservationChars(obs);
+            if (totalChars + obsChars > maxChars && result.length > 0) {
+                break;
+            }
+            totalChars += obsChars;
+            result.push(obs);
+        }
+        // Re-sort: pinned first by ID ASC, then non-pinned by ID ASC
+        // (ensures deterministic order even after budget trim)
+        result.sort((a, b) => {
+            if (a.pinned !== b.pinned)
+                return a.pinned ? -1 : 1;
+            return a.id - b.id;
+        });
+        return result;
+    }
+    /**
+     * Render observations as compact XML for system prompt injection.
+     */
+    renderPromptContext(observations, config) {
+        if (observations.length === 0) {
+            return { xml: '', observationCount: 0, tokenCount: 0, budgetExceeded: false };
+        }
+        const parts = ['<memento_context>'];
+        let totalChars = 0;
+        const maxChars = config.maxTokens * 4;
+        let budgetExceeded = false;
+        for (const obs of observations) {
+            const xmlNode = this.renderObservationXml(obs);
+            const nodeChars = xmlNode.length;
+            if (totalChars + nodeChars > maxChars && parts.length > 1) {
+                budgetExceeded = true;
+                break;
+            }
+            parts.push(xmlNode);
+            totalChars += nodeChars;
+        }
+        parts.push('</memento_context>');
+        const xml = parts.join('\n');
+        return {
+            xml,
+            observationCount: parts.length - 2, // subtract opening and closing tags
+            tokenCount: Math.ceil(xml.length / 4),
+            budgetExceeded,
+        };
+    }
+    renderObservationXml(obs) {
+        const pinnedAttr = obs.pinned ? ' pinned="true"' : '';
+        const projectAttr = obs.projectId ? ` project="${obs.projectId}"` : '';
+        // Compact: title as attribute, content as text (trimmed to first 500 chars for budget)
+        const truncatedContent = obs.content.length > 500
+            ? obs.content.slice(0, 500) + '...'
+            : obs.content;
+        return `<observation id="${obs.id}" type="${obs.type}"${projectAttr}${pinnedAttr}>\n${obs.title}\n${truncatedContent}\n</observation>`;
+    }
+    estimateObservationChars(obs) {
+        // Estimate XML overhead: ~100 chars for tags + attributes
+        // Plus title + first 500 chars of content
+        const contentLen = Math.min(obs.content.length, 500);
+        return 100 + obs.title.length + contentLen;
+    }
+    /**
+     * Pin an observation (always include in prompt injection).
+     */
+    async pinObservation(id) {
+        return this.updateObservation(id, { pinned: true });
+    }
+    /**
+     * Unpin an observation.
+     */
+    async unpinObservation(id) {
+        return this.updateObservation(id, { pinned: false });
+    }
+    /**
+     * Lock an observation (set read-only). Prevents all modifications.
+     */
+    async lockObservation(id) {
+        return this.updateObservation(id, { readOnly: true });
+    }
+    /**
+     * Unlock an observation (remove read-only protection).
+     */
+    async unlockObservation(id) {
+        return this.updateObservation(id, { readOnly: false });
+    }
+    // ─── 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);
+        const observation = this.mapObservation(row);
+        // Calculate duplicatesCount when topicKey is present
+        if (observation.topicKey) {
+            const dupResult = this.db
+                .prepare('SELECT COUNT(*) as count FROM observations WHERE topic_key = ? AND deleted_at IS NULL')
+                .get(observation.topicKey);
+            observation.duplicatesCount = dupResult?.count ?? 0;
+        }
+        return observation;
     }
     async getSessionById(id) {
         const row = this.db.prepare('SELECT * FROM sessions WHERE id = ?').get(id);
@@ -339,7 +1440,12 @@ 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),
+            scope: r.scope || 'project',
+            pinned: Boolean(r.pinned),
+            readOnly: Boolean(r.read_only),
+            revisionCount: r.revision_count ?? 0,
         };
     }
     mapSession(row) {
@@ -351,6 +1457,7 @@ class MemoryEngine {
             startedAt: new Date(r.started_at),
             endedAt: r.ended_at ? new Date(r.ended_at) : null,
             metadata: this.deserialize(r.metadata),
+            observationCount: r.observation_count ?? 0,
         };
     }
     mapPrompt(row) {
@@ -365,6 +1472,1114 @@ class MemoryEngine {
             metadata: this.deserialize(r.metadata),
         };
     }
+    // ─── Timeline & Context ──────────────────────────────────────
+    async getTimeline(params) {
+        this.checkHealth();
+        const { projectId, scope, limit = 50, offset = 0 } = params;
+        let countSql = 'SELECT COUNT(*) as count FROM observations WHERE deleted_at IS NULL';
+        let sql = 'SELECT * FROM observations WHERE deleted_at IS NULL';
+        const values = [];
+        if (projectId) {
+            countSql += ' AND project_id = ?';
+            sql += ' AND project_id = ?';
+            values.push(projectId);
+        }
+        if (scope) {
+            countSql += ' AND scope = ?';
+            sql += ' AND scope = ?';
+            values.push(scope);
+        }
+        const countResult = this.db.prepare(countSql).get(...values);
+        const total = countResult?.count ?? 0;
+        sql += ' ORDER BY created_at DESC, id DESC LIMIT ? OFFSET ?';
+        const rows = this.db.prepare(sql).all(...values, limit, offset);
+        const observations = rows.map((row) => this.mapObservation(row));
+        return { observations, total };
+    }
+    async getRecentContext(params) {
+        this.checkHealth();
+        const { projectId, limit = 20, scope } = params;
+        let sql = 'SELECT * FROM observations WHERE deleted_at IS NULL';
+        const values = [];
+        if (projectId) {
+            sql += ' AND project_id = ?';
+            values.push(projectId);
+        }
+        if (scope) {
+            sql += ' AND scope = ?';
+            values.push(scope);
+        }
+        sql += ' ORDER BY created_at DESC, id DESC LIMIT ?';
+        const rows = this.db.prepare(sql).all(...values, limit);
+        const observations = rows.map((row) => this.mapObservation(row));
+        // Get total for context
+        let countSql = 'SELECT COUNT(*) as count FROM observations WHERE deleted_at IS NULL';
+        const countValues = [];
+        if (projectId) {
+            countSql += ' AND project_id = ?';
+            countValues.push(projectId);
+        }
+        const countResult = this.db.prepare(countSql).get(...countValues);
+        const total = countResult?.count ?? 0;
+        return { observations, total };
+    }
+    // ─── TUI Explorer API ──────────────────────────────────────
+    async listSessions(params) {
+        this.checkHealth();
+        const { projectId, activeOnly = false, limit = 50, offset = 0 } = params;
+        // Build WHERE conditions once, reuse for count and fetch
+        let whereClause = ' WHERE 1=1';
+        const values = [];
+        if (projectId) {
+            whereClause += ' AND project_id = ?';
+            values.push(projectId);
+        }
+        if (activeOnly) {
+            whereClause += ' AND ended_at IS NULL';
+        }
+        // Count (no subquery needed)
+        const countResult = this.db.prepare(`SELECT COUNT(*) as count FROM sessions${whereClause}`).get(...values);
+        const total = countResult?.count ?? 0;
+        // Fetch with observation count subquery
+        const sql = `SELECT s.*,
+      (SELECT COUNT(*) FROM observations o WHERE o.session_id = s.id AND o.deleted_at IS NULL) as observation_count
+      FROM sessions s${whereClause}
+      ORDER BY s.started_at DESC, s.id DESC LIMIT ? OFFSET ?`;
+        values.push(limit, offset);
+        const rows = this.db.prepare(sql).all(...values);
+        const sessions = rows.map((row) => this.mapSession(row));
+        return { sessions, total };
+    }
+    async listProjects() {
+        this.checkHealth();
+        // Get all distinct project_ids with their stats
+        const rows = this.db
+            .prepare(`
+      SELECT
+        project_id,
+        SUM(CASE WHEN deleted_at IS NULL THEN 1 ELSE 0 END) as active_count,
+        SUM(CASE WHEN deleted_at IS NOT NULL THEN 1 ELSE 0 END) as deleted_count,
+        MAX(created_at) as last_activity,
+        MAX(id) as max_id
+      FROM observations
+      GROUP BY project_id
+      ORDER BY last_activity DESC, max_id DESC
+    `)
+            .all();
+        const projects = rows.map((row) => {
+            const projectId = row.project_id;
+            // Get type distribution for this project
+            const typeRows = this.db
+                .prepare(`
+        SELECT type, COUNT(*) as count
+        FROM observations
+        WHERE project_id = ?
+        GROUP BY type
+      `)
+                .all(projectId);
+            const byType = {
+                decision: 0,
+                bug: 0,
+                discovery: 0,
+                note: 0,
+                summary: 0,
+                learning: 0,
+                pattern: 0,
+                architecture: 0,
+                config: 0,
+                preference: 0,
+            };
+            for (const tr of typeRows) {
+                byType[tr.type] = tr.count;
+            }
+            return {
+                name: projectId,
+                activeCount: row.active_count,
+                deletedCount: row.deleted_count,
+                lastActivity: row.last_activity ? new Date(row.last_activity) : null,
+                byType,
+            };
+        });
+        return projects;
+    }
+    // ─── Project Registry (Issue #177) ────────────────────────
+    /**
+     * Register a project in the projects table.
+     * Uses INSERT OR IGNORE to be idempotent.
+     * Returns the registered project name (normalized).
+     */
+    registerProject(name, workingDir) {
+        this.checkHealth();
+        const { normalizeProjectId } = require('./ConfigManager');
+        const normalizedName = normalizeProjectId(name);
+        const now = Date.now();
+        this.db
+            .prepare(`INSERT OR IGNORE INTO projects (name, created_at, metadata, working_dir, aliases) VALUES (?, ?, ?, ?, ?)`)
+            .run(normalizedName, now, '{}', workingDir || null, '[]');
+        return normalizedName;
+    }
+    /**
+     * Get all registered project names from the projects table.
+     */
+    listRegisteredProjects() {
+        this.checkHealth();
+        const rows = this.db
+            .prepare('SELECT name, working_dir, aliases FROM projects ORDER BY name')
+            .all();
+        return rows.map((row) => ({
+            name: row.name,
+            workingDir: row.working_dir,
+            aliases: row.aliases ? JSON.parse(row.aliases) : [],
+        }));
+    }
+    /**
+     * Merge all observations and sessions from sourceProject into targetProject.
+     * Also updates FTS index. Returns count of affected records.
+     *
+     * Tries both the raw source name and the normalized version to handle
+     * un-normalized data in the database.
+     */
+    mergeProject(sourceProjectId, targetProjectId) {
+        this.checkHealth();
+        const { normalizeProjectId } = require('./ConfigManager');
+        const normalizedSource = normalizeProjectId(sourceProjectId);
+        const target = normalizeProjectId(targetProjectId);
+        // Check same-name BEFORE searching for data
+        if (normalizedSource === target) {
+            throw new Error(`Source and target are the same after normalization: "${normalizedSource}"`);
+        }
+        // Resolve source: try raw name first, then normalized
+        const candidates = [sourceProjectId, normalizedSource];
+        let source = null;
+        for (const candidate of candidates) {
+            if (candidate === target)
+                continue; // skip if same as target
+            const count = this.db
+                .prepare('SELECT COUNT(*) as count FROM observations WHERE project_id = ?')
+                .get(candidate);
+            if (count.count > 0) {
+                source = candidate;
+                break;
+            }
+            // Also check sessions and journal
+            const sessionCount = this.db
+                .prepare('SELECT COUNT(*) as count FROM sessions WHERE project_id = ?')
+                .get(candidate);
+            const journalCount = this.db
+                .prepare('SELECT COUNT(*) as count FROM journal WHERE project_id = ?')
+                .get(candidate);
+            if (sessionCount.count > 0 || journalCount.count > 0) {
+                source = candidate;
+                break;
+            }
+        }
+        if (!source) {
+            throw new Error(`No data found for source project: "${sourceProjectId}" (also tried "${normalizedSource}")`);
+        }
+        // Move observations
+        const obsResult = this.db
+            .prepare('UPDATE observations SET project_id = ? WHERE project_id = ?')
+            .run(target, source);
+        // Move sessions
+        const sessionResult = this.db
+            .prepare('UPDATE sessions SET project_id = ? WHERE project_id = ?')
+            .run(target, source);
+        // Move journal entries
+        const journalResult = this.db
+            .prepare('UPDATE journal SET project_id = ? WHERE project_id = ?')
+            .run(target, source);
+        // Move prompts
+        const promptsResult = this.db
+            .prepare('UPDATE prompts SET project_id = ? WHERE project_id = ?')
+            .run(target, source);
+        // Re-index FTS for moved observations (delete old + insert new)
+        this.db.prepare('DELETE FROM observations_fts WHERE project_id = ?').run(source);
+        const movedObs = this.db
+            .prepare('SELECT id, title, content, topic_key, project_id FROM observations WHERE project_id = ?')
+            .all(target);
+        for (const obs of movedObs) {
+            this.db
+                .prepare('INSERT OR REPLACE INTO observations_fts(rowid, title, content, topic_key, project_id) VALUES (?, ?, ?, ?, ?)')
+                .run(obs.id, obs.title, obs.content, obs.topic_key ?? '', obs.project_id);
+        }
+        // Add source as alias of target in projects table
+        try {
+            const existing = this.db
+                .prepare('SELECT aliases FROM projects WHERE name = ?')
+                .get(target);
+            if (existing) {
+                const aliases = existing.aliases ? JSON.parse(existing.aliases) : [];
+                if (!aliases.includes(source)) {
+                    aliases.push(source);
+                    this.db.prepare('UPDATE projects SET aliases = ? WHERE name = ?').run(JSON.stringify(aliases), target);
+                }
+            }
+        }
+        catch {
+            // Non-critical — alias tracking is best-effort
+        }
+        return {
+            observationsMoved: obsResult.changes,
+            sessionsMoved: sessionResult.changes,
+            journalMoved: journalResult.changes,
+            promptsMoved: promptsResult.changes,
+        };
+    }
+    /**
+     * Normalize all project_id values in the database.
+     * After normalization, merges projects that became identical.
+     * Returns details of what was changed.
+     */
+    normalizeAllProjectIds() {
+        this.checkHealth();
+        const { normalizeProjectId } = require('./ConfigManager');
+        // Get all distinct project_ids
+        const obsProjects = this.db
+            .prepare('SELECT DISTINCT project_id FROM observations')
+            .all();
+        const sessionProjects = this.db
+            .prepare('SELECT DISTINCT project_id FROM sessions')
+            .all();
+        const allProjects = new Set([
+            ...obsProjects.map((r) => r.project_id),
+            ...sessionProjects.map((r) => r.project_id),
+        ]);
+        // Build normalization map: original → normalized
+        const normalizationMap = new Map();
+        for (const original of allProjects) {
+            const normalized = normalizeProjectId(original);
+            if (normalized !== original) {
+                normalizationMap.set(original, normalized);
+            }
+        }
+        // Apply normalizations
+        let normalizedCount = 0;
+        for (const [original, normalized] of normalizationMap) {
+            // Update observations
+            const obsResult = this.db
+                .prepare('UPDATE observations SET project_id = ? WHERE project_id = ?')
+                .run(normalized, original);
+            normalizedCount += obsResult.changes;
+            // Update sessions
+            const sessionResult = this.db
+                .prepare('UPDATE sessions SET project_id = ? WHERE project_id = ?')
+                .run(normalized, original);
+            normalizedCount += sessionResult.changes;
+            // Update journal
+            const journalResult = this.db
+                .prepare('UPDATE journal SET project_id = ? WHERE project_id = ?')
+                .run(normalized, original);
+            normalizedCount += journalResult.changes;
+            // Update prompts
+            const promptsResult = this.db
+                .prepare('UPDATE prompts SET project_id = ? WHERE project_id = ?')
+                .run(normalized, original);
+            normalizedCount += promptsResult.changes;
+        }
+        // After normalization, find duplicates (same normalized name) and merge
+        const currentProjects = this.db
+            .prepare('SELECT DISTINCT project_id FROM observations')
+            .all();
+        // Group by normalized name to find duplicates — but since we already normalized,
+        // just check for remaining duplicates (shouldn't be any after normalization above)
+        // The main purpose of mergeProject is for MANUAL consolidation of differently-named projects
+        // that happen to represent the same real-world project
+        // Re-index FTS completely for affected projects
+        if (normalizedCount > 0) {
+            // Delete and rebuild FTS for all changed projects
+            for (const normalized of new Set(normalizationMap.values())) {
+                this.db.prepare('DELETE FROM observations_fts WHERE project_id = ?').run(normalized);
+                const obs = this.db
+                    .prepare('SELECT id, title, content, topic_key, project_id FROM observations WHERE project_id = ?')
+                    .all(normalized);
+                for (const o of obs) {
+                    this.db
+                        .prepare('INSERT OR REPLACE INTO observations_fts(rowid, title, content, topic_key, project_id) VALUES (?, ?, ?, ?, ?)')
+                        .run(o.id, o.title, o.content, o.topic_key ?? '', o.project_id);
+                }
+            }
+        }
+        return {
+            normalized: normalizedCount,
+            merged: [],
+        };
+    }
+    async getDashboardStats() {
+        this.checkHealth();
+        // Total counts
+        const countRow = this.db
+            .prepare(`
+      SELECT
+        COUNT(*) as total,
+        SUM(CASE WHEN deleted_at IS NULL THEN 1 ELSE 0 END) as active,
+        SUM(CASE WHEN deleted_at IS NOT NULL THEN 1 ELSE 0 END) as deleted
+      FROM observations
+    `)
+            .get();
+        // By type
+        const typeRows = this.db
+            .prepare(`
+      SELECT type, COUNT(*) as count
+      FROM observations
+      WHERE deleted_at IS NULL
+      GROUP BY type
+    `)
+            .all();
+        const byType = { decision: 0, bug: 0, discovery: 0, note: 0, summary: 0, learning: 0, pattern: 0, architecture: 0, config: 0, preference: 0 };
+        for (const tr of typeRows) {
+            byType[tr.type] = tr.count;
+        }
+        // By project (active only)
+        const projectRows = this.db
+            .prepare(`
+      SELECT project_id, COUNT(*) as count
+      FROM observations
+      WHERE deleted_at IS NULL
+      GROUP BY project_id
+      ORDER BY count DESC
+    `)
+            .all();
+        const byProject = {};
+        for (const pr of projectRows) {
+            byProject[pr.project_id] = pr.count;
+        }
+        // Active sessions
+        const sessionRow = this.db
+            .prepare('SELECT COUNT(*) as count FROM sessions WHERE ended_at IS NULL')
+            .get();
+        // Recent 5 observations (active only)
+        const recentRows = this.db
+            .prepare(`
+      SELECT * FROM observations
+      WHERE deleted_at IS NULL
+      ORDER BY created_at DESC, id DESC
+      LIMIT 5
+    `)
+            .all();
+        const recentObservations = recentRows.map((row) => this.mapObservation(row));
+        return {
+            totalObservations: countRow.total ?? 0,
+            activeObservations: countRow.active ?? 0,
+            deletedObservations: countRow.deleted ?? 0,
+            byType,
+            byProject,
+            activeSessions: sessionRow.count,
+            recentObservations,
+        };
+    }
+    // ─── Import/Export ──────────────────────────────────────────
+    async exportToJson(options) {
+        this.checkHealth();
+        const { projectId, includeSessions = false } = options || {};
+        const searchResult = await this.search({ projectId, limit: 100000 });
+        const observations = searchResult.observations.map((obs) => ({
+            uuid: obs.uuid,
+            title: obs.title,
+            content: obs.content,
+            type: obs.type,
+            topicKey: obs.topicKey,
+            projectId: obs.projectId,
+            metadata: obs.metadata,
+            createdAt: obs.createdAt.toISOString(),
+        }));
+        let sessions;
+        if (includeSessions) {
+            const sessionIds = [...new Set(searchResult.observations.map((o) => o.sessionId))];
+            const sessionResults = await Promise.all(sessionIds.map((id) => this.getSession(id)));
+            sessions = sessionResults
+                .filter((s) => s !== null)
+                .map((s) => ({
+                uuid: s.uuid,
+                projectId: s.projectId,
+                startedAt: s.startedAt.toISOString(),
+                endedAt: s.endedAt?.toISOString() || null,
+                metadata: s.metadata,
+            }));
+        }
+        return {
+            version: '1.0',
+            exportedAt: new Date().toISOString(),
+            project: projectId,
+            observations,
+            ...(includeSessions && sessions && { sessions }),
+        };
+    }
+    async importFromJson(data, options) {
+        this.checkHealth();
+        const { conflictStrategy = 'skip', dryRun = false, projectId } = options || {};
+        // Validate schema
+        if (!data.version || !Array.isArray(data.observations)) {
+            throw new Error('Invalid import data: missing version or observations array');
+        }
+        const validTypes = ['decision', 'bug', 'discovery', 'note', 'summary', 'learning', 'pattern', 'architecture', 'config', 'preference'];
+        const targetProject = projectId || data.project || 'import';
+        const result = {
+            imported: 0,
+            skipped: 0,
+            overwritten: 0,
+            failed: 0,
+            errors: [],
+            observations: [],
+        };
+        if (data.observations.length === 0) {
+            return result;
+        }
+        // Create import session
+        const session = await this.createSession({
+            projectId: targetProject,
+            endedAt: null,
+            metadata: { type: 'import', source: 'mem_import', timestamp: new Date().toISOString() },
+        });
+        // Use db.transaction() for safe atomic import (#70)
+        // Replaces manual BEGIN/COMMIT which was fragile — if createObservation's
+        // withRetry() hit SQLITE_BUSY inside a manual transaction, the retry would
+        // fail because the transaction was already in error state.
+        const doImport = this.db.transaction(() => {
+            for (const obs of data.observations) {
+                // Validate required fields
+                if (!obs.title || !obs.content || !obs.type) {
+                    result.errors.push(`Invalid observation: missing required fields (title, content, type)`);
+                    if (conflictStrategy === 'fail') {
+                        result.failed++;
+                        throw new Error('IMPORT_ABORT');
+                    }
+                    result.failed++;
+                    continue;
+                }
+                // Validate type
+                if (!validTypes.includes(obs.type)) {
+                    result.errors.push(`Invalid type: "${obs.type}". Valid types: ${validTypes.join(', ')}`);
+                    if (conflictStrategy === 'fail') {
+                        result.failed++;
+                        throw new Error('IMPORT_ABORT');
+                    }
+                    result.failed++;
+                    continue;
+                }
+                // Check for duplicates by uuid
+                if (obs.uuid) {
+                    const existing = this.findObservationByUuid(obs.uuid);
+                    if (existing) {
+                        if (conflictStrategy === 'skip') {
+                            result.skipped++;
+                            continue;
+                        }
+                        if (conflictStrategy === 'overwrite') {
+                            if (!dryRun) {
+                                // Direct UPDATE + FTS5 sync (avoids withRetry inside transaction)
+                                const fields = [];
+                                const values = [];
+                                if (obs.title !== undefined) {
+                                    fields.push('title = ?');
+                                    values.push(obs.title);
+                                }
+                                if (obs.content !== undefined) {
+                                    fields.push('content = ?');
+                                    values.push(obs.content);
+                                }
+                                if (obs.type !== undefined) {
+                                    fields.push('type = ?');
+                                    values.push(obs.type);
+                                }
+                                if (obs.topicKey !== undefined) {
+                                    fields.push('topic_key = ?');
+                                    values.push(obs.topicKey ?? null);
+                                }
+                                if (obs.metadata !== undefined) {
+                                    fields.push('metadata = ?');
+                                    values.push(this.serialize(obs.metadata || {}));
+                                }
+                                fields.push('revision_count = revision_count + 1');
+                                values.push(existing.id);
+                                this.db.prepare(`UPDATE observations SET ${fields.join(', ')} WHERE id = ?`).run(...values);
+                                // FTS5 sync — delete + re-insert
+                                this.db.prepare('DELETE FROM observations_fts WHERE rowid = ?').run(existing.id);
+                                const row = this.db
+                                    .prepare('SELECT title, content, topic_key, project_id FROM observations WHERE id = ?')
+                                    .get(existing.id);
+                                if (row) {
+                                    this.db.prepare('INSERT INTO observations_fts(rowid, title, content, topic_key, project_id) VALUES (?, ?, ?, ?, ?)').run(existing.id, row.title, row.content, row.topic_key, row.project_id);
+                                }
+                            }
+                            result.overwritten++;
+                            continue;
+                        }
+                        if (conflictStrategy === 'fail') {
+                            result.errors.push(`Duplicate uuid: ${obs.uuid}`);
+                            result.failed++;
+                            throw new Error('IMPORT_ABORT');
+                        }
+                    }
+                }
+                if (!dryRun) {
+                    // Direct INSERT + FTS5 sync (avoids withRetry inside transaction)
+                    const uuid = obs.uuid || crypto.randomUUID();
+                    const metadata = this.serialize(obs.metadata || {});
+                    const createdAt = Date.now();
+                    const insertResult = this.db.prepare(`INSERT INTO observations (uuid, session_id, title, content, type, topic_key, project_id, created_at, deleted_at, metadata, scope) VALUES (?, ?, ?, ?, ?, ?, ?, ?, NULL, ?, 'project')`).run(uuid, session.id, obs.title, obs.content, obs.type, obs.topicKey ?? null, targetProject, createdAt, metadata);
+                    const insertId = typeof insertResult.lastInsertRowid === 'bigint'
+                        ? Number(insertResult.lastInsertRowid)
+                        : insertResult.lastInsertRowid;
+                    // FTS5 sync
+                    this.db.prepare('INSERT INTO observations_fts(rowid, title, content, topic_key, project_id) VALUES (?, ?, ?, ?, ?)').run(insertId, obs.title, obs.content, obs.topicKey ?? '', targetProject);
+                    // Fetch created observation for result
+                    const importedRow = this.db.prepare('SELECT * FROM observations WHERE id = ?').get(insertId);
+                    if (importedRow) {
+                        result.observations.push(this.mapObservation(importedRow));
+                    }
+                }
+                result.imported++;
+            }
+        });
+        try {
+            doImport();
+        }
+        catch (error) {
+            if (error instanceof Error && error.message === 'IMPORT_ABORT') {
+                // Transaction auto-rolled back; return partial result with errors
+                return result;
+            }
+            throw error;
+        }
+        return result;
+    }
+    findObservationByUuid(uuid) {
+        const row = this.db.prepare('SELECT * FROM observations WHERE uuid = ?').get(uuid);
+        if (!row)
+            return null;
+        return this.mapObservation(row);
+    }
+    async resetFull() {
+        this.checkHealth();
+        // Count before reset
+        const countResult = this.db.prepare('SELECT COUNT(*) as count FROM observations').get();
+        const deleted = countResult?.count || 0;
+        // Drop everything (no observation triggers — FTS5 sync is application-level)
+        this.db.exec('DROP TABLE IF EXISTS observations_fts');
+        this.db.exec('DROP TRIGGER IF EXISTS journal_ai');
+        this.db.exec('DROP TABLE IF EXISTS journal_fts');
+        this.db.exec('DROP TABLE IF EXISTS journal_tags');
+        this.db.exec('DROP TABLE IF EXISTS journal');
+        this.db.exec('DROP TABLE IF EXISTS observations');
+        this.db.exec('DROP TABLE IF EXISTS prompts');
+        this.db.exec('DROP TABLE IF EXISTS sessions');
+        this.db.exec('DROP TABLE IF EXISTS projects');
+        // Recreate schema
+        this.initializeDatabase();
+        return { deleted };
+    }
+    async resetProject(projectId) {
+        this.checkHealth();
+        // Count observations to delete
+        const obsCount = this.db
+            .prepare('SELECT COUNT(*) as count FROM observations WHERE project_id = ?')
+            .get(projectId);
+        const promptCount = this.db
+            .prepare('SELECT COUNT(*) as count FROM prompts WHERE project_id = ?')
+            .get(projectId);
+        const deleted = obsCount.count + promptCount.count;
+        // Delete observations (FTS5 first, then main table) and prompts for this project
+        // Application-level FTS5 sync (was trigger observations_ad)
+        this.db.prepare('DELETE FROM observations_fts WHERE rowid IN (SELECT id FROM observations WHERE project_id = ?)').run(projectId);
+        this.db.prepare('DELETE FROM observations WHERE project_id = ?').run(projectId);
+        this.db.prepare('DELETE FROM prompts WHERE project_id = ?').run(projectId);
+        // Clean up orphan sessions (no observations AND no prompts)
+        const orphanResult = this.db.prepare(`
+      DELETE FROM sessions WHERE id NOT IN (
+        SELECT DISTINCT session_id FROM observations
+        UNION
+        SELECT DISTINCT session_id FROM prompts
+      )
+    `).run();
+        const orphanSessions = typeof orphanResult.changes === 'bigint'
+            ? Number(orphanResult.changes)
+            : orphanResult.changes;
+        return { deleted, orphanSessions };
+    }
+    async countByProject(projectId) {
+        this.checkHealth();
+        const obsCount = this.db
+            .prepare('SELECT COUNT(*) as count FROM observations WHERE project_id = ?')
+            .get(projectId);
+        const promptCount = this.db
+            .prepare('SELECT COUNT(*) as count FROM prompts WHERE project_id = ?')
+            .get(projectId);
+        const sessionCount = this.db
+            .prepare('SELECT COUNT(DISTINCT session_id) as count FROM observations WHERE project_id = ?')
+            .get(projectId);
+        return {
+            observations: obsCount.count,
+            prompts: promptCount.count,
+            sessions: sessionCount.count,
+        };
+    }
+    // ─── Journal (append-only evidence) ──────────────────────────
+    async writeJournal(data) {
+        this.checkHealth();
+        const uuid = crypto.randomUUID();
+        const createdAt = Date.now();
+        const metadata = this.serialize(data.metadata || {});
+        // If supersedes is set, validate and invalidate the old entry
+        if (data.supersedes) {
+            const existing = await this.readJournal(data.supersedes);
+            if (!existing)
+                throw new Error(`Journal entry ${data.supersedes} not found`);
+            if (existing.invalidatedAt)
+                throw new Error(`Journal entry ${data.supersedes} is already invalidated`);
+        }
+        const id = await this.withRetry(() => {
+            const result = this.db
+                .prepare(`INSERT INTO journal (uuid, project_id, session_id, title, body, model, provider, agent, superseded_by, invalidated_at, metadata, created_at)
+           VALUES (?, ?, ?, ?, ?, ?, ?, ?, NULL, NULL, ?, ?)`)
+                .run(uuid, data.projectId, data.sessionId ?? null, data.title, data.body, data.model ?? null, data.provider ?? null, data.agent ?? null, metadata, createdAt);
+            return typeof result.lastInsertRowid === 'bigint'
+                ? Number(result.lastInsertRowid)
+                : result.lastInsertRowid;
+        });
+        // Insert tags
+        if (data.tags && data.tags.length > 0) {
+            const insertTag = this.db.prepare('INSERT OR IGNORE INTO journal_tags (journal_id, tag) VALUES (?, ?)');
+            for (const tag of data.tags) {
+                insertTag.run(id, tag);
+            }
+        }
+        // If supersedes, mark the old entry
+        if (data.supersedes) {
+            await this.withRetry(() => this.db
+                .prepare('UPDATE journal SET superseded_by = ?, invalidated_at = ? WHERE id = ?')
+                .run(id, createdAt, data.supersedes));
+        }
+        const entry = await this.readJournal(id);
+        if (!entry)
+            throw new Error('Failed to retrieve created journal entry');
+        return entry;
+    }
+    async readJournal(id) {
+        this.checkHealth();
+        const row = this.db.prepare('SELECT * FROM journal WHERE id = ?').get(id);
+        if (!row)
+            return null;
+        // Fetch tags
+        const tagRows = this.db
+            .prepare('SELECT tag FROM journal_tags WHERE journal_id = ?')
+            .all(id);
+        const tags = tagRows.map((t) => t.tag);
+        return this.mapJournalEntry(row, tags);
+    }
+    async searchJournal(params) {
+        this.checkHealth();
+        const { query, tags, projectId, sessionId, dateFrom, dateTo, activeOnly = false, limit = 50, offset = 0, } = params;
+        let sql;
+        const values = [];
+        const sanitizedQuery = query ? this.sanitizeFTS5Query(query) : '';
+        if (sanitizedQuery) {
+            // FTS5 search — qualify column names to avoid ambiguity with journal_fts
+            sql =
+                'SELECT journal.* FROM journal JOIN journal_fts ON journal.id = journal_fts.rowid WHERE journal_fts MATCH ?';
+            values.push(sanitizedQuery);
+        }
+        else {
+            sql = 'SELECT * FROM journal WHERE 1=1';
+        }
+        if (activeOnly) {
+            sql += ' AND journal.invalidated_at IS NULL';
+        }
+        if (projectId) {
+            sql += ' AND journal.project_id = ?';
+            values.push(projectId);
+        }
+        if (sessionId) {
+            sql += ' AND journal.session_id = ?';
+            values.push(sessionId);
+        }
+        if (dateFrom) {
+            sql += ' AND journal.created_at >= ?';
+            values.push(dateFrom.getTime());
+        }
+        if (dateTo) {
+            sql += ' AND journal.created_at <= ?';
+            values.push(dateTo.getTime());
+        }
+        // Tag filtering — if tags specified, intersect with journal_tags
+        if (tags && tags.length > 0) {
+            // Find journal entries that have ALL specified tags
+            const tagPlaceholders = tags.map(() => '?').join(',');
+            const tagSubquery = `
+        AND journal.id IN (
+          SELECT jt.journal_id FROM journal_tags jt
+          WHERE jt.tag IN (${tagPlaceholders})
+          GROUP BY jt.journal_id
+          HAVING COUNT(DISTINCT jt.tag) = ${tags.length}
+        )
+      `;
+            sql += tagSubquery;
+            values.push(...tags);
+        }
+        // Count
+        const countSql = sql.replace(/SELECT.*?FROM/, 'SELECT COUNT(*) as count FROM');
+        const countResult = this.db.prepare(countSql).get(...values);
+        const total = countResult?.count ?? 0;
+        // Fetch
+        sql += ' ORDER BY journal.created_at DESC, journal.id DESC LIMIT ? OFFSET ?';
+        values.push(limit, offset);
+        const rows = this.db.prepare(sql).all(...values);
+        // Fetch tags for each entry
+        const entries = [];
+        for (const row of rows) {
+            const entryId = row.id;
+            const tagRows = this.db
+                .prepare('SELECT tag FROM journal_tags WHERE journal_id = ?')
+                .all(entryId);
+            entries.push(this.mapJournalEntry(row, tagRows.map((t) => t.tag)));
+        }
+        return { entries, total };
+    }
+    async invalidateJournal(id, supersededById) {
+        this.checkHealth();
+        const entry = await this.readJournal(id);
+        if (!entry)
+            throw new Error(`Journal entry ${id} not found`);
+        if (entry.invalidatedAt)
+            throw new Error(`Journal entry ${id} is already invalidated`);
+        // Validate the superseding entry exists
+        const superseding = await this.readJournal(supersededById);
+        if (!superseding)
+            throw new Error(`Superseding journal entry ${supersededById} not found`);
+        const now = Date.now();
+        await this.withRetry(() => this.db
+            .prepare('UPDATE journal SET superseded_by = ?, invalidated_at = ? WHERE id = ?')
+            .run(supersededById, now, id));
+    }
+    mapJournalEntry(row, tags) {
+        const r = row;
+        return {
+            id: r.id,
+            uuid: r.uuid,
+            projectId: r.project_id,
+            sessionId: r.session_id,
+            title: r.title,
+            body: r.body,
+            tags,
+            model: r.model,
+            provider: r.provider,
+            agent: r.agent,
+            supersededBy: r.superseded_by,
+            invalidatedAt: r.invalidated_at ? new Date(r.invalidated_at) : null,
+            metadata: this.deserialize(r.metadata),
+            createdAt: new Date(r.created_at),
+        };
+    }
+    // ─── Full Export/Import (v2.0) ────────────────────────────────
+    async listPrompts(params) {
+        this.checkHealth();
+        const { projectId, sessionId, limit = 50, offset = 0 } = params || {};
+        let whereClause = ' WHERE 1=1';
+        const values = [];
+        if (projectId) {
+            whereClause += ' AND project_id = ?';
+            values.push(projectId);
+        }
+        if (sessionId) {
+            whereClause += ' AND session_id = ?';
+            values.push(sessionId);
+        }
+        const countResult = this.db.prepare(`SELECT COUNT(*) as count FROM prompts${whereClause}`).get(...values);
+        const total = countResult?.count ?? 0;
+        const rows = this.db.prepare(`SELECT * FROM prompts${whereClause} ORDER BY created_at ASC LIMIT ? OFFSET ?`).all(...values, limit, offset);
+        const prompts = rows.map((row) => this.mapPrompt(row));
+        return { prompts, total };
+    }
+    async exportProject(projectId) {
+        this.checkHealth();
+        // Fetch all data in parallel using Promise.all
+        const [observationsResult, sessionsResult, journalResult, promptsResult,] = await Promise.all([
+            this.search({ projectId, limit: 100000, includeDeleted: true }),
+            this.listSessions({ projectId, limit: 100000 }),
+            this.searchJournal({ projectId, limit: 100000 }),
+            this.listPrompts({ projectId, limit: 100000 }),
+        ]);
+        // Fetch project data
+        const projectRow = this.db
+            .prepare('SELECT * FROM projects WHERE name = ?')
+            .get(projectId);
+        const projects = projectRow
+            ? [{
+                    name: projectRow.name,
+                    createdAt: new Date(projectRow.created_at).toISOString(),
+                    metadata: this.deserialize(projectRow.metadata),
+                }]
+            : [{
+                    name: projectId,
+                    createdAt: new Date().toISOString(),
+                    metadata: {},
+                }];
+        const sessions = sessionsResult.sessions.map((s) => ({
+            uuid: s.uuid,
+            projectId: s.projectId,
+            startedAt: s.startedAt.toISOString(),
+            endedAt: s.endedAt ? s.endedAt.toISOString() : null,
+            metadata: s.metadata,
+        }));
+        const observations = observationsResult.observations.map((o) => ({
+            uuid: o.uuid,
+            title: o.title,
+            content: o.content,
+            type: o.type,
+            topicKey: o.topicKey,
+            projectId: o.projectId,
+            scope: o.scope,
+            pinned: o.pinned,
+            readOnly: o.readOnly,
+            revisionCount: o.revisionCount,
+            createdAt: o.createdAt.toISOString(),
+            deletedAt: o.deletedAt ? o.deletedAt.toISOString() : null,
+            metadata: o.metadata,
+        }));
+        const prompts = promptsResult.prompts.map((p) => ({
+            uuid: p.uuid,
+            content: p.content,
+            projectId: p.projectId,
+            createdAt: p.createdAt.toISOString(),
+            metadata: p.metadata,
+        }));
+        const journal = journalResult.entries.map((j) => ({
+            uuid: j.uuid,
+            title: j.title,
+            body: j.body,
+            tags: j.tags,
+            projectId: j.projectId,
+            model: j.model,
+            provider: j.provider,
+            agent: j.agent,
+            supersededByUuid: null, // Resolved below
+            invalidatedAt: j.invalidatedAt ? j.invalidatedAt.toISOString() : null,
+            metadata: j.metadata,
+            createdAt: j.createdAt.toISOString(),
+        }));
+        // Resolve journal supersedes references from ID to UUID
+        const journalIdToUuid = new Map();
+        for (const entry of journalResult.entries) {
+            journalIdToUuid.set(entry.id, entry.uuid);
+        }
+        for (let i = 0; i < journal.length; i++) {
+            const supersededById = journalResult.entries[i].supersededBy;
+            if (supersededById !== null) {
+                journal[i].supersededByUuid = journalIdToUuid.get(supersededById) ?? null;
+            }
+        }
+        return {
+            version: '2.0',
+            exportedAt: new Date().toISOString(),
+            source: {
+                project: projectId,
+                allProjects: false,
+            },
+            stats: {
+                totalProjects: projects.length,
+                totalSessions: sessions.length,
+                totalObservations: observations.length,
+                totalPrompts: prompts.length,
+                totalJournalEntries: journal.length,
+            },
+            projects,
+            sessions,
+            observations,
+            prompts,
+            journal,
+        };
+    }
+    async importProject(data, options) {
+        this.checkHealth();
+        const { conflictStrategy = 'skip', dryRun = false } = options || {};
+        const result = {
+            imported: { projects: 0, sessions: 0, observations: 0, prompts: 0, journalEntries: 0 },
+            skipped: { observations: 0, sessions: 0, journalEntries: 0 },
+            overwritten: { observations: 0 },
+            failed: 0,
+            errors: [],
+        };
+        if (!data.version) {
+            throw new Error('Invalid import data: missing version field');
+        }
+        // Determine target project
+        const targetProject = options?.projectId || data.source?.project || 'import';
+        // Validate observations types
+        const validTypes = ['decision', 'bug', 'discovery', 'note', 'summary', 'learning', 'pattern', 'architecture', 'config', 'preference'];
+        // UUID → new ID mappings for referential integrity
+        const sessionUuidToId = new Map();
+        // Create import session
+        const importSession = await this.createSession({
+            projectId: targetProject,
+            endedAt: null,
+            metadata: { type: 'full-import', source: 'web-ui', timestamp: new Date().toISOString() },
+        });
+        const doImport = this.db.transaction(() => {
+            // 1. Import projects (register if not exists)
+            if (data.projects && data.projects.length > 0) {
+                for (const proj of data.projects) {
+                    if (!dryRun) {
+                        this.db.prepare('INSERT OR IGNORE INTO projects (name, created_at, metadata) VALUES (?, ?, ?)').run(proj.name, Date.now(), this.serialize(proj.metadata || {}));
+                    }
+                    result.imported.projects++;
+                }
+            }
+            // 2. Import sessions (create new, map UUID → new ID)
+            if (data.sessions && data.sessions.length > 0) {
+                for (const sess of data.sessions) {
+                    // Check if session with this UUID already exists
+                    const existing = this.db
+                        .prepare('SELECT id FROM sessions WHERE uuid = ?')
+                        .get(sess.uuid);
+                    if (existing) {
+                        sessionUuidToId.set(sess.uuid, existing.id);
+                        result.skipped.sessions++;
+                        continue;
+                    }
+                    if (!dryRun) {
+                        const insertResult = this.db.prepare('INSERT INTO sessions (uuid, project_id, started_at, ended_at, metadata) VALUES (?, ?, ?, ?, ?)').run(sess.uuid, targetProject, new Date(sess.startedAt).getTime(), sess.endedAt ? new Date(sess.endedAt).getTime() : null, this.serialize(sess.metadata || {}));
+                        const newId = typeof insertResult.lastInsertRowid === 'bigint'
+                            ? Number(insertResult.lastInsertRowid)
+                            : insertResult.lastInsertRowid;
+                        sessionUuidToId.set(sess.uuid, newId);
+                    }
+                    else {
+                        // For dry run, assign placeholder IDs
+                        sessionUuidToId.set(sess.uuid, -(result.imported.sessions + 1));
+                    }
+                    result.imported.sessions++;
+                }
+            }
+            // 3. Import observations
+            if (data.observations && data.observations.length > 0) {
+                for (const obs of data.observations) {
+                    if (!obs.title || !obs.content || !obs.type) {
+                        result.errors.push(`Invalid observation: missing required fields`);
+                        result.failed++;
+                        continue;
+                    }
+                    if (!validTypes.includes(obs.type)) {
+                        result.errors.push(`Invalid type: "${obs.type}"`);
+                        result.failed++;
+                        continue;
+                    }
+                    // Check for duplicate by UUID
+                    const existing = obs.uuid
+                        ? this.db.prepare('SELECT id FROM observations WHERE uuid = ?').get(obs.uuid)
+                        : undefined;
+                    if (existing) {
+                        if (conflictStrategy === 'skip') {
+                            result.skipped.observations++;
+                            continue;
+                        }
+                        if (conflictStrategy === 'overwrite' && !dryRun) {
+                            this.db.prepare(`UPDATE observations SET title = ?, content = ?, type = ?, topic_key = ?, metadata = ?, scope = ?, pinned = ?, read_only = ?, revision_count = revision_count + 1 WHERE id = ?`).run(obs.title, obs.content, obs.type, obs.topicKey ?? null, this.serialize(obs.metadata || {}), obs.scope || 'project', obs.pinned ? 1 : 0, obs.readOnly ? 1 : 0, existing.id);
+                            // FTS5 sync
+                            this.db.prepare('DELETE FROM observations_fts WHERE rowid = ?').run(existing.id);
+                            const row = this.db
+                                .prepare('SELECT title, content, topic_key, project_id FROM observations WHERE id = ?')
+                                .get(existing.id);
+                            if (row) {
+                                this.db.prepare('INSERT INTO observations_fts(rowid, title, content, topic_key, project_id) VALUES (?, ?, ?, ?, ?)').run(existing.id, row.title, row.content, row.topic_key, row.project_id);
+                            }
+                        }
+                        result.overwritten.observations++;
+                        continue;
+                    }
+                    if (!dryRun) {
+                        const uuid = obs.uuid || crypto.randomUUID();
+                        const createdAt = obs.createdAt ? new Date(obs.createdAt).getTime() : Date.now();
+                        const sessionId = importSession.id;
+                        const metadata = this.serialize(obs.metadata || {});
+                        const insertResult = this.db.prepare(`INSERT INTO observations (uuid, session_id, title, content, type, topic_key, project_id, created_at, deleted_at, metadata, scope, pinned, read_only, revision_count)
+               VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(uuid, sessionId, obs.title, obs.content, obs.type, obs.topicKey ?? null, targetProject, createdAt, obs.deletedAt ? new Date(obs.deletedAt).getTime() : null, metadata, obs.scope || 'project', obs.pinned ? 1 : 0, obs.readOnly ? 1 : 0, obs.revisionCount ?? 0);
+                        const insertId = typeof insertResult.lastInsertRowid === 'bigint'
+                            ? Number(insertResult.lastInsertRowid)
+                            : insertResult.lastInsertRowid;
+                        // FTS5 sync
+                        this.db.prepare('INSERT INTO observations_fts(rowid, title, content, topic_key, project_id) VALUES (?, ?, ?, ?, ?)').run(insertId, obs.title, obs.content, obs.topicKey ?? '', targetProject);
+                    }
+                    result.imported.observations++;
+                }
+            }
+            // 4. Import prompts
+            if (data.prompts && data.prompts.length > 0) {
+                for (const prompt of data.prompts) {
+                    // Skip if UUID already exists
+                    if (prompt.uuid) {
+                        const existingPrompt = this.db
+                            .prepare('SELECT id FROM prompts WHERE uuid = ?')
+                            .get(prompt.uuid);
+                        if (existingPrompt)
+                            continue;
+                    }
+                    if (!dryRun) {
+                        const uuid = prompt.uuid || crypto.randomUUID();
+                        const createdAt = prompt.createdAt ? new Date(prompt.createdAt).getTime() : Date.now();
+                        this.db.prepare('INSERT INTO prompts (uuid, session_id, content, project_id, created_at, metadata) VALUES (?, ?, ?, ?, ?, ?)').run(uuid, importSession.id, prompt.content, targetProject, createdAt, this.serialize(prompt.metadata || {}));
+                    }
+                    result.imported.prompts++;
+                }
+            }
+            // 5. Import journal entries (with tag support and supersedes UUID mapping)
+            if (data.journal && data.journal.length > 0) {
+                // Two-pass: first insert all entries, then resolve supersedes
+                const journalUuidToId = new Map();
+                for (const entry of data.journal) {
+                    // Check if UUID already exists
+                    const existingEntry = entry.uuid
+                        ? this.db.prepare('SELECT id FROM journal WHERE uuid = ?').get(entry.uuid)
+                        : undefined;
+                    if (existingEntry) {
+                        journalUuidToId.set(entry.uuid, existingEntry.id);
+                        result.skipped.journalEntries++;
+                        continue;
+                    }
+                    if (!dryRun) {
+                        const uuid = entry.uuid || crypto.randomUUID();
+                        const createdAt = entry.createdAt ? new Date(entry.createdAt).getTime() : Date.now();
+                        // Find session by UUID if available
+                        let sessionId = null;
+                        // We don't have session UUID reference in journal import, use import session
+                        const insertResult = this.db.prepare(`INSERT INTO journal (uuid, project_id, session_id, title, body, model, provider, agent, superseded_by, invalidated_at, metadata, created_at)
+               VALUES (?, ?, ?, ?, ?, ?, ?, ?, NULL, ?, ?, ?)`).run(uuid, targetProject, sessionId, entry.title, entry.body, entry.model ?? null, entry.provider ?? null, entry.agent ?? null, entry.invalidatedAt ? new Date(entry.invalidatedAt).getTime() : null, this.serialize(entry.metadata || {}), createdAt);
+                        const newId = typeof insertResult.lastInsertRowid === 'bigint'
+                            ? Number(insertResult.lastInsertRowid)
+                            : insertResult.lastInsertRowid;
+                        journalUuidToId.set(uuid, newId);
+                        // Insert tags
+                        if (entry.tags && entry.tags.length > 0) {
+                            for (const tag of entry.tags) {
+                                this.db.prepare('INSERT INTO journal_tags (journal_id, tag) VALUES (?, ?)').run(newId, tag);
+                            }
+                        }
+                    }
+                    result.imported.journalEntries++;
+                }
+                // Second pass: resolve supersedes references
+                if (!dryRun) {
+                    for (const entry of data.journal) {
+                        if (entry.supersededByUuid && entry.uuid) {
+                            const entryId = journalUuidToId.get(entry.uuid);
+                            const supersededById = journalUuidToId.get(entry.supersededByUuid);
+                            if (entryId && supersededById) {
+                                this.db.prepare('UPDATE journal SET superseded_by = ? WHERE id = ?').run(supersededById, entryId);
+                            }
+                        }
+                    }
+                }
+            }
+        });
+        try {
+            doImport();
+        }
+        catch (error) {
+            if (error instanceof Error) {
+                result.errors.push(`Transaction failed: ${error.message}`);
+            }
+            result.failed++;
+        }
+        return result;
+    }
     close() {
         this.db.close();
     }