wolbarg 0.5.4 → 0.5.6

package/dist/index.js

@@ -1,5 +1,5 @@
-import fs6 from "node:fs";
-import path7 from "node:path";
+import fs6, { existsSync, readFileSync, mkdirSync, writeFileSync } from "node:fs";
+import path7, { isAbsolute, resolve, dirname, join } from "node:path";
 import { createHash } from 'crypto';
 import fs from 'fs/promises';
 import { DatabaseSync } from "node:sqlite";
@@ -15,6 +15,11 @@ var WolbargError = class extends Error {
   reason;
   suggestion;
   operation;
+  /**
+   * @param message - Human-readable error message.
+   * @param code - Stable error code string.
+   * @param options - Optional cause, reason, suggestion, and operation name.
+   */
   constructor(message, code, options) {
     super(message, options);
     this.name = "WolbargError";
@@ -26,48 +31,80 @@ var WolbargError = class extends Error {
   }
 };
 var InitializationError = class extends WolbargError {
+  /**
+   * @param message - Description of the initialization failure.
+   * @param options - Optional cause and structured hints.
+   */
   constructor(message, options) {
     super(message, "INITIALIZATION_ERROR", options);
     this.name = "InitializationError";
   }
 };
 var ConfigurationError = class extends WolbargError {
+  /**
+   * @param message - Description of the misconfiguration.
+   * @param options - Optional cause, reason, suggestion, and operation name.
+   */
   constructor(message, options) {
     super(message, "CONFIGURATION_ERROR", options);
     this.name = "ConfigurationError";
   }
 };
 var ValidationError = class extends WolbargError {
+  /**
+   * @param message - Which argument failed and why.
+   * @param options - Optional cause and structured hints.
+   */
   constructor(message, options) {
     super(message, "VALIDATION_ERROR", options);
     this.name = "ValidationError";
   }
 };
 var DatabaseError = class extends WolbargError {
+  /**
+   * @param message - Operation-scoped failure message.
+   * @param options - Optional underlying `cause` and hints.
+   */
   constructor(message, options) {
     super(message, "DATABASE_ERROR", options);
     this.name = "DatabaseError";
   }
 };
 var StorageLockedError = class extends WolbargError {
+  /**
+   * @param message - Lock contention description.
+   * @param options - Typically includes suggestion to tune concurrency or use Postgres.
+   */
   constructor(message, options) {
     super(message, "WOLBARG_STORAGE_LOCKED", options);
     this.name = "StorageLockedError";
   }
 };
 var EmbeddingError = class extends WolbargError {
+  /**
+   * @param message - Embedding failure description.
+   * @param options - Optional HTTP cause and provider hints.
+   */
   constructor(message, options) {
     super(message, "EMBEDDING_ERROR", options);
     this.name = "EmbeddingError";
   }
 };
 var CompressionError = class extends WolbargError {
+  /**
+   * @param message - Compression failure description.
+   * @param options - Optional LLM cause chain.
+   */
   constructor(message, options) {
     super(message, "COMPRESSION_ERROR", options);
     this.name = "CompressionError";
   }
 };
 var MemoryNotFoundError = class extends WolbargError {
+  /**
+   * @param message - Which memory was not found.
+   * @param options - Optional operation context.
+   */
   constructor(message, options) {
     super(message, "MEMORY_NOT_FOUND", options);
     this.name = "MemoryNotFoundError";
@@ -75,6 +112,11 @@ var MemoryNotFoundError = class extends WolbargError {
 };
 var ProviderNotConfiguredError = class extends ConfigurationError {
   provider;
+  /**
+   * @param provider - Provider name (e.g. `"reranker"`, `"graph"`).
+   * @param method - Facade method that requires the provider.
+   * @param hint - Install or config instruction shown to the developer.
+   */
   constructor(provider, method, hint) {
     super(`${method} requires ${provider} \u2014 ${hint}`, {
       operation: method,
@@ -86,6 +128,10 @@ var ProviderNotConfiguredError = class extends ConfigurationError {
   }
 };
 var GraphCheckpointNotSupportedError = class extends WolbargError {
+  /**
+   * @param backend - Graph backend name (e.g. `"neo4j"`).
+   * @param operation - Requested operation (e.g. `"checkpoint"`).
+   */
   constructor(backend, operation) {
     super(
       `graph checkpoint not supported for network-backed graph providers (${backend})`,
@@ -158,9 +204,11 @@ Rules:
 var LlmCompressionProvider = class {
   name = "llm";
   llm;
+  /** @param llm - Configured LLM used for summarization. */
   constructor(llm) {
     this.llm = llm;
   }
+  /** @inheritdoc */
   async compress(memories) {
     return compressMemories(this.llm, memories);
   }
@@ -269,6 +317,7 @@ function slidingWindow(text, chunkSize, overlap) {
 }
 var FixedChunkingStrategy = class {
   name = "fixed";
+  /** @inheritdoc */
   chunk(text, options) {
     const { chunkSize, overlap } = clampOptions(options);
     return slidingWindow(text, chunkSize, overlap);
@@ -276,6 +325,7 @@ var FixedChunkingStrategy = class {
 };
 var SentenceChunkingStrategy = class {
   name = "sentence";
+  /** @inheritdoc */
   chunk(text, options) {
     const { chunkSize, overlap } = clampOptions(options);
     const sentences = text.split(/(?<=[.!?])\s+/).map((s) => s.trim()).filter(Boolean);
@@ -284,6 +334,7 @@ var SentenceChunkingStrategy = class {
 };
 var ParagraphChunkingStrategy = class {
   name = "paragraph";
+  /** @inheritdoc */
   chunk(text, options) {
     const { chunkSize, overlap } = clampOptions(options);
     const paragraphs = text.split(/\n\s*\n/).map((p) => p.trim()).filter(Boolean);
@@ -292,6 +343,7 @@ var ParagraphChunkingStrategy = class {
 };
 var MarkdownChunkingStrategy = class {
   name = "markdown";
+  /** @inheritdoc */
   chunk(text, options) {
     const { chunkSize, overlap } = clampOptions(options);
     const sections = text.split(/(?=^#{1,6}\s)/m).map((s) => s.trim()).filter(Boolean);
@@ -303,6 +355,7 @@ var MarkdownChunkingStrategy = class {
 };
 var HeadingChunkingStrategy = class {
   name = "heading";
+  /** @inheritdoc */
   chunk(text, options) {
     return new MarkdownChunkingStrategy().chunk(text, options);
   }
@@ -384,10 +437,16 @@ function distanceToSimilarity(distance) {
 }
 var AsyncMutex = class {
   chain = Promise.resolve();
+  /**
+   * Run `fn` exclusively — concurrent callers queue on the same mutex.
+   *
+   * @param fn - Async or sync work to serialize.
+   * @returns The value returned by `fn`.
+   */
   async runExclusive(fn) {
     let release;
-    const next = new Promise((resolve) => {
-      release = resolve;
+    const next = new Promise((resolve3) => {
+      release = resolve3;
     });
     const previous = this.chain;
     this.chain = previous.then(() => next);
@@ -407,16 +466,32 @@ function joinUrl(baseUrl, path8) {
 
 // src/embedding/index.ts
 var OpenAICompatibleEmbeddingProvider = class {
+  /** Model name sent in the request body. */
   model;
   baseUrl;
   apiKey;
   timeoutMs;
+  /**
+   * @param config - OpenAI-compatible embedding endpoint settings.
+   * @param config.baseUrl - API root, e.g. `https://api.openai.com/v1`.
+   * @param config.apiKey - Bearer token. Use any non-empty string for local
+   *   servers that ignore auth.
+   * @param config.model - Embedding model id (e.g. `"text-embedding-3-small"`).
+   * @param config.timeoutMs - Abort after this many ms. Defaults to `30_000`.
+   */
   constructor(config) {
     this.baseUrl = config.baseUrl;
     this.apiKey = config.apiKey;
     this.model = config.model;
     this.timeoutMs = config.timeoutMs ?? 3e4;
   }
+  /**
+   * Embed a single string.
+   *
+   * @param text - Input text.
+   * @returns Embedding vector.
+   * @throws {EmbeddingError} On HTTP errors, timeouts, or empty vectors.
+   */
   async embed(text) {
     const response = await this.request(text);
     const vector = response.data?.[0]?.embedding;
@@ -425,6 +500,13 @@ var OpenAICompatibleEmbeddingProvider = class {
     }
     return Float32Array.from(vector);
   }
+  /**
+   * Embed multiple strings in one API call when the server supports batch input.
+   * Falls back to sequential {@link embed} if the response length mismatches.
+   *
+   * @param texts - Inputs to embed.
+   * @returns One vector per input, same order.
+   */
   async embedBatch(texts) {
     if (texts.length === 0) {
       return [];
@@ -451,6 +533,12 @@ var OpenAICompatibleEmbeddingProvider = class {
       return Float32Array.from(item.embedding);
     });
   }
+  /**
+   * Probe the endpoint and report vector dimensionality.
+   *
+   * @returns `{ dimensions }` from a fixed health-check string.
+   * @throws {EmbeddingError} When the probe fails.
+   */
   async validate() {
     try {
       const embedding = await this.embed("Wolbarg health check");
@@ -465,6 +553,12 @@ var OpenAICompatibleEmbeddingProvider = class {
       );
     }
   }
+  /**
+   * Low-level HTTP request to `/embeddings`.
+   *
+   * @param input - Single string or batch of strings.
+   * @returns Parsed OpenAI-style JSON body.
+   */
   async request(input) {
     const url = joinUrl(this.baseUrl, "/embeddings");
     const controller = new AbortController();
@@ -512,6 +606,7 @@ var OpenAICompatibleEmbeddingProvider = class {
       clearTimeout(timer);
     }
   }
+  /** @param error - Unknown thrown value. @returns Human-readable message. */
   describe(error) {
     if (error instanceof Error) {
       return error.message;
@@ -768,6 +863,10 @@ var SqliteEmbeddingCacheStore = class {
   pendingSets = /* @__PURE__ */ new Map();
   persistScheduled = false;
   stmts = null;
+  /**
+   * @param dbOrGetter - SQLite `DatabaseSync` or lazy getter (allows late bind).
+   * @param options.ttlMs - Optional TTL for cache entries on read.
+   */
   constructor(dbOrGetter, options) {
     this.ttlMs = options?.ttlMs ?? null;
     this.getDb = typeof dbOrGetter === "function" ? dbOrGetter : () => dbOrGetter;
@@ -1044,12 +1143,23 @@ var PostgresEmbeddingCacheStore = class {
 
 // src/llm/index.ts
 var OpenAICompatibleLlmProvider = class {
+  /** Model name sent in the request body and exposed on the provider. */
   model;
   baseUrl;
   apiKey;
   temperature;
   maxTokens;
   timeoutMs;
+  /**
+   * @param config - OpenAI-compatible endpoint settings.
+   * @param config.baseUrl - API root, e.g. `https://api.openai.com/v1` (no trailing `/chat/completions`).
+   * @param config.apiKey - Bearer token (`Authorization: Bearer …`). Use any non-empty
+   *   string for local servers that ignore auth (e.g. `"ollama"`).
+   * @param config.model - Chat model id (e.g. `"gpt-4o-mini"`, `"llama3.2"`).
+   * @param config.temperature - Sampling temperature. Defaults to `0.2`.
+   * @param config.maxTokens - Max completion tokens. Defaults to `4096`.
+   * @param config.timeoutMs - Abort after this many ms. Defaults to `60_000`.
+   */
   constructor(config) {
     this.baseUrl = config.baseUrl;
     this.apiKey = config.apiKey;
@@ -1058,6 +1168,13 @@ var OpenAICompatibleLlmProvider = class {
     this.maxTokens = config.maxTokens ?? 4096;
     this.timeoutMs = config.timeoutMs ?? 6e4;
   }
+  /**
+   * Call `/chat/completions` and return the first choice’s message content.
+   *
+   * @param messages - Chat turns in OpenAI message format.
+   * @returns Trimmed assistant text.
+   * @throws {CompressionError} On HTTP errors, timeouts, or empty content.
+   */
   async complete(messages) {
     const response = await this.request(messages);
     const content = response.choices?.[0]?.message?.content;
@@ -1066,6 +1183,11 @@ var OpenAICompatibleLlmProvider = class {
     }
     return content.trim();
   }
+  /**
+   * Probe the endpoint with a fixed `"ok"` prompt.
+   *
+   * @throws {CompressionError} When validation fails.
+   */
   async validate() {
     try {
       await this.complete([
@@ -1087,6 +1209,12 @@ var OpenAICompatibleLlmProvider = class {
       );
     }
   }
+  /**
+   * Low-level HTTP request to `/chat/completions`.
+   *
+   * @param messages - Chat turns to send.
+   * @returns Parsed OpenAI-style JSON body.
+   */
   async request(messages) {
     const url = joinUrl(this.baseUrl, "/chat/completions");
     const controller = new AbortController();
@@ -1135,6 +1263,7 @@ var OpenAICompatibleLlmProvider = class {
       clearTimeout(timer);
     }
   }
+  /** @param error - Unknown thrown value. @returns Human-readable message. */
   describe(error) {
     if (error instanceof Error) {
       return error.message;
@@ -1530,28 +1659,48 @@ var LEVEL_ORDER = {
   trace: 10
 };
 var WolbargLogger = class {
+  /** @param level - Minimum level to print (default `"info"`). */
   constructor(level = "info") {
     this.level = level;
   }
   level;
+  /** Change the minimum log level at runtime. */
   setLevel(level) {
     this.level = level;
   }
+  /** @returns Current minimum log level. */
   getLevel() {
     return this.level;
   }
+  /** Log at error level. */
   error(message, extra) {
     this.write("error", message, extra);
   }
+  /** Log at warn level.
+   * @param message - Primary log line.
+   * @param extra - Optional structured payload.
+   */
   warn(message, extra) {
     this.write("warn", message, extra);
   }
+  /** Log at info level.
+   * @param message - Primary log line.
+   * @param extra - Optional structured payload.
+   */
   info(message, extra) {
     this.write("info", message, extra);
   }
+  /** Log at debug level.
+   * @param message - Primary log line.
+   * @param extra - Optional structured payload.
+   */
   debug(message, extra) {
     this.write("debug", message, extra);
   }
+  /** Log at trace level.
+   * @param message - Primary log line.
+   * @param extra - Optional structured payload.
+   */
   trace(message, extra) {
     this.write("trace", message, extra);
   }
@@ -1894,18 +2043,29 @@ var InMemoryVectorIndex = class {
   data;
   count = 0;
   rowidToSlot = /* @__PURE__ */ new Map();
+  /**
+   * @param dimensions - Embedding vector length.
+   * @param initialCapacity - Initial slot capacity (default `256`).
+   */
   constructor(dimensions, initialCapacity = 256) {
     this.dims = dimensions;
     this.data = new Float32Array(initialCapacity * dimensions);
   }
+  /** Number of indexed vectors. */
   get size() {
     return this.count;
   }
+  /** Remove all vectors from the index. */
   clear() {
     this.rowids.length = 0;
     this.rowidToSlot.clear();
     this.count = 0;
   }
+  /**
+   * Insert or replace a vector for `rowid` (L2-normalized internally).
+   * @param rowid - Memory table row identifier.
+   * @param embedding - Raw embedding vector.
+   */
   upsert(rowid, embedding) {
     const existing = this.rowidToSlot.get(rowid);
     const slot = existing !== void 0 ? existing : (() => {
@@ -1936,6 +2096,10 @@ var InMemoryVectorIndex = class {
       }
     }
   }
+  /**
+   * Remove a vector by `rowid`.
+   * @param rowid - Memory table row identifier.
+   */
   remove(rowid) {
     const slot = this.rowidToSlot.get(rowid);
     if (slot === void 0) {
@@ -1955,7 +2119,12 @@ var InMemoryVectorIndex = class {
     this.rowidToSlot.delete(rowid);
     this.count = last;
   }
-  /** Top-k by cosine distance (1 - dot) assuming query is L2-normalized. */
+  /**
+   * Top-k by cosine distance (1 - dot) assuming query is L2-normalized.
+   *
+   * @param queryNormalized - L2-normalized query vector (use {@link normalizeEmbedding}).
+   * @param topK - Maximum hits to return.
+   */
   search(queryNormalized, topK) {
     const n = this.count;
     if (n === 0 || topK <= 0) {
@@ -2107,7 +2276,7 @@ function isSqliteBusyError(error) {
   return lower.includes("database is locked") || lower.includes("sqlite_busy") || lower.includes("busy");
 }
 function sleep(ms) {
-  return new Promise((resolve) => setTimeout(resolve, ms));
+  return new Promise((resolve3) => setTimeout(resolve3, ms));
 }
 function backoffDelay(attempt, config) {
   const exp = Math.min(
@@ -2231,6 +2400,9 @@ var SqliteStorageProvider = class _SqliteStorageProvider {
   /** Coalesce concurrent insertMemory callers into one IMMEDIATE transaction. */
   insertQueue = [];
   insertFlushScheduled = false;
+  /**
+   * @param options - SQLite path / `:memory:` and optional concurrency config.
+   */
   constructor(options) {
     this.connectionString = options.connectionString;
     this.concurrency = resolveConcurrencyConfig(options.concurrency);
@@ -2243,9 +2415,11 @@ var SqliteStorageProvider = class _SqliteStorageProvider {
   getDatabase() {
     return this.db;
   }
+  /** Register a callback invoked when SQLite busy retries occur (tests / diagnostics). */
   setRetryLogger(fn) {
     this.retryLog = fn;
   }
+  /** Open the database, run migrations, and prepare statements. */
   async open() {
     try {
       const dbPath = this.resolvePath(this.connectionString);
@@ -2305,6 +2479,7 @@ var SqliteStorageProvider = class _SqliteStorageProvider {
       );
     }
   }
+  /** Drain pending inserts, optimize, and close the SQLite connection. */
   async close() {
     const deadline = Date.now() + 2e3;
     while (this.insertQueue.length > 0 && Date.now() < deadline) {
@@ -2335,6 +2510,11 @@ var SqliteStorageProvider = class _SqliteStorageProvider {
       this.batchBlobEmbStatements.clear();
     }
   }
+  /**
+   * Create or validate vec0 / blob vector storage for the given dimensionality.
+   *
+   * @param dimensions - Embedding length from the configured model.
+   */
   async ensureVectorSchema(dimensions) {
     const existing = await this.getEmbeddingDimensions();
     if (existing !== null && existing !== dimensions) {
@@ -2357,17 +2537,20 @@ var SqliteStorageProvider = class _SqliteStorageProvider {
     this.reprepareVectorStatements();
     this.hydrateMemoryIndex();
   }
+  /** @inheritdoc StorageProvider.getEmbeddingDimensions */
   async getEmbeddingDimensions() {
     return this.readMetaNumber(META_KEYS.embeddingDimensions);
   }
+  /** @inheritdoc StorageProvider.setEmbeddingDimensions */
   async setEmbeddingDimensions(dimensions) {
     await this.setMeta(META_KEYS.embeddingDimensions, String(dimensions));
     this.vectorDimensions = dimensions;
   }
+  /** Insert a single memory row (coalesced under concurrent writers). */
   async insertMemory(input) {
     this.requireVectorReady();
-    return new Promise((resolve, reject) => {
-      this.insertQueue.push({ input, resolve, reject });
+    return new Promise((resolve3, reject) => {
+      this.insertQueue.push({ input, resolve: resolve3, reject });
       if (this.insertQueue.length >= INSERT_COALESCE_THRESHOLD) {
         this.insertFlushScheduled = false;
         void this.flushInsertQueue();
@@ -2445,6 +2628,7 @@ var SqliteStorageProvider = class _SqliteStorageProvider {
       return row;
     });
   }
+  /** Batch insert memories in chunked multi-row transactions. */
   async insertMemoriesBatch(inputs) {
     if (inputs.length === 0) {
       return [];
@@ -2460,6 +2644,7 @@ var SqliteStorageProvider = class _SqliteStorageProvider {
       return rows;
     });
   }
+  /** Update memory content, metadata, embedding, and content hash. */
   async updateMemory(input) {
     const stmts = this.requireStatements();
     return this.withTransaction(() => {
@@ -2503,6 +2688,7 @@ var SqliteStorageProvider = class _SqliteStorageProvider {
       return stmts.getMemoryById.get(input.id, input.organization);
     });
   }
+  /** Find an active memory by org, agent, and content hash (dedupe). */
   async findActiveByContentHash(organization, agent, contentHash) {
     const stmts = this.requireStatements();
     const row = stmts.findActiveByContentHash.get(
@@ -2512,6 +2698,7 @@ var SqliteStorageProvider = class _SqliteStorageProvider {
     );
     return row ?? null;
   }
+  /** Scan memories matching metadata filters (may paginate in SQL). */
   async searchByMetadata(filter, limit) {
     const rows = await this.listMemories(filter, limit);
     if (!filter.metadata) {
@@ -2522,6 +2709,7 @@ var SqliteStorageProvider = class _SqliteStorageProvider {
     );
   }
   /** Keyword search via FTS5 BM25. Returns memory IDs ranked by relevance. */
+  /** BM25 keyword search via FTS5 (`memories_fts`). */
   async searchKeyword(query, organization, topK) {
     const stmts = this.requireStatements();
     if (!stmts.searchFts) {
@@ -2557,16 +2745,19 @@ var SqliteStorageProvider = class _SqliteStorageProvider {
       return [];
     }
   }
+  /** Fetch a memory row by UUID within an organization. */
   async getMemoryById(id, organization) {
     const stmts = this.requireStatements();
     const row = stmts.getMemoryById.get(id, organization);
     return row ?? null;
   }
+  /** Fetch a memory row by SQLite integer rowid within an organization. */
   async getMemoryByRowid(rowid, organization) {
     const stmts = this.requireStatements();
     const row = stmts.getMemoryByRowid.get(rowid, organization);
     return row ?? null;
   }
+  /** Batch-fetch memory rows by SQLite rowids within an organization. */
   async getMemoriesByRowids(rowids, organization) {
     const out = /* @__PURE__ */ new Map();
     if (rowids.length === 0) {
@@ -2585,6 +2776,7 @@ var SqliteStorageProvider = class _SqliteStorageProvider {
     }
     return out;
   }
+  /** List memories matching repository filters with optional limit. */
   async listMemories(filter, limit) {
     try {
       if (filter.metadata) {
@@ -2597,6 +2789,7 @@ var SqliteStorageProvider = class _SqliteStorageProvider {
       });
     }
   }
+  /** Approximate nearest-neighbor search (vec0 or in-memory blob index). */
   async searchVectors(embedding, topK) {
     this.requireVectorReady();
     if (this.vectorBackend === "sqlite-vec") {
@@ -2608,6 +2801,7 @@ var SqliteStorageProvider = class _SqliteStorageProvider {
    * Org-scoped KNN + memory rows with adaptive overfetch.
    * Global ANN is post-filtered by org/agent/archived; underfill triggers larger k.
    */
+  /** ANN search joined with memory rows and org/archived post-filters. */
   async searchVectorsWithMemories(embedding, topK, organization, options) {
     this.requireVectorReady();
     if (topK <= 0) {
@@ -2646,6 +2840,7 @@ var SqliteStorageProvider = class _SqliteStorageProvider {
     }
     return out;
   }
+  /** Soft-archive memories (compression / forget paths). */
   async archiveMemories(ids, organization, compressedIntoId, archivedAt) {
     const stmts = this.requireStatements();
     const archived = [];
@@ -2683,6 +2878,7 @@ var SqliteStorageProvider = class _SqliteStorageProvider {
       return archived;
     });
   }
+  /** Hard-delete a single memory by id; returns whether a row was removed. */
   async deleteMemoryById(id, organization) {
     const stmts = this.requireStatements();
     return this.withTransaction(() => {
@@ -2696,6 +2892,7 @@ var SqliteStorageProvider = class _SqliteStorageProvider {
       return Number(result.changes) > 0;
     });
   }
+  /** Hard-delete memories matching org / agent / metadata filters. */
   async deleteMemoriesByFilter(filter) {
     const stmts = this.requireStatements();
     const agent = filter.agent;
@@ -2712,6 +2909,7 @@ var SqliteStorageProvider = class _SqliteStorageProvider {
       return Number(result.changes);
     });
   }
+  /** Remove all memories (and side tables) for an organization. */
   async clearOrganization(organization) {
     const stmts = this.requireStatements();
     return this.withTransaction(() => {
@@ -2728,10 +2926,12 @@ var SqliteStorageProvider = class _SqliteStorageProvider {
       return Number(result.changes);
     });
   }
+  /** List audit history events for a memory id. */
   async getHistory(memoryId) {
     const stmts = this.requireStatements();
     return stmts.getHistory.all(memoryId);
   }
+  /** Append a history row (created / archived / compressed / updated). */
   async insertHistoryEvent(event) {
     const stmts = this.requireStatements();
     stmts.insertHistory.run(
@@ -2742,6 +2942,7 @@ var SqliteStorageProvider = class _SqliteStorageProvider {
       event.created_at
     );
   }
+  /** Aggregate memory counts for an organization (single-pass SQL). */
   async getStats(organization) {
     const stmts = this.requireStatements();
     const row = stmts.getStats.get(organization);
@@ -2752,6 +2953,7 @@ var SqliteStorageProvider = class _SqliteStorageProvider {
       totalAgents: Number(row.agents)
     };
   }
+  /** On-disk database file size in bytes (0 for `:memory:`). */
   async getDatabaseSizeBytes() {
     const db = this.requireDb();
     if (this.connectionString === ":memory:") {
@@ -3810,11 +4012,17 @@ var PostgresSubscribeListener = class {
   reconnectDelayMs;
   connect;
   onError;
+  /**
+   * @param options.connect - Factory returning a dedicated LISTEN client.
+   * @param options.reconnectDelayMs - Delay before reconnect attempts (default 1000).
+   * @param options.onError - Optional error hook for connection failures.
+   */
   constructor(options) {
     this.connect = options.connect;
     this.reconnectDelayMs = options.reconnectDelayMs ?? 1e3;
     this.onError = options.onError;
   }
+  /** Open the LISTEN connection (lazy — also started on first subscribe). */
   async start() {
     if (this.closed) {
       return;
@@ -3911,6 +4119,13 @@ var PostgresSubscribeListener = class {
       }
     }
   }
+  /**
+   * Register a filtered callback for memory change events.
+   *
+   * @param filter - Organization / agent / event-type filter.
+   * @param callback - Invoked synchronously on each matching NOTIFY.
+   * @returns Unsubscribe function.
+   */
   subscribe(filter, callback) {
     if (this.closed) {
       throw new Error("Subscribe backend is closed");
@@ -3932,6 +4147,7 @@ var PostgresSubscribeListener = class {
    */
   emit(_event) {
   }
+  /** Tear down LISTEN connection and clear subscriptions. */
   async close() {
     this.closed = true;
     this.subscriptions.clear();
@@ -4096,6 +4312,9 @@ var PostgresStorageProvider = class _PostgresStorageProvider {
   insertFlushScheduled = false;
   insertFlushTimer = null;
   insertFlushInFlight = 0;
+  /**
+   * @param options - Connection string, pool size, and durability flags.
+   */
   constructor(options) {
     this.maxPoolSize = options.maxPoolSize ?? 64;
     this.durableWrites = options.durableWrites !== false;
@@ -4104,6 +4323,7 @@ var PostgresStorageProvider = class _PostgresStorageProvider {
       this.durableWrites
     );
   }
+  /** Current pg pool occupancy stats (for diagnostics / subscribe setup). */
   getPoolStats() {
     const pool = this.pool;
     return {
@@ -4117,6 +4337,7 @@ var PostgresStorageProvider = class _PostgresStorageProvider {
   getPool() {
     return this.pool;
   }
+  /** Open the connection pool and run migrations. */
   async open() {
     let PoolCtor;
     try {
@@ -4165,6 +4386,7 @@ var PostgresStorageProvider = class _PostgresStorageProvider {
       );
     }
   }
+  /** Drain coalesced inserts and end the connection pool. */
   async close() {
     if (this.insertFlushTimer) {
       clearTimeout(this.insertFlushTimer);
@@ -4205,6 +4427,11 @@ var PostgresStorageProvider = class _PostgresStorageProvider {
   async ensureVectorIndex() {
     await this.ensureHnswIndex();
   }
+  /**
+   * Create pgvector tables and HNSW index for the given dimensionality.
+   *
+   * @param dimensions - Embedding length from the configured model.
+   */
   async ensureVectorSchema(dimensions) {
     const existing = await this.getEmbeddingDimensions();
     if (existing !== null && existing !== dimensions) {
@@ -4269,6 +4496,11 @@ var PostgresStorageProvider = class _PostgresStorageProvider {
     }
   }
   /** Cross-process subscribe: NOTIFY after a committed write. */
+  /**
+   * Issue `pg_notify` for cross-process {@link subscribe} delivery.
+   *
+   * @param event - Memory change payload (IDs + metadata only).
+   */
   async notifyChange(event) {
     await notifyMemoryChange(this.requirePool(), event);
   }
@@ -4276,6 +4508,7 @@ var PostgresStorageProvider = class _PostgresStorageProvider {
    * Soft reset for a single organization. Drops HNSW only when the embeddings
    * table is empty so other corpora on a shared bench DB stay intact.
    */
+  /** Delete all rows for an organization (dev / test helper). */
   async resetOrganization(organization) {
     await this.query(`DELETE FROM memories WHERE organization = $1`, [
       organization
@@ -4293,6 +4526,7 @@ var PostgresStorageProvider = class _PostgresStorageProvider {
   /**
    * Wipe all Wolbarg tables (explicit opt-in). Prefer {@link resetOrganization}.
    */
+  /** Truncate all Wolbarg tables (dev / test helper). */
   async wipeAllData() {
     await this.query(`TRUNCATE TABLE memories CASCADE`).catch(() => void 0);
     await this.query(
@@ -4352,6 +4586,7 @@ var PostgresStorageProvider = class _PostgresStorageProvider {
       }
     }
   }
+  /** @inheritdoc StorageProvider.getEmbeddingDimensions */
   async getEmbeddingDimensions() {
     const result = await this.query(
       `SELECT value FROM Wolbarg_meta WHERE key = $1`,
@@ -4364,6 +4599,7 @@ var PostgresStorageProvider = class _PostgresStorageProvider {
     const parsed = Number(value);
     return Number.isFinite(parsed) ? parsed : null;
   }
+  /** @inheritdoc StorageProvider.setEmbeddingDimensions */
   async setEmbeddingDimensions(dimensions) {
     await this.query(
       `INSERT INTO Wolbarg_meta (key, value) VALUES ($1, $2)
@@ -4372,10 +4608,11 @@ var PostgresStorageProvider = class _PostgresStorageProvider {
     );
     this.vectorDimensions = dimensions;
   }
+  /** Insert a single memory row (coalesced under concurrent writers). */
   async insertMemory(input) {
     this.requireVectorReady();
-    return new Promise((resolve, reject) => {
-      this.insertQueue.push({ input, resolve, reject });
+    return new Promise((resolve3, reject) => {
+      this.insertQueue.push({ input, resolve: resolve3, reject });
       if (this.insertQueue.length >= COALESCE_FLUSH_THRESHOLD) {
         this.clearInsertFlushTimer();
         void this.flushInsertQueue();
@@ -4458,6 +4695,7 @@ var PostgresStorageProvider = class _PostgresStorageProvider {
     }
     return this.insertOneBlob(input);
   }
+  /** Batch insert via unnest / COPY paths with optional HNSW deferral. */
   async insertMemoriesBatch(inputs) {
     if (inputs.length === 0) {
       return [];
@@ -4606,6 +4844,7 @@ var PostgresStorageProvider = class _PostgresStorageProvider {
       return row;
     });
   }
+  /** Update memory content, metadata, embedding, and content hash. */
   async updateMemory(input) {
     return this.withTransaction(async () => {
       const existing = await this.getMemoryById(input.id, input.organization);
@@ -4641,6 +4880,7 @@ var PostgresStorageProvider = class _PostgresStorageProvider {
       return this.getMemoryById(input.id, input.organization);
     });
   }
+  /** Find an active memory by org, agent, and content hash (dedupe). */
   async findActiveByContentHash(organization, agent, contentHash) {
     const result = await this.query(
       `SELECT id, organization, agent, content_text, metadata_json,
@@ -4653,6 +4893,7 @@ var PostgresStorageProvider = class _PostgresStorageProvider {
     const row = result.rows[0];
     return row ? this.mapRow(row) : null;
   }
+  /** Fetch a memory row by UUID within an organization. */
   async getMemoryById(id, organization) {
     const result = await this.query(
       `SELECT id, organization, agent, content_text, metadata_json,
@@ -4663,6 +4904,7 @@ var PostgresStorageProvider = class _PostgresStorageProvider {
     const row = result.rows[0];
     return row ? this.mapRow(row) : null;
   }
+  /** Fetch a memory row by internal rowid within an organization. */
   async getMemoryByRowid(rowid, organization) {
     const result = await this.query(
       `SELECT m.id, m.organization, m.agent, m.content_text, m.metadata_json,
@@ -4676,6 +4918,7 @@ var PostgresStorageProvider = class _PostgresStorageProvider {
     const row = result.rows[0];
     return row ? this.mapRow(row) : null;
   }
+  /** Batch-fetch memory rows by rowids within an organization. */
   async getMemoriesByRowids(rowids, organization) {
     const out = /* @__PURE__ */ new Map();
     if (rowids.length === 0) {
@@ -4698,6 +4941,7 @@ var PostgresStorageProvider = class _PostgresStorageProvider {
     }
     return out;
   }
+  /** List memories matching repository filters with optional limit. */
   async listMemories(filter, limit) {
     const want = limit !== void 0 ? limit : filter.metadata ? 1e4 : void 0;
     const compiled = filter.metadata ? compileMetadataFilterToPostgres(filter.metadata, 2) : null;
@@ -4759,9 +5003,11 @@ var PostgresStorageProvider = class _PostgresStorageProvider {
     }
     return rows;
   }
+  /** Scan memories matching metadata filters. */
   async searchByMetadata(filter, limit) {
     return this.listMemories(filter, limit);
   }
+  /** Full-text keyword search via `tsvector` / GIN index. */
   async searchKeyword(query, organization, topK) {
     const trimmed = query.trim();
     if (!trimmed || topK <= 0) {
@@ -4801,6 +5047,7 @@ var PostgresStorageProvider = class _PostgresStorageProvider {
       return [];
     }
   }
+  /** pgvector cosine ANN search (HNSW when index is present). */
   async searchVectors(embedding, topK) {
     this.requireVectorReady();
     if (this.hasPgvector) {
@@ -4850,6 +5097,7 @@ var PostgresStorageProvider = class _PostgresStorageProvider {
     scored.sort((a, b) => a.distance - b.distance);
     return scored.slice(0, topK);
   }
+  /** ANN search joined with memory rows and org/archived post-filters. */
   async searchVectorsWithMemories(embedding, topK, organization, options) {
     this.requireVectorReady();
     if (!this.hasPgvector) {
@@ -4914,6 +5162,7 @@ var PostgresStorageProvider = class _PostgresStorageProvider {
     );
     return mapHits(result.rows);
   }
+  /** Soft-archive memories (compression / forget paths). */
   async archiveMemories(ids, organization, compressedIntoId, archivedAt) {
     return this.withTransaction(async () => {
       if (ids.length === 0) {
@@ -4956,6 +5205,7 @@ var PostgresStorageProvider = class _PostgresStorageProvider {
       return archived;
     });
   }
+  /** Hard-delete a single memory by id; returns whether a row was removed. */
   async deleteMemoryById(id, organization) {
     const result = await this.query(
       `DELETE FROM memories WHERE id = $1 AND organization = $2`,
@@ -4963,6 +5213,7 @@ var PostgresStorageProvider = class _PostgresStorageProvider {
     );
     return (result.rowCount ?? 0) > 0;
   }
+  /** Hard-delete memories matching org / agent / metadata filters. */
   async deleteMemoriesByFilter(filter) {
     if (!filter.agent) {
       throw new DatabaseError("deleteMemoriesByFilter requires an agent filter");
@@ -4973,6 +5224,7 @@ var PostgresStorageProvider = class _PostgresStorageProvider {
     );
     return result.rowCount ?? 0;
   }
+  /** Remove all memories for an organization. */
   async clearOrganization(organization) {
     const result = await this.query(
       `DELETE FROM memories WHERE organization = $1`,
@@ -4980,6 +5232,7 @@ var PostgresStorageProvider = class _PostgresStorageProvider {
     );
     return result.rowCount ?? 0;
   }
+  /** List audit history events for a memory id. */
   async getHistory(memoryId) {
     const result = await this.query(
       `SELECT id, memory_id, event_type, related_memory_id, created_at
@@ -4994,6 +5247,7 @@ var PostgresStorageProvider = class _PostgresStorageProvider {
       created_at: String(row.created_at)
     }));
   }
+  /** Append a history row (created / archived / compressed / updated). */
   async insertHistoryEvent(event) {
     await this.query(
       `INSERT INTO memory_history (id, memory_id, event_type, related_memory_id, created_at)
@@ -5007,6 +5261,7 @@ var PostgresStorageProvider = class _PostgresStorageProvider {
       ]
     );
   }
+  /** Aggregate memory counts for an organization. */
   async getStats(organization) {
     const result = await this.query(
       `SELECT
@@ -5024,6 +5279,7 @@ var PostgresStorageProvider = class _PostgresStorageProvider {
       totalAgents: Number(result.rows[0]?.agents ?? 0)
     };
   }
+  /** Approximate on-disk database size in bytes (`pg_database_size`). */
   async getDatabaseSizeBytes() {
     const result = await this.query(
       `SELECT pg_database_size(current_database())::bigint AS size`
@@ -5371,7 +5627,7 @@ function createDatabaseProvider(config) {
 }
 
 // src/version.ts
-var SDK_VERSION = "0.5.4";
+var SDK_VERSION = "0.5.6";
 
 // src/memory/transfer.ts
 var warnedMissingExportManifest = false;
@@ -5840,6 +6096,9 @@ var SqliteGraphProvider = class {
   concurrency;
   db = null;
   opened = false;
+  /**
+   * @param options - Graph SQLite path and optional concurrency tuning.
+   */
   constructor(options) {
     if (!options?.path || typeof options.path !== "string" || !options.path.trim()) {
       throw new ConfigurationError("sqlite graph requires a non-empty path");
@@ -5847,12 +6106,15 @@ var SqliteGraphProvider = class {
     this.dbPath = path7.resolve(options.path.trim());
     this.concurrency = resolveConcurrencyConfig(options.concurrency);
   }
+  /** Whether this provider supports file snapshots for checkpoint / export. */
   supportsFileSnapshot() {
     return this.dbPath !== ":memory:";
   }
+  /** Absolute graph database path, or `null` for `:memory:`. */
   getDataPath() {
     return this.dbPath === ":memory:" ? null : this.dbPath;
   }
+  /** Open the graph SQLite file, apply pragmas, and create schema if needed. */
   async open() {
     if (this.opened) return;
     try {
@@ -5889,6 +6151,7 @@ var SqliteGraphProvider = class {
       );
     }
   }
+  /** Close the graph database connection. */
   async close() {
     if (!this.db) {
       this.opened = false;
@@ -5910,6 +6173,14 @@ var SqliteGraphProvider = class {
       this.opened = false;
     }
   }
+  /**
+   * Create or replace a directed memory↔memory edge.
+   *
+   * @param fromId - Source memory UUID.
+   * @param toId - Target memory UUID.
+   * @param relation - Edge label (e.g. `"related_to"`, `"caused_by"`).
+   * @param metadata - Optional JSON metadata stored on the edge.
+   */
   async linkMemories(fromId, toId, relation, metadata) {
     const db = this.requireDb();
     await this.withTx(() => {
@@ -5932,6 +6203,13 @@ var SqliteGraphProvider = class {
       );
     });
   }
+  /**
+   * Remove edges between two memories.
+   *
+   * @param fromId - Source memory UUID.
+   * @param toId - Target memory UUID.
+   * @param relation - When set, only delete edges with this relation label.
+   */
   async unlinkMemories(fromId, toId, relation) {
     const db = this.requireDb();
     await this.withTx(() => {
@@ -5981,6 +6259,12 @@ var SqliteGraphProvider = class {
     }
     return out;
   }
+  /**
+   * Insert or update a named entity node.
+   *
+   * @param entity - Entity name, type, and optional metadata.
+   * @returns Stable entity id ({@link entityIdFrom}).
+   */
   async upsertEntity(entity) {
     const id = entityIdFrom(entity.name, entity.type);
     const db = this.requireDb();
@@ -6005,6 +6289,13 @@ var SqliteGraphProvider = class {
     });
     return id;
   }
+  /**
+   * Link an entity to a memory via a `MENTIONS` edge (not traversed by {@link getRelated}).
+   *
+   * @param entityId - Entity id from {@link upsertEntity}.
+   * @param memoryId - Target memory UUID.
+   * @param role - Optional role string stored on the edge metadata.
+   */
   async linkEntityToMemory(entityId, memoryId, role) {
     const db = this.requireDb();
     await this.withTx(() => {
@@ -6034,6 +6325,11 @@ var SqliteGraphProvider = class {
       );
     });
   }
+  /**
+   * Remove the memory node and incident edges when a memory is hard-deleted.
+   *
+   * @param memoryId - Wolbarg memory UUID.
+   */
   async deleteMemory(memoryId) {
     const db = this.requireDb();
     await this.withTx(() => {
@@ -6053,6 +6349,7 @@ var SqliteGraphProvider = class {
       }
     );
   }
+  /** Lightweight connectivity and schema statistics check. */
   async health() {
     try {
       if (!this.opened || !this.db) {
@@ -6198,6 +6495,9 @@ var Neo4jGraphProvider = class {
   database;
   driver = null;
   opened = false;
+  /**
+   * @param options - Bolt URL, credentials, and optional database name.
+   */
   constructor(options) {
     if (!options?.url?.trim()) {
       throw new ConfigurationError("neo4j graph requires a non-empty url");
@@ -6213,12 +6513,15 @@ var Neo4jGraphProvider = class {
     this.password = options.password;
     this.database = options.database?.trim() || void 0;
   }
+  /** Neo4j does not support local file snapshots for checkpoint pairing. */
   supportsFileSnapshot() {
     return false;
   }
+  /** Always `null` — graph data lives in the remote Neo4j cluster. */
   getDataPath() {
     return null;
   }
+  /** Connect to Neo4j, verify connectivity, and ensure uniqueness constraints. */
   async open() {
     if (this.opened) return;
     let mod;
@@ -6250,6 +6553,7 @@ var Neo4jGraphProvider = class {
       }
     });
   }
+  /** Close the neo4j-driver connection. */
   async close() {
     if (this.driver) {
       await this.driver.close();
@@ -6311,6 +6615,14 @@ var Neo4jGraphProvider = class {
     }
     await this.run(cypher, { id });
   }
+  /**
+   * MERGE a directed `RELATED` relationship between two memory nodes.
+   *
+   * @param fromId - Source memory UUID.
+   * @param toId - Target memory UUID.
+   * @param relation - Relationship label stored on `RELATED.relation`.
+   * @param metadata - Optional JSON metadata on the relationship.
+   */
   async linkMemories(fromId, toId, relation, metadata) {
     await this.withSession(async (session) => {
       await this.ensureMemoryNode(fromId, session);
@@ -6329,6 +6641,13 @@ var Neo4jGraphProvider = class {
       );
     });
   }
+  /**
+   * Delete `RELATED` relationship(s) between two memories.
+   *
+   * @param fromId - Source memory UUID.
+   * @param toId - Target memory UUID.
+   * @param relation - When set, only delete edges with this relation property.
+   */
   async unlinkMemories(fromId, toId, relation) {
     if (relation !== void 0) {
       await this.run(
@@ -6374,6 +6693,12 @@ var Neo4jGraphProvider = class {
       (row) => rowToMemoryRecord(unwrapRow(row))
     );
   }
+  /**
+   * MERGE an `Entity` node keyed by deterministic id.
+   *
+   * @param entity - Entity name, type, and optional metadata.
+   * @returns Stable entity id ({@link entityIdFrom}).
+   */
   async upsertEntity(entity) {
     const id = entityIdFrom(entity.name, entity.type);
     await this.run(
@@ -6388,6 +6713,13 @@ var Neo4jGraphProvider = class {
     );
     return id;
   }
+  /**
+   * MERGE a `MENTIONS` relationship from entity to memory.
+   *
+   * @param entityId - Entity id from {@link upsertEntity}.
+   * @param memoryId - Target memory UUID.
+   * @param role - Optional role string on the relationship.
+   */
   async linkEntityToMemory(entityId, memoryId, role) {
     await this.withSession(async (session) => {
       await this.ensureMemoryNode(memoryId, session);
@@ -6410,6 +6742,11 @@ var Neo4jGraphProvider = class {
       );
     });
   }
+  /**
+   * DETACH DELETE the memory node and all incident relationships.
+   *
+   * @param memoryId - Wolbarg memory UUID.
+   */
   async deleteMemory(memoryId) {
     await this.run(
       `MATCH (m:Memory { id: $id })
@@ -6417,9 +6754,17 @@ var Neo4jGraphProvider = class {
       { id: memoryId }
     );
   }
+  /**
+   * Run arbitrary parameterized Cypher (escape hatch for advanced graph queries).
+   *
+   * @param cypher - Cypher query string.
+   * @param params - Bound parameters for the query.
+   * @returns Raw row objects from the driver.
+   */
   async query(cypher, params) {
     return this.run(cypher, params ?? {});
   }
+  /** Verify connectivity and return server metadata when available. */
   async health() {
     try {
       if (!this.opened || !this.driver) {
@@ -6910,21 +7255,32 @@ function createChildTrace(parent) {
 // src/telemetry/emitter.ts
 var NoopTelemetryProvider = class {
   name = "noop";
+  /** @inheritdoc TelemetryProvider.open */
   async open() {
   }
+  /** @inheritdoc TelemetryProvider.close */
   async close() {
   }
+  /** @inheritdoc TelemetryProvider.emit */
   emit(_event) {
   }
+  /** @inheritdoc TelemetryProvider.flush */
   async flush() {
   }
 };
 var TelemetryEmitter = class {
+  /** Stable session id for this Wolbarg instance lifetime. */
   sessionId;
+  /** Structured logger gated by telemetry log level. */
   logger;
   provider;
   config;
   context;
+  /**
+   * @param provider - Telemetry backend, or `null` for {@link NoopTelemetryProvider}.
+   * @param config - Capture flags and log level.
+   * @param context - Default organization injected into events.
+   */
   constructor(provider, config, context = {}) {
     this.sessionId = createSessionId();
     this.provider = provider ?? new NoopTelemetryProvider();
@@ -6940,25 +7296,37 @@ var TelemetryEmitter = class {
     this.context = context;
     this.logger = new WolbargLogger(this.config.level);
   }
+  /** Whether telemetry is enabled and backed by a non-noop provider. */
   get enabled() {
     return this.config.enabled && this.provider.name !== "noop";
   }
+  /** Replace the underlying telemetry provider (e.g. after lazy init). */
   setProvider(provider) {
     this.provider = provider;
   }
+  /** Open the underlying telemetry provider when enabled. */
   async open() {
     if (!this.config.enabled) {
       return;
     }
     await this.provider.open();
   }
+  /** Flush pending events and close the telemetry provider. */
   async close() {
     await this.provider.flush();
     await this.provider.close();
   }
+  /** Flush pending telemetry events without closing the provider. */
   async flush() {
     await this.provider.flush();
   }
+  /**
+   * Begin tracing an operation.
+   *
+   * @param operation - Public telemetry operation name.
+   * @param parent - Optional parent trace for nested spans.
+   * @returns Handle — call `success()` or `failure()` when done.
+   */
   start(operation, parent) {
     const context = parent ? createChildTrace(parent) : createRootTrace(this.sessionId);
     const startedAt = performance.now();
@@ -7033,10 +7401,12 @@ var TelemetryEmitter = class {
       }
     };
   }
+  /** Emit a startup telemetry event. */
   emitStartup(provider) {
     const trace = this.start("startup");
     trace.success({ provider });
   }
+  /** Emit a shutdown telemetry event. */
   emitShutdown(provider) {
     const trace = this.start("shutdown");
     trace.success({ provider });
@@ -7102,10 +7472,15 @@ var SqliteEventDatabase = class {
   db = null;
   insertStmt = null;
   columns = /* @__PURE__ */ new Set();
+  /**
+   * @param options.url - Path to the telemetry SQLite file.
+   * @param options.readonly - Open read-only (Studio / analytics).
+   */
   constructor(options) {
     this.url = options.url;
     this.readonly = options.readonly ?? false;
   }
+  /** Open the telemetry database and run schema migrations. */
   async open() {
     try {
       const dbPath = this.resolvePath(this.url);
@@ -7160,6 +7535,7 @@ var SqliteEventDatabase = class {
       );
     }
   }
+  /** Close the telemetry database connection. */
   async close() {
     if (!this.db) return;
     try {
@@ -7170,6 +7546,7 @@ var SqliteEventDatabase = class {
       this.columns.clear();
     }
   }
+  /** Insert one normalized telemetry event row. */
   async insertEvent(input) {
     const event = normalizeEvent(input);
     const stmt = this.insertStmt;
@@ -7215,6 +7592,7 @@ var SqliteEventDatabase = class {
       );
     }
   }
+  /** Insert many events in a single transaction. */
   async insertEvents(inputs) {
     const db = this.requireDb();
     const out = [];
@@ -7233,6 +7611,7 @@ var SqliteEventDatabase = class {
       throw error;
     }
   }
+  /** Query telemetry events with filters, sort, and pagination. */
   async query(options) {
     const db = this.requireDb();
     const clauses = [];
@@ -7313,11 +7692,13 @@ var SqliteEventDatabase = class {
       offset
     };
   }
+  /** Fetch one event by primary key. */
   async getEvent(id) {
     const db = this.requireDb();
     const row = db.prepare(`SELECT * FROM telemetry_events WHERE id = ?`).get(id);
     return row ? rowToEvent(row) : null;
   }
+  /** Count events optionally filtered by time and operation. */
   async countEvents(filter) {
     const db = this.requireDb();
     const clauses = [];
@@ -7468,9 +7849,13 @@ var SqliteTelemetryProvider = class {
   openPromise = null;
   warnedQueueDrop = false;
   warnedFlushFailure = false;
+  /**
+   * @param options.url - Path to the independent telemetry SQLite database file.
+   */
   constructor(options) {
     this.db = new SqliteEventDatabase({ url: options.url });
   }
+  /** Open the telemetry EventDatabase (lazy — also invoked on first emit). */
   async open() {
     if (!this.openPromise) {
       this.openPromise = this.db.open();
@@ -7478,12 +7863,18 @@ var SqliteTelemetryProvider = class {
     await this.openPromise;
     this.closed = false;
   }
+  /** Flush pending events and close the telemetry database. */
   async close() {
     this.closed = true;
     await this.flush();
     await this.db.close();
     this.openPromise = null;
   }
+  /**
+   * Enqueue a telemetry event for async persistence (never throws).
+   *
+   * @param event - Partial or complete {@link TelemetryEventInput}.
+   */
   emit(event) {
     if (this.closed) {
       return;
@@ -7500,6 +7891,7 @@ var SqliteTelemetryProvider = class {
     this.queue.push(event);
     void this.scheduleFlush();
   }
+  /** Block until all queued events are written (or dropped on failure). */
   async flush() {
     while (this.queue.length > 0 || this.flushing) {
       await this.scheduleFlush();
@@ -7508,10 +7900,12 @@ var SqliteTelemetryProvider = class {
       }
     }
   }
+  /** Query persisted telemetry events with filters and pagination. */
   async query(options) {
     await this.open();
     return this.db.query(options);
   }
+  /** Fetch a single telemetry event by id. */
   async getEvent(id) {
     await this.open();
     return this.db.getEvent(id);
@@ -7553,16 +7947,28 @@ var SqliteCheckpointProvider = class {
   name = "sqlite";
   directory;
   ready = false;
+  /**
+   * @param options.directory - Folder for `.json` metadata and `.db` snapshot files.
+   */
   constructor(options) {
     this.directory = options?.directory ?? path7.resolve(process.cwd(), ".wolbarg", "checkpoints");
   }
+  /** Ensure the checkpoint directory exists. */
   async open() {
     fs6.mkdirSync(this.directory, { recursive: true });
     this.ready = true;
   }
+  /** Mark the provider closed (does not delete snapshots). */
   async close() {
     this.ready = false;
   }
+  /**
+   * Create an immutable SQLite backup of `sourcePath` under a unique name.
+   *
+   * @param name - Checkpoint label (must not already exist).
+   * @param sourcePath - Live memory database path to snapshot.
+   * @param options.description - Optional human-readable description stored in metadata.
+   */
   async checkpoint(name, sourcePath, options) {
     this.requireReady();
     assertCheckpointName(name);
@@ -7617,6 +8023,12 @@ Ensure Wolbarg has been initialized and the database path is correct.`
     fs6.renameSync(tmpMetaPath, metaPath);
     return meta2;
   }
+  /**
+   * Restore a named checkpoint over `targetPath` (replaces WAL/SHM side files).
+   *
+   * @param name - Existing checkpoint name.
+   * @param targetPath - Live memory database path to overwrite.
+   */
   async rollback(name, targetPath) {
     this.requireReady();
     const meta2 = await this.getCheckpoint(name);
@@ -7639,6 +8051,7 @@ Ensure Wolbarg has been initialized and the database path is correct.`
     await safeSqliteBackup(meta2.snapshotPath, resolvedTarget);
     return meta2;
   }
+  /** Delete checkpoint metadata and snapshot files for `name`. */
   async deleteCheckpoint(name) {
     this.requireReady();
     const metaPath = this.metaPath(name);
@@ -7654,6 +8067,7 @@ Ensure Wolbarg has been initialized and the database path is correct.`
     }
     return removed;
   }
+  /** List all checkpoints sorted by creation time. */
   async listCheckpoints() {
     this.requireReady();
     if (!fs6.existsSync(this.directory)) {
@@ -7670,6 +8084,7 @@ Ensure Wolbarg has been initialized and the database path is correct.`
     }
     return out.sort((a, b) => a.createdAt.localeCompare(b.createdAt));
   }
+  /** Load checkpoint metadata by name, or `null` if missing / corrupt. */
   async getCheckpoint(name) {
     this.requireReady();
     const metaPath = this.metaPath(name);
@@ -7854,6 +8269,13 @@ var SqliteSubscribeEmitter = class {
       }
     });
   }
+  /**
+   * Register a filtered callback for in-process memory change events.
+   *
+   * @param filter - Organization / agent / event-type filter.
+   * @param callback - Invoked synchronously on each matching emit.
+   * @returns Unsubscribe function.
+   */
   subscribe(filter, callback) {
     if (this.closed) {
       throw new Error("Subscribe backend is closed");
@@ -7864,12 +8286,14 @@ var SqliteSubscribeEmitter = class {
       this.subscriptions.delete(id);
     };
   }
+  /** Emit a memory change event to registered subscribers. */
   emit(event) {
     if (this.closed) {
       return;
     }
     this.emitter.emit("change", event);
   }
+  /** Remove all listeners and mark the emitter closed. */
   async close() {
     this.closed = true;
     this.subscriptions.clear();
@@ -7907,6 +8331,20 @@ var Wolbarg = class {
   memoryDedupe = resolveMemoryDedupeConfig();
   embeddingCacheConfig = resolveEmbeddingCacheConfig();
   rawEmbedding = null;
+  /**
+   * @param options - Full {@link WolbargOptions}. Key fields:
+   * - `organization` — namespace isolating memories in a shared DB
+   * - `database` / `storage` — SQLite/Postgres config **or** a custom
+   *   {@link StorageProvider} instance
+   * - `embedding` — {@link EmbeddingProvider} instance **or**
+   *   {@link EmbeddingConfig} / {@link openaiEmbedding} (etc.)
+   * - `llm` — optional {@link LlmProvider} or {@link LlmConfig} / {@link openaiLlm};
+   *   required for {@link Wolbarg.compress} and extract-mode
+   *   {@link Wolbarg.rememberFromMessages}
+   * - `graph`, `telemetry`, `reranker`, `keywordSearch`, `ocr`, `vision`,
+   *   `compression`, `chunking`, `retrieval`, `concurrency`, `embeddingCache`,
+   *   `memory.dedupe` — optional plugins / tuning
+   */
   constructor(options) {
     this.telemetry = new TelemetryEmitter(null, { enabled: false, level: "off" });
     if (!options) {
@@ -7965,6 +8403,12 @@ var Wolbarg = class {
   }
   /**
    * Backwards-compatible initialization (v0.1 API).
+   * Prefer constructing with options + {@link Wolbarg.ready} instead.
+   *
+   * @param options - Organization, database, embedding, and optional LLM config.
+   * @returns Resolves when storage is open and the vector schema is ready.
+   * @throws {InitializationError} If already initialized.
+   * @throws {ConfigurationError} | {ValidationError} On invalid options.
    */
   async init(options) {
     if (this.initialized || this.storage) {
@@ -7996,7 +8440,14 @@ var Wolbarg = class {
     }
     await this.ready();
   }
-  /** Ensure storage (and optional telemetry) are open. */
+  /**
+   * Open storage, optional telemetry / checkpoint / graph providers, wrap the
+   * embedding cache, and probe embedding dimensions. Safe to call multiple times;
+   * concurrent callers share one boot promise.
+   *
+   * @returns Resolves when the instance is ready for remember/recall.
+   * @throws {InitializationError} If neither constructor options nor {@link init} were used.
+   */
   async ready() {
     if (this.initialized) {
       return;
@@ -8012,6 +8463,7 @@ var Wolbarg = class {
       this.booting = null;
     }
   }
+  /** Internal boot sequence invoked by {@link Wolbarg.ready}. */
   async boot() {
     if (!this.storage || !this.embedding || !this.organization) {
       throw new InitializationError(
@@ -8087,7 +8539,17 @@ var Wolbarg = class {
       );
     }
   }
-  /** Store a semantic memory for an agent (may upsert when dedupe is enabled). */
+  /**
+   * Store a semantic memory for an agent. Embeds `content.text`, writes the row,
+   * and may **upsert** an existing active memory when dedupe is enabled
+   * (constructor `memory.dedupe` or per-call `options.dedupe`).
+   *
+   * @param options - Agent id, text content, optional metadata / dedupe overrides.
+   *   See {@link RememberOptions}.
+   * @returns The stored record plus `action` (`"created"` | `"updated"`).
+   * @throws {ValidationError} On empty agent/content.
+   * @throws {InitializationError} If not configured / ready.
+   */
   async remember(options) {
     const trace = this.telemetry.start("remember");
     try {
@@ -8109,7 +8571,15 @@ var Wolbarg = class {
       throw wrapOperationError("remember", error);
     }
   }
-  /** Batch remember — sequential when dedupe enabled; otherwise one TX batch. */
+  /**
+   * Remember many memories in one call. Runs sequentially when any item (or the
+   * global config) enables dedupe; otherwise embeds in batch and inserts in one
+   * transaction for throughput.
+   *
+   * @param items - Non-empty list of {@link RememberOptions}.
+   * @returns One {@link RememberResult} per input, same order.
+   * @throws {ValidationError} If `items` is empty or an entry is invalid.
+   */
   async rememberBatch(items) {
     const parent = this.telemetry.start("rememberBatch");
     try {
@@ -8235,7 +8705,15 @@ var Wolbarg = class {
    * **Experimental** until 1.0 — API shape may change.
    *
    * - `mode: "raw"` (default) — remember user message text (no LLM).
-   * - `mode: "extract"` — require configured `llm`; extract atomic facts then remember each.
+   * - `mode: "extract"` — requires configured `llm`; extracts atomic facts then
+   *   remembers each. Pass a custom {@link LlmProvider} or {@link openaiLlm}
+   *   in the constructor.
+   *
+   * @param messages - Conversation turns (`role` + `content`).
+   * @param options - Agent, mode, optional metadata/dedupe. See
+   *   {@link RememberFromMessagesOptions}.
+   * @returns One {@link RememberResult} per remembered fact/message.
+   * @throws {ProviderNotConfiguredError} When `mode: "extract"` but no `llm` was configured.
    */
   async rememberFromMessages(messages, options) {
     const parent = this.telemetry.start("rememberFromMessages");
@@ -8305,7 +8783,14 @@ var Wolbarg = class {
     }
   }
   /**
-   * Update an existing memory by id (re-embeds when content changes).
+   * Update an existing memory by id. Re-embeds when `content` changes; merges
+   * metadata when provided.
+   *
+   * @param options.id - Memory id to update.
+   * @param options.content - Optional new `{ text }` (triggers re-embed + content hash).
+   * @param options.metadata - Optional metadata merged onto the existing record.
+   * @returns Updated record with `action: "updated"`.
+   * @throws {MemoryNotFoundError} If the id is unknown in this organization.
    */
   async update(options) {
     const trace = this.telemetry.start("update");
@@ -8375,10 +8860,18 @@ var Wolbarg = class {
     }
   }
   /**
-   * Subscribe to memory change events.
+   * Subscribe to memory change events (remember / update / forget / compress / clear).
    *
    * **SQLite:** delivers events only within this Node.js process.
    * A second process writing the same `memory.db` will not notify subscribers here.
+   *
+   * **Postgres:** uses LISTEN/NOTIFY across processes (lazy connection on first subscribe).
+   *
+   * @param filter - Scope by `organization` (defaults to this instance’s org),
+   *   optional `agent`, and optional `events` allow-list. See {@link SubscribeFilter}.
+   * @param callback - Invoked with each {@link MemoryChangeEvent}.
+   * @returns {@link Unsubscribe} function — call to stop receiving events.
+   * @throws {ValidationError} If organization cannot be resolved.
    */
   subscribe(filter, callback) {
     const org = filter.organization || this.organization;
@@ -8407,6 +8900,7 @@ var Wolbarg = class {
     }
     return this.subscribeBackend.subscribe(normalized, callback);
   }
+  /** Broadcast a memory change event to in-process or Postgres NOTIFY subscribers. */
   emitChange(event) {
     try {
       if (this.storage instanceof PostgresStorageProvider) {
@@ -8632,6 +9126,17 @@ var Wolbarg = class {
       throw error;
     }
   }
+  /**
+   * Find the best active near-duplicate memory for upsert (cosine similarity ≥ threshold).
+   *
+   * @param storage - Open storage provider.
+   * @param organization - Org namespace.
+   * @param agent - Agent scope for the search.
+   * @param vector - Embedding of the candidate text.
+   * @param threshold - Minimum similarity (0–1) to treat as a duplicate.
+   * @param limit - Max vector candidates to inspect.
+   * @returns Matching memory row, or `null` if none qualify.
+   */
   async findNearDuplicate(storage, organization, agent, vector, threshold, limit) {
     if (typeof storage.searchVectorsWithMemories === "function") {
       const hits2 = await storage.searchVectorsWithMemories(
@@ -8969,7 +9474,13 @@ var Wolbarg = class {
       throw wrapOperationError("recall", error);
     }
   }
-  /** Batch recall — parent event + child traces. */
+  /**
+   * Run multiple recalls sequentially under one parent telemetry span.
+   *
+   * @param queries - Non-empty list of recall options (`explain` is forced off).
+   * @returns One hit array per query, same order.
+   * @throws {ValidationError} If `queries` is empty.
+   */
   async recallBatch(queries) {
     const parent = this.telemetry.start("recallBatch");
     try {
@@ -9003,10 +9514,21 @@ var Wolbarg = class {
       throw wrapOperationError("recallBatch", error);
     }
   }
+  /**
+   * Compress the newest active memories for an agent into one summary memory
+   * and archive the sources. Requires an `llm` (or custom `compression`) at
+   * construction — typed only on `Wolbarg<true>`.
+   *
+   * @param options - `agent` required; optional `limit` (default 50, min 2).
+   *   See {@link CompressOptions}.
+   * @returns Summary record plus archived source ids. See {@link CompressResult}.
+   * @throws {ProviderNotConfiguredError} If no LLM/compression provider is set.
+   * @throws {ValidationError} If fewer than 2 active memories exist for the agent.
+   */
   async compress(options) {
     return this.runCompress(options);
   }
-  /** @internal */
+  /** @internal Runs compress for both typed and untyped call sites. */
   async runCompress(options) {
     const trace = this.telemetry.start("compress");
     try {
@@ -9095,6 +9617,16 @@ var Wolbarg = class {
       throw wrapOperationError("compress", error);
     }
   }
+  /**
+   * Ingest a document (path, URL, Buffer, or text), chunk it, embed chunks, and
+   * store each as a memory. Images use optional `ocr` / `vision` providers from
+   * the constructor.
+   *
+   * @param options - `agent`, `source`, optional chunking overrides / metadata.
+   *   See {@link IngestOptions}.
+   * @returns Counts and created memory ids. See {@link IngestResult}.
+   * @throws {ValidationError} If no text can be extracted or chunking yields zero chunks.
+   */
   async ingest(options) {
     const trace = this.telemetry.start("ingest");
     try {
@@ -9265,8 +9797,14 @@ var Wolbarg = class {
     }
   }
   /**
-   * Link two memories in the optional graph layer.
-   * Throws {@link ProviderNotConfiguredError} when no graph provider is set.
+   * Link two memories in the optional graph layer with a typed relation edge.
+   *
+   * @param fromId - Source memory id.
+   * @param toId - Target memory id.
+   * @param relation - Edge label (e.g. `"supports"`, `"caused_by"`).
+   * @param metadata - Optional edge properties stored on the graph provider.
+   * @throws {ProviderNotConfiguredError} When no `graph` was configured.
+   * @throws {ValidationError} On empty ids/relation.
    */
   async linkMemories(fromId, toId, relation, metadata) {
     const trace = this.telemetry.start("linkMemories");
@@ -9296,8 +9834,13 @@ var Wolbarg = class {
   }
   /**
    * Traverse related memories via the optional graph layer.
-   * Throws {@link ProviderNotConfiguredError} when no graph provider is set.
-   * Results are re-hydrated from SQL storage when available.
+   * Neighbor stubs from the graph are re-hydrated from SQL storage when available.
+   *
+   * @param memoryId - Seed memory id.
+   * @param options - Optional `relation`, `direction`, `depth`, `limit`.
+   *   See {@link GetRelatedOptions}.
+   * @returns Related {@link MemoryRecord} list (may be empty).
+   * @throws {ProviderNotConfiguredError} When no `graph` was configured.
    */
   async getRelated(memoryId, options) {
     const trace = this.telemetry.start("getRelated");
@@ -9334,6 +9877,14 @@ var Wolbarg = class {
       throw wrapOperationError("getRelated", error);
     }
   }
+  /**
+   * Delete memories by id or by agent filter. Cascades graph nodes/edges when
+   * a graph provider is configured.
+   *
+   * @param options - Either `{ id }` or `{ filter: { agent } }`. See {@link ForgetOptions}.
+   * @returns Number of memories deleted.
+   * @throws {ValidationError} If neither `id` nor `filter.agent` is provided.
+   */
   async forget(options) {
     const trace = this.telemetry.start("forget");
     try {
@@ -9398,6 +9949,13 @@ var Wolbarg = class {
       throw wrapOperationError("forget", error);
     }
   }
+  /**
+   * Return the audit/history timeline for a single memory.
+   *
+   * @param options - `{ id }` of the memory. See {@link HistoryOptions}.
+   * @returns Memory record plus ordered {@link HistoryEvent} list.
+   * @throws {MemoryNotFoundError} If the id is unknown.
+   */
   async history(options) {
     const trace = this.telemetry.start("history");
     try {
@@ -9425,6 +9983,11 @@ var Wolbarg = class {
       throw wrapOperationError("history", error);
     }
   }
+  /**
+   * Aggregate counts for this organization (active / archived / agents / etc.).
+   *
+   * @returns {@link StatsResult} snapshot.
+   */
   async stats() {
     const trace = this.telemetry.start("stats");
     try {
@@ -9452,6 +10015,13 @@ var Wolbarg = class {
       throw wrapOperationError("stats", error);
     }
   }
+  /**
+   * Delete all memories for this organization (optionally scoped by agent).
+   * Cascades graph cleanup when a graph provider is configured.
+   *
+   * @param options - Optional `{ agent }` scope. See {@link ClearOptions}.
+   * @returns Number of memories deleted.
+   */
   async clear(options) {
     const trace = this.telemetry.start("clear");
     try {
@@ -9480,7 +10050,16 @@ var Wolbarg = class {
       throw wrapOperationError("clear", error);
     }
   }
-  /** Create an immutable named checkpoint of the memory database. */
+  /**
+   * Create an immutable named checkpoint of the file-backed SQLite memory DB
+   * (and SQLite graph snapshot when applicable).
+   *
+   * @param name - Checkpoint name (unique).
+   * @param options - Optional metadata. See {@link CheckpointOptions}.
+   * @returns {@link CheckpointInfo} for the new checkpoint.
+   * @throws {ProviderNotConfiguredError} Without a checkpoint provider / file DB.
+   * @throws {GraphCheckpointNotSupportedError} For Neo4j graph backends.
+   */
   async checkpoint(name, options) {
     const trace = this.telemetry.start("checkpoint");
     try {
@@ -9511,7 +10090,12 @@ var Wolbarg = class {
       throw wrapOperationError("checkpoint", error);
     }
   }
-  /** Restore the memory database from a named checkpoint. */
+  /**
+   * Restore the memory database from a named checkpoint (replaces the live DB file).
+   *
+   * @param name - Checkpoint name previously created with {@link Wolbarg.checkpoint}.
+   * @returns {@link CheckpointInfo} of the restored checkpoint.
+   */
   async rollback(name) {
     const trace = this.telemetry.start("rollback");
     let storageClosed = false;
@@ -9557,6 +10141,12 @@ var Wolbarg = class {
       throw wrapOperationError("rollback", error);
     }
   }
+  /**
+   * Delete a named checkpoint from disk / the checkpoint store.
+   *
+   * @param name - Checkpoint name.
+   * @returns `true` if a checkpoint was removed.
+   */
   async deleteCheckpoint(name) {
     const trace = this.telemetry.start("deleteCheckpoint");
     try {
@@ -9583,6 +10173,11 @@ var Wolbarg = class {
       throw wrapOperationError("deleteCheckpoint", error);
     }
   }
+  /**
+   * List all known checkpoints for this instance.
+   *
+   * @returns Array of {@link CheckpointInfo} (may be empty).
+   */
   async listCheckpoints() {
     const trace = this.telemetry.start("listCheckpoints");
     try {
@@ -9601,6 +10196,12 @@ var Wolbarg = class {
       throw wrapOperationError("listCheckpoints", error);
     }
   }
+  /**
+   * Look up a single checkpoint by name.
+   *
+   * @param name - Checkpoint name.
+   * @returns {@link CheckpointInfo} or `null` if missing.
+   */
   async getCheckpoint(name) {
     const trace = this.telemetry.start("getCheckpoint");
     try {
@@ -9620,7 +10221,13 @@ var Wolbarg = class {
       throw wrapOperationError("getCheckpoint", error);
     }
   }
-  /** Export the memory database to a portable SQLite + manifest bundle. */
+  /**
+   * Export the memory database to a portable SQLite + manifest bundle
+   * (includes SQLite graph sidecar when applicable).
+   *
+   * @param exportPath - Destination file path for the export bundle.
+   * @returns {@link ExportResult} with path, size, and timestamp.
+   */
   async export(exportPath) {
     const trace = this.telemetry.start("export");
     try {
@@ -9651,7 +10258,13 @@ var Wolbarg = class {
       throw wrapOperationError("export", error);
     }
   }
-  /** Import a previously exported memory database, replacing the current file. */
+  /**
+   * Import a previously exported memory database, replacing the current file.
+   * Closes and reopens storage around the swap.
+   *
+   * @param exportPath - Path to a bundle produced by {@link Wolbarg.export}.
+   * @returns {@link ImportResult} with restored path and timestamp.
+   */
   async import(exportPath) {
     const trace = this.telemetry.start("import");
     let storageClosed = false;
@@ -9701,11 +10314,17 @@ var Wolbarg = class {
       throw wrapOperationError("import", error);
     }
   }
-  /** Flush pending telemetry (useful in tests). */
+  /**
+   * Flush pending telemetry writes (useful in tests / before process exit).
+   *
+   * @returns Resolves when the telemetry provider has flushed.
+   */
   async flushTelemetry() {
     await this.telemetry.flush();
   }
-  /** Session id for this SDK instance (telemetry traces). */
+  /**
+   * Session id for this SDK instance (attached to telemetry traces and change events).
+   */
   get sessionId() {
     return this.telemetry.sessionId;
   }
@@ -9720,6 +10339,12 @@ var Wolbarg = class {
     }
     return fn();
   }
+  /**
+   * Close storage, graph, telemetry, checkpoints, and subscribe backends.
+   * The instance can be discarded afterward; construct a new one to reopen.
+   *
+   * @returns Resolves when all providers have closed (errors are swallowed per-provider).
+   */
   async close() {
     if (this.storage) {
       this.telemetry.emitShutdown(this.storage.name);
@@ -9744,9 +10369,11 @@ var Wolbarg = class {
     this.embeddingDimensions = null;
     this.initialized = false;
   }
+  /** Whether {@link Wolbarg.ready} / {@link Wolbarg.init} has completed successfully. */
   get isInitialized() {
     return this.initialized;
   }
+  /** Ensure {@link Wolbarg.ready} completed and core providers are available. */
   async requireReady() {
     await this.ready();
     if (!this.initialized || !this.storage || !this.embedding || !this.organization) {
@@ -9760,6 +10387,7 @@ var Wolbarg = class {
       organization: this.organization
     };
   }
+  /** Reject embeddings whose dimensionality differs from the initialized model. */
   assertEmbeddingDimensions(dimensions) {
     if (this.embeddingDimensions !== null && dimensions !== this.embeddingDimensions) {
       throw new ValidationError(
@@ -9767,6 +10395,7 @@ var Wolbarg = class {
       );
     }
   }
+  /** Return the configured checkpoint provider or throw {@link ProviderNotConfiguredError}. */
   requireCheckpointProvider() {
     if (!this.checkpointProvider) {
       throw new ProviderNotConfiguredError(
@@ -9777,6 +10406,7 @@ var Wolbarg = class {
     }
     return this.checkpointProvider;
   }
+  /** Return the configured graph provider or throw with a setup hint for `method`. */
   requireGraph(method) {
     if (!this.graph) {
       throw new ProviderNotConfiguredError(
@@ -9787,20 +10417,24 @@ var Wolbarg = class {
     }
     return this.graph;
   }
+  /** Throw when graph checkpoint pairing is requested on a non-file-backed graph backend. */
   assertGraphCheckpointSupported(operation) {
     if (!this.graph) return;
     if (!this.graph.supportsFileSnapshot()) {
       throw new GraphCheckpointNotSupportedError(this.graph.name, operation);
     }
   }
+  /** Directory path where a graph file snapshot is stored alongside a memory checkpoint. */
   graphSnapshotDir(alongsidePath) {
     return `${alongsidePath}.graph`;
   }
+  /** Close the graph provider before copying files; returns whether a close occurred. */
   async closeGraphForSnapshot() {
     if (!this.graph || !this.graph.supportsFileSnapshot()) return false;
     await this.graph.close();
     return true;
   }
+  /** Copy the SQLite graph database next to a memory checkpoint directory. */
   async snapshotGraphAlongside(alongsidePath, operation) {
     if (!this.graph) return;
     if (!this.graph.supportsFileSnapshot()) {
@@ -9839,6 +10473,7 @@ var Wolbarg = class {
       await this.graph.open();
     }
   }
+  /** Restore a graph file snapshot written by {@link snapshotGraphAlongside}. */
   async restoreGraphAlongside(alongsidePath, operation) {
     if (!this.graph) return;
     if (!this.graph.supportsFileSnapshot()) {
@@ -9862,6 +10497,7 @@ var Wolbarg = class {
       fs6.cpSync(src, dataPath, { recursive: true });
     }
   }
+  /** Run graph traversal then re-hydrate stub records from storage when rows exist. */
   async hydrateRelated(memoryId, options) {
     const graph = this.requireGraph("getRelated");
     const related = await graph.getRelated(memoryId, options);
@@ -9877,6 +10513,7 @@ var Wolbarg = class {
     }
     return out;
   }
+  /** Resolve the on-disk SQLite memory database path (throws for Postgres / `:memory:`). */
   requireMemoryDbPath() {
     if (this.storage && !(this.storage instanceof SqliteStorageProvider)) {
       throw new ConfigurationError(
@@ -9928,6 +10565,7 @@ function commonTags(metadata) {
 
 // src/filters/types.ts
 var meta = {
+  /** Field equals value (strict equality). */
   eq: (field, value) => ({
     field,
     op: { eq: value }
@@ -10011,16 +10649,23 @@ function createTelemetryProvider(config) {
 function wolbarg2(options) {
   return new Wolbarg(options);
 }
+var createWolbarg = wolbarg2;
 
 // src/keyword/index.ts
 var Bm25KeywordSearchProvider = class {
   name = "bm25";
   k1;
   b;
+  /**
+   * @param options - BM25 tuning parameters.
+   * @param options.k1 - Term frequency saturation (default `1.2`).
+   * @param options.b - Length normalization (default `0.75`).
+   */
   constructor(options) {
     this.k1 = options?.k1 ?? 1.2;
     this.b = options?.b ?? 0.75;
   }
+  /** @inheritdoc */
   async search(query, documents, topK) {
     if (documents.length === 0 || topK <= 0) {
       return [];
@@ -10473,6 +11118,271 @@ function percentile(sorted, p) {
   return sorted[idx];
 }
 
-export { CompressionError, ConfigurationError, DatabaseError, EmbeddingError, FixedChunkingStrategy, GraphCheckpointNotSupportedError, HeadingChunkingStrategy, InitializationError, LlmCompressionProvider, MarkdownChunkingStrategy, MemoryNotFoundError, Neo4jGraphProvider, NoopTelemetryProvider, ParagraphChunkingStrategy, PostgresStorageProvider, ProviderNotConfiguredError, SDK_VERSION, SentenceChunkingStrategy, SqliteCheckpointProvider, SqliteDatabaseProvider, SqliteEventDatabase, SqliteGraphProvider, SqliteStorageProvider, SqliteTelemetryProvider, StorageLockedError, TelemetryEmitter, ValidationError, Wolbarg, WolbargError, WolbargLogger, bgeReranker, bm25, cohereReranker, createChunkingStrategy, createCompressionProvider, createDatabaseProvider, createEmbeddingProvider, createLlmProvider, createStorageProvider, createTelemetryProvider, wolbarg2 as createWolbarg, crossEncoder, geminiEmbedding, geminiVision, jinaReranker, lmStudioEmbedding, meta, neo4jGraph, ollamaEmbedding, ollamaLlm, openRouterEmbedding, openRouterLlm, openaiCompatibleEmbedding, openaiCompatibleLlm, openaiEmbedding, openaiLlm, openaiReranker, openaiVision, postgres, postgresConfig, runBenchmark, sqlite, sqliteCheckpoint, sqliteConfig, sqliteGraph, sqliteTelemetry, summarizeBenchmark, tesseract, togetherEmbedding, vllmEmbedding, wolbarg, wrapOperationError };
+// src/config/providers.ts
+var EMBEDDING_PROVIDER_PRESETS = [
+  {
+    id: "openai",
+    label: "OpenAI",
+    defaultBaseUrl: "https://api.openai.com/v1",
+    defaultModel: "text-embedding-3-small",
+    apiKeyEnv: "OPENAI_API_KEY"
+  },
+  {
+    id: "ollama",
+    label: "Ollama (local)",
+    defaultBaseUrl: "http://127.0.0.1:11434/v1",
+    defaultModel: "nomic-embed-text",
+    apiKeyEnv: "OLLAMA_API_KEY",
+    apiKeyHint: "Any non-empty value works locally (e.g. ollama)"
+  },
+  {
+    id: "openrouter",
+    label: "OpenRouter",
+    defaultBaseUrl: "https://openrouter.ai/api/v1",
+    defaultModel: "openai/text-embedding-3-small",
+    apiKeyEnv: "OPENROUTER_API_KEY"
+  },
+  {
+    id: "lmstudio",
+    label: "LM Studio (local)",
+    defaultBaseUrl: "http://127.0.0.1:1234/v1",
+    defaultModel: "text-embedding-nomic-embed-text-v1.5",
+    apiKeyEnv: "LM_STUDIO_API_KEY",
+    apiKeyHint: "Often unused locally \u2014 any non-empty value is fine"
+  },
+  {
+    id: "gemini",
+    label: "Google Gemini",
+    defaultBaseUrl: "https://generativelanguage.googleapis.com/v1beta/openai",
+    defaultModel: "text-embedding-004",
+    apiKeyEnv: "GEMINI_API_KEY"
+  },
+  {
+    id: "together",
+    label: "Together AI",
+    defaultBaseUrl: "https://api.together.xyz/v1",
+    defaultModel: "togethercomputer/m2-bert-80M-8k-retrieval",
+    apiKeyEnv: "TOGETHER_API_KEY"
+  },
+  {
+    id: "vllm",
+    label: "vLLM (local/server)",
+    defaultBaseUrl: "http://127.0.0.1:8000/v1",
+    defaultModel: "text-embedding-ada-002",
+    apiKeyEnv: "VLLM_API_KEY",
+    apiKeyHint: "Only if your server requires auth"
+  },
+  {
+    id: "custom",
+    label: "Custom OpenAI-compatible",
+    defaultBaseUrl: "https://api.openai.com/v1",
+    defaultModel: "text-embedding-3-small",
+    apiKeyEnv: "WOLBARG_EMBEDDING_API_KEY"
+  }
+];
+function getEmbeddingProviderPreset(id) {
+  return EMBEDDING_PROVIDER_PRESETS.find((p) => p.id === id);
+}
+var DEFAULT_SQLITE_DB_PATH = ".wolbarg/shared-memory/memory.db";
+var DEFAULT_ORGANIZATION = "default";
+var DEFAULT_CONFIG_PATH = ".wolbarg/config.json";
+var DEFAULT_ENV_PATH = ".wolbarg/.env";
+function defaultProjectConfig() {
+  return {
+    version: 1,
+    organization: DEFAULT_ORGANIZATION,
+    database: {
+      provider: "sqlite",
+      url: DEFAULT_SQLITE_DB_PATH
+    },
+    paths: {
+      config: DEFAULT_CONFIG_PATH
+    }
+  };
+}
+function resolveConfigPath(cwd = process.cwd(), configPath) {
+  const rel = configPath ?? DEFAULT_CONFIG_PATH;
+  return isAbsolute(rel) ? rel : resolve(cwd, rel);
+}
+function resolveEnvPath(cwd = process.cwd(), envPath) {
+  const rel = envPath ?? DEFAULT_ENV_PATH;
+  return isAbsolute(rel) ? rel : resolve(cwd, rel);
+}
+function loadProjectConfig(cwd = process.cwd(), configPath) {
+  const full = resolveConfigPath(cwd, configPath);
+  if (!existsSync(full)) return null;
+  const raw = JSON.parse(readFileSync(full, "utf8"));
+  if (!raw || raw.version !== 1 || !raw.database?.url) {
+    throw new Error(`Invalid Wolbarg config at ${full}`);
+  }
+  return raw;
+}
+function saveProjectConfig(config, options = {}) {
+  const cwd = options.cwd ?? process.cwd();
+  const configPath = resolveConfigPath(cwd, options.configPath);
+  const dir = dirname(configPath);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  if (existsSync(configPath) && options.overwrite === false) {
+    throw new Error(`Config already exists: ${configPath} (pass --force to overwrite)`);
+  }
+  const toWrite = {
+    ...config,
+    paths: {
+      config: options.configPath ?? DEFAULT_CONFIG_PATH,
+      ...options.envPath || options.apiKey ? { env: options.envPath ?? DEFAULT_ENV_PATH } : config.paths?.env ? { env: config.paths.env } : {}
+    }
+  };
+  writeFileSync(configPath, `${JSON.stringify(toWrite, null, 2)}
+`, "utf8");
+  let envPath;
+  if (options.apiKey && config.embedding?.apiKeyEnv) {
+    envPath = resolveEnvPath(cwd, options.envPath);
+    ensureParent(envPath);
+    upsertEnvVar(envPath, config.embedding.apiKeyEnv, options.apiKey);
+    ensureGitignore(cwd, [DEFAULT_ENV_PATH, ".env"]);
+  }
+  if (config.database.provider === "sqlite" && !config.database.url.includes("://")) {
+    const dbPath = isAbsolute(config.database.url) ? config.database.url : resolve(cwd, config.database.url);
+    ensureParent(dbPath);
+  }
+  return { configPath, envPath };
+}
+function ensureParent(filePath) {
+  const dir = dirname(filePath);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+}
+function upsertEnvVar(envPath, key, value) {
+  ensureParent(envPath);
+  let text = existsSync(envPath) ? readFileSync(envPath, "utf8") : "";
+  const line = `${key}=${shellQuoteEnv(value)}`;
+  const re = new RegExp(`^${escapeRegExp(key)}=.*$`, "m");
+  if (re.test(text)) {
+    text = text.replace(re, line);
+  } else {
+    if (text && !text.endsWith("\n")) text += "\n";
+    text += `${line}
+`;
+  }
+  writeFileSync(envPath, text, "utf8");
+}
+function shellQuoteEnv(value) {
+  if (/[\s#"']/.test(value)) {
+    return `"${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+  }
+  return value;
+}
+function escapeRegExp(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function ensureGitignore(cwd, entries) {
+  const gi = join(cwd, ".gitignore");
+  let text = existsSync(gi) ? readFileSync(gi, "utf8") : "";
+  let changed = false;
+  for (const entry of entries) {
+    if (text.split(/\r?\n/).some((l) => l.trim() === entry)) continue;
+    if (text && !text.endsWith("\n")) text += "\n";
+    text += `${entry}
+`;
+    changed = true;
+  }
+  if (changed) writeFileSync(gi, text, "utf8");
+}
+function resolveEmbeddingApiKey(config, env = process.env) {
+  const name = config.embedding?.apiKeyEnv;
+  if (!name) return "";
+  return env[name] ?? "";
+}
+function assertEmbeddingPreset(provider) {
+  const preset = getEmbeddingProviderPreset(provider);
+  if (!preset) {
+    throw new Error(
+      `Unknown embedding provider "${provider}". Choose one of: ${[
+        "openai",
+        "ollama",
+        "openrouter",
+        "lmstudio",
+        "gemini",
+        "together",
+        "vllm",
+        "custom"
+      ].join(", ")}`
+    );
+  }
+  return preset.id;
+}
+function applyEnvFile(envPath, base = {}) {
+  const out = { ...base };
+  if (!existsSync(envPath)) return out;
+  const text = readFileSync(envPath, "utf8");
+  for (const rawLine of text.split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith("#")) continue;
+    const eq = line.indexOf("=");
+    if (eq <= 0) continue;
+    const key = line.slice(0, eq).trim();
+    let value = line.slice(eq + 1).trim();
+    if (value.startsWith('"') && value.endsWith('"') || value.startsWith("'") && value.endsWith("'")) {
+      value = value.slice(1, -1);
+    }
+    if (out[key] === void 0) out[key] = value;
+  }
+  return out;
+}
+function projectConfigToWolbargOptions(config, env = process.env) {
+  if (!config.embedding) {
+    throw new Error(
+      "Project config has no embedding section. Re-run `wolbarg init` and configure an embedding provider, or pass embedding explicitly to wolbarg()."
+    );
+  }
+  const apiKey = resolveEmbeddingApiKey(config, env);
+  if (!apiKey) {
+    throw new Error(
+      `Missing API key. Set ${config.embedding.apiKeyEnv} in the environment or in .wolbarg/.env (from wolbarg init).`
+    );
+  }
+  const dbUrl = config.database.url;
+  return {
+    organization: config.organization,
+    database: {
+      provider: config.database.provider,
+      url: dbUrl,
+      connectionString: dbUrl
+    },
+    embedding: {
+      baseUrl: config.embedding.baseUrl,
+      apiKey,
+      model: config.embedding.model
+    }
+  };
+}
+function createWolbargFromProjectConfig(options = {}) {
+  const cwd = options.cwd ?? process.cwd();
+  const config = loadProjectConfig(cwd, options.configPath);
+  if (!config) {
+    throw new Error(
+      `No Wolbarg config found. Run \`wolbarg init\` in ${cwd} (expected .wolbarg/config.json).`
+    );
+  }
+  let env = options.env ?? { ...process.env };
+  if (options.loadEnvFile !== false) {
+    const envFile = resolveEnvPath(
+      cwd,
+      config.paths?.env ?? DEFAULT_ENV_PATH
+    );
+    env = applyEnvFile(envFile, env);
+  }
+  if (options.organization) {
+    config.organization = options.organization;
+  }
+  if (config.database.provider === "sqlite" && !config.database.url.includes("://") && !isAbsolute(config.database.url)) {
+    config.database = {
+      ...config.database,
+      url: resolve(cwd, config.database.url)
+    };
+  }
+  return wolbarg(projectConfigToWolbargOptions(config, env));
+}
+
+export { CompressionError, ConfigurationError, DEFAULT_CONFIG_PATH, DEFAULT_ENV_PATH, DEFAULT_ORGANIZATION, DEFAULT_SQLITE_DB_PATH, DatabaseError, EMBEDDING_PROVIDER_PRESETS, EmbeddingError, FixedChunkingStrategy, GraphCheckpointNotSupportedError, HeadingChunkingStrategy, InitializationError, LlmCompressionProvider, MarkdownChunkingStrategy, MemoryNotFoundError, Neo4jGraphProvider, NoopTelemetryProvider, ParagraphChunkingStrategy, PostgresStorageProvider, ProviderNotConfiguredError, SDK_VERSION, SentenceChunkingStrategy, SqliteCheckpointProvider, SqliteDatabaseProvider, SqliteEventDatabase, SqliteGraphProvider, SqliteStorageProvider, SqliteTelemetryProvider, StorageLockedError, TelemetryEmitter, ValidationError, Wolbarg, WolbargError, WolbargLogger, applyEnvFile, assertEmbeddingPreset, bgeReranker, bm25, cohereReranker, createChunkingStrategy, createCompressionProvider, createDatabaseProvider, createEmbeddingProvider, createLlmProvider, createStorageProvider, createTelemetryProvider, createWolbarg, createWolbargFromProjectConfig, crossEncoder, defaultProjectConfig, geminiEmbedding, geminiVision, getEmbeddingProviderPreset, jinaReranker, lmStudioEmbedding, loadProjectConfig, meta, neo4jGraph, ollamaEmbedding, ollamaLlm, openRouterEmbedding, openRouterLlm, openaiCompatibleEmbedding, openaiCompatibleLlm, openaiEmbedding, openaiLlm, openaiReranker, openaiVision, postgres, postgresConfig, projectConfigToWolbargOptions, resolveConfigPath, resolveEmbeddingApiKey, resolveEnvPath, runBenchmark, saveProjectConfig, sqlite, sqliteCheckpoint, sqliteConfig, sqliteGraph, sqliteTelemetry, summarizeBenchmark, tesseract, togetherEmbedding, upsertEnvVar, vllmEmbedding, wolbarg, wrapOperationError };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map