@desplega.ai/agent-swarm 1.92.0 → 1.92.2

package/src/be/memory/constants.ts

@@ -15,12 +15,54 @@ export const TTL_DEFAULTS: Record<AgentMemorySource, number | null> = {
   manual: null,
 };
 
+// Per-source recency decay half-life (in days).
+// manual = Infinity (no decay — curated knowledge stays relevant forever).
+// A global MEMORY_RECENCY_HALF_LIFE_DAYS override forces ALL sources to the same value.
+const GLOBAL_HALF_LIFE_OVERRIDE = process.env.MEMORY_RECENCY_HALF_LIFE_DAYS;
+const GLOBAL_HALF_LIFE =
+  GLOBAL_HALF_LIFE_OVERRIDE != null && GLOBAL_HALF_LIFE_OVERRIDE !== ""
+    ? Number(GLOBAL_HALF_LIFE_OVERRIDE)
+    : null;
+
+export const RECENCY_DECAY_HALF_LIFE: Record<AgentMemorySource, number> =
+  GLOBAL_HALF_LIFE != null && Number.isFinite(GLOBAL_HALF_LIFE)
+    ? {
+        manual: GLOBAL_HALF_LIFE,
+        file_index: GLOBAL_HALF_LIFE,
+        task_completion: GLOBAL_HALF_LIFE,
+        session_summary: GLOBAL_HALF_LIFE,
+      }
+    : {
+        manual: Number.POSITIVE_INFINITY,
+        file_index: 180,
+        task_completion: 14,
+        session_summary: 7,
+      };
+
+// Legacy export — callers that don't have a source fall back to task_completion's value.
+export const RECENCY_DECAY_HALF_LIFE_DAYS = RECENCY_DECAY_HALF_LIFE.task_completion;
+
+// Source-quality multiplier for reranking.
+// Curated manual memories rank higher; ephemeral session summaries rank lower.
+export const SOURCE_QUALITY_MULTIPLIER: Record<AgentMemorySource, number> = {
+  manual: 1.5,
+  file_index: 1.0,
+  task_completion: 0.7,
+  session_summary: 0.5,
+};
+
+// Minimum raw cosine similarity to keep a candidate. Below this, the result is noise.
+export const MIN_SIMILARITY = numEnv("MEMORY_MIN_SIMILARITY", 0.1);
+
 // Reranking parameters
-export const RECENCY_DECAY_HALF_LIFE_DAYS = numEnv("MEMORY_RECENCY_HALF_LIFE_DAYS", 14);
 export const ACCESS_BOOST_MAX_MULTIPLIER = numEnv("MEMORY_ACCESS_BOOST_MAX", 1.5);
 export const ACCESS_BOOST_RECENCY_WINDOW_HOURS = numEnv("MEMORY_ACCESS_RECENCY_HOURS", 48);
 export const CANDIDATE_SET_MULTIPLIER = numEnv("MEMORY_CANDIDATE_MULTIPLIER", 3);
 
 // Embedding defaults
-export const DEFAULT_EMBEDDING_DIMENSIONS = 512;
+export const EMBEDDING_DIMENSIONS = numEnv("EMBEDDING_DIMENSIONS", 512);
+export const DEFAULT_EMBEDDING_DIMENSIONS = EMBEDDING_DIMENSIONS;
 export const DEFAULT_EMBEDDING_MODEL = "openai/text-embedding-3-small";
+
+// Manual memories must NEVER be deleted by automated processes (curator, GC, etc.)
+export const PROTECTED_SOURCES: ReadonlySet<AgentMemorySource> = new Set(["manual"]);

package/src/be/memory/providers/openai-embedding.ts

@@ -1,5 +1,5 @@
 import OpenAI from "openai";
-import { DEFAULT_EMBEDDING_DIMENSIONS, DEFAULT_EMBEDDING_MODEL } from "../constants";
+import { DEFAULT_EMBEDDING_MODEL, EMBEDDING_DIMENSIONS } from "../constants";
 import type { EmbeddingProvider } from "../types";
 
 interface OpenAIEmbeddingConfig {
@@ -21,10 +21,7 @@ export class OpenAIEmbeddingProvider implements EmbeddingProvider {
 
     this.model = config?.model ?? process.env.EMBEDDING_MODEL ?? "text-embedding-3-small";
 
-    this.dimensions =
-      config?.dimensions ??
-      Number(process.env.EMBEDDING_DIMENSIONS) ??
-      DEFAULT_EMBEDDING_DIMENSIONS;
+    this.dimensions = config?.dimensions ?? EMBEDDING_DIMENSIONS;
 
     this.name = config?.model
       ? `openai/${config.model}`
@@ -58,6 +55,13 @@ export class OpenAIEmbeddingProvider implements EmbeddingProvider {
       const values = response.data[0]?.embedding;
       if (!values) return null;
 
+      if (values.length !== this.dimensions) {
+        console.error(
+          `[memory] Embedding dimension mismatch: expected=${this.dimensions} got=${values.length}. Provider may not support the 'dimensions' parameter.`,
+        );
+        return null;
+      }
+
       return new Float32Array(values);
     } catch (err) {
       console.error("[memory] Embedding failed:", (err as Error).message);
@@ -93,6 +97,12 @@ export class OpenAIEmbeddingProvider implements EmbeddingProvider {
       for (const item of response.data) {
         const originalIndex = nonEmptyIndices[item.index];
         if (originalIndex !== undefined && item.embedding) {
+          if (item.embedding.length !== this.dimensions) {
+            console.error(
+              `[memory] Batch embedding dimension mismatch: expected=${this.dimensions} got=${item.embedding.length}. Provider may not support the 'dimensions' parameter.`,
+            );
+            continue;
+          }
           results[originalIndex] = new Float32Array(item.embedding);
         }
       }

package/src/be/memory/providers/sqlite-store.ts

@@ -1,16 +1,25 @@
 import { getDb, isSqliteVecAvailable } from "@/be/db";
 import { cosineSimilarity, deserializeEmbedding, serializeEmbedding } from "@/be/embedding";
 import type { AgentMemory, AgentMemoryScope, AgentMemorySource } from "@/types";
-import { TTL_DEFAULTS } from "../constants";
+import {
+  EMBEDDING_DIMENSIONS,
+  MIN_SIMILARITY,
+  PROTECTED_SOURCES,
+  TTL_DEFAULTS,
+} from "../constants";
 import type {
   MemoryCandidate,
+  MemoryHealth,
   MemoryInput,
   MemoryListOptions,
   MemorySearchOptions,
   MemoryStats,
   MemoryStore,
+  MemoryVecPopulateStats,
 } from "../types";
 
+const VECTOR_BYTES = EMBEDDING_DIMENSIONS * Float32Array.BYTES_PER_ELEMENT;
+
 type AgentMemoryRow = {
   id: string;
   agentId: string | null;
@@ -76,54 +85,152 @@ function computeExpiresAt(source: AgentMemorySource): string | null {
 
 export class SqliteMemoryStore implements MemoryStore {
   private vecInitialized = false;
+  private lastPopulate: MemoryVecPopulateStats | null = null;
 
   constructor() {
     this.ensureVecTable();
   }
 
   private ensureVecTable(): void {
-    if (this.vecInitialized || !isSqliteVecAvailable()) return;
+    if (this.vecInitialized) return;
+
+    if (!isSqliteVecAvailable()) {
+      console.warn("[memory-vec] sqlite-vec extension_loaded=false; retrieval_mode=fallback");
+      return;
+    }
 
     const db = getDb();
-    // Create the virtual table if it doesn't exist
     try {
+      console.log(
+        `[memory-vec] sqlite-vec extension_loaded=true vector_dimensions=${EMBEDDING_DIMENSIONS}`,
+      );
+
+      const existingSchema = this.getVecTableSchema();
+      if (existingSchema && !existingSchema.includes("distance_metric=cosine")) {
+        console.warn(
+          "[memory-vec] Existing memory_vec table is missing cosine distance metric; rebuilding from agent_memory",
+        );
+        db.run("DROP TABLE memory_vec");
+      }
+
       db.run(`
         CREATE VIRTUAL TABLE IF NOT EXISTS memory_vec USING vec0(
           memory_id TEXT PRIMARY KEY,
-          embedding float[512]
+          embedding float[${EMBEDDING_DIMENSIONS}] distance_metric=cosine
         )
       `);
 
-      // Populate from existing embeddings that aren't yet in the vec table
-      const existing = db
-        .prepare<{ id: string; embedding: Buffer }, []>(
-          "SELECT id, embedding FROM agent_memory WHERE embedding IS NOT NULL",
-        )
-        .all();
-
-      if (existing.length > 0) {
-        const vecCount = db
-          .prepare<{ count: number }, []>("SELECT COUNT(*) as count FROM memory_vec")
-          .get();
-
-        if ((vecCount?.count ?? 0) < existing.length) {
-          const insert = db.prepare(
-            "INSERT OR IGNORE INTO memory_vec(memory_id, embedding) VALUES (?, ?)",
-          );
-          const tx = db.transaction(() => {
-            for (const row of existing) {
-              insert.run(row.id, row.embedding);
-            }
-          });
-          tx();
-          console.log(`[memory] Synced ${existing.length} embeddings to memory_vec`);
-        }
+      const healthBefore = this.getHealthCounts();
+      if (healthBefore.missingFromVec > 0 || healthBefore.extraInVec > 0) {
+        this.populateVecTable(healthBefore.memoryVec);
+      } else {
+        console.log(
+          `[memory-vec] populate skipped attempted=0 inserted=0 memory_vec=${healthBefore.memoryVec} valid_embedding=${healthBefore.validEmbedding}`,
+        );
       }
 
       this.vecInitialized = true;
     } catch (err) {
-      console.warn("[memory] Failed to initialize memory_vec:", (err as Error).message);
+      this.vecInitialized = false;
+      console.error("[memory-vec] Failed to initialize memory_vec:", (err as Error).message);
+    }
+  }
+
+  private getVecTableSchema(): string | null {
+    try {
+      return (
+        getDb()
+          .prepare<{ sql: string | null }, []>(
+            "SELECT sql FROM sqlite_master WHERE type = 'table' AND name = 'memory_vec'",
+          )
+          .get()?.sql ?? null
+      );
+    } catch {
+      return null;
+    }
+  }
+
+  private getVecCount(): number {
+    if (!this.getVecTableSchema()) return 0;
+    return (
+      getDb().prepare<{ count: number }, []>("SELECT COUNT(*) as count FROM memory_vec").get()
+        ?.count ?? 0
+    );
+  }
+
+  private populateVecTable(beforeCount: number): void {
+    const db = getDb();
+    const deletedExtra = db
+      .prepare(
+        `DELETE FROM memory_vec
+         WHERE memory_id NOT IN (SELECT id FROM agent_memory)`,
+      )
+      .run();
+    if (deletedExtra.changes > 0) {
+      console.warn(`[memory-vec] removed_extra_rows count=${deletedExtra.changes}`);
+    }
+
+    const rows = db
+      .prepare<{ id: string; embedding: Buffer }, []>(
+        "SELECT id, embedding FROM agent_memory WHERE embedding IS NOT NULL",
+      )
+      .all();
+    const deleteVec = db.prepare("DELETE FROM memory_vec WHERE memory_id = ?");
+    const insertVec = db.prepare("INSERT INTO memory_vec(memory_id, embedding) VALUES (?, ?)");
+
+    let attempted = 0;
+    let inserted = 0;
+    let skippedInvalidDimensions = 0;
+    let failed = 0;
+
+    for (const row of rows) {
+      const embeddingBuffer = this.toVecBuffer(row.embedding);
+      if (!embeddingBuffer) {
+        skippedInvalidDimensions++;
+        continue;
+      }
+
+      attempted++;
+      try {
+        deleteVec.run(row.id);
+        insertVec.run(row.id, embeddingBuffer);
+        inserted++;
+      } catch (err) {
+        failed++;
+        console.error(
+          `[memory-vec] populate failed memory_id=${row.id}: ${(err as Error).message}`,
+        );
+      }
+    }
+
+    const afterCount = this.getVecCount();
+    this.lastPopulate = {
+      attempted,
+      inserted,
+      skippedInvalidDimensions,
+      failed,
+      beforeCount,
+      afterCount,
+    };
+
+    console.log(
+      `[memory-vec] populate attempted=${attempted} inserted=${inserted} skipped_invalid_dimensions=${skippedInvalidDimensions} failed=${failed} before_count=${beforeCount} after_count=${afterCount}`,
+    );
+
+    if (failed > 0 || afterCount < attempted) {
+      console.error(
+        `[memory-vec] populate incomplete attempted=${attempted} after_count=${afterCount} failed=${failed}`,
+      );
+    }
+  }
+
+  private toVecBuffer(embedding: Buffer | Float32Array): Buffer | null {
+    if (embedding instanceof Float32Array) {
+      if (embedding.length !== EMBEDDING_DIMENSIONS) return null;
+      return serializeEmbedding(embedding);
     }
+    if (embedding.length !== VECTOR_BYTES) return null;
+    return embedding;
   }
 
   store(input: MemoryInput): AgentMemory {
@@ -223,7 +330,11 @@ export class SqliteMemoryStore implements MemoryStore {
   ): MemoryCandidate[] {
     const { scope = "all", limit = 10, source, isLead = false, includeExpired = false } = options;
 
-    if (isSqliteVecAvailable() && this.vecInitialized) {
+    const health = this.getHealth();
+    if (health.retrievalMode === "vec" && embedding.length === EMBEDDING_DIMENSIONS) {
+      console.log(
+        `[memory-search] retrieval_path=vec scope=${scope} limit=${limit} vec_rows=${health.counts.memoryVec} searchable=${health.counts.searchable}`,
+      );
       return this.searchWithVec(embedding, agentId, {
         scope,
         limit,
@@ -232,6 +343,10 @@ export class SqliteMemoryStore implements MemoryStore {
         includeExpired,
       });
     }
+
+    console.log(
+      `[memory-search] retrieval_path=fallback scope=${scope} limit=${limit} reason=${embedding.length !== EMBEDDING_DIMENSIONS ? "query_dimension_mismatch" : health.reasons.join("|") || "vec_unavailable"}`,
+    );
     return this.searchBruteForce(embedding, agentId, {
       scope,
       limit,
@@ -255,58 +370,46 @@ export class SqliteMemoryStore implements MemoryStore {
     const db = getDb();
     const { scope, limit, source, isLead, includeExpired } = options;
 
-    // KNN query — fetch more candidates than needed for post-filtering
-    const knnLimit = limit * 5; // over-fetch to account for scope/expiry filters
     const embeddingBuffer = serializeEmbedding(queryEmbedding);
+    // sqlite-vec hard ceiling is 4096 for knn queries
+    const knnLimit = Math.min(Math.max(limit, this.getVecCount()), 4096);
 
-    const vecRows = db
-      .prepare<{ memory_id: string; distance: number }, [Buffer, number]>(
-        "SELECT memory_id, distance FROM memory_vec WHERE embedding MATCH ? AND k = ?",
-      )
-      .all(embeddingBuffer, knnLimit);
-
-    if (vecRows.length === 0) return [];
-
-    // Build ID list and distance map
-    const distanceMap = new Map<string, number>();
-    const ids: string[] = [];
-    for (const vr of vecRows) {
-      distanceMap.set(vr.memory_id, vr.distance);
-      ids.push(vr.memory_id);
-    }
+    const conditions: string[] = ["v.embedding MATCH ?"];
+    const params: (Buffer | string | number | null)[] = [embeddingBuffer];
 
-    // Hydrate from agent_memory with filters
-    const placeholders = ids.map(() => "?").join(",");
-    const conditions: string[] = [`id IN (${placeholders})`];
-    const params: (string | null)[] = [...ids];
-
-    this.addScopeConditions(conditions, params, agentId, scope, isLead);
+    this.addScopeConditions(conditions, params, agentId, scope, isLead, "m");
 
     if (source) {
-      conditions.push("source = ?");
+      conditions.push("m.source = ?");
       params.push(source);
     }
 
     if (!includeExpired) {
-      conditions.push("(expiresAt IS NULL OR expiresAt > datetime('now'))");
+      conditions.push("(m.expiresAt IS NULL OR m.expiresAt > datetime('now'))");
     }
 
+    conditions.push("v.k = ?");
+    params.push(knnLimit);
+
     const rows = db
-      .prepare<AgentMemoryRow, (string | null)[]>(
-        `SELECT * FROM agent_memory WHERE ${conditions.join(" AND ")}`,
+      .prepare<AgentMemoryRow & { distance: number }, (Buffer | string | number | null)[]>(
+        `SELECT m.*, v.distance
+         FROM memory_vec v
+         JOIN agent_memory m ON m.id = v.memory_id
+         WHERE ${conditions.join(" AND ")}
+         ORDER BY v.distance
+         LIMIT ?`,
       )
-      .all(...params);
+      .all(...params, limit);
 
-    // Map to candidates with similarity scores
     const candidates: MemoryCandidate[] = [];
     for (const row of rows) {
-      const distance = distanceMap.get(row.id) ?? 1;
-      const similarity = 1 - distance; // cosine distance to similarity
+      const similarity = 1 - row.distance;
+      if (similarity < MIN_SIMILARITY) continue;
       candidates.push(rowToCandidate(row, similarity));
     }
 
-    candidates.sort((a, b) => b.similarity - a.similarity);
-    return candidates.slice(0, limit);
+    return candidates;
   }
 
   private searchBruteForce(
@@ -349,6 +452,7 @@ export class SqliteMemoryStore implements MemoryStore {
       const emb = deserializeEmbedding(row.embedding);
       if (emb.length !== queryEmbedding.length) continue;
       const similarity = cosineSimilarity(queryEmbedding, emb);
+      if (similarity < MIN_SIMILARITY) continue;
       candidates.push(rowToCandidate(row, similarity));
     }
 
@@ -358,26 +462,28 @@ export class SqliteMemoryStore implements MemoryStore {
 
   private addScopeConditions(
     conditions: string[],
-    params: (string | null)[],
+    params: (Buffer | string | number | null)[],
     agentId: string,
     scope: string,
     isLead: boolean,
+    tableAlias = "",
   ): void {
+    const col = (name: string) => (tableAlias ? `${tableAlias}.${name}` : name);
     if (!isLead) {
       if (scope === "agent") {
-        conditions.push("agentId = ? AND scope = 'agent'");
+        conditions.push(`${col("agentId")} = ? AND ${col("scope")} = 'agent'`);
         params.push(agentId);
       } else if (scope === "swarm") {
-        conditions.push("scope = 'swarm'");
+        conditions.push(`${col("scope")} = 'swarm'`);
       } else {
-        conditions.push("(agentId = ? OR scope = 'swarm')");
+        conditions.push(`(${col("agentId")} = ? OR ${col("scope")} = 'swarm')`);
         params.push(agentId);
       }
     } else {
       if (scope === "agent") {
-        conditions.push("scope = 'agent'");
+        conditions.push(`${col("scope")} = 'agent'`);
       } else if (scope === "swarm") {
-        conditions.push("scope = 'swarm'");
+        conditions.push(`${col("scope")} = 'swarm'`);
       }
     }
   }
@@ -424,6 +530,31 @@ export class SqliteMemoryStore implements MemoryStore {
     return rows.map(rowToAgentMemory);
   }
 
+  isSourceProtected(source: AgentMemorySource): boolean {
+    return PROTECTED_SOURCES.has(source);
+  }
+
+  listForCuration(
+    agentId?: string,
+  ): { id: string; source: string; name: string; createdAt: string }[] {
+    const db = getDb();
+    const protectedList = [...PROTECTED_SOURCES].map((s) => `'${s}'`).join(",");
+    if (agentId) {
+      return db
+        .prepare<{ id: string; source: string; name: string; createdAt: string }, [string]>(
+          `SELECT id, source, name, createdAt FROM agent_memory
+           WHERE agentId = ? AND source NOT IN (${protectedList})`,
+        )
+        .all(agentId);
+    }
+    return db
+      .prepare<{ id: string; source: string; name: string; createdAt: string }, []>(
+        `SELECT id, source, name, createdAt FROM agent_memory
+         WHERE source NOT IN (${protectedList})`,
+      )
+      .all();
+  }
+
   listForReembedding(options?: { agentId?: string }): { id: string; content: string }[] {
     const db = getDb();
     if (options?.agentId) {
@@ -440,7 +571,7 @@ export class SqliteMemoryStore implements MemoryStore {
 
   delete(id: string): boolean {
     const db = getDb();
-    if (isSqliteVecAvailable() && this.vecInitialized) {
+    if (this.vecInitialized && this.getVecTableSchema()) {
       db.prepare("DELETE FROM memory_vec WHERE memory_id = ?").run(id);
     }
     const result = db.prepare("DELETE FROM agent_memory WHERE id = ?").run(id);
@@ -450,7 +581,7 @@ export class SqliteMemoryStore implements MemoryStore {
   deleteBySourcePath(sourcePath: string, agentId: string): number {
     const db = getDb();
 
-    if (isSqliteVecAvailable() && this.vecInitialized) {
+    if (this.vecInitialized && this.getVecTableSchema()) {
       // Get IDs first for vec table cleanup
       const ids = db
         .prepare<{ id: string }, [string, string]>(
@@ -472,6 +603,40 @@ export class SqliteMemoryStore implements MemoryStore {
     return result.changes;
   }
 
+  purgeExpired(): number {
+    const db = getDb();
+
+    const expiredIds = db
+      .prepare<{ id: string }, []>(
+        "SELECT id FROM agent_memory WHERE expiresAt IS NOT NULL AND expiresAt <= datetime('now')",
+      )
+      .all();
+
+    if (expiredIds.length === 0) return 0;
+
+    if (this.vecInitialized && this.getVecTableSchema()) {
+      const batchSize = 500;
+      for (let i = 0; i < expiredIds.length; i += batchSize) {
+        const batch = expiredIds.slice(i, i + batchSize);
+        const placeholders = batch.map(() => "?").join(",");
+        db.prepare(`DELETE FROM memory_vec WHERE memory_id IN (${placeholders})`).run(
+          ...batch.map((r) => r.id),
+        );
+      }
+    }
+
+    const result = db
+      .prepare(
+        "DELETE FROM agent_memory WHERE expiresAt IS NOT NULL AND expiresAt <= datetime('now')",
+      )
+      .run();
+
+    console.log(
+      `[memory] Purged ${result.changes} expired memory row(s) (vec cleanup: ${expiredIds.length} id(s))`,
+    );
+    return result.changes;
+  }
+
   updateEmbedding(id: string, embedding: Float32Array, model: string): void {
     const db = getDb();
     const buffer = serializeEmbedding(embedding);
@@ -481,11 +646,20 @@ export class SqliteMemoryStore implements MemoryStore {
       id,
     );
 
-    if (isSqliteVecAvailable() && this.vecInitialized) {
-      db.prepare("INSERT OR REPLACE INTO memory_vec(memory_id, embedding) VALUES (?, ?)").run(
-        id,
-        buffer,
-      );
+    if (this.vecInitialized && this.getVecTableSchema()) {
+      const vecBuffer = this.toVecBuffer(embedding);
+      if (!vecBuffer) {
+        console.warn(
+          `[memory-vec] update skipped memory_id=${id} reason=invalid_dimensions dimensions=${embedding.length} expected=${EMBEDDING_DIMENSIONS}`,
+        );
+        return;
+      }
+      try {
+        db.prepare("DELETE FROM memory_vec WHERE memory_id = ?").run(id);
+        db.prepare("INSERT INTO memory_vec(memory_id, embedding) VALUES (?, ?)").run(id, vecBuffer);
+      } catch (err) {
+        console.error(`[memory-vec] update failed memory_id=${id}: ${(err as Error).message}`);
+      }
     }
   }
 
@@ -536,4 +710,79 @@ export class SqliteMemoryStore implements MemoryStore {
       expired: expired?.count ?? 0,
     };
   }
+
+  private getHealthCounts(): MemoryHealth["counts"] {
+    const db = getDb();
+    const tableExists = this.getVecTableSchema() !== null;
+    const tableUsable = tableExists && isSqliteVecAvailable();
+    const count = (sql: string) => db.prepare<{ count: number }, []>(sql).get()?.count ?? 0;
+
+    return {
+      total: count("SELECT COUNT(*) as count FROM agent_memory"),
+      withEmbedding: count(
+        "SELECT COUNT(*) as count FROM agent_memory WHERE embedding IS NOT NULL",
+      ),
+      validEmbedding: count(
+        `SELECT COUNT(*) as count FROM agent_memory WHERE embedding IS NOT NULL AND length(embedding) = ${VECTOR_BYTES}`,
+      ),
+      invalidEmbedding: count(
+        `SELECT COUNT(*) as count FROM agent_memory WHERE embedding IS NOT NULL AND length(embedding) != ${VECTOR_BYTES}`,
+      ),
+      searchable: count(
+        `SELECT COUNT(*) as count FROM agent_memory
+         WHERE embedding IS NOT NULL
+           AND length(embedding) = ${VECTOR_BYTES}
+           AND (expiresAt IS NULL OR expiresAt > datetime('now'))`,
+      ),
+      memoryVec: tableUsable ? count("SELECT COUNT(*) as count FROM memory_vec") : 0,
+      missingFromVec: tableUsable
+        ? count(
+            `SELECT COUNT(*) as count
+             FROM agent_memory m
+             LEFT JOIN memory_vec v ON v.memory_id = m.id
+             WHERE m.embedding IS NOT NULL
+               AND length(m.embedding) = ${VECTOR_BYTES}
+               AND v.memory_id IS NULL`,
+          )
+        : count(
+            `SELECT COUNT(*) as count FROM agent_memory WHERE embedding IS NOT NULL AND length(embedding) = ${VECTOR_BYTES}`,
+          ),
+      extraInVec: tableUsable
+        ? count(
+            `SELECT COUNT(*) as count
+             FROM memory_vec v
+             LEFT JOIN agent_memory m ON m.id = v.memory_id
+             WHERE m.id IS NULL`,
+          )
+        : 0,
+    };
+  }
+
+  getHealth(): MemoryHealth {
+    const schema = this.getVecTableSchema();
+    const counts = this.getHealthCounts();
+    const reasons: string[] = [];
+
+    if (!isSqliteVecAvailable()) reasons.push("sqlite_vec_extension_unavailable");
+    if (!schema) reasons.push("memory_vec_table_missing");
+    if (!this.vecInitialized) reasons.push("memory_vec_not_initialized");
+    if (counts.memoryVec === 0) reasons.push("memory_vec_empty");
+    if (counts.missingFromVec > 0) reasons.push("memory_vec_missing_embeddings");
+    if (counts.extraInVec > 0) reasons.push("memory_vec_extra_rows");
+
+    return {
+      sqliteVec: {
+        extensionLoaded: isSqliteVecAvailable(),
+        tableExists: schema !== null,
+        initialized: this.vecInitialized,
+        vectorDimensions: EMBEDDING_DIMENSIONS,
+        distanceMetric: "cosine",
+        schema,
+        lastPopulate: this.lastPopulate,
+      },
+      counts,
+      retrievalMode: reasons.length === 0 ? "vec" : "fallback",
+      reasons,
+    };
+  }
 }