audrey 0.3.0

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "audrey",
+  "version": "0.3.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",
+  "exports": {
+    ".": "./src/index.js",
+    "./mcp": "./mcp-server/index.js"
+  },
+  "bin": {
+    "audrey-mcp": "./mcp-server/index.js"
+  },
+  "files": [
+    "src/",
+    "mcp-server/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "keywords": [
+    "ai",
+    "memory",
+    "agents",
+    "llm",
+    "cognitive",
+    "sqlite",
+    "embedding",
+    "mcp",
+    "biological-memory",
+    "episodic-memory",
+    "semantic-memory",
+    "forgetting-curve",
+    "vector-search",
+    "knowledge-graph",
+    "causal-graph",
+    "ai-agent",
+    "model-context-protocol",
+    "recall",
+    "consolidation",
+    "confidence",
+    "long-term-memory",
+    "persistent-memory",
+    "rag",
+    "claude",
+    "agent-framework"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Evilander/Audrey.git"
+  },
+  "homepage": "https://github.com/Evilander/Audrey",
+  "bugs": {
+    "url": "https://github.com/Evilander/Audrey/issues"
+  },
+  "author": "Tyler Eveland <j.tyler.eveland@gmail.com>",
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "better-sqlite3": "^12.6.2",
+    "sqlite-vec": "^0.1.7-alpha.2",
+    "ulid": "^3.0.2",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "vitest": "^4.0.18"
+  }
+}

package/src/audrey.js

@@ -0,0 +1,179 @@
+import { EventEmitter } from 'node:events';
+import { createDatabase, closeDatabase } from './db.js';
+import { createEmbeddingProvider } from './embedding.js';
+import { createLLMProvider } from './llm.js';
+import { encodeEpisode } from './encode.js';
+import { recall as recallFn, recallStream as recallStreamFn } from './recall.js';
+import { validateMemory } from './validate.js';
+import { runConsolidation } from './consolidate.js';
+import { applyDecay } from './decay.js';
+import { rollbackConsolidation, getConsolidationHistory } from './rollback.js';
+import { introspect as introspectFn } from './introspect.js';
+import { buildContextResolutionPrompt } from './prompts.js';
+
+export class Audrey extends EventEmitter {
+  constructor({
+    dataDir = './audrey-data',
+    agent = 'default',
+    embedding = { provider: 'mock', dimensions: 64 },
+    llm,
+    consolidation = {},
+    decay = {},
+  } = {}) {
+    super();
+    this.agent = agent;
+    this.dataDir = dataDir;
+    this.embeddingProvider = createEmbeddingProvider(embedding);
+    this.db = createDatabase(dataDir, { dimensions: this.embeddingProvider.dimensions });
+    this.llmProvider = llm ? createLLMProvider(llm) : null;
+    this.consolidationConfig = {
+      minEpisodes: consolidation.minEpisodes || 3,
+    };
+    this.decayConfig = { dormantThreshold: decay.dormantThreshold || 0.1 };
+  }
+
+  _emitValidation(id, params) {
+    validateMemory(this.db, this.embeddingProvider, { id, ...params }, {
+      llmProvider: this.llmProvider,
+    })
+      .then(validation => {
+        if (validation.action === 'reinforced') {
+          this.emit('reinforcement', {
+            episodeId: id,
+            targetId: validation.semanticId,
+            similarity: validation.similarity,
+          });
+        } else if (validation.action === 'contradiction') {
+          this.emit('contradiction', {
+            episodeId: id,
+            contradictionId: validation.contradictionId,
+            semanticId: validation.semanticId,
+            similarity: validation.similarity,
+            resolution: validation.resolution,
+          });
+        }
+      })
+      .catch(err => this.emit('error', err));
+  }
+
+  async encode(params) {
+    const id = await encodeEpisode(this.db, this.embeddingProvider, params);
+    this.emit('encode', { id, ...params });
+    this._emitValidation(id, params);
+    return id;
+  }
+
+  async encodeBatch(paramsList) {
+    const ids = [];
+    for (const params of paramsList) {
+      const id = await encodeEpisode(this.db, this.embeddingProvider, params);
+      ids.push(id);
+      this.emit('encode', { id, ...params });
+    }
+
+    for (let i = 0; i < ids.length; i++) {
+      this._emitValidation(ids[i], paramsList[i]);
+    }
+
+    return ids;
+  }
+
+  recall(query, options = {}) {
+    return recallFn(this.db, this.embeddingProvider, query, options);
+  }
+
+  async *recallStream(query, options = {}) {
+    yield* recallStreamFn(this.db, this.embeddingProvider, query, options);
+  }
+
+  async consolidate(options = {}) {
+    const result = await runConsolidation(this.db, this.embeddingProvider, {
+      minClusterSize: options.minClusterSize || this.consolidationConfig.minEpisodes,
+      similarityThreshold: options.similarityThreshold || 0.80,
+      extractPrinciple: options.extractPrinciple,
+      llmProvider: options.llmProvider || this.llmProvider,
+    });
+    const run = this.db.prepare('SELECT status FROM consolidation_runs WHERE id = ?').get(result.runId);
+    const output = { ...result, status: run?.status || 'completed' };
+    this.emit('consolidation', output);
+    return output;
+  }
+
+  decay(options = {}) {
+    const result = applyDecay(this.db, {
+      dormantThreshold: options.dormantThreshold || this.decayConfig.dormantThreshold,
+    });
+    this.emit('decay', result);
+    return result;
+  }
+
+  rollback(runId) {
+    const result = rollbackConsolidation(this.db, runId);
+    this.emit('rollback', { runId, ...result });
+    return result;
+  }
+
+  async resolveTruth(contradictionId) {
+    if (!this.llmProvider) {
+      throw new Error('resolveTruth requires an LLM provider');
+    }
+
+    const contradiction = this.db.prepare(
+      'SELECT * FROM contradictions WHERE id = ?'
+    ).get(contradictionId);
+    if (!contradiction) throw new Error(`Contradiction not found: ${contradictionId}`);
+
+    const claimA = this._loadClaimContent(contradiction.claim_a_id, contradiction.claim_a_type);
+    const claimB = this._loadClaimContent(contradiction.claim_b_id, contradiction.claim_b_type);
+
+    const messages = buildContextResolutionPrompt(claimA, claimB);
+    const result = await this.llmProvider.json(messages);
+
+    const now = new Date().toISOString();
+    const newState = result.resolution === 'context_dependent' ? 'context_dependent' : 'resolved';
+    this.db.prepare(`
+      UPDATE contradictions SET state = ?, resolution = ?, resolved_at = ?
+      WHERE id = ?
+    `).run(newState, JSON.stringify(result), now, contradictionId);
+
+    if (result.resolution === 'a_wins' && contradiction.claim_a_type === 'semantic') {
+      this.db.prepare("UPDATE semantics SET state = 'active' WHERE id = ?").run(contradiction.claim_a_id);
+    }
+    if (result.resolution === 'b_wins' && contradiction.claim_b_type === 'semantic') {
+      this.db.prepare("UPDATE semantics SET state = 'active' WHERE id = ?").run(contradiction.claim_b_id);
+    }
+    if (result.resolution === 'context_dependent') {
+      if (contradiction.claim_a_type === 'semantic' && result.conditions) {
+        this.db.prepare("UPDATE semantics SET state = 'context_dependent', conditions = ? WHERE id = ?")
+          .run(JSON.stringify(result.conditions), contradiction.claim_a_id);
+      }
+    }
+
+    return result;
+  }
+
+  _loadClaimContent(claimId, claimType) {
+    if (claimType === 'semantic') {
+      const row = this.db.prepare('SELECT content FROM semantics WHERE id = ?').get(claimId);
+      if (!row) throw new Error(`Semantic memory not found: ${claimId}`);
+      return row.content;
+    } else if (claimType === 'episodic') {
+      const row = this.db.prepare('SELECT content FROM episodes WHERE id = ?').get(claimId);
+      if (!row) throw new Error(`Episode not found: ${claimId}`);
+      return row.content;
+    }
+    throw new Error(`Unknown claim type: ${claimType}`);
+  }
+
+  consolidationHistory() {
+    return getConsolidationHistory(this.db);
+  }
+
+  introspect() {
+    return introspectFn(this.db);
+  }
+
+  close() {
+    closeDatabase(this.db);
+  }
+}

package/src/causal.js

@@ -0,0 +1,77 @@
+import { generateId } from './ulid.js';
+import { buildCausalArticulationPrompt } from './prompts.js';
+
+export function addCausalLink(db, { causeId, effectId, linkType = 'causal', mechanism, confidence }) {
+  const id = generateId();
+  const now = new Date().toISOString();
+
+  db.prepare(`
+    INSERT INTO causal_links (id, cause_id, effect_id, link_type, mechanism, confidence, created_at)
+    VALUES (?, ?, ?, ?, ?, ?, ?)
+  `).run(id, causeId, effectId, linkType, mechanism, confidence, now);
+
+  return id;
+}
+
+export function getCausalChain(db, memoryId, options = {}) {
+  const { depth = 10 } = options;
+  const results = [];
+  const visited = new Set();
+  const queue = [memoryId];
+  let currentDepth = 0;
+
+  while (queue.length > 0 && currentDepth < depth) {
+    const nextQueue = [];
+    for (const nodeId of queue) {
+      if (visited.has(nodeId)) continue;
+      visited.add(nodeId);
+
+      const links = db.prepare(
+        'SELECT * FROM causal_links WHERE cause_id = ?'
+      ).all(nodeId);
+
+      for (const link of links) {
+        if (!visited.has(link.effect_id)) {
+          results.push(link);
+          nextQueue.push(link.effect_id);
+        }
+      }
+    }
+    queue.length = 0;
+    queue.push(...nextQueue);
+    currentDepth++;
+  }
+
+  return results;
+}
+
+export async function articulateCausalLink(db, llmProvider, cause, effect) {
+  const messages = buildCausalArticulationPrompt(cause, effect);
+  const result = await llmProvider.json(messages);
+
+  if (result.spurious) {
+    return {
+      linkId: null,
+      mechanism: result.mechanism,
+      linkType: result.linkType,
+      confidence: result.confidence,
+      spurious: true,
+    };
+  }
+
+  const linkId = addCausalLink(db, {
+    causeId: cause.id,
+    effectId: effect.id,
+    linkType: result.linkType || 'correlational',
+    mechanism: result.mechanism,
+    confidence: result.confidence,
+  });
+
+  return {
+    linkId,
+    mechanism: result.mechanism,
+    linkType: result.linkType,
+    confidence: result.confidence,
+    spurious: false,
+  };
+}

package/src/confidence.js

@@ -0,0 +1,75 @@
+export const DEFAULT_SOURCE_RELIABILITY = {
+  'direct-observation': 0.95,
+  'told-by-user': 0.90,
+  'tool-result': 0.85,
+  'inference': 0.60,
+  'model-generated': 0.40,
+};
+
+export const DEFAULT_WEIGHTS = {
+  source: 0.30,
+  evidence: 0.35,
+  recency: 0.20,
+  retrieval: 0.15,
+};
+
+export const DEFAULT_HALF_LIVES = {
+  episodic: 7,
+  semantic: 30,
+  procedural: 90,
+};
+
+export const MODEL_GENERATED_CONFIDENCE_CAP = 0.6;
+
+export function sourceReliability(sourceType, customReliability) {
+  const table = customReliability || DEFAULT_SOURCE_RELIABILITY;
+  const value = table[sourceType];
+  if (value === undefined) {
+    throw new Error(`Unknown source type: ${sourceType}. Valid types: ${Object.keys(table).join(', ')}`);
+  }
+  return value;
+}
+
+export function evidenceAgreement(supportingCount, contradictingCount) {
+  const total = supportingCount + contradictingCount;
+  if (total === 0) return 1.0;
+  return supportingCount / total;
+}
+
+export function recencyDecay(ageDays, halfLifeDays) {
+  const lambda = Math.LN2 / halfLifeDays;
+  return Math.exp(-lambda * ageDays);
+}
+
+export function retrievalReinforcement(retrievalCount, daysSinceRetrieval) {
+  if (retrievalCount === 0) return 0;
+  const lambdaRet = Math.LN2 / 14; // 14-day half-life for retrieval decay
+  return Math.min(1.0, 0.3 * Math.log(1 + retrievalCount) * Math.exp(-lambdaRet * daysSinceRetrieval));
+}
+
+export function computeConfidence({
+  sourceType,
+  supportingCount,
+  contradictingCount,
+  ageDays,
+  halfLifeDays,
+  retrievalCount,
+  daysSinceRetrieval,
+  weights,
+  customSourceReliability,
+}) {
+  const w = weights || DEFAULT_WEIGHTS;
+
+  const s = sourceReliability(sourceType, customSourceReliability);
+  const e = evidenceAgreement(supportingCount, contradictingCount);
+  const r = recencyDecay(ageDays, halfLifeDays);
+  const ret = retrievalReinforcement(retrievalCount, daysSinceRetrieval);
+
+  let confidence = w.source * s + w.evidence * e + w.recency * r + w.retrieval * ret;
+
+  if (sourceType === 'model-generated') {
+    confidence = Math.min(confidence, MODEL_GENERATED_CONFIDENCE_CAP);
+  }
+
+  return Math.max(0, Math.min(1, confidence));
+}

package/src/consolidate.js

@@ -0,0 +1,219 @@
+import { generateId } from './ulid.js';
+import { buildPrincipleExtractionPrompt } from './prompts.js';
+
+function clusterViaKNN(db, episodes, similarityThreshold, minClusterSize) {
+  const n = episodes.length;
+  const k = Math.min(50, n);
+  const idToIndex = new Map(episodes.map((ep, i) => [ep.id, i]));
+
+  const parent = new Array(n);
+  for (let i = 0; i < n; i++) parent[i] = i;
+
+  function find(x) {
+    while (parent[x] !== x) {
+      parent[x] = parent[parent[x]];
+      x = parent[x];
+    }
+    return x;
+  }
+
+  function union(a, b) {
+    const ra = find(a);
+    const rb = find(b);
+    if (ra !== rb) parent[ra] = rb;
+  }
+
+  const getEmbedding = db.prepare('SELECT embedding FROM vec_episodes WHERE id = ?');
+  const knnQuery = db.prepare(`
+    SELECT id, distance
+    FROM vec_episodes
+    WHERE embedding MATCH ? AND k = ? AND consolidated = 0
+  `);
+
+  for (let i = 0; i < n; i++) {
+    const ep = episodes[i];
+    const vecRow = getEmbedding.get(ep.id);
+    if (!vecRow) continue;
+
+    const neighbors = knnQuery.all(vecRow.embedding, k);
+    for (const neighbor of neighbors) {
+      if (neighbor.id === ep.id) continue;
+      const j = idToIndex.get(neighbor.id);
+      if (j === undefined) continue;
+      const similarity = 1.0 - neighbor.distance;
+      if (similarity >= similarityThreshold) {
+        union(i, j);
+      }
+    }
+  }
+
+  const groups = new Map();
+  for (let i = 0; i < n; i++) {
+    const root = find(i);
+    if (!groups.has(root)) groups.set(root, []);
+    groups.get(root).push(episodes[i]);
+  }
+
+  const clusters = [];
+  for (const group of groups.values()) {
+    if (group.length >= minClusterSize) {
+      clusters.push(group);
+    }
+  }
+  return clusters;
+}
+
+export function clusterEpisodes(db, embeddingProvider, options = {}) {
+  const {
+    similarityThreshold = 0.85,
+    minClusterSize = 3,
+  } = options;
+
+  const episodes = db.prepare(
+    'SELECT * FROM episodes WHERE consolidated = 0 AND superseded_by IS NULL AND embedding IS NOT NULL'
+  ).all();
+
+  if (episodes.length === 0) return [];
+
+  return clusterViaKNN(db, episodes, similarityThreshold, minClusterSize);
+}
+
+function defaultExtractPrinciple(episodes) {
+  const uniqueContents = [...new Set(episodes.map(e => e.content))];
+  return {
+    content: `Recurring pattern: ${uniqueContents.join('; ')}`,
+    type: 'semantic',
+  };
+}
+
+async function llmExtractPrinciple(llmProvider, episodes) {
+  const messages = buildPrincipleExtractionPrompt(episodes);
+  return llmProvider.json(messages);
+}
+
+export async function runConsolidation(db, embeddingProvider, options = {}) {
+  const {
+    similarityThreshold = 0.85,
+    minClusterSize = 3,
+    extractPrinciple,
+    llmProvider,
+  } = options;
+
+  const runId = generateId();
+  const now = new Date().toISOString();
+
+  db.prepare(`
+    INSERT INTO consolidation_runs (id, started_at, status, input_episode_ids, output_memory_ids, consolidation_model)
+    VALUES (?, ?, 'running', '[]', '[]', ?)
+  `).run(runId, now, llmProvider?.modelName || null);
+
+  try {
+    const clusters = clusterEpisodes(db, embeddingProvider, { similarityThreshold, minClusterSize });
+
+    const episodesEvaluated = db.prepare(
+      'SELECT COUNT(*) as count FROM episodes WHERE consolidated = 0 AND superseded_by IS NULL AND embedding IS NOT NULL'
+    ).get().count;
+
+    const clusterData = [];
+    for (const cluster of clusters) {
+      let principle;
+      if (extractPrinciple) {
+        principle = extractPrinciple(cluster);
+      } else if (llmProvider) {
+        principle = await llmExtractPrinciple(llmProvider, cluster);
+      } else {
+        principle = defaultExtractPrinciple(cluster);
+      }
+
+      if (!principle || !principle.content) continue;
+
+      const clusterIds = cluster.map(ep => ep.id);
+      const sourceTypes = new Set(cluster.map(ep => ep.source));
+      const vector = await embeddingProvider.embed(principle.content);
+      const embeddingBuffer = embeddingProvider.vectorToBuffer(vector);
+
+      clusterData.push({
+        cluster,
+        principle,
+        clusterIds,
+        sourceTypeDiversity: sourceTypes.size,
+        embeddingBuffer,
+        semanticId: generateId(),
+        semanticNow: new Date().toISOString(),
+      });
+    }
+
+    const allInputIds = [];
+    const allOutputIds = [];
+    let principlesExtracted = 0;
+
+    const promoteAll = db.transaction(() => {
+      for (const entry of clusterData) {
+        allInputIds.push(...entry.clusterIds);
+
+        db.prepare(`
+          INSERT INTO semantics (
+            id, content, embedding, state, evidence_episode_ids,
+            evidence_count, supporting_count, source_type_diversity,
+            consolidation_checkpoint, embedding_model, embedding_version,
+            consolidation_model, created_at
+          ) VALUES (?, ?, ?, 'active', ?, ?, ?, ?, ?, ?, ?, ?, ?)
+        `).run(
+          entry.semanticId,
+          entry.principle.content,
+          entry.embeddingBuffer,
+          JSON.stringify(entry.clusterIds),
+          entry.cluster.length,
+          entry.cluster.length,
+          entry.sourceTypeDiversity,
+          runId,
+          embeddingProvider.modelName,
+          embeddingProvider.modelVersion,
+          llmProvider?.modelName || null,
+          entry.semanticNow,
+        );
+
+        db.prepare('INSERT INTO vec_semantics(id, embedding, state) VALUES (?, ?, ?)').run(
+          entry.semanticId, entry.embeddingBuffer, 'active'
+        );
+
+        allOutputIds.push(entry.semanticId);
+        principlesExtracted++;
+
+        const markStmt = db.prepare('UPDATE episodes SET consolidated = 1 WHERE id = ?');
+        const markVecStmt = db.prepare('UPDATE vec_episodes SET consolidated = ? WHERE id = ?');
+        for (const ep of entry.cluster) {
+          markStmt.run(ep.id);
+          markVecStmt.run(BigInt(1), ep.id);
+        }
+      }
+
+      const completedAt = new Date().toISOString();
+      db.prepare(`
+        UPDATE consolidation_runs
+        SET status = 'completed',
+            completed_at = ?,
+            input_episode_ids = ?,
+            output_memory_ids = ?
+        WHERE id = ?
+      `).run(completedAt, JSON.stringify(allInputIds), JSON.stringify(allOutputIds), runId);
+    });
+
+    promoteAll();
+
+    return {
+      runId,
+      episodesEvaluated,
+      clustersFound: clusters.length,
+      principlesExtracted,
+    };
+  } catch (err) {
+    const failedAt = new Date().toISOString();
+    db.prepare(`
+      UPDATE consolidation_runs
+      SET status = 'failed', completed_at = ?
+      WHERE id = ?
+    `).run(failedAt, runId);
+    throw err;
+  }
+}