wolbarg 0.3.0 → 0.3.2

package/dist/index.js

@@ -1,17 +1,25 @@
+import path5 from "node:path";
 import fs from 'fs/promises';
-import path2 from "node:path";
-import fs2 from "node:fs";
+import fs5 from "node:fs";
 import { DatabaseSync } from "node:sqlite";
 import * as sqliteVec from 'sqlite-vec';
 import { AsyncLocalStorage } from 'async_hooks';
 
+// src/core/wolbarg.ts
+
 // src/errors/index.ts
 var WolbargError = class extends Error {
   code;
+  reason;
+  suggestion;
+  operation;
   constructor(message, code, options) {
     super(message, options);
     this.name = "WolbargError";
     this.code = code;
+    this.reason = options?.reason;
+    this.suggestion = options?.suggestion;
+    this.operation = options?.operation;
     Object.setPrototypeOf(this, new.target.prototype);
   }
 };
@@ -60,13 +68,58 @@ var MemoryNotFoundError = class extends WolbargError {
 var ProviderNotConfiguredError = class extends ConfigurationError {
   provider;
   constructor(provider, method, hint) {
-    super(
-      `${method} requires ${provider} \u2014 ${hint}`
-    );
+    super(`${method} requires ${provider} \u2014 ${hint}`, {
+      operation: method,
+      reason: `${provider} was not configured`,
+      suggestion: hint
+    });
     this.name = "ProviderNotConfiguredError";
     this.provider = provider;
   }
 };
+function wrapOperationError(operation, error) {
+  if (error instanceof WolbargError) {
+    return error;
+  }
+  const raw = error instanceof Error ? error.message : String(error);
+  const lower = raw.toLowerCase();
+  if (lower.includes("database is locked") || lower.includes("sqlite_busy")) {
+    return new DatabaseError(formatOperationMessage(operation, raw), {
+      cause: error instanceof Error ? error : void 0,
+      operation,
+      reason: "SQLite database locked",
+      suggestion: "Increase timeout or reduce concurrent writes."
+    });
+  }
+  if (lower.includes("no such file") || lower.includes("enoent")) {
+    return new DatabaseError(formatOperationMessage(operation, raw), {
+      cause: error instanceof Error ? error : void 0,
+      operation,
+      reason: "Database file not found",
+      suggestion: "Check the database path and ensure the directory exists."
+    });
+  }
+  if (lower.includes("readonly") || lower.includes("read-only")) {
+    return new DatabaseError(formatOperationMessage(operation, raw), {
+      cause: error instanceof Error ? error : void 0,
+      operation,
+      reason: "Database opened as read-only",
+      suggestion: "Open the database with write permissions or choose another path."
+    });
+  }
+  return new DatabaseError(formatOperationMessage(operation, raw), {
+    cause: error instanceof Error ? error : void 0,
+    operation,
+    reason: raw,
+    suggestion: "Inspect the underlying cause and retry the operation."
+  });
+}
+function formatOperationMessage(operation, reason) {
+  const reasonText = typeof reason === "string" ? reason : reason.reason ?? reason.message;
+  return `Failed to execute ${operation}()
+Reason:
+${reasonText}`;
+}
 
 // src/compression/index.ts
 var SYSTEM_PROMPT = `You are a memory compression engine for multi-agent systems.
@@ -324,9 +377,9 @@ var AsyncMutex = class {
     }
   }
 };
-function joinUrl(baseUrl, path3) {
+function joinUrl(baseUrl, path7) {
   const base = baseUrl.replace(/\/+$/, "");
-  const suffix = path3.startsWith("/") ? path3 : `/${path3}`;
+  const suffix = path7.startsWith("/") ? path7 : `/${path7}`;
   return `${base}${suffix}`;
 }
 
@@ -623,7 +676,7 @@ function extOf(filename) {
   if (!filename) {
     return "";
   }
-  return path2.extname(filename).toLowerCase();
+  return path5.extname(filename).toLowerCase();
 }
 var TextParser = class {
   name = "text";
@@ -768,13 +821,31 @@ async function loadIngestSource(source) {
     const buffer = await fs.readFile(source.path);
     return {
       buffer,
-      filename: path2.basename(source.path),
+      filename: path5.basename(source.path),
       mimeType: source.mimeType
     };
   }
   throw new ConfigurationError("ingest source must include path, buffer, or text");
 }
 
+// src/core/options.ts
+function isEmbeddingProvider(value) {
+  return typeof value.embed === "function";
+}
+function isLlmProvider(value) {
+  return typeof value.complete === "function";
+}
+function isStorageProvider(value) {
+  return typeof value.open === "function";
+}
+function isTelemetryProvider(value) {
+  return typeof value.emit === "function";
+}
+function resolveDatabaseUrl(config) {
+  const url = "url" in config && config.url || "connectionString" in config && config.connectionString || "";
+  return typeof url === "string" ? url : "";
+}
+
 // src/filters/match.ts
 function getField(metadata, field) {
   const parts = field.split(".");
@@ -1256,12 +1327,16 @@ var SqliteStorageProvider = class {
   constructor(options) {
     this.connectionString = options.connectionString;
   }
+  /** Absolute or relative path / `:memory:` used by this provider. */
+  get path() {
+    return this.connectionString;
+  }
   async open() {
     try {
       const dbPath = this.resolvePath(this.connectionString);
       this.resolvedPath = dbPath;
       if (dbPath !== ":memory:") {
-        fs2.mkdirSync(path2.dirname(dbPath), { recursive: true });
+        fs5.mkdirSync(path5.dirname(dbPath), { recursive: true });
       }
       const db = new DatabaseSync(dbPath, { allowExtension: true });
       this.db = db;
@@ -1722,11 +1797,11 @@ var SqliteStorageProvider = class {
     }
     const dbPath = this.resolvedPath ?? this.resolvePath(this.connectionString);
     try {
-      let total = fs2.statSync(dbPath).size;
+      let total = fs5.statSync(dbPath).size;
       for (const suffix of ["-wal", "-shm"]) {
         const side = `${dbPath}${suffix}`;
-        if (fs2.existsSync(side)) {
-          total += fs2.statSync(side).size;
+        if (fs5.existsSync(side)) {
+          total += fs5.statSync(side).size;
         }
       }
       return total;
@@ -2057,7 +2132,7 @@ var SqliteStorageProvider = class {
     if (connectionString === ":memory:") {
       return ":memory:";
     }
-    return path2.isAbsolute(connectionString) ? connectionString : path2.resolve(process.cwd(), connectionString);
+    return path5.isAbsolute(connectionString) ? connectionString : path5.resolve(process.cwd(), connectionString);
   }
   requireDb() {
     if (!this.db) {
@@ -3121,14 +3196,20 @@ var PostgresStorageProvider = class {
 
 // src/storage/index.ts
 function createStorageProvider(config) {
+  const connectionString = resolveDatabaseUrl(config);
+  if (!connectionString) {
+    throw new ConfigurationError(
+      "database.url or database.connectionString is required"
+    );
+  }
   if (config.provider === "sqlite") {
     return new SqliteStorageProvider({
-      connectionString: config.connectionString
+      connectionString
     });
   }
   if (config.provider === "postgres") {
     return new PostgresStorageProvider({
-      connectionString: config.connectionString,
+      connectionString,
       maxPoolSize: config.maxPoolSize
     });
   }
@@ -3139,6 +3220,129 @@ function createStorageProvider(config) {
 function createDatabaseProvider(config) {
   return createStorageProvider(config);
 }
+var SDK_VERSION = "0.3.0";
+var SqliteMemoryTransferProvider = class {
+  async exportTo(exportPath, sourcePath, organization) {
+    const resolvedSource = resolvePath(sourcePath);
+    if (resolvedSource === ":memory:") {
+      throw new ConfigurationError(
+        "Cannot export an in-memory database. Use a file-backed SQLite database."
+      );
+    }
+    if (!fs5.existsSync(resolvedSource)) {
+      throw new DatabaseError(
+        `Failed to execute export()
+Reason:
+Source database not found at ${resolvedSource}
+Suggestion:
+Initialize Wolbarg and verify the database path.`
+      );
+    }
+    const resolvedExport = resolvePath(exportPath);
+    fs5.mkdirSync(path5.dirname(resolvedExport), { recursive: true });
+    const dbExportPath = resolvedExport.endsWith(".db") ? resolvedExport : `${resolvedExport}.db`;
+    const manifestPath = `${dbExportPath}.manifest.json`;
+    await copySqlite(resolvedSource, dbExportPath);
+    const manifest = {
+      format: "wolbarg-export-v1",
+      exportedAt: nowIso(),
+      sdkVersion: SDK_VERSION,
+      provider: "sqlite",
+      sourcePath: resolvedSource,
+      organization
+    };
+    fs5.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2), "utf8");
+    return {
+      path: dbExportPath,
+      manifest,
+      sizeBytes: fs5.statSync(dbExportPath).size
+    };
+  }
+  async importFrom(exportPath, targetPath) {
+    const resolvedExport = resolvePath(exportPath);
+    const dbExportPath = resolvedExport.endsWith(".db") ? resolvedExport : fs5.existsSync(`${resolvedExport}.db`) ? `${resolvedExport}.db` : resolvedExport;
+    if (!fs5.existsSync(dbExportPath)) {
+      throw new ValidationError(
+        `Failed to execute import()
+Reason:
+Export file not found at ${dbExportPath}
+Suggestion:
+Pass the path returned by export().`
+      );
+    }
+    const manifestPath = `${dbExportPath}.manifest.json`;
+    let manifest;
+    if (fs5.existsSync(manifestPath)) {
+      manifest = JSON.parse(fs5.readFileSync(manifestPath, "utf8"));
+      if (manifest.format !== "wolbarg-export-v1") {
+        throw new ValidationError(
+          `Unsupported export format: ${String(manifest.format)}`
+        );
+      }
+    } else {
+      manifest = {
+        format: "wolbarg-export-v1",
+        exportedAt: nowIso(),
+        sdkVersion: SDK_VERSION,
+        provider: "sqlite",
+        sourcePath: dbExportPath
+      };
+    }
+    const resolvedTarget = resolvePath(targetPath);
+    if (resolvedTarget === ":memory:") {
+      throw new ConfigurationError("Cannot import into an in-memory database.");
+    }
+    for (const suffix of ["", "-wal", "-shm"]) {
+      const side = `${resolvedTarget}${suffix}`;
+      if (fs5.existsSync(side)) {
+        fs5.rmSync(side, { force: true });
+      }
+    }
+    await copySqlite(dbExportPath, resolvedTarget);
+    return { path: resolvedTarget, manifest };
+  }
+};
+async function copySqlite(sourcePath, destPath) {
+  fs5.mkdirSync(path5.dirname(destPath), { recursive: true });
+  let source = null;
+  let dest = null;
+  try {
+    source = new DatabaseSync(sourcePath);
+    try {
+      source.exec("PRAGMA wal_checkpoint(TRUNCATE);");
+    } catch {
+    }
+    dest = new DatabaseSync(destPath);
+    const backupFn = source.backup;
+    if (typeof backupFn === "function") {
+      await backupFn.call(source, dest);
+    } else {
+      source.close();
+      source = null;
+      dest.close();
+      dest = null;
+      fs5.copyFileSync(sourcePath, destPath);
+    }
+  } catch (error) {
+    throw new DatabaseError(
+      `SQLite transfer failed: ${error instanceof Error ? error.message : String(error)}`,
+      { cause: error instanceof Error ? error : void 0 }
+    );
+  } finally {
+    try {
+      source?.close();
+    } catch {
+    }
+    try {
+      dest?.close();
+    } catch {
+    }
+  }
+}
+function resolvePath(p) {
+  if (p === ":memory:") return ":memory:";
+  return path5.isAbsolute(p) ? p : path5.resolve(process.cwd(), p);
+}
 
 // src/memory/index.ts
 function toMemoryRecord(row) {
@@ -3264,17 +3468,6 @@ function adaptiveFetchK(topK, overFetchFactor, hasFilters) {
   return Math.min(Math.max(Math.ceil(topK * factor), topK), 1e3);
 }
 
-// src/core/options.ts
-function isEmbeddingProvider(value) {
-  return typeof value.embed === "function";
-}
-function isLlmProvider(value) {
-  return typeof value.complete === "function";
-}
-function isStorageProvider(value) {
-  return typeof value.open === "function";
-}
-
 // src/core/validate.ts
 function assertNonEmpty(value, fieldName) {
   if (typeof value !== "string" || value.trim().length === 0) {
@@ -3327,6 +3520,64 @@ function validateLlmConfig(config) {
     ...config.timeoutMs !== void 0 ? { timeoutMs: config.timeoutMs } : {}
   };
 }
+function normalizeDatabaseConfig(config) {
+  const provider = config.provider;
+  if (provider !== "sqlite" && provider !== "postgres") {
+    throw new ConfigurationError(
+      `Unsupported database provider "${String(config.provider)}". Supported: "sqlite", "postgres".`
+    );
+  }
+  const connectionString = resolveDatabaseUrl(config).trim();
+  assertNonEmpty(connectionString, "database.url / database.connectionString");
+  if (provider === "postgres") {
+    return {
+      provider: "postgres",
+      connectionString,
+      url: connectionString,
+      ..."maxPoolSize" in config && config.maxPoolSize !== void 0 ? { maxPoolSize: config.maxPoolSize } : {}
+    };
+  }
+  return {
+    provider: "sqlite",
+    connectionString,
+    url: connectionString
+  };
+}
+function validateTelemetryConfig(config) {
+  if (!config.database || typeof config.database !== "object") {
+    throw new ConfigurationError("telemetry.database is required when telemetry is enabled");
+  }
+  if (config.database.provider !== "sqlite") {
+    throw new ConfigurationError(
+      `Unsupported telemetry provider "${config.database.provider}". Only "sqlite" is implemented in v0.3.0; PostgreSQL will be added later without changing application code.`,
+      {
+        reason: `provider=${config.database.provider}`,
+        suggestion: 'Use telemetry: { database: { provider: "sqlite", url: "./telemetry.db" } }'
+      }
+    );
+  }
+  const url = config.database.url?.trim() || config.database.connectionString?.trim() || "";
+  assertNonEmpty(url, "telemetry.database.url");
+  const level = config.level ?? "info";
+  const allowed = /* @__PURE__ */ new Set(["off", "error", "warn", "info", "debug", "trace"]);
+  if (!allowed.has(level)) {
+    throw new ConfigurationError(`Invalid telemetry.level "${level}"`);
+  }
+  return {
+    enabled: config.enabled ?? true,
+    database: {
+      provider: "sqlite",
+      url,
+      connectionString: url
+    },
+    level,
+    captureQueries: config.captureQueries ?? true,
+    captureLatency: config.captureLatency ?? true,
+    captureErrors: config.captureErrors ?? true,
+    captureSimilarity: config.captureSimilarity ?? true,
+    captureEmbeddings: config.captureEmbeddings ?? false
+  };
+}
 function validateInitOptions(options) {
   if (options === null || typeof options !== "object") {
     throw new ConfigurationError("init options must be an object");
@@ -3335,16 +3586,7 @@ function validateInitOptions(options) {
   if (!options.database || typeof options.database !== "object") {
     throw new ConfigurationError("database configuration is required");
   }
-  const provider = options.database.provider;
-  if (provider !== "sqlite" && provider !== "postgres") {
-    throw new ConfigurationError(
-      `Unsupported database provider "${String(options.database.provider)}". Supported: "sqlite", "postgres".`
-    );
-  }
-  assertNonEmpty(
-    options.database.connectionString,
-    "database.connectionString"
-  );
+  const database = normalizeDatabaseConfig(options.database);
   if (!options.embedding || typeof options.embedding !== "object") {
     throw new ConfigurationError("embedding configuration is required");
   }
@@ -3352,31 +3594,32 @@ function validateInitOptions(options) {
   const llm = options.llm ? validateLlmConfig(options.llm) : void 0;
   return {
     organization: options.organization.trim(),
-    database: provider === "postgres" ? {
-      provider: "postgres",
-      connectionString: options.database.connectionString.trim(),
-      ..."maxPoolSize" in options.database && options.database.maxPoolSize !== void 0 ? { maxPoolSize: options.database.maxPoolSize } : {}
-    } : {
-      provider: "sqlite",
-      connectionString: options.database.connectionString.trim()
-    },
+    database,
     embedding,
     ...llm ? { llm } : {}
   };
 }
+function resolveStorageInput(options) {
+  if (options.storage && options.database) {
+    throw new ConfigurationError(
+      "Pass either storage or database, not both"
+    );
+  }
+  const input = options.storage ?? options.database;
+  if (!input) {
+    throw new ConfigurationError("storage or database is required");
+  }
+  return input;
+}
 function validateWolbargOptions(options) {
   if (options === null || typeof options !== "object") {
     throw new ConfigurationError("Wolbarg options must be an object");
   }
   assertNonEmpty(options.organization, "organization");
-  if (!options.storage) {
-    throw new ConfigurationError("storage is required");
-  }
-  if (!isStorageProvider(options.storage)) {
-    if (typeof options.storage !== "object" || !("provider" in options.storage) || !("connectionString" in options.storage)) {
-      throw new ConfigurationError("storage must be a provider instance or config");
-    }
-    assertNonEmpty(options.storage.connectionString, "storage.connectionString");
+  const storageInput = resolveStorageInput(options);
+  let storage = storageInput;
+  if (!isStorageProvider(storageInput)) {
+    storage = normalizeDatabaseConfig(storageInput);
   }
   if (!options.embedding) {
     throw new ConfigurationError("embedding is required");
@@ -3387,82 +3630,1010 @@ function validateWolbargOptions(options) {
   if (options.llm !== void 0 && !isLlmProvider(options.llm)) {
     validateLlmConfig(options.llm);
   }
+  let telemetry = options.telemetry;
+  if (telemetry && !isTelemetryProvider(telemetry)) {
+    telemetry = validateTelemetryConfig(telemetry);
+  }
   return {
     ...options,
-    organization: options.organization.trim()
+    organization: options.organization.trim(),
+    storage,
+    database: void 0,
+    ...telemetry ? { telemetry } : {}
   };
 }
 
-// src/core/wolbarg.ts
-var Wolbarg = class {
-  initialized = false;
-  booting = null;
-  organization = null;
-  storage = null;
-  embedding = null;
-  llm = null;
-  compression = null;
-  reranker = null;
-  keywordSearch = null;
-  ocr = null;
-  vision = null;
-  chunking = null;
-  retrievalConfig = {};
-  embeddingDimensions = null;
-  writeMutex = new AsyncMutex();
-  constructor(options) {
-    if (!options) {
+// 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;
     }
-    const validated = validateWolbargOptions(options);
-    this.organization = validated.organization;
-    this.storage = isStorageProvider(validated.storage) ? validated.storage : createStorageProvider(validated.storage);
-    this.embedding = isEmbeddingProvider(validated.embedding) ? validated.embedding : createEmbeddingProvider(validated.embedding);
-    if (validated.llm) {
-      this.llm = isLlmProvider(validated.llm) ? validated.llm : createLlmProvider(validated.llm);
-      this.compression = validated.compression ?? createCompressionProvider(this.llm);
+    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 {
-      this.compression = validated.compression ?? null;
+      console.log(line, extra ?? "");
     }
-    this.reranker = validated.reranker ?? null;
-    this.keywordSearch = validated.keywordSearch ?? null;
-    this.ocr = validated.ocr ?? null;
-    this.vision = validated.vision ?? null;
-    this.chunking = validated.chunking ?? null;
-    this.retrievalConfig = validated.retrieval ?? {};
   }
-  /**
-   * Backwards-compatible initialization (v0.1 API).
-   * Prefer the constructor with `storage` / `embedding` / optional `llm`.
-   */
-  async init(options) {
-    if (this.initialized || this.storage) {
-      throw new InitializationError("Wolbarg is already initialized");
+};
+
+// src/telemetry/trace.ts
+function createSessionId() {
+  return createId();
+}
+function createTraceId() {
+  return createId();
+}
+function createRootTrace(sessionId) {
+  return {
+    sessionId,
+    traceId: createTraceId(),
+    parentTraceId: null
+  };
+}
+function createChildTrace(parent) {
+  return {
+    sessionId: parent.sessionId,
+    traceId: createTraceId(),
+    parentTraceId: parent.traceId
+  };
+}
+
+// src/telemetry/emitter.ts
+var NoopTelemetryProvider = class {
+  name = "noop";
+  async open() {
+  }
+  async close() {
+  }
+  emit(_event) {
+  }
+  async flush() {
+  }
+};
+var TelemetryEmitter = class {
+  sessionId;
+  logger;
+  provider;
+  config;
+  context;
+  constructor(provider, config, context = {}) {
+    this.sessionId = createSessionId();
+    this.provider = provider ?? new NoopTelemetryProvider();
+    this.config = {
+      enabled: config?.enabled ?? Boolean(provider),
+      level: config?.level ?? "info",
+      captureQueries: config?.captureQueries ?? true,
+      captureLatency: config?.captureLatency ?? true,
+      captureErrors: config?.captureErrors ?? true,
+      captureSimilarity: config?.captureSimilarity ?? true,
+      captureEmbeddings: config?.captureEmbeddings ?? false
+    };
+    this.context = context;
+    this.logger = new WolbargLogger(this.config.level);
+  }
+  get enabled() {
+    return this.config.enabled && this.provider.name !== "noop";
+  }
+  setProvider(provider) {
+    this.provider = provider;
+  }
+  async open() {
+    if (!this.config.enabled) {
+      return;
     }
-    let validated;
+    await this.provider.open();
+  }
+  async close() {
+    await this.provider.flush();
+    await this.provider.close();
+  }
+  async flush() {
+    await this.provider.flush();
+  }
+  start(operation, parent) {
+    const context = parent ? createChildTrace(parent) : createRootTrace(this.sessionId);
+    const startedAt = performance.now();
+    const latency = {};
+    const spans = [];
+    const self = this;
+    const finish = (status, fields, error) => {
+      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 (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(),
+        operation,
+        status,
+        sessionId: context.sessionId,
+        traceId: context.traceId,
+        parentTraceId: context.parentTraceId,
+        organization: fields?.organization ?? self.context.organization ?? null,
+        agentId: fields?.agentId ?? null,
+        tags: fields?.tags ?? null,
+        checkpointId: fields?.checkpointId ?? null,
+        durationMs: totalMs,
+        provider: fields?.provider ?? null,
+        query: self.config.captureQueries ? fields?.query ?? null : null,
+        filters: fields?.filters ?? null,
+        returnedCount: fields?.returnedCount ?? null,
+        memoryIds: fields?.memoryIds ?? null,
+        similarityScores: self.config.captureSimilarity ? fields?.similarityScores ?? null : null,
+        metadata: fields?.metadata ?? null,
+        embeddingProvider: fields?.embeddingProvider ?? null,
+        model: fields?.model ?? null,
+        error: self.config.captureErrors ? errMessage : null,
+        errorStack: self.config.captureErrors ? errStack : null,
+        userMetadata: fields?.userMetadata ?? null,
+        extra: fields?.extra ?? null,
+        latency: self.config.captureLatency ? { ...latency, totalMs, ...fields?.latency ?? {} } : { totalMs },
+        explain: fields?.explain ?? null,
+        spans: self.config.captureLatency ? [...spans, ...fields?.spans ?? []] : null
+      };
+      self.provider.emit(event);
+    };
+    return {
+      context,
+      startedAt,
+      latency,
+      child(childOp) {
+        return self.start(childOp, context);
+      },
+      mark(stage, ms) {
+        latency[stage] = ms;
+        const elapsed = performance.now() - startedAt;
+        spans.push({
+          name: stage,
+          startMs: Math.max(0, elapsed - ms),
+          durationMs: ms
+        });
+      },
+      success(fields) {
+        finish("ok", fields);
+      },
+      failure(error, fields) {
+        finish("error", fields, error);
+      }
+    };
+  }
+  emitStartup(provider) {
+    const trace = this.start("startup");
+    trace.success({ provider });
+  }
+  emitShutdown(provider) {
+    const trace = this.start("shutdown");
+    trace.success({ provider });
+  }
+};
+var SCHEMA_SQL = `
+CREATE TABLE IF NOT EXISTS telemetry_events (
+  id TEXT PRIMARY KEY,
+  timestamp TEXT NOT NULL,
+  operation TEXT NOT NULL,
+  provider TEXT,
+  duration_ms REAL,
+  status TEXT NOT NULL,
+  query TEXT,
+  filters_json TEXT,
+  returned_count INTEGER,
+  memory_ids_json TEXT,
+  similarity_scores_json TEXT,
+  metadata_json TEXT,
+  embedding_provider TEXT,
+  model TEXT,
+  error TEXT,
+  error_stack TEXT,
+  session_id TEXT NOT NULL,
+  trace_id TEXT NOT NULL,
+  parent_trace_id TEXT,
+  user_metadata_json TEXT,
+  extra_json TEXT,
+  latency_json TEXT,
+  organization TEXT,
+  agent_id TEXT,
+  tags_json TEXT,
+  checkpoint_id TEXT,
+  explain_json TEXT,
+  spans_json TEXT
+);
+
+CREATE INDEX IF NOT EXISTS idx_telemetry_timestamp ON telemetry_events(timestamp);
+CREATE INDEX IF NOT EXISTS idx_telemetry_operation ON telemetry_events(operation);
+CREATE INDEX IF NOT EXISTS idx_telemetry_trace ON telemetry_events(trace_id);
+CREATE INDEX IF NOT EXISTS idx_telemetry_session ON telemetry_events(session_id);
+CREATE INDEX IF NOT EXISTS idx_telemetry_status ON telemetry_events(status);
+`;
+var V2_COLUMNS = {
+  organization: "TEXT",
+  agent_id: "TEXT",
+  tags_json: "TEXT",
+  checkpoint_id: "TEXT",
+  explain_json: "TEXT",
+  spans_json: "TEXT"
+};
+var V2_INDEXES_SQL = `
+CREATE INDEX IF NOT EXISTS idx_telemetry_agent ON telemetry_events(agent_id);
+CREATE INDEX IF NOT EXISTS idx_telemetry_org ON telemetry_events(organization);
+CREATE INDEX IF NOT EXISTS idx_telemetry_checkpoint ON telemetry_events(checkpoint_id);
+CREATE INDEX IF NOT EXISTS idx_telemetry_operation_time ON telemetry_events(operation, timestamp);
+CREATE INDEX IF NOT EXISTS idx_telemetry_status_time ON telemetry_events(status, timestamp);
+`;
+var SqliteEventDatabase = class {
+  name = "sqlite";
+  url;
+  readonly;
+  db = null;
+  insertStmt = null;
+  columns = /* @__PURE__ */ new Set();
+  constructor(options) {
+    this.url = options.url;
+    this.readonly = options.readonly ?? false;
+  }
+  async open() {
     try {
-      validated = validateInitOptions(options);
+      const dbPath = this.resolvePath(this.url);
+      if (dbPath !== ":memory:" && !this.readonly) {
+        fs5.mkdirSync(path5.dirname(dbPath), { recursive: true });
+      }
+      const db = new DatabaseSync(dbPath, {
+        allowExtension: false,
+        readOnly: this.readonly
+      });
+      this.db = db;
+      if (!this.readonly) {
+        db.exec("PRAGMA journal_mode = WAL;");
+        db.exec(`
+          PRAGMA synchronous = NORMAL;
+          PRAGMA busy_timeout = 5000;
+          PRAGMA temp_store = MEMORY;
+        `);
+        db.exec(SCHEMA_SQL);
+        this.migrateToV2(db);
+      }
+      this.columns = readColumns(db);
+      if (!this.readonly) {
+        this.insertStmt = db.prepare(`
+          INSERT INTO telemetry_events (
+            id, timestamp, operation, provider, duration_ms, status,
+            query, filters_json, returned_count, memory_ids_json,
+            similarity_scores_json, metadata_json, embedding_provider, model,
+            error, error_stack, session_id, trace_id, parent_trace_id,
+            user_metadata_json, extra_json, latency_json, organization,
+            agent_id, tags_json, checkpoint_id, explain_json, spans_json
+          ) VALUES (
+            ?, ?, ?, ?, ?, ?,
+            ?, ?, ?, ?,
+            ?, ?, ?, ?,
+            ?, ?, ?, ?, ?,
+            ?, ?, ?, ?,
+            ?, ?, ?, ?, ?
+          )
+        `);
+      }
     } catch (error) {
-      if (error instanceof ConfigurationError || error instanceof ValidationError) {
-        throw error;
+      try {
+        this.db?.close();
+      } catch {
       }
-      throw new ConfigurationError(
-        `Invalid configuration: ${error instanceof Error ? error.message : String(error)}`,
+      this.db = null;
+      this.columns.clear();
+      throw new InitializationError(
+        `Failed to open telemetry EventDatabase: ${describe(error)}`,
         { cause: error instanceof Error ? error : void 0 }
       );
     }
-    this.organization = validated.organization;
-    this.storage = createStorageProvider(validated.database);
-    this.embedding = createEmbeddingProvider(validated.embedding);
-    if (validated.llm) {
-      this.llm = createLlmProvider(validated.llm);
-      this.compression = createCompressionProvider(this.llm);
-    }
-    await this.ready();
   }
-  /** Ensure storage is open and embedding dimensions are known. */
-  async ready() {
-    if (this.initialized) {
+  async close() {
+    if (!this.db) return;
+    try {
+      this.db.close();
+    } finally {
+      this.db = null;
+      this.insertStmt = null;
+      this.columns.clear();
+    }
+  }
+  async insertEvent(input) {
+    const event = normalizeEvent(input);
+    const stmt = this.insertStmt;
+    if (!stmt) {
+      throw new DatabaseError("Telemetry EventDatabase is not open for writes");
+    }
+    try {
+      stmt.run(
+        event.id,
+        event.timestamp,
+        event.operation,
+        event.provider,
+        event.durationMs,
+        event.status,
+        event.query,
+        jsonOrNull(event.filters),
+        event.returnedCount,
+        jsonOrNull(event.memoryIds),
+        jsonOrNull(event.similarityScores),
+        jsonOrNull(event.metadata),
+        event.embeddingProvider,
+        event.model,
+        event.error,
+        event.errorStack,
+        event.sessionId,
+        event.traceId,
+        event.parentTraceId,
+        jsonOrNull(event.userMetadata),
+        jsonOrNull(event.extra),
+        jsonOrNull(event.latency),
+        event.organization,
+        event.agentId,
+        jsonOrNull(event.tags),
+        event.checkpointId,
+        jsonOrNull(event.explain),
+        jsonOrNull(event.spans)
+      );
+      return event;
+    } catch (error) {
+      throw new DatabaseError(
+        `Failed to write telemetry event: ${describe(error)}`,
+        { cause: error instanceof Error ? error : void 0 }
+      );
+    }
+  }
+  async insertEvents(inputs) {
+    const db = this.requireDb();
+    const out = [];
+    db.exec("BEGIN");
+    try {
+      for (const input of inputs) {
+        out.push(await this.insertEvent(input));
+      }
+      db.exec("COMMIT");
+      return out;
+    } catch (error) {
+      try {
+        db.exec("ROLLBACK");
+      } catch {
+      }
+      throw error;
+    }
+  }
+  async query(options) {
+    const db = this.requireDb();
+    const clauses = [];
+    const params = [];
+    if (options.operation) {
+      const ops = Array.isArray(options.operation) ? options.operation : [options.operation];
+      clauses.push(`operation IN (${ops.map(() => "?").join(",")})`);
+      params.push(...ops);
+    }
+    if (options.status) {
+      clauses.push(`status = ?`);
+      params.push(options.status);
+    }
+    if (options.traceId) {
+      clauses.push(`(trace_id = ? OR parent_trace_id = ?)`);
+      params.push(options.traceId, options.traceId);
+    }
+    if (options.sessionId) {
+      clauses.push(`session_id = ?`);
+      params.push(options.sessionId);
+    }
+    this.addOptionalColumnFilter(
+      clauses,
+      params,
+      "organization",
+      options.organization
+    );
+    this.addOptionalColumnFilter(clauses, params, "agent_id", options.agentId);
+    this.addOptionalColumnFilter(
+      clauses,
+      params,
+      "checkpoint_id",
+      options.checkpointId
+    );
+    if (options.tag) {
+      if (this.columns.has("tags_json")) {
+        clauses.push(
+          `EXISTS (SELECT 1 FROM json_each(tags_json) WHERE json_each.value = ?)`
+        );
+        params.push(options.tag);
+      } else {
+        clauses.push("0 = 1");
+      }
+    }
+    if (options.memoryId) {
+      clauses.push(`memory_ids_json LIKE ?`);
+      params.push(`%${options.memoryId}%`);
+    }
+    if (options.queryText) {
+      clauses.push(`query LIKE ?`);
+      params.push(`%${options.queryText}%`);
+    }
+    if (options.since) {
+      clauses.push(`timestamp >= ?`);
+      params.push(options.since);
+    }
+    if (options.until) {
+      clauses.push(`timestamp <= ?`);
+      params.push(options.until);
+    }
+    const where = clauses.length > 0 ? `WHERE ${clauses.join(" AND ")}` : "";
+    const sortCol = options.sortBy === "duration_ms" ? "duration_ms" : "timestamp";
+    const sortDir = options.sortDir === "asc" ? "ASC" : "DESC";
+    const limit = options.limit ?? 50;
+    const offset = options.offset ?? 0;
+    const totalRow = db.prepare(`SELECT COUNT(*) AS c FROM telemetry_events ${where}`).get(...params);
+    const rows = db.prepare(
+      `SELECT * FROM telemetry_events ${where}
+         ORDER BY ${sortCol} ${sortDir}
+         LIMIT ? OFFSET ?`
+    ).all(...params, limit, offset);
+    return {
+      events: rows.map(rowToEvent),
+      total: Number(totalRow.c),
+      limit,
+      offset
+    };
+  }
+  async getEvent(id) {
+    const db = this.requireDb();
+    const row = db.prepare(`SELECT * FROM telemetry_events WHERE id = ?`).get(id);
+    return row ? rowToEvent(row) : null;
+  }
+  async countEvents(filter) {
+    const db = this.requireDb();
+    const clauses = [];
+    const params = [];
+    if (filter?.since) {
+      clauses.push(`timestamp >= ?`);
+      params.push(filter.since);
+    }
+    if (filter?.operation) {
+      clauses.push(`operation = ?`);
+      params.push(filter.operation);
+    }
+    const where = clauses.length ? `WHERE ${clauses.join(" AND ")}` : "";
+    const row = db.prepare(`SELECT COUNT(*) AS c FROM telemetry_events ${where}`).get(...params);
+    return Number(row.c);
+  }
+  requireDb() {
+    if (!this.db) {
+      throw new DatabaseError("Telemetry EventDatabase is not open");
+    }
+    return this.db;
+  }
+  migrateToV2(db) {
+    const columns = readColumns(db);
+    for (const [name, type] of Object.entries(V2_COLUMNS)) {
+      if (!columns.has(name)) {
+        db.exec(`ALTER TABLE telemetry_events ADD COLUMN ${name} ${type};`);
+      }
+    }
+    db.exec(`
+      CREATE TABLE IF NOT EXISTS telemetry_meta (
+        key TEXT PRIMARY KEY,
+        value TEXT NOT NULL
+      );
+      INSERT INTO telemetry_meta(key, value) VALUES ('schema_version', '2')
+      ON CONFLICT(key) DO UPDATE SET value = excluded.value;
+      ${V2_INDEXES_SQL}
+    `);
+  }
+  addOptionalColumnFilter(clauses, params, column, value) {
+    if (!value) return;
+    if (!this.columns.has(column)) {
+      clauses.push("0 = 1");
+      return;
+    }
+    clauses.push(`${column} = ?`);
+    params.push(value);
+  }
+  resolvePath(url) {
+    if (url === ":memory:") return ":memory:";
+    return path5.isAbsolute(url) ? url : path5.resolve(process.cwd(), url);
+  }
+};
+function normalizeEvent(input) {
+  return {
+    id: input.id ?? createId(),
+    timestamp: input.timestamp ?? nowIso(),
+    operation: input.operation,
+    provider: input.provider ?? null,
+    durationMs: input.durationMs ?? null,
+    status: input.status,
+    query: input.query ?? null,
+    filters: input.filters ?? null,
+    returnedCount: input.returnedCount ?? null,
+    memoryIds: input.memoryIds ?? null,
+    similarityScores: input.similarityScores ?? null,
+    metadata: input.metadata ?? null,
+    embeddingProvider: input.embeddingProvider ?? null,
+    model: input.model ?? null,
+    error: input.error ?? null,
+    errorStack: input.errorStack ?? null,
+    sessionId: input.sessionId,
+    traceId: input.traceId,
+    parentTraceId: input.parentTraceId ?? null,
+    organization: input.organization ?? null,
+    agentId: input.agentId ?? null,
+    tags: input.tags ?? null,
+    checkpointId: input.checkpointId ?? null,
+    userMetadata: input.userMetadata ?? null,
+    extra: input.extra ?? null,
+    latency: input.latency ?? null,
+    explain: input.explain ?? null,
+    spans: input.spans ?? null
+  };
+}
+function rowToEvent(row) {
+  return {
+    id: row.id,
+    timestamp: row.timestamp,
+    operation: row.operation,
+    provider: row.provider,
+    durationMs: row.duration_ms,
+    status: row.status,
+    query: row.query,
+    filters: parseJson(row.filters_json),
+    returnedCount: row.returned_count,
+    memoryIds: parseJson(row.memory_ids_json),
+    similarityScores: parseJson(row.similarity_scores_json),
+    metadata: parseJson(row.metadata_json),
+    embeddingProvider: row.embedding_provider,
+    model: row.model,
+    error: row.error,
+    errorStack: row.error_stack,
+    sessionId: row.session_id,
+    traceId: row.trace_id,
+    parentTraceId: row.parent_trace_id,
+    organization: row.organization ?? null,
+    agentId: row.agent_id ?? null,
+    tags: parseJson(row.tags_json ?? null),
+    checkpointId: row.checkpoint_id ?? null,
+    userMetadata: parseJson(row.user_metadata_json),
+    extra: parseJson(row.extra_json),
+    latency: parseJson(row.latency_json),
+    explain: parseJson(
+      row.explain_json ?? null
+    ),
+    spans: parseJson(row.spans_json ?? null)
+  };
+}
+function readColumns(db) {
+  const rows = db.prepare("PRAGMA table_info(telemetry_events)").all();
+  return new Set(rows.map((row) => row.name));
+}
+function jsonOrNull(value) {
+  if (value === void 0 || value === null) return null;
+  return JSON.stringify(value);
+}
+function parseJson(value) {
+  if (!value) return null;
+  try {
+    return JSON.parse(value);
+  } catch {
+    return null;
+  }
+}
+function describe(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+
+// src/providers/sqlite/sqliteTelemetryProvider.ts
+var SqliteTelemetryProvider = class {
+  name = "sqlite";
+  db;
+  queue = [];
+  flushing = null;
+  closed = false;
+  openPromise = null;
+  constructor(options) {
+    this.db = new SqliteEventDatabase({ url: options.url });
+  }
+  async open() {
+    if (!this.openPromise) {
+      this.openPromise = this.db.open();
+    }
+    await this.openPromise;
+    this.closed = false;
+  }
+  async close() {
+    this.closed = true;
+    await this.flush();
+    await this.db.close();
+    this.openPromise = null;
+  }
+  emit(event) {
+    if (this.closed) {
+      return;
+    }
+    this.queue.push(event);
+    void this.scheduleFlush();
+  }
+  async flush() {
+    while (this.queue.length > 0 || this.flushing) {
+      await this.scheduleFlush();
+      if (this.flushing) {
+        await this.flushing;
+      }
+    }
+  }
+  async query(options) {
+    await this.open();
+    return this.db.query(options);
+  }
+  async getEvent(id) {
+    await this.open();
+    return this.db.getEvent(id);
+  }
+  scheduleFlush() {
+    if (this.flushing) {
+      return this.flushing;
+    }
+    this.flushing = this.runFlush().finally(() => {
+      this.flushing = null;
+    });
+    return this.flushing;
+  }
+  async runFlush() {
+    if (this.queue.length === 0) {
+      return;
+    }
+    await this.open();
+    const batch = this.queue.splice(0, this.queue.length);
+    try {
+      if (typeof this.db.insertEvents === "function") {
+        await this.db.insertEvents(batch);
+      } else {
+        for (const event of batch) {
+          await this.db.insertEvent(event);
+        }
+      }
+    } catch {
+    }
+  }
+};
+var SDK_VERSION2 = "0.3.0";
+var SqliteCheckpointProvider = class {
+  name = "sqlite";
+  directory;
+  ready = false;
+  constructor(options) {
+    this.directory = options?.directory ?? path5.resolve(process.cwd(), ".wolbarg", "checkpoints");
+  }
+  async open() {
+    fs5.mkdirSync(this.directory, { recursive: true });
+    this.ready = true;
+  }
+  async close() {
+    this.ready = false;
+  }
+  async checkpoint(name, sourcePath, options) {
+    this.requireReady();
+    assertCheckpointName(name);
+    const metaPath = this.metaPath(name);
+    if (fs5.existsSync(metaPath)) {
+      throw new ValidationError(
+        `Checkpoint "${name}" already exists. Choose a different name \u2014 checkpoints are never overwritten.`
+      );
+    }
+    const resolvedSource = resolveDbPath(sourcePath);
+    if (resolvedSource === ":memory:") {
+      throw new ConfigurationError(
+        "Cannot checkpoint an in-memory database. Use a file-backed SQLite database."
+      );
+    }
+    if (!fs5.existsSync(resolvedSource)) {
+      throw new DatabaseError(
+        `Failed to execute checkpoint()
+Reason:
+Memory database not found at ${resolvedSource}
+Suggestion:
+Ensure Wolbarg has been initialized and the database path is correct.`
+      );
+    }
+    const snapshotPath = this.snapshotPath(name);
+    await safeSqliteBackup(resolvedSource, snapshotPath);
+    const stats = fs5.statSync(snapshotPath);
+    const meta2 = {
+      name,
+      description: options?.description ?? null,
+      createdAt: nowIso(),
+      sdkVersion: SDK_VERSION2,
+      provider: this.name,
+      snapshotPath,
+      sourcePath: resolvedSource,
+      sizeBytes: stats.size
+    };
+    fs5.writeFileSync(metaPath, JSON.stringify(meta2, null, 2), "utf8");
+    return meta2;
+  }
+  async rollback(name, targetPath) {
+    this.requireReady();
+    const meta2 = await this.getCheckpoint(name);
+    if (!meta2) {
+      throw new ValidationError(`Checkpoint "${name}" was not found`);
+    }
+    const resolvedTarget = resolveDbPath(targetPath);
+    if (resolvedTarget === ":memory:") {
+      throw new ConfigurationError(
+        "Cannot rollback into an in-memory database."
+      );
+    }
+    fs5.mkdirSync(path5.dirname(resolvedTarget), { recursive: true });
+    for (const suffix of ["", "-wal", "-shm"]) {
+      const side = `${resolvedTarget}${suffix}`;
+      if (fs5.existsSync(side)) {
+        fs5.rmSync(side, { force: true });
+      }
+    }
+    await safeSqliteBackup(meta2.snapshotPath, resolvedTarget);
+    return meta2;
+  }
+  async deleteCheckpoint(name) {
+    this.requireReady();
+    const metaPath = this.metaPath(name);
+    const snapshotPath = this.snapshotPath(name);
+    let removed = false;
+    if (fs5.existsSync(metaPath)) {
+      fs5.rmSync(metaPath, { force: true });
+      removed = true;
+    }
+    if (fs5.existsSync(snapshotPath)) {
+      fs5.rmSync(snapshotPath, { force: true });
+      removed = true;
+    }
+    return removed;
+  }
+  async listCheckpoints() {
+    this.requireReady();
+    if (!fs5.existsSync(this.directory)) {
+      return [];
+    }
+    const files = fs5.readdirSync(this.directory).filter((f) => f.endsWith(".json"));
+    const out = [];
+    for (const file of files) {
+      try {
+        const raw = fs5.readFileSync(path5.join(this.directory, file), "utf8");
+        out.push(JSON.parse(raw));
+      } catch {
+      }
+    }
+    return out.sort((a, b) => a.createdAt.localeCompare(b.createdAt));
+  }
+  async getCheckpoint(name) {
+    this.requireReady();
+    const metaPath = this.metaPath(name);
+    if (!fs5.existsSync(metaPath)) {
+      return null;
+    }
+    try {
+      return JSON.parse(fs5.readFileSync(metaPath, "utf8"));
+    } catch {
+      return null;
+    }
+  }
+  metaPath(name) {
+    return path5.join(this.directory, `${sanitize(name)}.json`);
+  }
+  snapshotPath(name) {
+    return path5.join(this.directory, `${sanitize(name)}.db`);
+  }
+  requireReady() {
+    if (!this.ready) {
+      throw new DatabaseError(
+        "Checkpoint provider is not open. Call ready() / open first."
+      );
+    }
+  }
+};
+function sanitize(name) {
+  return name.replace(/[^a-zA-Z0-9._-]/g, "_");
+}
+function assertCheckpointName(name) {
+  if (typeof name !== "string" || name.trim().length === 0) {
+    throw new ValidationError("checkpoint name must be a non-empty string");
+  }
+  if (name.length > 128) {
+    throw new ValidationError("checkpoint name must be <= 128 characters");
+  }
+}
+function resolveDbPath(connectionString) {
+  if (connectionString === ":memory:") return ":memory:";
+  return path5.isAbsolute(connectionString) ? connectionString : path5.resolve(process.cwd(), connectionString);
+}
+async function safeSqliteBackup(sourcePath, destPath) {
+  fs5.mkdirSync(path5.dirname(destPath), { recursive: true });
+  if (fs5.existsSync(destPath)) {
+    fs5.rmSync(destPath, { force: true });
+  }
+  let source = null;
+  let dest = null;
+  try {
+    source = new DatabaseSync(sourcePath);
+    try {
+      source.exec("PRAGMA wal_checkpoint(TRUNCATE);");
+    } catch {
+    }
+    dest = new DatabaseSync(destPath);
+    const backupFn = source.backup;
+    if (typeof backupFn === "function") {
+      await backupFn.call(source, dest);
+    } else {
+      source.close();
+      source = null;
+      dest.close();
+      dest = null;
+      fs5.copyFileSync(sourcePath, destPath);
+    }
+  } catch (error) {
+    throw new DatabaseError(
+      `Failed to execute checkpoint()
+Reason:
+${error instanceof Error ? error.message : String(error)}
+Suggestion:
+Ensure no exclusive lock is held and the destination directory is writable.`,
+      { cause: error instanceof Error ? error : void 0 }
+    );
+  } finally {
+    try {
+      source?.close();
+    } catch {
+    }
+    try {
+      dest?.close();
+    } catch {
+    }
+  }
+}
+
+// src/core/wolbarg.ts
+var Wolbarg = class {
+  initialized = false;
+  booting = null;
+  organization = null;
+  storage = null;
+  embedding = null;
+  llm = null;
+  compression = null;
+  reranker = null;
+  keywordSearch = null;
+  ocr = null;
+  vision = null;
+  chunking = null;
+  retrievalConfig = {};
+  embeddingDimensions = null;
+  writeMutex = new AsyncMutex();
+  telemetry;
+  checkpointProvider = null;
+  memoryDbPath = null;
+  transfer = new SqliteMemoryTransferProvider();
+  constructor(options) {
+    this.telemetry = new TelemetryEmitter(null, { enabled: false, level: "off" });
+    if (!options) {
+      return;
+    }
+    const validated = validateWolbargOptions(options);
+    this.organization = validated.organization;
+    const storageInput = validated.storage;
+    this.storage = isStorageProvider(storageInput) ? storageInput : createStorageProvider(storageInput);
+    if (!isStorageProvider(storageInput)) {
+      this.memoryDbPath = resolveDatabaseUrl(storageInput);
+    } else if (storageInput instanceof SqliteStorageProvider) {
+      this.memoryDbPath = storageInput.path;
+    }
+    this.embedding = isEmbeddingProvider(validated.embedding) ? validated.embedding : createEmbeddingProvider(validated.embedding);
+    if (validated.llm) {
+      this.llm = isLlmProvider(validated.llm) ? validated.llm : createLlmProvider(validated.llm);
+      this.compression = validated.compression ?? createCompressionProvider(this.llm);
+    } else {
+      this.compression = validated.compression ?? null;
+    }
+    this.reranker = validated.reranker ?? null;
+    this.keywordSearch = validated.keywordSearch ?? null;
+    this.ocr = validated.ocr ?? null;
+    this.vision = validated.vision ?? null;
+    this.chunking = validated.chunking ?? null;
+    this.retrievalConfig = validated.retrieval ?? {};
+    if (validated.telemetry) {
+      if (isTelemetryProvider(validated.telemetry)) {
+        this.telemetry = new TelemetryEmitter(validated.telemetry, {
+          enabled: true
+        }, { organization: validated.organization });
+      } else {
+        const url = validated.telemetry.database.url ?? validated.telemetry.database.connectionString ?? "";
+        const provider = new SqliteTelemetryProvider({ url });
+        this.telemetry = new TelemetryEmitter(provider, validated.telemetry, {
+          organization: validated.organization
+        });
+      }
+    }
+    this.checkpointProvider = validated.checkpoint ?? new SqliteCheckpointProvider({
+      directory: validated.checkpointDirectory
+    });
+  }
+  /**
+   * Backwards-compatible initialization (v0.1 API).
+   */
+  async init(options) {
+    if (this.initialized || this.storage) {
+      throw new InitializationError("Wolbarg is already initialized");
+    }
+    let validated;
+    try {
+      validated = validateInitOptions(options);
+    } catch (error) {
+      if (error instanceof ConfigurationError || error instanceof ValidationError) {
+        throw error;
+      }
+      throw new ConfigurationError(
+        `Invalid configuration: ${error instanceof Error ? error.message : String(error)}`,
+        { cause: error instanceof Error ? error : void 0 }
+      );
+    }
+    this.organization = validated.organization;
+    this.storage = createStorageProvider(validated.database);
+    this.memoryDbPath = resolveDatabaseUrl(validated.database);
+    this.embedding = createEmbeddingProvider(validated.embedding);
+    if (validated.llm) {
+      this.llm = createLlmProvider(validated.llm);
+      this.compression = createCompressionProvider(this.llm);
+    }
+    if (!this.checkpointProvider) {
+      this.checkpointProvider = new SqliteCheckpointProvider();
+    }
+    await this.ready();
+  }
+  /** Ensure storage (and optional telemetry) are open. */
+  async ready() {
+    if (this.initialized) {
       return;
     }
     if (this.booting) {
@@ -3484,12 +4655,16 @@ var Wolbarg = class {
     }
     try {
       await this.storage.open();
+      await this.telemetry.open();
+      await this.checkpointProvider?.open();
       const probe = await this.embedding.validate();
       await this.storage.ensureVectorSchema(probe.dimensions);
       this.embeddingDimensions = probe.dimensions;
       this.initialized = true;
+      this.telemetry.emitStartup(this.storage.name);
     } catch (error) {
       await this.storage.close().catch(() => void 0);
+      await this.telemetry.close().catch(() => void 0);
       this.initialized = false;
       if (error instanceof ConfigurationError || error instanceof InitializationError || error instanceof ValidationError) {
         throw error;
@@ -3502,484 +4677,946 @@ var Wolbarg = class {
   }
   /** Store a semantic memory for an agent. */
   async remember(options) {
-    const { storage, embedding, organization } = await this.requireReady();
-    assertNonEmptyString(options.agent, "agent");
-    if (!options.content || typeof options.content.text !== "string") {
-      throw new ValidationError("content.text must be a string");
-    }
-    assertNonEmptyString(options.content.text, "content.text");
-    const metadata = options.metadata ?? {};
-    if (metadata === null || typeof metadata !== "object" || Array.isArray(metadata)) {
-      throw new ValidationError("metadata must be a plain object when provided");
-    }
-    const profile = process.env.WOLBARG_PROFILE === "1";
-    const t0 = profile ? performance.now() : 0;
-    const vector = await embedding.embed(options.content.text);
-    const embedMs = profile ? performance.now() - t0 : 0;
-    this.assertEmbeddingDimensions(vector.length);
-    const id = createId();
-    const timestamp = nowIso();
-    return this.withWriteLock(async () => {
-      const tStore = profile ? performance.now() : 0;
-      const row = await storage.insertMemory({
-        id,
-        organization,
-        agent: options.agent.trim(),
-        contentText: options.content.text,
+    const trace = this.telemetry.start("remember");
+    try {
+      const { storage, embedding, organization } = await this.requireReady();
+      assertNonEmptyString(options.agent, "agent");
+      if (!options.content || typeof options.content.text !== "string") {
+        throw new ValidationError("content.text must be a string");
+      }
+      assertNonEmptyString(options.content.text, "content.text");
+      const metadata = options.metadata ?? {};
+      if (metadata === null || typeof metadata !== "object" || Array.isArray(metadata)) {
+        throw new ValidationError("metadata must be a plain object when provided");
+      }
+      const tEmbed = performance.now();
+      const vector = await embedding.embed(options.content.text);
+      trace.mark("embeddingMs", performance.now() - tEmbed);
+      this.assertEmbeddingDimensions(vector.length);
+      const id = createId();
+      const timestamp = nowIso();
+      const record = await this.withWriteLock(async () => {
+        const tStore = performance.now();
+        const row = await storage.insertMemory({
+          id,
+          organization,
+          agent: options.agent.trim(),
+          contentText: options.content.text,
+          metadata,
+          embedding: vector,
+          createdAt: timestamp,
+          updatedAt: timestamp
+        });
+        trace.mark("databaseWriteMs", performance.now() - tStore);
+        return toMemoryRecord(row);
+      });
+      trace.success({
+        provider: storage.name,
+        memoryIds: [record.id],
+        returnedCount: 1,
+        embeddingProvider: embedding.model,
+        model: embedding.model,
         metadata,
-        embedding: vector,
-        createdAt: timestamp,
-        updatedAt: timestamp
+        agentId: options.agent.trim(),
+        tags: telemetryTags(metadata)
       });
-      if (profile) {
-        const storeMs = performance.now() - tStore;
-        const totalMs = performance.now() - t0;
-        console.log(
-          `[profile] remember embed=${embedMs.toFixed(2)}ms store=${storeMs.toFixed(2)}ms total=${totalMs.toFixed(2)}ms backend=${storage.name}`
-        );
-      }
-      return toMemoryRecord(row);
-    });
+      return record;
+    } catch (error) {
+      trace.failure(error, { agentId: options.agent });
+      throw wrapOperationError("remember", error);
+    }
   }
-  /**
-   * Semantic / hybrid search over stored memories.
-   * Optional keyword, metadata, MMR, and rerank stages degrade gracefully.
-   */
-  async recall(options) {
-    const { storage, embedding, organization } = await this.requireReady();
-    assertNonEmptyString(options.query, "query");
-    const topK = options.topK ?? 5;
-    const threshold = options.threshold ?? 0;
-    assertFiniteNumber(topK, "topK", { min: 1, max: 1e3 });
-    assertFiniteNumber(threshold, "threshold", { min: 0, max: 1 });
-    const query = options.query.trim();
-    const vector = await embedding.embed(query);
-    this.assertEmbeddingDimensions(vector.length);
-    const hasFilters = Boolean(
-      options.filter?.agent || options.filter?.metadata
-    );
-    const overFetch = this.retrievalConfig.overFetchFactor ?? (hasFilters ? 4 : 2);
-    const fetchK = adaptiveFetchK(topK, overFetch, hasFilters);
-    const semanticScores = /* @__PURE__ */ new Map();
-    const byId = /* @__PURE__ */ new Map();
-    const joined = storage.searchVectorsWithMemories;
-    if (typeof joined === "function") {
-      const joinedHits = await joined.call(
-        storage,
-        vector,
-        fetchK,
-        organization,
-        {
-          agent: options.filter?.agent,
-          includeArchived: options.filter?.includeArchived
-        }
-      );
-      for (const { row, distance } of joinedHits) {
-        if (options.filter?.metadata && !matchesMetadata(
-          deserializeMetadata(row.metadata_json),
-          options.filter.metadata
-        )) {
-          continue;
-        }
-        const similarity = distanceToSimilarity(distance);
-        if (similarity < threshold) {
-          continue;
-        }
-        const result = toRecallResult(row, similarity);
-        semanticScores.set(result.id, similarity);
-        byId.set(result.id, result);
+  /** Batch remember — one parent event + child traces per item. */
+  async rememberBatch(items) {
+    const parent = this.telemetry.start("rememberBatch");
+    try {
+      if (!Array.isArray(items) || items.length === 0) {
+        throw new ValidationError("rememberBatch requires a non-empty array");
       }
-    } else {
-      const hits = await storage.searchVectors(vector, fetchK);
-      const rowids = hits.map((h) => h.memoryRowid);
-      let rowMap;
-      if (typeof storage.getMemoriesByRowids === "function") {
-        rowMap = await storage.getMemoriesByRowids(rowids, organization);
-      } else {
-        rowMap = /* @__PURE__ */ new Map();
-        const looked = await Promise.all(
-          hits.map(async (hit) => ({
-            hit,
-            row: await storage.getMemoryByRowid(hit.memoryRowid, organization)
-          }))
-        );
-        for (const { hit, row } of looked) {
-          if (row) rowMap.set(hit.memoryRowid, row);
+      const { storage, embedding, organization } = await this.requireReady();
+      const tEmbed = performance.now();
+      const texts = items.map((item, i) => {
+        assertNonEmptyString(item.agent, `items[${i}].agent`);
+        if (!item.content || typeof item.content.text !== "string") {
+          throw new ValidationError(`items[${i}].content.text must be a string`);
         }
+        assertNonEmptyString(item.content.text, `items[${i}].content.text`);
+        return item.content.text;
+      });
+      const vectors = await embedMany(embedding, texts);
+      parent.mark("embeddingMs", performance.now() - tEmbed);
+      for (const vector of vectors) {
+        this.assertEmbeddingDimensions(vector.length);
       }
-      for (const hit of hits) {
-        const row = rowMap.get(hit.memoryRowid);
-        if (!row) {
-          continue;
-        }
-        if (options.filter?.agent && row.agent !== options.filter.agent) {
-          continue;
-        }
-        if (!options.filter?.includeArchived && row.archived === 1) {
-          continue;
-        }
-        const metadata = deserializeMetadata(row.metadata_json);
-        if (options.filter?.metadata && !matchesMetadata(metadata, options.filter.metadata)) {
-          continue;
-        }
-        const similarity = distanceToSimilarity(hit.distance);
-        if (similarity < threshold) {
-          continue;
-        }
-        const result = toRecallResult(row, similarity);
-        semanticScores.set(result.id, similarity);
-        byId.set(result.id, result);
+      const timestamp = nowIso();
+      const inputs = items.map((item, i) => ({
+        id: createId(),
+        organization,
+        agent: item.agent.trim(),
+        contentText: item.content.text,
+        metadata: item.metadata ?? {},
+        embedding: vectors[i],
+        createdAt: timestamp,
+        updatedAt: timestamp
+      }));
+      for (let i = 0; i < inputs.length; i += 1) {
+        const child = parent.child("remember");
+        child.success({
+          provider: storage.name,
+          memoryIds: [inputs[i].id],
+          returnedCount: 1,
+          metadata: inputs[i].metadata,
+          agentId: inputs[i].agent,
+          tags: telemetryTags(inputs[i].metadata)
+        });
       }
+      const rows = await this.withWriteLock(async () => {
+        const tStore = performance.now();
+        const result = await storage.insertMemoriesBatch(inputs);
+        parent.mark("databaseWriteMs", performance.now() - tStore);
+        return result;
+      });
+      const records = rows.map(toMemoryRecord);
+      parent.success({
+        provider: storage.name,
+        memoryIds: records.map((r) => r.id),
+        returnedCount: records.length,
+        embeddingProvider: embedding.model,
+        model: embedding.model,
+        agentId: commonAgent(items.map((item) => item.agent.trim()))
+      });
+      return records;
+    } catch (error) {
+      parent.failure(error);
+      throw wrapOperationError("rememberBatch", error);
     }
-    const hybridWeights = resolveHybridWeights(options.hybrid) ?? (options.hybrid === void 0 ? resolveHybridWeights(this.retrievalConfig.hybrid) : null);
-    if (hybridWeights) {
-      let keywordScores = /* @__PURE__ */ new Map();
-      if (typeof storage.searchKeyword === "function") {
-        const ftsHits = await storage.searchKeyword(
-          query,
+  }
+  async recall(options) {
+    const trace = this.telemetry.start("recall");
+    const explain = options.explain === true;
+    try {
+      const { storage, embedding, organization } = await this.requireReady();
+      assertNonEmptyString(options.query, "query");
+      const topK = options.topK ?? 5;
+      const threshold = options.threshold ?? 0;
+      assertFiniteNumber(topK, "topK", { min: 1, max: 1e3 });
+      assertFiniteNumber(threshold, "threshold", { min: 0, max: 1 });
+      const query = options.query.trim();
+      const tEmbed = performance.now();
+      const vector = await embedding.embed(query);
+      trace.mark("embeddingMs", performance.now() - tEmbed);
+      this.assertEmbeddingDimensions(vector.length);
+      const hasFilters = Boolean(
+        options.filter?.agent || options.filter?.metadata
+      );
+      const overFetch = this.retrievalConfig.overFetchFactor ?? (hasFilters ? 4 : 2);
+      const fetchK = adaptiveFetchK(topK, overFetch, hasFilters);
+      const semanticScores = /* @__PURE__ */ new Map();
+      const distances = /* @__PURE__ */ new Map();
+      const byId = /* @__PURE__ */ new Map();
+      const metadataMatched = /* @__PURE__ */ new Map();
+      const tSearch = performance.now();
+      const joined = storage.searchVectorsWithMemories;
+      if (typeof joined === "function") {
+        const joinedHits = await joined.call(
+          storage,
+          vector,
+          fetchK,
           organization,
-          fetchK
-        );
-        keywordScores = new Map(
-          ftsHits.map((h) => [h.memoryId, h.score])
-        );
-        const missingIds = [];
-        for (const id of keywordScores.keys()) {
-          if (!byId.has(id)) missingIds.push(id);
-        }
-        if (missingIds.length > 0) {
-          const fetched = await Promise.all(
-            missingIds.map((id) => storage.getMemoryById(id, organization))
-          );
-          for (const row of fetched) {
-            if (!row) continue;
-            if (options.filter?.agent && row.agent !== options.filter.agent) {
-              continue;
-            }
-            if (!options.filter?.includeArchived && row.archived === 1) {
-              continue;
-            }
-            if (options.filter?.metadata && !matchesMetadata(
-              deserializeMetadata(row.metadata_json),
-              options.filter.metadata
-            )) {
-              continue;
-            }
-            byId.set(row.id, toRecallResult(row, 0));
-          }
-        }
-      } else if (this.keywordSearch) {
-        const corpus = await storage.listMemories(
           {
-            organization,
             agent: options.filter?.agent,
-            includeArchived: options.filter?.includeArchived,
-            metadata: options.filter?.metadata
-          },
-          Math.min(fetchK * 2, 2e3)
-        );
-        const keywordHits = await this.keywordSearch.search(
-          query,
-          corpus.map((row) => ({ id: row.id, text: row.content_text })),
-          fetchK
-        );
-        keywordScores = new Map(
-          keywordHits.map((h) => [h.memoryId, h.score])
+            includeArchived: options.filter?.includeArchived
+          }
         );
-        for (const row of corpus) {
-          if (byId.has(row.id)) {
+        const tFilter = performance.now();
+        for (const { row, distance } of joinedHits) {
+          let metaOk = true;
+          if (options.filter?.metadata && !matchesMetadata(
+            deserializeMetadata(row.metadata_json),
+            options.filter.metadata
+          )) {
+            metaOk = false;
             continue;
           }
-          if (!keywordScores.has(row.id)) {
+          const similarity = distanceToSimilarity(distance);
+          if (similarity < threshold) {
             continue;
           }
+          const result = toRecallResult(row, similarity);
+          semanticScores.set(result.id, similarity);
+          distances.set(result.id, distance);
+          metadataMatched.set(result.id, metaOk);
+          byId.set(result.id, result);
+        }
+        trace.mark("metadataFilteringMs", performance.now() - tFilter);
+      } else {
+        const hits = await storage.searchVectors(vector, fetchK);
+        const rowids = hits.map((h) => h.memoryRowid);
+        let rowMap;
+        if (typeof storage.getMemoriesByRowids === "function") {
+          rowMap = await storage.getMemoriesByRowids(rowids, organization);
+        } else {
+          rowMap = /* @__PURE__ */ new Map();
+          const looked = await Promise.all(
+            hits.map(async (hit) => ({
+              hit,
+              row: await storage.getMemoryByRowid(hit.memoryRowid, organization)
+            }))
+          );
+          for (const { hit, row } of looked) {
+            if (row) rowMap.set(hit.memoryRowid, row);
+          }
+        }
+        const tFilter = performance.now();
+        for (const hit of hits) {
+          const row = rowMap.get(hit.memoryRowid);
+          if (!row) continue;
+          if (options.filter?.agent && row.agent !== options.filter.agent) continue;
+          if (!options.filter?.includeArchived && row.archived === 1) continue;
           const metadata = deserializeMetadata(row.metadata_json);
           if (options.filter?.metadata && !matchesMetadata(metadata, options.filter.metadata)) {
             continue;
           }
-          if (!options.filter?.includeArchived && row.archived === 1) {
-            continue;
+          const similarity = distanceToSimilarity(hit.distance);
+          if (similarity < threshold) continue;
+          const result = toRecallResult(row, similarity);
+          semanticScores.set(result.id, similarity);
+          distances.set(result.id, hit.distance);
+          metadataMatched.set(result.id, true);
+          byId.set(result.id, result);
+        }
+        trace.mark("metadataFilteringMs", performance.now() - tFilter);
+      }
+      const searchTime = performance.now() - tSearch;
+      trace.mark("vectorSearchMs", searchTime);
+      trace.mark("databaseReadMs", searchTime);
+      const hybridWeights = resolveHybridWeights(options.hybrid) ?? (options.hybrid === void 0 ? resolveHybridWeights(this.retrievalConfig.hybrid) : null);
+      let keywordSignal = "disabled";
+      if (hybridWeights) {
+        let keywordScores = /* @__PURE__ */ new Map();
+        if (typeof storage.searchKeyword === "function") {
+          keywordSignal = "enabled";
+          const ftsHits = await storage.searchKeyword(
+            query,
+            organization,
+            fetchK
+          );
+          keywordScores = new Map(ftsHits.map((h) => [h.memoryId, h.score]));
+          const missingIds = [];
+          for (const id of keywordScores.keys()) {
+            if (!byId.has(id)) missingIds.push(id);
+          }
+          if (missingIds.length > 0) {
+            const fetched = await Promise.all(
+              missingIds.map((id) => storage.getMemoryById(id, organization))
+            );
+            for (const row of fetched) {
+              if (!row) continue;
+              if (options.filter?.agent && row.agent !== options.filter.agent) {
+                continue;
+              }
+              if (!options.filter?.includeArchived && row.archived === 1) {
+                continue;
+              }
+              if (options.filter?.metadata && !matchesMetadata(
+                deserializeMetadata(row.metadata_json),
+                options.filter.metadata
+              )) {
+                continue;
+              }
+              byId.set(row.id, toRecallResult(row, 0));
+              metadataMatched.set(row.id, true);
+            }
+          }
+        } else if (this.keywordSearch) {
+          keywordSignal = "enabled";
+          const corpus = await storage.listMemories(
+            {
+              organization,
+              agent: options.filter?.agent,
+              includeArchived: options.filter?.includeArchived,
+              metadata: options.filter?.metadata
+            },
+            Math.min(fetchK * 2, 2e3)
+          );
+          const keywordHits = await this.keywordSearch.search(
+            query,
+            corpus.map((row) => ({ id: row.id, text: row.content_text })),
+            fetchK
+          );
+          keywordScores = new Map(
+            keywordHits.map((h) => [h.memoryId, h.score])
+          );
+          for (const row of corpus) {
+            if (byId.has(row.id) || !keywordScores.has(row.id)) continue;
+            byId.set(row.id, toRecallResult(row, 0));
+            metadataMatched.set(row.id, true);
           }
-          byId.set(row.id, toRecallResult(row, 0));
         }
-      }
-      if (keywordScores.size > 0) {
-        const fused = fuseScores(semanticScores, keywordScores, hybridWeights);
-        for (const [id, score] of fused) {
-          const existing = byId.get(id);
-          if (existing) {
-            byId.set(id, { ...existing, similarity: score });
+        if (keywordScores.size > 0) {
+          const fused = fuseScores(semanticScores, keywordScores, hybridWeights);
+          for (const [id, score] of fused) {
+            const existing = byId.get(id);
+            if (existing) {
+              byId.set(id, { ...existing, similarity: score });
+            }
           }
         }
       }
-    }
-    let results = [...byId.values()].sort(
-      (a, b) => b.similarity - a.similarity
-    );
-    const mmrLambda = resolveMmr(options.mmr) ?? resolveMmr(
-      this.retrievalConfig.mmr ? { lambda: this.retrievalConfig.mmr.lambda } : void 0
-    );
-    if (mmrLambda !== null) {
-      results = applyMmr(results, Math.max(topK * 2, topK), mmrLambda);
-    }
-    if (options.rerank && this.reranker) {
-      const reranked = await this.reranker.rerank(
-        query,
-        results.map((r) => ({ id: r.id, text: r.content.text })),
-        topK
+      const tRank = performance.now();
+      let results = [...byId.values()].sort(
+        (a, b) => b.similarity - a.similarity
       );
-      const order = new Map(reranked.map((r, i) => [r.id, { score: r.score, i }]));
-      results = results.filter((r) => order.has(r.id)).sort((a, b) => order.get(a.id).i - order.get(b.id).i).map((r) => ({
-        ...r,
-        similarity: order.get(r.id)?.score ?? r.similarity
-      }));
+      const mmrLambda = resolveMmr(options.mmr) ?? resolveMmr(
+        this.retrievalConfig.mmr ? { lambda: this.retrievalConfig.mmr.lambda } : void 0
+      );
+      let rankingReason = "cosine similarity";
+      if (mmrLambda !== null) {
+        results = applyMmr(results, Math.max(topK * 2, topK), mmrLambda);
+        rankingReason = `MMR(lambda=${mmrLambda})`;
+      }
+      if (options.rerank && this.reranker) {
+        const reranked = await this.reranker.rerank(
+          query,
+          results.map((r) => ({ id: r.id, text: r.content.text })),
+          topK
+        );
+        const order = new Map(
+          reranked.map((r, i) => [r.id, { score: r.score, i }])
+        );
+        results = results.filter((r) => order.has(r.id)).sort((a, b) => order.get(a.id).i - order.get(b.id).i).map((r) => ({
+          ...r,
+          similarity: order.get(r.id)?.score ?? r.similarity
+        }));
+        rankingReason = `reranker:${this.reranker.name ?? "custom"}`;
+      }
+      const rankingTime = performance.now() - tRank;
+      trace.mark("rankingMs", rankingTime);
+      results = results.slice(0, topK);
+      const tSer = performance.now();
+      const serialized = results.map((r) => ({ ...r }));
+      trace.mark("serializationMs", performance.now() - tSer);
+      const telemetryFields = {
+        provider: storage.name,
+        query,
+        filters: options.filter ?? null,
+        returnedCount: serialized.length,
+        memoryIds: serialized.map((r) => r.id),
+        similarityScores: serialized.map((r) => r.similarity),
+        embeddingProvider: embedding.model,
+        model: embedding.model,
+        agentId: options.filter?.agent ?? commonAgent(serialized.map((result) => result.agent)),
+        tags: commonTags(serialized.map((result) => result.metadata))
+      };
+      if (!explain) {
+        trace.success(telemetryFields);
+        return serialized;
+      }
+      const explanations = serialized.map((memory) => {
+        const matchedFields = ["content"];
+        if (options.filter?.agent) matchedFields.push("agent");
+        if (options.filter?.metadata) matchedFields.push("metadata");
+        return {
+          memory,
+          score: memory.similarity,
+          distance: distances.get(memory.id) ?? 1 - memory.similarity,
+          rankingReason,
+          matchedFields,
+          metadataMatch: metadataMatched.get(memory.id) ?? true,
+          providerUsed: storage.name,
+          searchTime,
+          rankingTime
+        };
+      });
+      const totalTime = performance.now() - trace.startedAt;
+      const persistedExplain = {
+        enabled: true,
+        providerUsed: storage.name,
+        rankingStrategy: rankingReason,
+        signals: {
+          semantic: "enabled",
+          keyword: keywordSignal,
+          reranker: options.rerank === true && this.reranker ? "enabled" : "disabled",
+          mmr: mmrLambda === null ? "disabled" : "enabled",
+          recency: "disabled"
+        },
+        results: explanations.map((hit) => ({
+          memoryId: hit.memory.id,
+          score: hit.score,
+          distance: hit.distance,
+          rankingReason: hit.rankingReason,
+          matchedFields: hit.matchedFields,
+          metadataMatch: hit.metadataMatch
+        })),
+        searchTimeMs: searchTime,
+        rankingTimeMs: rankingTime,
+        totalTimeMs: totalTime
+      };
+      trace.success({ ...telemetryFields, explain: persistedExplain });
+      return {
+        results: explanations,
+        providerUsed: storage.name,
+        searchTime,
+        rankingTime,
+        totalTime,
+        traceId: trace.context.traceId
+      };
+    } catch (error) {
+      trace.failure(error, {
+        query: options.query,
+        agentId: options.filter?.agent ?? null
+      });
+      throw wrapOperationError("recall", error);
+    }
+  }
+  /** Batch recall — parent event + child traces. */
+  async recallBatch(queries) {
+    const parent = this.telemetry.start("recallBatch");
+    try {
+      if (!Array.isArray(queries) || queries.length === 0) {
+        throw new ValidationError("recallBatch requires a non-empty array");
+      }
+      const out = [];
+      for (const q of queries) {
+        const child = parent.child("recall");
+        try {
+          const hits = await this.recall({ ...q, explain: false });
+          child.success({
+            query: q.query,
+            returnedCount: hits.length,
+            memoryIds: hits.map((h) => h.id),
+            similarityScores: hits.map((h) => h.similarity)
+          });
+          out.push(hits);
+        } catch (error) {
+          child.failure(error, { query: q.query });
+          throw error;
+        }
+      }
+      parent.success({
+        returnedCount: out.reduce((n, r) => n + r.length, 0),
+        extra: { queryCount: queries.length }
+      });
+      return out;
+    } catch (error) {
+      parent.failure(error);
+      throw wrapOperationError("recallBatch", error);
     }
-    return results.slice(0, topK);
   }
-  /**
-   * Compress related memories for an agent into a single summarized memory.
-   * Only available when `llm` (or `compression`) was configured at construction.
-   */
   async compress(options) {
     return this.runCompress(options);
   }
   /** @internal */
   async runCompress(options) {
-    const { storage, embedding, organization } = await this.requireReady();
-    if (!this.compression) {
-      throw new ProviderNotConfiguredError(
-        "llm",
-        "compress",
-        "pass llm: openaiLlm(...) (or compression) in the constructor"
+    const trace = this.telemetry.start("compress");
+    try {
+      const { storage, embedding, organization } = await this.requireReady();
+      if (!this.compression) {
+        throw new ProviderNotConfiguredError(
+          "llm",
+          "compress",
+          "pass llm: openaiLlm(...) (or compression) in the constructor"
+        );
+      }
+      assertNonEmptyString(options.agent, "agent");
+      const limit = options.limit ?? 50;
+      assertFiniteNumber(limit, "limit", { min: 2, max: 500 });
+      const tRead = performance.now();
+      const rows = await storage.listMemories(
+        {
+          organization,
+          agent: options.agent.trim(),
+          includeArchived: false
+        },
+        limit
       );
+      trace.mark("databaseReadMs", performance.now() - tRead);
+      if (rows.length < 2) {
+        throw new ValidationError(
+          "compress requires at least 2 active memories for the given agent"
+        );
+      }
+      const records = rows.map(toMemoryRecord);
+      const summaryText = await this.compression.compress(records);
+      const tEmbed = performance.now();
+      const vector = await embedding.embed(summaryText);
+      trace.mark("embeddingMs", performance.now() - tEmbed);
+      this.assertEmbeddingDimensions(vector.length);
+      const summaryId = createId();
+      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 archivedIds = await storage.archiveMemories(
+          records.map((r) => r.id),
+          organization,
+          summaryId,
+          timestamp
+        );
+        trace.mark("databaseWriteMs", performance.now() - tWrite);
+        return {
+          summary: toMemoryRecord(summaryRow),
+          archivedIds
+        };
+      });
+      trace.success({
+        provider: storage.name,
+        memoryIds: [result.summary.id, ...result.archivedIds],
+        returnedCount: 1,
+        agentId: options.agent.trim()
+      });
+      return result;
+    } catch (error) {
+      trace.failure(error, { agentId: options.agent });
+      throw wrapOperationError("compress", error);
     }
-    assertNonEmptyString(options.agent, "agent");
-    const limit = options.limit ?? 50;
-    assertFiniteNumber(limit, "limit", { min: 2, max: 500 });
-    const rows = await storage.listMemories(
-      {
-        organization,
-        agent: options.agent.trim(),
-        includeArchived: false
-      },
-      limit
-    );
-    if (rows.length < 2) {
-      throw new ValidationError(
-        "compress requires at least 2 active memories for the given agent"
+  }
+  async ingest(options) {
+    const trace = this.telemetry.start("ingest");
+    try {
+      const { storage, embedding, organization } = await this.requireReady();
+      assertNonEmptyString(options.agent, "agent");
+      const loaded = await loadIngestSource(options.source);
+      let usedOcr = false;
+      let usedVision = false;
+      let text = loaded.rawText ?? "";
+      if (!loaded.rawText) {
+        const parser = resolveParser(loaded.filename, loaded.mimeType);
+        const parsed = await parser.parse({
+          buffer: loaded.buffer,
+          filename: loaded.filename,
+          mimeType: loaded.mimeType
+        });
+        text = parsed.text;
+        if (parsed.isImage && parsed.imageBuffer) {
+          const parts = [];
+          if (this.ocr) {
+            const ocrResult = await this.ocr.recognize(
+              parsed.imageBuffer,
+              parsed.mimeType
+            );
+            if (ocrResult.text) {
+              parts.push(ocrResult.text);
+              usedOcr = true;
+            }
+          }
+          if (this.vision) {
+            const visionResult = await this.vision.analyze(
+              parsed.imageBuffer,
+              parsed.mimeType
+            );
+            if (visionResult.caption) {
+              parts.push(`Caption: ${visionResult.caption}`);
+            }
+            if (visionResult.description) {
+              parts.push(visionResult.description);
+            }
+            if (visionResult.entities.length > 0) {
+              parts.push(`Entities: ${visionResult.entities.join(", ")}`);
+            }
+            if (parts.length > 0) {
+              usedVision = true;
+            }
+          }
+          text = parts.join("\n\n").trim();
+        }
+      }
+      if (!text) {
+        throw new ValidationError(
+          "ingest could not extract text from the document (configure ocr/vision for images, or provide text)"
+        );
+      }
+      const strategy = this.chunking ?? (options.chunking?.strategy ? createChunkingStrategy(options.chunking.strategy) : inferChunkingStrategy(text));
+      const chunks = strategy.chunk(text, {
+        chunkSize: options.chunking?.chunkSize,
+        overlap: options.chunking?.overlap
+      });
+      if (chunks.length === 0) {
+        throw new ValidationError("ingest produced zero chunks");
+      }
+      const tEmbed = performance.now();
+      const vectors = await embedMany(
+        embedding,
+        chunks.map((c) => c.text)
       );
-    }
-    const records = rows.map(toMemoryRecord);
-    const summaryText = await this.compression.compress(records);
-    const vector = await embedding.embed(summaryText);
-    this.assertEmbeddingDimensions(vector.length);
-    const summaryId = createId();
-    const timestamp = nowIso();
-    return this.withWriteLock(async () => {
-      const summaryRow = await storage.insertMemory({
-        id: summaryId,
+      trace.mark("embeddingMs", performance.now() - tEmbed);
+      for (const vector of vectors) {
+        this.assertEmbeddingDimensions(vector.length);
+      }
+      const baseMeta = options.metadata ?? {};
+      const timestamp = nowIso();
+      const inputs = chunks.map((chunk, i) => ({
+        id: createId(),
         organization,
         agent: options.agent.trim(),
-        contentText: summaryText,
+        contentText: chunk.text,
         metadata: {
-          compressed: true,
-          sourceCount: records.length,
-          sourceIds: records.map((r) => r.id)
+          ...baseMeta,
+          ingest: true,
+          chunkIndex: chunk.index,
+          chunkCount: chunks.length,
+          sourceFilename: loaded.filename ?? null
         },
-        embedding: vector,
+        embedding: vectors[i],
         createdAt: timestamp,
         updatedAt: timestamp
+      }));
+      const rows = await this.withWriteLock(async () => {
+        const tWrite = performance.now();
+        const result2 = await storage.insertMemoriesBatch(inputs);
+        trace.mark("databaseWriteMs", performance.now() - tWrite);
+        return result2;
       });
-      const archivedIds = await storage.archiveMemories(
-        records.map((r) => r.id),
-        organization,
-        summaryId,
-        timestamp
-      );
-      return {
-        summary: toMemoryRecord(summaryRow),
-        archivedIds
+      const result = {
+        memories: rows.map(toMemoryRecord),
+        extractedChars: text.length,
+        chunkCount: chunks.length,
+        usedOcr,
+        usedVision
       };
-    });
-  }
-  /** Ingest a document: parse → OCR/vision (optional) → chunk → embed → store. */
-  async ingest(options) {
-    const { storage, embedding, organization } = await this.requireReady();
-    assertNonEmptyString(options.agent, "agent");
-    const loaded = await loadIngestSource(options.source);
-    let usedOcr = false;
-    let usedVision = false;
-    let text = loaded.rawText ?? "";
-    if (!loaded.rawText) {
-      const parser = resolveParser(loaded.filename, loaded.mimeType);
-      const parsed = await parser.parse({
-        buffer: loaded.buffer,
-        filename: loaded.filename,
-        mimeType: loaded.mimeType
+      trace.success({
+        provider: storage.name,
+        memoryIds: result.memories.map((m) => m.id),
+        returnedCount: result.memories.length,
+        agentId: options.agent.trim(),
+        tags: telemetryTags(baseMeta)
       });
-      text = parsed.text;
-      if (parsed.isImage && parsed.imageBuffer) {
-        const parts = [];
-        if (this.ocr) {
-          const ocrResult = await this.ocr.recognize(
-            parsed.imageBuffer,
-            parsed.mimeType
+      return result;
+    } catch (error) {
+      trace.failure(error, { agentId: options.agent });
+      throw wrapOperationError("ingest", error);
+    }
+  }
+  async forget(options) {
+    const trace = this.telemetry.start("forget");
+    try {
+      const { storage, organization } = await this.requireReady();
+      const deleted = await this.withWriteLock(async () => {
+        if ("id" in options && options.id !== void 0) {
+          assertNonEmptyString(options.id, "id");
+          const ok = await storage.deleteMemoryById(
+            options.id.trim(),
+            organization
           );
-          if (ocrResult.text) {
-            parts.push(ocrResult.text);
-            usedOcr = true;
-          }
+          return ok ? 1 : 0;
         }
-        if (this.vision) {
-          const visionResult = await this.vision.analyze(
-            parsed.imageBuffer,
-            parsed.mimeType
-          );
-          if (visionResult.caption) {
-            parts.push(`Caption: ${visionResult.caption}`);
-          }
-          if (visionResult.description) {
-            parts.push(visionResult.description);
-          }
-          if (visionResult.entities.length > 0) {
-            parts.push(`Entities: ${visionResult.entities.join(", ")}`);
-          }
-          if (parts.length > 0) {
-            usedVision = true;
-          }
+        if ("filter" in options && options.filter?.agent) {
+          assertNonEmptyString(options.filter.agent, "filter.agent");
+          return storage.deleteMemoriesByFilter({
+            organization,
+            agent: options.filter.agent.trim(),
+            includeArchived: true
+          });
         }
-        text = parts.join("\n\n").trim();
+        throw new ValidationError(
+          "forget requires either { id } or { filter: { agent } }"
+        );
+      });
+      trace.success({
+        provider: storage.name,
+        returnedCount: deleted,
+        memoryIds: "id" in options && options.id ? [options.id.trim()] : null,
+        filters: "filter" in options ? options.filter : null,
+        agentId: "filter" in options ? options.filter?.agent?.trim() ?? null : null
+      });
+      return deleted;
+    } catch (error) {
+      trace.failure(error, {
+        agentId: "filter" in options ? options.filter?.agent ?? null : null
+      });
+      throw wrapOperationError("forget", error);
+    }
+  }
+  async history(options) {
+    const trace = this.telemetry.start("history");
+    try {
+      const { storage, organization } = await this.requireReady();
+      assertNonEmptyString(options.id, "id");
+      const row = await storage.getMemoryById(options.id.trim(), organization);
+      if (!row) {
+        throw new MemoryNotFoundError(`Memory not found: ${options.id}`);
       }
+      const events = await storage.getHistory(row.id);
+      const result = {
+        memory: toMemoryRecord(row),
+        events: events.map(toHistoryEvent)
+      };
+      trace.success({
+        provider: storage.name,
+        memoryIds: [row.id],
+        returnedCount: events.length,
+        agentId: row.agent,
+        tags: telemetryTags(deserializeMetadata(row.metadata_json))
+      });
+      return result;
+    } catch (error) {
+      trace.failure(error);
+      throw wrapOperationError("history", error);
     }
-    if (!text) {
-      throw new ValidationError(
-        "ingest could not extract text from the document (configure ocr/vision for images, or provide text)"
-      );
+  }
+  async stats() {
+    const trace = this.telemetry.start("stats");
+    try {
+      const { storage, embedding, organization } = await this.requireReady();
+      const counts = await storage.getStats(organization);
+      const databaseSizeBytes = await storage.getDatabaseSizeBytes();
+      const result = {
+        totalMemories: counts.totalMemories,
+        activeMemories: counts.activeMemories,
+        archivedMemories: counts.archivedMemories,
+        totalAgents: counts.totalAgents,
+        databaseSizeBytes,
+        embeddingModel: embedding.model,
+        llmModel: this.llm?.model ?? null,
+        organization,
+        embeddingDimensions: this.embeddingDimensions ?? 0
+      };
+      trace.success({
+        provider: storage.name,
+        returnedCount: result.totalMemories
+      });
+      return result;
+    } catch (error) {
+      trace.failure(error);
+      throw wrapOperationError("stats", error);
     }
-    const strategy = this.chunking ?? (options.chunking?.strategy ? createChunkingStrategy(options.chunking.strategy) : inferChunkingStrategy(text));
-    const chunks = strategy.chunk(text, {
-      chunkSize: options.chunking?.chunkSize,
-      overlap: options.chunking?.overlap
-    });
-    if (chunks.length === 0) {
-      throw new ValidationError("ingest produced zero chunks");
+  }
+  async clear(options) {
+    const trace = this.telemetry.start("clear");
+    try {
+      const { storage, organization } = await this.requireReady();
+      if (!options || options.confirm !== true) {
+        throw new ValidationError(
+          "clear requires { confirm: true } to permanently delete all memories"
+        );
+      }
+      const deleted = await this.withWriteLock(async () => {
+        return storage.clearOrganization(organization);
+      });
+      trace.success({ provider: storage.name, returnedCount: deleted });
+      return deleted;
+    } catch (error) {
+      trace.failure(error);
+      throw wrapOperationError("clear", error);
     }
-    const vectors = await embedMany(
-      embedding,
-      chunks.map((c) => c.text)
-    );
-    for (const vector of vectors) {
-      this.assertEmbeddingDimensions(vector.length);
+  }
+  /** Create an immutable named checkpoint of the memory database. */
+  async checkpoint(name, options) {
+    const trace = this.telemetry.start("checkpoint");
+    try {
+      await this.requireReady();
+      const provider = this.requireCheckpointProvider();
+      const source = this.requireMemoryDbPath();
+      const tCheckpoint = performance.now();
+      const meta2 = await provider.checkpoint(name, source, options);
+      trace.mark("databaseWriteMs", performance.now() - tCheckpoint);
+      trace.success({
+        provider: provider.name,
+        checkpointId: meta2.name,
+        extra: { checkpoint: meta2.name }
+      });
+      return meta2;
+    } catch (error) {
+      trace.failure(error, { checkpointId: name });
+      throw wrapOperationError("checkpoint", error);
     }
-    const baseMeta = options.metadata ?? {};
-    const timestamp = nowIso();
-    const inputs = chunks.map((chunk, i) => ({
-      id: createId(),
-      organization,
-      agent: options.agent.trim(),
-      contentText: chunk.text,
-      metadata: {
-        ...baseMeta,
-        ingest: true,
-        chunkIndex: chunk.index,
-        chunkCount: chunks.length,
-        sourceFilename: loaded.filename ?? null
-      },
-      embedding: vectors[i],
-      createdAt: timestamp,
-      updatedAt: timestamp
-    }));
-    const rows = await this.withWriteLock(async () => {
-      return storage.insertMemoriesBatch(inputs);
-    });
-    return {
-      memories: rows.map(toMemoryRecord),
-      extractedChars: text.length,
-      chunkCount: chunks.length,
-      usedOcr,
-      usedVision
-    };
   }
-  /** Delete memories by ID or filter. */
-  async forget(options) {
-    const { storage, organization } = await this.requireReady();
-    return this.withWriteLock(async () => {
-      if ("id" in options && options.id !== void 0) {
-        assertNonEmptyString(options.id, "id");
-        const deleted = await storage.deleteMemoryById(
-          options.id.trim(),
-          organization
-        );
-        return deleted ? 1 : 0;
+  /** Restore the memory database from a named checkpoint. */
+  async rollback(name) {
+    const trace = this.telemetry.start("rollback");
+    let storageClosed = false;
+    try {
+      await this.requireReady();
+      const provider = this.requireCheckpointProvider();
+      const target = this.requireMemoryDbPath();
+      const existing = await provider.getCheckpoint(name);
+      if (!existing) {
+        throw new ValidationError(`Checkpoint "${name}" was not found`);
       }
-      if ("filter" in options && options.filter?.agent) {
-        assertNonEmptyString(options.filter.agent, "filter.agent");
-        return storage.deleteMemoriesByFilter({
-          organization,
-          agent: options.filter.agent.trim(),
-          includeArchived: true
-        });
+      if (this.storage) {
+        await this.storage.close();
+        storageClosed = true;
       }
-      throw new ValidationError(
-        "forget requires either { id } or { filter: { agent } }"
-      );
-    });
+      const tRollback = performance.now();
+      const meta2 = await provider.rollback(name, target);
+      trace.mark("databaseWriteMs", performance.now() - tRollback);
+      await this.storage?.open();
+      storageClosed = false;
+      if (this.embeddingDimensions !== null) {
+        await this.storage?.ensureVectorSchema(this.embeddingDimensions);
+      }
+      trace.success({
+        provider: provider.name,
+        checkpointId: meta2.name,
+        extra: { checkpoint: meta2.name }
+      });
+      return meta2;
+    } catch (error) {
+      if (storageClosed && this.storage) {
+        await this.storage.open().catch(() => void 0);
+        if (this.embeddingDimensions !== null) {
+          await this.storage.ensureVectorSchema(this.embeddingDimensions).catch(() => void 0);
+        }
+      }
+      trace.failure(error, { checkpointId: name });
+      throw wrapOperationError("rollback", error);
+    }
   }
-  /** Return the history of a memory. */
-  async history(options) {
-    const { storage, organization } = await this.requireReady();
-    assertNonEmptyString(options.id, "id");
-    const row = await storage.getMemoryById(options.id.trim(), organization);
-    if (!row) {
-      throw new MemoryNotFoundError(`Memory not found: ${options.id}`);
+  async deleteCheckpoint(name) {
+    const trace = this.telemetry.start("deleteCheckpoint");
+    try {
+      await this.requireReady();
+      const provider = this.requireCheckpointProvider();
+      const tDelete = performance.now();
+      const removed = await provider.deleteCheckpoint(name);
+      trace.mark("databaseWriteMs", performance.now() - tDelete);
+      trace.success({
+        provider: provider.name,
+        checkpointId: name,
+        returnedCount: removed ? 1 : 0
+      });
+      return removed;
+    } catch (error) {
+      trace.failure(error, { checkpointId: name });
+      throw wrapOperationError("deleteCheckpoint", error);
     }
-    const events = await storage.getHistory(row.id);
-    return {
-      memory: toMemoryRecord(row),
-      events: events.map(toHistoryEvent)
-    };
   }
-  /** Aggregate statistics for the current organization. */
-  async stats() {
-    const { storage, embedding, organization } = await this.requireReady();
-    const counts = await storage.getStats(organization);
-    const databaseSizeBytes = await storage.getDatabaseSizeBytes();
-    return {
-      totalMemories: counts.totalMemories,
-      activeMemories: counts.activeMemories,
-      archivedMemories: counts.archivedMemories,
-      totalAgents: counts.totalAgents,
-      databaseSizeBytes,
-      embeddingModel: embedding.model,
-      llmModel: this.llm?.model ?? null,
-      organization,
-      embeddingDimensions: this.embeddingDimensions ?? 0
-    };
+  async listCheckpoints() {
+    const trace = this.telemetry.start("listCheckpoints");
+    try {
+      await this.requireReady();
+      const provider = this.requireCheckpointProvider();
+      const tList = performance.now();
+      const list = await provider.listCheckpoints();
+      trace.mark("databaseReadMs", performance.now() - tList);
+      trace.success({
+        provider: provider.name,
+        returnedCount: list.length
+      });
+      return list;
+    } catch (error) {
+      trace.failure(error);
+      throw wrapOperationError("listCheckpoints", error);
+    }
   }
-  /** Delete every memory in the current organization. */
-  async clear(options) {
-    const { storage, organization } = await this.requireReady();
-    if (!options || options.confirm !== true) {
-      throw new ValidationError(
-        "clear requires { confirm: true } to permanently delete all memories"
+  async getCheckpoint(name) {
+    const trace = this.telemetry.start("getCheckpoint");
+    try {
+      await this.requireReady();
+      const provider = this.requireCheckpointProvider();
+      const tGet = performance.now();
+      const meta2 = await provider.getCheckpoint(name);
+      trace.mark("databaseReadMs", performance.now() - tGet);
+      trace.success({
+        provider: provider.name,
+        checkpointId: name,
+        returnedCount: meta2 ? 1 : 0
+      });
+      return meta2;
+    } catch (error) {
+      trace.failure(error, { checkpointId: name });
+      throw wrapOperationError("getCheckpoint", error);
+    }
+  }
+  /** Export the memory database to a portable SQLite + manifest bundle. */
+  async export(exportPath) {
+    const trace = this.telemetry.start("export");
+    try {
+      await this.requireReady();
+      const source = this.requireMemoryDbPath();
+      if (this.storage?.name === "sqlite") {
+      }
+      const result = await this.transfer.exportTo(
+        exportPath,
+        source,
+        this.organization ?? void 0
+      );
+      trace.success({
+        provider: "sqlite",
+        extra: { path: result.path, sizeBytes: result.sizeBytes }
+      });
+      return {
+        path: result.path,
+        sizeBytes: result.sizeBytes,
+        exportedAt: result.manifest.exportedAt
+      };
+    } catch (error) {
+      trace.failure(error);
+      throw wrapOperationError("export", error);
+    }
+  }
+  /** Import a previously exported memory database, replacing the current file. */
+  async import(exportPath) {
+    const trace = this.telemetry.start("import");
+    let storageClosed = false;
+    try {
+      await this.requireReady();
+      const target = this.requireMemoryDbPath();
+      if (this.storage) {
+        await this.storage.close();
+        storageClosed = true;
+      }
+      const result = await this.transfer.importFrom(
+        exportPath,
+        target
       );
+      await this.storage?.open();
+      storageClosed = false;
+      if (this.embeddingDimensions !== null) {
+        await this.storage?.ensureVectorSchema(this.embeddingDimensions);
+      }
+      trace.success({
+        provider: "sqlite",
+        extra: { path: result.path }
+      });
+      return {
+        path: result.path,
+        importedAt: nowIso()
+      };
+    } catch (error) {
+      if (storageClosed && this.storage) {
+        await this.storage.open().catch(() => void 0);
+        if (this.embeddingDimensions !== null) {
+          await this.storage.ensureVectorSchema(this.embeddingDimensions).catch(() => void 0);
+        }
+      }
+      trace.failure(error);
+      throw wrapOperationError("import", error);
     }
-    return this.withWriteLock(async () => {
-      return storage.clearOrganization(organization);
-    });
   }
-  /**
-   * Serialize writes for SQLite (single connection). Postgres uses a pool and
-   * per-statement atomic CTEs — locking here only serializes throughput.
-   */
+  /** Flush pending telemetry (useful in tests). */
+  async flushTelemetry() {
+    await this.telemetry.flush();
+  }
+  /** Session id for this SDK instance (telemetry traces). */
+  get sessionId() {
+    return this.telemetry.sessionId;
+  }
   withWriteLock(fn) {
     if (this.storage?.name === "sqlite") {
       return this.writeMutex.runExclusive(fn);
     }
     return fn();
   }
-  /** Close the database connection and release resources. */
   async close() {
+    if (this.storage) {
+      this.telemetry.emitShutdown(this.storage.name);
+    }
+    await this.telemetry.close().catch(() => void 0);
+    await this.checkpointProvider?.close().catch(() => void 0);
     if (this.storage) {
       await this.storage.close();
     }
@@ -3991,7 +5628,6 @@ var Wolbarg = class {
     this.embeddingDimensions = null;
     this.initialized = false;
   }
-  /** Whether providers are ready for API calls. */
   get isInitialized() {
     return this.initialized;
   }
@@ -4015,7 +5651,56 @@ var Wolbarg = class {
       );
     }
   }
+  requireCheckpointProvider() {
+    if (!this.checkpointProvider) {
+      throw new ProviderNotConfiguredError(
+        "checkpoint",
+        "checkpoint",
+        "construct Wolbarg with a file-backed database"
+      );
+    }
+    return this.checkpointProvider;
+  }
+  requireMemoryDbPath() {
+    if (!this.memoryDbPath || this.memoryDbPath === ":memory:") {
+      throw new ConfigurationError(
+        "This operation requires a file-backed SQLite memory database (not :memory:).",
+        {
+          suggestion: 'Use database: { provider: "sqlite", url: "./memory.db" }'
+        }
+      );
+    }
+    return path5.isAbsolute(this.memoryDbPath) ? this.memoryDbPath : path5.resolve(process.cwd(), this.memoryDbPath);
+  }
 };
+function wolbarg(options) {
+  return new Wolbarg(options);
+}
+function telemetryTags(metadata) {
+  const value = metadata.tags;
+  if (typeof value === "string") {
+    const tag = value.trim();
+    return tag ? [tag] : null;
+  }
+  if (Array.isArray(value)) {
+    const tags = value.filter(
+      (tag) => typeof tag === "string" && tag.trim().length > 0
+    );
+    return tags.length > 0 ? tags.map((tag) => tag.trim()) : null;
+  }
+  return null;
+}
+function commonAgent(agents) {
+  const first = agents[0];
+  return first && agents.every((agent) => agent === first) ? first : null;
+}
+function commonTags(metadata) {
+  const tags = /* @__PURE__ */ new Set();
+  for (const item of metadata) {
+    for (const tag of telemetryTags(item) ?? []) tags.add(tag);
+  }
+  return tags.size > 0 ? [...tags] : null;
+}
 
 // src/filters/types.ts
 var meta = {
@@ -4057,7 +5742,11 @@ function sqlite(connectionString) {
   return new SqliteStorageProvider({ connectionString });
 }
 function sqliteConfig(connectionString) {
-  return { provider: "sqlite", connectionString };
+  return {
+    provider: "sqlite",
+    connectionString,
+    url: connectionString
+  };
 }
 function postgres(options) {
   const opts = typeof options === "string" ? { connectionString: options } : options;
@@ -4067,9 +5756,31 @@ function postgresConfig(connectionString, options) {
   return {
     provider: "postgres",
     connectionString,
+    url: connectionString,
     ...options
   };
 }
+function sqliteTelemetry(url) {
+  return new SqliteTelemetryProvider({ url });
+}
+function sqliteCheckpoint(directory) {
+  return new SqliteCheckpointProvider({ directory });
+}
+function createTelemetryProvider(config) {
+  if (config.database.provider !== "sqlite") {
+    throw new ConfigurationError(
+      `Unsupported telemetry provider "${config.database.provider}". Only "sqlite" is implemented in v0.3.0.`
+    );
+  }
+  const url = config.database.url ?? config.database.connectionString ?? "";
+  if (!url) {
+    throw new ConfigurationError("telemetry.database.url is required");
+  }
+  return new SqliteTelemetryProvider({ url });
+}
+function wolbarg2(options) {
+  return new Wolbarg(options);
+}
 
 // src/keyword/index.ts
 var Bm25KeywordSearchProvider = class {
@@ -4465,6 +6176,56 @@ function openaiVision(options) {
   });
 }
 
-export { CompressionError, ConfigurationError, DatabaseError, EmbeddingError, FixedChunkingStrategy, HeadingChunkingStrategy, InitializationError, LlmCompressionProvider, MarkdownChunkingStrategy, MemoryNotFoundError, ParagraphChunkingStrategy, PostgresStorageProvider, ProviderNotConfiguredError, SentenceChunkingStrategy, SqliteDatabaseProvider, SqliteStorageProvider, ValidationError, Wolbarg, WolbargError, bgeReranker, bm25, cohereReranker, createChunkingStrategy, createCompressionProvider, createDatabaseProvider, createEmbeddingProvider, createLlmProvider, createStorageProvider, crossEncoder, geminiEmbedding, geminiVision, jinaReranker, lmStudioEmbedding, meta, ollamaEmbedding, ollamaLlm, openRouterEmbedding, openRouterLlm, openaiCompatibleEmbedding, openaiCompatibleLlm, openaiEmbedding, openaiLlm, openaiReranker, openaiVision, postgres, postgresConfig, sqlite, sqliteConfig, tesseract, togetherEmbedding, vllmEmbedding };
+// src/benchmark/index.ts
+async function runBenchmark(name, iterations, fn) {
+  const samples = [];
+  for (let i = 0; i < iterations; i += 1) {
+    const t0 = performance.now();
+    try {
+      await fn();
+      samples.push({
+        name,
+        durationMs: performance.now() - t0,
+        ok: true
+      });
+    } catch (error) {
+      samples.push({
+        name,
+        durationMs: performance.now() - t0,
+        ok: false,
+        error: error instanceof Error ? error.message : String(error)
+      });
+    }
+  }
+  return samples;
+}
+function summarizeBenchmark(samples, startedAt, finishedAt) {
+  const durations = samples.filter((s) => s.ok).map((s) => s.durationMs).sort((a, b) => a - b);
+  const avg = durations.length === 0 ? 0 : durations.reduce((a, b) => a + b, 0) / durations.length;
+  return {
+    startedAt,
+    finishedAt,
+    samples,
+    summary: {
+      count: samples.length,
+      ok: samples.filter((s) => s.ok).length,
+      failed: samples.filter((s) => !s.ok).length,
+      avgMs: avg,
+      p50Ms: percentile(durations, 0.5),
+      p95Ms: percentile(durations, 0.95),
+      p99Ms: percentile(durations, 0.99)
+    }
+  };
+}
+function percentile(sorted, p) {
+  if (sorted.length === 0) return 0;
+  const idx = Math.min(
+    sorted.length - 1,
+    Math.max(0, Math.ceil(p * sorted.length) - 1)
+  );
+  return sorted[idx];
+}
+
+export { CompressionError, ConfigurationError, DatabaseError, EmbeddingError, FixedChunkingStrategy, HeadingChunkingStrategy, InitializationError, LlmCompressionProvider, MarkdownChunkingStrategy, MemoryNotFoundError, NoopTelemetryProvider, ParagraphChunkingStrategy, PostgresStorageProvider, ProviderNotConfiguredError, SentenceChunkingStrategy, SqliteCheckpointProvider, SqliteDatabaseProvider, SqliteEventDatabase, SqliteStorageProvider, SqliteTelemetryProvider, TelemetryEmitter, ValidationError, Wolbarg, WolbargError, WolbargLogger, bgeReranker, bm25, cohereReranker, createChunkingStrategy, createCompressionProvider, createDatabaseProvider, createEmbeddingProvider, createLlmProvider, createStorageProvider, createTelemetryProvider, wolbarg2 as createWolbarg, crossEncoder, geminiEmbedding, geminiVision, jinaReranker, lmStudioEmbedding, meta, ollamaEmbedding, ollamaLlm, openRouterEmbedding, openRouterLlm, openaiCompatibleEmbedding, openaiCompatibleLlm, openaiEmbedding, openaiLlm, openaiReranker, openaiVision, postgres, postgresConfig, runBenchmark, sqlite, sqliteCheckpoint, sqliteConfig, sqliteTelemetry, summarizeBenchmark, tesseract, togetherEmbedding, vllmEmbedding, wolbarg, wrapOperationError };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map