wolbarg 0.5.3 → 0.5.5

package/dist/index.cjs

@@ -42,6 +42,11 @@ var WolbargError = class extends Error {
   reason;
   suggestion;
   operation;
+  /**
+   * @param message - Human-readable error message.
+   * @param code - Stable error code string.
+   * @param options - Optional cause, reason, suggestion, and operation name.
+   */
   constructor(message, code, options) {
     super(message, options);
     this.name = "WolbargError";
@@ -53,48 +58,80 @@ var WolbargError = class extends Error {
   }
 };
 var InitializationError = class extends WolbargError {
+  /**
+   * @param message - Description of the initialization failure.
+   * @param options - Optional cause and structured hints.
+   */
   constructor(message, options) {
     super(message, "INITIALIZATION_ERROR", options);
     this.name = "InitializationError";
   }
 };
 var ConfigurationError = class extends WolbargError {
+  /**
+   * @param message - Description of the misconfiguration.
+   * @param options - Optional cause, reason, suggestion, and operation name.
+   */
   constructor(message, options) {
     super(message, "CONFIGURATION_ERROR", options);
     this.name = "ConfigurationError";
   }
 };
 var ValidationError = class extends WolbargError {
+  /**
+   * @param message - Which argument failed and why.
+   * @param options - Optional cause and structured hints.
+   */
   constructor(message, options) {
     super(message, "VALIDATION_ERROR", options);
     this.name = "ValidationError";
   }
 };
 var DatabaseError = class extends WolbargError {
+  /**
+   * @param message - Operation-scoped failure message.
+   * @param options - Optional underlying `cause` and hints.
+   */
   constructor(message, options) {
     super(message, "DATABASE_ERROR", options);
     this.name = "DatabaseError";
   }
 };
 var StorageLockedError = class extends WolbargError {
+  /**
+   * @param message - Lock contention description.
+   * @param options - Typically includes suggestion to tune concurrency or use Postgres.
+   */
   constructor(message, options) {
     super(message, "WOLBARG_STORAGE_LOCKED", options);
     this.name = "StorageLockedError";
   }
 };
 var EmbeddingError = class extends WolbargError {
+  /**
+   * @param message - Embedding failure description.
+   * @param options - Optional HTTP cause and provider hints.
+   */
   constructor(message, options) {
     super(message, "EMBEDDING_ERROR", options);
     this.name = "EmbeddingError";
   }
 };
 var CompressionError = class extends WolbargError {
+  /**
+   * @param message - Compression failure description.
+   * @param options - Optional LLM cause chain.
+   */
   constructor(message, options) {
     super(message, "COMPRESSION_ERROR", options);
     this.name = "CompressionError";
   }
 };
 var MemoryNotFoundError = class extends WolbargError {
+  /**
+   * @param message - Which memory was not found.
+   * @param options - Optional operation context.
+   */
   constructor(message, options) {
     super(message, "MEMORY_NOT_FOUND", options);
     this.name = "MemoryNotFoundError";
@@ -102,6 +139,11 @@ var MemoryNotFoundError = class extends WolbargError {
 };
 var ProviderNotConfiguredError = class extends ConfigurationError {
   provider;
+  /**
+   * @param provider - Provider name (e.g. `"reranker"`, `"graph"`).
+   * @param method - Facade method that requires the provider.
+   * @param hint - Install or config instruction shown to the developer.
+   */
   constructor(provider, method, hint) {
     super(`${method} requires ${provider} \u2014 ${hint}`, {
       operation: method,
@@ -113,6 +155,10 @@ var ProviderNotConfiguredError = class extends ConfigurationError {
   }
 };
 var GraphCheckpointNotSupportedError = class extends WolbargError {
+  /**
+   * @param backend - Graph backend name (e.g. `"neo4j"`).
+   * @param operation - Requested operation (e.g. `"checkpoint"`).
+   */
   constructor(backend, operation) {
     super(
       `graph checkpoint not supported for network-backed graph providers (${backend})`,
@@ -185,9 +231,11 @@ Rules:
 var LlmCompressionProvider = class {
   name = "llm";
   llm;
+  /** @param llm - Configured LLM used for summarization. */
   constructor(llm) {
     this.llm = llm;
   }
+  /** @inheritdoc */
   async compress(memories) {
     return compressMemories(this.llm, memories);
   }
@@ -296,6 +344,7 @@ function slidingWindow(text, chunkSize, overlap) {
 }
 var FixedChunkingStrategy = class {
   name = "fixed";
+  /** @inheritdoc */
   chunk(text, options) {
     const { chunkSize, overlap } = clampOptions(options);
     return slidingWindow(text, chunkSize, overlap);
@@ -303,6 +352,7 @@ var FixedChunkingStrategy = class {
 };
 var SentenceChunkingStrategy = class {
   name = "sentence";
+  /** @inheritdoc */
   chunk(text, options) {
     const { chunkSize, overlap } = clampOptions(options);
     const sentences = text.split(/(?<=[.!?])\s+/).map((s) => s.trim()).filter(Boolean);
@@ -311,6 +361,7 @@ var SentenceChunkingStrategy = class {
 };
 var ParagraphChunkingStrategy = class {
   name = "paragraph";
+  /** @inheritdoc */
   chunk(text, options) {
     const { chunkSize, overlap } = clampOptions(options);
     const paragraphs = text.split(/\n\s*\n/).map((p) => p.trim()).filter(Boolean);
@@ -319,6 +370,7 @@ var ParagraphChunkingStrategy = class {
 };
 var MarkdownChunkingStrategy = class {
   name = "markdown";
+  /** @inheritdoc */
   chunk(text, options) {
     const { chunkSize, overlap } = clampOptions(options);
     const sections = text.split(/(?=^#{1,6}\s)/m).map((s) => s.trim()).filter(Boolean);
@@ -330,6 +382,7 @@ var MarkdownChunkingStrategy = class {
 };
 var HeadingChunkingStrategy = class {
   name = "heading";
+  /** @inheritdoc */
   chunk(text, options) {
     return new MarkdownChunkingStrategy().chunk(text, options);
   }
@@ -411,6 +464,12 @@ function distanceToSimilarity(distance) {
 }
 var AsyncMutex = class {
   chain = Promise.resolve();
+  /**
+   * Run `fn` exclusively — concurrent callers queue on the same mutex.
+   *
+   * @param fn - Async or sync work to serialize.
+   * @returns The value returned by `fn`.
+   */
   async runExclusive(fn) {
     let release;
     const next = new Promise((resolve) => {
@@ -434,16 +493,32 @@ function joinUrl(baseUrl, path8) {
 
 // src/embedding/index.ts
 var OpenAICompatibleEmbeddingProvider = class {
+  /** Model name sent in the request body. */
   model;
   baseUrl;
   apiKey;
   timeoutMs;
+  /**
+   * @param config - OpenAI-compatible embedding endpoint settings.
+   * @param config.baseUrl - API root, e.g. `https://api.openai.com/v1`.
+   * @param config.apiKey - Bearer token. Use any non-empty string for local
+   *   servers that ignore auth.
+   * @param config.model - Embedding model id (e.g. `"text-embedding-3-small"`).
+   * @param config.timeoutMs - Abort after this many ms. Defaults to `30_000`.
+   */
   constructor(config) {
     this.baseUrl = config.baseUrl;
     this.apiKey = config.apiKey;
     this.model = config.model;
     this.timeoutMs = config.timeoutMs ?? 3e4;
   }
+  /**
+   * Embed a single string.
+   *
+   * @param text - Input text.
+   * @returns Embedding vector.
+   * @throws {EmbeddingError} On HTTP errors, timeouts, or empty vectors.
+   */
   async embed(text) {
     const response = await this.request(text);
     const vector = response.data?.[0]?.embedding;
@@ -452,6 +527,13 @@ var OpenAICompatibleEmbeddingProvider = class {
     }
     return Float32Array.from(vector);
   }
+  /**
+   * Embed multiple strings in one API call when the server supports batch input.
+   * Falls back to sequential {@link embed} if the response length mismatches.
+   *
+   * @param texts - Inputs to embed.
+   * @returns One vector per input, same order.
+   */
   async embedBatch(texts) {
     if (texts.length === 0) {
       return [];
@@ -478,6 +560,12 @@ var OpenAICompatibleEmbeddingProvider = class {
       return Float32Array.from(item.embedding);
     });
   }
+  /**
+   * Probe the endpoint and report vector dimensionality.
+   *
+   * @returns `{ dimensions }` from a fixed health-check string.
+   * @throws {EmbeddingError} When the probe fails.
+   */
   async validate() {
     try {
       const embedding = await this.embed("Wolbarg health check");
@@ -492,6 +580,12 @@ var OpenAICompatibleEmbeddingProvider = class {
       );
     }
   }
+  /**
+   * Low-level HTTP request to `/embeddings`.
+   *
+   * @param input - Single string or batch of strings.
+   * @returns Parsed OpenAI-style JSON body.
+   */
   async request(input) {
     const url = joinUrl(this.baseUrl, "/embeddings");
     const controller = new AbortController();
@@ -539,6 +633,7 @@ var OpenAICompatibleEmbeddingProvider = class {
       clearTimeout(timer);
     }
   }
+  /** @param error - Unknown thrown value. @returns Human-readable message. */
   describe(error) {
     if (error instanceof Error) {
       return error.message;
@@ -689,6 +784,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;
@@ -756,6 +890,10 @@ var SqliteEmbeddingCacheStore = class {
   pendingSets = /* @__PURE__ */ new Map();
   persistScheduled = false;
   stmts = null;
+  /**
+   * @param dbOrGetter - SQLite `DatabaseSync` or lazy getter (allows late bind).
+   * @param options.ttlMs - Optional TTL for cache entries on read.
+   */
   constructor(dbOrGetter, options) {
     this.ttlMs = options?.ttlMs ?? null;
     this.getDb = typeof dbOrGetter === "function" ? dbOrGetter : () => dbOrGetter;
@@ -773,7 +911,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 +948,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 +1022,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 +1066,10 @@ var SqliteEmbeddingCacheStore = class {
           db.exec("ROLLBACK");
         } catch {
         }
-        this.stmts = null;
+        requeue();
       }
     } catch {
-      this.stmts = null;
+      requeue();
     }
   }
 };
@@ -998,12 +1170,23 @@ var PostgresEmbeddingCacheStore = class {
 
 // src/llm/index.ts
 var OpenAICompatibleLlmProvider = class {
+  /** Model name sent in the request body and exposed on the provider. */
   model;
   baseUrl;
   apiKey;
   temperature;
   maxTokens;
   timeoutMs;
+  /**
+   * @param config - OpenAI-compatible endpoint settings.
+   * @param config.baseUrl - API root, e.g. `https://api.openai.com/v1` (no trailing `/chat/completions`).
+   * @param config.apiKey - Bearer token (`Authorization: Bearer …`). Use any non-empty
+   *   string for local servers that ignore auth (e.g. `"ollama"`).
+   * @param config.model - Chat model id (e.g. `"gpt-4o-mini"`, `"llama3.2"`).
+   * @param config.temperature - Sampling temperature. Defaults to `0.2`.
+   * @param config.maxTokens - Max completion tokens. Defaults to `4096`.
+   * @param config.timeoutMs - Abort after this many ms. Defaults to `60_000`.
+   */
   constructor(config) {
     this.baseUrl = config.baseUrl;
     this.apiKey = config.apiKey;
@@ -1012,6 +1195,13 @@ var OpenAICompatibleLlmProvider = class {
     this.maxTokens = config.maxTokens ?? 4096;
     this.timeoutMs = config.timeoutMs ?? 6e4;
   }
+  /**
+   * Call `/chat/completions` and return the first choice’s message content.
+   *
+   * @param messages - Chat turns in OpenAI message format.
+   * @returns Trimmed assistant text.
+   * @throws {CompressionError} On HTTP errors, timeouts, or empty content.
+   */
   async complete(messages) {
     const response = await this.request(messages);
     const content = response.choices?.[0]?.message?.content;
@@ -1020,6 +1210,11 @@ var OpenAICompatibleLlmProvider = class {
     }
     return content.trim();
   }
+  /**
+   * Probe the endpoint with a fixed `"ok"` prompt.
+   *
+   * @throws {CompressionError} When validation fails.
+   */
   async validate() {
     try {
       await this.complete([
@@ -1041,6 +1236,12 @@ var OpenAICompatibleLlmProvider = class {
       );
     }
   }
+  /**
+   * Low-level HTTP request to `/chat/completions`.
+   *
+   * @param messages - Chat turns to send.
+   * @returns Parsed OpenAI-style JSON body.
+   */
   async request(messages) {
     const url = joinUrl(this.baseUrl, "/chat/completions");
     const controller = new AbortController();
@@ -1089,6 +1290,7 @@ var OpenAICompatibleLlmProvider = class {
       clearTimeout(timer);
     }
   }
+  /** @param error - Unknown thrown value. @returns Human-readable message. */
   describe(error) {
     if (error instanceof Error) {
       return error.message;
@@ -1206,12 +1408,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 +1436,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 +1590,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 +1676,79 @@ 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 {
+  /** @param level - Minimum level to print (default `"info"`). */
+  constructor(level = "info") {
+    this.level = level;
+  }
+  level;
+  /** Change the minimum log level at runtime. */
+  setLevel(level) {
+    this.level = level;
+  }
+  /** @returns Current minimum log level. */
+  getLevel() {
+    return this.level;
+  }
+  /** Log at error level. */
+  error(message, extra) {
+    this.write("error", message, extra);
+  }
+  /** Log at warn level.
+   * @param message - Primary log line.
+   * @param extra - Optional structured payload.
+   */
+  warn(message, extra) {
+    this.write("warn", message, extra);
+  }
+  /** Log at info level.
+   * @param message - Primary log line.
+   * @param extra - Optional structured payload.
+   */
+  info(message, extra) {
+    this.write("info", message, extra);
+  }
+  /** Log at debug level.
+   * @param message - Primary log line.
+   * @param extra - Optional structured payload.
+   */
+  debug(message, extra) {
+    this.write("debug", message, extra);
+  }
+  /** Log at trace level.
+   * @param message - Primary log line.
+   * @param extra - Optional structured payload.
+   */
+  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 = {
@@ -1762,40 +2063,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;
@@ -1803,18 +2070,29 @@ var InMemoryVectorIndex = class {
   data;
   count = 0;
   rowidToSlot = /* @__PURE__ */ new Map();
+  /**
+   * @param dimensions - Embedding vector length.
+   * @param initialCapacity - Initial slot capacity (default `256`).
+   */
   constructor(dimensions, initialCapacity = 256) {
     this.dims = dimensions;
     this.data = new Float32Array(initialCapacity * dimensions);
   }
+  /** Number of indexed vectors. */
   get size() {
     return this.count;
   }
+  /** Remove all vectors from the index. */
   clear() {
     this.rowids.length = 0;
     this.rowidToSlot.clear();
     this.count = 0;
   }
+  /**
+   * Insert or replace a vector for `rowid` (L2-normalized internally).
+   * @param rowid - Memory table row identifier.
+   * @param embedding - Raw embedding vector.
+   */
   upsert(rowid, embedding) {
     const existing = this.rowidToSlot.get(rowid);
     const slot = existing !== void 0 ? existing : (() => {
@@ -1845,6 +2123,10 @@ var InMemoryVectorIndex = class {
       }
     }
   }
+  /**
+   * Remove a vector by `rowid`.
+   * @param rowid - Memory table row identifier.
+   */
   remove(rowid) {
     const slot = this.rowidToSlot.get(rowid);
     if (slot === void 0) {
@@ -1864,7 +2146,12 @@ var InMemoryVectorIndex = class {
     this.rowidToSlot.delete(rowid);
     this.count = last;
   }
-  /** Top-k by cosine distance (1 - dot) assuming query is L2-normalized. */
+  /**
+   * Top-k by cosine distance (1 - dot) assuming query is L2-normalized.
+   *
+   * @param queryNormalized - L2-normalized query vector (use {@link normalizeEmbedding}).
+   * @param topK - Maximum hits to return.
+   */
   search(queryNormalized, topK) {
     const n = this.count;
     if (n === 0 || topK <= 0) {
@@ -1888,24 +2175,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 +2247,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 +2390,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 +2402,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;
@@ -2124,6 +2427,9 @@ var SqliteStorageProvider = class _SqliteStorageProvider {
   /** Coalesce concurrent insertMemory callers into one IMMEDIATE transaction. */
   insertQueue = [];
   insertFlushScheduled = false;
+  /**
+   * @param options - SQLite path / `:memory:` and optional concurrency config.
+   */
   constructor(options) {
     this.connectionString = options.connectionString;
     this.concurrency = resolveConcurrencyConfig(options.concurrency);
@@ -2136,9 +2442,11 @@ var SqliteStorageProvider = class _SqliteStorageProvider {
   getDatabase() {
     return this.db;
   }
+  /** Register a callback invoked when SQLite busy retries occur (tests / diagnostics). */
   setRetryLogger(fn) {
     this.retryLog = fn;
   }
+  /** Open the database, run migrations, and prepare statements. */
   async open() {
     try {
       const dbPath = this.resolvePath(this.connectionString);
@@ -2169,6 +2477,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) {
@@ -2192,6 +2506,7 @@ var SqliteStorageProvider = class _SqliteStorageProvider {
       );
     }
   }
+  /** Drain pending inserts, optimize, and close the SQLite connection. */
   async close() {
     const deadline = Date.now() + 2e3;
     while (this.insertQueue.length > 0 && Date.now() < deadline) {
@@ -2222,6 +2537,11 @@ var SqliteStorageProvider = class _SqliteStorageProvider {
       this.batchBlobEmbStatements.clear();
     }
   }
+  /**
+   * Create or validate vec0 / blob vector storage for the given dimensionality.
+   *
+   * @param dimensions - Embedding length from the configured model.
+   */
   async ensureVectorSchema(dimensions) {
     const existing = await this.getEmbeddingDimensions();
     if (existing !== null && existing !== dimensions) {
@@ -2244,13 +2564,16 @@ var SqliteStorageProvider = class _SqliteStorageProvider {
     this.reprepareVectorStatements();
     this.hydrateMemoryIndex();
   }
+  /** @inheritdoc StorageProvider.getEmbeddingDimensions */
   async getEmbeddingDimensions() {
     return this.readMetaNumber(META_KEYS.embeddingDimensions);
   }
+  /** @inheritdoc StorageProvider.setEmbeddingDimensions */
   async setEmbeddingDimensions(dimensions) {
     await this.setMeta(META_KEYS.embeddingDimensions, String(dimensions));
     this.vectorDimensions = dimensions;
   }
+  /** Insert a single memory row (coalesced under concurrent writers). */
   async insertMemory(input) {
     this.requireVectorReady();
     return new Promise((resolve, reject) => {
@@ -2332,6 +2655,7 @@ var SqliteStorageProvider = class _SqliteStorageProvider {
       return row;
     });
   }
+  /** Batch insert memories in chunked multi-row transactions. */
   async insertMemoriesBatch(inputs) {
     if (inputs.length === 0) {
       return [];
@@ -2347,6 +2671,7 @@ var SqliteStorageProvider = class _SqliteStorageProvider {
       return rows;
     });
   }
+  /** Update memory content, metadata, embedding, and content hash. */
   async updateMemory(input) {
     const stmts = this.requireStatements();
     return this.withTransaction(() => {
@@ -2390,6 +2715,7 @@ var SqliteStorageProvider = class _SqliteStorageProvider {
       return stmts.getMemoryById.get(input.id, input.organization);
     });
   }
+  /** Find an active memory by org, agent, and content hash (dedupe). */
   async findActiveByContentHash(organization, agent, contentHash) {
     const stmts = this.requireStatements();
     const row = stmts.findActiveByContentHash.get(
@@ -2399,6 +2725,7 @@ var SqliteStorageProvider = class _SqliteStorageProvider {
     );
     return row ?? null;
   }
+  /** Scan memories matching metadata filters (may paginate in SQL). */
   async searchByMetadata(filter, limit) {
     const rows = await this.listMemories(filter, limit);
     if (!filter.metadata) {
@@ -2409,9 +2736,16 @@ var SqliteStorageProvider = class _SqliteStorageProvider {
     );
   }
   /** Keyword search via FTS5 BM25. Returns memory IDs ranked by relevance. */
+  /** BM25 keyword search via FTS5 (`memories_fts`). */
   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,20 +2759,32 @@ 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 [];
     }
   }
+  /** Fetch a memory row by UUID within an organization. */
   async getMemoryById(id, organization) {
     const stmts = this.requireStatements();
     const row = stmts.getMemoryById.get(id, organization);
     return row ?? null;
   }
+  /** Fetch a memory row by SQLite integer rowid within an organization. */
   async getMemoryByRowid(rowid, organization) {
     const stmts = this.requireStatements();
     const row = stmts.getMemoryByRowid.get(rowid, organization);
     return row ?? null;
   }
+  /** Batch-fetch memory rows by SQLite rowids within an organization. */
   async getMemoriesByRowids(rowids, organization) {
     const out = /* @__PURE__ */ new Map();
     if (rowids.length === 0) {
@@ -2457,6 +2803,7 @@ var SqliteStorageProvider = class _SqliteStorageProvider {
     }
     return out;
   }
+  /** List memories matching repository filters with optional limit. */
   async listMemories(filter, limit) {
     try {
       if (filter.metadata) {
@@ -2469,6 +2816,7 @@ var SqliteStorageProvider = class _SqliteStorageProvider {
       });
     }
   }
+  /** Approximate nearest-neighbor search (vec0 or in-memory blob index). */
   async searchVectors(embedding, topK) {
     this.requireVectorReady();
     if (this.vectorBackend === "sqlite-vec") {
@@ -2480,6 +2828,7 @@ var SqliteStorageProvider = class _SqliteStorageProvider {
    * Org-scoped KNN + memory rows with adaptive overfetch.
    * Global ANN is post-filtered by org/agent/archived; underfill triggers larger k.
    */
+  /** ANN search joined with memory rows and org/archived post-filters. */
   async searchVectorsWithMemories(embedding, topK, organization, options) {
     this.requireVectorReady();
     if (topK <= 0) {
@@ -2518,6 +2867,7 @@ var SqliteStorageProvider = class _SqliteStorageProvider {
     }
     return out;
   }
+  /** Soft-archive memories (compression / forget paths). */
   async archiveMemories(ids, organization, compressedIntoId, archivedAt) {
     const stmts = this.requireStatements();
     const archived = [];
@@ -2555,6 +2905,7 @@ var SqliteStorageProvider = class _SqliteStorageProvider {
       return archived;
     });
   }
+  /** Hard-delete a single memory by id; returns whether a row was removed. */
   async deleteMemoryById(id, organization) {
     const stmts = this.requireStatements();
     return this.withTransaction(() => {
@@ -2568,6 +2919,7 @@ var SqliteStorageProvider = class _SqliteStorageProvider {
       return Number(result.changes) > 0;
     });
   }
+  /** Hard-delete memories matching org / agent / metadata filters. */
   async deleteMemoriesByFilter(filter) {
     const stmts = this.requireStatements();
     const agent = filter.agent;
@@ -2584,6 +2936,7 @@ var SqliteStorageProvider = class _SqliteStorageProvider {
       return Number(result.changes);
     });
   }
+  /** Remove all memories (and side tables) for an organization. */
   async clearOrganization(organization) {
     const stmts = this.requireStatements();
     return this.withTransaction(() => {
@@ -2600,10 +2953,12 @@ var SqliteStorageProvider = class _SqliteStorageProvider {
       return Number(result.changes);
     });
   }
+  /** List audit history events for a memory id. */
   async getHistory(memoryId) {
     const stmts = this.requireStatements();
     return stmts.getHistory.all(memoryId);
   }
+  /** Append a history row (created / archived / compressed / updated). */
   async insertHistoryEvent(event) {
     const stmts = this.requireStatements();
     stmts.insertHistory.run(
@@ -2614,6 +2969,7 @@ var SqliteStorageProvider = class _SqliteStorageProvider {
       event.created_at
     );
   }
+  /** Aggregate memory counts for an organization (single-pass SQL). */
   async getStats(organization) {
     const stmts = this.requireStatements();
     const row = stmts.getStats.get(organization);
@@ -2624,6 +2980,7 @@ var SqliteStorageProvider = class _SqliteStorageProvider {
       totalAgents: Number(row.agents)
     };
   }
+  /** On-disk database file size in bytes (0 for `:memory:`). */
   async getDatabaseSizeBytes() {
     const db = this.requireDb();
     if (this.connectionString === ":memory:") {
@@ -2656,21 +3013,44 @@ 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;
       }
-    );
-  }
-  // ─── internals ───────────────────────────────────────────────────────────
-  tryLoadSqliteVec(db) {
-    const plat = `${process.platform}-${process.arch}`;
-    if (_SqliteStorageProvider.sqliteVecUnsupported.has(plat)) {
+    }
+    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) {
+    const plat = `${process.platform}-${process.arch}`;
+    if (_SqliteStorageProvider.sqliteVecUnsupported.has(plat)) {
       return false;
     }
     try {
@@ -3659,11 +4039,17 @@ var PostgresSubscribeListener = class {
   reconnectDelayMs;
   connect;
   onError;
+  /**
+   * @param options.connect - Factory returning a dedicated LISTEN client.
+   * @param options.reconnectDelayMs - Delay before reconnect attempts (default 1000).
+   * @param options.onError - Optional error hook for connection failures.
+   */
   constructor(options) {
     this.connect = options.connect;
     this.reconnectDelayMs = options.reconnectDelayMs ?? 1e3;
     this.onError = options.onError;
   }
+  /** Open the LISTEN connection (lazy — also started on first subscribe). */
   async start() {
     if (this.closed) {
       return;
@@ -3760,6 +4146,13 @@ var PostgresSubscribeListener = class {
       }
     }
   }
+  /**
+   * Register a filtered callback for memory change events.
+   *
+   * @param filter - Organization / agent / event-type filter.
+   * @param callback - Invoked synchronously on each matching NOTIFY.
+   * @returns Unsubscribe function.
+   */
   subscribe(filter, callback) {
     if (this.closed) {
       throw new Error("Subscribe backend is closed");
@@ -3781,6 +4174,7 @@ var PostgresSubscribeListener = class {
    */
   emit(_event) {
   }
+  /** Tear down LISTEN connection and clear subscriptions. */
   async close() {
     this.closed = true;
     this.subscriptions.clear();
@@ -3819,9 +4213,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);
@@ -3892,13 +4290,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 (
@@ -3914,7 +4312,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;
@@ -3941,6 +4339,9 @@ var PostgresStorageProvider = class _PostgresStorageProvider {
   insertFlushScheduled = false;
   insertFlushTimer = null;
   insertFlushInFlight = 0;
+  /**
+   * @param options - Connection string, pool size, and durability flags.
+   */
   constructor(options) {
     this.maxPoolSize = options.maxPoolSize ?? 64;
     this.durableWrites = options.durableWrites !== false;
@@ -3949,6 +4350,7 @@ var PostgresStorageProvider = class _PostgresStorageProvider {
       this.durableWrites
     );
   }
+  /** Current pg pool occupancy stats (for diagnostics / subscribe setup). */
   getPoolStats() {
     const pool = this.pool;
     return {
@@ -3962,6 +4364,7 @@ var PostgresStorageProvider = class _PostgresStorageProvider {
   getPool() {
     return this.pool;
   }
+  /** Open the connection pool and run migrations. */
   async open() {
     let PoolCtor;
     try {
@@ -4010,6 +4413,7 @@ var PostgresStorageProvider = class _PostgresStorageProvider {
       );
     }
   }
+  /** Drain coalesced inserts and end the connection pool. */
   async close() {
     if (this.insertFlushTimer) {
       clearTimeout(this.insertFlushTimer);
@@ -4050,6 +4454,11 @@ var PostgresStorageProvider = class _PostgresStorageProvider {
   async ensureVectorIndex() {
     await this.ensureHnswIndex();
   }
+  /**
+   * Create pgvector tables and HNSW index for the given dimensionality.
+   *
+   * @param dimensions - Embedding length from the configured model.
+   */
   async ensureVectorSchema(dimensions) {
     const existing = await this.getEmbeddingDimensions();
     if (existing !== null && existing !== dimensions) {
@@ -4114,6 +4523,11 @@ var PostgresStorageProvider = class _PostgresStorageProvider {
     }
   }
   /** Cross-process subscribe: NOTIFY after a committed write. */
+  /**
+   * Issue `pg_notify` for cross-process {@link subscribe} delivery.
+   *
+   * @param event - Memory change payload (IDs + metadata only).
+   */
   async notifyChange(event) {
     await notifyMemoryChange(this.requirePool(), event);
   }
@@ -4121,6 +4535,7 @@ var PostgresStorageProvider = class _PostgresStorageProvider {
    * Soft reset for a single organization. Drops HNSW only when the embeddings
    * table is empty so other corpora on a shared bench DB stay intact.
    */
+  /** Delete all rows for an organization (dev / test helper). */
   async resetOrganization(organization) {
     await this.query(`DELETE FROM memories WHERE organization = $1`, [
       organization
@@ -4138,6 +4553,7 @@ var PostgresStorageProvider = class _PostgresStorageProvider {
   /**
    * Wipe all Wolbarg tables (explicit opt-in). Prefer {@link resetOrganization}.
    */
+  /** Truncate all Wolbarg tables (dev / test helper). */
   async wipeAllData() {
     await this.query(`TRUNCATE TABLE memories CASCADE`).catch(() => void 0);
     await this.query(
@@ -4183,6 +4599,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)}`,
@@ -4191,6 +4613,7 @@ var PostgresStorageProvider = class _PostgresStorageProvider {
       }
     }
   }
+  /** @inheritdoc StorageProvider.getEmbeddingDimensions */
   async getEmbeddingDimensions() {
     const result = await this.query(
       `SELECT value FROM Wolbarg_meta WHERE key = $1`,
@@ -4203,6 +4626,7 @@ var PostgresStorageProvider = class _PostgresStorageProvider {
     const parsed = Number(value);
     return Number.isFinite(parsed) ? parsed : null;
   }
+  /** @inheritdoc StorageProvider.setEmbeddingDimensions */
   async setEmbeddingDimensions(dimensions) {
     await this.query(
       `INSERT INTO Wolbarg_meta (key, value) VALUES ($1, $2)
@@ -4211,6 +4635,7 @@ var PostgresStorageProvider = class _PostgresStorageProvider {
     );
     this.vectorDimensions = dimensions;
   }
+  /** Insert a single memory row (coalesced under concurrent writers). */
   async insertMemory(input) {
     this.requireVectorReady();
     return new Promise((resolve, reject) => {
@@ -4297,6 +4722,7 @@ var PostgresStorageProvider = class _PostgresStorageProvider {
     }
     return this.insertOneBlob(input);
   }
+  /** Batch insert via unnest / COPY paths with optional HNSW deferral. */
   async insertMemoriesBatch(inputs) {
     if (inputs.length === 0) {
       return [];
@@ -4327,6 +4753,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];
@@ -4337,6 +4764,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, [
@@ -4347,9 +4775,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],
@@ -4357,7 +4786,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]
     }));
@@ -4398,81 +4827,87 @@ 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;
+    });
   }
+  /** Update memory content, metadata, embedding, and content hash. */
   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);
+    });
   }
+  /** Find an active memory by org, agent, and content hash (dedupe). */
   async findActiveByContentHash(organization, agent, contentHash) {
     const result = await this.query(
       `SELECT id, organization, agent, content_text, metadata_json,
@@ -4485,6 +4920,7 @@ var PostgresStorageProvider = class _PostgresStorageProvider {
     const row = result.rows[0];
     return row ? this.mapRow(row) : null;
   }
+  /** Fetch a memory row by UUID within an organization. */
   async getMemoryById(id, organization) {
     const result = await this.query(
       `SELECT id, organization, agent, content_text, metadata_json,
@@ -4495,6 +4931,7 @@ var PostgresStorageProvider = class _PostgresStorageProvider {
     const row = result.rows[0];
     return row ? this.mapRow(row) : null;
   }
+  /** Fetch a memory row by internal rowid within an organization. */
   async getMemoryByRowid(rowid, organization) {
     const result = await this.query(
       `SELECT m.id, m.organization, m.agent, m.content_text, m.metadata_json,
@@ -4508,6 +4945,7 @@ var PostgresStorageProvider = class _PostgresStorageProvider {
     const row = result.rows[0];
     return row ? this.mapRow(row) : null;
   }
+  /** Batch-fetch memory rows by rowids within an organization. */
   async getMemoriesByRowids(rowids, organization) {
     const out = /* @__PURE__ */ new Map();
     if (rowids.length === 0) {
@@ -4530,6 +4968,7 @@ var PostgresStorageProvider = class _PostgresStorageProvider {
     }
     return out;
   }
+  /** List memories matching repository filters with optional limit. */
   async listMemories(filter, limit) {
     const want = limit !== void 0 ? limit : filter.metadata ? 1e4 : void 0;
     const compiled = filter.metadata ? compileMetadataFilterToPostgres(filter.metadata, 2) : null;
@@ -4591,9 +5030,11 @@ var PostgresStorageProvider = class _PostgresStorageProvider {
     }
     return rows;
   }
+  /** Scan memories matching metadata filters. */
   async searchByMetadata(filter, limit) {
     return this.listMemories(filter, limit);
   }
+  /** Full-text keyword search via `tsvector` / GIN index. */
   async searchKeyword(query, organization, topK) {
     const trimmed = query.trim();
     if (!trimmed || topK <= 0) {
@@ -4620,10 +5061,20 @@ 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 [];
     }
   }
+  /** pgvector cosine ANN search (HNSW when index is present). */
   async searchVectors(embedding, topK) {
     this.requireVectorReady();
     if (this.hasPgvector) {
@@ -4673,6 +5124,7 @@ var PostgresStorageProvider = class _PostgresStorageProvider {
     scored.sort((a, b) => a.distance - b.distance);
     return scored.slice(0, topK);
   }
+  /** ANN search joined with memory rows and org/archived post-filters. */
   async searchVectorsWithMemories(embedding, topK, organization, options) {
     this.requireVectorReady();
     if (!this.hasPgvector) {
@@ -4737,46 +5189,50 @@ var PostgresStorageProvider = class _PostgresStorageProvider {
     );
     return mapHits(result.rows);
   }
+  /** Soft-archive memories (compression / forget paths). */
   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;
+    });
   }
+  /** Hard-delete a single memory by id; returns whether a row was removed. */
   async deleteMemoryById(id, organization) {
     const result = await this.query(
       `DELETE FROM memories WHERE id = $1 AND organization = $2`,
@@ -4784,6 +5240,7 @@ var PostgresStorageProvider = class _PostgresStorageProvider {
     );
     return (result.rowCount ?? 0) > 0;
   }
+  /** Hard-delete memories matching org / agent / metadata filters. */
   async deleteMemoriesByFilter(filter) {
     if (!filter.agent) {
       throw new DatabaseError("deleteMemoriesByFilter requires an agent filter");
@@ -4794,6 +5251,7 @@ var PostgresStorageProvider = class _PostgresStorageProvider {
     );
     return result.rowCount ?? 0;
   }
+  /** Remove all memories for an organization. */
   async clearOrganization(organization) {
     const result = await this.query(
       `DELETE FROM memories WHERE organization = $1`,
@@ -4801,6 +5259,7 @@ var PostgresStorageProvider = class _PostgresStorageProvider {
     );
     return result.rowCount ?? 0;
   }
+  /** List audit history events for a memory id. */
   async getHistory(memoryId) {
     const result = await this.query(
       `SELECT id, memory_id, event_type, related_memory_id, created_at
@@ -4815,6 +5274,7 @@ var PostgresStorageProvider = class _PostgresStorageProvider {
       created_at: String(row.created_at)
     }));
   }
+  /** Append a history row (created / archived / compressed / updated). */
   async insertHistoryEvent(event) {
     await this.query(
       `INSERT INTO memory_history (id, memory_id, event_type, related_memory_id, created_at)
@@ -4828,6 +5288,7 @@ var PostgresStorageProvider = class _PostgresStorageProvider {
       ]
     );
   }
+  /** Aggregate memory counts for an organization. */
   async getStats(organization) {
     const result = await this.query(
       `SELECT
@@ -4845,6 +5306,7 @@ var PostgresStorageProvider = class _PostgresStorageProvider {
       totalAgents: Number(result.rows[0]?.agents ?? 0)
     };
   }
+  /** Approximate on-disk database size in bytes (`pg_database_size`). */
   async getDatabaseSizeBytes() {
     const result = await this.query(
       `SELECT pg_database_size(current_database())::bigint AS size`
@@ -4886,6 +5348,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
@@ -5036,8 +5503,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;
     }
   }
@@ -5178,11 +5654,12 @@ function createDatabaseProvider(config) {
 }
 
 // src/version.ts
-var SDK_VERSION = "0.5.3";
+var SDK_VERSION = "0.5.5";
 
 // 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(
@@ -5209,7 +5686,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 {
@@ -5218,7 +5697,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)) {
@@ -5240,26 +5719,57 @@ Pass the path returned by export().`
         );
       }
     } else {
-      manifest = {
-        format: "wolbarg-export-v1",
-        exportedAt: nowIso(),
-        sdkVersion: SDK_VERSION,
-        provider: "sqlite",
-        sourcePath: dbExportPath
-      };
+      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}).`
+        );
+      }
     }
     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) {
@@ -5488,7 +5998,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;
       }
@@ -5612,6 +6123,9 @@ var SqliteGraphProvider = class {
   concurrency;
   db = null;
   opened = false;
+  /**
+   * @param options - Graph SQLite path and optional concurrency tuning.
+   */
   constructor(options) {
     if (!options?.path || typeof options.path !== "string" || !options.path.trim()) {
       throw new ConfigurationError("sqlite graph requires a non-empty path");
@@ -5619,12 +6133,15 @@ var SqliteGraphProvider = class {
     this.dbPath = path7__default.default.resolve(options.path.trim());
     this.concurrency = resolveConcurrencyConfig(options.concurrency);
   }
+  /** Whether this provider supports file snapshots for checkpoint / export. */
   supportsFileSnapshot() {
     return this.dbPath !== ":memory:";
   }
+  /** Absolute graph database path, or `null` for `:memory:`. */
   getDataPath() {
     return this.dbPath === ":memory:" ? null : this.dbPath;
   }
+  /** Open the graph SQLite file, apply pragmas, and create schema if needed. */
   async open() {
     if (this.opened) return;
     try {
@@ -5661,6 +6178,7 @@ var SqliteGraphProvider = class {
       );
     }
   }
+  /** Close the graph database connection. */
   async close() {
     if (!this.db) {
       this.opened = false;
@@ -5682,6 +6200,14 @@ var SqliteGraphProvider = class {
       this.opened = false;
     }
   }
+  /**
+   * Create or replace a directed memory↔memory edge.
+   *
+   * @param fromId - Source memory UUID.
+   * @param toId - Target memory UUID.
+   * @param relation - Edge label (e.g. `"related_to"`, `"caused_by"`).
+   * @param metadata - Optional JSON metadata stored on the edge.
+   */
   async linkMemories(fromId, toId, relation, metadata) {
     const db = this.requireDb();
     await this.withTx(() => {
@@ -5704,6 +6230,13 @@ var SqliteGraphProvider = class {
       );
     });
   }
+  /**
+   * Remove edges between two memories.
+   *
+   * @param fromId - Source memory UUID.
+   * @param toId - Target memory UUID.
+   * @param relation - When set, only delete edges with this relation label.
+   */
   async unlinkMemories(fromId, toId, relation) {
     const db = this.requireDb();
     await this.withTx(() => {
@@ -5753,6 +6286,12 @@ var SqliteGraphProvider = class {
     }
     return out;
   }
+  /**
+   * Insert or update a named entity node.
+   *
+   * @param entity - Entity name, type, and optional metadata.
+   * @returns Stable entity id ({@link entityIdFrom}).
+   */
   async upsertEntity(entity) {
     const id = entityIdFrom(entity.name, entity.type);
     const db = this.requireDb();
@@ -5777,6 +6316,13 @@ var SqliteGraphProvider = class {
     });
     return id;
   }
+  /**
+   * Link an entity to a memory via a `MENTIONS` edge (not traversed by {@link getRelated}).
+   *
+   * @param entityId - Entity id from {@link upsertEntity}.
+   * @param memoryId - Target memory UUID.
+   * @param role - Optional role string stored on the edge metadata.
+   */
   async linkEntityToMemory(entityId, memoryId, role) {
     const db = this.requireDb();
     await this.withTx(() => {
@@ -5806,6 +6352,11 @@ var SqliteGraphProvider = class {
       );
     });
   }
+  /**
+   * Remove the memory node and incident edges when a memory is hard-deleted.
+   *
+   * @param memoryId - Wolbarg memory UUID.
+   */
   async deleteMemory(memoryId) {
     const db = this.requireDb();
     await this.withTx(() => {
@@ -5825,6 +6376,7 @@ var SqliteGraphProvider = class {
       }
     );
   }
+  /** Lightweight connectivity and schema statistics check. */
   async health() {
     try {
       if (!this.opened || !this.db) {
@@ -5970,6 +6522,9 @@ var Neo4jGraphProvider = class {
   database;
   driver = null;
   opened = false;
+  /**
+   * @param options - Bolt URL, credentials, and optional database name.
+   */
   constructor(options) {
     if (!options?.url?.trim()) {
       throw new ConfigurationError("neo4j graph requires a non-empty url");
@@ -5985,12 +6540,15 @@ var Neo4jGraphProvider = class {
     this.password = options.password;
     this.database = options.database?.trim() || void 0;
   }
+  /** Neo4j does not support local file snapshots for checkpoint pairing. */
   supportsFileSnapshot() {
     return false;
   }
+  /** Always `null` — graph data lives in the remote Neo4j cluster. */
   getDataPath() {
     return null;
   }
+  /** Connect to Neo4j, verify connectivity, and ensure uniqueness constraints. */
   async open() {
     if (this.opened) return;
     let mod;
@@ -6022,6 +6580,7 @@ var Neo4jGraphProvider = class {
       }
     });
   }
+  /** Close the neo4j-driver connection. */
   async close() {
     if (this.driver) {
       await this.driver.close();
@@ -6048,24 +6607,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 = '',
@@ -6074,25 +6635,46 @@ 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 });
   }
+  /**
+   * MERGE a directed `RELATED` relationship between two memory nodes.
+   *
+   * @param fromId - Source memory UUID.
+   * @param toId - Target memory UUID.
+   * @param relation - Relationship label stored on `RELATED.relation`.
+   * @param metadata - Optional JSON metadata on the relationship.
+   */
   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)
+        }
+      );
+    });
   }
+  /**
+   * Delete `RELATED` relationship(s) between two memories.
+   *
+   * @param fromId - Source memory UUID.
+   * @param toId - Target memory UUID.
+   * @param relation - When set, only delete edges with this relation property.
+   */
   async unlinkMemories(fromId, toId, relation) {
     if (relation !== void 0) {
       await this.run(
@@ -6138,6 +6720,12 @@ var Neo4jGraphProvider = class {
       (row) => rowToMemoryRecord(unwrapRow(row))
     );
   }
+  /**
+   * MERGE an `Entity` node keyed by deterministic id.
+   *
+   * @param entity - Entity name, type, and optional metadata.
+   * @returns Stable entity id ({@link entityIdFrom}).
+   */
   async upsertEntity(entity) {
     const id = entityIdFrom(entity.name, entity.type);
     await this.run(
@@ -6152,24 +6740,40 @@ var Neo4jGraphProvider = class {
     );
     return id;
   }
+  /**
+   * MERGE a `MENTIONS` relationship from entity to memory.
+   *
+   * @param entityId - Entity id from {@link upsertEntity}.
+   * @param memoryId - Target memory UUID.
+   * @param role - Optional role string on the relationship.
+   */
   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 ?? "" }
+      );
+    });
   }
+  /**
+   * DETACH DELETE the memory node and all incident relationships.
+   *
+   * @param memoryId - Wolbarg memory UUID.
+   */
   async deleteMemory(memoryId) {
     await this.run(
       `MATCH (m:Memory { id: $id })
@@ -6177,9 +6781,17 @@ var Neo4jGraphProvider = class {
       { id: memoryId }
     );
   }
+  /**
+   * Run arbitrary parameterized Cypher (escape hatch for advanced graph queries).
+   *
+   * @param cypher - Cypher query string.
+   * @param params - Bound parameters for the query.
+   * @returns Raw row objects from the driver.
+   */
   async query(cypher, params) {
     return this.run(cypher, params ?? {});
   }
+  /** Verify connectivity and return server metadata when available. */
   async health() {
     try {
       if (!this.opened || !this.driver) {
@@ -6241,6 +6853,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 {
@@ -6287,6 +6914,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") {
@@ -6396,11 +7152,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");
   }
@@ -6418,13 +7185,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) {
@@ -6483,59 +7257,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();
@@ -6561,21 +7282,32 @@ function createChildTrace(parent) {
 // src/telemetry/emitter.ts
 var NoopTelemetryProvider = class {
   name = "noop";
+  /** @inheritdoc TelemetryProvider.open */
   async open() {
   }
+  /** @inheritdoc TelemetryProvider.close */
   async close() {
   }
+  /** @inheritdoc TelemetryProvider.emit */
   emit(_event) {
   }
+  /** @inheritdoc TelemetryProvider.flush */
   async flush() {
   }
 };
 var TelemetryEmitter = class {
+  /** Stable session id for this Wolbarg instance lifetime. */
   sessionId;
+  /** Structured logger gated by telemetry log level. */
   logger;
   provider;
   config;
   context;
+  /**
+   * @param provider - Telemetry backend, or `null` for {@link NoopTelemetryProvider}.
+   * @param config - Capture flags and log level.
+   * @param context - Default organization injected into events.
+   */
   constructor(provider, config, context = {}) {
     this.sessionId = createSessionId();
     this.provider = provider ?? new NoopTelemetryProvider();
@@ -6591,25 +7323,37 @@ var TelemetryEmitter = class {
     this.context = context;
     this.logger = new WolbargLogger(this.config.level);
   }
+  /** Whether telemetry is enabled and backed by a non-noop provider. */
   get enabled() {
     return this.config.enabled && this.provider.name !== "noop";
   }
+  /** Replace the underlying telemetry provider (e.g. after lazy init). */
   setProvider(provider) {
     this.provider = provider;
   }
+  /** Open the underlying telemetry provider when enabled. */
   async open() {
     if (!this.config.enabled) {
       return;
     }
     await this.provider.open();
   }
+  /** Flush pending events and close the telemetry provider. */
   async close() {
     await this.provider.flush();
     await this.provider.close();
   }
+  /** Flush pending telemetry events without closing the provider. */
   async flush() {
     await this.provider.flush();
   }
+  /**
+   * Begin tracing an operation.
+   *
+   * @param operation - Public telemetry operation name.
+   * @param parent - Optional parent trace for nested spans.
+   * @returns Handle — call `success()` or `failure()` when done.
+   */
   start(operation, parent) {
     const context = parent ? createChildTrace(parent) : createRootTrace(this.sessionId);
     const startedAt = performance.now();
@@ -6620,14 +7364,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(),
@@ -6684,10 +7428,12 @@ var TelemetryEmitter = class {
       }
     };
   }
+  /** Emit a startup telemetry event. */
   emitStartup(provider) {
     const trace = this.start("startup");
     trace.success({ provider });
   }
+  /** Emit a shutdown telemetry event. */
   emitShutdown(provider) {
     const trace = this.start("shutdown");
     trace.success({ provider });
@@ -6753,10 +7499,15 @@ var SqliteEventDatabase = class {
   db = null;
   insertStmt = null;
   columns = /* @__PURE__ */ new Set();
+  /**
+   * @param options.url - Path to the telemetry SQLite file.
+   * @param options.readonly - Open read-only (Studio / analytics).
+   */
   constructor(options) {
     this.url = options.url;
     this.readonly = options.readonly ?? false;
   }
+  /** Open the telemetry database and run schema migrations. */
   async open() {
     try {
       const dbPath = this.resolvePath(this.url);
@@ -6811,6 +7562,7 @@ var SqliteEventDatabase = class {
       );
     }
   }
+  /** Close the telemetry database connection. */
   async close() {
     if (!this.db) return;
     try {
@@ -6821,6 +7573,7 @@ var SqliteEventDatabase = class {
       this.columns.clear();
     }
   }
+  /** Insert one normalized telemetry event row. */
   async insertEvent(input) {
     const event = normalizeEvent(input);
     const stmt = this.insertStmt;
@@ -6866,6 +7619,7 @@ var SqliteEventDatabase = class {
       );
     }
   }
+  /** Insert many events in a single transaction. */
   async insertEvents(inputs) {
     const db = this.requireDb();
     const out = [];
@@ -6884,6 +7638,7 @@ var SqliteEventDatabase = class {
       throw error;
     }
   }
+  /** Query telemetry events with filters, sort, and pagination. */
   async query(options) {
     const db = this.requireDb();
     const clauses = [];
@@ -6929,8 +7684,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 ?`);
@@ -6962,11 +7719,13 @@ var SqliteEventDatabase = class {
       offset
     };
   }
+  /** Fetch one event by primary key. */
   async getEvent(id) {
     const db = this.requireDb();
     const row = db.prepare(`SELECT * FROM telemetry_events WHERE id = ?`).get(id);
     return row ? rowToEvent(row) : null;
   }
+  /** Count events optionally filtered by time and operation. */
   async countEvents(filter) {
     const db = this.requireDb();
     const clauses = [];
@@ -7107,6 +7866,7 @@ function describe2(error) {
 }
 
 // src/providers/sqlite/sqliteTelemetryProvider.ts
+var MAX_QUEUE_SIZE = 1e4;
 var SqliteTelemetryProvider = class {
   name = "sqlite";
   db;
@@ -7114,9 +7874,15 @@ var SqliteTelemetryProvider = class {
   flushing = null;
   closed = false;
   openPromise = null;
+  warnedQueueDrop = false;
+  warnedFlushFailure = false;
+  /**
+   * @param options.url - Path to the independent telemetry SQLite database file.
+   */
   constructor(options) {
     this.db = new SqliteEventDatabase({ url: options.url });
   }
+  /** Open the telemetry EventDatabase (lazy — also invoked on first emit). */
   async open() {
     if (!this.openPromise) {
       this.openPromise = this.db.open();
@@ -7124,19 +7890,35 @@ var SqliteTelemetryProvider = class {
     await this.openPromise;
     this.closed = false;
   }
+  /** Flush pending events and close the telemetry database. */
   async close() {
     this.closed = true;
     await this.flush();
     await this.db.close();
     this.openPromise = null;
   }
+  /**
+   * Enqueue a telemetry event for async persistence (never throws).
+   *
+   * @param event - Partial or complete {@link TelemetryEventInput}.
+   */
   emit(event) {
     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();
   }
+  /** Block until all queued events are written (or dropped on failure). */
   async flush() {
     while (this.queue.length > 0 || this.flushing) {
       await this.scheduleFlush();
@@ -7145,10 +7927,12 @@ var SqliteTelemetryProvider = class {
       }
     }
   }
+  /** Query persisted telemetry events with filters and pagination. */
   async query(options) {
     await this.open();
     return this.db.query(options);
   }
+  /** Fetch a single telemetry event by id. */
   async getEvent(id) {
     await this.open();
     return this.db.getEvent(id);
@@ -7176,7 +7960,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)}`
+        );
+      }
     }
   }
 };
@@ -7184,16 +7974,28 @@ var SqliteCheckpointProvider = class {
   name = "sqlite";
   directory;
   ready = false;
+  /**
+   * @param options.directory - Folder for `.json` metadata and `.db` snapshot files.
+   */
   constructor(options) {
     this.directory = options?.directory ?? path7__default.default.resolve(process.cwd(), ".wolbarg", "checkpoints");
   }
+  /** Ensure the checkpoint directory exists. */
   async open() {
     fs6__default.default.mkdirSync(this.directory, { recursive: true });
     this.ready = true;
   }
+  /** Mark the provider closed (does not delete snapshots). */
   async close() {
     this.ready = false;
   }
+  /**
+   * Create an immutable SQLite backup of `sourcePath` under a unique name.
+   *
+   * @param name - Checkpoint label (must not already exist).
+   * @param sourcePath - Live memory database path to snapshot.
+   * @param options.description - Optional human-readable description stored in metadata.
+   */
   async checkpoint(name, sourcePath, options) {
     this.requireReady();
     assertCheckpointName(name);
@@ -7219,8 +8021,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,
@@ -7231,9 +8045,17 @@ 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;
   }
+  /**
+   * Restore a named checkpoint over `targetPath` (replaces WAL/SHM side files).
+   *
+   * @param name - Existing checkpoint name.
+   * @param targetPath - Live memory database path to overwrite.
+   */
   async rollback(name, targetPath) {
     this.requireReady();
     const meta2 = await this.getCheckpoint(name);
@@ -7256,6 +8078,7 @@ Ensure Wolbarg has been initialized and the database path is correct.`
     await safeSqliteBackup(meta2.snapshotPath, resolvedTarget);
     return meta2;
   }
+  /** Delete checkpoint metadata and snapshot files for `name`. */
   async deleteCheckpoint(name) {
     this.requireReady();
     const metaPath = this.metaPath(name);
@@ -7271,6 +8094,7 @@ Ensure Wolbarg has been initialized and the database path is correct.`
     }
     return removed;
   }
+  /** List all checkpoints sorted by creation time. */
   async listCheckpoints() {
     this.requireReady();
     if (!fs6__default.default.existsSync(this.directory)) {
@@ -7287,6 +8111,7 @@ Ensure Wolbarg has been initialized and the database path is correct.`
     }
     return out.sort((a, b) => a.createdAt.localeCompare(b.createdAt));
   }
+  /** Load checkpoint metadata by name, or `null` if missing / corrupt. */
   async getCheckpoint(name) {
     this.requireReady();
     const metaPath = this.metaPath(name);
@@ -7471,6 +8296,13 @@ var SqliteSubscribeEmitter = class {
       }
     });
   }
+  /**
+   * Register a filtered callback for in-process memory change events.
+   *
+   * @param filter - Organization / agent / event-type filter.
+   * @param callback - Invoked synchronously on each matching emit.
+   * @returns Unsubscribe function.
+   */
   subscribe(filter, callback) {
     if (this.closed) {
       throw new Error("Subscribe backend is closed");
@@ -7481,12 +8313,14 @@ var SqliteSubscribeEmitter = class {
       this.subscriptions.delete(id);
     };
   }
+  /** Emit a memory change event to registered subscribers. */
   emit(event) {
     if (this.closed) {
       return;
     }
     this.emitter.emit("change", event);
   }
+  /** Remove all listeners and mark the emitter closed. */
   async close() {
     this.closed = true;
     this.subscriptions.clear();
@@ -7495,6 +8329,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;
@@ -7521,6 +8358,20 @@ var Wolbarg = class {
   memoryDedupe = resolveMemoryDedupeConfig();
   embeddingCacheConfig = resolveEmbeddingCacheConfig();
   rawEmbedding = null;
+  /**
+   * @param options - Full {@link WolbargOptions}. Key fields:
+   * - `organization` — namespace isolating memories in a shared DB
+   * - `database` / `storage` — SQLite/Postgres config **or** a custom
+   *   {@link StorageProvider} instance
+   * - `embedding` — {@link EmbeddingProvider} instance **or**
+   *   {@link EmbeddingConfig} / {@link openaiEmbedding} (etc.)
+   * - `llm` — optional {@link LlmProvider} or {@link LlmConfig} / {@link openaiLlm};
+   *   required for {@link Wolbarg.compress} and extract-mode
+   *   {@link Wolbarg.rememberFromMessages}
+   * - `graph`, `telemetry`, `reranker`, `keywordSearch`, `ocr`, `vision`,
+   *   `compression`, `chunking`, `retrieval`, `concurrency`, `embeddingCache`,
+   *   `memory.dedupe` — optional plugins / tuning
+   */
   constructor(options) {
     this.telemetry = new TelemetryEmitter(null, { enabled: false, level: "off" });
     if (!options) {
@@ -7579,6 +8430,12 @@ var Wolbarg = class {
   }
   /**
    * Backwards-compatible initialization (v0.1 API).
+   * Prefer constructing with options + {@link Wolbarg.ready} instead.
+   *
+   * @param options - Organization, database, embedding, and optional LLM config.
+   * @returns Resolves when storage is open and the vector schema is ready.
+   * @throws {InitializationError} If already initialized.
+   * @throws {ConfigurationError} | {ValidationError} On invalid options.
    */
   async init(options) {
     if (this.initialized || this.storage) {
@@ -7600,6 +8457,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);
@@ -7609,7 +8467,14 @@ var Wolbarg = class {
     }
     await this.ready();
   }
-  /** Ensure storage (and optional telemetry) are open. */
+  /**
+   * Open storage, optional telemetry / checkpoint / graph providers, wrap the
+   * embedding cache, and probe embedding dimensions. Safe to call multiple times;
+   * concurrent callers share one boot promise.
+   *
+   * @returns Resolves when the instance is ready for remember/recall.
+   * @throws {InitializationError} If neither constructor options nor {@link init} were used.
+   */
   async ready() {
     if (this.initialized) {
       return;
@@ -7625,6 +8490,7 @@ var Wolbarg = class {
       this.booting = null;
     }
   }
+  /** Internal boot sequence invoked by {@link Wolbarg.ready}. */
   async boot() {
     if (!this.storage || !this.embedding || !this.organization) {
       throw new InitializationError(
@@ -7700,7 +8566,17 @@ var Wolbarg = class {
       );
     }
   }
-  /** Store a semantic memory for an agent (may upsert when dedupe is enabled). */
+  /**
+   * Store a semantic memory for an agent. Embeds `content.text`, writes the row,
+   * and may **upsert** an existing active memory when dedupe is enabled
+   * (constructor `memory.dedupe` or per-call `options.dedupe`).
+   *
+   * @param options - Agent id, text content, optional metadata / dedupe overrides.
+   *   See {@link RememberOptions}.
+   * @returns The stored record plus `action` (`"created"` | `"updated"`).
+   * @throws {ValidationError} On empty agent/content.
+   * @throws {InitializationError} If not configured / ready.
+   */
   async remember(options) {
     const trace = this.telemetry.start("remember");
     try {
@@ -7722,7 +8598,15 @@ var Wolbarg = class {
       throw wrapOperationError("remember", error);
     }
   }
-  /** Batch remember — sequential when dedupe enabled; otherwise one TX batch. */
+  /**
+   * Remember many memories in one call. Runs sequentially when any item (or the
+   * global config) enables dedupe; otherwise embeds in batch and inserts in one
+   * transaction for throughput.
+   *
+   * @param items - Non-empty list of {@link RememberOptions}.
+   * @returns One {@link RememberResult} per input, same order.
+   * @throws {ValidationError} If `items` is empty or an entry is invalid.
+   */
   async rememberBatch(items) {
     const parent = this.telemetry.start("rememberBatch");
     try {
@@ -7848,7 +8732,15 @@ var Wolbarg = class {
    * **Experimental** until 1.0 — API shape may change.
    *
    * - `mode: "raw"` (default) — remember user message text (no LLM).
-   * - `mode: "extract"` — require configured `llm`; extract atomic facts then remember each.
+   * - `mode: "extract"` — requires configured `llm`; extracts atomic facts then
+   *   remembers each. Pass a custom {@link LlmProvider} or {@link openaiLlm}
+   *   in the constructor.
+   *
+   * @param messages - Conversation turns (`role` + `content`).
+   * @param options - Agent, mode, optional metadata/dedupe. See
+   *   {@link RememberFromMessagesOptions}.
+   * @returns One {@link RememberResult} per remembered fact/message.
+   * @throws {ProviderNotConfiguredError} When `mode: "extract"` but no `llm` was configured.
    */
   async rememberFromMessages(messages, options) {
     const parent = this.telemetry.start("rememberFromMessages");
@@ -7918,10 +8810,17 @@ var Wolbarg = class {
     }
   }
   /**
-   * Update an existing memory by id (re-embeds when content changes).
+   * Update an existing memory by id. Re-embeds when `content` changes; merges
+   * metadata when provided.
+   *
+   * @param options.id - Memory id to update.
+   * @param options.content - Optional new `{ text }` (triggers re-embed + content hash).
+   * @param options.metadata - Optional metadata merged onto the existing record.
+   * @returns Updated record with `action: "updated"`.
+   * @throws {MemoryNotFoundError} If the id is unknown in this organization.
    */
   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");
@@ -7988,10 +8887,18 @@ var Wolbarg = class {
     }
   }
   /**
-   * Subscribe to memory change events.
+   * Subscribe to memory change events (remember / update / forget / compress / clear).
    *
    * **SQLite:** delivers events only within this Node.js process.
    * A second process writing the same `memory.db` will not notify subscribers here.
+   *
+   * **Postgres:** uses LISTEN/NOTIFY across processes (lazy connection on first subscribe).
+   *
+   * @param filter - Scope by `organization` (defaults to this instance’s org),
+   *   optional `agent`, and optional `events` allow-list. See {@link SubscribeFilter}.
+   * @param callback - Invoked with each {@link MemoryChangeEvent}.
+   * @returns {@link Unsubscribe} function — call to stop receiving events.
+   * @throws {ValidationError} If organization cannot be resolved.
    */
   subscribe(filter, callback) {
     const org = filter.organization || this.organization;
@@ -8020,6 +8927,7 @@ var Wolbarg = class {
     }
     return this.subscribeBackend.subscribe(normalized, callback);
   }
+  /** Broadcast a memory change event to in-process or Postgres NOTIFY subscribers. */
   emitChange(event) {
     try {
       if (this.storage instanceof PostgresStorageProvider) {
@@ -8245,6 +9153,17 @@ var Wolbarg = class {
       throw error;
     }
   }
+  /**
+   * Find the best active near-duplicate memory for upsert (cosine similarity ≥ threshold).
+   *
+   * @param storage - Open storage provider.
+   * @param organization - Org namespace.
+   * @param agent - Agent scope for the search.
+   * @param vector - Embedding of the candidate text.
+   * @param threshold - Minimum similarity (0–1) to treat as a duplicate.
+   * @param limit - Max vector candidates to inspect.
+   * @returns Matching memory row, or `null` if none qualify.
+   */
   async findNearDuplicate(storage, organization, agent, vector, threshold, limit) {
     if (typeof storage.searchVectorsWithMemories === "function") {
       const hits2 = await storage.searchVectorsWithMemories(
@@ -8447,17 +9366,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(
@@ -8492,14 +9431,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;
       }
@@ -8528,7 +9469,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) => ({
@@ -8560,7 +9501,13 @@ var Wolbarg = class {
       throw wrapOperationError("recall", error);
     }
   }
-  /** Batch recall — parent event + child traces. */
+  /**
+   * Run multiple recalls sequentially under one parent telemetry span.
+   *
+   * @param queries - Non-empty list of recall options (`explain` is forced off).
+   * @returns One hit array per query, same order.
+   * @throws {ValidationError} If `queries` is empty.
+   */
   async recallBatch(queries) {
     const parent = this.telemetry.start("recallBatch");
     try {
@@ -8594,10 +9541,21 @@ var Wolbarg = class {
       throw wrapOperationError("recallBatch", error);
     }
   }
+  /**
+   * Compress the newest active memories for an agent into one summary memory
+   * and archive the sources. Requires an `llm` (or custom `compression`) at
+   * construction — typed only on `Wolbarg<true>`.
+   *
+   * @param options - `agent` required; optional `limit` (default 50, min 2).
+   *   See {@link CompressOptions}.
+   * @returns Summary record plus archived source ids. See {@link CompressResult}.
+   * @throws {ProviderNotConfiguredError} If no LLM/compression provider is set.
+   * @throws {ValidationError} If fewer than 2 active memories exist for the agent.
+   */
   async compress(options) {
     return this.runCompress(options);
   }
-  /** @internal */
+  /** @internal Runs compress for both typed and untyped call sites. */
   async runCompress(options) {
     const trace = this.telemetry.start("compress");
     try {
@@ -8637,31 +9595,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,
@@ -8683,6 +9644,16 @@ var Wolbarg = class {
       throw wrapOperationError("compress", error);
     }
   }
+  /**
+   * Ingest a document (path, URL, Buffer, or text), chunk it, embed chunks, and
+   * store each as a memory. Images use optional `ocr` / `vision` providers from
+   * the constructor.
+   *
+   * @param options - `agent`, `source`, optional chunking overrides / metadata.
+   *   See {@link IngestOptions}.
+   * @returns Counts and created memory ids. See {@link IngestResult}.
+   * @throws {ValidationError} If no text can be extracted or chunking yields zero chunks.
+   */
   async ingest(options) {
     const trace = this.telemetry.start("ingest");
     try {
@@ -8853,8 +9824,14 @@ var Wolbarg = class {
     }
   }
   /**
-   * Link two memories in the optional graph layer.
-   * Throws {@link ProviderNotConfiguredError} when no graph provider is set.
+   * Link two memories in the optional graph layer with a typed relation edge.
+   *
+   * @param fromId - Source memory id.
+   * @param toId - Target memory id.
+   * @param relation - Edge label (e.g. `"supports"`, `"caused_by"`).
+   * @param metadata - Optional edge properties stored on the graph provider.
+   * @throws {ProviderNotConfiguredError} When no `graph` was configured.
+   * @throws {ValidationError} On empty ids/relation.
    */
   async linkMemories(fromId, toId, relation, metadata) {
     const trace = this.telemetry.start("linkMemories");
@@ -8884,8 +9861,13 @@ var Wolbarg = class {
   }
   /**
    * Traverse related memories via the optional graph layer.
-   * Throws {@link ProviderNotConfiguredError} when no graph provider is set.
-   * Results are re-hydrated from SQL storage when available.
+   * Neighbor stubs from the graph are re-hydrated from SQL storage when available.
+   *
+   * @param memoryId - Seed memory id.
+   * @param options - Optional `relation`, `direction`, `depth`, `limit`.
+   *   See {@link GetRelatedOptions}.
+   * @returns Related {@link MemoryRecord} list (may be empty).
+   * @throws {ProviderNotConfiguredError} When no `graph` was configured.
    */
   async getRelated(memoryId, options) {
     const trace = this.telemetry.start("getRelated");
@@ -8893,8 +9875,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,
@@ -8907,6 +9904,14 @@ var Wolbarg = class {
       throw wrapOperationError("getRelated", error);
     }
   }
+  /**
+   * Delete memories by id or by agent filter. Cascades graph nodes/edges when
+   * a graph provider is configured.
+   *
+   * @param options - Either `{ id }` or `{ filter: { agent } }`. See {@link ForgetOptions}.
+   * @returns Number of memories deleted.
+   * @throws {ValidationError} If neither `id` nor `filter.agent` is provided.
+   */
   async forget(options) {
     const trace = this.telemetry.start("forget");
     try {
@@ -8971,6 +9976,13 @@ var Wolbarg = class {
       throw wrapOperationError("forget", error);
     }
   }
+  /**
+   * Return the audit/history timeline for a single memory.
+   *
+   * @param options - `{ id }` of the memory. See {@link HistoryOptions}.
+   * @returns Memory record plus ordered {@link HistoryEvent} list.
+   * @throws {MemoryNotFoundError} If the id is unknown.
+   */
   async history(options) {
     const trace = this.telemetry.start("history");
     try {
@@ -8998,6 +10010,11 @@ var Wolbarg = class {
       throw wrapOperationError("history", error);
     }
   }
+  /**
+   * Aggregate counts for this organization (active / archived / agents / etc.).
+   *
+   * @returns {@link StatsResult} snapshot.
+   */
   async stats() {
     const trace = this.telemetry.start("stats");
     try {
@@ -9025,6 +10042,13 @@ var Wolbarg = class {
       throw wrapOperationError("stats", error);
     }
   }
+  /**
+   * Delete all memories for this organization (optionally scoped by agent).
+   * Cascades graph cleanup when a graph provider is configured.
+   *
+   * @param options - Optional `{ agent }` scope. See {@link ClearOptions}.
+   * @returns Number of memories deleted.
+   */
   async clear(options) {
     const trace = this.telemetry.start("clear");
     try {
@@ -9053,7 +10077,16 @@ var Wolbarg = class {
       throw wrapOperationError("clear", error);
     }
   }
-  /** Create an immutable named checkpoint of the memory database. */
+  /**
+   * Create an immutable named checkpoint of the file-backed SQLite memory DB
+   * (and SQLite graph snapshot when applicable).
+   *
+   * @param name - Checkpoint name (unique).
+   * @param options - Optional metadata. See {@link CheckpointOptions}.
+   * @returns {@link CheckpointInfo} for the new checkpoint.
+   * @throws {ProviderNotConfiguredError} Without a checkpoint provider / file DB.
+   * @throws {GraphCheckpointNotSupportedError} For Neo4j graph backends.
+   */
   async checkpoint(name, options) {
     const trace = this.telemetry.start("checkpoint");
     try {
@@ -9063,7 +10096,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,
@@ -9076,7 +10117,12 @@ var Wolbarg = class {
       throw wrapOperationError("checkpoint", error);
     }
   }
-  /** Restore the memory database from a named checkpoint. */
+  /**
+   * Restore the memory database from a named checkpoint (replaces the live DB file).
+   *
+   * @param name - Checkpoint name previously created with {@link Wolbarg.checkpoint}.
+   * @returns {@link CheckpointInfo} of the restored checkpoint.
+   */
   async rollback(name) {
     const trace = this.telemetry.start("rollback");
     let storageClosed = false;
@@ -9122,13 +10168,26 @@ var Wolbarg = class {
       throw wrapOperationError("rollback", error);
     }
   }
+  /**
+   * Delete a named checkpoint from disk / the checkpoint store.
+   *
+   * @param name - Checkpoint name.
+   * @returns `true` if a checkpoint was removed.
+   */
   async deleteCheckpoint(name) {
     const trace = this.telemetry.start("deleteCheckpoint");
     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,
@@ -9141,6 +10200,11 @@ var Wolbarg = class {
       throw wrapOperationError("deleteCheckpoint", error);
     }
   }
+  /**
+   * List all known checkpoints for this instance.
+   *
+   * @returns Array of {@link CheckpointInfo} (may be empty).
+   */
   async listCheckpoints() {
     const trace = this.telemetry.start("listCheckpoints");
     try {
@@ -9159,6 +10223,12 @@ var Wolbarg = class {
       throw wrapOperationError("listCheckpoints", error);
     }
   }
+  /**
+   * Look up a single checkpoint by name.
+   *
+   * @param name - Checkpoint name.
+   * @returns {@link CheckpointInfo} or `null` if missing.
+   */
   async getCheckpoint(name) {
     const trace = this.telemetry.start("getCheckpoint");
     try {
@@ -9178,7 +10248,13 @@ var Wolbarg = class {
       throw wrapOperationError("getCheckpoint", error);
     }
   }
-  /** Export the memory database to a portable SQLite + manifest bundle. */
+  /**
+   * Export the memory database to a portable SQLite + manifest bundle
+   * (includes SQLite graph sidecar when applicable).
+   *
+   * @param exportPath - Destination file path for the export bundle.
+   * @returns {@link ExportResult} with path, size, and timestamp.
+   */
   async export(exportPath) {
     const trace = this.telemetry.start("export");
     try {
@@ -9190,7 +10266,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({
@@ -9207,22 +10285,33 @@ var Wolbarg = class {
       throw wrapOperationError("export", error);
     }
   }
-  /** Import a previously exported memory database, replacing the current file. */
+  /**
+   * Import a previously exported memory database, replacing the current file.
+   * Closes and reopens storage around the swap.
+   *
+   * @param exportPath - Path to a bundle produced by {@link Wolbarg.export}.
+   * @returns {@link ImportResult} with restored path and timestamp.
+   */
   async import(exportPath) {
     const trace = this.telemetry.start("import");
     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) {
@@ -9252,11 +10341,17 @@ var Wolbarg = class {
       throw wrapOperationError("import", error);
     }
   }
-  /** Flush pending telemetry (useful in tests). */
+  /**
+   * Flush pending telemetry writes (useful in tests / before process exit).
+   *
+   * @returns Resolves when the telemetry provider has flushed.
+   */
   async flushTelemetry() {
     await this.telemetry.flush();
   }
-  /** Session id for this SDK instance (telemetry traces). */
+  /**
+   * Session id for this SDK instance (attached to telemetry traces and change events).
+   */
   get sessionId() {
     return this.telemetry.sessionId;
   }
@@ -9271,6 +10366,12 @@ var Wolbarg = class {
     }
     return fn();
   }
+  /**
+   * Close storage, graph, telemetry, checkpoints, and subscribe backends.
+   * The instance can be discarded afterward; construct a new one to reopen.
+   *
+   * @returns Resolves when all providers have closed (errors are swallowed per-provider).
+   */
   async close() {
     if (this.storage) {
       this.telemetry.emitShutdown(this.storage.name);
@@ -9295,9 +10396,11 @@ var Wolbarg = class {
     this.embeddingDimensions = null;
     this.initialized = false;
   }
+  /** Whether {@link Wolbarg.ready} / {@link Wolbarg.init} has completed successfully. */
   get isInitialized() {
     return this.initialized;
   }
+  /** Ensure {@link Wolbarg.ready} completed and core providers are available. */
   async requireReady() {
     await this.ready();
     if (!this.initialized || !this.storage || !this.embedding || !this.organization) {
@@ -9311,6 +10414,7 @@ var Wolbarg = class {
       organization: this.organization
     };
   }
+  /** Reject embeddings whose dimensionality differs from the initialized model. */
   assertEmbeddingDimensions(dimensions) {
     if (this.embeddingDimensions !== null && dimensions !== this.embeddingDimensions) {
       throw new ValidationError(
@@ -9318,6 +10422,7 @@ var Wolbarg = class {
       );
     }
   }
+  /** Return the configured checkpoint provider or throw {@link ProviderNotConfiguredError}. */
   requireCheckpointProvider() {
     if (!this.checkpointProvider) {
       throw new ProviderNotConfiguredError(
@@ -9328,6 +10433,7 @@ var Wolbarg = class {
     }
     return this.checkpointProvider;
   }
+  /** Return the configured graph provider or throw with a setup hint for `method`. */
   requireGraph(method) {
     if (!this.graph) {
       throw new ProviderNotConfiguredError(
@@ -9338,20 +10444,24 @@ var Wolbarg = class {
     }
     return this.graph;
   }
+  /** Throw when graph checkpoint pairing is requested on a non-file-backed graph backend. */
   assertGraphCheckpointSupported(operation) {
     if (!this.graph) return;
     if (!this.graph.supportsFileSnapshot()) {
       throw new GraphCheckpointNotSupportedError(this.graph.name, operation);
     }
   }
+  /** Directory path where a graph file snapshot is stored alongside a memory checkpoint. */
   graphSnapshotDir(alongsidePath) {
     return `${alongsidePath}.graph`;
   }
+  /** Close the graph provider before copying files; returns whether a close occurred. */
   async closeGraphForSnapshot() {
     if (!this.graph || !this.graph.supportsFileSnapshot()) return false;
     await this.graph.close();
     return true;
   }
+  /** Copy the SQLite graph database next to a memory checkpoint directory. */
   async snapshotGraphAlongside(alongsidePath, operation) {
     if (!this.graph) return;
     if (!this.graph.supportsFileSnapshot()) {
@@ -9390,6 +10500,7 @@ var Wolbarg = class {
       await this.graph.open();
     }
   }
+  /** Restore a graph file snapshot written by {@link snapshotGraphAlongside}. */
   async restoreGraphAlongside(alongsidePath, operation) {
     if (!this.graph) return;
     if (!this.graph.supportsFileSnapshot()) {
@@ -9413,22 +10524,32 @@ var Wolbarg = class {
       fs6__default.default.cpSync(src, dataPath, { recursive: true });
     }
   }
+  /** Run graph traversal then re-hydrate stub records from storage when rows exist. */
   async hydrateRelated(memoryId, options) {
     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;
   }
+  /** Resolve the on-disk SQLite memory database path (throws for Postgres / `:memory:`). */
   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:).",
@@ -9471,6 +10592,7 @@ function commonTags(metadata) {
 
 // src/filters/types.ts
 var meta = {
+  /** Field equals value (strict equality). */
   eq: (field, value) => ({
     field,
     op: { eq: value }
@@ -9554,16 +10676,23 @@ function createTelemetryProvider(config) {
 function wolbarg2(options) {
   return new Wolbarg(options);
 }
+var createWolbarg = wolbarg2;
 
 // src/keyword/index.ts
 var Bm25KeywordSearchProvider = class {
   name = "bm25";
   k1;
   b;
+  /**
+   * @param options - BM25 tuning parameters.
+   * @param options.k1 - Term frequency saturation (default `1.2`).
+   * @param options.b - Length normalization (default `0.75`).
+   */
   constructor(options) {
     this.k1 = options?.k1 ?? 1.2;
     this.b = options?.b ?? 0.75;
   }
+  /** @inheritdoc */
   async search(query, documents, topK) {
     if (documents.length === 0 || topK <= 0) {
       return [];
@@ -9657,7 +10786,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,
@@ -9842,21 +10978,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();
       }
     }
   };
@@ -10039,7 +11185,7 @@ exports.createEmbeddingProvider = createEmbeddingProvider;
 exports.createLlmProvider = createLlmProvider;
 exports.createStorageProvider = createStorageProvider;
 exports.createTelemetryProvider = createTelemetryProvider;
-exports.createWolbarg = wolbarg2;
+exports.createWolbarg = createWolbarg;
 exports.crossEncoder = crossEncoder;
 exports.geminiEmbedding = geminiEmbedding;
 exports.geminiVision = geminiVision;