audrey 0.3.0

package/src/db.js

@@ -0,0 +1,234 @@
+import Database from 'better-sqlite3';
+import * as sqliteVec from 'sqlite-vec';
+import { join } from 'node:path';
+import { mkdirSync } 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,
+    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,
+    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
+  );
+
+  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
+  );
+
+  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 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);
+`;
+
+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
+    );
+  `);
+}
+
+function migrateTable(db, { source, target, selectCols, insertCols, placeholders, transform }) {
+  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 insert = db.prepare(`INSERT INTO ${target}(${insertCols}) VALUES (${placeholders})`);
+  const tx = db.transaction(() => {
+    for (const row of rows) {
+      insert.run(...transform(row));
+    }
+  });
+  tx();
+}
+
+function migrateEmbeddingsToVec0(db) {
+  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)],
+  });
+
+  migrateTable(db, {
+    source: 'semantics',
+    target: 'vec_semantics',
+    selectCols: 'id, embedding, state',
+    insertCols: 'id, embedding, state',
+    placeholders: '?, ?, ?',
+    transform: (row) => [row.id, row.embedding, row.state],
+  });
+
+  migrateTable(db, {
+    source: 'procedures',
+    target: 'vec_procedures',
+    selectCols: 'id, embedding, state',
+    insertCols: 'id, embedding, state',
+    placeholders: '?, ?, ?',
+    transform: (row) => [row.id, row.embedding, row.state],
+  });
+}
+
+export function createDatabase(dataDir, options = {}) {
+  const { dimensions } = options;
+
+  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);
+
+  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) {
+        db.close();
+        throw new Error(
+          `Dimension mismatch: database was created with ${storedDims} dimensions, but ${dimensions} were requested`
+        );
+      }
+    } else {
+      db.prepare(
+        "INSERT INTO audrey_config (key, value) VALUES ('dimensions', ?)"
+      ).run(String(dimensions));
+    }
+
+    createVec0Tables(db, dimensions);
+
+    migrateEmbeddingsToVec0(db);
+  }
+
+  return db;
+}
+
+export function closeDatabase(db) {
+  if (db && db.open) {
+    db.close();
+  }
+}

package/src/decay.js

@@ -0,0 +1,72 @@
+import { computeConfidence, DEFAULT_HALF_LIVES } from './confidence.js';
+import { daysBetween } from './utils.js';
+
+export function applyDecay(db, { dormantThreshold = 0.1 } = {}) {
+  const now = new Date();
+  let totalEvaluated = 0;
+  let transitionedToDormant = 0;
+
+  const semantics = db.prepare(`
+    SELECT id, supporting_count, contradicting_count, created_at,
+           last_reinforced_at, retrieval_count
+    FROM semantics WHERE state = 'active'
+  `).all();
+
+  const markDormantSem = db.prepare('UPDATE semantics SET state = ? WHERE id = ?');
+
+  for (const sem of semantics) {
+    totalEvaluated++;
+    const ageDays = daysBetween(sem.created_at, now);
+    const daysSinceRetrieval = sem.last_reinforced_at
+      ? daysBetween(sem.last_reinforced_at, now)
+      : ageDays;
+
+    const confidence = computeConfidence({
+      sourceType: 'tool-result',
+      supportingCount: sem.supporting_count || 0,
+      contradictingCount: sem.contradicting_count || 0,
+      ageDays,
+      halfLifeDays: DEFAULT_HALF_LIVES.semantic,
+      retrievalCount: sem.retrieval_count || 0,
+      daysSinceRetrieval,
+    });
+
+    if (confidence < dormantThreshold) {
+      markDormantSem.run('dormant', sem.id);
+      transitionedToDormant++;
+    }
+  }
+
+  const procedures = db.prepare(`
+    SELECT id, success_count, failure_count, created_at,
+           last_reinforced_at, retrieval_count
+    FROM procedures WHERE state = 'active'
+  `).all();
+
+  const markDormantProc = db.prepare('UPDATE procedures SET state = ? WHERE id = ?');
+
+  for (const proc of procedures) {
+    totalEvaluated++;
+    const ageDays = daysBetween(proc.created_at, now);
+    const daysSinceRetrieval = proc.last_reinforced_at
+      ? daysBetween(proc.last_reinforced_at, now)
+      : ageDays;
+
+    const confidence = computeConfidence({
+      sourceType: 'tool-result',
+      supportingCount: proc.success_count || 0,
+      contradictingCount: proc.failure_count || 0,
+      ageDays,
+      halfLifeDays: DEFAULT_HALF_LIVES.procedural,
+      retrievalCount: proc.retrieval_count || 0,
+      daysSinceRetrieval,
+    });
+
+    if (confidence < dormantThreshold) {
+      markDormantProc.run('dormant', proc.id);
+      transitionedToDormant++;
+    }
+  }
+
+  return { totalEvaluated, transitionedToDormant, timestamp: now.toISOString() };
+}

package/src/embedding.js

@@ -0,0 +1,88 @@
+import { createHash } from 'node:crypto';
+
+export class MockEmbeddingProvider {
+  constructor({ dimensions = 64 } = {}) {
+    this.dimensions = dimensions;
+    this.modelName = 'mock-embedding';
+    this.modelVersion = '1.0.0';
+  }
+
+  async embed(text) {
+    const hash = createHash('sha256').update(text).digest();
+    const vector = new Array(this.dimensions);
+    for (let i = 0; i < this.dimensions; i++) {
+      vector[i] = (hash[i % hash.length] / 255) * 2 - 1;
+    }
+    const magnitude = Math.sqrt(vector.reduce((sum, v) => sum + v * v, 0));
+    return vector.map(v => v / magnitude);
+  }
+
+  async embedBatch(texts) {
+    return Promise.all(texts.map(t => this.embed(t)));
+  }
+
+  vectorToBuffer(vector) {
+    return Buffer.from(new Float32Array(vector).buffer);
+  }
+
+  bufferToVector(buffer) {
+    return Array.from(new Float32Array(buffer.buffer, buffer.byteOffset, buffer.byteLength / 4));
+  }
+}
+
+export class OpenAIEmbeddingProvider {
+  constructor({ apiKey, model = 'text-embedding-3-small', dimensions = 1536 } = {}) {
+    this.apiKey = apiKey || process.env.OPENAI_API_KEY;
+    this.model = model;
+    this.dimensions = dimensions;
+    this.modelName = model;
+    this.modelVersion = 'latest';
+  }
+
+  async embed(text) {
+    const response = await fetch('https://api.openai.com/v1/embeddings', {
+      method: 'POST',
+      headers: {
+        'Authorization': `Bearer ${this.apiKey}`,
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({ input: text, model: this.model, dimensions: this.dimensions }),
+    });
+    if (!response.ok) throw new Error(`OpenAI embedding failed: ${response.status}`);
+    const data = await response.json();
+    return data.data[0].embedding;
+  }
+
+  async embedBatch(texts) {
+    const response = await fetch('https://api.openai.com/v1/embeddings', {
+      method: 'POST',
+      headers: {
+        'Authorization': `Bearer ${this.apiKey}`,
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({ input: texts, model: this.model, dimensions: this.dimensions }),
+    });
+    if (!response.ok) throw new Error(`OpenAI embedding failed: ${response.status}`);
+    const data = await response.json();
+    return data.data.map(d => d.embedding);
+  }
+
+  vectorToBuffer(vector) {
+    return Buffer.from(new Float32Array(vector).buffer);
+  }
+
+  bufferToVector(buffer) {
+    return Array.from(new Float32Array(buffer.buffer, buffer.byteOffset, buffer.byteLength / 4));
+  }
+}
+
+export function createEmbeddingProvider(config) {
+  switch (config.provider) {
+    case 'mock':
+      return new MockEmbeddingProvider(config);
+    case 'openai':
+      return new OpenAIEmbeddingProvider(config);
+    default:
+      throw new Error(`Unknown embedding provider: ${config.provider}. Valid: mock, openai`);
+  }
+}

package/src/encode.js

@@ -0,0 +1,46 @@
+import { generateId } from './ulid.js';
+import { sourceReliability } from './confidence.js';
+
+export async function encodeEpisode(db, embeddingProvider, {
+  content,
+  source,
+  salience = 0.5,
+  causal,
+  tags,
+  supersedes,
+}) {
+  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 insertAndLink = db.transaction(() => {
+    db.prepare(`
+      INSERT INTO episodes (
+        id, content, embedding, source, source_reliability, salience,
+        tags, causal_trigger, causal_consequence, created_at,
+        embedding_model, embedding_version, supersedes
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `).run(
+      id, content, embeddingBuffer, source, reliability, salience,
+      tags ? JSON.stringify(tags) : null,
+      causal?.trigger || null, causal?.consequence || null,
+      now, embeddingProvider.modelName, embeddingProvider.modelVersion,
+      supersedes || null,
+    );
+    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;
+}

package/src/index.js

@@ -0,0 +1,12 @@
+export { Audrey } from './audrey.js';
+export { computeConfidence, sourceReliability, DEFAULT_SOURCE_RELIABILITY, DEFAULT_WEIGHTS, DEFAULT_HALF_LIVES } from './confidence.js';
+export { createEmbeddingProvider, MockEmbeddingProvider, OpenAIEmbeddingProvider } from './embedding.js';
+export { createLLMProvider, MockLLMProvider, AnthropicLLMProvider, OpenAILLMProvider } from './llm.js';
+export { recall, recallStream } from './recall.js';
+export { addCausalLink, getCausalChain, articulateCausalLink } from './causal.js';
+export {
+  buildPrincipleExtractionPrompt,
+  buildContradictionDetectionPrompt,
+  buildCausalArticulationPrompt,
+  buildContextResolutionPrompt,
+} from './prompts.js';

package/src/introspect.js

@@ -0,0 +1,44 @@
+import { safeJsonParse } from './utils.js';
+
+export function introspect(db) {
+  const counts = db.prepare(`
+    SELECT
+      (SELECT COUNT(*) FROM episodes) as episodic,
+      (SELECT COUNT(*) FROM semantics WHERE state != 'rolled_back') as semantic,
+      (SELECT COUNT(*) FROM procedures WHERE state != 'rolled_back') as procedural,
+      (SELECT COUNT(*) FROM causal_links) as causal_links,
+      (SELECT COUNT(*) FROM semantics WHERE state = 'dormant')
+        + (SELECT COUNT(*) FROM procedures WHERE state = 'dormant') as dormant
+  `).get();
+
+  const contradictions = db.prepare(`
+    SELECT
+      SUM(CASE WHEN state = 'open' THEN 1 ELSE 0 END) as open,
+      SUM(CASE WHEN state = 'resolved' THEN 1 ELSE 0 END) as resolved,
+      SUM(CASE WHEN state = 'context_dependent' THEN 1 ELSE 0 END) as context_dependent,
+      SUM(CASE WHEN state = 'reopened' THEN 1 ELSE 0 END) as reopened
+    FROM contradictions
+  `).get();
+
+  const lastRun = db.prepare(`
+    SELECT completed_at FROM consolidation_runs
+    WHERE status = 'completed' ORDER BY completed_at DESC LIMIT 1
+  `).get();
+  const totalRuns = db.prepare('SELECT COUNT(*) as count FROM consolidation_runs').get().count;
+
+  return {
+    episodic: counts.episodic,
+    semantic: counts.semantic,
+    procedural: counts.procedural,
+    causalLinks: counts.causal_links,
+    dormant: counts.dormant,
+    contradictions: {
+      open: contradictions?.open || 0,
+      resolved: contradictions?.resolved || 0,
+      context_dependent: contradictions?.context_dependent || 0,
+      reopened: contradictions?.reopened || 0,
+    },
+    lastConsolidation: lastRun?.completed_at || null,
+    totalConsolidationRuns: totalRuns,
+  };
+}

package/src/llm.js

@@ -0,0 +1,132 @@
+const PROMPT_TYPE_KEYS = [
+  'principleExtraction',
+  'contradictionDetection',
+  'causalArticulation',
+  'contextResolution',
+];
+
+export class MockLLMProvider {
+  constructor({ responses = {} } = {}) {
+    this.responses = responses;
+    this.modelName = 'mock-llm';
+    this.modelVersion = '1.0.0';
+  }
+
+  _matchPromptType(messages) {
+    const systemMsg = messages.find(m => m.role === 'system')?.content || '';
+    for (const key of PROMPT_TYPE_KEYS) {
+      if (systemMsg.includes(key)) return key;
+    }
+    return null;
+  }
+
+  async complete(messages) {
+    const promptType = this._matchPromptType(messages);
+    const cannedResponse = promptType ? this.responses[promptType] : undefined;
+    return { content: cannedResponse !== undefined ? JSON.stringify(cannedResponse) : '{}' };
+  }
+
+  async json(messages) {
+    const promptType = this._matchPromptType(messages);
+    const cannedResponse = promptType ? this.responses[promptType] : undefined;
+    return cannedResponse !== undefined ? cannedResponse : {};
+  }
+}
+
+export class AnthropicLLMProvider {
+  constructor({ apiKey, model = 'claude-sonnet-4-6', maxTokens = 1024 } = {}) {
+    this.apiKey = apiKey || process.env.ANTHROPIC_API_KEY;
+    this.model = model;
+    this.maxTokens = maxTokens;
+    this.modelName = model;
+    this.modelVersion = 'latest';
+  }
+
+  async complete(messages, options = {}) {
+    const systemMsg = messages.find(m => m.role === 'system')?.content;
+    const nonSystemMsgs = messages.filter(m => m.role !== 'system');
+
+    const body = {
+      model: this.model,
+      max_tokens: options.maxTokens || this.maxTokens,
+      messages: nonSystemMsgs,
+    };
+    if (systemMsg) body.system = systemMsg;
+
+    const response = await fetch('https://api.anthropic.com/v1/messages', {
+      method: 'POST',
+      headers: {
+        'x-api-key': this.apiKey,
+        'anthropic-version': '2023-06-01',
+        'content-type': 'application/json',
+      },
+      body: JSON.stringify(body),
+    });
+
+    if (!response.ok) {
+      throw new Error(`Anthropic API error: ${response.status}`);
+    }
+
+    const data = await response.json();
+    const text = data.content?.[0]?.text || '';
+    return { content: text };
+  }
+
+  async json(messages, options = {}) {
+    const result = await this.complete(messages, options);
+    return JSON.parse(result.content);
+  }
+}
+
+export class OpenAILLMProvider {
+  constructor({ apiKey, model = 'gpt-4o', maxTokens = 1024 } = {}) {
+    this.apiKey = apiKey || process.env.OPENAI_API_KEY;
+    this.model = model;
+    this.maxTokens = maxTokens;
+    this.modelName = model;
+    this.modelVersion = 'latest';
+  }
+
+  async complete(messages, options = {}) {
+    const body = {
+      model: this.model,
+      max_tokens: options.maxTokens || this.maxTokens,
+      messages,
+    };
+
+    const response = await fetch('https://api.openai.com/v1/chat/completions', {
+      method: 'POST',
+      headers: {
+        'Authorization': `Bearer ${this.apiKey}`,
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify(body),
+    });
+
+    if (!response.ok) {
+      throw new Error(`OpenAI API error: ${response.status}`);
+    }
+
+    const data = await response.json();
+    const text = data.choices?.[0]?.message?.content || '';
+    return { content: text };
+  }
+
+  async json(messages, options = {}) {
+    const result = await this.complete(messages, options);
+    return JSON.parse(result.content);
+  }
+}
+
+export function createLLMProvider(config) {
+  switch (config.provider) {
+    case 'mock':
+      return new MockLLMProvider(config);
+    case 'anthropic':
+      return new AnthropicLLMProvider(config);
+    case 'openai':
+      return new OpenAILLMProvider(config);
+    default:
+      throw new Error(`Unknown LLM provider: ${config.provider}. Valid: mock, anthropic, openai`);
+  }
+}