audrey 0.8.0 → 0.11.0

package/src/embedding.js

@@ -11,33 +11,14 @@ import { createHash } from 'node:crypto';
  * @property {(buffer: Buffer) => number[]} bufferToVector
  */
 
-/**
- * @typedef {Object} MockEmbeddingConfig
- * @property {'mock'} provider
- * @property {number} [dimensions=64]
- */
-
-/**
- * @typedef {Object} OpenAIEmbeddingConfig
- * @property {'openai'} provider
- * @property {string} [apiKey]
- * @property {string} [model='text-embedding-3-small']
- * @property {number} [dimensions=1536]
- */
-
 /** @implements {EmbeddingProvider} */
 export class MockEmbeddingProvider {
-  /** @param {Partial<MockEmbeddingConfig>} [config={}] */
   constructor({ dimensions = 64 } = {}) {
     this.dimensions = dimensions;
     this.modelName = 'mock-embedding';
     this.modelVersion = '1.0.0';
   }
 
-  /**
-   * @param {string} text
-   * @returns {Promise<number[]>}
-   */
   async embed(text) {
     const hash = createHash('sha256').update(text).digest();
     const vector = new Array(this.dimensions);
@@ -48,26 +29,14 @@ export class MockEmbeddingProvider {
     return vector.map(v => v / magnitude);
   }
 
-  /**
-   * @param {string[]} texts
-   * @returns {Promise<number[][]>}
-   */
   async embedBatch(texts) {
     return Promise.all(texts.map(t => this.embed(t)));
   }
 
-  /**
-   * @param {number[]} vector
-   * @returns {Buffer}
-   */
   vectorToBuffer(vector) {
     return Buffer.from(new Float32Array(vector).buffer);
   }
 
-  /**
-   * @param {Buffer} buffer
-   * @returns {number[]}
-   */
   bufferToVector(buffer) {
     return Array.from(new Float32Array(buffer.buffer, buffer.byteOffset, buffer.byteLength / 4));
   }
@@ -75,7 +44,6 @@ export class MockEmbeddingProvider {
 
 /** @implements {EmbeddingProvider} */
 export class OpenAIEmbeddingProvider {
-  /** @param {Partial<OpenAIEmbeddingConfig>} [config={}] */
   constructor({ apiKey, model = 'text-embedding-3-small', dimensions = 1536, timeout = 30000 } = {}) {
     this.apiKey = apiKey || process.env.OPENAI_API_KEY;
     this.model = model;
@@ -85,10 +53,6 @@ export class OpenAIEmbeddingProvider {
     this.modelVersion = 'latest';
   }
 
-  /**
-   * @param {string} text
-   * @returns {Promise<number[]>}
-   */
   async embed(text) {
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), this.timeout);
@@ -110,10 +74,6 @@ export class OpenAIEmbeddingProvider {
     }
   }
 
-  /**
-   * @param {string[]} texts
-   * @returns {Promise<number[][]>}
-   */
   async embedBatch(texts) {
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), this.timeout);
@@ -135,34 +95,111 @@ export class OpenAIEmbeddingProvider {
     }
   }
 
-  /**
-   * @param {number[]} vector
-   * @returns {Buffer}
-   */
   vectorToBuffer(vector) {
     return Buffer.from(new Float32Array(vector).buffer);
   }
 
-  /**
-   * @param {Buffer} buffer
-   * @returns {number[]}
-   */
   bufferToVector(buffer) {
     return Array.from(new Float32Array(buffer.buffer, buffer.byteOffset, buffer.byteLength / 4));
   }
 }
 
-/**
- * @param {MockEmbeddingConfig | OpenAIEmbeddingConfig} config
- * @returns {MockEmbeddingProvider | OpenAIEmbeddingProvider}
- */
+/** @implements {EmbeddingProvider} */
+export class LocalEmbeddingProvider {
+  constructor({ model = 'Xenova/all-MiniLM-L6-v2' } = {}) {
+    this.model = model;
+    this.dimensions = 384;
+    this.modelName = model;
+    this.modelVersion = '1.0.0';
+    this._pipeline = null;
+    this._readyPromise = null;
+  }
+
+  ready() {
+    if (!this._readyPromise) {
+      this._readyPromise = import('@huggingface/transformers').then(({ pipeline }) =>
+        pipeline('feature-extraction', this.model, { dtype: 'fp32' })
+      ).then(pipe => { this._pipeline = pipe; });
+    }
+    return this._readyPromise;
+  }
+
+  async embed(text) {
+    await this.ready();
+    const output = await this._pipeline(text, { pooling: 'mean', normalize: true });
+    return Array.from(output.data);
+  }
+
+  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));
+  }
+}
+
+/** @implements {EmbeddingProvider} */
+export class GeminiEmbeddingProvider {
+  constructor({ apiKey, model = 'gemini-embedding-001', timeout = 30000 } = {}) {
+    this.apiKey = apiKey || process.env.GOOGLE_API_KEY;
+    this.model = model;
+    this.dimensions = 3072;
+    this.timeout = timeout;
+    this.modelName = model;
+    this.modelVersion = 'latest';
+  }
+
+  async embed(text) {
+    if (!this.apiKey) throw new Error('Gemini embedding requires GOOGLE_API_KEY');
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeout);
+    try {
+      const response = await fetch(
+        `https://generativelanguage.googleapis.com/v1beta/models/${this.model}:embedContent?key=${this.apiKey}`,
+        {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({ model: `models/${this.model}`, content: { parts: [{ text }] } }),
+          signal: controller.signal,
+        }
+      );
+      if (!response.ok) throw new Error(`Gemini embedding failed: ${response.status}`);
+      const data = await response.json();
+      return data.embedding.values;
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  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 function createEmbeddingProvider(config) {
   switch (config.provider) {
     case 'mock':
       return new MockEmbeddingProvider(config);
     case 'openai':
       return new OpenAIEmbeddingProvider(config);
+    case 'local':
+      return new LocalEmbeddingProvider(config);
+    case 'gemini':
+      return new GeminiEmbeddingProvider(config);
     default:
-      throw new Error(`Unknown embedding provider: ${config.provider}. Valid: mock, openai`);
+      throw new Error(`Unknown embedding provider: ${config.provider}. Valid: mock, openai, local, gemini`);
   }
 }

package/src/encode.js

@@ -1,54 +1,63 @@
-import { generateId } from './ulid.js';
-import { sourceReliability } from './confidence.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 }} params
- * @returns {Promise<string>}
- */
-export async function encodeEpisode(db, embeddingProvider, {
-  content,
-  source,
-  salience = 0.5,
-  causal,
-  tags,
-  supersedes,
-  context = {},
-}) {
-  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, context,
-        tags, causal_trigger, causal_consequence, created_at,
-        embedding_model, embedding_version, supersedes
-      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-    `).run(
-      id, content, embeddingBuffer, source, reliability, salience,
-      JSON.stringify(context),
-      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;
-}
+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;
+}

package/src/export.js

@@ -8,21 +8,23 @@ const pkg = JSON.parse(readFileSync(join(__dirname, '../package.json'), 'utf-8')
 
 export function exportMemories(db) {
   const episodes = db.prepare(
-    'SELECT id, content, source, source_reliability, salience, tags, causal_trigger, causal_consequence, created_at, supersedes, superseded_by, consolidated FROM episodes'
+    'SELECT id, content, source, source_reliability, salience, context, affect, tags, causal_trigger, causal_consequence, created_at, supersedes, superseded_by, consolidated, "private" FROM episodes'
   ).all().map(ep => ({
     ...ep,
     tags: safeJsonParse(ep.tags, null),
+    context: safeJsonParse(ep.context, null),
+    affect: safeJsonParse(ep.affect, null),
   }));
 
   const semantics = db.prepare(
-    'SELECT id, content, state, conditions, evidence_episode_ids, evidence_count, supporting_count, contradicting_count, source_type_diversity, consolidation_checkpoint, created_at, last_reinforced_at, retrieval_count, challenge_count FROM semantics'
+    'SELECT id, content, state, conditions, evidence_episode_ids, evidence_count, supporting_count, contradicting_count, source_type_diversity, consolidation_checkpoint, created_at, last_reinforced_at, retrieval_count, challenge_count, interference_count, salience FROM semantics'
   ).all().map(sem => ({
     ...sem,
     evidence_episode_ids: safeJsonParse(sem.evidence_episode_ids, []),
   }));
 
   const procedures = db.prepare(
-    'SELECT id, content, state, trigger_conditions, evidence_episode_ids, success_count, failure_count, created_at, last_reinforced_at, retrieval_count FROM procedures'
+    'SELECT id, content, state, trigger_conditions, evidence_episode_ids, success_count, failure_count, created_at, last_reinforced_at, retrieval_count, interference_count, salience FROM procedures'
   ).all().map(proc => ({
     ...proc,
     evidence_episode_ids: safeJsonParse(proc.evidence_episode_ids, []),

package/src/import.js

@@ -5,9 +5,9 @@ export async function importMemories(db, embeddingProvider, snapshot) {
   }
 
   const insertEpisode = db.prepare(`
-    INSERT INTO episodes (id, content, source, source_reliability, salience, tags,
-      causal_trigger, causal_consequence, created_at, supersedes, superseded_by, consolidated)
-    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    INSERT INTO episodes (id, content, source, source_reliability, salience, context, affect, tags,
+      causal_trigger, causal_consequence, created_at, supersedes, superseded_by, consolidated, "private")
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
   `);
 
   const insertVecEpisode = db.prepare(
@@ -17,8 +17,9 @@ export async function importMemories(db, embeddingProvider, snapshot) {
   const insertSemantic = db.prepare(`
     INSERT INTO semantics (id, content, state, conditions, evidence_episode_ids,
       evidence_count, supporting_count, contradicting_count, source_type_diversity,
-      consolidation_checkpoint, created_at, last_reinforced_at, retrieval_count, challenge_count)
-    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      consolidation_checkpoint, created_at, last_reinforced_at, retrieval_count, challenge_count,
+      interference_count, salience)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
   `);
 
   const insertVecSemantic = db.prepare(
@@ -27,8 +28,9 @@ export async function importMemories(db, embeddingProvider, snapshot) {
 
   const insertProcedure = db.prepare(`
     INSERT INTO procedures (id, content, state, trigger_conditions, evidence_episode_ids,
-      success_count, failure_count, created_at, last_reinforced_at, retrieval_count)
-    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      success_count, failure_count, created_at, last_reinforced_at, retrieval_count,
+      interference_count, salience)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
   `);
 
   const insertVecProcedure = db.prepare(
@@ -53,10 +55,13 @@ export async function importMemories(db, embeddingProvider, snapshot) {
 
   for (const ep of snapshot.episodes) {
     const tags = ep.tags ? JSON.stringify(ep.tags) : null;
+    const context = ep.context ? JSON.stringify(ep.context) : '{}';
+    const affect = ep.affect ? JSON.stringify(ep.affect) : '{}';
     insertEpisode.run(
       ep.id, ep.content, ep.source, ep.source_reliability, ep.salience ?? 0.5,
-      tags, ep.causal_trigger ?? null, ep.causal_consequence ?? null,
+      context, affect, tags, ep.causal_trigger ?? null, ep.causal_consequence ?? null,
       ep.created_at, ep.supersedes ?? null, ep.superseded_by ?? null, ep.consolidated ?? 0,
+      ep.private ?? 0,
     );
 
     const vector = await embeddingProvider.embed(ep.content);
@@ -71,6 +76,7 @@ export async function importMemories(db, embeddingProvider, snapshot) {
       sem.evidence_count ?? 0, sem.supporting_count ?? 0, sem.contradicting_count ?? 0,
       sem.source_type_diversity ?? 0, sem.consolidation_checkpoint ?? null,
       sem.created_at, sem.last_reinforced_at ?? null, sem.retrieval_count ?? 0, sem.challenge_count ?? 0,
+      sem.interference_count ?? 0, sem.salience ?? 0.5,
     );
 
     const vector = await embeddingProvider.embed(sem.content);
@@ -84,6 +90,7 @@ export async function importMemories(db, embeddingProvider, snapshot) {
       JSON.stringify(proc.evidence_episode_ids || []),
       proc.success_count ?? 0, proc.failure_count ?? 0,
       proc.created_at, proc.last_reinforced_at ?? null, proc.retrieval_count ?? 0,
+      proc.interference_count ?? 0, proc.salience ?? 0.5,
     );
 
     const vector = await embeddingProvider.embed(proc.content);

package/src/index.js

@@ -17,3 +17,4 @@ export { reembedAll } from './migrate.js';
 export { forgetMemory, forgetByQuery, purgeMemories } from './forget.js';
 export { applyInterference, interferenceModifier } from './interference.js';
 export { contextMatchRatio, contextModifier } from './context.js';
+export { arousalSalienceBoost, affectSimilarity, moodCongruenceModifier, detectResonance } from './affect.js';

package/src/migrate.js

@@ -1,4 +1,11 @@
-export async function reembedAll(db, embeddingProvider) {
+import { dropVec0Tables, createVec0Tables } from './db.js';
+
+export async function reembedAll(db, embeddingProvider, { dropAndRecreate = false } = {}) {
+  if (dropAndRecreate) {
+    dropVec0Tables(db);
+    createVec0Tables(db, embeddingProvider.dimensions);
+  }
+
   const episodes = db.prepare('SELECT id, content, source FROM episodes').all();
   const semantics = db.prepare('SELECT id, content, state FROM semantics').all();
   const procedures = db.prepare('SELECT id, content, state FROM procedures').all();
@@ -7,26 +14,37 @@ export async function reembedAll(db, embeddingProvider) {
     const vector = await embeddingProvider.embed(ep.content);
     const buffer = embeddingProvider.vectorToBuffer(vector);
     db.prepare('UPDATE episodes SET embedding = ? WHERE id = ?').run(buffer, ep.id);
-    db.prepare('INSERT INTO vec_episodes(id, embedding, source, consolidated) VALUES (?, ?, ?, ?)').run(ep.id, buffer, ep.source, BigInt(0));
+    const exists = db.prepare('SELECT id FROM vec_episodes WHERE id = ?').get(ep.id);
+    if (!exists) {
+      db.prepare('INSERT INTO vec_episodes(id, embedding, source, consolidated) VALUES (?, ?, ?, ?)').run(ep.id, buffer, ep.source, BigInt(0));
+    } else {
+      db.prepare('UPDATE vec_episodes SET embedding = ? WHERE id = ?').run(buffer, ep.id);
+    }
   }
 
   for (const sem of semantics) {
     const vector = await embeddingProvider.embed(sem.content);
     const buffer = embeddingProvider.vectorToBuffer(vector);
     db.prepare('UPDATE semantics SET embedding = ? WHERE id = ?').run(buffer, sem.id);
-    db.prepare('INSERT INTO vec_semantics(id, embedding, state) VALUES (?, ?, ?)').run(sem.id, buffer, sem.state);
+    const exists = db.prepare('SELECT id FROM vec_semantics WHERE id = ?').get(sem.id);
+    if (!exists) {
+      db.prepare('INSERT INTO vec_semantics(id, embedding, state) VALUES (?, ?, ?)').run(sem.id, buffer, sem.state);
+    } else {
+      db.prepare('UPDATE vec_semantics SET embedding = ? WHERE id = ?').run(buffer, sem.id);
+    }
   }
 
   for (const proc of procedures) {
     const vector = await embeddingProvider.embed(proc.content);
     const buffer = embeddingProvider.vectorToBuffer(vector);
     db.prepare('UPDATE procedures SET embedding = ? WHERE id = ?').run(buffer, proc.id);
-    db.prepare('INSERT INTO vec_procedures(id, embedding, state) VALUES (?, ?, ?)').run(proc.id, buffer, proc.state);
+    const exists = db.prepare('SELECT id FROM vec_procedures WHERE id = ?').get(proc.id);
+    if (!exists) {
+      db.prepare('INSERT INTO vec_procedures(id, embedding, state) VALUES (?, ?, ?)').run(proc.id, buffer, proc.state);
+    } else {
+      db.prepare('UPDATE vec_procedures SET embedding = ? WHERE id = ?').run(buffer, proc.id);
+    }
   }
 
-  return {
-    episodes: episodes.length,
-    semantics: semantics.length,
-    procedures: procedures.length,
-  };
+  return { episodes: episodes.length, semantics: semantics.length, procedures: procedures.length };
 }

package/src/prompts.js

@@ -152,3 +152,46 @@ CLAIM B: ${claimB}${contextSection}`,
     },
   ];
 }
+
+/**
+ * @param {{ role: string, content: string }[]} turns
+ * @returns {import('./llm.js').ChatMessage[]}
+ */
+export function buildReflectionPrompt(turns) {
+  const transcript = turns.map(t => `${t.role.toUpperCase()}: ${t.content}`).join('\n\n');
+
+  return [
+    {
+      role: 'system',
+      content: `You are performing memoryReflection. Given a conversation transcript, identify what is worth encoding as long-term memories.
+
+Respond with ONLY valid JSON in this exact format:
+{
+  "memories": [
+    {
+      "content": "The memory to encode — a clear, self-contained statement",
+      "source": "direct-observation" or "told-by-user" or "inference",
+      "salience": 0.0 to 1.0,
+      "tags": ["tag1", "tag2"],
+      "private": true or false,
+      "affect": { "valence": -1 to 1, "arousal": 0 to 1, "label": "emotion label" } or null
+    }
+  ]
+}
+
+Rules:
+- Encode facts about the user, decisions made, things that shifted
+- Mark private: true for AI self-observations, emotional reactions, things felt but not said
+- Mark private: false for facts about the user and project context
+- Omit trivial exchanges — only encode what would matter in a future session
+- Salience: 1.0 = extremely important, 0.5 = useful, 0.3 = background context
+- Return empty memories array if nothing is worth encoding`,
+    },
+    {
+      role: 'user',
+      content: turns.length > 0
+        ? `Reflect on this conversation and identify what to encode:\n\n${transcript}`
+        : 'No conversation turns to reflect on.',
+    },
+  ];
+}

package/src/recall.js

@@ -1,6 +1,7 @@
 import { computeConfidence, DEFAULT_HALF_LIVES, salienceModifier } from './confidence.js';
 import { interferenceModifier } from './interference.js';
 import { contextMatchRatio, contextModifier } from './context.js';
+import { moodCongruenceModifier, affectSimilarity } from './affect.js';
 import { daysBetween, safeJsonParse } from './utils.js';
 
 function computeEpisodicConfidence(ep, now, confidenceConfig = {}) {
@@ -65,7 +66,7 @@ function computeProceduralConfidence(proc, now, confidenceConfig = {}) {
   return Math.max(0, Math.min(1, confidence));
 }
 
-function buildEpisodicEntry(ep, confidence, score, includeProvenance, contextMatch) {
+function buildEpisodicEntry(ep, confidence, score, includeProvenance, contextMatch, moodCongruence) {
   const entry = {
     id: ep.id,
     content: ep.content,
@@ -78,6 +79,9 @@ function buildEpisodicEntry(ep, confidence, score, includeProvenance, contextMat
   if (contextMatch !== undefined) {
     entry.contextMatch = contextMatch;
   }
+  if (moodCongruence !== undefined) {
+    entry.moodCongruence = moodCongruence;
+  }
   if (includeProvenance) {
     entry.provenance = {
       source: ep.source,
@@ -146,7 +150,8 @@ function matchesDateFilters(createdAt, filters) {
   return true;
 }
 
-function knnEpisodic(db, queryBuffer, candidateK, now, minConfidence, includeProvenance, confidenceConfig, filters = {}) {
+function knnEpisodic(db, queryBuffer, candidateK, now, minConfidence, includeProvenance, confidenceConfig, filters = {}, includePrivate = false) {
+  const privateClause = includePrivate ? '' : 'AND e."private" = 0';
   const rows = db.prepare(`
     SELECT e.*, (1.0 - v.distance) AS similarity
     FROM vec_episodes v
@@ -154,6 +159,7 @@ function knnEpisodic(db, queryBuffer, candidateK, now, minConfidence, includePro
     WHERE v.embedding MATCH ?
       AND k = ?
       AND e.superseded_by IS NULL
+      ${privateClause}
   `).all(queryBuffer, candidateK);
 
   const results = [];
@@ -174,9 +180,17 @@ function knnEpisodic(db, queryBuffer, candidateK, now, minConfidence, includePro
       confidence = Math.max(0, Math.min(1, confidence));
     }
 
+    let moodMatch;
+    if (confidenceConfig?.retrievalMood) {
+      const encodingAffect = safeJsonParse(row.affect, {});
+      moodMatch = affectSimilarity(encodingAffect, confidenceConfig.retrievalMood);
+      confidence *= moodCongruenceModifier(encodingAffect, confidenceConfig.retrievalMood, confidenceConfig.affectWeight);
+      confidence = Math.max(0, Math.min(1, confidence));
+    }
+
     if (confidence < minConfidence) continue;
     const score = row.similarity * confidence;
-    results.push(buildEpisodicEntry(row, confidence, score, includeProvenance, ctxMatch));
+    results.push(buildEpisodicEntry(row, confidence, score, includeProvenance, ctxMatch, moodMatch));
   }
   return results;
 }
@@ -246,6 +260,7 @@ export async function* recallStream(db, embeddingProvider, query, options = {})
     sources,
     after,
     before,
+    includePrivate = false,
   } = options;
 
   const queryVector = await embeddingProvider.embed(query);
@@ -259,7 +274,7 @@ export async function* recallStream(db, embeddingProvider, query, options = {})
   const allResults = [];
 
   if (searchTypes.includes('episodic')) {
-    const episodic = knnEpisodic(db, queryBuffer, candidateK, now, minConfidence, includeProvenance, confidenceConfig, filters);
+    const episodic = knnEpisodic(db, queryBuffer, candidateK, now, minConfidence, includeProvenance, confidenceConfig, filters, includePrivate);
     allResults.push(...episodic);
   }
 
@@ -269,13 +284,11 @@ export async function* recallStream(db, embeddingProvider, query, options = {})
     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);
-      }
+      const placeholders = semIds.map(() => '?').join(',');
+      db.prepare(
+        `UPDATE semantics SET retrieval_count = retrieval_count + 1, last_reinforced_at = ? WHERE id IN (${placeholders})`
+      ).run(nowISO, ...semIds);
     }
   }
 
@@ -285,13 +298,11 @@ export async function* recallStream(db, embeddingProvider, query, options = {})
     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);
-      }
+      const placeholders = procIds.map(() => '?').join(',');
+      db.prepare(
+        `UPDATE procedures SET retrieval_count = retrieval_count + 1, last_reinforced_at = ? WHERE id IN (${placeholders})`
+      ).run(nowISO, ...procIds);
     }
   }