@devflow-tools/memory-engine 0.16.11 → 0.16.13

package/dist/memory-store.js

@@ -2,11 +2,15 @@ import Database from 'better-sqlite3';
 import * as sqliteVec from 'sqlite-vec';
 import { dirname, join } from 'node:path';
 import { existsSync, mkdirSync } from 'node:fs';
-import { randomUUID } from 'node:crypto';
+import { createHash, randomUUID } from 'node:crypto';
 import { applyV2ToV3Migration } from './migrations/v2-to-v3.js';
 import { applyV3ToV4Migration } from './migrations/v3-to-v4.js';
 import { applyV4ToV5Migration } from './migrations/v4-to-v5.js';
+import { applyV6ToV7Migration } from './migrations/v6-to-v7.js';
+import { applyV7ToV8Migration } from './migrations/v7-to-v8.js';
+import { applyV8ToV9Migration } from './migrations/v8-to-v9.js';
 import { observationDedupKey, } from './observation-types.js';
+import { analysesConflict, analyzePreference, analyzePreferenceObservation, } from './preference-conflicts.js';
 // ── Schema ─────────────────────────────────────────────
 const SCHEMA_V2 = `
 -- ============================================================
@@ -169,7 +173,10 @@ CREATE TABLE IF NOT EXISTS observations (
   source_event_ids TEXT NOT NULL DEFAULT '[]',
   memory_id        TEXT,
   embedding        BLOB,
-  timestamp        INTEGER NOT NULL
+  timestamp        INTEGER NOT NULL,
+  explicit_accepted_at INTEGER,
+  evidence_status TEXT NOT NULL DEFAULT 'unverified',
+  evidence_details TEXT NOT NULL DEFAULT '[]'
 );
 CREATE INDEX IF NOT EXISTS idx_observations_session ON observations(session_id);
 CREATE INDEX IF NOT EXISTS idx_observations_project ON observations(project);
@@ -256,6 +263,126 @@ CREATE TRIGGER IF NOT EXISTS memories_au AFTER UPDATE ON memories BEGIN
   VALUES (new.rowid, new.id, new.content, new.scope);
 END;
 `;
+const OBSERVATION_FTS_SCHEMA = `
+CREATE VIRTUAL TABLE IF NOT EXISTS observations_fts USING fts5(
+  id UNINDEXED,
+  title,
+  narrative,
+  facts,
+  concepts,
+  tokenize='trigram'
+);
+
+CREATE VIRTUAL TABLE IF NOT EXISTS observations_terms_fts USING fts5(
+  id UNINDEXED,
+  title,
+  narrative,
+  facts,
+  concepts,
+  tokenize = "unicode61 tokenchars '#+'"
+);
+
+CREATE TRIGGER IF NOT EXISTS observations_fts_ai
+AFTER INSERT ON observations
+WHEN new.quality_status = 'accepted' AND new.resolution_state = 'current'
+BEGIN
+  INSERT INTO observations_fts(rowid, id, title, narrative, facts, concepts)
+  VALUES (new.rowid, new.id, new.title, new.narrative, new.facts, new.concepts);
+  INSERT INTO observations_terms_fts(rowid, id, title, narrative, facts, concepts)
+  VALUES (new.rowid, new.id, new.title, new.narrative, new.facts, new.concepts);
+END;
+
+CREATE TRIGGER IF NOT EXISTS observations_fts_ad
+AFTER DELETE ON observations
+WHEN old.quality_status = 'accepted' AND old.resolution_state = 'current'
+BEGIN
+  DELETE FROM observations_fts WHERE rowid = old.rowid;
+  DELETE FROM observations_terms_fts WHERE rowid = old.rowid;
+END;
+
+CREATE TRIGGER IF NOT EXISTS observations_fts_au
+AFTER UPDATE OF title, narrative, facts, concepts, quality_status, resolution_state ON observations
+BEGIN
+  DELETE FROM observations_fts WHERE rowid = old.rowid;
+  DELETE FROM observations_terms_fts WHERE rowid = old.rowid;
+  INSERT INTO observations_fts(rowid, id, title, narrative, facts, concepts)
+  SELECT new.rowid, new.id, new.title, new.narrative, new.facts, new.concepts
+  WHERE new.quality_status = 'accepted' AND new.resolution_state = 'current';
+  INSERT INTO observations_terms_fts(rowid, id, title, narrative, facts, concepts)
+  SELECT new.rowid, new.id, new.title, new.narrative, new.facts, new.concepts
+  WHERE new.quality_status = 'accepted' AND new.resolution_state = 'current';
+END;
+`;
+const MAX_OBSERVATION_FTS_QUERY_LENGTH = 512;
+const MAX_OBSERVATION_FTS_TERMS = 16;
+const MAX_OBSERVATION_FTS_TERM_LENGTH = 64;
+const OBSERVATION_FTS_SCHEMA_VERSION = 6;
+const OBSERVATION_EXCLUSION_CTE = `
+  WITH excluded_observation_ids(id) AS (
+    SELECT CAST(value AS TEXT) FROM json_each(?)
+  )
+`;
+function serializeObservationSearchExcludedIds(excludedIds) {
+    return JSON.stringify(excludedIds ? [...excludedIds] : []);
+}
+function normalizeObservationLexicalQuery(query) {
+    const phrase = query
+        .slice(0, MAX_OBSERVATION_FTS_QUERY_LENGTH)
+        .normalize('NFKC')
+        .slice(0, MAX_OBSERVATION_FTS_QUERY_LENGTH)
+        .replace(/\s+/gu, ' ')
+        .trim();
+    if (!phrase)
+        return { trigramQuery: null, termQuery: null };
+    const lexicalTerms = phrase.match(/[\p{L}\p{N}]+/gu) ?? [];
+    const compact = lexicalTerms.join('');
+    const candidates = [compact, phrase, ...lexicalTerms];
+    const trigramTerms = [];
+    const termTerms = [];
+    const seenTrigrams = new Set();
+    const seenTerms = new Set();
+    for (const candidate of candidates) {
+        const term = [...candidate].slice(0, MAX_OBSERVATION_FTS_TERM_LENGTH).join('');
+        const searchableCharacters = term.match(/[\p{L}\p{N}]/gu) ?? [];
+        const normalized = term.toLocaleLowerCase('en-US');
+        const quoted = `"${term.replaceAll('"', '""')}"`;
+        if (searchableCharacters.length >= 3 && !seenTrigrams.has(normalized)) {
+            seenTrigrams.add(normalized);
+            trigramTerms.push(quoted);
+        }
+        if (searchableCharacters.length >= 1 && !seenTerms.has(normalized)) {
+            seenTerms.add(normalized);
+            termTerms.push(quoted);
+        }
+        if (trigramTerms.length >= MAX_OBSERVATION_FTS_TERMS
+            && termTerms.length >= MAX_OBSERVATION_FTS_TERMS)
+            break;
+    }
+    return {
+        trigramQuery: trigramTerms.length > 0
+            ? trigramTerms.slice(0, MAX_OBSERVATION_FTS_TERMS).join(' OR ')
+            : null,
+        termQuery: termTerms.length > 0
+            ? termTerms.slice(0, MAX_OBSERVATION_FTS_TERMS).join(' OR ')
+            : null,
+    };
+}
+export function isRecoverableObservationFtsError(error) {
+    const candidate = error;
+    const code = typeof candidate?.code === 'string' ? candidate.code.toUpperCase() : '';
+    const message = typeof candidate?.message === 'string' ? candidate.message : '';
+    if (/^SQLITE_(?:BUSY|LOCKED|READONLY|IOERR|FULL|CANTOPEN|PERM)/.test(code))
+        return false;
+    if (code === 'SQLITE_CORRUPT_VTAB')
+        return true;
+    const referencesObservationFts = /observations_(?:terms_)?fts(?:_(?:data|idx|content|docsize|config))?/i
+        .test(message);
+    if (!referencesObservationFts)
+        return false;
+    if (/^SQLITE_CORRUPT(?:_|$)/.test(code))
+        return true;
+    return code === 'SQLITE_ERROR' && /no such table|malformed schema|vtable constructor failed/i.test(message);
+}
 // ── MemoryStore ─────────────────────────────────────────
 export class MemoryStore {
     db;
@@ -275,10 +402,15 @@ export class MemoryStore {
         sqliteVec.load(this.db);
         this.db.exec(SCHEMA_V2);
         this.db.exec(FTS_TRIGGERS);
+        this.dropOrphanedObservationFtsTriggers();
         this.migrateV1ToV2();
         applyV2ToV3Migration(this.db);
         applyV3ToV4Migration(this.db);
         applyV4ToV5Migration(this.db);
+        this.ensureObservationFts();
+        applyV6ToV7Migration(this.db);
+        applyV7ToV8Migration(this.db);
+        applyV8ToV9Migration(this.db);
         this.repairOrphanSessions(rootPath);
         console.log('[MemoryStore] Schema initialized', {
             dbPath: this.dbPath,
@@ -292,6 +424,66 @@ export class MemoryStore {
         const row = this.db.prepare("SELECT COUNT(*) as c FROM sqlite_master WHERE type='table'").get();
         return row.c;
     }
+    dropOrphanedObservationFtsTriggers() {
+        const ftsTables = this.db.prepare("SELECT name FROM sqlite_master WHERE type = 'table' AND name IN ('observations_fts', 'observations_terms_fts')").all();
+        if (ftsTables.length === 2)
+            return;
+        this.db.exec(`
+      DROP TRIGGER IF EXISTS observations_fts_ai;
+      DROP TRIGGER IF EXISTS observations_fts_ad;
+      DROP TRIGGER IF EXISTS observations_fts_au;
+    `);
+    }
+    ensureObservationFts(forceRebuild = false) {
+        this.db.transaction(() => {
+            const ftsTableCount = this.db.prepare("SELECT COUNT(*) AS count FROM sqlite_master WHERE type = 'table' AND name IN ('observations_fts', 'observations_terms_fts')").get().count;
+            const migrationApplied = this.db.prepare('SELECT 1 FROM schema_versions WHERE version = ?').get(OBSERVATION_FTS_SCHEMA_VERSION) !== undefined;
+            const triggersCurrent = this.db.prepare(`
+        SELECT COUNT(*) AS count
+        FROM sqlite_master
+        WHERE type = 'trigger'
+          AND name IN ('observations_fts_ai', 'observations_fts_ad', 'observations_fts_au')
+          AND sql LIKE '%observations_terms_fts%'
+      `).get().count === 3;
+            const needsRebuild = forceRebuild
+                || ftsTableCount !== 2
+                || !migrationApplied
+                || !triggersCurrent;
+            if (needsRebuild) {
+                this.db.exec(`
+          DROP TRIGGER IF EXISTS observations_fts_ai;
+          DROP TRIGGER IF EXISTS observations_fts_ad;
+          DROP TRIGGER IF EXISTS observations_fts_au;
+        `);
+            }
+            if (forceRebuild) {
+                this.db.exec(`
+          DROP TABLE IF EXISTS observations_fts;
+          DROP TABLE IF EXISTS observations_terms_fts;
+        `);
+            }
+            this.db.exec(OBSERVATION_FTS_SCHEMA);
+            if (!needsRebuild)
+                return;
+            this.db.exec(`
+        DELETE FROM observations_fts;
+        DELETE FROM observations_terms_fts;
+
+        INSERT INTO observations_fts(rowid, id, title, narrative, facts, concepts)
+        SELECT o.rowid, o.id, o.title, o.narrative, o.facts, o.concepts
+        FROM observations o
+        WHERE o.quality_status = 'accepted'
+          AND o.resolution_state = 'current';
+
+        INSERT INTO observations_terms_fts(rowid, id, title, narrative, facts, concepts)
+        SELECT o.rowid, o.id, o.title, o.narrative, o.facts, o.concepts
+        FROM observations o
+        WHERE o.quality_status = 'accepted'
+          AND o.resolution_state = 'current';
+      `);
+            this.db.prepare('INSERT OR REPLACE INTO schema_versions(version, applied_at) VALUES (?, ?)').run(OBSERVATION_FTS_SCHEMA_VERSION, Date.now());
+        })();
+    }
     // ── V1 → V2 Migration ────────────────────────────
     migrateV1ToV2() {
         const tables = this.db.prepare("SELECT name FROM sqlite_master WHERE type='table'").all().map(r => r.name);
@@ -503,16 +695,18 @@ export class MemoryStore {
         const row = this.db.prepare('SELECT vector FROM embeddings WHERE source_type = ? AND source_id = ?').get(sourceType, sourceId);
         return row?.vector ?? null;
     }
-    searchObservationVector(embedding, limit = 20) {
+    searchObservationVector(embedding, limit = 20, excludedIds) {
         const buffer = Buffer.from(embedding.buffer, embedding.byteOffset, embedding.byteLength);
-        const rows = this.db.prepare(`
+        const excludedJson = serializeObservationSearchExcludedIds(excludedIds);
+        const rows = this.db.prepare(`${OBSERVATION_EXCLUSION_CTE}
       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'
+        AND o.id NOT IN (SELECT id FROM excluded_observation_ids)
       ORDER BY distance LIMIT ?
-    `).all(buffer, limit);
+    `).all(excludedJson, buffer, limit);
         return rows.map(row => ({ observation: row, distance: row.distance }));
     }
     // ── Search ───────────────────────────────────────
@@ -525,6 +719,66 @@ export class MemoryStore {
       ORDER BY rank LIMIT ?
     `).all(query, limit);
     }
+    searchObservationBM25(query, limit = 20, excludedIds) {
+        const normalizedQuery = normalizeObservationLexicalQuery(query);
+        if ((!normalizedQuery.trigramQuery && !normalizedQuery.termQuery) || limit <= 0)
+            return [];
+        const boundedLimit = Number.isFinite(limit)
+            ? Math.min(Math.max(Math.floor(limit), 1), 100)
+            : 20;
+        const excludedJson = serializeObservationSearchExcludedIds(excludedIds);
+        const scores = new Map();
+        const addRanked = (rows) => {
+            for (let index = 0; index < rows.length; index++) {
+                const id = rows[index].id;
+                scores.set(id, (scores.get(id) ?? 0) + 1 / (60 + index + 1));
+            }
+        };
+        if (normalizedQuery.trigramQuery) {
+            addRanked(this.searchObservationFtsWithRecovery('observations_fts', normalizedQuery.trigramQuery, boundedLimit, excludedJson));
+        }
+        if (normalizedQuery.termQuery) {
+            addRanked(this.searchObservationFtsWithRecovery('observations_terms_fts', normalizedQuery.termQuery, boundedLimit, excludedJson));
+        }
+        return [...scores]
+            .map(([id, score]) => ({ id, rank: -score }))
+            .sort((left, right) => left.rank - right.rank || left.id.localeCompare(right.id))
+            .slice(0, boundedLimit);
+    }
+    searchObservationFtsWithRecovery(table, query, limit, excludedJson) {
+        try {
+            return this.searchObservationFts(table, query, limit, excludedJson);
+        }
+        catch (error) {
+            if (!isRecoverableObservationFtsError(error))
+                throw error;
+            this.ensureObservationFts(true);
+            return this.searchObservationFts(table, query, limit, excludedJson);
+        }
+    }
+    searchObservationFts(table, query, limit, excludedJson) {
+        const sql = table === 'observations_fts' ? `${OBSERVATION_EXCLUSION_CTE}
+      SELECT o.id, bm25(observations_fts) AS rank
+      FROM observations_fts f
+      JOIN observations o ON o.rowid = f.rowid
+      WHERE observations_fts MATCH ?
+        AND o.quality_status = 'accepted'
+        AND o.resolution_state = 'current'
+        AND o.id NOT IN (SELECT id FROM excluded_observation_ids)
+      ORDER BY rank LIMIT ?
+    ` : `${OBSERVATION_EXCLUSION_CTE}
+      SELECT o.id, bm25(observations_terms_fts) AS rank
+      FROM observations_terms_fts f
+      JOIN observations o ON o.rowid = f.rowid
+      WHERE observations_terms_fts MATCH ?
+        AND o.quality_status = 'accepted'
+        AND o.resolution_state = 'current'
+        AND o.id NOT IN (SELECT id FROM excluded_observation_ids)
+      ORDER BY rank, updated_at DESC
+      LIMIT ?
+    `;
+        return this.db.prepare(sql).all(excludedJson, query, limit);
+    }
     searchVector(embedding, limit = 20) {
         const buffer = Buffer.from(embedding.buffer);
         return this.db.prepare(`
@@ -569,6 +823,123 @@ export class MemoryStore {
     getSessionEvents(sessionId) {
         return this.db.prepare('SELECT * FROM session_events WHERE session_id = ? ORDER BY created_at ASC').all(sessionId);
     }
+    reconcileDecidedTurnEventWindows(sessionId, turns, sessionEndAt = Number.MAX_SAFE_INTEGER) {
+        const normalizedSessionId = sessionId.trim();
+        if (!normalizedSessionId)
+            throw new Error('Session event reconciliation requires a session ID');
+        if (!Number.isSafeInteger(sessionEndAt) || sessionEndAt < 0) {
+            throw new Error('Session event reconciliation requires a safe session end timestamp');
+        }
+        const orderedTurns = turns.filter(turn => turn.sessionId === normalizedSessionId);
+        if (orderedTurns.length !== turns.length) {
+            throw new Error('Memory turn session does not match event reconciliation session');
+        }
+        for (let index = 1; index < orderedTurns.length; index += 1) {
+            if (orderedTurns[index].createdAt < orderedTurns[index - 1].createdAt) {
+                throw new Error('Memory turns must be ordered by createdAt for event reconciliation');
+            }
+        }
+        const selectSessionEvents = this.db.prepare(`
+      SELECT id, created_at FROM session_events
+      WHERE session_id = ? AND processed = 0 AND maintenance_status = 'active'
+      ORDER BY created_at ASC, id ASC
+    `);
+        const markCommitted = this.db.prepare(`
+      UPDATE session_events SET processed = 1
+      WHERE id = ? AND session_id = ? AND processed = 0 AND maintenance_status = 'active'
+    `);
+        const markSkipped = this.db.prepare(`
+      UPDATE session_events
+      SET processed = 1, maintenance_status = 'discarded', quarantine_reason = ?
+      WHERE id = ? AND session_id = ? AND processed = 0 AND maintenance_status = 'active'
+    `);
+        const insertAudit = this.db.prepare(`
+      INSERT INTO event_processing_audit
+        (id, event_id, disposition, reason, run_id, timestamp)
+      VALUES (?, ?, ?, ?, ?, ?)
+    `);
+        const countAuditsForRuns = this.db.prepare(`
+      WITH requested_runs(run_id) AS (
+        SELECT DISTINCT value FROM json_each(?)
+      )
+      SELECT audit.disposition, COUNT(*) AS count
+      FROM event_processing_audit audit
+      INNER JOIN requested_runs requested ON requested.run_id = audit.run_id
+      GROUP BY audit.disposition
+    `);
+        return this.db.transaction(() => {
+            const reconciledAt = Date.now();
+            const groups = [];
+            for (const turn of orderedTurns) {
+                const current = groups.at(-1);
+                if (current?.[0]?.createdAt === turn.createdAt)
+                    current.push(turn);
+                else
+                    groups.push([turn]);
+            }
+            let processedThisRun = 0;
+            let discardedThisRun = 0;
+            let decidedTurnCount = 0;
+            let eventIndex = 0;
+            const canonicalRunIds = [];
+            const events = selectSessionEvents.all(normalizedSessionId);
+            for (let groupIndex = 0; groupIndex < groups.length; groupIndex += 1) {
+                const group = groups[groupIndex];
+                const windowStart = group[0].createdAt;
+                const windowEnd = Math.min(groups[groupIndex + 1]?.[0]?.createdAt ?? sessionEndAt, sessionEndAt);
+                while (eventIndex < events.length && events[eventIndex].created_at < windowStart)
+                    eventIndex += 1;
+                if (windowStart >= windowEnd)
+                    continue;
+                const allCanonical = group.every(turn => turn.status !== 'pending' && turn.receiptId?.startsWith('memory-receipt:'));
+                const allCommitted = allCanonical && group.every(turn => turn.status === 'committed');
+                const allSkipped = allCanonical && group.every(turn => turn.status === 'skipped');
+                const disposition = allCommitted ? 'processed' : allSkipped ? 'discarded' : null;
+                const canonicalGroup = disposition
+                    ? group.map(turn => `${turn.turnId}=${turn.receiptId}`).join(',')
+                    : '';
+                const reason = disposition
+                    ? `canonical_turn_group_${allCommitted ? 'committed' : 'skipped'}:${windowStart}:${canonicalGroup}`
+                    : '';
+                const runId = disposition
+                    ? `turn-reconcile:${createHash('sha256')
+                        .update(`${normalizedSessionId}\0${windowStart}\0${allCommitted ? 'committed' : 'skipped'}\0${canonicalGroup}`)
+                        .digest('hex').slice(0, 32)}`
+                    : '';
+                if (disposition) {
+                    decidedTurnCount += group.length;
+                    canonicalRunIds.push(runId);
+                }
+                while (eventIndex < events.length && events[eventIndex].created_at < windowEnd) {
+                    const event = events[eventIndex++];
+                    if (!disposition)
+                        continue;
+                    const changed = disposition === 'processed'
+                        ? markCommitted.run(event.id, normalizedSessionId).changes
+                        : markSkipped.run(reason, event.id, normalizedSessionId).changes;
+                    if (changed === 0)
+                        continue;
+                    if (disposition === 'processed')
+                        processedThisRun += changed;
+                    else
+                        discardedThisRun += changed;
+                    insertAudit.run(`epa:${reconciledAt}:${randomUUID().slice(0, 8)}`, event.id, disposition, reason, runId, reconciledAt);
+                }
+            }
+            const historicalCounts = canonicalRunIds.length > 0
+                ? countAuditsForRuns.all(JSON.stringify(canonicalRunIds))
+                : [];
+            const countByDisposition = new Map(historicalCounts.map(row => [row.disposition, Number(row.count)]));
+            return {
+                sessionId: normalizedSessionId,
+                turnCount: orderedTurns.length,
+                decidedTurnCount,
+                committedProcessed: countByDisposition.get('processed') ?? 0,
+                skippedDiscarded: countByDisposition.get('discarded') ?? 0,
+                remainingUndecided: events.length - processedThisRun - discardedThisRun,
+            };
+        })();
+    }
     getUnprocessedEvents() {
         const events = this.db.prepare(`SELECT * FROM session_events
        WHERE processed = 0 AND maintenance_status = 'active'
@@ -873,9 +1244,18 @@ export class MemoryStore {
         (id, session_id, project, type, title, narrative, facts, files, tools, concepts,
          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');
+         failure_category, resolution_state, evidence_status, evidence_details)
+      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', obs.evidenceStatus
+            ?? (obs.source === 'explicit_intent'
+                ? 'unverified'
+                : obs.source === 'manual' || (obs.sourceEventIds?.length ?? 0) > 0
+                    ? 'verified'
+                    : 'unverified'), JSON.stringify(obs.evidenceDetails ?? (obs.sourceEventIds ?? []).map(source => ({
+            kind: 'source_event',
+            source,
+            summary: 'Observation was accepted from an evidence-bound session event.',
+        }))));
         // 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 (?, ?)');
@@ -895,6 +1275,197 @@ export class MemoryStore {
             return this.getObservation(row.id);
         })();
     }
+    acceptExplicitPreference(input) {
+        return this.db.transaction(() => {
+            this.ensureSession(input.sessionId, input.project);
+            const latest = this.db.prepare(`
+        SELECT MAX(COALESCE(explicit_accepted_at, timestamp)) AS latest
+        FROM observations
+        WHERE project = ? AND type IN ('user_preference', 'project_convention', 'decision_made')
+          AND source = 'explicit_intent'
+      `).get(input.project);
+            const acceptedAt = Math.max(Date.now(), (latest.latest ?? 0) + 1);
+            const dedupKey = observationDedupKey('user_preference', input.title);
+            const exact = this.db.prepare('SELECT * FROM observations WHERE dedup_key = ? AND project = ?').get(dedupKey, input.project) ?? null;
+            let row;
+            if (exact) {
+                const contentChanged = exact.title !== input.title || exact.narrative !== input.content;
+                const sourceEventIds = new Set(parseStringArray(exact.source_event_ids));
+                if (input.sourceEventId)
+                    sourceEventIds.add(input.sourceEventId);
+                this.db.prepare(`
+          UPDATE observations
+          SET title = ?, narrative = ?, source = 'explicit_intent',
+            confidence = MAX(confidence, 0.95),
+            importance = MAX(importance, 10), quality_status = 'accepted',
+            quarantine_reason = NULL, quality_details = NULL, quarantined_at = NULL,
+            resolution_state = 'current', superseded_by_observation = NULL,
+            source_event_ids = ?, updated_at = ?, explicit_accepted_at = ?,
+            embedding = CASE WHEN ? = 1 THEN NULL ELSE embedding END
+          WHERE id = ?
+        `).run(input.title, input.content, JSON.stringify([...sourceEventIds]), acceptedAt, acceptedAt, contentChanged ? 1 : 0, exact.id);
+                if (contentChanged) {
+                    this.db.prepare("DELETE FROM embeddings WHERE source_type = 'observation' AND source_id = ?").run(exact.id);
+                }
+                this.incrementObservationAccess(exact.id, acceptedAt);
+                row = this.getObservation(exact.id);
+            }
+            else {
+                row = this.addObservation({
+                    sessionId: input.sessionId,
+                    project: input.project,
+                    type: 'user_preference',
+                    title: input.title,
+                    narrative: input.content,
+                    importance: 10,
+                    confidence: 0.95,
+                    source: 'explicit_intent',
+                    sourceEventIds: input.sourceEventId ? [input.sourceEventId] : [],
+                    timestamp: acceptedAt,
+                    qualityStatus: 'accepted',
+                });
+                this.db.prepare('UPDATE observations SET explicit_accepted_at = ? WHERE id = ?').run(acceptedAt, row.id);
+                row = this.getObservation(row.id);
+            }
+            this.supersedeConflictingExplicitPreferences(row, analyzePreference(input.content));
+            if (input.sourceEventId)
+                this.markEventsProcessed([input.sourceEventId]);
+            return this.getObservation(row.id);
+        })();
+    }
+    applyExplicitMemoryEnrichment(observationId, enrichment) {
+        return this.db.transaction(() => {
+            const current = this.getObservation(observationId);
+            if (!current)
+                throw new Error(`Observation ${observationId} not found`);
+            if (current.source !== 'explicit_intent') {
+                throw new Error(`Observation ${observationId} is not an explicit memory`);
+            }
+            const dedupKey = observationDedupKey(enrichment.type, enrichment.title);
+            const collisions = this.db.prepare(`
+        SELECT id, timestamp, explicit_accepted_at FROM observations
+        WHERE project = ? AND dedup_key = ? AND id <> ?
+      `).all(current.project, dedupKey, observationId);
+            let dedupKeyForCurrent = dedupKey;
+            if (collisions.length > 0) {
+                const candidates = [
+                    {
+                        id: current.id,
+                        timestamp: current.timestamp,
+                        explicit_accepted_at: current.explicit_accepted_at,
+                    },
+                    ...collisions,
+                ].sort((left, right) => (right.explicit_accepted_at ?? right.timestamp) - (left.explicit_accepted_at ?? left.timestamp)
+                    || right.id.localeCompare(left.id));
+                const winner = candidates[0];
+                const now = Date.now();
+                const supersede = this.db.prepare(`
+          UPDATE observations
+          SET resolution_state = 'superseded', superseded_by_observation = ?,
+            dedup_key = NULL, updated_at = ?
+          WHERE id = ?
+        `);
+                for (const candidate of candidates.slice(1)) {
+                    supersede.run(winner.id, now, candidate.id);
+                }
+                this.db.prepare(`
+          UPDATE observations
+          SET resolution_state = 'current', superseded_by_observation = NULL,
+            dedup_key = ?, updated_at = ?
+          WHERE id = ?
+        `).run(dedupKey, now, winner.id);
+                dedupKeyForCurrent = winner.id === current.id ? dedupKey : null;
+            }
+            const nextFacts = JSON.stringify(enrichment.facts);
+            const nextFiles = JSON.stringify(enrichment.files);
+            const nextTools = JSON.stringify(enrichment.tools);
+            const nextConcepts = JSON.stringify(enrichment.concepts);
+            const semanticContentChanged = current.type !== enrichment.type
+                || current.title !== enrichment.title
+                || current.narrative !== enrichment.narrative
+                || current.facts !== nextFacts
+                || current.concepts !== nextConcepts;
+            const now = Date.now();
+            this.db.prepare(`
+        UPDATE observations
+        SET type = ?, title = ?, narrative = ?, facts = ?, files = ?, tools = ?, concepts = ?,
+          dedup_key = ?, evidence_status = ?, evidence_details = ?, updated_at = ?,
+          embedding = CASE WHEN ? = 1 THEN NULL ELSE embedding END
+        WHERE id = ?
+      `).run(enrichment.type, enrichment.title, enrichment.narrative, nextFacts, nextFiles, nextTools, nextConcepts, dedupKeyForCurrent, enrichment.evidenceStatus, JSON.stringify(enrichment.evidence), now, semanticContentChanged ? 1 : 0, observationId);
+            if (semanticContentChanged) {
+                this.db.prepare("DELETE FROM embeddings WHERE source_type = 'observation' AND source_id = ?").run(observationId);
+            }
+            this.db.prepare('DELETE FROM observation_concepts WHERE observation_id = ?').run(observationId);
+            const insertConcept = this.db.prepare('INSERT OR IGNORE INTO observation_concepts (observation_id, concept) VALUES (?, ?)');
+            for (const concept of enrichment.concepts)
+                insertConcept.run(observationId, concept);
+            this.reconcileExplicitPreferenceConflicts(current.project);
+            return this.getObservation(observationId);
+        })();
+    }
+    reconcileExplicitPreferenceConflicts(project = this.defaultProjectRoot) {
+        return this.db.transaction(() => {
+            const rows = this.listCurrentExplicitPreferences(project).sort((left, right) => this.explicitPreferenceAcceptanceTime(left)
+                - this.explicitPreferenceAcceptanceTime(right)
+                || left.timestamp - right.timestamp
+                || left.id.localeCompare(right.id));
+            let superseded = 0;
+            const active = [];
+            for (const row of rows) {
+                const analysis = analyzePreferenceObservation(row);
+                if (analysis.status !== 'high_confidence') {
+                    active.push({ row, analysis });
+                    continue;
+                }
+                for (let index = active.length - 1; index >= 0; index--) {
+                    const previous = active[index];
+                    if (!analysesConflict(previous.analysis, analysis))
+                        continue;
+                    this.db.prepare(`
+            UPDATE observations
+            SET resolution_state = 'superseded', superseded_by_observation = ?
+            WHERE id = ? AND resolution_state = 'current'
+          `).run(row.id, previous.row.id);
+                    active.splice(index, 1);
+                    superseded += 1;
+                }
+                active.push({ row, analysis });
+            }
+            return superseded;
+        })();
+    }
+    listCurrentExplicitPreferences(project = this.defaultProjectRoot) {
+        return this.db.prepare(`
+      SELECT * FROM observations
+      WHERE project = ? AND type IN ('user_preference', 'project_convention', 'decision_made')
+        AND source = 'explicit_intent'
+        AND quality_status = 'accepted' AND resolution_state = 'current'
+      ORDER BY COALESCE(explicit_accepted_at, timestamp) DESC, timestamp DESC, id DESC
+    `).all(project);
+    }
+    explicitPreferenceAcceptanceTime(row) {
+        return row.explicit_accepted_at ?? row.timestamp;
+    }
+    supersedeConflictingExplicitPreferences(winner, winnerAnalysis) {
+        if (winnerAnalysis.status !== 'high_confidence')
+            return 0;
+        const update = this.db.prepare(`
+      UPDATE observations
+      SET resolution_state = 'superseded', superseded_by_observation = ?
+      WHERE id = ? AND resolution_state = 'current'
+    `);
+        let superseded = 0;
+        for (const candidate of this.listCurrentExplicitPreferences(winner.project)) {
+            if (candidate.id === winner.id)
+                continue;
+            const analysis = analyzePreferenceObservation(candidate);
+            if (!analysesConflict(analysis, winnerAnalysis))
+                continue;
+            superseded += update.run(winner.id, candidate.id).changes;
+        }
+        return superseded;
+    }
     getObservation(id) {
         return this.db.prepare('SELECT * FROM observations WHERE id = ?').get(id) ?? null;
     }
@@ -935,7 +1506,7 @@ export class MemoryStore {
         this.recordRetrievalAccess({
             sourceType: 'observation',
             sourceId: id,
-            accessType: 'operational',
+            accessType: 'adopted',
             purpose: 'dedup_or_reinforcement',
             timestamp: now,
         });
@@ -1125,7 +1696,9 @@ export class MemoryStore {
         const timestamp = input.timestamp ?? Date.now();
         const id = `racc:${timestamp}:${randomUUID().slice(0, 8)}`;
         this.db.transaction(() => {
-            if (input.sourceType === 'memory') {
+            const accessType = input.accessType ?? 'exposed';
+            const reinforces = accessType === 'adopted';
+            if (input.sourceType === 'memory' && reinforces) {
                 const updated = this.db.prepare(`
           UPDATE memories SET access_count = access_count + 1,
             last_reinforced_at = COALESCE(last_reinforced_at, ?),
@@ -1134,17 +1707,13 @@ export class MemoryStore {
         `).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);
+        `).run(`acc:${timestamp}:${randomUUID().slice(0, 8)}`, input.sourceId, 'agent_use', input.sessionId ?? null, timestamp, input.query ?? null, input.purpose ?? null, input.rank ?? null, input.score ?? null);
             }
-            else {
+            else if (input.sourceType === 'observation' && reinforces) {
                 const updated = this.db.prepare(`
           UPDATE observations
           SET access_count = access_count + 1, updated_at = ?
@@ -1155,9 +1724,10 @@ export class MemoryStore {
             }
             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);
+          (id, source_type, source_id, access_type, project, session_id, request_id,
+           execution_id, query, purpose, rank, score, timestamp)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      `).run(id, input.sourceType, input.sourceId, accessType, input.project ?? this.defaultProjectRoot, input.sessionId ?? null, input.requestId ?? null, input.executionId ?? null, input.query ?? null, input.purpose ?? null, input.rank ?? null, input.score ?? null, timestamp);
         })();
     }
     recordAccess(memoryId, accessType, sessionId) {
@@ -1172,7 +1742,7 @@ export class MemoryStore {
         this.recordRetrievalAccess({
             sourceType: 'memory',
             sourceId: id,
-            accessType: 'agent_use',
+            accessType: 'adopted',
             purpose: 'reinforcement',
         });
     }
@@ -1181,6 +1751,15 @@ export class MemoryStore {
       SELECT * FROM retrieval_access_log ORDER BY timestamp DESC, id DESC LIMIT ?
     `).all(limit);
     }
+    listRetrievalAccessForAttribution(sessionId, executionId) {
+        return this.db.prepare(`
+      SELECT * FROM retrieval_access_log
+      WHERE session_id = ? AND access_type = 'selected'
+        AND (? IS NULL OR execution_id = ?)
+      ORDER BY timestamp DESC, id DESC
+      LIMIT 500
+    `).all(sessionId, executionId ?? null, executionId ?? null);
+    }
     // ── Memory History ───────────────────────────────
     recordHistory(entry) {
         const id = `hist:${Date.now()}:${randomUUID().slice(0, 8)}`;