wolbarg 0.5.3 → 0.5.5

package/dist/index.js

@@ -15,6 +15,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";
@@ -26,48 +31,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";
@@ -75,6 +112,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,
@@ -86,6 +128,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})`,
@@ -158,9 +204,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);
   }
@@ -269,6 +317,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);
@@ -276,6 +325,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);
@@ -284,6 +334,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);
@@ -292,6 +343,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);
@@ -303,6 +355,7 @@ var MarkdownChunkingStrategy = class {
 };
 var HeadingChunkingStrategy = class {
   name = "heading";
+  /** @inheritdoc */
   chunk(text, options) {
     return new MarkdownChunkingStrategy().chunk(text, options);
   }
@@ -384,6 +437,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) => {
@@ -407,16 +466,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;
@@ -425,6 +500,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 [];
@@ -451,6 +533,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");
@@ -465,6 +553,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();
@@ -512,6 +606,7 @@ var OpenAICompatibleEmbeddingProvider = class {
       clearTimeout(timer);
     }
   }
+  /** @param error - Unknown thrown value. @returns Human-readable message. */
   describe(error) {
     if (error instanceof Error) {
       return error.message;
@@ -662,6 +757,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;
@@ -729,6 +863,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;
@@ -746,7 +884,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(
@@ -781,7 +921,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);
@@ -833,6 +995,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);
@@ -867,10 +1039,10 @@ var SqliteEmbeddingCacheStore = class {
           db.exec("ROLLBACK");
         } catch {
         }
-        this.stmts = null;
+        requeue();
       }
     } catch {
-      this.stmts = null;
+      requeue();
     }
   }
 };
@@ -971,12 +1143,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;
@@ -985,6 +1168,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;
@@ -993,6 +1183,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([
@@ -1014,6 +1209,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();
@@ -1062,6 +1263,7 @@ var OpenAICompatibleLlmProvider = class {
       clearTimeout(timer);
     }
   }
+  /** @param error - Unknown thrown value. @returns Human-readable message. */
   describe(error) {
     if (error instanceof Error) {
       return error.message;
@@ -1179,12 +1381,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 ?? "",
@@ -1192,9 +1409,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"
+        }
       );
     }
   }
@@ -1341,6 +1563,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;
     }
@@ -1421,6 +1649,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 = {
@@ -1735,40 +2036,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;
@@ -1776,18 +2043,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 : (() => {
@@ -1818,6 +2096,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) {
@@ -1837,7 +2119,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) {
@@ -1861,24 +2148,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) {
@@ -1924,8 +2220,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];
@@ -2067,6 +2363,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;
@@ -2076,6 +2375,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;
@@ -2097,6 +2400,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);
@@ -2109,9 +2415,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);
@@ -2142,6 +2450,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) {
@@ -2165,6 +2479,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) {
@@ -2195,6 +2510,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) {
@@ -2217,13 +2537,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) => {
@@ -2305,6 +2628,7 @@ var SqliteStorageProvider = class _SqliteStorageProvider {
       return row;
     });
   }
+  /** Batch insert memories in chunked multi-row transactions. */
   async insertMemoriesBatch(inputs) {
     if (inputs.length === 0) {
       return [];
@@ -2320,6 +2644,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(() => {
@@ -2363,6 +2688,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(
@@ -2372,6 +2698,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) {
@@ -2382,9 +2709,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 {
@@ -2398,20 +2732,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) {
@@ -2430,6 +2776,7 @@ var SqliteStorageProvider = class _SqliteStorageProvider {
     }
     return out;
   }
+  /** List memories matching repository filters with optional limit. */
   async listMemories(filter, limit) {
     try {
       if (filter.metadata) {
@@ -2442,6 +2789,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") {
@@ -2453,6 +2801,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) {
@@ -2491,6 +2840,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 = [];
@@ -2528,6 +2878,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(() => {
@@ -2541,6 +2892,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;
@@ -2557,6 +2909,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(() => {
@@ -2573,10 +2926,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(
@@ -2587,6 +2942,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);
@@ -2597,6 +2953,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:") {
@@ -2629,21 +2986,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 {
@@ -3632,11 +4012,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;
@@ -3733,6 +4119,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");
@@ -3754,6 +4147,7 @@ var PostgresSubscribeListener = class {
    */
   emit(_event) {
   }
+  /** Tear down LISTEN connection and clear subscriptions. */
   async close() {
     this.closed = true;
     this.subscriptions.clear();
@@ -3792,9 +4186,13 @@ function createPostgresListenerFromPool(pool, onError) {
 
 // src/storage/providers/postgres.ts
 var txStore = new 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);
@@ -3865,13 +4263,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 (
@@ -3887,7 +4285,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;
@@ -3914,6 +4312,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;
@@ -3922,6 +4323,7 @@ var PostgresStorageProvider = class _PostgresStorageProvider {
       this.durableWrites
     );
   }
+  /** Current pg pool occupancy stats (for diagnostics / subscribe setup). */
   getPoolStats() {
     const pool = this.pool;
     return {
@@ -3935,6 +4337,7 @@ var PostgresStorageProvider = class _PostgresStorageProvider {
   getPool() {
     return this.pool;
   }
+  /** Open the connection pool and run migrations. */
   async open() {
     let PoolCtor;
     try {
@@ -3983,6 +4386,7 @@ var PostgresStorageProvider = class _PostgresStorageProvider {
       );
     }
   }
+  /** Drain coalesced inserts and end the connection pool. */
   async close() {
     if (this.insertFlushTimer) {
       clearTimeout(this.insertFlushTimer);
@@ -4023,6 +4427,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) {
@@ -4087,6 +4496,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);
   }
@@ -4094,6 +4508,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
@@ -4111,6 +4526,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(
@@ -4156,6 +4572,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)}`,
@@ -4164,6 +4586,7 @@ var PostgresStorageProvider = class _PostgresStorageProvider {
       }
     }
   }
+  /** @inheritdoc StorageProvider.getEmbeddingDimensions */
   async getEmbeddingDimensions() {
     const result = await this.query(
       `SELECT value FROM Wolbarg_meta WHERE key = $1`,
@@ -4176,6 +4599,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)
@@ -4184,6 +4608,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) => {
@@ -4270,6 +4695,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 [];
@@ -4300,6 +4726,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];
@@ -4310,6 +4737,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, [
@@ -4320,9 +4748,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],
@@ -4330,7 +4759,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]
     }));
@@ -4371,81 +4800,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,
@@ -4458,6 +4893,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,
@@ -4468,6 +4904,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,
@@ -4481,6 +4918,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) {
@@ -4503,6 +4941,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;
@@ -4564,9 +5003,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) {
@@ -4593,10 +5034,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) {
@@ -4646,6 +5097,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) {
@@ -4710,46 +5162,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`,
@@ -4757,6 +5213,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");
@@ -4767,6 +5224,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`,
@@ -4774,6 +5232,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
@@ -4788,6 +5247,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)
@@ -4801,6 +5261,7 @@ var PostgresStorageProvider = class _PostgresStorageProvider {
       ]
     );
   }
+  /** Aggregate memory counts for an organization. */
   async getStats(organization) {
     const result = await this.query(
       `SELECT
@@ -4818,6 +5279,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`
@@ -4859,6 +5321,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
@@ -5009,8 +5476,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;
     }
   }
@@ -5151,11 +5627,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(
@@ -5182,7 +5659,9 @@ Initialize Wolbarg and verify the database path.`
       sdkVersion: SDK_VERSION,
       provider: "sqlite",
       sourcePath: resolvedSource,
-      organization
+      organization,
+      ...embeddingModel ? { embeddingModel } : {},
+      ...embeddingDimensions ? { embeddingDimensions } : {}
     };
     fs6.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2), "utf8");
     return {
@@ -5191,7 +5670,7 @@ Initialize Wolbarg and verify the database path.`
       sizeBytes: fs6.statSync(dbExportPath).size
     };
   }
-  async importFrom(exportPath, targetPath) {
+  async importFrom(exportPath, targetPath, expected) {
     const resolvedExport = resolvePath(exportPath);
     const dbExportPath = resolvedExport.endsWith(".db") ? resolvedExport : fs6.existsSync(`${resolvedExport}.db`) ? `${resolvedExport}.db` : resolvedExport;
     if (!fs6.existsSync(dbExportPath)) {
@@ -5213,26 +5692,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.existsSync(side)) {
+        fs6.rmSync(side, { force: true });
+      }
+    }
+    await copySqlite(dbExportPath, tmpTarget);
     for (const suffix of ["", "-wal", "-shm"]) {
       const side = `${resolvedTarget}${suffix}`;
       if (fs6.existsSync(side)) {
         fs6.rmSync(side, { force: true });
       }
     }
-    await copySqlite(dbExportPath, resolvedTarget);
-    return { path: resolvedTarget, manifest };
+    fs6.renameSync(tmpTarget, resolvedTarget);
+    for (const suffix of ["-wal", "-shm"]) {
+      const from = `${tmpTarget}${suffix}`;
+      const to = `${resolvedTarget}${suffix}`;
+      if (fs6.existsSync(from)) {
+        fs6.renameSync(from, to);
+      }
+    }
+    return { path: resolvedTarget, manifest: manifest ?? void 0 };
   }
 };
 async function copySqlite(sourcePath, destPath) {
@@ -5461,7 +5971,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;
       }
@@ -5585,6 +6096,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");
@@ -5592,12 +6106,15 @@ var SqliteGraphProvider = class {
     this.dbPath = path7.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 {
@@ -5634,6 +6151,7 @@ var SqliteGraphProvider = class {
       );
     }
   }
+  /** Close the graph database connection. */
   async close() {
     if (!this.db) {
       this.opened = false;
@@ -5655,6 +6173,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(() => {
@@ -5677,6 +6203,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(() => {
@@ -5726,6 +6259,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();
@@ -5750,6 +6289,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(() => {
@@ -5779,6 +6325,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(() => {
@@ -5798,6 +6349,7 @@ var SqliteGraphProvider = class {
       }
     );
   }
+  /** Lightweight connectivity and schema statistics check. */
   async health() {
     try {
       if (!this.opened || !this.db) {
@@ -5943,6 +6495,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");
@@ -5958,12 +6513,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;
@@ -5995,6 +6553,7 @@ var Neo4jGraphProvider = class {
       }
     });
   }
+  /** Close the neo4j-driver connection. */
   async close() {
     if (this.driver) {
       await this.driver.close();
@@ -6021,24 +6580,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 = '',
@@ -6047,25 +6608,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(
@@ -6111,6 +6693,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(
@@ -6125,24 +6713,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 })
@@ -6150,9 +6754,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) {
@@ -6214,6 +6826,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 {
@@ -6260,6 +6887,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") {
@@ -6369,11 +7125,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");
   }
@@ -6391,13 +7158,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) {
@@ -6456,59 +7230,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();
@@ -6534,21 +7255,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();
@@ -6564,25 +7296,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();
@@ -6593,14 +7337,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(),
@@ -6657,10 +7401,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 });
@@ -6726,10 +7472,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);
@@ -6784,6 +7535,7 @@ var SqliteEventDatabase = class {
       );
     }
   }
+  /** Close the telemetry database connection. */
   async close() {
     if (!this.db) return;
     try {
@@ -6794,6 +7546,7 @@ var SqliteEventDatabase = class {
       this.columns.clear();
     }
   }
+  /** Insert one normalized telemetry event row. */
   async insertEvent(input) {
     const event = normalizeEvent(input);
     const stmt = this.insertStmt;
@@ -6839,6 +7592,7 @@ var SqliteEventDatabase = class {
       );
     }
   }
+  /** Insert many events in a single transaction. */
   async insertEvents(inputs) {
     const db = this.requireDb();
     const out = [];
@@ -6857,6 +7611,7 @@ var SqliteEventDatabase = class {
       throw error;
     }
   }
+  /** Query telemetry events with filters, sort, and pagination. */
   async query(options) {
     const db = this.requireDb();
     const clauses = [];
@@ -6902,8 +7657,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 ?`);
@@ -6935,11 +7692,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 = [];
@@ -7080,6 +7839,7 @@ function describe2(error) {
 }
 
 // src/providers/sqlite/sqliteTelemetryProvider.ts
+var MAX_QUEUE_SIZE = 1e4;
 var SqliteTelemetryProvider = class {
   name = "sqlite";
   db;
@@ -7087,9 +7847,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();
@@ -7097,19 +7863,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();
@@ -7118,10 +7900,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);
@@ -7149,7 +7933,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)}`
+        );
+      }
     }
   }
 };
@@ -7157,16 +7947,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.resolve(process.cwd(), ".wolbarg", "checkpoints");
   }
+  /** Ensure the checkpoint directory exists. */
   async open() {
     fs6.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);
@@ -7192,8 +7994,20 @@ Ensure Wolbarg has been initialized and the database path is correct.`
       );
     }
     const snapshotPath = this.snapshotPath(name);
-    await safeSqliteBackup(resolvedSource, snapshotPath);
-    const stats = fs6.statSync(snapshotPath);
+    const tmpSnapshotPath = `${snapshotPath}.tmp-${Date.now()}`;
+    try {
+      await safeSqliteBackup(resolvedSource, tmpSnapshotPath);
+    } catch (error) {
+      if (fs6.existsSync(tmpSnapshotPath)) {
+        fs6.rmSync(tmpSnapshotPath, { force: true });
+      }
+      throw error;
+    }
+    const stats = fs6.statSync(tmpSnapshotPath);
+    if (fs6.existsSync(snapshotPath)) {
+      fs6.rmSync(snapshotPath, { force: true });
+    }
+    fs6.renameSync(tmpSnapshotPath, snapshotPath);
     const meta2 = {
       name,
       description: options?.description ?? null,
@@ -7204,9 +8018,17 @@ Ensure Wolbarg has been initialized and the database path is correct.`
       sourcePath: resolvedSource,
       sizeBytes: stats.size
     };
-    fs6.writeFileSync(metaPath, JSON.stringify(meta2, null, 2), "utf8");
+    const tmpMetaPath = `${metaPath}.tmp-${Date.now()}`;
+    fs6.writeFileSync(tmpMetaPath, JSON.stringify(meta2, null, 2), "utf8");
+    fs6.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);
@@ -7229,6 +8051,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);
@@ -7244,6 +8067,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.existsSync(this.directory)) {
@@ -7260,6 +8084,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);
@@ -7444,6 +8269,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");
@@ -7454,12 +8286,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();
@@ -7468,6 +8302,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;
@@ -7494,6 +8331,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) {
@@ -7552,6 +8403,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) {
@@ -7573,6 +8430,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);
@@ -7582,7 +8440,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;
@@ -7598,6 +8463,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(
@@ -7673,7 +8539,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 {
@@ -7695,7 +8571,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 {
@@ -7821,7 +8705,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");
@@ -7891,10 +8783,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");
@@ -7961,10 +8860,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;
@@ -7993,6 +8900,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) {
@@ -8218,6 +9126,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(
@@ -8420,17 +9339,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(
@@ -8465,14 +9404,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;
       }
@@ -8501,7 +9442,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) => ({
@@ -8533,7 +9474,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 {
@@ -8567,10 +9514,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 {
@@ -8610,31 +9568,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,
@@ -8656,6 +9617,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 {
@@ -8826,8 +9797,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");
@@ -8857,8 +9834,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");
@@ -8866,8 +9848,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,
@@ -8880,6 +9877,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 {
@@ -8944,6 +9949,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 {
@@ -8971,6 +9983,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 {
@@ -8998,6 +10015,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 {
@@ -9026,7 +10050,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 {
@@ -9036,7 +10069,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.existsSync(sidecar)) {
+          fs6.rmSync(sidecar, { recursive: true, force: true });
+        }
+        throw error;
+      }
       trace.mark("databaseWriteMs", performance.now() - tCheckpoint);
       trace.success({
         provider: provider.name,
@@ -9049,7 +10090,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;
@@ -9095,13 +10141,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.existsSync(sidecar)) {
+          fs6.rmSync(sidecar, { recursive: true, force: true });
+        }
+      }
       trace.mark("databaseWriteMs", performance.now() - tDelete);
       trace.success({
         provider: provider.name,
@@ -9114,6 +10173,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 {
@@ -9132,6 +10196,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 {
@@ -9151,7 +10221,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 {
@@ -9163,7 +10239,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({
@@ -9180,22 +10258,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) {
@@ -9225,11 +10314,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;
   }
@@ -9244,6 +10339,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);
@@ -9268,9 +10369,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) {
@@ -9284,6 +10387,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(
@@ -9291,6 +10395,7 @@ var Wolbarg = class {
       );
     }
   }
+  /** Return the configured checkpoint provider or throw {@link ProviderNotConfiguredError}. */
   requireCheckpointProvider() {
     if (!this.checkpointProvider) {
       throw new ProviderNotConfiguredError(
@@ -9301,6 +10406,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(
@@ -9311,20 +10417,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()) {
@@ -9363,6 +10473,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()) {
@@ -9386,22 +10497,32 @@ var Wolbarg = class {
       fs6.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:).",
@@ -9444,6 +10565,7 @@ function commonTags(metadata) {
 
 // src/filters/types.ts
 var meta = {
+  /** Field equals value (strict equality). */
   eq: (field, value) => ({
     field,
     op: { eq: value }
@@ -9527,16 +10649,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 [];
@@ -9630,7 +10759,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,
@@ -9815,21 +10951,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();
       }
     }
   };
@@ -9972,6 +11118,6 @@ function percentile(sorted, p) {
   return sorted[idx];
 }
 
-export { CompressionError, ConfigurationError, DatabaseError, EmbeddingError, FixedChunkingStrategy, GraphCheckpointNotSupportedError, HeadingChunkingStrategy, InitializationError, LlmCompressionProvider, MarkdownChunkingStrategy, MemoryNotFoundError, Neo4jGraphProvider, NoopTelemetryProvider, ParagraphChunkingStrategy, PostgresStorageProvider, ProviderNotConfiguredError, SDK_VERSION, SentenceChunkingStrategy, SqliteCheckpointProvider, SqliteDatabaseProvider, SqliteEventDatabase, SqliteGraphProvider, SqliteStorageProvider, SqliteTelemetryProvider, StorageLockedError, TelemetryEmitter, ValidationError, Wolbarg, WolbargError, WolbargLogger, bgeReranker, bm25, cohereReranker, createChunkingStrategy, createCompressionProvider, createDatabaseProvider, createEmbeddingProvider, createLlmProvider, createStorageProvider, createTelemetryProvider, wolbarg2 as createWolbarg, crossEncoder, geminiEmbedding, geminiVision, jinaReranker, lmStudioEmbedding, meta, neo4jGraph, ollamaEmbedding, ollamaLlm, openRouterEmbedding, openRouterLlm, openaiCompatibleEmbedding, openaiCompatibleLlm, openaiEmbedding, openaiLlm, openaiReranker, openaiVision, postgres, postgresConfig, runBenchmark, sqlite, sqliteCheckpoint, sqliteConfig, sqliteGraph, sqliteTelemetry, summarizeBenchmark, tesseract, togetherEmbedding, vllmEmbedding, wolbarg, wrapOperationError };
+export { CompressionError, ConfigurationError, DatabaseError, EmbeddingError, FixedChunkingStrategy, GraphCheckpointNotSupportedError, HeadingChunkingStrategy, InitializationError, LlmCompressionProvider, MarkdownChunkingStrategy, MemoryNotFoundError, Neo4jGraphProvider, NoopTelemetryProvider, ParagraphChunkingStrategy, PostgresStorageProvider, ProviderNotConfiguredError, SDK_VERSION, SentenceChunkingStrategy, SqliteCheckpointProvider, SqliteDatabaseProvider, SqliteEventDatabase, SqliteGraphProvider, SqliteStorageProvider, SqliteTelemetryProvider, StorageLockedError, TelemetryEmitter, ValidationError, Wolbarg, WolbargError, WolbargLogger, bgeReranker, bm25, cohereReranker, createChunkingStrategy, createCompressionProvider, createDatabaseProvider, createEmbeddingProvider, createLlmProvider, createStorageProvider, createTelemetryProvider, createWolbarg, crossEncoder, geminiEmbedding, geminiVision, jinaReranker, lmStudioEmbedding, meta, neo4jGraph, ollamaEmbedding, ollamaLlm, openRouterEmbedding, openRouterLlm, openaiCompatibleEmbedding, openaiCompatibleLlm, openaiEmbedding, openaiLlm, openaiReranker, openaiVision, postgres, postgresConfig, runBenchmark, sqlite, sqliteCheckpoint, sqliteConfig, sqliteGraph, sqliteTelemetry, summarizeBenchmark, tesseract, togetherEmbedding, vllmEmbedding, wolbarg, wrapOperationError };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map