audrey 0.14.0 → 0.15.0

package/mcp-server/config.js

@@ -1,7 +1,7 @@
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 
-export const VERSION = '0.14.0';
+export const VERSION = '0.15.0';
 export const SERVER_NAME = 'audrey-memory';
 export const DEFAULT_DATA_DIR = join(homedir(), '.audrey', 'data');
 

package/mcp-server/index.js

@@ -63,11 +63,8 @@ function install() {
     process.exit(1);
   }
 
-  if (process.env.OPENAI_API_KEY) {
-    console.log('Detected OPENAI_API_KEY — using OpenAI embeddings (1536d)');
-  } else {
-    console.log('No OPENAI_API_KEY found — using mock embeddings (upgrade anytime by re-running with the key set)');
-  }
+  const embedding = resolveEmbeddingProvider(process.env);
+  console.log(`Embedding: ${embedding.provider} (${embedding.dimensions}d)`);
 
   if (process.env.ANTHROPIC_API_KEY) {
     console.log('Detected ANTHROPIC_API_KEY — enabling LLM-powered consolidation + contradiction detection');
@@ -199,11 +196,12 @@ async function main() {
         arousal: z.number().min(0).max(1).optional().describe('Emotional arousal: 0 (calm) to 1 (highly activated)'),
         label: z.string().optional().describe('Human-readable emotion label (e.g., "curiosity", "frustration", "relief")'),
       }).optional().describe('Emotional affect — how this memory feels'),
-      private: z.boolean().optional().describe('If true, memory is only visible to the AI � excluded from public recall results'),
+      private: z.boolean().optional().describe('If true, memory is only visible to the AI — excluded from public recall results'),
+      auto_supersede: z.boolean().optional().describe('If true, automatically supersede the most similar existing memory if similarity > 0.95'),
     },
-    async ({ content, source, tags, salience, private: isPrivate, context, affect }) => {
+    async ({ content, source, tags, salience, private: isPrivate, context, affect, auto_supersede }) => {
       try {
-        const id = await audrey.encode({ content, source, tags, salience, private: isPrivate, context, affect });
+        const id = await audrey.encode({ content, source, tags, salience, private: isPrivate, context, affect, autoSupersede: auto_supersede });
         return toolResult({ id, content, source, private: isPrivate ?? false });
       } catch (err) {
         return toolError(err);
@@ -411,6 +409,27 @@ async function main() {
     },
   );
 
+  server.tool(
+    'memory_dream',
+    {
+      min_cluster_size: z.number().optional().describe('Minimum episodes per cluster for consolidation'),
+      similarity_threshold: z.number().optional().describe('Similarity threshold for clustering'),
+      dormant_threshold: z.number().min(0).max(1).optional().describe('Confidence below which memories go dormant'),
+    },
+    async ({ min_cluster_size, similarity_threshold, dormant_threshold }) => {
+      try {
+        const result = await audrey.dream({
+          minClusterSize: min_cluster_size,
+          similarityThreshold: similarity_threshold,
+          dormantThreshold: dormant_threshold,
+        });
+        return toolResult(result);
+      } catch (err) {
+        return toolError(err);
+      }
+    },
+  );
+
   server.tool(
     'memory_greeting',
     {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "audrey",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "description": "Biological memory architecture for AI agents — encode, consolidate, and recall memories with confidence decay, contradiction detection, and causal graphs",
   "type": "module",
   "main": "src/index.js",

package/src/audrey.js

@@ -193,7 +193,10 @@ export class Audrey extends EventEmitter {
    */
   async encode(params) {
     await this._ensureMigrated();
-    const encodeParams = { ...params, arousalWeight: this.affectConfig.arousalWeight };
+    const encodeParams = {
+      ...params,
+      arousalWeight: this.affectConfig.arousalWeight,
+    };
     const id = await encodeEpisode(this.db, this.embeddingProvider, encodeParams);
     this.emit('encode', { id, ...params });
     if (this.interferenceConfig.enabled) {
@@ -503,7 +506,47 @@ export class Audrey extends EventEmitter {
       };
     }
 
-    const result = { recent, principles, mood, unresolved, identity };
+    // Health & staleness
+    const stats = this.introspect();
+    const status = this.memoryStatus();
+
+    const lastConsolidation = stats.lastConsolidation;
+    const daysSinceConsolidation = lastConsolidation
+      ? (Date.now() - new Date(lastConsolidation).getTime()) / (1000 * 60 * 60 * 24)
+      : null;
+
+    const lastEpisode = this.db.prepare(
+      'SELECT created_at FROM episodes ORDER BY created_at DESC LIMIT 1'
+    ).get();
+    const daysSinceLastMemory = lastEpisode
+      ? (Date.now() - new Date(lastEpisode.created_at).getTime()) / (1000 * 60 * 60 * 24)
+      : null;
+
+    const suggestions = [];
+    if (stats.episodic > 50 && stats.totalConsolidationRuns === 0) {
+      suggestions.push('run consolidation — enough episodes have accumulated');
+    }
+    if (daysSinceConsolidation !== null && daysSinceConsolidation > 7) {
+      suggestions.push('consolidation overdue — consider running dream()');
+    }
+    if (!status.healthy) {
+      suggestions.push('vector tables out of sync — run reembed');
+    }
+
+    const health = {
+      totalEpisodes: stats.episodic,
+      totalSemantics: stats.semantic,
+      totalProcedural: stats.procedural,
+      dormant: stats.dormant,
+      contradictions: stats.contradictions.open,
+      consolidationRuns: stats.totalConsolidationRuns,
+      lastConsolidation,
+      healthy: status.healthy,
+      stale: daysSinceLastMemory !== null && daysSinceLastMemory > 7,
+      suggestion: suggestions.length > 0 ? suggestions.join('; ') : null,
+    };
+
+    const result = { recent, principles, mood, unresolved, identity, health };
 
     if (context) {
       result.contextual = await this.recall(context, { limit: 5, includePrivate: true });
@@ -512,6 +555,40 @@ export class Audrey extends EventEmitter {
     return result;
   }
 
+  /**
+   * Run a full "dreaming" cycle: consolidation + decay + interference cleanup.
+   * Inspired by CMA paper's REM-like replay. Designed to be called by hooks or on a schedule.
+   * @param {{ minClusterSize?: number, similarityThreshold?: number, dormantThreshold?: number }} [options]
+   * @returns {Promise<{ consolidated: ConsolidationResult, decayed: { totalEvaluated: number, transitionedToDormant: number }, summary: string }>}
+   */
+  async dream(options = {}) {
+    await this._ensureMigrated();
+
+    const consolidated = await this.consolidate({
+      minClusterSize: options.minClusterSize,
+      similarityThreshold: options.similarityThreshold,
+    });
+
+    const decayed = this.decay({
+      dormantThreshold: options.dormantThreshold,
+    });
+
+    const parts = [];
+    if (consolidated.principlesExtracted > 0) {
+      parts.push(`extracted ${consolidated.principlesExtracted} principles from ${consolidated.clustersFound} clusters`);
+    }
+    if (decayed.transitionedToDormant > 0) {
+      parts.push(`${decayed.transitionedToDormant} memories went dormant`);
+    }
+    if (parts.length === 0) {
+      parts.push('nothing changed — memories are well-maintained');
+    }
+
+    const result = { consolidated, decayed, summary: parts.join('; ') };
+    this.emit('dream', result);
+    return result;
+  }
+
   export() {
     return exportMemories(this.db);
   }

package/src/db.js

@@ -1,333 +1,333 @@
-import Database from 'better-sqlite3';
-import * as sqliteVec from 'sqlite-vec';
-import { join } from 'node:path';
-import { mkdirSync, existsSync } from 'node:fs';
-
-const SCHEMA = `
-  CREATE TABLE IF NOT EXISTS episodes (
-    id TEXT PRIMARY KEY,
-    content TEXT NOT NULL,
-    embedding BLOB,
-    source TEXT NOT NULL CHECK(source IN ('direct-observation','told-by-user','tool-result','inference','model-generated')),
-    source_reliability REAL NOT NULL,
-    salience REAL DEFAULT 0.5,
-    context TEXT DEFAULT '{}',
-    affect TEXT DEFAULT '{}',
-    tags TEXT,
-    causal_trigger TEXT,
-    causal_consequence TEXT,
-    created_at TEXT NOT NULL,
-    embedding_model TEXT,
-    embedding_version TEXT,
-    supersedes TEXT,
-    superseded_by TEXT,
-    consolidated INTEGER DEFAULT 0,
-    private INTEGER DEFAULT 0,
-    FOREIGN KEY (supersedes) REFERENCES episodes(id)
-  );
-
-  CREATE TABLE IF NOT EXISTS semantics (
-    id TEXT PRIMARY KEY,
-    content TEXT NOT NULL,
-    embedding BLOB,
-    state TEXT DEFAULT 'active' CHECK(state IN ('active','disputed','superseded','context_dependent','dormant','rolled_back')),
-    conditions TEXT,
-    evidence_episode_ids TEXT,
-    evidence_count INTEGER DEFAULT 0,
-    supporting_count INTEGER DEFAULT 0,
-    contradicting_count INTEGER DEFAULT 0,
-    source_type_diversity INTEGER DEFAULT 0,
-    consolidation_checkpoint TEXT,
-    embedding_model TEXT,
-    embedding_version TEXT,
-    consolidation_model TEXT,
-    consolidation_prompt_hash TEXT,
-    created_at TEXT NOT NULL,
-    last_reinforced_at TEXT,
-    retrieval_count INTEGER DEFAULT 0,
-    challenge_count INTEGER DEFAULT 0,
-    interference_count INTEGER DEFAULT 0,
-    salience REAL DEFAULT 0.5
-  );
-
-  CREATE TABLE IF NOT EXISTS procedures (
-    id TEXT PRIMARY KEY,
-    content TEXT NOT NULL,
-    embedding BLOB,
-    state TEXT DEFAULT 'active' CHECK(state IN ('active','disputed','superseded','context_dependent','dormant','rolled_back')),
-    trigger_conditions TEXT,
-    evidence_episode_ids TEXT,
-    success_count INTEGER DEFAULT 0,
-    failure_count INTEGER DEFAULT 0,
-    embedding_model TEXT,
-    embedding_version TEXT,
-    created_at TEXT NOT NULL,
-    last_reinforced_at TEXT,
-    retrieval_count INTEGER DEFAULT 0,
-    interference_count INTEGER DEFAULT 0,
-    salience REAL DEFAULT 0.5
-  );
-
-  CREATE TABLE IF NOT EXISTS causal_links (
-    id TEXT PRIMARY KEY,
-    cause_id TEXT NOT NULL,
-    effect_id TEXT NOT NULL,
-    link_type TEXT DEFAULT 'causal' CHECK(link_type IN ('causal','correlational','temporal')),
-    mechanism TEXT,
-    confidence REAL,
-    evidence_count INTEGER DEFAULT 1,
-    created_at TEXT NOT NULL
-  );
-
-  CREATE TABLE IF NOT EXISTS contradictions (
-    id TEXT PRIMARY KEY,
-    claim_a_id TEXT NOT NULL,
-    claim_b_id TEXT NOT NULL,
-    claim_a_type TEXT NOT NULL,
-    claim_b_type TEXT NOT NULL,
-    state TEXT DEFAULT 'open' CHECK(state IN ('open','resolved','context_dependent','reopened')),
-    resolution TEXT,
-    resolved_at TEXT,
-    reopened_at TEXT,
-    reopen_evidence_id TEXT,
-    created_at TEXT NOT NULL
-  );
-
-  CREATE TABLE IF NOT EXISTS consolidation_runs (
-    id TEXT PRIMARY KEY,
-    checkpoint_cursor TEXT,
-    input_episode_ids TEXT,
-    output_memory_ids TEXT,
-    confidence_deltas TEXT,
-    consolidation_model TEXT,
-    consolidation_prompt_hash TEXT,
-    started_at TEXT,
-    completed_at TEXT,
-    status TEXT DEFAULT 'running' CHECK(status IN ('running','completed','failed','rolled_back'))
-  );
-
-  CREATE TABLE IF NOT EXISTS audrey_config (
-    key TEXT PRIMARY KEY,
-    value TEXT NOT NULL
-  );
-
-  CREATE TABLE IF NOT EXISTS consolidation_metrics (
-    id TEXT PRIMARY KEY,
-    run_id TEXT NOT NULL,
-    min_cluster_size INTEGER NOT NULL,
-    similarity_threshold REAL NOT NULL,
-    episodes_evaluated INTEGER NOT NULL,
-    clusters_found INTEGER NOT NULL,
-    principles_extracted INTEGER NOT NULL,
-    created_at TEXT NOT NULL,
-    FOREIGN KEY (run_id) REFERENCES consolidation_runs(id)
-  );
-
-  CREATE INDEX IF NOT EXISTS idx_episodes_created ON episodes(created_at);
-  CREATE INDEX IF NOT EXISTS idx_episodes_consolidated ON episodes(consolidated);
-  CREATE INDEX IF NOT EXISTS idx_episodes_source ON episodes(source);
-  CREATE INDEX IF NOT EXISTS idx_semantics_state ON semantics(state);
-  CREATE INDEX IF NOT EXISTS idx_procedures_state ON procedures(state);
-  CREATE INDEX IF NOT EXISTS idx_contradictions_state ON contradictions(state);
-  CREATE INDEX IF NOT EXISTS idx_consolidation_status ON consolidation_runs(status);
-`;
-
-export function createVec0Tables(db, dimensions) {
-  db.exec(`
-    CREATE VIRTUAL TABLE IF NOT EXISTS vec_episodes USING vec0(
-      id text primary key,
-      embedding float[${dimensions}] distance_metric=cosine,
-      source text,
-      consolidated integer
-    );
-  `);
-  db.exec(`
-    CREATE VIRTUAL TABLE IF NOT EXISTS vec_semantics USING vec0(
-      id text primary key,
-      embedding float[${dimensions}] distance_metric=cosine,
-      state text
-    );
-  `);
-  db.exec(`
-    CREATE VIRTUAL TABLE IF NOT EXISTS vec_procedures USING vec0(
-      id text primary key,
-      embedding float[${dimensions}] distance_metric=cosine,
-      state text
-    );
-  `);
-}
-
-export function dropVec0Tables(db) {
-  db.exec('DROP TABLE IF EXISTS vec_episodes');
-  db.exec('DROP TABLE IF EXISTS vec_semantics');
-  db.exec('DROP TABLE IF EXISTS vec_procedures');
-}
-
-function migrateTable(db, { source, target, selectCols, insertCols, placeholders, transform, dimensions }) {
-  const count = db.prepare(`SELECT COUNT(*) as c FROM ${target}`).get().c;
-  if (count > 0) return;
-
-  const rows = db.prepare(`SELECT ${selectCols} FROM ${source} WHERE embedding IS NOT NULL`).all();
-  if (rows.length === 0) return;
-
-  const expectedBytes = dimensions ? dimensions * 4 : null;
-  const insert = db.prepare(`INSERT INTO ${target}(${insertCols}) VALUES (${placeholders})`);
-  const tx = db.transaction(() => {
-    for (const row of rows) {
-      if (expectedBytes && row.embedding.byteLength !== expectedBytes) continue;
-      insert.run(...transform(row));
-    }
-  });
-  tx();
-}
-
-function migrateEmbeddingsToVec0(db, dimensions) {
-  migrateTable(db, {
-    source: 'episodes',
-    target: 'vec_episodes',
-    selectCols: 'id, embedding, source, consolidated',
-    insertCols: 'id, embedding, source, consolidated',
-    placeholders: '?, ?, ?, ?',
-    transform: (row) => [row.id, row.embedding, row.source, BigInt(row.consolidated ?? 0)],
-    dimensions,
-  });
-
-  migrateTable(db, {
-    source: 'semantics',
-    target: 'vec_semantics',
-    selectCols: 'id, embedding, state',
-    insertCols: 'id, embedding, state',
-    placeholders: '?, ?, ?',
-    transform: (row) => [row.id, row.embedding, row.state],
-    dimensions,
-  });
-
-  migrateTable(db, {
-    source: 'procedures',
-    target: 'vec_procedures',
-    selectCols: 'id, embedding, state',
-    insertCols: 'id, embedding, state',
-    placeholders: '?, ?, ?',
-    transform: (row) => [row.id, row.embedding, row.state],
-    dimensions,
-  });
-}
-
-function addColumnIfMissing(db, table, column, definition) {
-  const columns = db.pragma(`table_info(${table})`);
-  const exists = columns.some(col => col.name === column);
-  if (!exists) {
-    db.exec(`ALTER TABLE ${table} ADD COLUMN ${column} ${definition}`);
-  }
-}
-
-const SCHEMA_VERSION = 7;
-
-const MIGRATIONS = [
-  { version: 1, up(db) { addColumnIfMissing(db, 'episodes', 'context', "TEXT DEFAULT '{}'"); } },
-  { version: 2, up(db) { addColumnIfMissing(db, 'episodes', 'affect', "TEXT DEFAULT '{}'"); } },
-  { version: 3, up(db) { addColumnIfMissing(db, 'semantics', 'interference_count', 'INTEGER DEFAULT 0'); } },
-  { version: 4, up(db) { addColumnIfMissing(db, 'semantics', 'salience', 'REAL DEFAULT 0.5'); } },
-  { version: 5, up(db) { addColumnIfMissing(db, 'procedures', 'interference_count', 'INTEGER DEFAULT 0'); } },
-  { version: 6, up(db) { addColumnIfMissing(db, 'procedures', 'salience', 'REAL DEFAULT 0.5'); } },
-  { version: 7, up(db) { addColumnIfMissing(db, 'episodes', 'private', 'INTEGER DEFAULT 0'); } },
-];
-
-function runMigrations(db) {
-  const row = db.prepare("SELECT value FROM audrey_config WHERE key = 'schema_version'").get();
-  const currentVersion = row ? Number(row.value) : 0;
-
-  if (currentVersion >= SCHEMA_VERSION) return;
-
-  const pending = MIGRATIONS.filter(m => m.version > currentVersion);
-  for (const migration of pending) {
-    migration.up(db);
-  }
-
-  db.prepare(
-    `INSERT INTO audrey_config (key, value) VALUES ('schema_version', ?)
-     ON CONFLICT(key) DO UPDATE SET value = excluded.value`
-  ).run(String(SCHEMA_VERSION));
-}
-
-/**
- * @param {string} dataDir
- * @param {{ dimensions?: number }} [options]
- * @returns {{ db: import('better-sqlite3').Database, migrated: boolean }}
- */
-export function createDatabase(dataDir, options = {}) {
-  let { dimensions } = options;
-  let migrated = false;
-
-  mkdirSync(dataDir, { recursive: true });
-  const dbPath = join(dataDir, 'audrey.db');
-  const db = new Database(dbPath);
-  db.pragma('journal_mode = WAL');
-  db.pragma('foreign_keys = ON');
-  db.pragma('busy_timeout = 5000');
-  db.exec(SCHEMA);
-  runMigrations(db);
-
-  if (dimensions == null) {
-    const stored = db.prepare("SELECT value FROM audrey_config WHERE key = 'dimensions'").get();
-    if (stored) {
-      dimensions = parseInt(stored.value, 10);
-    }
-  }
-
-  if (dimensions != null) {
-    if (!Number.isInteger(dimensions) || dimensions <= 0) {
-      throw new Error(`dimensions must be a positive integer, got: ${dimensions}`);
-    }
-
-    sqliteVec.load(db);
-
-    const existing = db.prepare(
-      "SELECT value FROM audrey_config WHERE key = 'dimensions'"
-    ).get();
-
-    if (existing) {
-      const storedDims = parseInt(existing.value, 10);
-      if (storedDims !== dimensions) {
-        dropVec0Tables(db);
-        db.prepare(
-          "UPDATE audrey_config SET value = ? WHERE key = 'dimensions'"
-        ).run(String(dimensions));
-        migrated = true;
-      }
-    } else {
-      db.prepare(
-        "INSERT INTO audrey_config (key, value) VALUES ('dimensions', ?)"
-      ).run(String(dimensions));
-    }
-
-    createVec0Tables(db, dimensions);
-
-    if (!migrated) {
-      migrateEmbeddingsToVec0(db, dimensions);
-    }
-  }
-
-  return { db, migrated };
-}
-
-export function readStoredDimensions(dataDir) {
-  const dbPath = join(dataDir, 'audrey.db');
-  if (!existsSync(dbPath)) return null;
-  const db = new Database(dbPath, { readonly: true });
-  try {
-    const row = db.prepare("SELECT value FROM audrey_config WHERE key = 'dimensions'").get();
-    return row ? parseInt(row.value, 10) : null;
-  } catch (err) {
-    if (err.message?.includes('no such table')) return null;
-    throw err;
-  } finally {
-    db.close();
-  }
-}
-
-export function closeDatabase(db) {
-  if (db && db.open) {
-    db.close();
-  }
-}
+import Database from 'better-sqlite3';
+import * as sqliteVec from 'sqlite-vec';
+import { join } from 'node:path';
+import { mkdirSync, existsSync } from 'node:fs';
+
+const SCHEMA = `
+  CREATE TABLE IF NOT EXISTS episodes (
+    id TEXT PRIMARY KEY,
+    content TEXT NOT NULL,
+    embedding BLOB,
+    source TEXT NOT NULL CHECK(source IN ('direct-observation','told-by-user','tool-result','inference','model-generated')),
+    source_reliability REAL NOT NULL,
+    salience REAL DEFAULT 0.5,
+    context TEXT DEFAULT '{}',
+    affect TEXT DEFAULT '{}',
+    tags TEXT,
+    causal_trigger TEXT,
+    causal_consequence TEXT,
+    created_at TEXT NOT NULL,
+    embedding_model TEXT,
+    embedding_version TEXT,
+    supersedes TEXT,
+    superseded_by TEXT,
+    consolidated INTEGER DEFAULT 0,
+    private INTEGER DEFAULT 0,
+    FOREIGN KEY (supersedes) REFERENCES episodes(id)
+  );
+
+  CREATE TABLE IF NOT EXISTS semantics (
+    id TEXT PRIMARY KEY,
+    content TEXT NOT NULL,
+    embedding BLOB,
+    state TEXT DEFAULT 'active' CHECK(state IN ('active','disputed','superseded','context_dependent','dormant','rolled_back')),
+    conditions TEXT,
+    evidence_episode_ids TEXT,
+    evidence_count INTEGER DEFAULT 0,
+    supporting_count INTEGER DEFAULT 0,
+    contradicting_count INTEGER DEFAULT 0,
+    source_type_diversity INTEGER DEFAULT 0,
+    consolidation_checkpoint TEXT,
+    embedding_model TEXT,
+    embedding_version TEXT,
+    consolidation_model TEXT,
+    consolidation_prompt_hash TEXT,
+    created_at TEXT NOT NULL,
+    last_reinforced_at TEXT,
+    retrieval_count INTEGER DEFAULT 0,
+    challenge_count INTEGER DEFAULT 0,
+    interference_count INTEGER DEFAULT 0,
+    salience REAL DEFAULT 0.5
+  );
+
+  CREATE TABLE IF NOT EXISTS procedures (
+    id TEXT PRIMARY KEY,
+    content TEXT NOT NULL,
+    embedding BLOB,
+    state TEXT DEFAULT 'active' CHECK(state IN ('active','disputed','superseded','context_dependent','dormant','rolled_back')),
+    trigger_conditions TEXT,
+    evidence_episode_ids TEXT,
+    success_count INTEGER DEFAULT 0,
+    failure_count INTEGER DEFAULT 0,
+    embedding_model TEXT,
+    embedding_version TEXT,
+    created_at TEXT NOT NULL,
+    last_reinforced_at TEXT,
+    retrieval_count INTEGER DEFAULT 0,
+    interference_count INTEGER DEFAULT 0,
+    salience REAL DEFAULT 0.5
+  );
+
+  CREATE TABLE IF NOT EXISTS causal_links (
+    id TEXT PRIMARY KEY,
+    cause_id TEXT NOT NULL,
+    effect_id TEXT NOT NULL,
+    link_type TEXT DEFAULT 'causal' CHECK(link_type IN ('causal','correlational','temporal')),
+    mechanism TEXT,
+    confidence REAL,
+    evidence_count INTEGER DEFAULT 1,
+    created_at TEXT NOT NULL
+  );
+
+  CREATE TABLE IF NOT EXISTS contradictions (
+    id TEXT PRIMARY KEY,
+    claim_a_id TEXT NOT NULL,
+    claim_b_id TEXT NOT NULL,
+    claim_a_type TEXT NOT NULL,
+    claim_b_type TEXT NOT NULL,
+    state TEXT DEFAULT 'open' CHECK(state IN ('open','resolved','context_dependent','reopened')),
+    resolution TEXT,
+    resolved_at TEXT,
+    reopened_at TEXT,
+    reopen_evidence_id TEXT,
+    created_at TEXT NOT NULL
+  );
+
+  CREATE TABLE IF NOT EXISTS consolidation_runs (
+    id TEXT PRIMARY KEY,
+    checkpoint_cursor TEXT,
+    input_episode_ids TEXT,
+    output_memory_ids TEXT,
+    confidence_deltas TEXT,
+    consolidation_model TEXT,
+    consolidation_prompt_hash TEXT,
+    started_at TEXT,
+    completed_at TEXT,
+    status TEXT DEFAULT 'running' CHECK(status IN ('running','completed','failed','rolled_back'))
+  );
+
+  CREATE TABLE IF NOT EXISTS audrey_config (
+    key TEXT PRIMARY KEY,
+    value TEXT NOT NULL
+  );
+
+  CREATE TABLE IF NOT EXISTS consolidation_metrics (
+    id TEXT PRIMARY KEY,
+    run_id TEXT NOT NULL,
+    min_cluster_size INTEGER NOT NULL,
+    similarity_threshold REAL NOT NULL,
+    episodes_evaluated INTEGER NOT NULL,
+    clusters_found INTEGER NOT NULL,
+    principles_extracted INTEGER NOT NULL,
+    created_at TEXT NOT NULL,
+    FOREIGN KEY (run_id) REFERENCES consolidation_runs(id)
+  );
+
+  CREATE INDEX IF NOT EXISTS idx_episodes_created ON episodes(created_at);
+  CREATE INDEX IF NOT EXISTS idx_episodes_consolidated ON episodes(consolidated);
+  CREATE INDEX IF NOT EXISTS idx_episodes_source ON episodes(source);
+  CREATE INDEX IF NOT EXISTS idx_semantics_state ON semantics(state);
+  CREATE INDEX IF NOT EXISTS idx_procedures_state ON procedures(state);
+  CREATE INDEX IF NOT EXISTS idx_contradictions_state ON contradictions(state);
+  CREATE INDEX IF NOT EXISTS idx_consolidation_status ON consolidation_runs(status);
+`;
+
+export function createVec0Tables(db, dimensions) {
+  db.exec(`
+    CREATE VIRTUAL TABLE IF NOT EXISTS vec_episodes USING vec0(
+      id text primary key,
+      embedding float[${dimensions}] distance_metric=cosine,
+      source text,
+      consolidated integer
+    );
+  `);
+  db.exec(`
+    CREATE VIRTUAL TABLE IF NOT EXISTS vec_semantics USING vec0(
+      id text primary key,
+      embedding float[${dimensions}] distance_metric=cosine,
+      state text
+    );
+  `);
+  db.exec(`
+    CREATE VIRTUAL TABLE IF NOT EXISTS vec_procedures USING vec0(
+      id text primary key,
+      embedding float[${dimensions}] distance_metric=cosine,
+      state text
+    );
+  `);
+}
+
+export function dropVec0Tables(db) {
+  db.exec('DROP TABLE IF EXISTS vec_episodes');
+  db.exec('DROP TABLE IF EXISTS vec_semantics');
+  db.exec('DROP TABLE IF EXISTS vec_procedures');
+}
+
+function migrateTable(db, { source, target, selectCols, insertCols, placeholders, transform, dimensions }) {
+  const count = db.prepare(`SELECT COUNT(*) as c FROM ${target}`).get().c;
+  if (count > 0) return;
+
+  const rows = db.prepare(`SELECT ${selectCols} FROM ${source} WHERE embedding IS NOT NULL`).all();
+  if (rows.length === 0) return;
+
+  const expectedBytes = dimensions ? dimensions * 4 : null;
+  const insert = db.prepare(`INSERT INTO ${target}(${insertCols}) VALUES (${placeholders})`);
+  const tx = db.transaction(() => {
+    for (const row of rows) {
+      if (expectedBytes && row.embedding.byteLength !== expectedBytes) continue;
+      insert.run(...transform(row));
+    }
+  });
+  tx();
+}
+
+function migrateEmbeddingsToVec0(db, dimensions) {
+  migrateTable(db, {
+    source: 'episodes',
+    target: 'vec_episodes',
+    selectCols: 'id, embedding, source, consolidated',
+    insertCols: 'id, embedding, source, consolidated',
+    placeholders: '?, ?, ?, ?',
+    transform: (row) => [row.id, row.embedding, row.source, BigInt(row.consolidated ?? 0)],
+    dimensions,
+  });
+
+  migrateTable(db, {
+    source: 'semantics',
+    target: 'vec_semantics',
+    selectCols: 'id, embedding, state',
+    insertCols: 'id, embedding, state',
+    placeholders: '?, ?, ?',
+    transform: (row) => [row.id, row.embedding, row.state],
+    dimensions,
+  });
+
+  migrateTable(db, {
+    source: 'procedures',
+    target: 'vec_procedures',
+    selectCols: 'id, embedding, state',
+    insertCols: 'id, embedding, state',
+    placeholders: '?, ?, ?',
+    transform: (row) => [row.id, row.embedding, row.state],
+    dimensions,
+  });
+}
+
+function addColumnIfMissing(db, table, column, definition) {
+  const columns = db.pragma(`table_info(${table})`);
+  const exists = columns.some(col => col.name === column);
+  if (!exists) {
+    db.exec(`ALTER TABLE ${table} ADD COLUMN ${column} ${definition}`);
+  }
+}
+
+const SCHEMA_VERSION = 7;
+
+const MIGRATIONS = [
+  { version: 1, up(db) { addColumnIfMissing(db, 'episodes', 'context', "TEXT DEFAULT '{}'"); } },
+  { version: 2, up(db) { addColumnIfMissing(db, 'episodes', 'affect', "TEXT DEFAULT '{}'"); } },
+  { version: 3, up(db) { addColumnIfMissing(db, 'semantics', 'interference_count', 'INTEGER DEFAULT 0'); } },
+  { version: 4, up(db) { addColumnIfMissing(db, 'semantics', 'salience', 'REAL DEFAULT 0.5'); } },
+  { version: 5, up(db) { addColumnIfMissing(db, 'procedures', 'interference_count', 'INTEGER DEFAULT 0'); } },
+  { version: 6, up(db) { addColumnIfMissing(db, 'procedures', 'salience', 'REAL DEFAULT 0.5'); } },
+  { version: 7, up(db) { addColumnIfMissing(db, 'episodes', 'private', 'INTEGER DEFAULT 0'); } },
+];
+
+function runMigrations(db) {
+  const row = db.prepare("SELECT value FROM audrey_config WHERE key = 'schema_version'").get();
+  const currentVersion = row ? Number(row.value) : 0;
+
+  if (currentVersion >= SCHEMA_VERSION) return;
+
+  const pending = MIGRATIONS.filter(m => m.version > currentVersion);
+  for (const migration of pending) {
+    migration.up(db);
+  }
+
+  db.prepare(
+    `INSERT INTO audrey_config (key, value) VALUES ('schema_version', ?)
+     ON CONFLICT(key) DO UPDATE SET value = excluded.value`
+  ).run(String(SCHEMA_VERSION));
+}
+
+/**
+ * @param {string} dataDir
+ * @param {{ dimensions?: number }} [options]
+ * @returns {{ db: import('better-sqlite3').Database, migrated: boolean }}
+ */
+export function createDatabase(dataDir, options = {}) {
+  let { dimensions } = options;
+  let migrated = false;
+
+  mkdirSync(dataDir, { recursive: true });
+  const dbPath = join(dataDir, 'audrey.db');
+  const db = new Database(dbPath);
+  db.pragma('journal_mode = WAL');
+  db.pragma('foreign_keys = ON');
+  db.pragma('busy_timeout = 5000');
+  db.exec(SCHEMA);
+  runMigrations(db);
+
+  if (dimensions == null) {
+    const stored = db.prepare("SELECT value FROM audrey_config WHERE key = 'dimensions'").get();
+    if (stored) {
+      dimensions = parseInt(stored.value, 10);
+    }
+  }
+
+  if (dimensions != null) {
+    if (!Number.isInteger(dimensions) || dimensions <= 0) {
+      throw new Error(`dimensions must be a positive integer, got: ${dimensions}`);
+    }
+
+    sqliteVec.load(db);
+
+    const existing = db.prepare(
+      "SELECT value FROM audrey_config WHERE key = 'dimensions'"
+    ).get();
+
+    if (existing) {
+      const storedDims = parseInt(existing.value, 10);
+      if (storedDims !== dimensions) {
+        dropVec0Tables(db);
+        db.prepare(
+          "UPDATE audrey_config SET value = ? WHERE key = 'dimensions'"
+        ).run(String(dimensions));
+        migrated = true;
+      }
+    } else {
+      db.prepare(
+        "INSERT INTO audrey_config (key, value) VALUES ('dimensions', ?)"
+      ).run(String(dimensions));
+    }
+
+    createVec0Tables(db, dimensions);
+
+    if (!migrated) {
+      migrateEmbeddingsToVec0(db, dimensions);
+    }
+  }
+
+  return { db, migrated };
+}
+
+export function readStoredDimensions(dataDir) {
+  const dbPath = join(dataDir, 'audrey.db');
+  if (!existsSync(dbPath)) return null;
+  const db = new Database(dbPath, { readonly: true });
+  try {
+    const row = db.prepare("SELECT value FROM audrey_config WHERE key = 'dimensions'").get();
+    return row ? parseInt(row.value, 10) : null;
+  } catch (err) {
+    if (err.message?.includes('no such table')) return null;
+    throw err;
+  } finally {
+    db.close();
+  }
+}
+
+export function closeDatabase(db) {
+  if (db && db.open) {
+    db.close();
+  }
+}

package/src/encode.js

@@ -1,63 +1,85 @@
-import { generateId } from './ulid.js';
-import { sourceReliability } from './confidence.js';
-import { arousalSalienceBoost } from './affect.js';
-
-/**
- * @param {import('better-sqlite3').Database} db
- * @param {import('./embedding.js').EmbeddingProvider} embeddingProvider
- * @param {{ content: string, source: string, salience?: number, causal?: { trigger?: string, consequence?: string }, tags?: string[], supersedes?: string, context?: object, affect?: object, arousalWeight?: number, private?: boolean }} params
- * @returns {Promise<string>}
- */
-export async function encodeEpisode(db, embeddingProvider, {
-  content,
-  source,
-  salience = 0.5,
-  causal,
-  tags,
-  supersedes,
-  context = {},
-  affect = {},
-  arousalWeight = 0.3,
-  private: isPrivate = false,
-}) {
-  if (!content || typeof content !== 'string') throw new Error('content must be a non-empty string');
-  if (salience < 0 || salience > 1) throw new Error('salience must be between 0 and 1');
-  if (tags && !Array.isArray(tags)) throw new Error('tags must be an array');
-
-  const reliability = sourceReliability(source);
-  const vector = await embeddingProvider.embed(content);
-  const embeddingBuffer = embeddingProvider.vectorToBuffer(vector);
-  const id = generateId();
-  const now = new Date().toISOString();
-
-  const boost = arousalSalienceBoost(affect.arousal);
-  const effectiveSalience = Math.min(1.0, salience + (boost * arousalWeight));
-
-  const insertAndLink = db.transaction(() => {
-    db.prepare(`
-      INSERT INTO episodes (
-        id, content, embedding, source, source_reliability, salience, context, affect,
-        tags, causal_trigger, causal_consequence, created_at,
-        embedding_model, embedding_version, supersedes, "private"
-      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-    `).run(
-      id, content, embeddingBuffer, source, reliability, effectiveSalience,
-      JSON.stringify(context),
-      JSON.stringify(affect),
-      tags ? JSON.stringify(tags) : null,
-      causal?.trigger || null, causal?.consequence || null,
-      now, embeddingProvider.modelName, embeddingProvider.modelVersion,
-      supersedes || null,
-      isPrivate ? 1 : 0,
-    );
-    db.prepare(
-      'INSERT INTO vec_episodes(id, embedding, source, consolidated) VALUES (?, ?, ?, ?)'
-    ).run(id, embeddingBuffer, source, BigInt(0));
-    if (supersedes) {
-      db.prepare('UPDATE episodes SET superseded_by = ? WHERE id = ?').run(id, supersedes);
-    }
-  });
-
-  insertAndLink();
-  return id;
-}
+import { generateId } from './ulid.js';
+import { sourceReliability } from './confidence.js';
+import { arousalSalienceBoost } from './affect.js';
+
+/**
+ * @param {import('better-sqlite3').Database} db
+ * @param {import('./embedding.js').EmbeddingProvider} embeddingProvider
+ * @param {{ content: string, source: string, salience?: number, causal?: { trigger?: string, consequence?: string }, tags?: string[], supersedes?: string, context?: object, affect?: object, arousalWeight?: number, private?: boolean }} params
+ * @returns {Promise<string>}
+ */
+export async function encodeEpisode(db, embeddingProvider, {
+  content,
+  source,
+  salience = 0.5,
+  causal,
+  tags,
+  supersedes,
+  autoSupersede = false,
+  autoSupersedeThreshold = 0.95,
+  context = {},
+  affect = {},
+  arousalWeight = 0.3,
+  private: isPrivate = false,
+}) {
+  if (!content || typeof content !== 'string') throw new Error('content must be a non-empty string');
+  if (salience < 0 || salience > 1) throw new Error('salience must be between 0 and 1');
+  if (tags && !Array.isArray(tags)) throw new Error('tags must be an array');
+
+  const reliability = sourceReliability(source);
+  const vector = await embeddingProvider.embed(content);
+  const embeddingBuffer = embeddingProvider.vectorToBuffer(vector);
+
+  // Auto-supersede: find the most similar existing episode and supersede it
+  if (autoSupersede && !supersedes) {
+    try {
+      const match = db.prepare(`
+        SELECT v.id, (1.0 - v.distance) AS similarity
+        FROM vec_episodes v
+        JOIN episodes e ON e.id = v.id
+        WHERE v.embedding MATCH ?
+          AND k = 1
+          AND e.superseded_by IS NULL
+      `).get(embeddingBuffer);
+
+      if (match && match.similarity >= autoSupersedeThreshold) {
+        supersedes = match.id;
+      }
+    } catch {
+      // vec table might be empty — proceed without supersession
+    }
+  }
+  const id = generateId();
+  const now = new Date().toISOString();
+
+  const boost = arousalSalienceBoost(affect.arousal);
+  const effectiveSalience = Math.min(1.0, salience + (boost * arousalWeight));
+
+  const insertAndLink = db.transaction(() => {
+    db.prepare(`
+      INSERT INTO episodes (
+        id, content, embedding, source, source_reliability, salience, context, affect,
+        tags, causal_trigger, causal_consequence, created_at,
+        embedding_model, embedding_version, supersedes, "private"
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `).run(
+      id, content, embeddingBuffer, source, reliability, effectiveSalience,
+      JSON.stringify(context),
+      JSON.stringify(affect),
+      tags ? JSON.stringify(tags) : null,
+      causal?.trigger || null, causal?.consequence || null,
+      now, embeddingProvider.modelName, embeddingProvider.modelVersion,
+      supersedes || null,
+      isPrivate ? 1 : 0,
+    );
+    db.prepare(
+      'INSERT INTO vec_episodes(id, embedding, source, consolidated) VALUES (?, ?, ?, ?)'
+    ).run(id, embeddingBuffer, source, BigInt(0));
+    if (supersedes) {
+      db.prepare('UPDATE episodes SET superseded_by = ? WHERE id = ?').run(id, supersedes);
+    }
+  });
+
+  insertAndLink();
+  return id;
+}