wolbarg 0.5.2 → 0.5.4

package/dist/index.cjs

@@ -689,6 +689,45 @@ function withEmbeddingCache(provider, store, config) {
   };
 }
 
+// src/utils/vector.ts
+function cosineDistance(a, b) {
+  if (a.length !== b.length) {
+    throw new Error(
+      `cosineDistance dimension mismatch: a.length=${a.length}, b.length=${b.length}`
+    );
+  }
+  const len = a.length;
+  let dot = 0;
+  let normA = 0;
+  let normB = 0;
+  for (let i = 0; i < len; i += 1) {
+    const av = a[i] ?? 0;
+    const bv = b[i] ?? 0;
+    dot += av * bv;
+    normA += av * av;
+    normB += bv * bv;
+  }
+  if (normA === 0 || normB === 0) {
+    return 1;
+  }
+  const similarity = dot / (Math.sqrt(normA) * Math.sqrt(normB));
+  return 1 - similarity;
+}
+function bufferToEmbedding(data) {
+  const byteOffset = data.byteOffset ?? 0;
+  const byteLength = data.byteLength;
+  if (byteOffset % Float32Array.BYTES_PER_ELEMENT === 0) {
+    return new Float32Array(
+      data.buffer,
+      byteOffset,
+      byteLength / Float32Array.BYTES_PER_ELEMENT
+    );
+  }
+  const copy = new Uint8Array(byteLength);
+  copy.set(data);
+  return new Float32Array(copy.buffer);
+}
+
 // src/embedding/cache-store.ts
 var TOUCH_FLUSH_THRESHOLD = 64;
 var L1_DEFAULT_MAX = 5e4;
@@ -773,7 +812,9 @@ var SqliteEmbeddingCacheStore = class {
     }
     this.stmts = {
       get: db.prepare(
-        `SELECT vector, last_used_at, created_at FROM embedding_cache WHERE cache_key = ?`
+        `SELECT model, vector, last_used_at, created_at
+         FROM embedding_cache
+         WHERE cache_key = ?`
       ),
       delete: db.prepare(`DELETE FROM embedding_cache WHERE cache_key = ?`),
       set: db.prepare(
@@ -808,7 +849,29 @@ var SqliteEmbeddingCacheStore = class {
       this.l1.set(cacheKey, pending.model, pending.vector);
       return pending.vector;
     }
-    return null;
+    const db = this.requireDb();
+    if (!db) return null;
+    try {
+      const stmts = this.ensureStatements(db);
+      const row = stmts.get.get(cacheKey);
+      if (!row) return null;
+      if (this.ttlMs !== null) {
+        const createdMs = row.created_at ? Date.parse(row.created_at) : 0;
+        if (createdMs && Date.now() - createdMs > this.ttlMs) {
+          stmts.delete.run(cacheKey);
+          return null;
+        }
+      }
+      const vector = bufferToEmbedding(row.vector);
+      this.l1.set(cacheKey, row.model, vector);
+      this.pendingTouches.add(cacheKey);
+      if (this.pendingTouches.size >= TOUCH_FLUSH_THRESHOLD) {
+        this.schedulePersist();
+      }
+      return vector;
+    } catch {
+      return null;
+    }
   }
   async set(cacheKey, model, vector) {
     this.l1.set(cacheKey, model, vector);
@@ -860,6 +923,16 @@ var SqliteEmbeddingCacheStore = class {
     this.pendingSets.clear();
     const touches = [...this.pendingTouches];
     this.pendingTouches.clear();
+    const requeue = () => {
+      for (const [key, value] of sets) {
+        this.pendingSets.set(key, value);
+      }
+      for (const key of touches) {
+        this.pendingTouches.add(key);
+      }
+      this.stmts = null;
+      this.schedulePersist();
+    };
     const now = (/* @__PURE__ */ new Date()).toISOString();
     try {
       const stmts = this.ensureStatements(db);
@@ -894,10 +967,10 @@ var SqliteEmbeddingCacheStore = class {
           db.exec("ROLLBACK");
         } catch {
         }
-        this.stmts = null;
+        requeue();
       }
     } catch {
-      this.stmts = null;
+      requeue();
     }
   }
 };
@@ -1206,12 +1279,27 @@ var DocxParser = class {
   name = "docx";
   extensions = [".docx"];
   async parse(input) {
+    let mod;
+    try {
+      mod = await import('mammoth');
+    } catch (error) {
+      throw new ConfigurationError(
+        'DOCX ingest requires the optional peer package "mammoth". Install it with: npm install mammoth',
+        {
+          cause: error instanceof Error ? error : void 0,
+          suggestion: "npm install mammoth",
+          operation: "parse"
+        }
+      );
+    }
+    const extractRawText = mod.extractRawText ?? mod.default?.extractRawText;
+    if (!extractRawText) {
+      throw new ConfigurationError(
+        "DOCX ingest could not find mammoth.extractRawText. Ensure your mammoth version is compatible.",
+        { operation: "parse" }
+      );
+    }
     try {
-      const mod = await import('mammoth');
-      const extractRawText = mod.extractRawText ?? mod.default?.extractRawText;
-      if (!extractRawText) {
-        throw new Error("mammoth.extractRawText unavailable");
-      }
       const result = await extractRawText({ buffer: input.buffer });
       return {
         text: result.value ?? "",
@@ -1219,9 +1307,14 @@ var DocxParser = class {
         filename: input.filename,
         isImage: false
       };
-    } catch {
+    } catch (error) {
       throw new ConfigurationError(
-        'DOCX ingest requires the optional "mammoth" package. Install it with: npm install mammoth'
+        "DOCX ingest failed to parse the document (it may be corrupt or an unsupported .docx).",
+        {
+          cause: error instanceof Error ? error : void 0,
+          suggestion: "Try a different DOCX file or ensure it is not password-protected.",
+          operation: "parse"
+        }
       );
     }
   }
@@ -1368,6 +1461,12 @@ function compileComparison(field, op) {
   const extract = `json_extract(metadata_json, '${path8}')`;
   if ("eq" in op) {
     const value = op.eq;
+    if (value === null) {
+      return {
+        expression: `json_type(metadata_json, '${path8}') = 'null'`,
+        params: []
+      };
+    }
     if (value !== null && typeof value !== "string" && typeof value !== "number" && typeof value !== "boolean") {
       return null;
     }
@@ -1448,6 +1547,59 @@ function compileMetadataFilterToSql(filter) {
   return compileComparison(filter.field, filter.op);
 }
 
+// src/telemetry/logger.ts
+var LEVEL_ORDER = {
+  off: 100,
+  error: 50,
+  warn: 40,
+  info: 30,
+  debug: 20,
+  trace: 10
+};
+var WolbargLogger = class {
+  constructor(level = "info") {
+    this.level = level;
+  }
+  level;
+  setLevel(level) {
+    this.level = level;
+  }
+  getLevel() {
+    return this.level;
+  }
+  error(message, extra) {
+    this.write("error", message, extra);
+  }
+  warn(message, extra) {
+    this.write("warn", message, extra);
+  }
+  info(message, extra) {
+    this.write("info", message, extra);
+  }
+  debug(message, extra) {
+    this.write("debug", message, extra);
+  }
+  trace(message, extra) {
+    this.write("trace", message, extra);
+  }
+  write(level, message, extra) {
+    if (LEVEL_ORDER[level] < LEVEL_ORDER[this.level]) {
+      return;
+    }
+    if (this.level === "off") {
+      return;
+    }
+    const line = `[wolbarg:${level}] ${message}`;
+    if (level === "error") {
+      console.error(line, extra ?? "");
+    } else if (level === "warn") {
+      console.warn(line, extra ?? "");
+    } else {
+      console.log(line, extra ?? "");
+    }
+  }
+};
+
 // src/schema/index.ts
 var SCHEMA_VERSION = 4;
 var META_KEYS = {
@@ -1634,7 +1786,7 @@ var SQL = {
       AND k = ?
   `,
   insertEmbeddingBlob: `
-    INSERT INTO memory_embeddings_blob (memory_rowid, embedding) VALUES (?, ?)
+    INSERT OR REPLACE INTO memory_embeddings_blob (memory_rowid, embedding) VALUES (?, ?)
   `,
   deleteEmbeddingBlob: `
     DELETE FROM memory_embeddings_blob WHERE memory_rowid = ?
@@ -1762,40 +1914,6 @@ var SQL = {
   `
 };
 
-// src/utils/vector.ts
-function cosineDistance(a, b) {
-  const len = Math.min(a.length, b.length);
-  let dot = 0;
-  let normA = 0;
-  let normB = 0;
-  for (let i = 0; i < len; i += 1) {
-    const av = a[i] ?? 0;
-    const bv = b[i] ?? 0;
-    dot += av * bv;
-    normA += av * av;
-    normB += bv * bv;
-  }
-  if (normA === 0 || normB === 0) {
-    return 1;
-  }
-  const similarity = dot / (Math.sqrt(normA) * Math.sqrt(normB));
-  return 1 - similarity;
-}
-function bufferToEmbedding(data) {
-  const byteOffset = data.byteOffset ?? 0;
-  const byteLength = data.byteLength;
-  if (byteOffset % Float32Array.BYTES_PER_ELEMENT === 0) {
-    return new Float32Array(
-      data.buffer,
-      byteOffset,
-      byteLength / Float32Array.BYTES_PER_ELEMENT
-    );
-  }
-  const copy = new Uint8Array(byteLength);
-  copy.set(data);
-  return new Float32Array(copy.buffer);
-}
-
 // src/utils/vector-index.ts
 var InMemoryVectorIndex = class {
   dims;
@@ -1888,24 +2006,33 @@ var InMemoryVectorIndex = class {
         dot += queryNormalized[d] * data[base + d];
       }
       const distance = 1 - dot;
+      const rowid = rowids[i];
       if (heapSize < k) {
         heapDist[heapSize] = distance;
-        heapRow[heapSize] = rowids[i];
+        heapRow[heapSize] = rowid;
         heapSize += 1;
         if (heapSize === k) {
           buildMaxHeap(heapDist, heapRow, k);
         }
-      } else if (distance < heapDist[0]) {
-        heapDist[0] = distance;
-        heapRow[0] = rowids[i];
-        siftDown(heapDist, heapRow, 0, k);
+      } else {
+        const worstDist = heapDist[0];
+        const worstRow = heapRow[0];
+        if (distance < worstDist || distance === worstDist && rowid < worstRow) {
+          heapDist[0] = distance;
+          heapRow[0] = rowid;
+          siftDown(heapDist, heapRow, 0, k);
+        }
       }
     }
     const hits = new Array(heapSize);
     for (let i = 0; i < heapSize; i += 1) {
       hits[i] = { memoryRowid: heapRow[i], distance: heapDist[i] };
     }
-    hits.sort((a, b) => a.distance - b.distance);
+    hits.sort((a, b) => {
+      const diff = a.distance - b.distance;
+      if (diff !== 0) return diff;
+      return a.memoryRowid - b.memoryRowid;
+    });
     return hits;
   }
   ensureCapacity(needed) {
@@ -1951,8 +2078,8 @@ function siftDown(dist, rows, i, n) {
     let largest = i;
     const left = (i << 1) + 1;
     const right = left + 1;
-    if (left < n && dist[left] > dist[largest]) largest = left;
-    if (right < n && dist[right] > dist[largest]) largest = right;
+    if (left < n && (dist[left] > dist[largest] || dist[left] === dist[largest] && rows[left] > rows[largest])) largest = left;
+    if (right < n && (dist[right] > dist[largest] || dist[right] === dist[largest] && rows[right] > rows[largest])) largest = right;
     if (largest === i) return;
     const td = dist[i];
     dist[i] = dist[largest];
@@ -2094,6 +2221,9 @@ var BATCH_INSERT_CHUNK = 96;
 var MAX_ANN_OVERFETCH = 8192;
 var INSERT_COALESCE_THRESHOLD = 24;
 var INSERT_COALESCE_MAX = 96;
+var warnLogger = new WolbargLogger("warn");
+var warnedSqliteVecFallback = false;
+var warnedFtsKeywordSearch = false;
 var SqliteStorageProvider = class _SqliteStorageProvider {
   name = "sqlite";
   connectionString;
@@ -2103,6 +2233,10 @@ var SqliteStorageProvider = class _SqliteStorageProvider {
   vectorDimensions = null;
   vectorBackend = null;
   sqliteVecLoaded = false;
+  /** Tracks nesting depth for {@link withTransaction} so we can use savepoints. */
+  transactionDepth = 0;
+  /** Incrementing counter for deterministic savepoint names. */
+  savepointCounter = 0;
   /** Hot in-process ANN for blob backend (sqlite-vec unavailable platforms). */
   memoryIndex = null;
   memoryIndexDirty = false;
@@ -2169,6 +2303,12 @@ var SqliteStorageProvider = class _SqliteStorageProvider {
       } else if (this.sqliteVecLoaded) {
         this.vectorBackend = "sqlite-vec";
       } else {
+        if (!warnedSqliteVecFallback) {
+          warnedSqliteVecFallback = true;
+          warnLogger.warn(
+            "sqlite-vec unavailable on this platform; using blob ANN fallback."
+          );
+        }
         this.vectorBackend = "blob";
       }
       if (dims !== null) {
@@ -2412,6 +2552,12 @@ var SqliteStorageProvider = class _SqliteStorageProvider {
   async searchKeyword(query, organization, topK) {
     const stmts = this.requireStatements();
     if (!stmts.searchFts) {
+      if (!warnedFtsKeywordSearch) {
+        warnedFtsKeywordSearch = true;
+        warnLogger.warn(
+          "FTS keyword search is unavailable; returning empty keyword hits."
+        );
+      }
       return [];
     }
     try {
@@ -2425,7 +2571,16 @@ var SqliteStorageProvider = class _SqliteStorageProvider {
         // bm25 returns lower (more negative) for better matches — invert to [0, ∞)
         score: 1 / (1 + Math.abs(row.rank))
       }));
-    } catch {
+    } catch (error) {
+      if (!warnedFtsKeywordSearch) {
+        warnedFtsKeywordSearch = true;
+        warnLogger.warn(
+          "FTS keyword search failed; returning empty keyword hits.",
+          {
+            cause: error instanceof Error ? error.message : String(error)
+          }
+        );
+      }
       return [];
     }
   }
@@ -2590,6 +2745,13 @@ var SqliteStorageProvider = class _SqliteStorageProvider {
       this.deleteEmbeddingsForScope(organization);
       this.deleteFtsForScope(organization);
       const result = stmts.deleteMemoriesByOrg.run(organization);
+      try {
+        this.requireDb().exec(`
+          DELETE FROM memory_embeddings_blob
+          WHERE memory_rowid NOT IN (SELECT rowid FROM memories)
+        `);
+      } catch {
+      }
       return Number(result.changes);
     });
   }
@@ -2649,16 +2811,39 @@ var SqliteStorageProvider = class _SqliteStorageProvider {
   }
   async withTransaction(fn) {
     const db = this.requireDb();
-    return withImmediateTransaction(
-      db,
-      this.concurrency,
-      fn,
-      (attempt, delayMs) => {
-        this.retryLog?.(
-          `SQLITE_BUSY retry attempt=${attempt} backoffMs=${Math.round(delayMs)}`
-        );
+    if (this.transactionDepth > 0) {
+      const savepointName = `wolbarg_sp_${this.savepointCounter++}`;
+      db.exec(`SAVEPOINT ${savepointName}`);
+      try {
+        this.transactionDepth += 1;
+        const result = await fn();
+        db.exec(`RELEASE SAVEPOINT ${savepointName}`);
+        return result;
+      } catch (error) {
+        try {
+          db.exec(`ROLLBACK TO SAVEPOINT ${savepointName}`);
+        } catch {
+        }
+        throw error;
+      } finally {
+        this.transactionDepth -= 1;
       }
-    );
+    }
+    this.transactionDepth = 1;
+    try {
+      return await withImmediateTransaction(
+        db,
+        this.concurrency,
+        fn,
+        (attempt, delayMs) => {
+          this.retryLog?.(
+            `SQLITE_BUSY retry attempt=${attempt} backoffMs=${Math.round(delayMs)}`
+          );
+        }
+      );
+    } finally {
+      this.transactionDepth = 0;
+    }
   }
   // ─── internals ───────────────────────────────────────────────────────────
   tryLoadSqliteVec(db) {
@@ -3104,7 +3289,7 @@ var SqliteStorageProvider = class _SqliteStorageProvider {
     if (!stmt) {
       const values = Array.from({ length: n }, () => "(?, ?)").join(", ");
       stmt = this.requireDb().prepare(
-        `INSERT INTO memory_embeddings_blob (memory_rowid, embedding) VALUES ${values}`
+        `INSERT OR REPLACE INTO memory_embeddings_blob (memory_rowid, embedding) VALUES ${values}`
       );
       this.batchBlobEmbStatements.set(n, stmt);
     }
@@ -3812,9 +3997,13 @@ function createPostgresListenerFromPool(pool, onError) {
 
 // src/storage/providers/postgres.ts
 var txStore = new async_hooks.AsyncLocalStorage();
+var warnLogger2 = new WolbargLogger("warn");
+var warnedPgvectorFallback = false;
+var warnedFtsKeywordSearch2 = false;
+var warnedHnswSoftFail = false;
 var STMT = {
   insertOne: "Wolbarg_insert_one_v5",
-  insertBatch: "Wolbarg_insert_batch_v5"
+  insertBatch: "Wolbarg_insert_batch_v6"
 };
 function toFloat4Param(embedding) {
   const out = new Array(embedding.length);
@@ -3885,13 +4074,13 @@ var INSERT_ONE_SQL = `WITH mem AS (
 var INSERT_BATCH_SQL = `WITH mem AS (
    INSERT INTO memories (
      id, organization, agent, content_text, metadata_json,
-     archived, compressed_into, created_at, updated_at
+     archived, compressed_into, content_hash, created_at, updated_at
    )
-   SELECT id, org, agent, txt, meta::jsonb, false, NULL, c, u
+   SELECT id, org, agent, txt, meta::jsonb, false, NULL, h, c, u
    FROM unnest(
      $1::text[], $2::text[], $3::text[], $4::text[],
-     $5::text[], $6::timestamptz[], $7::timestamptz[]
-   ) AS t(id, org, agent, txt, meta, c, u)
+     $5::text[], $6::timestamptz[], $7::timestamptz[], $8::text[]
+   ) AS t(id, org, agent, txt, meta, c, u, h)
    RETURNING id
  ),
  hist AS (
@@ -3907,7 +4096,7 @@ var INSERT_BATCH_SQL = `WITH mem AS (
  emb AS (
    INSERT INTO memory_embeddings (memory_id, embedding, organization, agent, archived)
    SELECT id, emb::vector, org, agent, false
-   FROM unnest($1::text[], $8::text[], $2::text[], $3::text[]) AS t(id, emb, org, agent)
+   FROM unnest($1::text[], $9::text[], $2::text[], $3::text[]) AS t(id, emb, org, agent)
  )
  SELECT id FROM mem`;
 var COALESCE_FLUSH_MAX = 128;
@@ -4176,6 +4365,12 @@ var PostgresStorageProvider = class _PostgresStorageProvider {
         return;
       }
       this.hnswCreateFailures += 1;
+      if (this.hnswCreateFailures === 1 && !warnedHnswSoftFail) {
+        warnedHnswSoftFail = true;
+        warnLogger2.warn(
+          "HNSW index creation failed; ANN will fall back to sequential scan."
+        );
+      }
       if (this.hnswCreateFailures >= 3) {
         throw new DatabaseError(
           `Failed to create HNSW index after ${this.hnswCreateFailures} attempts: ${this.describe(error)}`,
@@ -4320,6 +4515,7 @@ var PostgresStorageProvider = class _PostgresStorageProvider {
     const metas = new Array(inputs.length);
     const created = new Array(inputs.length);
     const updated = new Array(inputs.length);
+    const contentHashes = new Array(inputs.length);
     const vectors = new Array(inputs.length);
     for (let i = 0; i < inputs.length; i += 1) {
       const input = inputs[i];
@@ -4330,6 +4526,7 @@ var PostgresStorageProvider = class _PostgresStorageProvider {
       metas[i] = serializeMetadata(input.metadata);
       created[i] = input.createdAt;
       updated[i] = input.updatedAt;
+      contentHashes[i] = input.contentHash !== void 0 ? input.contentHash : hashMemoryContent(input.contentText);
       vectors[i] = toVectorLiteral(input.embedding);
     }
     await this.queryNamed(STMT.insertBatch, INSERT_BATCH_SQL, [
@@ -4340,9 +4537,10 @@ var PostgresStorageProvider = class _PostgresStorageProvider {
       metas,
       created,
       updated,
+      contentHashes,
       vectors
     ]);
-    return inputs.map((input, i) => ({
+    return inputs.map((_, i) => ({
       id: ids[i],
       organization: orgs[i],
       agent: agents[i],
@@ -4350,7 +4548,7 @@ var PostgresStorageProvider = class _PostgresStorageProvider {
       metadata_json: metas[i],
       archived: 0,
       compressed_into: null,
-      content_hash: input.contentHash !== void 0 ? input.contentHash : null,
+      content_hash: contentHashes[i] ?? null,
       created_at: created[i],
       updated_at: updated[i]
     }));
@@ -4391,80 +4589,84 @@ var PostgresStorageProvider = class _PostgresStorageProvider {
     return out;
   }
   async insertOneBlob(input) {
-    const buf = Buffer.from(
-      input.embedding.buffer,
-      input.embedding.byteOffset,
-      input.embedding.byteLength
-    );
-    const contentHash = input.contentHash !== void 0 ? input.contentHash : hashMemoryContent(input.contentText);
-    const inserted = await this.query(
-      `INSERT INTO memories (
-        id, organization, agent, content_text, metadata_json,
-        archived, compressed_into, content_hash, created_at, updated_at
-      ) VALUES ($1,$2,$3,$4,$5::jsonb,false,NULL,$8,$6,$7)
-      RETURNING id, organization, agent, content_text, metadata_json,
-                archived::int AS archived, compressed_into, content_hash, created_at, updated_at`,
-      [
-        input.id,
-        input.organization,
-        input.agent,
-        input.contentText,
-        serializeMetadata(input.metadata),
-        input.createdAt,
-        input.updatedAt,
-        contentHash
-      ]
-    );
-    const row = this.mapRow(inserted.rows[0]);
-    await this.query(
-      `WITH mapped AS (
-         INSERT INTO memory_row_map (memory_id) VALUES ($1)
-         ON CONFLICT (memory_id) DO NOTHING
-       )
-       INSERT INTO memory_embeddings_blob (memory_id, embedding)
-       VALUES ($1, $2)
-       ON CONFLICT (memory_id) DO UPDATE SET embedding = EXCLUDED.embedding`,
-      [input.id, buf]
-    );
-    await this.query(
-      `INSERT INTO memory_history (id, memory_id, event_type, related_memory_id, created_at)
-       VALUES ($1,$2,'created',NULL,$3)`,
-      [crypto.randomUUID(), input.id, input.createdAt]
-    );
-    return row;
+    return this.withTransaction(async () => {
+      const buf = Buffer.from(
+        input.embedding.buffer,
+        input.embedding.byteOffset,
+        input.embedding.byteLength
+      );
+      const contentHash = input.contentHash !== void 0 ? input.contentHash : hashMemoryContent(input.contentText);
+      const inserted = await this.query(
+        `INSERT INTO memories (
+          id, organization, agent, content_text, metadata_json,
+          archived, compressed_into, content_hash, created_at, updated_at
+        ) VALUES ($1,$2,$3,$4,$5::jsonb,false,NULL,$8,$6,$7)
+        RETURNING id, organization, agent, content_text, metadata_json,
+                  archived::int AS archived, compressed_into, content_hash, created_at, updated_at`,
+        [
+          input.id,
+          input.organization,
+          input.agent,
+          input.contentText,
+          serializeMetadata(input.metadata),
+          input.createdAt,
+          input.updatedAt,
+          contentHash
+        ]
+      );
+      const row = this.mapRow(inserted.rows[0]);
+      await this.query(
+        `WITH mapped AS (
+           INSERT INTO memory_row_map (memory_id) VALUES ($1)
+           ON CONFLICT (memory_id) DO NOTHING
+         )
+         INSERT INTO memory_embeddings_blob (memory_id, embedding)
+         VALUES ($1, $2)
+         ON CONFLICT (memory_id) DO UPDATE SET embedding = EXCLUDED.embedding`,
+        [input.id, buf]
+      );
+      await this.query(
+        `INSERT INTO memory_history (id, memory_id, event_type, related_memory_id, created_at)
+         VALUES ($1,$2,'created',NULL,$3)`,
+        [crypto.randomUUID(), input.id, input.createdAt]
+      );
+      return row;
+    });
   }
   async updateMemory(input) {
-    const existing = await this.getMemoryById(input.id, input.organization);
-    if (!existing) {
-      return null;
-    }
-    const contentHash = input.contentHash !== void 0 ? input.contentHash : input.contentText !== void 0 ? hashMemoryContent(input.contentText) : existing.content_hash ?? null;
-    await this.query(
-      `UPDATE memories SET
-        content_text = COALESCE($1, content_text),
-        metadata_json = COALESCE($2::jsonb, metadata_json),
-        content_hash = COALESCE($3, content_hash),
-        updated_at = $4
-       WHERE id = $5 AND organization = $6`,
-      [
-        input.contentText ?? null,
-        input.metadata !== void 0 ? serializeMetadata(input.metadata) : null,
-        contentHash,
-        input.updatedAt,
-        input.id,
-        input.organization
-      ]
-    );
-    if (input.embedding) {
-      await this.deleteEmbedding(input.id);
-      await this.insertEmbedding(input.id, input.embedding);
-    }
-    await this.query(
-      `INSERT INTO memory_history (id, memory_id, event_type, related_memory_id, created_at)
-       VALUES ($1,$2,'updated',NULL,$3)`,
-      [crypto.randomUUID(), input.id, input.updatedAt]
-    );
-    return this.getMemoryById(input.id, input.organization);
+    return this.withTransaction(async () => {
+      const existing = await this.getMemoryById(input.id, input.organization);
+      if (!existing) {
+        return null;
+      }
+      const contentHash = input.contentHash !== void 0 ? input.contentHash : input.contentText !== void 0 ? hashMemoryContent(input.contentText) : existing.content_hash ?? null;
+      await this.query(
+        `UPDATE memories SET
+          content_text = COALESCE($1, content_text),
+          metadata_json = COALESCE($2::jsonb, metadata_json),
+          content_hash = COALESCE($3, content_hash),
+          updated_at = $4
+         WHERE id = $5 AND organization = $6`,
+        [
+          input.contentText ?? null,
+          input.metadata !== void 0 ? serializeMetadata(input.metadata) : null,
+          contentHash,
+          input.updatedAt,
+          input.id,
+          input.organization
+        ]
+      );
+      if (input.embedding) {
+        await this.deleteEmbedding(input.id);
+        await this.insertEmbedding(input.id, input.embedding);
+      }
+      await this.query(
+        `INSERT INTO memory_history (id, memory_id, event_type, related_memory_id, created_at)
+         VALUES ($1,$2,'updated',NULL,$3)`,
+        [crypto.randomUUID(), input.id, input.updatedAt]
+      );
+      return this.getMemoryById(input.id, input.organization);
+    });
   }
   async findActiveByContentHash(organization, agent, contentHash) {
     const result = await this.query(
@@ -4613,7 +4815,16 @@ var PostgresStorageProvider = class _PostgresStorageProvider {
         memoryId: String(row.memory_id),
         score: Number(row.rank)
       }));
-    } catch {
+    } catch (error) {
+      if (!warnedFtsKeywordSearch2) {
+        warnedFtsKeywordSearch2 = true;
+        warnLogger2.warn(
+          "FTS keyword search failed; returning empty keyword hits.",
+          {
+            cause: error instanceof Error ? error.message : String(error)
+          }
+        );
+      }
       return [];
     }
   }
@@ -4731,44 +4942,46 @@ var PostgresStorageProvider = class _PostgresStorageProvider {
     return mapHits(result.rows);
   }
   async archiveMemories(ids, organization, compressedIntoId, archivedAt) {
-    if (ids.length === 0) {
-      return [];
-    }
-    const result = await this.query(
-      `UPDATE memories
-       SET archived = true, compressed_into = $1, updated_at = $2
-       WHERE organization = $3 AND archived = false AND id = ANY($4::text[])
-       RETURNING id`,
-      [compressedIntoId, archivedAt, organization, ids]
-    );
-    const archived = result.rows.map((r) => String(r.id));
-    if (archived.length === 0) {
-      return [];
-    }
-    await this.query(
-      `UPDATE memory_embeddings
-       SET archived = true
-       WHERE memory_id = ANY($1::text[])`,
-      [archived]
-    ).catch(() => void 0);
-    const histIds = [];
-    const memIds = [];
-    const types = [];
-    const related = [];
-    const times = [];
-    for (const id of archived) {
-      histIds.push(crypto.randomUUID(), crypto.randomUUID());
-      memIds.push(id, compressedIntoId);
-      types.push("archived", "compressed");
-      related.push(compressedIntoId, id);
-      times.push(archivedAt, archivedAt);
-    }
-    await this.query(
-      `INSERT INTO memory_history (id, memory_id, event_type, related_memory_id, created_at)
-       SELECT * FROM unnest($1::text[], $2::text[], $3::text[], $4::text[], $5::timestamptz[])`,
-      [histIds, memIds, types, related, times]
-    );
-    return archived;
+    return this.withTransaction(async () => {
+      if (ids.length === 0) {
+        return [];
+      }
+      const result = await this.query(
+        `UPDATE memories
+         SET archived = true, compressed_into = $1, updated_at = $2
+         WHERE organization = $3 AND archived = false AND id = ANY($4::text[])
+         RETURNING id`,
+        [compressedIntoId, archivedAt, organization, ids]
+      );
+      const archived = result.rows.map((r) => String(r.id));
+      if (archived.length === 0) {
+        return [];
+      }
+      await this.query(
+        `UPDATE memory_embeddings
+         SET archived = true
+         WHERE memory_id = ANY($1::text[])`,
+        [archived]
+      );
+      const histIds = [];
+      const memIds = [];
+      const types = [];
+      const related = [];
+      const times = [];
+      for (const id of archived) {
+        histIds.push(crypto.randomUUID(), crypto.randomUUID());
+        memIds.push(id, compressedIntoId);
+        types.push("archived", "compressed");
+        related.push(compressedIntoId, id);
+        times.push(archivedAt, archivedAt);
+      }
+      await this.query(
+        `INSERT INTO memory_history (id, memory_id, event_type, related_memory_id, created_at)
+         SELECT * FROM unnest($1::text[], $2::text[], $3::text[], $4::text[], $5::timestamptz[])`,
+        [histIds, memIds, types, related, times]
+      );
+      return archived;
+    });
   }
   async deleteMemoryById(id, organization) {
     const result = await this.query(
@@ -4879,6 +5092,11 @@ var PostgresStorageProvider = class _PostgresStorageProvider {
       [META_KEYS.schemaVersion]
     ).catch(() => ({ rows: [] }));
     const current = versionRow.rows[0]?.value !== void 0 ? Number(versionRow.rows[0].value) : null;
+    if (current !== null && current > SCHEMA_VERSION) {
+      throw new InitializationError(
+        `Database schema version ${current} is newer than this Wolbarg SDK (${SCHEMA_VERSION}). Please upgrade Wolbarg to open this database.`
+      );
+    }
     if (current === SCHEMA_VERSION) {
       const tsvProbe2 = await this.query(
         `SELECT 1 FROM information_schema.columns
@@ -5029,8 +5247,17 @@ var PostgresStorageProvider = class _PostgresStorageProvider {
       await this.query(`CREATE EXTENSION IF NOT EXISTS vector`);
       _PostgresStorageProvider.pgvectorByConn.set(this.connectionString, true);
       return true;
-    } catch {
+    } catch (error) {
       _PostgresStorageProvider.pgvectorByConn.set(this.connectionString, false);
+      if (!warnedPgvectorFallback) {
+        warnedPgvectorFallback = true;
+        warnLogger2.warn(
+          "pgvector extension is unavailable; using blob cosine search fallback.",
+          {
+            cause: error instanceof Error ? error.message : `unknown error: ${String(error)}`
+          }
+        );
+      }
       return false;
     }
   }
@@ -5171,11 +5398,12 @@ function createDatabaseProvider(config) {
 }
 
 // src/version.ts
-var SDK_VERSION = "0.5.2";
+var SDK_VERSION = "0.5.4";
 
 // src/memory/transfer.ts
+var warnedMissingExportManifest = false;
 var SqliteMemoryTransferProvider = class {
-  async exportTo(exportPath, sourcePath, organization) {
+  async exportTo(exportPath, sourcePath, organization, embeddingModel, embeddingDimensions) {
     const resolvedSource = resolvePath(sourcePath);
     if (resolvedSource === ":memory:") {
       throw new ConfigurationError(
@@ -5202,7 +5430,9 @@ Initialize Wolbarg and verify the database path.`
       sdkVersion: SDK_VERSION,
       provider: "sqlite",
       sourcePath: resolvedSource,
-      organization
+      organization,
+      ...embeddingModel ? { embeddingModel } : {},
+      ...embeddingDimensions ? { embeddingDimensions } : {}
     };
     fs6__default.default.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2), "utf8");
     return {
@@ -5211,7 +5441,7 @@ Initialize Wolbarg and verify the database path.`
       sizeBytes: fs6__default.default.statSync(dbExportPath).size
     };
   }
-  async importFrom(exportPath, targetPath) {
+  async importFrom(exportPath, targetPath, expected) {
     const resolvedExport = resolvePath(exportPath);
     const dbExportPath = resolvedExport.endsWith(".db") ? resolvedExport : fs6__default.default.existsSync(`${resolvedExport}.db`) ? `${resolvedExport}.db` : resolvedExport;
     if (!fs6__default.default.existsSync(dbExportPath)) {
@@ -5229,30 +5459,61 @@ Pass the path returned by export().`
       manifest = JSON.parse(fs6__default.default.readFileSync(manifestPath, "utf8"));
       if (manifest.format !== "wolbarg-export-v1") {
         throw new ValidationError(
-          `Unsupported export format: ${String(manifest.format)}`
+          `Unsupported export format: ${String(manifest.format)}`
+        );
+      }
+    } else {
+      if (!warnedMissingExportManifest) {
+        warnedMissingExportManifest = true;
+        console.warn(
+          "[wolbarg:warn] export manifest is missing; skipping manifest-based import validation."
+        );
+      }
+    }
+    if (manifest) {
+      if (expected?.organization && manifest.organization && expected.organization !== manifest.organization) {
+        throw new ValidationError(
+          "Import failed: export organization does not match the current Wolbarg organization."
+        );
+      }
+      if (expected?.embeddingDimensions != null && manifest.embeddingDimensions != null && expected.embeddingDimensions !== manifest.embeddingDimensions) {
+        throw new ValidationError(
+          `Import failed: embedding dimension mismatch (expected ${expected.embeddingDimensions}, got ${manifest.embeddingDimensions}).`
+        );
+      }
+      if (expected?.embeddingModel && manifest.embeddingModel && expected.embeddingModel !== manifest.embeddingModel) {
+        throw new ValidationError(
+          `Import failed: embedding model mismatch (expected ${expected.embeddingModel}, got ${manifest.embeddingModel}).`
         );
       }
-    } else {
-      manifest = {
-        format: "wolbarg-export-v1",
-        exportedAt: nowIso(),
-        sdkVersion: SDK_VERSION,
-        provider: "sqlite",
-        sourcePath: dbExportPath
-      };
     }
     const resolvedTarget = resolvePath(targetPath);
     if (resolvedTarget === ":memory:") {
       throw new ConfigurationError("Cannot import into an in-memory database.");
     }
+    const tmpTarget = `${resolvedTarget}.tmp-import-${Date.now()}`;
+    for (const suffix of ["", "-wal", "-shm"]) {
+      const side = `${tmpTarget}${suffix}`;
+      if (fs6__default.default.existsSync(side)) {
+        fs6__default.default.rmSync(side, { force: true });
+      }
+    }
+    await copySqlite(dbExportPath, tmpTarget);
     for (const suffix of ["", "-wal", "-shm"]) {
       const side = `${resolvedTarget}${suffix}`;
       if (fs6__default.default.existsSync(side)) {
         fs6__default.default.rmSync(side, { force: true });
       }
     }
-    await copySqlite(dbExportPath, resolvedTarget);
-    return { path: resolvedTarget, manifest };
+    fs6__default.default.renameSync(tmpTarget, resolvedTarget);
+    for (const suffix of ["-wal", "-shm"]) {
+      const from = `${tmpTarget}${suffix}`;
+      const to = `${resolvedTarget}${suffix}`;
+      if (fs6__default.default.existsSync(from)) {
+        fs6__default.default.renameSync(from, to);
+      }
+    }
+    return { path: resolvedTarget, manifest: manifest ?? void 0 };
   }
 };
 async function copySqlite(sourcePath, destPath) {
@@ -5481,7 +5742,8 @@ function applyMmr(candidates, topK, lambda) {
         );
       }
       const score = lambda * relevance - (1 - lambda) * maxSim;
-      if (score > bestScore) {
+      const best = remaining[bestIdx];
+      if (score > bestScore || score === bestScore && candidate.id < best.id) {
         bestScore = score;
         bestIdx = i;
       }
@@ -6041,24 +6303,26 @@ var Neo4jGraphProvider = class {
     }
   }
   async run(cypher, params = {}) {
-    return this.withSession(async (session) => {
-      const result = await session.run(cypher, params);
-      return result.records.map((rec) => {
-        try {
-          return rec.toObject();
-        } catch {
-          const obj = {};
-          for (const key of rec.keys) {
-            obj[key] = unwrapNeo4jValue(rec.get(key));
-          }
-          return obj;
+    return this.withSession(
+      (session) => this.runOnSession(session, cypher, params)
+    );
+  }
+  async runOnSession(session, cypher, params = {}) {
+    const result = await session.run(cypher, params);
+    return result.records.map((rec) => {
+      try {
+        return rec.toObject();
+      } catch {
+        const obj = {};
+        for (const key of rec.keys) {
+          obj[key] = unwrapNeo4jValue(rec.get(key));
         }
-      });
+        return obj;
+      }
     });
   }
-  async ensureMemoryNode(id) {
-    await this.run(
-      `MERGE (m:Memory { id: $id })
+  async ensureMemoryNode(id, session) {
+    const cypher = `MERGE (m:Memory { id: $id })
        ON CREATE SET
          m.organization = '',
          m.agent = '',
@@ -6067,24 +6331,30 @@ var Neo4jGraphProvider = class {
          m.archived = false,
          m.compressed_into = '',
          m.created_at = '',
-         m.updated_at = ''`,
-      { id }
-    );
+         m.updated_at = ''`;
+    if (session) {
+      await this.runOnSession(session, cypher, { id });
+      return;
+    }
+    await this.run(cypher, { id });
   }
   async linkMemories(fromId, toId, relation, metadata) {
-    await this.ensureMemoryNode(fromId);
-    await this.ensureMemoryNode(toId);
-    await this.run(
-      `MATCH (a:Memory { id: $fromId }), (b:Memory { id: $toId })
-       MERGE (a)-[r:RELATED { relation: $relation }]->(b)
-       SET r.metadata_json = $metadata`,
-      {
-        fromId,
-        toId,
-        relation,
-        metadata: serializeMetadata2(metadata)
-      }
-    );
+    await this.withSession(async (session) => {
+      await this.ensureMemoryNode(fromId, session);
+      await this.ensureMemoryNode(toId, session);
+      await this.runOnSession(
+        session,
+        `MATCH (a:Memory { id: $fromId }), (b:Memory { id: $toId })
+         MERGE (a)-[r:RELATED { relation: $relation }]->(b)
+         SET r.metadata_json = $metadata`,
+        {
+          fromId,
+          toId,
+          relation,
+          metadata: serializeMetadata2(metadata)
+        }
+      );
+    });
   }
   async unlinkMemories(fromId, toId, relation) {
     if (relation !== void 0) {
@@ -6146,22 +6416,26 @@ var Neo4jGraphProvider = class {
     return id;
   }
   async linkEntityToMemory(entityId, memoryId, role) {
-    await this.ensureMemoryNode(memoryId);
-    const found = await this.run(
-      `MATCH (e:Entity { id: $id }) RETURN e.id AS id`,
-      { id: entityId }
-    );
-    if (found.length === 0) {
-      throw new DatabaseError(`Entity not found: ${entityId}`, {
-        operation: "linkEntityToMemory"
-      });
-    }
-    await this.run(
-      `MATCH (e:Entity { id: $entityId }), (m:Memory { id: $memoryId })
-       MERGE (e)-[r:MENTIONS]->(m)
-       SET r.role = $role`,
-      { entityId, memoryId, role: role ?? "" }
-    );
+    await this.withSession(async (session) => {
+      await this.ensureMemoryNode(memoryId, session);
+      const found = await this.runOnSession(
+        session,
+        `MATCH (e:Entity { id: $id }) RETURN e.id AS id`,
+        { id: entityId }
+      );
+      if (found.length === 0) {
+        throw new DatabaseError(`Entity not found: ${entityId}`, {
+          operation: "linkEntityToMemory"
+        });
+      }
+      await this.runOnSession(
+        session,
+        `MATCH (e:Entity { id: $entityId }), (m:Memory { id: $memoryId })
+         MERGE (e)-[r:MENTIONS]->(m)
+         SET r.role = $role`,
+        { entityId, memoryId, role: role ?? "" }
+      );
+    });
   }
   async deleteMemory(memoryId) {
     await this.run(
@@ -6234,6 +6508,21 @@ function assertNonEmpty(value, fieldName) {
     throw new ConfigurationError(`${fieldName} must be a non-empty string`);
   }
 }
+function assertFiniteNumber2(value, fieldName) {
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    throw new ConfigurationError(`${fieldName} must be a finite number`);
+  }
+}
+function assertNumberMin(value, fieldName, min) {
+  if (!Number.isFinite(value) || value < min) {
+    throw new ConfigurationError(`${fieldName} must be >= ${min}`);
+  }
+}
+function assertNumberInRange(value, fieldName, min, max) {
+  if (!Number.isFinite(value) || value < min || value > max) {
+    throw new ConfigurationError(`${fieldName} must be between ${min} and ${max}`);
+  }
+}
 function assertUrl(value, fieldName) {
   assertNonEmpty(value, fieldName);
   try {
@@ -6280,6 +6569,135 @@ function validateLlmConfig(config) {
     ...config.timeoutMs !== void 0 ? { timeoutMs: config.timeoutMs } : {}
   };
 }
+function validateRetrievalConfig(config) {
+  if (config === null || typeof config !== "object") {
+    throw new ConfigurationError("retrieval must be an object");
+  }
+  const out = {};
+  if (config.overFetchFactor !== void 0) {
+    assertFiniteNumber2(config.overFetchFactor, "retrieval.overFetchFactor");
+    assertNumberMin(config.overFetchFactor, "retrieval.overFetchFactor", 0);
+    if (config.overFetchFactor <= 0) {
+      throw new ConfigurationError("retrieval.overFetchFactor must be > 0");
+    }
+    out.overFetchFactor = config.overFetchFactor;
+  }
+  if (config.hybrid !== void 0) {
+    if (config.hybrid === null || typeof config.hybrid !== "object") {
+      throw new ConfigurationError("retrieval.hybrid must be an object");
+    }
+    const hybrid = config.hybrid;
+    const outHybrid = {};
+    if (hybrid.semanticWeight !== void 0) {
+      assertFiniteNumber2(hybrid.semanticWeight, "retrieval.hybrid.semanticWeight");
+      if (hybrid.semanticWeight < 0) {
+        throw new ConfigurationError(
+          "retrieval.hybrid.semanticWeight must be >= 0"
+        );
+      }
+      outHybrid.semanticWeight = hybrid.semanticWeight;
+    }
+    if (hybrid.keywordWeight !== void 0) {
+      assertFiniteNumber2(hybrid.keywordWeight, "retrieval.hybrid.keywordWeight");
+      if (hybrid.keywordWeight < 0) {
+        throw new ConfigurationError(
+          "retrieval.hybrid.keywordWeight must be >= 0"
+        );
+      }
+      outHybrid.keywordWeight = hybrid.keywordWeight;
+    }
+    if (Object.keys(outHybrid).length > 0) {
+      out.hybrid = outHybrid;
+    }
+  }
+  if (config.mmr !== void 0) {
+    if (config.mmr === null || typeof config.mmr !== "object") {
+      throw new ConfigurationError("retrieval.mmr must be an object");
+    }
+    const mmr = config.mmr;
+    const outMmr = {};
+    if (mmr.lambda !== void 0) {
+      assertFiniteNumber2(mmr.lambda, "retrieval.mmr.lambda");
+      assertNumberInRange(mmr.lambda, "retrieval.mmr.lambda", 0, 1);
+      outMmr.lambda = mmr.lambda;
+    }
+    if (Object.keys(outMmr).length > 0) {
+      out.mmr = outMmr;
+    }
+  }
+  return out;
+}
+function validateMemoryDedupeConfig(config) {
+  if (config === null || typeof config !== "object") {
+    throw new ConfigurationError("memory.dedupe must be an object");
+  }
+  const out = {};
+  if (config.enabled !== void 0) {
+    if (typeof config.enabled !== "boolean") {
+      throw new ConfigurationError("memory.dedupe.enabled must be a boolean");
+    }
+    out.enabled = config.enabled;
+  }
+  if (config.strategy !== void 0) {
+    const allowed = /* @__PURE__ */ new Set(["exact", "near", "exact-or-near"]);
+    if (!allowed.has(config.strategy)) {
+      throw new ConfigurationError(
+        `memory.dedupe.strategy must be one of ${Array.from(allowed).join(", ")}`
+      );
+    }
+    out.strategy = config.strategy;
+  }
+  if (config.nearThreshold !== void 0) {
+    assertFiniteNumber2(config.nearThreshold, "memory.dedupe.nearThreshold");
+    assertNumberInRange(
+      config.nearThreshold,
+      "memory.dedupe.nearThreshold",
+      0,
+      1
+    );
+    out.nearThreshold = config.nearThreshold;
+  }
+  if (config.nearCandidateLimit !== void 0) {
+    assertFiniteNumber2(
+      config.nearCandidateLimit,
+      "memory.dedupe.nearCandidateLimit"
+    );
+    assertNumberMin(
+      config.nearCandidateLimit,
+      "memory.dedupe.nearCandidateLimit",
+      1
+    );
+    out.nearCandidateLimit = config.nearCandidateLimit;
+  }
+  return out;
+}
+function validateEmbeddingCacheConfig(config) {
+  if (config === null || typeof config !== "object") {
+    throw new ConfigurationError("embeddingCache must be an object");
+  }
+  const out = {};
+  if (config.enabled !== void 0) {
+    if (typeof config.enabled !== "boolean") {
+      throw new ConfigurationError("embeddingCache.enabled must be a boolean");
+    }
+    out.enabled = config.enabled;
+  }
+  if (config.ttlMs !== void 0) {
+    assertFiniteNumber2(config.ttlMs, "embeddingCache.ttlMs");
+    if (config.ttlMs < 0) {
+      throw new ConfigurationError("embeddingCache.ttlMs must be >= 0");
+    }
+    out.ttlMs = config.ttlMs;
+  }
+  if (config.maxEntries !== void 0) {
+    assertFiniteNumber2(config.maxEntries, "embeddingCache.maxEntries");
+    if (config.maxEntries < 0) {
+      throw new ConfigurationError("embeddingCache.maxEntries must be >= 0");
+    }
+    out.maxEntries = config.maxEntries;
+  }
+  return out;
+}
 function normalizeDatabaseConfig(config) {
   const provider = config.provider;
   if (provider !== "sqlite" && provider !== "postgres") {
@@ -6389,11 +6807,22 @@ function validateWolbargOptions(options) {
     throw new ConfigurationError("Wolbarg options must be an object");
   }
   assertNonEmpty(options.organization, "organization");
+  const checkpointDirectory = options.checkpointDirectory !== void 0 ? (() => {
+    assertNonEmpty(options.checkpointDirectory, "checkpointDirectory");
+    return options.checkpointDirectory.trim();
+  })() : void 0;
   const storageInput = resolveStorageInput(options);
   let storage = storageInput;
   if (!isStorageProvider(storageInput)) {
     storage = normalizeDatabaseConfig(storageInput);
   }
+  if (!isStorageProvider(storageInput) && storageInput.provider === "postgres" && storageInput.maxPoolSize !== void 0) {
+    assertFiniteNumber2(
+      storageInput.maxPoolSize,
+      "database.maxPoolSize"
+    );
+    assertNumberMin(storageInput.maxPoolSize, "database.maxPoolSize", 1);
+  }
   if (!options.embedding) {
     throw new ConfigurationError("embedding is required");
   }
@@ -6411,13 +6840,20 @@ function validateWolbargOptions(options) {
   if (graph !== void 0) {
     graph = resolveGraphInput(graph);
   }
+  const retrieval = options.retrieval !== void 0 ? validateRetrievalConfig(options.retrieval) : void 0;
+  const embeddingCache = options.embeddingCache !== void 0 ? validateEmbeddingCacheConfig(options.embeddingCache) : void 0;
+  const memory = options.memory !== void 0 && options.memory.dedupe !== void 0 ? { ...options.memory, dedupe: validateMemoryDedupeConfig(options.memory.dedupe) } : options.memory;
   return {
     ...options,
     organization: options.organization.trim(),
     storage,
     database: void 0,
     ...telemetry ? { telemetry } : {},
-    ...graph !== void 0 ? { graph } : {}
+    ...graph !== void 0 ? { graph } : {},
+    ...retrieval !== void 0 ? { retrieval } : {},
+    ...embeddingCache !== void 0 ? { embeddingCache } : {},
+    ...checkpointDirectory !== void 0 ? { checkpointDirectory } : {},
+    ...memory !== void 0 ? { memory } : {}
   };
 }
 function resolveGraphInput(input) {
@@ -6476,59 +6912,6 @@ function resolveGraphInput(input) {
   );
 }
 
-// src/telemetry/logger.ts
-var LEVEL_ORDER = {
-  off: 100,
-  error: 50,
-  warn: 40,
-  info: 30,
-  debug: 20,
-  trace: 10
-};
-var WolbargLogger = class {
-  constructor(level = "info") {
-    this.level = level;
-  }
-  level;
-  setLevel(level) {
-    this.level = level;
-  }
-  getLevel() {
-    return this.level;
-  }
-  error(message, extra) {
-    this.write("error", message, extra);
-  }
-  warn(message, extra) {
-    this.write("warn", message, extra);
-  }
-  info(message, extra) {
-    this.write("info", message, extra);
-  }
-  debug(message, extra) {
-    this.write("debug", message, extra);
-  }
-  trace(message, extra) {
-    this.write("trace", message, extra);
-  }
-  write(level, message, extra) {
-    if (LEVEL_ORDER[level] < LEVEL_ORDER[this.level]) {
-      return;
-    }
-    if (this.level === "off") {
-      return;
-    }
-    const line = `[wolbarg:${level}] ${message}`;
-    if (level === "error") {
-      console.error(line, extra ?? "");
-    } else if (level === "warn") {
-      console.warn(line, extra ?? "");
-    } else {
-      console.log(line, extra ?? "");
-    }
-  }
-};
-
 // src/telemetry/trace.ts
 function createSessionId() {
   return createId();
@@ -6613,14 +6996,14 @@ var TelemetryEmitter = class {
       const totalMs = performance.now() - startedAt;
       const errMessage = error instanceof Error ? error.message : error ? String(error) : fields?.error ?? null;
       const errStack = error instanceof Error ? error.stack ?? null : fields?.errorStack ?? null;
+      if (!self.config.enabled) {
+        return;
+      }
       if (status === "error") {
         self.logger.error(`${operation} failed: ${errMessage ?? "unknown"}`);
       } else {
         self.logger.debug(`${operation} completed in ${totalMs.toFixed(2)}ms`);
       }
-      if (!self.config.enabled) {
-        return;
-      }
       const event = {
         id: createId(),
         timestamp: nowIso(),
@@ -6922,8 +7305,10 @@ var SqliteEventDatabase = class {
       }
     }
     if (options.memoryId) {
-      clauses.push(`memory_ids_json LIKE ?`);
-      params.push(`%${options.memoryId}%`);
+      clauses.push(
+        `EXISTS (SELECT 1 FROM json_each(memory_ids_json) WHERE json_each.value = ?)`
+      );
+      params.push(options.memoryId);
     }
     if (options.queryText) {
       clauses.push(`query LIKE ?`);
@@ -7100,6 +7485,7 @@ function describe2(error) {
 }
 
 // src/providers/sqlite/sqliteTelemetryProvider.ts
+var MAX_QUEUE_SIZE = 1e4;
 var SqliteTelemetryProvider = class {
   name = "sqlite";
   db;
@@ -7107,6 +7493,8 @@ var SqliteTelemetryProvider = class {
   flushing = null;
   closed = false;
   openPromise = null;
+  warnedQueueDrop = false;
+  warnedFlushFailure = false;
   constructor(options) {
     this.db = new SqliteEventDatabase({ url: options.url });
   }
@@ -7127,6 +7515,15 @@ var SqliteTelemetryProvider = class {
     if (this.closed) {
       return;
     }
+    if (this.queue.length >= MAX_QUEUE_SIZE) {
+      this.queue.shift();
+      if (!this.warnedQueueDrop) {
+        this.warnedQueueDrop = true;
+        console.warn(
+          `[wolbarg telemetry] event queue capped at ${MAX_QUEUE_SIZE}; dropping oldest events`
+        );
+      }
+    }
     this.queue.push(event);
     void this.scheduleFlush();
   }
@@ -7169,7 +7566,13 @@ var SqliteTelemetryProvider = class {
           await this.db.insertEvent(event);
         }
       }
-    } catch {
+    } catch (error) {
+      if (!this.warnedFlushFailure) {
+        this.warnedFlushFailure = true;
+        console.warn(
+          `[wolbarg telemetry] flush failed; dropping batch: ${error instanceof Error ? error.message : String(error)}`
+        );
+      }
     }
   }
 };
@@ -7212,8 +7615,20 @@ Ensure Wolbarg has been initialized and the database path is correct.`
       );
     }
     const snapshotPath = this.snapshotPath(name);
-    await safeSqliteBackup(resolvedSource, snapshotPath);
-    const stats = fs6__default.default.statSync(snapshotPath);
+    const tmpSnapshotPath = `${snapshotPath}.tmp-${Date.now()}`;
+    try {
+      await safeSqliteBackup(resolvedSource, tmpSnapshotPath);
+    } catch (error) {
+      if (fs6__default.default.existsSync(tmpSnapshotPath)) {
+        fs6__default.default.rmSync(tmpSnapshotPath, { force: true });
+      }
+      throw error;
+    }
+    const stats = fs6__default.default.statSync(tmpSnapshotPath);
+    if (fs6__default.default.existsSync(snapshotPath)) {
+      fs6__default.default.rmSync(snapshotPath, { force: true });
+    }
+    fs6__default.default.renameSync(tmpSnapshotPath, snapshotPath);
     const meta2 = {
       name,
       description: options?.description ?? null,
@@ -7224,7 +7639,9 @@ Ensure Wolbarg has been initialized and the database path is correct.`
       sourcePath: resolvedSource,
       sizeBytes: stats.size
     };
-    fs6__default.default.writeFileSync(metaPath, JSON.stringify(meta2, null, 2), "utf8");
+    const tmpMetaPath = `${metaPath}.tmp-${Date.now()}`;
+    fs6__default.default.writeFileSync(tmpMetaPath, JSON.stringify(meta2, null, 2), "utf8");
+    fs6__default.default.renameSync(tmpMetaPath, metaPath);
     return meta2;
   }
   async rollback(name, targetPath) {
@@ -7488,6 +7905,9 @@ var SqliteSubscribeEmitter = class {
 };
 
 // src/core/wolbarg.ts
+var warnLogger3 = new WolbargLogger("warn");
+var warnedHybridNoKeyword = false;
+var warnedRerankNoProvider = false;
 var Wolbarg = class {
   initialized = false;
   booting = null;
@@ -7593,6 +8013,7 @@ var Wolbarg = class {
     this.storage = createStorageProvider(validated.database);
     this.memoryDbPath = resolveDatabaseUrl(validated.database);
     this.embedding = createEmbeddingProvider(validated.embedding);
+    this.rawEmbedding = this.embedding;
     if (validated.llm) {
       this.llm = createLlmProvider(validated.llm);
       this.compression = createCompressionProvider(this.llm);
@@ -7914,7 +8335,7 @@ var Wolbarg = class {
    * Update an existing memory by id (re-embeds when content changes).
    */
   async update(options) {
-    const trace = this.telemetry.start("remember");
+    const trace = this.telemetry.start("update");
     try {
       const { storage, embedding, organization } = await this.requireReady();
       assertNonEmptyString(options.id, "id");
@@ -8440,17 +8861,37 @@ var Wolbarg = class {
           }
         }
       }
+      if (hybridWeights && keywordSignal === "disabled" && !warnedHybridNoKeyword) {
+        warnedHybridNoKeyword = true;
+        warnLogger3.warn(
+          "hybrid search requested but no keyword channel is available; using semantic-only results."
+        );
+      }
       const tRank = performance.now();
-      let results = [...byId.values()].sort(
-        (a, b) => b.similarity - a.similarity
-      );
+      let results = [...byId.values()].sort((a, b) => {
+        const diff = b.similarity - a.similarity;
+        if (diff !== 0) return diff;
+        return a.id.localeCompare(b.id);
+      });
       const mmrLambda = resolveMmr(options.mmr) ?? resolveMmr(
         this.retrievalConfig.mmr ? { lambda: this.retrievalConfig.mmr.lambda } : void 0
       );
       let rankingReason = "cosine similarity";
+      let mmrApplied = false;
       if (mmrLambda !== null) {
-        results = applyMmr(results, Math.max(topK * 2, topK), mmrLambda);
-        rankingReason = `MMR(lambda=${mmrLambda})`;
+        mmrApplied = results.length > topK;
+        if (mmrApplied) {
+          results = applyMmr(results, topK, mmrLambda);
+          rankingReason = `MMR(lambda=${mmrLambda})`;
+        } else {
+          rankingReason = `MMR(lambda=${mmrLambda})(skipped:insufficient_candidates)`;
+        }
+      }
+      if (options.rerank === true && !this.reranker && !warnedRerankNoProvider) {
+        warnedRerankNoProvider = true;
+        warnLogger3.warn(
+          "rerank is enabled but no reranker provider is configured; using identity order."
+        );
       }
       if (options.rerank && this.reranker) {
         const reranked = await this.reranker.rerank(
@@ -8485,14 +8926,16 @@ var Wolbarg = class {
         agentId: options.filter?.agent ?? commonAgent(serialized.map((result) => result.agent)),
         tags: commonTags(serialized.map((result) => result.metadata))
       };
-      if (!explain) {
-        if (options.includeGraph === true && this.graph) {
-          const tGraph = performance.now();
-          for (const hit of serialized) {
+      if (options.includeGraph === true && this.graph) {
+        const tGraph = performance.now();
+        await Promise.all(
+          serialized.map(async (hit) => {
             hit.related = await this.hydrateRelated(hit.id);
-          }
-          trace.mark("databaseReadMs", performance.now() - tGraph);
-        }
+          })
+        );
+        trace.mark("databaseReadMs", performance.now() - tGraph);
+      }
+      if (!explain) {
         trace.success(telemetryFields);
         return serialized;
       }
@@ -8521,7 +8964,7 @@ var Wolbarg = class {
           semantic: "enabled",
           keyword: keywordSignal,
           reranker: options.rerank === true && this.reranker ? "enabled" : "disabled",
-          mmr: mmrLambda === null ? "disabled" : "enabled",
+          mmr: mmrLambda === null ? "disabled" : mmrApplied ? "enabled" : "disabled",
           recency: "disabled"
         },
         results: explanations.map((hit) => ({
@@ -8630,31 +9073,34 @@ var Wolbarg = class {
       const timestamp = nowIso();
       const result = await this.withWriteLock(async () => {
         const tWrite = performance.now();
-        const summaryRow = await storage.insertMemory({
-          id: summaryId,
-          organization,
-          agent: options.agent.trim(),
-          contentText: summaryText,
-          metadata: {
-            compressed: true,
-            sourceCount: records.length,
-            sourceIds: records.map((r) => r.id)
-          },
-          embedding: vector,
-          createdAt: timestamp,
-          updatedAt: timestamp
+        const txResult = await storage.withTransaction(async () => {
+          const summaryRow = await storage.insertMemory({
+            id: summaryId,
+            organization,
+            agent: options.agent.trim(),
+            contentText: summaryText,
+            metadata: {
+              compressed: true,
+              sourceCount: records.length,
+              sourceIds: records.map((r) => r.id)
+            },
+            embedding: vector,
+            createdAt: timestamp,
+            updatedAt: timestamp
+          });
+          const archivedIds = await storage.archiveMemories(
+            records.map((r) => r.id),
+            organization,
+            summaryId,
+            timestamp
+          );
+          return {
+            summary: toMemoryRecord(summaryRow),
+            archivedIds
+          };
         });
-        const archivedIds = await storage.archiveMemories(
-          records.map((r) => r.id),
-          organization,
-          summaryId,
-          timestamp
-        );
         trace.mark("databaseWriteMs", performance.now() - tWrite);
-        return {
-          summary: toMemoryRecord(summaryRow),
-          archivedIds
-        };
+        return txResult;
       });
       trace.success({
         provider: storage.name,
@@ -8886,8 +9332,23 @@ var Wolbarg = class {
       await this.requireReady();
       const graph = this.requireGraph("getRelated");
       assertNonEmptyString(memoryId, "memoryId");
+      let validatedOptions = options;
+      if (options?.depth !== void 0) {
+        if (!Number.isFinite(options.depth)) {
+          throw new ConfigurationError("graph.depth must be a finite number");
+        }
+        if (options.depth < 1) {
+          throw new ConfigurationError("graph.depth must be >= 1");
+        }
+        if (options.depth > 16) {
+          validatedOptions = { ...options, depth: 16 };
+        }
+      }
       const tGraph = performance.now();
-      const related = await this.hydrateRelated(memoryId.trim(), options);
+      const related = await this.hydrateRelated(
+        memoryId.trim(),
+        validatedOptions
+      );
       trace.mark("databaseReadMs", performance.now() - tGraph);
       trace.success({
         provider: graph.name,
@@ -9056,7 +9517,15 @@ var Wolbarg = class {
       this.assertGraphCheckpointSupported("checkpoint");
       const tCheckpoint = performance.now();
       const meta2 = await provider.checkpoint(name, source, options);
-      await this.snapshotGraphAlongside(meta2.snapshotPath, "checkpoint");
+      try {
+        await this.snapshotGraphAlongside(meta2.snapshotPath, "checkpoint");
+      } catch (error) {
+        const sidecar = this.graphSnapshotDir(meta2.snapshotPath);
+        if (fs6__default.default.existsSync(sidecar)) {
+          fs6__default.default.rmSync(sidecar, { recursive: true, force: true });
+        }
+        throw error;
+      }
       trace.mark("databaseWriteMs", performance.now() - tCheckpoint);
       trace.success({
         provider: provider.name,
@@ -9120,8 +9589,15 @@ var Wolbarg = class {
     try {
       await this.requireReady();
       const provider = this.requireCheckpointProvider();
+      const existing = await provider.getCheckpoint(name);
       const tDelete = performance.now();
       const removed = await provider.deleteCheckpoint(name);
+      if (removed && existing) {
+        const sidecar = this.graphSnapshotDir(existing.snapshotPath);
+        if (fs6__default.default.existsSync(sidecar)) {
+          fs6__default.default.rmSync(sidecar, { recursive: true, force: true });
+        }
+      }
       trace.mark("databaseWriteMs", performance.now() - tDelete);
       trace.success({
         provider: provider.name,
@@ -9183,7 +9659,9 @@ var Wolbarg = class {
       const result = await this.transfer.exportTo(
         exportPath,
         source,
-        this.organization ?? void 0
+        this.organization ?? void 0,
+        this.embedding?.model,
+        this.embeddingDimensions ?? void 0
       );
       await this.snapshotGraphAlongside(result.path, "export");
       trace.success({
@@ -9206,16 +9684,21 @@ var Wolbarg = class {
     let storageClosed = false;
     try {
       await this.requireReady();
+      this.assertGraphCheckpointSupported("import");
       const target = this.requireMemoryDbPath();
       if (this.storage) {
         await this.storage.close();
         storageClosed = true;
       }
       const graphClosed = await this.closeGraphForSnapshot();
-      this.assertGraphCheckpointSupported("import");
       const result = await this.transfer.importFrom(
         exportPath,
-        target
+        target,
+        {
+          organization: this.organization ?? void 0,
+          embeddingModel: this.embedding?.model,
+          embeddingDimensions: this.embeddingDimensions ?? void 0
+        }
       );
       await this.restoreGraphAlongside(result.path, "import");
       if (graphClosed) {
@@ -9410,18 +9893,26 @@ var Wolbarg = class {
     const graph = this.requireGraph("getRelated");
     const related = await graph.getRelated(memoryId, options);
     const { storage, organization } = await this.requireReady();
+    const rows = await Promise.all(
+      related.map((stub) => storage.getMemoryById(stub.id, organization))
+    );
     const out = [];
-    for (const stub of related) {
-      const row = await storage.getMemoryById(stub.id, organization);
-      if (row) {
-        out.push(toMemoryRecord(row));
-      } else {
-        out.push(stub);
-      }
+    for (let i = 0; i < related.length; i += 1) {
+      const stub = related[i];
+      const row = rows[i];
+      out.push(row ? toMemoryRecord(row) : stub);
     }
     return out;
   }
   requireMemoryDbPath() {
+    if (this.storage && !(this.storage instanceof SqliteStorageProvider)) {
+      throw new ConfigurationError(
+        "This operation requires a file-backed SQLite database (checkpoints / export-import are not supported for PostgreSQL).",
+        {
+          suggestion: 'Use database: { provider: "sqlite", url: "./memory.db" }'
+        }
+      );
+    }
     if (!this.memoryDbPath || this.memoryDbPath === ":memory:") {
       throw new ConfigurationError(
         "This operation requires a file-backed SQLite memory database (not :memory:).",
@@ -9650,7 +10141,14 @@ var HttpRerankerProvider = class {
         }));
       }
       const parsed = this.options.parseResults(body, documents);
-      return parsed.slice(0, topK);
+      const hits = parsed.slice(0, topK);
+      if (hits.length === 0) {
+        return documents.slice(0, topK).map((d, i) => ({
+          id: d.id,
+          score: 1 - i / Math.max(documents.length, 1)
+        }));
+      }
+      return hits;
     } catch {
       return documents.slice(0, topK).map((d, i) => ({
         id: d.id,
@@ -9835,21 +10333,31 @@ function tesseract() {
   return {
     name: "tesseract",
     async recognize(image) {
+      let mod;
       try {
-        const mod = await import('tesseract.js');
-        const createWorker = mod.createWorker ?? mod.default?.createWorker;
-        if (!createWorker) {
-          return { text: "" };
-        }
-        const worker = await createWorker("eng");
-        try {
-          const result = await worker.recognize(image);
-          return { text: result.data.text.trim() };
-        } finally {
-          await worker.terminate();
-        }
-      } catch {
-        return { text: "" };
+        mod = await import('tesseract.js');
+      } catch (error) {
+        throw new ConfigurationError(
+          'OCR provider "tesseract" requires the optional peer package "tesseract.js". Install it with: npm install tesseract.js',
+          {
+            cause: error instanceof Error ? error : void 0,
+            suggestion: "npm install tesseract.js",
+            operation: "recognize"
+          }
+        );
+      }
+      const createWorker = mod.createWorker ?? mod.default?.createWorker;
+      if (!createWorker) {
+        throw new ConfigurationError(
+          'OCR provider "tesseract" could not find tesseract.js.createWorker. Ensure your tesseract.js version is compatible.'
+        );
+      }
+      const worker = await createWorker("eng");
+      try {
+        const result = await worker.recognize(image);
+        return { text: result.data.text.trim() };
+      } finally {
+        await worker.terminate();
       }
     }
   };