audrey 0.3.0

package/src/prompts.js

@@ -0,0 +1,134 @@
+import { safeJsonParse } from './utils.js';
+
+export function buildPrincipleExtractionPrompt(episodes) {
+  const episodeList = episodes.map((ep, i) => {
+    const tags = safeJsonParse(ep.tags, []);
+    return `Episode ${i + 1}:
+- Content: ${ep.content}
+- Source: ${ep.source}
+- Date: ${ep.created_at}
+- Tags: ${tags.length > 0 ? tags.join(', ') : 'none'}`;
+  }).join('\n\n');
+
+  return [
+    {
+      role: 'system',
+      content: `You are performing principleExtraction for a memory system. Given a cluster of related episodic memories, extract a generalized principle or procedure.
+
+Respond with ONLY valid JSON in this exact format:
+{
+  "content": "The generalized principle expressed as a clear, actionable statement",
+  "type": "semantic or procedural — semantic for factual principles, procedural for how-to/workflow knowledge",
+  "conditions": ["boundary condition 1", "boundary condition 2"] or null if universally applicable
+}
+
+Rules:
+- GENERALIZE, do not merely summarize or concatenate the episodes
+- Identify boundary conditions: when does this principle NOT apply?
+- Classify as "semantic" (facts, rules, patterns) or "procedural" (steps, workflows, strategies)
+- Consider source diversity — principles from diverse sources are stronger
+- Be concise but precise`,
+    },
+    {
+      role: 'user',
+      content: `Extract a principle from these ${episodes.length} related episodes:\n\n${episodeList}`,
+    },
+  ];
+}
+
+export function buildContradictionDetectionPrompt(newContent, existingContent) {
+  return [
+    {
+      role: 'system',
+      content: `You are performing contradictionDetection for a memory system. Given two claims, determine if they contradict each other.
+
+Respond with ONLY valid JSON in this exact format:
+{
+  "contradicts": true or false,
+  "explanation": "Brief explanation of why these do or do not contradict",
+  "resolution": "new_wins" or "existing_wins" or "context_dependent" or null if no contradiction,
+  "conditions": { "new": "context where new claim is true", "existing": "context where existing claim is true" } or null
+}
+
+Rules:
+- Two claims contradict if they cannot both be true in the same context
+- If both can be true under different conditions, set resolution to "context_dependent" and specify conditions
+- If one clearly supersedes the other, indicate which wins
+- If unclear, set resolution to null (leave as open contradiction)`,
+    },
+    {
+      role: 'user',
+      content: `Compare these two claims for contradiction:
+
+NEW CLAIM: ${newContent}
+
+EXISTING CLAIM: ${existingContent}`,
+    },
+  ];
+}
+
+export function buildCausalArticulationPrompt(cause, effect) {
+  return [
+    {
+      role: 'system',
+      content: `You are performing causalArticulation for a memory system. Given a cause and effect, articulate the mechanism that connects them.
+
+Respond with ONLY valid JSON in this exact format:
+{
+  "mechanism": "A clear explanation of WHY the cause leads to the effect",
+  "linkType": "causal" or "correlational" or "temporal",
+  "confidence": 0.0 to 1.0,
+  "spurious": true or false
+}
+
+Rules:
+- "causal": there is a clear mechanistic explanation for why A causes B
+- "correlational": A and B co-occur but no clear mechanism (may share a common cause)
+- "temporal": A happens before B but that may be coincidence
+- If you cannot articulate a mechanism, classify as "correlational" or "temporal", NOT "causal"
+- Set "spurious" to true if the correlation is likely coincidental
+- Confidence reflects how certain you are about the link type classification`,
+    },
+    {
+      role: 'user',
+      content: `Analyze the causal relationship:
+
+CAUSE: ${cause.content} (source: ${cause.source})
+
+EFFECT: ${effect.content} (source: ${effect.source})`,
+    },
+  ];
+}
+
+export function buildContextResolutionPrompt(claimA, claimB, context) {
+  const contextSection = context
+    ? `\n\nADDITIONAL CONTEXT: ${context}`
+    : '';
+
+  return [
+    {
+      role: 'system',
+      content: `You are performing contextResolution for a memory system. Given two contradicting claims, determine how to resolve the contradiction.
+
+Respond with ONLY valid JSON in this exact format:
+{
+  "resolution": "a_wins" or "b_wins" or "context_dependent",
+  "conditions": { "a": "context where claim A is true", "b": "context where claim B is true" } or null,
+  "explanation": "Brief explanation of the resolution"
+}
+
+Rules:
+- If one claim is clearly more accurate/recent/well-sourced, it wins
+- If both can be true in different contexts, mark as "context_dependent" and specify conditions
+- Provide clear conditions that an agent could evaluate at retrieval time`,
+    },
+    {
+      role: 'user',
+      content: `Resolve this contradiction:
+
+CLAIM A: ${claimA}
+
+CLAIM B: ${claimB}${contextSection}`,
+    },
+  ];
+}

package/src/recall.js

@@ -0,0 +1,260 @@
+import { computeConfidence, DEFAULT_HALF_LIVES } from './confidence.js';
+import { daysBetween, safeJsonParse } from './utils.js';
+
+function computeEpisodicConfidence(ep, now) {
+  const ageDays = daysBetween(ep.created_at, now);
+  return computeConfidence({
+    sourceType: ep.source,
+    supportingCount: 1,
+    contradictingCount: 0,
+    ageDays,
+    halfLifeDays: DEFAULT_HALF_LIVES.episodic,
+    retrievalCount: 0,
+    daysSinceRetrieval: ageDays,
+  });
+}
+
+function computeSemanticConfidence(sem, now) {
+  const ageDays = daysBetween(sem.created_at, now);
+  const daysSinceRetrieval = sem.last_reinforced_at
+    ? daysBetween(sem.last_reinforced_at, now)
+    : ageDays;
+  return 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,
+  });
+}
+
+function computeProceduralConfidence(proc, now) {
+  const ageDays = daysBetween(proc.created_at, now);
+  const daysSinceRetrieval = proc.last_reinforced_at
+    ? daysBetween(proc.last_reinforced_at, now)
+    : ageDays;
+  return 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,
+  });
+}
+
+function buildEpisodicEntry(ep, confidence, score, includeProvenance) {
+  const entry = {
+    id: ep.id,
+    content: ep.content,
+    type: 'episodic',
+    confidence,
+    score,
+    source: ep.source,
+    createdAt: ep.created_at,
+  };
+  if (includeProvenance) {
+    entry.provenance = {
+      source: ep.source,
+      sourceReliability: ep.source_reliability,
+      createdAt: ep.created_at,
+      supersedes: ep.supersedes || null,
+    };
+  }
+  return entry;
+}
+
+function buildSemanticEntry(sem, confidence, score, includeProvenance) {
+  const entry = {
+    id: sem.id,
+    content: sem.content,
+    type: 'semantic',
+    confidence,
+    score,
+    source: 'consolidation',
+    state: sem.state,
+    createdAt: sem.created_at,
+  };
+  if (includeProvenance) {
+    entry.provenance = {
+      evidenceEpisodeIds: safeJsonParse(sem.evidence_episode_ids, []),
+      evidenceCount: sem.evidence_count || 0,
+      supportingCount: sem.supporting_count || 0,
+      contradictingCount: sem.contradicting_count || 0,
+      consolidationCheckpoint: sem.consolidation_checkpoint || null,
+    };
+  }
+  return entry;
+}
+
+function buildProceduralEntry(proc, confidence, score, includeProvenance) {
+  const entry = {
+    id: proc.id,
+    content: proc.content,
+    type: 'procedural',
+    confidence,
+    score,
+    source: 'consolidation',
+    state: proc.state,
+    createdAt: proc.created_at,
+  };
+  if (includeProvenance) {
+    entry.provenance = {
+      evidenceEpisodeIds: safeJsonParse(proc.evidence_episode_ids, []),
+      successCount: proc.success_count || 0,
+      failureCount: proc.failure_count || 0,
+      triggerConditions: proc.trigger_conditions || null,
+    };
+  }
+  return entry;
+}
+
+function knnEpisodic(db, queryBuffer, candidateK, now, minConfidence, includeProvenance) {
+  const rows = db.prepare(`
+    SELECT e.*, (1.0 - v.distance) AS similarity
+    FROM vec_episodes v
+    JOIN episodes e ON e.id = v.id
+    WHERE v.embedding MATCH ?
+      AND k = ?
+      AND e.superseded_by IS NULL
+  `).all(queryBuffer, candidateK);
+
+  const results = [];
+  for (const row of rows) {
+    const confidence = computeEpisodicConfidence(row, now);
+    if (confidence < minConfidence) continue;
+    const score = row.similarity * confidence;
+    results.push(buildEpisodicEntry(row, confidence, score, includeProvenance));
+  }
+  return results;
+}
+
+function knnSemantic(db, queryBuffer, candidateK, now, minConfidence, includeProvenance, includeDormant) {
+  let stateFilter;
+  if (includeDormant) {
+    stateFilter = "AND (v.state = 'active' OR v.state = 'context_dependent' OR v.state = 'dormant')";
+  } else {
+    stateFilter = "AND (v.state = 'active' OR v.state = 'context_dependent')";
+  }
+
+  const rows = db.prepare(`
+    SELECT s.*, (1.0 - v.distance) AS similarity
+    FROM vec_semantics v
+    JOIN semantics s ON s.id = v.id
+    WHERE v.embedding MATCH ?
+      AND k = ?
+      ${stateFilter}
+  `).all(queryBuffer, candidateK);
+
+  const results = [];
+  const matchedIds = [];
+  for (const row of rows) {
+    const confidence = computeSemanticConfidence(row, now);
+    if (confidence < minConfidence) continue;
+    const score = row.similarity * confidence;
+    matchedIds.push(row.id);
+    results.push(buildSemanticEntry(row, confidence, score, includeProvenance));
+  }
+  return { results, matchedIds };
+}
+
+function knnProcedural(db, queryBuffer, candidateK, now, minConfidence, includeProvenance, includeDormant) {
+  let stateFilter;
+  if (includeDormant) {
+    stateFilter = "AND (v.state = 'active' OR v.state = 'context_dependent' OR v.state = 'dormant')";
+  } else {
+    stateFilter = "AND (v.state = 'active' OR v.state = 'context_dependent')";
+  }
+
+  const rows = db.prepare(`
+    SELECT p.*, (1.0 - v.distance) AS similarity
+    FROM vec_procedures v
+    JOIN procedures p ON p.id = v.id
+    WHERE v.embedding MATCH ?
+      AND k = ?
+      ${stateFilter}
+  `).all(queryBuffer, candidateK);
+
+  const results = [];
+  const matchedIds = [];
+  for (const row of rows) {
+    const confidence = computeProceduralConfidence(row, now);
+    if (confidence < minConfidence) continue;
+    const score = row.similarity * confidence;
+    matchedIds.push(row.id);
+    results.push(buildProceduralEntry(row, confidence, score, includeProvenance));
+  }
+  return { results, matchedIds };
+}
+
+export async function* recallStream(db, embeddingProvider, query, options = {}) {
+  const {
+    minConfidence = 0,
+    types,
+    limit = 10,
+    includeProvenance = false,
+    includeDormant = false,
+  } = options;
+
+  const queryVector = await embeddingProvider.embed(query);
+  const queryBuffer = embeddingProvider.vectorToBuffer(queryVector);
+  const searchTypes = types || ['episodic', 'semantic', 'procedural'];
+  const now = new Date();
+  const candidateK = limit * 3;
+
+  const allResults = [];
+
+  if (searchTypes.includes('episodic')) {
+    const episodic = knnEpisodic(db, queryBuffer, candidateK, now, minConfidence, includeProvenance);
+    allResults.push(...episodic);
+  }
+
+  if (searchTypes.includes('semantic')) {
+    const { results: semResults, matchedIds: semIds } =
+      knnSemantic(db, queryBuffer, candidateK, now, minConfidence, includeProvenance, includeDormant);
+    allResults.push(...semResults);
+
+    if (semIds.length > 0) {
+      const updateStmt = db.prepare(
+        'UPDATE semantics SET retrieval_count = retrieval_count + 1, last_reinforced_at = ? WHERE id = ?'
+      );
+      const nowISO = now.toISOString();
+      for (const id of semIds) {
+        updateStmt.run(nowISO, id);
+      }
+    }
+  }
+
+  if (searchTypes.includes('procedural')) {
+    const { results: procResults, matchedIds: procIds } =
+      knnProcedural(db, queryBuffer, candidateK, now, minConfidence, includeProvenance, includeDormant);
+    allResults.push(...procResults);
+
+    if (procIds.length > 0) {
+      const updateStmt = db.prepare(
+        'UPDATE procedures SET retrieval_count = retrieval_count + 1, last_reinforced_at = ? WHERE id = ?'
+      );
+      const nowISO = now.toISOString();
+      for (const id of procIds) {
+        updateStmt.run(nowISO, id);
+      }
+    }
+  }
+
+  allResults.sort((a, b) => b.score - a.score);
+  const top = allResults.slice(0, limit);
+  for (const entry of top) {
+    yield entry;
+  }
+}
+
+export async function recall(db, embeddingProvider, query, options = {}) {
+  const results = [];
+  for await (const entry of recallStream(db, embeddingProvider, query, options)) {
+    results.push(entry);
+  }
+  return results;
+}

package/src/rollback.js

@@ -0,0 +1,33 @@
+import { safeJsonParse } from './utils.js';
+
+export function getConsolidationHistory(db) {
+  return db.prepare(`
+    SELECT id, checkpoint_cursor, input_episode_ids, output_memory_ids,
+           started_at, completed_at, status
+    FROM consolidation_runs ORDER BY started_at DESC
+  `).all();
+}
+
+export function rollbackConsolidation(db, runId) {
+  const run = db.prepare('SELECT * FROM consolidation_runs WHERE id = ?').get(runId);
+  if (!run) throw new Error(`Consolidation run not found: ${runId}`);
+  if (run.status === 'rolled_back') throw new Error(`Run already rolled back: ${runId}`);
+
+  const outputIds = safeJsonParse(run.output_memory_ids, []);
+  const inputIds = safeJsonParse(run.input_episode_ids, []);
+
+  const doRollback = db.transaction(() => {
+    const markSemantics = db.prepare('UPDATE semantics SET state = ? WHERE id = ?');
+    const markProcedures = db.prepare('UPDATE procedures SET state = ? WHERE id = ?');
+    for (const id of outputIds) {
+      markSemantics.run('rolled_back', id);
+      markProcedures.run('rolled_back', id);
+    }
+    const unmark = db.prepare('UPDATE episodes SET consolidated = 0 WHERE id = ?');
+    for (const id of inputIds) { unmark.run(id); }
+    db.prepare('UPDATE consolidation_runs SET status = ? WHERE id = ?').run('rolled_back', runId);
+  });
+
+  doRollback();
+  return { rolledBackMemories: outputIds.length, restoredEpisodes: inputIds.length };
+}

package/src/ulid.js

@@ -0,0 +1,11 @@
+import { ulid } from 'ulid';
+import { createHash } from 'node:crypto';
+
+export function generateId() {
+  return ulid();
+}
+
+export function generateDeterministicId(...parts) {
+  const input = JSON.stringify(parts);
+  return createHash('sha256').update(input).digest('hex').slice(0, 26);
+}

package/src/utils.js

@@ -0,0 +1,22 @@
+export function cosineSimilarity(bufA, bufB, provider) {
+  const a = provider.bufferToVector(bufA);
+  const b = provider.bufferToVector(bufB);
+  let dot = 0, magA = 0, magB = 0;
+  for (let i = 0; i < a.length; i++) {
+    dot += a[i] * b[i];
+    magA += a[i] * a[i];
+    magB += b[i] * b[i];
+  }
+  const mag = Math.sqrt(magA) * Math.sqrt(magB);
+  return mag === 0 ? 0 : dot / mag;
+}
+
+export function daysBetween(dateStr, now) {
+  return Math.max(0, (now.getTime() - new Date(dateStr).getTime()) / (1000 * 60 * 60 * 24));
+}
+
+export function safeJsonParse(str, fallback = null) {
+  if (!str) return fallback;
+  try { return JSON.parse(str); }
+  catch { return fallback; }
+}

package/src/validate.js

@@ -0,0 +1,150 @@
+import { generateId } from './ulid.js';
+import { safeJsonParse } from './utils.js';
+import { buildContradictionDetectionPrompt } from './prompts.js';
+
+const REINFORCEMENT_THRESHOLD = 0.85;
+const CONTRADICTION_THRESHOLD = 0.60;
+
+export async function validateMemory(db, embeddingProvider, episode, options = {}) {
+  const {
+    threshold = REINFORCEMENT_THRESHOLD,
+    contradictionThreshold = CONTRADICTION_THRESHOLD,
+    llmProvider,
+  } = options;
+
+  const episodeVector = await embeddingProvider.embed(episode.content);
+  const episodeBuffer = embeddingProvider.vectorToBuffer(episodeVector);
+
+  const nearestSemantic = db.prepare(`
+    SELECT s.*, (1.0 - v.distance) AS similarity
+    FROM vec_semantics v
+    JOIN semantics s ON s.id = v.id
+    WHERE v.embedding MATCH ?
+      AND k = 1
+      AND (v.state = 'active' OR v.state = 'context_dependent')
+  `).get(episodeBuffer);
+
+  let bestMatch = null;
+  let bestSimilarity = 0;
+
+  if (nearestSemantic) {
+    bestMatch = nearestSemantic;
+    bestSimilarity = nearestSemantic.similarity;
+  }
+
+  if (bestMatch && bestSimilarity >= threshold) {
+    const evidenceIds = safeJsonParse(bestMatch.evidence_episode_ids, []);
+    if (!evidenceIds.includes(episode.id)) {
+      evidenceIds.push(episode.id);
+    }
+
+    const diversity = computeSourceDiversity(db, evidenceIds, episode);
+
+    const now = new Date().toISOString();
+    db.prepare(`
+      UPDATE semantics SET
+        supporting_count = supporting_count + 1,
+        evidence_episode_ids = ?,
+        evidence_count = ?,
+        source_type_diversity = ?,
+        last_reinforced_at = ?
+      WHERE id = ?
+    `).run(
+      JSON.stringify(evidenceIds),
+      evidenceIds.length,
+      diversity,
+      now,
+      bestMatch.id,
+    );
+
+    return {
+      action: 'reinforced',
+      semanticId: bestMatch.id,
+      similarity: bestSimilarity,
+    };
+  }
+
+  if (bestMatch && bestSimilarity >= contradictionThreshold && llmProvider) {
+    const messages = buildContradictionDetectionPrompt(episode.content, bestMatch.content);
+    const verdict = await llmProvider.json(messages);
+
+    if (verdict.contradicts) {
+      const resolution = verdict.resolution === 'context_dependent'
+        ? { type: 'context_dependent', conditions: verdict.conditions, explanation: verdict.explanation }
+        : verdict.resolution
+          ? { type: verdict.resolution, explanation: verdict.explanation }
+          : null;
+
+      const contradictionId = createContradiction(
+        db,
+        bestMatch.id,
+        'semantic',
+        episode.id,
+        'episodic',
+        resolution,
+      );
+
+      if (verdict.resolution === 'new_wins') {
+        db.prepare("UPDATE semantics SET state = 'disputed' WHERE id = ?").run(bestMatch.id);
+      } else if (verdict.resolution === 'context_dependent' && verdict.conditions) {
+        db.prepare("UPDATE semantics SET state = 'context_dependent', conditions = ? WHERE id = ?")
+          .run(JSON.stringify(verdict.conditions), bestMatch.id);
+      }
+
+      return {
+        action: 'contradiction',
+        contradictionId,
+        semanticId: bestMatch.id,
+        similarity: bestSimilarity,
+        resolution: verdict.resolution || null,
+      };
+    }
+  }
+
+  return { action: 'none' };
+}
+
+function computeSourceDiversity(db, evidenceIds, currentEpisode) {
+  const sourceTypes = new Set();
+  sourceTypes.add(currentEpisode.source);
+
+  if (evidenceIds.length > 0) {
+    const placeholders = evidenceIds.map(() => '?').join(',');
+    const rows = db.prepare(
+      `SELECT DISTINCT source FROM episodes WHERE id IN (${placeholders})`
+    ).all(...evidenceIds);
+    for (const row of rows) {
+      sourceTypes.add(row.source);
+    }
+  }
+
+  return sourceTypes.size;
+}
+
+export function createContradiction(db, claimAId, claimAType, claimBId, claimBType, resolution) {
+  const id = generateId();
+  const now = new Date().toISOString();
+
+  const state = resolution ? 'resolved' : 'open';
+  const resolvedAt = resolution ? now : null;
+  const resolutionJson = resolution ? JSON.stringify(resolution) : null;
+
+  db.prepare(`
+    INSERT INTO contradictions (id, claim_a_id, claim_a_type, claim_b_id, claim_b_type,
+      state, resolution, resolved_at, created_at)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `).run(id, claimAId, claimAType, claimBId, claimBType, state, resolutionJson, resolvedAt, now);
+
+  return id;
+}
+
+export function reopenContradiction(db, contradictionId, newEvidenceId) {
+  const now = new Date().toISOString();
+  db.prepare(`
+    UPDATE contradictions SET
+      state = 'reopened',
+      reopen_evidence_id = ?,
+      reopened_at = ?
+    WHERE id = ?
+  `).run(newEvidenceId, now, contradictionId);
+}