@devflow-tools/memory-engine 0.16.1 → 0.16.3

package/dist/memory-store.js

@@ -1,9 +1,10 @@
 import Database from 'better-sqlite3';
 import * as sqliteVec from 'sqlite-vec';
-import { join } from 'node:path';
+import { dirname, join } from 'node:path';
 import { existsSync, mkdirSync } from 'node:fs';
 import { randomUUID } from 'node:crypto';
 import { applyV2ToV3Migration } from './migrations/v2-to-v3.js';
+import { applyV3ToV4Migration } from './migrations/v3-to-v4.js';
 import { observationDedupKey, } from './observation-types.js';
 // ── Schema ─────────────────────────────────────────────
 const SCHEMA_V2 = `
@@ -258,8 +259,10 @@ END;
 export class MemoryStore {
     db;
     dbPath;
+    defaultProjectRoot;
     leaseStore = null;
     constructor(rootPath) {
+        this.defaultProjectRoot = rootPath;
         const memDir = join(rootPath, '.devflow', 'memory');
         if (!existsSync(memDir))
             mkdirSync(memDir, { recursive: true });
@@ -273,6 +276,8 @@ export class MemoryStore {
         this.db.exec(FTS_TRIGGERS);
         this.migrateV1ToV2();
         applyV2ToV3Migration(this.db);
+        applyV3ToV4Migration(this.db);
+        this.repairOrphanSessions(rootPath);
         console.log('[MemoryStore] Schema initialized', {
             dbPath: this.dbPath,
             tableCount: this.countTables(),
@@ -377,6 +382,9 @@ export class MemoryStore {
     }
     // ── Memory CRUD ──────────────────────────────────
     add(entry) {
+        if (entry.sessionId) {
+            this.ensureSession(entry.sessionId, this.defaultProjectRoot);
+        }
         const id = entry.id ?? `mem:${Date.now()}:${randomUUID().slice(0, 8)}`;
         const now = Date.now();
         const memType = entry.type ?? entry.category ?? 'fact';
@@ -479,6 +487,12 @@ export class MemoryStore {
             }
         })();
     }
+    commitObservationEmbeddingBatch(entries, checkpoint) {
+        this.db.transaction(() => {
+            this.insertObservationEmbeddings(entries);
+            this.setMaintenanceCheckpoint(checkpoint.action, checkpoint.cursor, checkpoint.details ?? {});
+        })();
+    }
     getEmbedding(id) {
         const row = this.db.prepare('SELECT embedding FROM memories_vec WHERE id = ?').get(id);
         return row?.embedding ?? null;
@@ -493,6 +507,8 @@ export class MemoryStore {
       SELECT o.*, vec_distance_cosine(o.embedding, ?) AS distance
       FROM observations o
       WHERE o.embedding IS NOT NULL
+        AND o.quality_status = 'accepted'
+        AND o.resolution_state <> 'superseded'
       ORDER BY distance LIMIT ?
     `).all(buffer, limit);
         return rows.map(row => ({ observation: row, distance: row.distance }));
@@ -529,19 +545,22 @@ export class MemoryStore {
     }
     // ── Events CRUD ──────────────────────────────────
     recordEvent(event) {
+        this.ensureSession(event.sessionId, event.project ?? this.defaultProjectRoot);
         this.db.prepare(`
       INSERT OR IGNORE INTO session_events
         (id, session_id, project, tool, command, exit_code, stderr,
          duration_ms, created_at, l1_score, dialog_score, user_message,
          kind, payload)
       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-    `).run(event.id, event.sessionId, event.project ?? '', event.tool, event.command ?? null, event.exitCode ?? null, event.stderr ?? null, event.durationMs ?? null, event.createdAt, event.l1Score ?? 0, event.dialogScore ?? 0, event.userMessage ?? null, event.kind ?? null, event.payload ? JSON.stringify(event.payload) : null);
+    `).run(event.id, event.sessionId, event.project ?? this.defaultProjectRoot, event.tool, event.command ?? null, event.exitCode ?? null, event.stderr ?? null, event.durationMs ?? null, event.createdAt, event.l1Score ?? 0, event.dialogScore ?? 0, event.userMessage ?? null, event.kind ?? null, event.payload ? JSON.stringify(event.payload) : null);
     }
     getSessionEvents(sessionId) {
         return this.db.prepare('SELECT * FROM session_events WHERE session_id = ? ORDER BY created_at ASC').all(sessionId);
     }
     getUnprocessedEvents() {
-        const events = this.db.prepare('SELECT * FROM session_events WHERE processed = 0 ORDER BY created_at ASC').all();
+        const events = this.db.prepare(`SELECT * FROM session_events
+       WHERE processed = 0 AND maintenance_status = 'active'
+       ORDER BY created_at ASC`).all();
         const pendingIds = this.leaseStore?.getPendingEventIds();
         if (!pendingIds || pendingIds.size === 0)
             return events;
@@ -551,7 +570,170 @@ export class MemoryStore {
         if (ids.length === 0)
             return;
         const placeholders = ids.map(() => '?').join(',');
-        this.db.prepare(`UPDATE session_events SET processed = 1 WHERE id IN (${placeholders})`).run(...ids);
+        const unprocessed = this.db.prepare(`SELECT id FROM session_events WHERE processed = 0 AND id IN (${placeholders})`).all(...ids);
+        if (unprocessed.length === 0)
+            return;
+        const coveredEventIds = new Set();
+        const observationRows = this.db.prepare(`SELECT source_event_ids FROM observations
+       WHERE quality_status = 'accepted' AND resolution_state <> 'superseded'`).all();
+        for (const row of observationRows) {
+            try {
+                const sourceEventIds = JSON.parse(row.source_event_ids);
+                if (Array.isArray(sourceEventIds)) {
+                    for (const eventId of sourceEventIds) {
+                        if (typeof eventId === 'string')
+                            coveredEventIds.add(eventId);
+                    }
+                }
+            }
+            catch {
+                // Malformed historical evidence cannot justify processing an event.
+            }
+        }
+        const missing = unprocessed.map(event => event.id).filter(id => !coveredEventIds.has(id));
+        if (missing.length > 0) {
+            throw new Error(`Cannot mark events processed without committed distilled observations: ${missing.join(', ')}`);
+        }
+        const pendingIds = unprocessed.map(event => event.id);
+        const pendingPlaceholders = pendingIds.map(() => '?').join(',');
+        this.db.prepare(`UPDATE session_events SET processed = 1 WHERE id IN (${pendingPlaceholders})`).run(...pendingIds);
+    }
+    discardEvents(ids, reason, runId) {
+        if (ids.length === 0)
+            return 0;
+        const uniqueIds = [...new Set(ids)];
+        const update = this.db.prepare(`
+      UPDATE session_events
+      SET processed = 1, maintenance_status = 'discarded', quarantine_reason = ?
+      WHERE id = ? AND processed = 0
+    `);
+        const insertAudit = this.db.prepare(`
+      INSERT INTO event_processing_audit
+        (id, event_id, disposition, reason, run_id, timestamp)
+      VALUES (?, ?, 'discarded', ?, ?, ?)
+    `);
+        return this.db.transaction(() => {
+            let changed = 0;
+            const now = Date.now();
+            for (const id of uniqueIds) {
+                const result = update.run(reason, id);
+                if (result.changes === 0)
+                    continue;
+                changed += result.changes;
+                insertAudit.run(`epa:${now}:${randomUUID().slice(0, 8)}`, id, reason, runId ?? null, now);
+            }
+            return changed;
+        })();
+    }
+    listAllEvents() {
+        return this.db.prepare('SELECT * FROM session_events ORDER BY created_at ASC, id ASC').all();
+    }
+    deduplicateEvents(canonicalId, duplicateIds, runId) {
+        const duplicates = [...new Set(duplicateIds)].filter(id => id !== canonicalId);
+        if (duplicates.length === 0)
+            return { deleted: 0, observationsRewritten: 0 };
+        const allIds = [canonicalId, ...duplicates];
+        const placeholders = allIds.map(() => '?').join(',');
+        const rows = this.db.prepare(`SELECT * FROM session_events WHERE id IN (${placeholders}) ORDER BY created_at ASC, id ASC`).all(...allIds);
+        if (rows.length !== allIds.length)
+            throw new Error('Duplicate event group changed during maintenance');
+        const pendingLeaseRows = this.db.prepare("SELECT event_ids FROM distill_leases WHERE status = 'pending'").all();
+        for (const lease of pendingLeaseRows) {
+            const eventIds = parseStringArray(lease.event_ids);
+            if (eventIds.some(id => allIds.includes(id))) {
+                throw new Error('Cannot deduplicate events referenced by a pending distill lease');
+            }
+        }
+        return this.db.transaction(() => {
+            const canonical = rows.find(row => row.id === canonicalId);
+            const richest = [...rows].sort((left, right) => eventRichness(right) - eventRichness(left))[0];
+            const processed = rows.some(row => row.processed === 1) ? 1 : 0;
+            this.db.prepare(`
+        UPDATE session_events SET
+          command = ?, exit_code = ?, stderr = ?, duration_ms = ?, processed = ?,
+          l1_score = MAX(l1_score, ?), dialog_score = MAX(dialog_score, ?),
+          user_message = ?, kind = ?, payload = ?
+        WHERE id = ?
+      `).run(richest.command ?? canonical.command, richest.exit_code ?? canonical.exit_code, richest.stderr ?? canonical.stderr, richest.duration_ms ?? canonical.duration_ms, processed, ...rows.map(row => row.l1_score).sort((a, b) => b - a).slice(0, 1), ...rows.map(row => row.dialog_score).sort((a, b) => b - a).slice(0, 1), richest.user_message ?? canonical.user_message, richest.kind ?? canonical.kind, richest.payload ?? canonical.payload, canonicalId);
+            let observationsRewritten = 0;
+            const observations = this.db.prepare('SELECT id, source_event_ids FROM observations').all();
+            const duplicateSet = new Set(duplicates);
+            const updateObservation = this.db.prepare('UPDATE observations SET source_event_ids = ?, updated_at = ? WHERE id = ?');
+            for (const observation of observations) {
+                const sourceIds = parseStringArray(observation.source_event_ids);
+                if (!sourceIds.some(id => duplicateSet.has(id)))
+                    continue;
+                const rewritten = [...new Set(sourceIds.map(id => duplicateSet.has(id) ? canonicalId : id))];
+                updateObservation.run(JSON.stringify(rewritten), Date.now(), observation.id);
+                observationsRewritten += 1;
+            }
+            const deleteEvent = this.db.prepare('DELETE FROM session_events WHERE id = ?');
+            const insertAudit = this.db.prepare(`
+        INSERT INTO event_processing_audit
+          (id, event_id, disposition, reason, run_id, timestamp)
+        VALUES (?, ?, 'duplicate_merged', 'historical_duplicate', ?, ?)
+      `);
+            let deleted = 0;
+            const now = Date.now();
+            for (const id of duplicates) {
+                deleted += deleteEvent.run(id).changes;
+                insertAudit.run(`epa:${now}:${randomUUID().slice(0, 8)}`, id, runId ?? null, now);
+            }
+            return { deleted, observationsRewritten };
+        })();
+    }
+    quarantineDuplicateEvents(groupKey, eventIds, reason) {
+        const uniqueIds = [...new Set(eventIds)];
+        if (uniqueIds.length === 0)
+            return 0;
+        return this.db.transaction(() => {
+            const update = this.db.prepare(`
+        UPDATE session_events
+        SET maintenance_status = 'quarantined', quarantine_reason = ?
+        WHERE id = ? AND maintenance_status <> 'quarantined'
+      `);
+            let changed = 0;
+            for (const id of uniqueIds)
+                changed += update.run(reason, id).changes;
+            this.db.prepare(`
+        INSERT INTO event_duplicate_quarantine
+          (group_key, event_ids, reason, created_at, resolved_at)
+        VALUES (?, ?, ?, ?, NULL)
+        ON CONFLICT(group_key) DO UPDATE SET
+          event_ids = excluded.event_ids,
+          reason = excluded.reason,
+          resolved_at = NULL
+      `).run(groupKey, JSON.stringify(uniqueIds), reason, Date.now());
+            return changed;
+        })();
+    }
+    requeueProcessedEventsWithoutAcceptedEvidence() {
+        const acceptedEvidence = new Set();
+        const observations = this.db.prepare(`
+      SELECT source_event_ids FROM observations
+      WHERE quality_status = 'accepted' AND resolution_state <> 'superseded'
+    `).all();
+        for (const observation of observations) {
+            for (const id of parseStringArray(observation.source_event_ids))
+                acceptedEvidence.add(id);
+        }
+        const intentionallyDiscarded = new Set(this.db.prepare(`
+      SELECT DISTINCT event_id FROM event_processing_audit WHERE disposition = 'discarded'
+    `).all().map(row => row.event_id));
+        const candidates = this.db.prepare(`
+      SELECT id FROM session_events WHERE processed = 1
+    `).all();
+        const ids = candidates
+            .map(row => row.id)
+            .filter(id => !acceptedEvidence.has(id) && !intentionallyDiscarded.has(id));
+        if (ids.length === 0)
+            return 0;
+        const update = this.db.prepare(`
+      UPDATE session_events
+      SET processed = 0, maintenance_status = 'active', quarantine_reason = NULL
+      WHERE id = ?
+    `);
+        return this.db.transaction(() => ids.reduce((count, id) => count + update.run(id).changes, 0))();
     }
     eventWindowExists(tool, command, windowMs = 5 * 60 * 1000) {
         const since = Date.now() - windowMs;
@@ -563,14 +745,72 @@ export class MemoryStore {
         return row !== undefined;
     }
     // ── Session CRUD ─────────────────────────────────
-    createSession(id, projectRoot, task = '') {
+    ensureSession(id, projectRoot = this.defaultProjectRoot, task = '') {
+        const sessionId = id.trim();
+        if (!sessionId)
+            throw new Error('Memory session ID must be a nonblank canonical host session ID');
+        const normalizedProjectRoot = projectRoot.trim() || this.defaultProjectRoot;
         this.db.prepare(`
       INSERT INTO sessions (id, project_root, task, status, created_at)
       VALUES (?, ?, ?, 'active', ?)
-    `).run(id, projectRoot, task, Date.now());
+      ON CONFLICT(id) DO UPDATE SET
+        project_root = CASE
+          WHEN sessions.project_root = '' THEN excluded.project_root
+          ELSE sessions.project_root
+        END,
+        task = CASE
+          WHEN sessions.task = '' AND excluded.task <> '' THEN excluded.task
+          ELSE sessions.task
+        END
+    `).run(sessionId, normalizedProjectRoot, task, Date.now());
+        return this.getSession(sessionId);
+    }
+    repairOrphanSessions(projectRoot = this.defaultProjectRoot) {
+        const repair = this.db.transaction(() => {
+            const blankEvents = this.db.prepare(`
+        SELECT id FROM session_events WHERE TRIM(session_id) = '' ORDER BY created_at ASC
+      `).all();
+            const assignRecoveredSession = this.db.prepare('UPDATE session_events SET session_id = ? WHERE id = ? AND TRIM(session_id) = \'\'');
+            for (const event of blankEvents) {
+                assignRecoveredSession.run(`recovered:orphan:${event.id}`, event.id);
+            }
+            const orphanSessions = this.db.prepare(`
+        SELECT
+          e.session_id AS id,
+          COALESCE(NULLIF(MAX(e.project), ''), ?) AS project_root,
+          MIN(e.created_at) AS created_at,
+          MAX(e.created_at) AS closed_at,
+          COUNT(*) AS tool_count,
+          SUM(CASE WHEN e.exit_code IS NOT NULL AND e.exit_code <> 0 THEN 1 ELSE 0 END) AS error_count
+        FROM session_events e
+        LEFT JOIN sessions s ON s.id = e.session_id
+        WHERE s.id IS NULL
+        GROUP BY e.session_id
+      `).all(projectRoot);
+            const insertRecovered = this.db.prepare(`
+        INSERT OR IGNORE INTO sessions
+          (id, project_root, task, status, phase_summary, signal_summary,
+           tool_count, error_count, created_at, closed_at)
+        VALUES (?, ?, 'Recovered orphan session events', 'closed', ?, '[]', ?, ?, ?, ?)
+      `);
+            let repaired = 0;
+            for (const session of orphanSessions) {
+                repaired += insertRecovered.run(session.id, session.project_root || projectRoot, JSON.stringify(['recovered_orphan_events']), session.tool_count, session.error_count, session.created_at, session.closed_at).changes;
+            }
+            return repaired;
+        });
+        const repaired = repair();
+        if (repaired > 0) {
+            console.log('[MemoryStore] Recovered orphan event sessions', { count: repaired });
+        }
+        return repaired;
+    }
+    createSession(id, projectRoot, task = '') {
+        this.ensureSession(id, projectRoot, task);
         console.log('[MemoryStore] Session created', { id, project: projectRoot, task });
     }
     closeSession(id) {
+        this.ensureSession(id, this.defaultProjectRoot, 'Recovered session close');
         const now = Date.now();
         this.db.prepare(`
       UPDATE sessions SET status = 'closed', closed_at = ?
@@ -606,20 +846,24 @@ export class MemoryStore {
     }
     // ── Observation CRUD ─────────────────────────────
     addObservation(obs) {
+        this.ensureSession(obs.sessionId, obs.project ?? this.defaultProjectRoot);
         const id = obs.id ?? `obs:${Date.now()}:${randomUUID().slice(0, 8)}`;
         const now = obs.timestamp ?? Date.now();
         const dedupKey = observationDedupKey(obs.type, obs.title);
         const duplicate = this.findObservationByDedupKey(dedupKey);
         if (duplicate) {
+            this.linkObservationToEvents(duplicate.id, obs.sourceEventIds ?? []);
             this.incrementObservationAccess(duplicate.id, now);
             return this.getObservation(duplicate.id);
         }
         this.db.prepare(`
       INSERT INTO observations
         (id, session_id, project, type, title, narrative, facts, files, tools, concepts,
-         importance, confidence, source, dedup_key, source_event_ids, timestamp, updated_at)
-      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-    `).run(id, obs.sessionId, obs.project ?? '', obs.type, obs.title, obs.narrative ?? '', JSON.stringify(obs.facts ?? []), JSON.stringify(obs.files ?? []), JSON.stringify(obs.tools ?? []), JSON.stringify(obs.concepts ?? []), obs.importance ?? 5, obs.confidence ?? 0.5, obs.source ?? 'distill', dedupKey, JSON.stringify(obs.sourceEventIds ?? []), now, now);
+         importance, confidence, source, dedup_key, source_event_ids, timestamp, updated_at,
+         quality_status, quarantine_reason, quality_details, quarantined_at,
+         failure_category, resolution_state)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `).run(id, obs.sessionId, obs.project ?? this.defaultProjectRoot, obs.type, obs.title, obs.narrative ?? '', JSON.stringify(obs.facts ?? []), JSON.stringify(obs.files ?? []), JSON.stringify(obs.tools ?? []), JSON.stringify(obs.concepts ?? []), obs.importance ?? 5, obs.confidence ?? 0.5, obs.source ?? 'distill', dedupKey, JSON.stringify(obs.sourceEventIds ?? []), now, now, obs.qualityStatus ?? 'accepted', obs.quarantineReason ?? null, obs.qualityDetails ? JSON.stringify(obs.qualityDetails) : null, obs.qualityStatus === 'quarantined' ? now : null, obs.failureCategory ?? null, obs.resolutionState ?? 'current');
         // Insert concept junction rows
         if (obs.concepts && obs.concepts.length > 0) {
             const insertConcept = this.db.prepare('INSERT OR IGNORE INTO observation_concepts (observation_id, concept) VALUES (?, ?)');
@@ -632,9 +876,34 @@ export class MemoryStore {
         });
         return this.getObservation(id);
     }
+    addObservationWithEmbedding(obs, embedding) {
+        return this.db.transaction(() => {
+            const row = this.addObservation(obs);
+            this.insertObservationEmbedding(row.id, embedding);
+            return this.getObservation(row.id);
+        })();
+    }
     getObservation(id) {
         return this.db.prepare('SELECT * FROM observations WHERE id = ?').get(id) ?? null;
     }
+    linkObservationToEvents(observationId, eventIds) {
+        if (eventIds.length === 0)
+            return;
+        const observation = this.getObservation(observationId);
+        if (!observation)
+            throw new Error(`Observation ${observationId} not found`);
+        let existing = [];
+        try {
+            const parsed = JSON.parse(observation.source_event_ids);
+            if (Array.isArray(parsed))
+                existing = parsed.filter((id) => typeof id === 'string');
+        }
+        catch {
+            // Replace malformed historical evidence with the current committed links.
+        }
+        const merged = [...new Set([...existing, ...eventIds])];
+        this.db.prepare('UPDATE observations SET source_event_ids = ?, updated_at = ? WHERE id = ?').run(JSON.stringify(merged), Date.now(), observationId);
+    }
     findObservationByDedupKey(dedupKey) {
         return this.db.prepare('SELECT * FROM observations WHERE dedup_key = ?').get(dedupKey) ?? null;
     }
@@ -644,26 +913,30 @@ export class MemoryStore {
       SELECT o.*
       FROM observations o
       WHERE o.type = ? AND o.timestamp >= ? AND o.embedding IS NOT NULL
+        AND o.quality_status = 'accepted' AND o.resolution_state <> 'superseded'
         AND (1.0 - vec_distance_cosine(o.embedding, ?)) > ?
       ORDER BY vec_distance_cosine(o.embedding, ?) ASC
       LIMIT 1
     `).get(type, cutoff, buffer, threshold, buffer) ?? null;
     }
     incrementObservationAccess(id, now = Date.now()) {
-        this.db.prepare(`
-      UPDATE observations
-      SET access_count = access_count + 1, updated_at = ?
-      WHERE id = ?
-    `).run(now, id);
+        this.recordRetrievalAccess({
+            sourceType: 'observation',
+            sourceId: id,
+            accessType: 'operational',
+            purpose: 'dedup_or_reinforcement',
+            timestamp: now,
+        });
     }
     promoteObservationToExplicitIntent(id, now = Date.now()) {
         this.db.prepare(`
       UPDATE observations
       SET source = 'explicit_intent', confidence = MAX(confidence, 0.95),
-        importance = MAX(importance, 10), access_count = access_count + 1,
+        importance = MAX(importance, 10),
         updated_at = ?
       WHERE id = ?
     `).run(now, id);
+        this.incrementObservationAccess(id, now);
         return this.getObservation(id);
     }
     listObservations(filter) {
@@ -681,6 +954,14 @@ export class MemoryStore {
             conditions.push('o.type = ?');
             vals.push(filter.type);
         }
+        if (filter?.qualityStatus) {
+            conditions.push('o.quality_status = ?');
+            vals.push(filter.qualityStatus);
+        }
+        if (filter?.resolutionState) {
+            conditions.push('o.resolution_state = ?');
+            vals.push(filter.resolutionState);
+        }
         if (filter?.memoryId !== undefined) {
             if (filter.memoryId === null) {
                 conditions.push('o.memory_id IS NULL');
@@ -709,23 +990,44 @@ export class MemoryStore {
     listObservationsMissingEmbedding(limit = 32, afterId) {
         return this.db.prepare(`
       SELECT * FROM observations
-      WHERE embedding IS NULL AND (? IS NULL OR id > ?)
+      WHERE embedding IS NULL AND quality_status = 'accepted'
+        AND resolution_state <> 'superseded' AND (? IS NULL OR id > ?)
       ORDER BY id LIMIT ?
     `).all(afterId ?? null, afterId ?? null, limit);
     }
     countObservationVectors() {
         const row = this.db.prepare(`
       SELECT COUNT(*) AS observations,
-        SUM(CASE WHEN embedding IS NOT NULL THEN 1 ELSE 0 END) AS vectors,
-        SUM(CASE WHEN embedding IS NULL THEN 1 ELSE 0 END) AS missing
+        SUM(CASE WHEN quality_status = 'accepted' AND resolution_state <> 'superseded' THEN 1 ELSE 0 END) AS eligible,
+        SUM(CASE WHEN quality_status = 'accepted' AND resolution_state <> 'superseded' AND embedding IS NOT NULL THEN 1 ELSE 0 END) AS vectors,
+        SUM(CASE WHEN quality_status = 'accepted' AND resolution_state <> 'superseded' AND embedding IS NULL THEN 1 ELSE 0 END) AS missing,
+        SUM(CASE WHEN quality_status = 'quarantined' THEN 1 ELSE 0 END) AS quarantined
       FROM observations
     `).get();
         return {
             observations: row.observations,
+            eligible: row.eligible ?? 0,
             vectors: row.vectors ?? 0,
             missing: row.missing ?? 0,
+            quarantined: row.quarantined ?? 0,
         };
     }
+    quarantineObservation(id, reason, details = {}, now = Date.now()) {
+        const result = this.db.prepare(`
+      UPDATE observations
+      SET quality_status = 'quarantined', quarantine_reason = ?, quality_details = ?,
+        quarantined_at = ?, updated_at = ?
+      WHERE id = ? AND quality_status <> 'quarantined'
+    `).run(reason, JSON.stringify(details), now, now, id);
+        return result.changes === 1;
+    }
+    setObservationResolution(id, state, supersededBy) {
+        this.db.prepare(`
+      UPDATE observations
+      SET resolution_state = ?, superseded_by_observation = ?, updated_at = ?
+      WHERE id = ?
+    `).run(state, supersededBy ?? null, Date.now(), id);
+    }
     getObservationsByConcept(concept, limit = 50) {
         return this.listObservations({ concept, limit });
     }
@@ -749,6 +1051,7 @@ export class MemoryStore {
         return this.db.prepare(`
       SELECT * FROM observations
       WHERE project = ? AND memory_id IS NULL AND importance >= ?
+        AND quality_status = 'accepted' AND resolution_state <> 'superseded'
       ORDER BY timestamp DESC
     `).all(project, minImportance);
     }
@@ -763,6 +1066,7 @@ export class MemoryStore {
       FROM observation_concepts oc
       JOIN observations o ON o.id = oc.observation_id
       WHERE o.project = ? AND o.memory_id IS NULL AND o.importance >= 5
+        AND o.quality_status = 'accepted' AND o.resolution_state <> 'superseded'
       GROUP BY oc.concept
       HAVING observation_count >= ? AND session_count >= ?
       ORDER BY observation_count DESC
@@ -782,6 +1086,7 @@ export class MemoryStore {
       VALUES (?, ?, ?, ?, ?, ?, ?)
     `);
         for (const s of signals) {
+            this.ensureSession(s.sessionId, this.defaultProjectRoot);
             insert.run(s.id, s.sessionId, s.type, s.strength, JSON.stringify(s.sourceEventIds), JSON.stringify(s.payload), s.timestamp);
         }
         if (signals.length > 0) {
@@ -804,21 +1109,65 @@ export class MemoryStore {
         return this.db.prepare('SELECT * FROM evidence WHERE memory_id = ? ORDER BY timestamp DESC').all(memoryId);
     }
     // ── Access Log ───────────────────────────────────
+    recordRetrievalAccess(input) {
+        const timestamp = input.timestamp ?? Date.now();
+        const id = `racc:${timestamp}:${randomUUID().slice(0, 8)}`;
+        this.db.transaction(() => {
+            if (input.sourceType === 'memory') {
+                const updated = this.db.prepare(`
+          UPDATE memories SET access_count = access_count + 1,
+            last_reinforced_at = COALESCE(last_reinforced_at, ?),
+            last_accessed_at = ?, updated_at = ?
+          WHERE id = ?
+        `).run(timestamp, timestamp, timestamp, input.sourceId);
+                if (updated.changes !== 1)
+                    throw new Error(`Memory ${input.sourceId} not found`);
+                const legacyAccessTypes = new Set(['search_hit', 'user_view', 'agent_use', 'manual_ref']);
+                const accessType = legacyAccessTypes.has(input.accessType ?? '')
+                    ? input.accessType
+                    : 'agent_use';
+                this.db.prepare(`
+          INSERT INTO access_log
+            (id, memory_id, access_type, session_id, timestamp, query, purpose, rank, score)
+          VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+        `).run(`acc:${timestamp}:${randomUUID().slice(0, 8)}`, input.sourceId, accessType, input.sessionId ?? null, timestamp, input.query ?? null, input.purpose ?? null, input.rank ?? null, input.score ?? null);
+            }
+            else {
+                const updated = this.db.prepare(`
+          UPDATE observations
+          SET access_count = access_count + 1, updated_at = ?
+          WHERE id = ?
+        `).run(timestamp, input.sourceId);
+                if (updated.changes !== 1)
+                    throw new Error(`Observation ${input.sourceId} not found`);
+            }
+            this.db.prepare(`
+        INSERT INTO retrieval_access_log
+          (id, source_type, source_id, access_type, session_id, query, purpose, rank, score, timestamp)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      `).run(id, input.sourceType, input.sourceId, input.accessType ?? 'search_hit', input.sessionId ?? null, input.query ?? null, input.purpose ?? null, input.rank ?? null, input.score ?? null, timestamp);
+        })();
+    }
     recordAccess(memoryId, accessType, sessionId) {
-        const id = `acc:${Date.now()}:${randomUUID().slice(0, 8)}`;
-        this.db.prepare(`
-      INSERT INTO access_log (id, memory_id, access_type, session_id, timestamp)
-      VALUES (?, ?, ?, ?, ?)
-    `).run(id, memoryId, accessType, sessionId ?? null, Date.now());
+        this.recordRetrievalAccess({
+            sourceType: 'memory',
+            sourceId: memoryId,
+            accessType,
+            sessionId,
+        });
     }
     incrementAccess(id) {
-        const now = Date.now();
-        this.db.prepare(`
-      UPDATE memories SET access_count = access_count + 1,
-        last_reinforced_at = COALESCE(last_reinforced_at, ?),
-        last_accessed_at = ?, updated_at = ?
-      WHERE id = ?
-    `).run(now, now, now, id);
+        this.recordRetrievalAccess({
+            sourceType: 'memory',
+            sourceId: id,
+            accessType: 'agent_use',
+            purpose: 'reinforcement',
+        });
+    }
+    listRetrievalAccessLog(limit = 100) {
+        return this.db.prepare(`
+      SELECT * FROM retrieval_access_log ORDER BY timestamp DESC, id DESC LIMIT ?
+    `).all(limit);
     }
     // ── Memory History ───────────────────────────────
     recordHistory(entry) {
@@ -979,6 +1328,52 @@ export class MemoryStore {
         const result = this.db.prepare("DELETE FROM memories WHERE status = 'pending' AND source = 'rule_engine' AND confidence < 0.6").run();
         return { removed: result.changes };
     }
+    getMaintenanceCheckpoint(action) {
+        const row = this.db.prepare(`
+      SELECT action, cursor, details, updated_at
+      FROM maintenance_checkpoints WHERE action = ?
+    `).get(action);
+        if (!row)
+            return null;
+        return {
+            action: row.action,
+            cursor: row.cursor,
+            details: parseObject(row.details),
+            updatedAt: row.updated_at,
+        };
+    }
+    setMaintenanceCheckpoint(action, cursor, details = {}) {
+        this.db.prepare(`
+      INSERT INTO maintenance_checkpoints (action, cursor, details, updated_at)
+      VALUES (?, ?, ?, ?)
+      ON CONFLICT(action) DO UPDATE SET
+        cursor = excluded.cursor,
+        details = excluded.details,
+        updated_at = excluded.updated_at
+    `).run(action, cursor, JSON.stringify(details), Date.now());
+    }
+    clearMaintenanceCheckpoint(action) {
+        this.db.prepare('DELETE FROM maintenance_checkpoints WHERE action = ?').run(action);
+    }
+    recordMaintenanceRun(input) {
+        this.db.prepare(`
+      INSERT INTO memory_maintenance_runs (id, mode, actions, manifest, created_at)
+      VALUES (?, ?, ?, ?, ?)
+    `).run(input.id, input.mode, JSON.stringify(input.actions), JSON.stringify(input.manifest), input.createdAt ?? Date.now());
+    }
+    countRecentRetrievalAccess(since) {
+        const row = this.db.prepare(`
+      SELECT COUNT(*) AS count FROM retrieval_access_log WHERE timestamp >= ?
+    `).get(since);
+        return row.count;
+    }
+    getDatabasePath() {
+        return this.dbPath;
+    }
+    async backupTo(destination) {
+        mkdirSync(dirname(destination), { recursive: true });
+        await this.db.backup(destination);
+    }
     // ── Lifecycle ────────────────────────────────────
     close() {
         this.db.close();
@@ -988,4 +1383,35 @@ export class MemoryStore {
 function camelToSnake(str) {
     return str.replace(/[A-Z]/g, letter => `_${letter.toLowerCase()}`);
 }
+function parseStringArray(value) {
+    try {
+        const parsed = JSON.parse(value);
+        return Array.isArray(parsed)
+            ? parsed.filter((entry) => typeof entry === 'string' && entry.length > 0)
+            : [];
+    }
+    catch {
+        return [];
+    }
+}
+function parseObject(value) {
+    try {
+        const parsed = JSON.parse(value);
+        return parsed && typeof parsed === 'object' && !Array.isArray(parsed)
+            ? parsed
+            : {};
+    }
+    catch {
+        return {};
+    }
+}
+function eventRichness(event) {
+    return [
+        event.command,
+        event.stderr,
+        event.user_message,
+        event.kind,
+        event.payload,
+    ].filter(value => value !== null && value !== '').length;
+}
 //# sourceMappingURL=memory-store.js.map