audrey 0.16.0 → 0.17.0

package/src/fts.js

@@ -0,0 +1,134 @@
+/**
+ * FTS5 full-text search for Audrey memories.
+ * Creates virtual tables alongside vec0 tables for hybrid retrieval.
+ */
+
+export function createFTSTables(db) {
+  db.exec(`
+    CREATE VIRTUAL TABLE IF NOT EXISTS fts_episodes
+      USING fts5(id UNINDEXED, content, tags, tokenize='porter unicode61');
+    CREATE VIRTUAL TABLE IF NOT EXISTS fts_semantics
+      USING fts5(id UNINDEXED, content, tokenize='porter unicode61');
+    CREATE VIRTUAL TABLE IF NOT EXISTS fts_procedures
+      USING fts5(id UNINDEXED, content, tokenize='porter unicode61');
+  `);
+}
+
+export function hasFTSTables(db) {
+  const row = db.prepare(
+    "SELECT COUNT(*) AS c FROM sqlite_master WHERE type='table' AND name='fts_episodes'"
+  ).get();
+  return row.c > 0;
+}
+
+export function insertFTSEpisode(db, id, content, tags) {
+  db.prepare('INSERT OR REPLACE INTO fts_episodes(id, content, tags) VALUES (?, ?, ?)').run(
+    id, content, tags ? (Array.isArray(tags) ? tags.join(' ') : tags) : ''
+  );
+}
+
+export function insertFTSSemantic(db, id, content) {
+  db.prepare('INSERT OR REPLACE INTO fts_semantics(id, content) VALUES (?, ?)').run(id, content);
+}
+
+export function insertFTSProcedure(db, id, content) {
+  db.prepare('INSERT OR REPLACE INTO fts_procedures(id, content) VALUES (?, ?)').run(id, content);
+}
+
+export function deleteFTSEpisode(db, id) {
+  db.prepare('DELETE FROM fts_episodes WHERE id = ?').run(id);
+}
+
+export function deleteFTSSemantic(db, id) {
+  db.prepare('DELETE FROM fts_semantics WHERE id = ?').run(id);
+}
+
+export function deleteFTSProcedure(db, id) {
+  db.prepare('DELETE FROM fts_procedures WHERE id = ?').run(id);
+}
+
+/**
+ * Search episodes via FTS5 BM25.
+ * Returns [{ id, content, rank }] sorted by relevance.
+ */
+export function searchFTSEpisodes(db, query, limit = 30, agentFilter = null) {
+  const agentClause = agentFilter ? 'AND e.agent = ?' : '';
+  const params = agentFilter ? [query, agentFilter, limit] : [query, limit];
+  return db.prepare(`
+    SELECT f.id, f.content, e.agent, bm25(fts_episodes) AS rank
+    FROM fts_episodes f
+    JOIN episodes e ON e.id = f.id
+    WHERE fts_episodes MATCH ?
+      AND e.superseded_by IS NULL
+      ${agentClause}
+    ORDER BY rank
+    LIMIT ?
+  `).all(...params);
+}
+
+export function searchFTSSemantics(db, query, limit = 30, agentFilter = null) {
+  const agentClause = agentFilter ? 'AND s.agent = ?' : '';
+  const params = agentFilter ? [query, agentFilter, limit] : [query, limit];
+  return db.prepare(`
+    SELECT f.id, f.content, s.agent, bm25(fts_semantics) AS rank
+    FROM fts_semantics f
+    JOIN semantics s ON s.id = f.id
+    WHERE fts_semantics MATCH ?
+      AND s.state = 'active'
+      ${agentClause}
+    ORDER BY rank
+    LIMIT ?
+  `).all(...params);
+}
+
+export function searchFTSProcedures(db, query, limit = 30, agentFilter = null) {
+  const agentClause = agentFilter ? 'AND p.agent = ?' : '';
+  const params = agentFilter ? [query, agentFilter, limit] : [query, limit];
+  return db.prepare(`
+    SELECT f.id, f.content, p.agent, bm25(fts_procedures) AS rank
+    FROM fts_procedures f
+    JOIN procedures p ON p.id = f.id
+    WHERE fts_procedures MATCH ?
+      AND p.state = 'active'
+      ${agentClause}
+    ORDER BY rank
+    LIMIT ?
+  `).all(...params);
+}
+
+/**
+ * Backfill FTS tables from existing data.
+ */
+export function backfillFTS(db) {
+  const episodes = db.prepare('SELECT id, content, tags FROM episodes').all();
+  const insert = db.prepare('INSERT OR IGNORE INTO fts_episodes(id, content, tags) VALUES (?, ?, ?)');
+  for (const ep of episodes) {
+    const tags = ep.tags ? (typeof ep.tags === 'string' ? JSON.parse(ep.tags) : ep.tags) : [];
+    insert.run(ep.id, ep.content, Array.isArray(tags) ? tags.join(' ') : '');
+  }
+
+  const semantics = db.prepare('SELECT id, content FROM semantics').all();
+  const insertSem = db.prepare('INSERT OR IGNORE INTO fts_semantics(id, content) VALUES (?, ?)');
+  for (const sem of semantics) {
+    insertSem.run(sem.id, sem.content);
+  }
+
+  const procedures = db.prepare('SELECT id, content FROM procedures').all();
+  const insertProc = db.prepare('INSERT OR IGNORE INTO fts_procedures(id, content) VALUES (?, ?)');
+  for (const proc of procedures) {
+    insertProc.run(proc.id, proc.content);
+  }
+}
+
+/**
+ * Sanitize FTS5 query — escape special characters.
+ */
+export function sanitizeFTSQuery(query) {
+  return query
+    .replace(/[*"(){}[\]^~\\:]/g, ' ')
+    .replace(/\bAND\b|\bOR\b|\bNOT\b|\bNEAR\b/gi, ' ')
+    .trim()
+    .split(/\s+/)
+    .filter(Boolean)
+    .join(' ');
+}

package/src/import.js

@@ -16,11 +16,39 @@ function isDatabaseEmpty(db) {
   return tables.every(table => db.prepare(`SELECT COUNT(*) AS c FROM ${table}`).get().c === 0);
 }
 
+const VALID_SOURCES = new Set(['direct-observation', 'told-by-user', 'tool-result', 'inference', 'model-generated']);
+
+function validateSnapshot(snapshot) {
+  const errors = [];
+  for (let i = 0; i < (snapshot.episodes || []).length; i++) {
+    const ep = snapshot.episodes[i];
+    if (!ep.id) errors.push(`episodes[${i}]: missing id`);
+    if (!ep.content) errors.push(`episodes[${i}]: missing content`);
+    if (!ep.source || !VALID_SOURCES.has(ep.source)) errors.push(`episodes[${i}]: invalid source "${ep.source}"`);
+  }
+  for (let i = 0; i < (snapshot.semantics || []).length; i++) {
+    const sem = snapshot.semantics[i];
+    if (!sem.id) errors.push(`semantics[${i}]: missing id`);
+    if (!sem.content) errors.push(`semantics[${i}]: missing content`);
+  }
+  for (let i = 0; i < (snapshot.procedures || []).length; i++) {
+    const proc = snapshot.procedures[i];
+    if (!proc.id) errors.push(`procedures[${i}]: missing id`);
+    if (!proc.content) errors.push(`procedures[${i}]: missing content`);
+  }
+  return errors;
+}
+
 export async function importMemories(db, embeddingProvider, snapshot) {
   if (!isDatabaseEmpty(db)) {
     throw new Error('Cannot import into a database that is not empty');
   }
 
+  const validationErrors = validateSnapshot(snapshot);
+  if (validationErrors.length > 0) {
+    throw new Error(`Invalid snapshot: ${validationErrors.join('; ')}`);
+  }
+
   const episodes = snapshot.episodes || [];
   const semantics = snapshot.semantics || [];
   const procedures = snapshot.procedures || [];

package/src/llm.js

@@ -4,6 +4,8 @@
  * @property {string} content
  */
 
+import { describeHttpError, requireApiKey } from './utils.js';
+
 function extractJSON(text) {
   const fenced = text.match(/```(?:json)?\s*\n?([\s\S]*?)```/);
   return fenced ? fenced[1].trim() : text.trim();
@@ -112,6 +114,7 @@ export class AnthropicLLMProvider {
    * @returns {Promise<LLMCompletionResult>}
    */
   async complete(messages, options = {}) {
+    requireApiKey(this.apiKey, 'Anthropic LLM', 'ANTHROPIC_API_KEY');
     const systemMsg = messages.find(m => m.role === 'system')?.content;
     const nonSystemMsgs = messages.filter(m => m.role !== 'system');
 
@@ -137,8 +140,7 @@ export class AnthropicLLMProvider {
       });
 
       if (!response.ok) {
-        const errorBody = await response.text().catch(() => '');
-        throw new Error(`Anthropic API error: ${response.status} ${errorBody}`);
+        throw new Error(`Anthropic API error: ${await describeHttpError(response)}`);
       }
 
       const data = await response.json();
@@ -182,6 +184,7 @@ export class OpenAILLMProvider {
    * @returns {Promise<LLMCompletionResult>}
    */
   async complete(messages, options = {}) {
+    requireApiKey(this.apiKey, 'OpenAI LLM', 'OPENAI_API_KEY');
     const body = {
       model: this.model,
       max_tokens: options.maxTokens || this.maxTokens,
@@ -202,7 +205,7 @@ export class OpenAILLMProvider {
       });
 
       if (!response.ok) {
-        throw new Error(`OpenAI API error: ${response.status}`);
+        throw new Error(`OpenAI API error: ${await describeHttpError(response)}`);
       }
 
       const data = await response.json();

package/src/migrate.js

@@ -6,7 +6,7 @@ export async function reembedAll(db, embeddingProvider, { dropAndRecreate = fals
     createVec0Tables(db, embeddingProvider.dimensions);
   }
 
-  const episodes = db.prepare('SELECT id, content, source FROM episodes').all();
+  const episodes = db.prepare('SELECT id, content, source, consolidated 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();
 
@@ -37,7 +37,7 @@ export async function reembedAll(db, embeddingProvider, { dropAndRecreate = fals
       const buf = embeddingProvider.vectorToBuffer(episodeVectors[i]);
       updateEpLegacy.run(buf, episodes[i].id);
       deleteVecEp.run(episodes[i].id);
-      insertVecEp.run(episodes[i].id, buf, episodes[i].source, BigInt(0));
+      insertVecEp.run(episodes[i].id, buf, episodes[i].source, BigInt(episodes[i].consolidated ?? 0));
     }
     for (let i = 0; i < semantics.length; i++) {
       const buf = embeddingProvider.vectorToBuffer(semanticVectors[i]);

package/src/recall.js

@@ -1,8 +1,120 @@
-import { computeConfidence, DEFAULT_HALF_LIVES, salienceModifier } from './confidence.js';
+import { computeConfidence, DEFAULT_HALF_LIVES, salienceModifier, sourceReliability } 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';
+import { hasFTSTables, searchFTSEpisodes, searchFTSSemantics, searchFTSProcedures, sanitizeFTSQuery } from './fts.js';
+
+const STOPWORDS = new Set([
+  'a', 'an', 'and', 'are', 'at', 'be', 'by', 'did', 'do', 'does', 'for', 'from', 'had', 'has', 'have',
+  'how', 'i', 'in', 'is', 'it', 'me', 'my', 'now', 'of', 'on', 'or', 'our', 's', 'sam', 'she', 'that',
+  'the', 'their', 'them', 'there', 'they', 'this', 'to', 'was', 'we', 'were', 'what', 'when', 'where',
+  'which', 'who', 'why', 'with', 'would', 'you', 'your',
+]);
+
+const IDENTIFIER_TERMS = new Set(['account', 'api', 'credential', 'id', 'identifier', 'key', 'number', 'password', 'secret', 'ssn', 'token']);
+
+function tokenize(text) {
+  return String(text || '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, ' ')
+    .trim()
+    .split(/\s+/)
+    .filter(Boolean);
+}
+
+function significantTokens(text) {
+  return tokenize(text).filter(token => !STOPWORDS.has(token));
+}
+
+function lexicalCoverage(query, content) {
+  const queryTokens = significantTokens(query);
+  if (queryTokens.length === 0) return 1;
+  const contentTokens = new Set(significantTokens(content));
+  let matched = 0;
+  for (const token of queryTokens) {
+    if (contentTokens.has(token)) matched++;
+  }
+  return matched / queryTokens.length;
+}
+
+function hasIdentifierIntent(query) {
+  const normalized = String(query || '').toLowerCase();
+  const asksForValue = /\b(find|give|lookup|show|tell|what|which)\b/.test(normalized);
+  const mentionsIdentifier = /\b(account number|api key|credential|id|identifier|key|number|passport number|password|secret|ssn|token)\b/.test(normalized);
+  return asksForValue && mentionsIdentifier;
+}
+
+function hasIdentifierEvidence(content) {
+  const tokens = significantTokens(content);
+  if (tokens.some(token => IDENTIFIER_TERMS.has(token))) {
+    return true;
+  }
+  return /(?:\b\d{4,}\b|sk-[a-z0-9_-]+)/i.test(content);
+}
+
+function adjustedScore(query, entry) {
+  const coverage = lexicalCoverage(query, entry.content);
+  let score = entry.score;
+
+  if (hasIdentifierIntent(query) && !hasIdentifierEvidence(entry.content)) {
+    score *= 0.02;
+  }
+
+  return { score, coverage };
+}
+
+function overlapRatio(contentA, contentB) {
+  const tokensA = significantTokens(contentA);
+  const tokensB = significantTokens(contentB);
+  if (tokensA.length === 0 || tokensB.length === 0) return 0;
+  const setB = new Set(tokensB);
+  let matched = 0;
+  for (const token of tokensA) {
+    if (setB.has(token)) matched++;
+  }
+  return matched / Math.min(tokensA.length, tokensB.length);
+}
+
+function reliabilityForRecallSource(source) {
+  if (source === 'consolidation') {
+    return sourceReliability('tool-result');
+  }
+  return sourceReliability(source);
+}
+
+function shouldSuppressDuplicate(existing, candidate) {
+  const overlap = overlapRatio(existing.content, candidate.content);
+  if (overlap < 0.5) return false;
+  if (existing.type !== candidate.type) return false;
+  const existingReliability = reliabilityForRecallSource(existing.source);
+  const candidateReliability = reliabilityForRecallSource(candidate.source);
+  if (existingReliability < candidateReliability) return false;
+  if (existingReliability - candidateReliability < 0.2) return false;
+  return existing.score >= candidate.score * 0.95;
+}
+
+function applyResultGuards(query, results, limit) {
+  const identifierIntent = hasIdentifierIntent(query);
+  const rescored = results
+    .map(entry => {
+      const { score, coverage } = adjustedScore(query, entry);
+      return { ...entry, score, lexicalCoverage: coverage };
+    })
+    .filter(entry => !identifierIntent || entry.score > 0.05)
+    .sort((a, b) => b.score - a.score);
+
+  const accepted = [];
+  for (const candidate of rescored) {
+    if (accepted.some(existing => shouldSuppressDuplicate(existing, candidate))) {
+      continue;
+    }
+    accepted.push(candidate);
+    if (accepted.length >= limit) break;
+  }
+
+  return accepted;
+}
 
 function computeEpisodicConfidence(ep, now, confidenceConfig = {}) {
   const ageDays = daysBetween(ep.created_at, now);
@@ -75,6 +187,7 @@ function buildEpisodicEntry(ep, confidence, score, includeProvenance, contextMat
     score,
     source: ep.source,
     createdAt: ep.created_at,
+    agent: ep.agent || 'default',
   };
   if (contextMatch !== undefined) {
     entry.contextMatch = contextMatch;
@@ -103,6 +216,7 @@ function buildSemanticEntry(sem, confidence, score, includeProvenance) {
     source: 'consolidation',
     state: sem.state,
     createdAt: sem.created_at,
+    agent: sem.agent || 'default',
   };
   if (includeProvenance) {
     entry.provenance = {
@@ -126,6 +240,7 @@ function buildProceduralEntry(proc, confidence, score, includeProvenance) {
     source: 'consolidation',
     state: proc.state,
     createdAt: proc.created_at,
+    agent: proc.agent || 'default',
   };
   if (includeProvenance) {
     entry.provenance = {
@@ -155,10 +270,12 @@ function safeKForTable(db, table, candidateK) {
   return rowCount > 0 ? Math.min(candidateK, rowCount) : 0;
 }
 
-function knnEpisodic(db, queryBuffer, candidateK, now, minConfidence, includeProvenance, confidenceConfig, filters = {}, includePrivate = false) {
+function knnEpisodic(db, queryBuffer, candidateK, now, minConfidence, includeProvenance, confidenceConfig, filters = {}, includePrivate = false, agentFilter = null) {
   const safeK = safeKForTable(db, 'vec_episodes', candidateK);
   if (safeK === 0) return [];
   const privateClause = includePrivate ? '' : 'AND e."private" = 0';
+  const agentClause = agentFilter ? 'AND e.agent = ?' : '';
+  const params = agentFilter ? [queryBuffer, safeK, agentFilter] : [queryBuffer, safeK];
   const rows = db.prepare(`
     SELECT e.*, (1.0 - v.distance) AS similarity
     FROM vec_episodes v
@@ -167,7 +284,8 @@ function knnEpisodic(db, queryBuffer, candidateK, now, minConfidence, includePro
       AND k = ?
       AND e.superseded_by IS NULL
       ${privateClause}
-  `).all(queryBuffer, safeK);
+      ${agentClause}
+  `).all(...params);
 
   const results = [];
   for (const row of rows) {
@@ -202,9 +320,11 @@ function knnEpisodic(db, queryBuffer, candidateK, now, minConfidence, includePro
   return results;
 }
 
-function knnSemantic(db, queryBuffer, candidateK, now, minConfidence, includeProvenance, includeDormant, confidenceConfig, filters = {}) {
+function knnSemantic(db, queryBuffer, candidateK, now, minConfidence, includeProvenance, includeDormant, confidenceConfig, filters = {}, agentFilter = null) {
   const safeK = safeKForTable(db, 'vec_semantics', candidateK);
   if (safeK === 0) return { results: [], matchedIds: [] };
+  const agentClause = agentFilter ? 'AND s.agent = ?' : '';
+  const params = agentFilter ? [queryBuffer, safeK, agentFilter] : [queryBuffer, safeK];
   const rows = db.prepare(`
     SELECT s.*, (1.0 - v.distance) AS similarity
     FROM vec_semantics v
@@ -212,7 +332,8 @@ function knnSemantic(db, queryBuffer, candidateK, now, minConfidence, includePro
     WHERE v.embedding MATCH ?
       AND k = ?
       ${stateClause(includeDormant)}
-  `).all(queryBuffer, safeK);
+      ${agentClause}
+  `).all(...params);
 
   const results = [];
   const matchedIds = [];
@@ -227,9 +348,11 @@ function knnSemantic(db, queryBuffer, candidateK, now, minConfidence, includePro
   return { results, matchedIds };
 }
 
-function knnProcedural(db, queryBuffer, candidateK, now, minConfidence, includeProvenance, includeDormant, confidenceConfig, filters = {}) {
+function knnProcedural(db, queryBuffer, candidateK, now, minConfidence, includeProvenance, includeDormant, confidenceConfig, filters = {}, agentFilter = null) {
   const safeK = safeKForTable(db, 'vec_procedures', candidateK);
   if (safeK === 0) return { results: [], matchedIds: [] };
+  const agentClause = agentFilter ? 'AND p.agent = ?' : '';
+  const params = agentFilter ? [queryBuffer, safeK, agentFilter] : [queryBuffer, safeK];
   const rows = db.prepare(`
     SELECT p.*, (1.0 - v.distance) AS similarity
     FROM vec_procedures v
@@ -237,7 +360,8 @@ function knnProcedural(db, queryBuffer, candidateK, now, minConfidence, includeP
     WHERE v.embedding MATCH ?
       AND k = ?
       ${stateClause(includeDormant)}
-  `).all(queryBuffer, safeK);
+      ${agentClause}
+  `).all(...params);
 
   const results = [];
   const matchedIds = [];
@@ -252,14 +376,7 @@ function knnProcedural(db, queryBuffer, candidateK, now, minConfidence, includeP
   return { results, matchedIds };
 }
 
-/**
- * @param {import('better-sqlite3').Database} db
- * @param {import('./embedding.js').EmbeddingProvider} embeddingProvider
- * @param {string} query
- * @param {{ minConfidence?: number, types?: string[], limit?: number, includeProvenance?: boolean, includeDormant?: boolean, tags?: string[], sources?: string[], after?: string, before?: string }} [options]
- * @returns {AsyncGenerator<{ id: string, content: string, type: string, confidence: number, score: number, source: string, createdAt: string }>}
- */
-export async function* recallStream(db, embeddingProvider, query, options = {}) {
+async function runRecallQuery(db, embeddingProvider, query, options = {}) {
   const {
     minConfidence = 0,
     types,
@@ -272,31 +389,76 @@ export async function* recallStream(db, embeddingProvider, query, options = {})
     after,
     before,
     includePrivate = false,
+    scope = 'shared',
+    agent,
+    retrieval = 'hybrid',
   } = options;
 
-  const queryVector = await embeddingProvider.embed(query);
-  const queryBuffer = embeddingProvider.vectorToBuffer(queryVector);
   const searchTypes = types || ['episodic', 'semantic', 'procedural'];
   const now = new Date();
+  const agentFilter = scope === 'agent' && agent ? agent : null;
+
+  // Keyword-only mode: FTS5 search without vector embeddings
+  if (retrieval === 'keyword') {
+    const ftsAvailable = hasFTSTables(db);
+    if (!ftsAvailable) {
+      return { top: [], errors: [] };
+    }
+    const sanitized = sanitizeFTSQuery(query);
+    if (!sanitized) return { top: [], errors: [] };
+
+    const keywordResults = [];
+    try {
+      if (searchTypes.includes('episodic')) {
+        for (const row of searchFTSEpisodes(db, sanitized, limit * 3, agentFilter)) {
+          keywordResults.push({ id: row.id, content: row.content, type: 'episodic', score: -row.rank, agent: row.agent || 'default' });
+        }
+      }
+      if (searchTypes.includes('semantic')) {
+        for (const row of searchFTSSemantics(db, sanitized, limit * 3, agentFilter)) {
+          keywordResults.push({ id: row.id, content: row.content, type: 'semantic', score: -row.rank, agent: row.agent || 'default' });
+        }
+      }
+      if (searchTypes.includes('procedural')) {
+        for (const row of searchFTSProcedures(db, sanitized, limit * 3, agentFilter)) {
+          keywordResults.push({ id: row.id, content: row.content, type: 'procedural', score: -row.rank, agent: row.agent || 'default' });
+        }
+      }
+    } catch {
+      // FTS query syntax error — fall through with whatever we have
+    }
+    keywordResults.sort((a, b) => b.score - a.score);
+    const top = keywordResults.slice(0, limit).map(entry => ({
+      ...entry,
+      confidence: 1,
+      source: 'keyword',
+      createdAt: now.toISOString(),
+    }));
+    return { top, errors: [] };
+  }
+
+  const queryVector = await embeddingProvider.embed(query);
+  const queryBuffer = embeddingProvider.vectorToBuffer(queryVector);
   const hasFilters = tags?.length || sources?.length || after || before;
   const candidateK = hasFilters ? limit * 5 : limit * 3;
   const filters = { tags, sources, after, before };
 
   const allResults = [];
+  const errors = [];
 
   if (searchTypes.includes('episodic')) {
     try {
-      const episodic = knnEpisodic(db, queryBuffer, candidateK, now, minConfidence, includeProvenance, confidenceConfig, filters, includePrivate);
+      const episodic = knnEpisodic(db, queryBuffer, candidateK, now, minConfidence, includeProvenance, confidenceConfig, filters, includePrivate, agentFilter);
       allResults.push(...episodic);
-    } catch {
-      // A broken episodic index should not block semantic/procedural recall.
+    } catch (err) {
+      errors.push({ type: 'episodic', message: err.message });
     }
   }
 
   if (searchTypes.includes('semantic')) {
     try {
       const { results: semResults, matchedIds: semIds } =
-        knnSemantic(db, queryBuffer, candidateK, now, minConfidence, includeProvenance, includeDormant, confidenceConfig, filters);
+        knnSemantic(db, queryBuffer, candidateK, now, minConfidence, includeProvenance, includeDormant, confidenceConfig, filters, agentFilter);
       allResults.push(...semResults);
 
       if (semIds.length > 0) {
@@ -306,15 +468,15 @@ export async function* recallStream(db, embeddingProvider, query, options = {})
           `UPDATE semantics SET retrieval_count = retrieval_count + 1, last_reinforced_at = ? WHERE id IN (${placeholders})`
         ).run(nowISO, ...semIds);
       }
-    } catch {
-      // A broken semantic index should not block other memory types.
+    } catch (err) {
+      errors.push({ type: 'semantic', message: err.message });
     }
   }
 
   if (searchTypes.includes('procedural')) {
     try {
       const { results: procResults, matchedIds: procIds } =
-        knnProcedural(db, queryBuffer, candidateK, now, minConfidence, includeProvenance, includeDormant, confidenceConfig, filters);
+        knnProcedural(db, queryBuffer, candidateK, now, minConfidence, includeProvenance, includeDormant, confidenceConfig, filters, agentFilter);
       allResults.push(...procResults);
 
       if (procIds.length > 0) {
@@ -324,14 +486,73 @@ export async function* recallStream(db, embeddingProvider, query, options = {})
           `UPDATE procedures SET retrieval_count = retrieval_count + 1, last_reinforced_at = ? WHERE id IN (${placeholders})`
         ).run(nowISO, ...procIds);
       }
-    } catch {
-      // A broken procedural index should not block other memory types.
+    } catch (err) {
+      errors.push({ type: 'procedural', message: err.message });
     }
   }
 
-  allResults.sort((a, b) => b.score - a.score);
-  const top = allResults.slice(0, limit);
+  // Hybrid mode: merge vector results with FTS5 keyword results via RRF
+  if (retrieval === 'hybrid' && hasFTSTables(db)) {
+    const sanitized = sanitizeFTSQuery(query);
+    if (sanitized) {
+      const keywordHits = new Map();
+      try {
+        if (searchTypes.includes('episodic')) {
+          for (const row of searchFTSEpisodes(db, sanitized, limit * 3, agentFilter)) {
+            keywordHits.set(row.id, (keywordHits.get(row.id) || 0) + 1);
+          }
+        }
+        if (searchTypes.includes('semantic')) {
+          for (const row of searchFTSSemantics(db, sanitized, limit * 3, agentFilter)) {
+            keywordHits.set(row.id, (keywordHits.get(row.id) || 0) + 1);
+          }
+        }
+        if (searchTypes.includes('procedural')) {
+          for (const row of searchFTSProcedures(db, sanitized, limit * 3, agentFilter)) {
+            keywordHits.set(row.id, (keywordHits.get(row.id) || 0) + 1);
+          }
+        }
+      } catch {
+        // FTS query error — continue with vector-only results
+      }
+
+      // RRF boost: memories found by both vector AND keyword get a score bonus
+      const RRF_K = 60;
+      if (keywordHits.size > 0) {
+        // Rank keyword results by their BM25 order
+        const keywordRanks = new Map();
+        let rank = 1;
+        for (const id of keywordHits.keys()) {
+          keywordRanks.set(id, rank++);
+        }
+
+        for (const result of allResults) {
+          if (keywordRanks.has(result.id)) {
+            // Boost score for results found by both vector AND keyword search
+            const kRank = keywordRanks.get(result.id);
+            const rrfBoost = 1 / (RRF_K + kRank);
+            result.score = result.score + rrfBoost;
+          }
+        }
+      }
+    }
+  }
+
+  const top = applyResultGuards(query, allResults, limit);
+  return { top, errors };
+}
+
+/**
+ * @param {import('better-sqlite3').Database} db
+ * @param {import('./embedding.js').EmbeddingProvider} embeddingProvider
+ * @param {string} query
+ * @param {{ minConfidence?: number, types?: string[], limit?: number, includeProvenance?: boolean, includeDormant?: boolean, tags?: string[], sources?: string[], after?: string, before?: string }} [options]
+ * @returns {AsyncGenerator<{ id: string, content: string, type: string, confidence: number, score: number, source: string, createdAt: string }>}
+ */
+export async function* recallStream(db, embeddingProvider, query, options = {}) {
+  const { top, errors } = await runRecallQuery(db, embeddingProvider, query, options);
   for (const entry of top) {
+    if (errors.length > 0) entry._recallErrors = errors;
     yield entry;
   }
 }
@@ -344,9 +565,9 @@ export async function* recallStream(db, embeddingProvider, query, options = {})
  * @returns {Promise<Array<{ id: string, content: string, type: string, confidence: number, score: number, source: string, createdAt: string }>>}
  */
 export async function recall(db, embeddingProvider, query, options = {}) {
-  const results = [];
-  for await (const entry of recallStream(db, embeddingProvider, query, options)) {
-    results.push(entry);
-  }
+  const { top, errors } = await runRecallQuery(db, embeddingProvider, query, options);
+  const results = [...top];
+  results.partialFailure = errors.length > 0;
+  results.errors = errors;
   return results;
 }

package/src/utils.js

@@ -36,3 +36,28 @@ export function safeJsonParse(str, fallback = null) {
   try { return JSON.parse(str); }
   catch { return fallback; }
 }
+
+/**
+ * @param {string | undefined | null} apiKey
+ * @param {string} operation
+ * @param {string} envVar
+ * @returns {void}
+ */
+export function requireApiKey(apiKey, operation, envVar) {
+  if (typeof apiKey !== 'string' || apiKey.trim() === '') {
+    throw new Error(`${operation} requires ${envVar}`);
+  }
+}
+
+/**
+ * @param {{ status: number, text: () => Promise<string> }} response
+ * @returns {Promise<string>}
+ */
+export async function describeHttpError(response) {
+  if (typeof response.text !== 'function') {
+    return `${response.status}`;
+  }
+  const body = await response.text().catch(() => '');
+  const normalized = body.replace(/\s+/g, ' ').trim().slice(0, 300);
+  return normalized ? `${response.status} ${normalized}` : `${response.status}`;
+}