wolbarg 0.3.0 → 0.3.2

package/dist/index.cjs

@@ -1,8 +1,8 @@
 'use strict';
 
+var path5 = require("node:path");
 var fs = require('fs/promises');
-var path2 = require("node:path");
-var fs2 = require("node:fs");
+var fs5 = require("node:fs");
 var sqlite$1 = require("node:sqlite");
 var sqliteVec = require('sqlite-vec');
 var async_hooks = require('async_hooks');
@@ -27,18 +27,26 @@ function _interopNamespace(e) {
   return Object.freeze(n);
 }
 
+var path5__default = /*#__PURE__*/_interopDefault(path5);
 var fs__default = /*#__PURE__*/_interopDefault(fs);
-var path2__default = /*#__PURE__*/_interopDefault(path2);
-var fs2__default = /*#__PURE__*/_interopDefault(fs2);
+var fs5__default = /*#__PURE__*/_interopDefault(fs5);
 var sqliteVec__namespace = /*#__PURE__*/_interopNamespace(sqliteVec);
 
+// 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);
   }
 };
@@ -87,13 +95,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.
@@ -351,9 +404,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}`;
 }
 
@@ -650,7 +703,7 @@ function extOf(filename) {
   if (!filename) {
     return "";
   }
-  return path2__default.default.extname(filename).toLowerCase();
+  return path5__default.default.extname(filename).toLowerCase();
 }
 var TextParser = class {
   name = "text";
@@ -795,13 +848,31 @@ async function loadIngestSource(source) {
     const buffer = await fs__default.default.readFile(source.path);
     return {
       buffer,
-      filename: path2__default.default.basename(source.path),
+      filename: path5__default.default.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(".");
@@ -1283,12 +1354,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__default.default.mkdirSync(path2__default.default.dirname(dbPath), { recursive: true });
+        fs5__default.default.mkdirSync(path5__default.default.dirname(dbPath), { recursive: true });
       }
       const db = new sqlite$1.DatabaseSync(dbPath, { allowExtension: true });
       this.db = db;
@@ -1749,11 +1824,11 @@ var SqliteStorageProvider = class {
     }
     const dbPath = this.resolvedPath ?? this.resolvePath(this.connectionString);
     try {
-      let total = fs2__default.default.statSync(dbPath).size;
+      let total = fs5__default.default.statSync(dbPath).size;
       for (const suffix of ["-wal", "-shm"]) {
         const side = `${dbPath}${suffix}`;
-        if (fs2__default.default.existsSync(side)) {
-          total += fs2__default.default.statSync(side).size;
+        if (fs5__default.default.existsSync(side)) {
+          total += fs5__default.default.statSync(side).size;
         }
       }
       return total;
@@ -2084,7 +2159,7 @@ var SqliteStorageProvider = class {
     if (connectionString === ":memory:") {
       return ":memory:";
     }
-    return path2__default.default.isAbsolute(connectionString) ? connectionString : path2__default.default.resolve(process.cwd(), connectionString);
+    return path5__default.default.isAbsolute(connectionString) ? connectionString : path5__default.default.resolve(process.cwd(), connectionString);
   }
   requireDb() {
     if (!this.db) {
@@ -3148,14 +3223,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
     });
   }
@@ -3166,6 +3247,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__default.default.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__default.default.mkdirSync(path5__default.default.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__default.default.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2), "utf8");
+    return {
+      path: dbExportPath,
+      manifest,
+      sizeBytes: fs5__default.default.statSync(dbExportPath).size
+    };
+  }
+  async importFrom(exportPath, targetPath) {
+    const resolvedExport = resolvePath(exportPath);
+    const dbExportPath = resolvedExport.endsWith(".db") ? resolvedExport : fs5__default.default.existsSync(`${resolvedExport}.db`) ? `${resolvedExport}.db` : resolvedExport;
+    if (!fs5__default.default.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__default.default.existsSync(manifestPath)) {
+      manifest = JSON.parse(fs5__default.default.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__default.default.existsSync(side)) {
+        fs5__default.default.rmSync(side, { force: true });
+      }
+    }
+    await copySqlite(dbExportPath, resolvedTarget);
+    return { path: resolvedTarget, manifest };
+  }
+};
+async function copySqlite(sourcePath, destPath) {
+  fs5__default.default.mkdirSync(path5__default.default.dirname(destPath), { recursive: true });
+  let source = null;
+  let dest = null;
+  try {
+    source = new sqlite$1.DatabaseSync(sourcePath);
+    try {
+      source.exec("PRAGMA wal_checkpoint(TRUNCATE);");
+    } catch {
+    }
+    dest = new sqlite$1.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__default.default.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__default.default.isAbsolute(p) ? p : path5__default.default.resolve(process.cwd(), p);
+}
 
 // src/memory/index.ts
 function toMemoryRecord(row) {
@@ -3291,17 +3495,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) {
@@ -3354,6 +3547,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");
@@ -3362,16 +3613,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");
   }
@@ -3379,31 +3621,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");
@@ -3414,82 +3657,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__default.default.mkdirSync(path5__default.default.dirname(dbPath), { recursive: true });
+      }
+      const db = new sqlite$1.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__default.default.isAbsolute(url) ? url : path5__default.default.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__default.default.resolve(process.cwd(), ".wolbarg", "checkpoints");
+  }
+  async open() {
+    fs5__default.default.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__default.default.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__default.default.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__default.default.statSync(snapshotPath);
+    const meta2 = {
+      name,
+      description: options?.description ?? null,
+      createdAt: nowIso(),
+      sdkVersion: SDK_VERSION2,
+      provider: this.name,
+      snapshotPath,
+      sourcePath: resolvedSource,
+      sizeBytes: stats.size
+    };
+    fs5__default.default.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__default.default.mkdirSync(path5__default.default.dirname(resolvedTarget), { recursive: true });
+    for (const suffix of ["", "-wal", "-shm"]) {
+      const side = `${resolvedTarget}${suffix}`;
+      if (fs5__default.default.existsSync(side)) {
+        fs5__default.default.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__default.default.existsSync(metaPath)) {
+      fs5__default.default.rmSync(metaPath, { force: true });
+      removed = true;
+    }
+    if (fs5__default.default.existsSync(snapshotPath)) {
+      fs5__default.default.rmSync(snapshotPath, { force: true });
+      removed = true;
+    }
+    return removed;
+  }
+  async listCheckpoints() {
+    this.requireReady();
+    if (!fs5__default.default.existsSync(this.directory)) {
+      return [];
+    }
+    const files = fs5__default.default.readdirSync(this.directory).filter((f) => f.endsWith(".json"));
+    const out = [];
+    for (const file of files) {
+      try {
+        const raw = fs5__default.default.readFileSync(path5__default.default.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__default.default.existsSync(metaPath)) {
+      return null;
+    }
+    try {
+      return JSON.parse(fs5__default.default.readFileSync(metaPath, "utf8"));
+    } catch {
+      return null;
+    }
+  }
+  metaPath(name) {
+    return path5__default.default.join(this.directory, `${sanitize(name)}.json`);
+  }
+  snapshotPath(name) {
+    return path5__default.default.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__default.default.isAbsolute(connectionString) ? connectionString : path5__default.default.resolve(process.cwd(), connectionString);
+}
+async function safeSqliteBackup(sourcePath, destPath) {
+  fs5__default.default.mkdirSync(path5__default.default.dirname(destPath), { recursive: true });
+  if (fs5__default.default.existsSync(destPath)) {
+    fs5__default.default.rmSync(destPath, { force: true });
+  }
+  let source = null;
+  let dest = null;
+  try {
+    source = new sqlite$1.DatabaseSync(sourcePath);
+    try {
+      source.exec("PRAGMA wal_checkpoint(TRUNCATE);");
+    } catch {
+    }
+    dest = new sqlite$1.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__default.default.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) {
@@ -3511,12 +4682,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;
@@ -3529,484 +4704,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();
     }
@@ -4018,7 +5655,6 @@ var Wolbarg = class {
     this.embeddingDimensions = null;
     this.initialized = false;
   }
-  /** Whether providers are ready for API calls. */
   get isInitialized() {
     return this.initialized;
   }
@@ -4042,7 +5678,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__default.default.isAbsolute(this.memoryDbPath) ? this.memoryDbPath : path5__default.default.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 = {
@@ -4084,7 +5769,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;
@@ -4094,9 +5783,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 {
@@ -4492,6 +6203,56 @@ function openaiVision(options) {
   });
 }
 
+// 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];
+}
+
 exports.CompressionError = CompressionError;
 exports.ConfigurationError = ConfigurationError;
 exports.DatabaseError = DatabaseError;
@@ -4502,15 +6263,21 @@ exports.InitializationError = InitializationError;
 exports.LlmCompressionProvider = LlmCompressionProvider;
 exports.MarkdownChunkingStrategy = MarkdownChunkingStrategy;
 exports.MemoryNotFoundError = MemoryNotFoundError;
+exports.NoopTelemetryProvider = NoopTelemetryProvider;
 exports.ParagraphChunkingStrategy = ParagraphChunkingStrategy;
 exports.PostgresStorageProvider = PostgresStorageProvider;
 exports.ProviderNotConfiguredError = ProviderNotConfiguredError;
 exports.SentenceChunkingStrategy = SentenceChunkingStrategy;
+exports.SqliteCheckpointProvider = SqliteCheckpointProvider;
 exports.SqliteDatabaseProvider = SqliteDatabaseProvider;
+exports.SqliteEventDatabase = SqliteEventDatabase;
 exports.SqliteStorageProvider = SqliteStorageProvider;
+exports.SqliteTelemetryProvider = SqliteTelemetryProvider;
+exports.TelemetryEmitter = TelemetryEmitter;
 exports.ValidationError = ValidationError;
 exports.Wolbarg = Wolbarg;
 exports.WolbargError = WolbargError;
+exports.WolbargLogger = WolbargLogger;
 exports.bgeReranker = bgeReranker;
 exports.bm25 = bm25;
 exports.cohereReranker = cohereReranker;
@@ -4520,6 +6287,8 @@ exports.createDatabaseProvider = createDatabaseProvider;
 exports.createEmbeddingProvider = createEmbeddingProvider;
 exports.createLlmProvider = createLlmProvider;
 exports.createStorageProvider = createStorageProvider;
+exports.createTelemetryProvider = createTelemetryProvider;
+exports.createWolbarg = wolbarg2;
 exports.crossEncoder = crossEncoder;
 exports.geminiEmbedding = geminiEmbedding;
 exports.geminiVision = geminiVision;
@@ -4538,10 +6307,16 @@ exports.openaiReranker = openaiReranker;
 exports.openaiVision = openaiVision;
 exports.postgres = postgres;
 exports.postgresConfig = postgresConfig;
+exports.runBenchmark = runBenchmark;
 exports.sqlite = sqlite;
+exports.sqliteCheckpoint = sqliteCheckpoint;
 exports.sqliteConfig = sqliteConfig;
+exports.sqliteTelemetry = sqliteTelemetry;
+exports.summarizeBenchmark = summarizeBenchmark;
 exports.tesseract = tesseract;
 exports.togetherEmbedding = togetherEmbedding;
 exports.vllmEmbedding = vllmEmbedding;
+exports.wolbarg = wolbarg;
+exports.wrapOperationError = wrapOperationError;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map