wolbarg 0.5.4 → 0.5.6

package/dist/index.cjs

@@ -42,6 +42,11 @@ var WolbargError = class extends Error {
   reason;
   suggestion;
   operation;
+  /**
+   * @param message - Human-readable error message.
+   * @param code - Stable error code string.
+   * @param options - Optional cause, reason, suggestion, and operation name.
+   */
   constructor(message, code, options) {
     super(message, options);
     this.name = "WolbargError";
@@ -53,48 +58,80 @@ var WolbargError = class extends Error {
   }
 };
 var InitializationError = class extends WolbargError {
+  /**
+   * @param message - Description of the initialization failure.
+   * @param options - Optional cause and structured hints.
+   */
   constructor(message, options) {
     super(message, "INITIALIZATION_ERROR", options);
     this.name = "InitializationError";
   }
 };
 var ConfigurationError = class extends WolbargError {
+  /**
+   * @param message - Description of the misconfiguration.
+   * @param options - Optional cause, reason, suggestion, and operation name.
+   */
   constructor(message, options) {
     super(message, "CONFIGURATION_ERROR", options);
     this.name = "ConfigurationError";
   }
 };
 var ValidationError = class extends WolbargError {
+  /**
+   * @param message - Which argument failed and why.
+   * @param options - Optional cause and structured hints.
+   */
   constructor(message, options) {
     super(message, "VALIDATION_ERROR", options);
     this.name = "ValidationError";
   }
 };
 var DatabaseError = class extends WolbargError {
+  /**
+   * @param message - Operation-scoped failure message.
+   * @param options - Optional underlying `cause` and hints.
+   */
   constructor(message, options) {
     super(message, "DATABASE_ERROR", options);
     this.name = "DatabaseError";
   }
 };
 var StorageLockedError = class extends WolbargError {
+  /**
+   * @param message - Lock contention description.
+   * @param options - Typically includes suggestion to tune concurrency or use Postgres.
+   */
   constructor(message, options) {
     super(message, "WOLBARG_STORAGE_LOCKED", options);
     this.name = "StorageLockedError";
   }
 };
 var EmbeddingError = class extends WolbargError {
+  /**
+   * @param message - Embedding failure description.
+   * @param options - Optional HTTP cause and provider hints.
+   */
   constructor(message, options) {
     super(message, "EMBEDDING_ERROR", options);
     this.name = "EmbeddingError";
   }
 };
 var CompressionError = class extends WolbargError {
+  /**
+   * @param message - Compression failure description.
+   * @param options - Optional LLM cause chain.
+   */
   constructor(message, options) {
     super(message, "COMPRESSION_ERROR", options);
     this.name = "CompressionError";
   }
 };
 var MemoryNotFoundError = class extends WolbargError {
+  /**
+   * @param message - Which memory was not found.
+   * @param options - Optional operation context.
+   */
   constructor(message, options) {
     super(message, "MEMORY_NOT_FOUND", options);
     this.name = "MemoryNotFoundError";
@@ -102,6 +139,11 @@ var MemoryNotFoundError = class extends WolbargError {
 };
 var ProviderNotConfiguredError = class extends ConfigurationError {
   provider;
+  /**
+   * @param provider - Provider name (e.g. `"reranker"`, `"graph"`).
+   * @param method - Facade method that requires the provider.
+   * @param hint - Install or config instruction shown to the developer.
+   */
   constructor(provider, method, hint) {
     super(`${method} requires ${provider} \u2014 ${hint}`, {
       operation: method,
@@ -113,6 +155,10 @@ var ProviderNotConfiguredError = class extends ConfigurationError {
   }
 };
 var GraphCheckpointNotSupportedError = class extends WolbargError {
+  /**
+   * @param backend - Graph backend name (e.g. `"neo4j"`).
+   * @param operation - Requested operation (e.g. `"checkpoint"`).
+   */
   constructor(backend, operation) {
     super(
       `graph checkpoint not supported for network-backed graph providers (${backend})`,
@@ -185,9 +231,11 @@ Rules:
 var LlmCompressionProvider = class {
   name = "llm";
   llm;
+  /** @param llm - Configured LLM used for summarization. */
   constructor(llm) {
     this.llm = llm;
   }
+  /** @inheritdoc */
   async compress(memories) {
     return compressMemories(this.llm, memories);
   }
@@ -296,6 +344,7 @@ function slidingWindow(text, chunkSize, overlap) {
 }
 var FixedChunkingStrategy = class {
   name = "fixed";
+  /** @inheritdoc */
   chunk(text, options) {
     const { chunkSize, overlap } = clampOptions(options);
     return slidingWindow(text, chunkSize, overlap);
@@ -303,6 +352,7 @@ var FixedChunkingStrategy = class {
 };
 var SentenceChunkingStrategy = class {
   name = "sentence";
+  /** @inheritdoc */
   chunk(text, options) {
     const { chunkSize, overlap } = clampOptions(options);
     const sentences = text.split(/(?<=[.!?])\s+/).map((s) => s.trim()).filter(Boolean);
@@ -311,6 +361,7 @@ var SentenceChunkingStrategy = class {
 };
 var ParagraphChunkingStrategy = class {
   name = "paragraph";
+  /** @inheritdoc */
   chunk(text, options) {
     const { chunkSize, overlap } = clampOptions(options);
     const paragraphs = text.split(/\n\s*\n/).map((p) => p.trim()).filter(Boolean);
@@ -319,6 +370,7 @@ var ParagraphChunkingStrategy = class {
 };
 var MarkdownChunkingStrategy = class {
   name = "markdown";
+  /** @inheritdoc */
   chunk(text, options) {
     const { chunkSize, overlap } = clampOptions(options);
     const sections = text.split(/(?=^#{1,6}\s)/m).map((s) => s.trim()).filter(Boolean);
@@ -330,6 +382,7 @@ var MarkdownChunkingStrategy = class {
 };
 var HeadingChunkingStrategy = class {
   name = "heading";
+  /** @inheritdoc */
   chunk(text, options) {
     return new MarkdownChunkingStrategy().chunk(text, options);
   }
@@ -411,10 +464,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);
@@ -434,16 +493,32 @@ function joinUrl(baseUrl, path8) {
 
 // src/embedding/index.ts
 var OpenAICompatibleEmbeddingProvider = class {
+  /** Model name sent in the request body. */
   model;
   baseUrl;
   apiKey;
   timeoutMs;
+  /**
+   * @param config - OpenAI-compatible embedding endpoint settings.
+   * @param config.baseUrl - API root, e.g. `https://api.openai.com/v1`.
+   * @param config.apiKey - Bearer token. Use any non-empty string for local
+   *   servers that ignore auth.
+   * @param config.model - Embedding model id (e.g. `"text-embedding-3-small"`).
+   * @param config.timeoutMs - Abort after this many ms. Defaults to `30_000`.
+   */
   constructor(config) {
     this.baseUrl = config.baseUrl;
     this.apiKey = config.apiKey;
     this.model = config.model;
     this.timeoutMs = config.timeoutMs ?? 3e4;
   }
+  /**
+   * Embed a single string.
+   *
+   * @param text - Input text.
+   * @returns Embedding vector.
+   * @throws {EmbeddingError} On HTTP errors, timeouts, or empty vectors.
+   */
   async embed(text) {
     const response = await this.request(text);
     const vector = response.data?.[0]?.embedding;
@@ -452,6 +527,13 @@ var OpenAICompatibleEmbeddingProvider = class {
     }
     return Float32Array.from(vector);
   }
+  /**
+   * Embed multiple strings in one API call when the server supports batch input.
+   * Falls back to sequential {@link embed} if the response length mismatches.
+   *
+   * @param texts - Inputs to embed.
+   * @returns One vector per input, same order.
+   */
   async embedBatch(texts) {
     if (texts.length === 0) {
       return [];
@@ -478,6 +560,12 @@ var OpenAICompatibleEmbeddingProvider = class {
       return Float32Array.from(item.embedding);
     });
   }
+  /**
+   * Probe the endpoint and report vector dimensionality.
+   *
+   * @returns `{ dimensions }` from a fixed health-check string.
+   * @throws {EmbeddingError} When the probe fails.
+   */
   async validate() {
     try {
       const embedding = await this.embed("Wolbarg health check");
@@ -492,6 +580,12 @@ var OpenAICompatibleEmbeddingProvider = class {
       );
     }
   }
+  /**
+   * Low-level HTTP request to `/embeddings`.
+   *
+   * @param input - Single string or batch of strings.
+   * @returns Parsed OpenAI-style JSON body.
+   */
   async request(input) {
     const url = joinUrl(this.baseUrl, "/embeddings");
     const controller = new AbortController();
@@ -539,6 +633,7 @@ var OpenAICompatibleEmbeddingProvider = class {
       clearTimeout(timer);
     }
   }
+  /** @param error - Unknown thrown value. @returns Human-readable message. */
   describe(error) {
     if (error instanceof Error) {
       return error.message;
@@ -795,6 +890,10 @@ var SqliteEmbeddingCacheStore = class {
   pendingSets = /* @__PURE__ */ new Map();
   persistScheduled = false;
   stmts = null;
+  /**
+   * @param dbOrGetter - SQLite `DatabaseSync` or lazy getter (allows late bind).
+   * @param options.ttlMs - Optional TTL for cache entries on read.
+   */
   constructor(dbOrGetter, options) {
     this.ttlMs = options?.ttlMs ?? null;
     this.getDb = typeof dbOrGetter === "function" ? dbOrGetter : () => dbOrGetter;
@@ -1071,12 +1170,23 @@ var PostgresEmbeddingCacheStore = class {
 
 // src/llm/index.ts
 var OpenAICompatibleLlmProvider = class {
+  /** Model name sent in the request body and exposed on the provider. */
   model;
   baseUrl;
   apiKey;
   temperature;
   maxTokens;
   timeoutMs;
+  /**
+   * @param config - OpenAI-compatible endpoint settings.
+   * @param config.baseUrl - API root, e.g. `https://api.openai.com/v1` (no trailing `/chat/completions`).
+   * @param config.apiKey - Bearer token (`Authorization: Bearer …`). Use any non-empty
+   *   string for local servers that ignore auth (e.g. `"ollama"`).
+   * @param config.model - Chat model id (e.g. `"gpt-4o-mini"`, `"llama3.2"`).
+   * @param config.temperature - Sampling temperature. Defaults to `0.2`.
+   * @param config.maxTokens - Max completion tokens. Defaults to `4096`.
+   * @param config.timeoutMs - Abort after this many ms. Defaults to `60_000`.
+   */
   constructor(config) {
     this.baseUrl = config.baseUrl;
     this.apiKey = config.apiKey;
@@ -1085,6 +1195,13 @@ var OpenAICompatibleLlmProvider = class {
     this.maxTokens = config.maxTokens ?? 4096;
     this.timeoutMs = config.timeoutMs ?? 6e4;
   }
+  /**
+   * Call `/chat/completions` and return the first choice’s message content.
+   *
+   * @param messages - Chat turns in OpenAI message format.
+   * @returns Trimmed assistant text.
+   * @throws {CompressionError} On HTTP errors, timeouts, or empty content.
+   */
   async complete(messages) {
     const response = await this.request(messages);
     const content = response.choices?.[0]?.message?.content;
@@ -1093,6 +1210,11 @@ var OpenAICompatibleLlmProvider = class {
     }
     return content.trim();
   }
+  /**
+   * Probe the endpoint with a fixed `"ok"` prompt.
+   *
+   * @throws {CompressionError} When validation fails.
+   */
   async validate() {
     try {
       await this.complete([
@@ -1114,6 +1236,12 @@ var OpenAICompatibleLlmProvider = class {
       );
     }
   }
+  /**
+   * Low-level HTTP request to `/chat/completions`.
+   *
+   * @param messages - Chat turns to send.
+   * @returns Parsed OpenAI-style JSON body.
+   */
   async request(messages) {
     const url = joinUrl(this.baseUrl, "/chat/completions");
     const controller = new AbortController();
@@ -1162,6 +1290,7 @@ var OpenAICompatibleLlmProvider = class {
       clearTimeout(timer);
     }
   }
+  /** @param error - Unknown thrown value. @returns Human-readable message. */
   describe(error) {
     if (error instanceof Error) {
       return error.message;
@@ -1557,28 +1686,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);
   }
@@ -1921,18 +2070,29 @@ var InMemoryVectorIndex = class {
   data;
   count = 0;
   rowidToSlot = /* @__PURE__ */ new Map();
+  /**
+   * @param dimensions - Embedding vector length.
+   * @param initialCapacity - Initial slot capacity (default `256`).
+   */
   constructor(dimensions, initialCapacity = 256) {
     this.dims = dimensions;
     this.data = new Float32Array(initialCapacity * dimensions);
   }
+  /** Number of indexed vectors. */
   get size() {
     return this.count;
   }
+  /** Remove all vectors from the index. */
   clear() {
     this.rowids.length = 0;
     this.rowidToSlot.clear();
     this.count = 0;
   }
+  /**
+   * Insert or replace a vector for `rowid` (L2-normalized internally).
+   * @param rowid - Memory table row identifier.
+   * @param embedding - Raw embedding vector.
+   */
   upsert(rowid, embedding) {
     const existing = this.rowidToSlot.get(rowid);
     const slot = existing !== void 0 ? existing : (() => {
@@ -1963,6 +2123,10 @@ var InMemoryVectorIndex = class {
       }
     }
   }
+  /**
+   * Remove a vector by `rowid`.
+   * @param rowid - Memory table row identifier.
+   */
   remove(rowid) {
     const slot = this.rowidToSlot.get(rowid);
     if (slot === void 0) {
@@ -1982,7 +2146,12 @@ var InMemoryVectorIndex = class {
     this.rowidToSlot.delete(rowid);
     this.count = last;
   }
-  /** Top-k by cosine distance (1 - dot) assuming query is L2-normalized. */
+  /**
+   * Top-k by cosine distance (1 - dot) assuming query is L2-normalized.
+   *
+   * @param queryNormalized - L2-normalized query vector (use {@link normalizeEmbedding}).
+   * @param topK - Maximum hits to return.
+   */
   search(queryNormalized, topK) {
     const n = this.count;
     if (n === 0 || topK <= 0) {
@@ -2134,7 +2303,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(
@@ -2258,6 +2427,9 @@ var SqliteStorageProvider = class _SqliteStorageProvider {
   /** Coalesce concurrent insertMemory callers into one IMMEDIATE transaction. */
   insertQueue = [];
   insertFlushScheduled = false;
+  /**
+   * @param options - SQLite path / `:memory:` and optional concurrency config.
+   */
   constructor(options) {
     this.connectionString = options.connectionString;
     this.concurrency = resolveConcurrencyConfig(options.concurrency);
@@ -2270,9 +2442,11 @@ var SqliteStorageProvider = class _SqliteStorageProvider {
   getDatabase() {
     return this.db;
   }
+  /** Register a callback invoked when SQLite busy retries occur (tests / diagnostics). */
   setRetryLogger(fn) {
     this.retryLog = fn;
   }
+  /** Open the database, run migrations, and prepare statements. */
   async open() {
     try {
       const dbPath = this.resolvePath(this.connectionString);
@@ -2332,6 +2506,7 @@ var SqliteStorageProvider = class _SqliteStorageProvider {
       );
     }
   }
+  /** Drain pending inserts, optimize, and close the SQLite connection. */
   async close() {
     const deadline = Date.now() + 2e3;
     while (this.insertQueue.length > 0 && Date.now() < deadline) {
@@ -2362,6 +2537,11 @@ var SqliteStorageProvider = class _SqliteStorageProvider {
       this.batchBlobEmbStatements.clear();
     }
   }
+  /**
+   * Create or validate vec0 / blob vector storage for the given dimensionality.
+   *
+   * @param dimensions - Embedding length from the configured model.
+   */
   async ensureVectorSchema(dimensions) {
     const existing = await this.getEmbeddingDimensions();
     if (existing !== null && existing !== dimensions) {
@@ -2384,17 +2564,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();
@@ -2472,6 +2655,7 @@ var SqliteStorageProvider = class _SqliteStorageProvider {
       return row;
     });
   }
+  /** Batch insert memories in chunked multi-row transactions. */
   async insertMemoriesBatch(inputs) {
     if (inputs.length === 0) {
       return [];
@@ -2487,6 +2671,7 @@ var SqliteStorageProvider = class _SqliteStorageProvider {
       return rows;
     });
   }
+  /** Update memory content, metadata, embedding, and content hash. */
   async updateMemory(input) {
     const stmts = this.requireStatements();
     return this.withTransaction(() => {
@@ -2530,6 +2715,7 @@ var SqliteStorageProvider = class _SqliteStorageProvider {
       return stmts.getMemoryById.get(input.id, input.organization);
     });
   }
+  /** Find an active memory by org, agent, and content hash (dedupe). */
   async findActiveByContentHash(organization, agent, contentHash) {
     const stmts = this.requireStatements();
     const row = stmts.findActiveByContentHash.get(
@@ -2539,6 +2725,7 @@ var SqliteStorageProvider = class _SqliteStorageProvider {
     );
     return row ?? null;
   }
+  /** Scan memories matching metadata filters (may paginate in SQL). */
   async searchByMetadata(filter, limit) {
     const rows = await this.listMemories(filter, limit);
     if (!filter.metadata) {
@@ -2549,6 +2736,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) {
@@ -2584,16 +2772,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) {
@@ -2612,6 +2803,7 @@ var SqliteStorageProvider = class _SqliteStorageProvider {
     }
     return out;
   }
+  /** List memories matching repository filters with optional limit. */
   async listMemories(filter, limit) {
     try {
       if (filter.metadata) {
@@ -2624,6 +2816,7 @@ var SqliteStorageProvider = class _SqliteStorageProvider {
       });
     }
   }
+  /** Approximate nearest-neighbor search (vec0 or in-memory blob index). */
   async searchVectors(embedding, topK) {
     this.requireVectorReady();
     if (this.vectorBackend === "sqlite-vec") {
@@ -2635,6 +2828,7 @@ var SqliteStorageProvider = class _SqliteStorageProvider {
    * Org-scoped KNN + memory rows with adaptive overfetch.
    * Global ANN is post-filtered by org/agent/archived; underfill triggers larger k.
    */
+  /** ANN search joined with memory rows and org/archived post-filters. */
   async searchVectorsWithMemories(embedding, topK, organization, options) {
     this.requireVectorReady();
     if (topK <= 0) {
@@ -2673,6 +2867,7 @@ var SqliteStorageProvider = class _SqliteStorageProvider {
     }
     return out;
   }
+  /** Soft-archive memories (compression / forget paths). */
   async archiveMemories(ids, organization, compressedIntoId, archivedAt) {
     const stmts = this.requireStatements();
     const archived = [];
@@ -2710,6 +2905,7 @@ var SqliteStorageProvider = class _SqliteStorageProvider {
       return archived;
     });
   }
+  /** Hard-delete a single memory by id; returns whether a row was removed. */
   async deleteMemoryById(id, organization) {
     const stmts = this.requireStatements();
     return this.withTransaction(() => {
@@ -2723,6 +2919,7 @@ var SqliteStorageProvider = class _SqliteStorageProvider {
       return Number(result.changes) > 0;
     });
   }
+  /** Hard-delete memories matching org / agent / metadata filters. */
   async deleteMemoriesByFilter(filter) {
     const stmts = this.requireStatements();
     const agent = filter.agent;
@@ -2739,6 +2936,7 @@ var SqliteStorageProvider = class _SqliteStorageProvider {
       return Number(result.changes);
     });
   }
+  /** Remove all memories (and side tables) for an organization. */
   async clearOrganization(organization) {
     const stmts = this.requireStatements();
     return this.withTransaction(() => {
@@ -2755,10 +2953,12 @@ var SqliteStorageProvider = class _SqliteStorageProvider {
       return Number(result.changes);
     });
   }
+  /** List audit history events for a memory id. */
   async getHistory(memoryId) {
     const stmts = this.requireStatements();
     return stmts.getHistory.all(memoryId);
   }
+  /** Append a history row (created / archived / compressed / updated). */
   async insertHistoryEvent(event) {
     const stmts = this.requireStatements();
     stmts.insertHistory.run(
@@ -2769,6 +2969,7 @@ var SqliteStorageProvider = class _SqliteStorageProvider {
       event.created_at
     );
   }
+  /** Aggregate memory counts for an organization (single-pass SQL). */
   async getStats(organization) {
     const stmts = this.requireStatements();
     const row = stmts.getStats.get(organization);
@@ -2779,6 +2980,7 @@ var SqliteStorageProvider = class _SqliteStorageProvider {
       totalAgents: Number(row.agents)
     };
   }
+  /** On-disk database file size in bytes (0 for `:memory:`). */
   async getDatabaseSizeBytes() {
     const db = this.requireDb();
     if (this.connectionString === ":memory:") {
@@ -3837,11 +4039,17 @@ var PostgresSubscribeListener = class {
   reconnectDelayMs;
   connect;
   onError;
+  /**
+   * @param options.connect - Factory returning a dedicated LISTEN client.
+   * @param options.reconnectDelayMs - Delay before reconnect attempts (default 1000).
+   * @param options.onError - Optional error hook for connection failures.
+   */
   constructor(options) {
     this.connect = options.connect;
     this.reconnectDelayMs = options.reconnectDelayMs ?? 1e3;
     this.onError = options.onError;
   }
+  /** Open the LISTEN connection (lazy — also started on first subscribe). */
   async start() {
     if (this.closed) {
       return;
@@ -3938,6 +4146,13 @@ var PostgresSubscribeListener = class {
       }
     }
   }
+  /**
+   * Register a filtered callback for memory change events.
+   *
+   * @param filter - Organization / agent / event-type filter.
+   * @param callback - Invoked synchronously on each matching NOTIFY.
+   * @returns Unsubscribe function.
+   */
   subscribe(filter, callback) {
     if (this.closed) {
       throw new Error("Subscribe backend is closed");
@@ -3959,6 +4174,7 @@ var PostgresSubscribeListener = class {
    */
   emit(_event) {
   }
+  /** Tear down LISTEN connection and clear subscriptions. */
   async close() {
     this.closed = true;
     this.subscriptions.clear();
@@ -4123,6 +4339,9 @@ var PostgresStorageProvider = class _PostgresStorageProvider {
   insertFlushScheduled = false;
   insertFlushTimer = null;
   insertFlushInFlight = 0;
+  /**
+   * @param options - Connection string, pool size, and durability flags.
+   */
   constructor(options) {
     this.maxPoolSize = options.maxPoolSize ?? 64;
     this.durableWrites = options.durableWrites !== false;
@@ -4131,6 +4350,7 @@ var PostgresStorageProvider = class _PostgresStorageProvider {
       this.durableWrites
     );
   }
+  /** Current pg pool occupancy stats (for diagnostics / subscribe setup). */
   getPoolStats() {
     const pool = this.pool;
     return {
@@ -4144,6 +4364,7 @@ var PostgresStorageProvider = class _PostgresStorageProvider {
   getPool() {
     return this.pool;
   }
+  /** Open the connection pool and run migrations. */
   async open() {
     let PoolCtor;
     try {
@@ -4192,6 +4413,7 @@ var PostgresStorageProvider = class _PostgresStorageProvider {
       );
     }
   }
+  /** Drain coalesced inserts and end the connection pool. */
   async close() {
     if (this.insertFlushTimer) {
       clearTimeout(this.insertFlushTimer);
@@ -4232,6 +4454,11 @@ var PostgresStorageProvider = class _PostgresStorageProvider {
   async ensureVectorIndex() {
     await this.ensureHnswIndex();
   }
+  /**
+   * Create pgvector tables and HNSW index for the given dimensionality.
+   *
+   * @param dimensions - Embedding length from the configured model.
+   */
   async ensureVectorSchema(dimensions) {
     const existing = await this.getEmbeddingDimensions();
     if (existing !== null && existing !== dimensions) {
@@ -4296,6 +4523,11 @@ var PostgresStorageProvider = class _PostgresStorageProvider {
     }
   }
   /** Cross-process subscribe: NOTIFY after a committed write. */
+  /**
+   * Issue `pg_notify` for cross-process {@link subscribe} delivery.
+   *
+   * @param event - Memory change payload (IDs + metadata only).
+   */
   async notifyChange(event) {
     await notifyMemoryChange(this.requirePool(), event);
   }
@@ -4303,6 +4535,7 @@ var PostgresStorageProvider = class _PostgresStorageProvider {
    * Soft reset for a single organization. Drops HNSW only when the embeddings
    * table is empty so other corpora on a shared bench DB stay intact.
    */
+  /** Delete all rows for an organization (dev / test helper). */
   async resetOrganization(organization) {
     await this.query(`DELETE FROM memories WHERE organization = $1`, [
       organization
@@ -4320,6 +4553,7 @@ var PostgresStorageProvider = class _PostgresStorageProvider {
   /**
    * Wipe all Wolbarg tables (explicit opt-in). Prefer {@link resetOrganization}.
    */
+  /** Truncate all Wolbarg tables (dev / test helper). */
   async wipeAllData() {
     await this.query(`TRUNCATE TABLE memories CASCADE`).catch(() => void 0);
     await this.query(
@@ -4379,6 +4613,7 @@ var PostgresStorageProvider = class _PostgresStorageProvider {
       }
     }
   }
+  /** @inheritdoc StorageProvider.getEmbeddingDimensions */
   async getEmbeddingDimensions() {
     const result = await this.query(
       `SELECT value FROM Wolbarg_meta WHERE key = $1`,
@@ -4391,6 +4626,7 @@ var PostgresStorageProvider = class _PostgresStorageProvider {
     const parsed = Number(value);
     return Number.isFinite(parsed) ? parsed : null;
   }
+  /** @inheritdoc StorageProvider.setEmbeddingDimensions */
   async setEmbeddingDimensions(dimensions) {
     await this.query(
       `INSERT INTO Wolbarg_meta (key, value) VALUES ($1, $2)
@@ -4399,10 +4635,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();
@@ -4485,6 +4722,7 @@ var PostgresStorageProvider = class _PostgresStorageProvider {
     }
     return this.insertOneBlob(input);
   }
+  /** Batch insert via unnest / COPY paths with optional HNSW deferral. */
   async insertMemoriesBatch(inputs) {
     if (inputs.length === 0) {
       return [];
@@ -4633,6 +4871,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);
@@ -4668,6 +4907,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,
@@ -4680,6 +4920,7 @@ var PostgresStorageProvider = class _PostgresStorageProvider {
     const row = result.rows[0];
     return row ? this.mapRow(row) : null;
   }
+  /** Fetch a memory row by UUID within an organization. */
   async getMemoryById(id, organization) {
     const result = await this.query(
       `SELECT id, organization, agent, content_text, metadata_json,
@@ -4690,6 +4931,7 @@ var PostgresStorageProvider = class _PostgresStorageProvider {
     const row = result.rows[0];
     return row ? this.mapRow(row) : null;
   }
+  /** Fetch a memory row by internal rowid within an organization. */
   async getMemoryByRowid(rowid, organization) {
     const result = await this.query(
       `SELECT m.id, m.organization, m.agent, m.content_text, m.metadata_json,
@@ -4703,6 +4945,7 @@ var PostgresStorageProvider = class _PostgresStorageProvider {
     const row = result.rows[0];
     return row ? this.mapRow(row) : null;
   }
+  /** Batch-fetch memory rows by rowids within an organization. */
   async getMemoriesByRowids(rowids, organization) {
     const out = /* @__PURE__ */ new Map();
     if (rowids.length === 0) {
@@ -4725,6 +4968,7 @@ var PostgresStorageProvider = class _PostgresStorageProvider {
     }
     return out;
   }
+  /** List memories matching repository filters with optional limit. */
   async listMemories(filter, limit) {
     const want = limit !== void 0 ? limit : filter.metadata ? 1e4 : void 0;
     const compiled = filter.metadata ? compileMetadataFilterToPostgres(filter.metadata, 2) : null;
@@ -4786,9 +5030,11 @@ var PostgresStorageProvider = class _PostgresStorageProvider {
     }
     return rows;
   }
+  /** Scan memories matching metadata filters. */
   async searchByMetadata(filter, limit) {
     return this.listMemories(filter, limit);
   }
+  /** Full-text keyword search via `tsvector` / GIN index. */
   async searchKeyword(query, organization, topK) {
     const trimmed = query.trim();
     if (!trimmed || topK <= 0) {
@@ -4828,6 +5074,7 @@ var PostgresStorageProvider = class _PostgresStorageProvider {
       return [];
     }
   }
+  /** pgvector cosine ANN search (HNSW when index is present). */
   async searchVectors(embedding, topK) {
     this.requireVectorReady();
     if (this.hasPgvector) {
@@ -4877,6 +5124,7 @@ var PostgresStorageProvider = class _PostgresStorageProvider {
     scored.sort((a, b) => a.distance - b.distance);
     return scored.slice(0, topK);
   }
+  /** ANN search joined with memory rows and org/archived post-filters. */
   async searchVectorsWithMemories(embedding, topK, organization, options) {
     this.requireVectorReady();
     if (!this.hasPgvector) {
@@ -4941,6 +5189,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) {
@@ -4983,6 +5232,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`,
@@ -4990,6 +5240,7 @@ var PostgresStorageProvider = class _PostgresStorageProvider {
     );
     return (result.rowCount ?? 0) > 0;
   }
+  /** Hard-delete memories matching org / agent / metadata filters. */
   async deleteMemoriesByFilter(filter) {
     if (!filter.agent) {
       throw new DatabaseError("deleteMemoriesByFilter requires an agent filter");
@@ -5000,6 +5251,7 @@ var PostgresStorageProvider = class _PostgresStorageProvider {
     );
     return result.rowCount ?? 0;
   }
+  /** Remove all memories for an organization. */
   async clearOrganization(organization) {
     const result = await this.query(
       `DELETE FROM memories WHERE organization = $1`,
@@ -5007,6 +5259,7 @@ var PostgresStorageProvider = class _PostgresStorageProvider {
     );
     return result.rowCount ?? 0;
   }
+  /** List audit history events for a memory id. */
   async getHistory(memoryId) {
     const result = await this.query(
       `SELECT id, memory_id, event_type, related_memory_id, created_at
@@ -5021,6 +5274,7 @@ var PostgresStorageProvider = class _PostgresStorageProvider {
       created_at: String(row.created_at)
     }));
   }
+  /** Append a history row (created / archived / compressed / updated). */
   async insertHistoryEvent(event) {
     await this.query(
       `INSERT INTO memory_history (id, memory_id, event_type, related_memory_id, created_at)
@@ -5034,6 +5288,7 @@ var PostgresStorageProvider = class _PostgresStorageProvider {
       ]
     );
   }
+  /** Aggregate memory counts for an organization. */
   async getStats(organization) {
     const result = await this.query(
       `SELECT
@@ -5051,6 +5306,7 @@ var PostgresStorageProvider = class _PostgresStorageProvider {
       totalAgents: Number(result.rows[0]?.agents ?? 0)
     };
   }
+  /** Approximate on-disk database size in bytes (`pg_database_size`). */
   async getDatabaseSizeBytes() {
     const result = await this.query(
       `SELECT pg_database_size(current_database())::bigint AS size`
@@ -5398,7 +5654,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;
@@ -5867,6 +6123,9 @@ var SqliteGraphProvider = class {
   concurrency;
   db = null;
   opened = false;
+  /**
+   * @param options - Graph SQLite path and optional concurrency tuning.
+   */
   constructor(options) {
     if (!options?.path || typeof options.path !== "string" || !options.path.trim()) {
       throw new ConfigurationError("sqlite graph requires a non-empty path");
@@ -5874,12 +6133,15 @@ var SqliteGraphProvider = class {
     this.dbPath = path7__default.default.resolve(options.path.trim());
     this.concurrency = resolveConcurrencyConfig(options.concurrency);
   }
+  /** Whether this provider supports file snapshots for checkpoint / export. */
   supportsFileSnapshot() {
     return this.dbPath !== ":memory:";
   }
+  /** Absolute graph database path, or `null` for `:memory:`. */
   getDataPath() {
     return this.dbPath === ":memory:" ? null : this.dbPath;
   }
+  /** Open the graph SQLite file, apply pragmas, and create schema if needed. */
   async open() {
     if (this.opened) return;
     try {
@@ -5916,6 +6178,7 @@ var SqliteGraphProvider = class {
       );
     }
   }
+  /** Close the graph database connection. */
   async close() {
     if (!this.db) {
       this.opened = false;
@@ -5937,6 +6200,14 @@ var SqliteGraphProvider = class {
       this.opened = false;
     }
   }
+  /**
+   * Create or replace a directed memory↔memory edge.
+   *
+   * @param fromId - Source memory UUID.
+   * @param toId - Target memory UUID.
+   * @param relation - Edge label (e.g. `"related_to"`, `"caused_by"`).
+   * @param metadata - Optional JSON metadata stored on the edge.
+   */
   async linkMemories(fromId, toId, relation, metadata) {
     const db = this.requireDb();
     await this.withTx(() => {
@@ -5959,6 +6230,13 @@ var SqliteGraphProvider = class {
       );
     });
   }
+  /**
+   * Remove edges between two memories.
+   *
+   * @param fromId - Source memory UUID.
+   * @param toId - Target memory UUID.
+   * @param relation - When set, only delete edges with this relation label.
+   */
   async unlinkMemories(fromId, toId, relation) {
     const db = this.requireDb();
     await this.withTx(() => {
@@ -6008,6 +6286,12 @@ var SqliteGraphProvider = class {
     }
     return out;
   }
+  /**
+   * Insert or update a named entity node.
+   *
+   * @param entity - Entity name, type, and optional metadata.
+   * @returns Stable entity id ({@link entityIdFrom}).
+   */
   async upsertEntity(entity) {
     const id = entityIdFrom(entity.name, entity.type);
     const db = this.requireDb();
@@ -6032,6 +6316,13 @@ var SqliteGraphProvider = class {
     });
     return id;
   }
+  /**
+   * Link an entity to a memory via a `MENTIONS` edge (not traversed by {@link getRelated}).
+   *
+   * @param entityId - Entity id from {@link upsertEntity}.
+   * @param memoryId - Target memory UUID.
+   * @param role - Optional role string stored on the edge metadata.
+   */
   async linkEntityToMemory(entityId, memoryId, role) {
     const db = this.requireDb();
     await this.withTx(() => {
@@ -6061,6 +6352,11 @@ var SqliteGraphProvider = class {
       );
     });
   }
+  /**
+   * Remove the memory node and incident edges when a memory is hard-deleted.
+   *
+   * @param memoryId - Wolbarg memory UUID.
+   */
   async deleteMemory(memoryId) {
     const db = this.requireDb();
     await this.withTx(() => {
@@ -6080,6 +6376,7 @@ var SqliteGraphProvider = class {
       }
     );
   }
+  /** Lightweight connectivity and schema statistics check. */
   async health() {
     try {
       if (!this.opened || !this.db) {
@@ -6225,6 +6522,9 @@ var Neo4jGraphProvider = class {
   database;
   driver = null;
   opened = false;
+  /**
+   * @param options - Bolt URL, credentials, and optional database name.
+   */
   constructor(options) {
     if (!options?.url?.trim()) {
       throw new ConfigurationError("neo4j graph requires a non-empty url");
@@ -6240,12 +6540,15 @@ var Neo4jGraphProvider = class {
     this.password = options.password;
     this.database = options.database?.trim() || void 0;
   }
+  /** Neo4j does not support local file snapshots for checkpoint pairing. */
   supportsFileSnapshot() {
     return false;
   }
+  /** Always `null` — graph data lives in the remote Neo4j cluster. */
   getDataPath() {
     return null;
   }
+  /** Connect to Neo4j, verify connectivity, and ensure uniqueness constraints. */
   async open() {
     if (this.opened) return;
     let mod;
@@ -6277,6 +6580,7 @@ var Neo4jGraphProvider = class {
       }
     });
   }
+  /** Close the neo4j-driver connection. */
   async close() {
     if (this.driver) {
       await this.driver.close();
@@ -6338,6 +6642,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);
@@ -6356,6 +6668,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(
@@ -6401,6 +6720,12 @@ var Neo4jGraphProvider = class {
       (row) => rowToMemoryRecord(unwrapRow(row))
     );
   }
+  /**
+   * MERGE an `Entity` node keyed by deterministic id.
+   *
+   * @param entity - Entity name, type, and optional metadata.
+   * @returns Stable entity id ({@link entityIdFrom}).
+   */
   async upsertEntity(entity) {
     const id = entityIdFrom(entity.name, entity.type);
     await this.run(
@@ -6415,6 +6740,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);
@@ -6437,6 +6769,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 })
@@ -6444,9 +6781,17 @@ var Neo4jGraphProvider = class {
       { id: memoryId }
     );
   }
+  /**
+   * Run arbitrary parameterized Cypher (escape hatch for advanced graph queries).
+   *
+   * @param cypher - Cypher query string.
+   * @param params - Bound parameters for the query.
+   * @returns Raw row objects from the driver.
+   */
   async query(cypher, params) {
     return this.run(cypher, params ?? {});
   }
+  /** Verify connectivity and return server metadata when available. */
   async health() {
     try {
       if (!this.opened || !this.driver) {
@@ -6937,21 +7282,32 @@ function createChildTrace(parent) {
 // src/telemetry/emitter.ts
 var NoopTelemetryProvider = class {
   name = "noop";
+  /** @inheritdoc TelemetryProvider.open */
   async open() {
   }
+  /** @inheritdoc TelemetryProvider.close */
   async close() {
   }
+  /** @inheritdoc TelemetryProvider.emit */
   emit(_event) {
   }
+  /** @inheritdoc TelemetryProvider.flush */
   async flush() {
   }
 };
 var TelemetryEmitter = class {
+  /** Stable session id for this Wolbarg instance lifetime. */
   sessionId;
+  /** Structured logger gated by telemetry log level. */
   logger;
   provider;
   config;
   context;
+  /**
+   * @param provider - Telemetry backend, or `null` for {@link NoopTelemetryProvider}.
+   * @param config - Capture flags and log level.
+   * @param context - Default organization injected into events.
+   */
   constructor(provider, config, context = {}) {
     this.sessionId = createSessionId();
     this.provider = provider ?? new NoopTelemetryProvider();
@@ -6967,25 +7323,37 @@ var TelemetryEmitter = class {
     this.context = context;
     this.logger = new WolbargLogger(this.config.level);
   }
+  /** Whether telemetry is enabled and backed by a non-noop provider. */
   get enabled() {
     return this.config.enabled && this.provider.name !== "noop";
   }
+  /** Replace the underlying telemetry provider (e.g. after lazy init). */
   setProvider(provider) {
     this.provider = provider;
   }
+  /** Open the underlying telemetry provider when enabled. */
   async open() {
     if (!this.config.enabled) {
       return;
     }
     await this.provider.open();
   }
+  /** Flush pending events and close the telemetry provider. */
   async close() {
     await this.provider.flush();
     await this.provider.close();
   }
+  /** Flush pending telemetry events without closing the provider. */
   async flush() {
     await this.provider.flush();
   }
+  /**
+   * Begin tracing an operation.
+   *
+   * @param operation - Public telemetry operation name.
+   * @param parent - Optional parent trace for nested spans.
+   * @returns Handle — call `success()` or `failure()` when done.
+   */
   start(operation, parent) {
     const context = parent ? createChildTrace(parent) : createRootTrace(this.sessionId);
     const startedAt = performance.now();
@@ -7060,10 +7428,12 @@ var TelemetryEmitter = class {
       }
     };
   }
+  /** Emit a startup telemetry event. */
   emitStartup(provider) {
     const trace = this.start("startup");
     trace.success({ provider });
   }
+  /** Emit a shutdown telemetry event. */
   emitShutdown(provider) {
     const trace = this.start("shutdown");
     trace.success({ provider });
@@ -7129,10 +7499,15 @@ var SqliteEventDatabase = class {
   db = null;
   insertStmt = null;
   columns = /* @__PURE__ */ new Set();
+  /**
+   * @param options.url - Path to the telemetry SQLite file.
+   * @param options.readonly - Open read-only (Studio / analytics).
+   */
   constructor(options) {
     this.url = options.url;
     this.readonly = options.readonly ?? false;
   }
+  /** Open the telemetry database and run schema migrations. */
   async open() {
     try {
       const dbPath = this.resolvePath(this.url);
@@ -7187,6 +7562,7 @@ var SqliteEventDatabase = class {
       );
     }
   }
+  /** Close the telemetry database connection. */
   async close() {
     if (!this.db) return;
     try {
@@ -7197,6 +7573,7 @@ var SqliteEventDatabase = class {
       this.columns.clear();
     }
   }
+  /** Insert one normalized telemetry event row. */
   async insertEvent(input) {
     const event = normalizeEvent(input);
     const stmt = this.insertStmt;
@@ -7242,6 +7619,7 @@ var SqliteEventDatabase = class {
       );
     }
   }
+  /** Insert many events in a single transaction. */
   async insertEvents(inputs) {
     const db = this.requireDb();
     const out = [];
@@ -7260,6 +7638,7 @@ var SqliteEventDatabase = class {
       throw error;
     }
   }
+  /** Query telemetry events with filters, sort, and pagination. */
   async query(options) {
     const db = this.requireDb();
     const clauses = [];
@@ -7340,11 +7719,13 @@ var SqliteEventDatabase = class {
       offset
     };
   }
+  /** Fetch one event by primary key. */
   async getEvent(id) {
     const db = this.requireDb();
     const row = db.prepare(`SELECT * FROM telemetry_events WHERE id = ?`).get(id);
     return row ? rowToEvent(row) : null;
   }
+  /** Count events optionally filtered by time and operation. */
   async countEvents(filter) {
     const db = this.requireDb();
     const clauses = [];
@@ -7495,9 +7876,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();
@@ -7505,12 +7890,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;
@@ -7527,6 +7918,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();
@@ -7535,10 +7927,12 @@ var SqliteTelemetryProvider = class {
       }
     }
   }
+  /** Query persisted telemetry events with filters and pagination. */
   async query(options) {
     await this.open();
     return this.db.query(options);
   }
+  /** Fetch a single telemetry event by id. */
   async getEvent(id) {
     await this.open();
     return this.db.getEvent(id);
@@ -7580,16 +7974,28 @@ var SqliteCheckpointProvider = class {
   name = "sqlite";
   directory;
   ready = false;
+  /**
+   * @param options.directory - Folder for `.json` metadata and `.db` snapshot files.
+   */
   constructor(options) {
     this.directory = options?.directory ?? path7__default.default.resolve(process.cwd(), ".wolbarg", "checkpoints");
   }
+  /** Ensure the checkpoint directory exists. */
   async open() {
     fs6__default.default.mkdirSync(this.directory, { recursive: true });
     this.ready = true;
   }
+  /** Mark the provider closed (does not delete snapshots). */
   async close() {
     this.ready = false;
   }
+  /**
+   * Create an immutable SQLite backup of `sourcePath` under a unique name.
+   *
+   * @param name - Checkpoint label (must not already exist).
+   * @param sourcePath - Live memory database path to snapshot.
+   * @param options.description - Optional human-readable description stored in metadata.
+   */
   async checkpoint(name, sourcePath, options) {
     this.requireReady();
     assertCheckpointName(name);
@@ -7644,6 +8050,12 @@ Ensure Wolbarg has been initialized and the database path is correct.`
     fs6__default.default.renameSync(tmpMetaPath, metaPath);
     return meta2;
   }
+  /**
+   * Restore a named checkpoint over `targetPath` (replaces WAL/SHM side files).
+   *
+   * @param name - Existing checkpoint name.
+   * @param targetPath - Live memory database path to overwrite.
+   */
   async rollback(name, targetPath) {
     this.requireReady();
     const meta2 = await this.getCheckpoint(name);
@@ -7666,6 +8078,7 @@ Ensure Wolbarg has been initialized and the database path is correct.`
     await safeSqliteBackup(meta2.snapshotPath, resolvedTarget);
     return meta2;
   }
+  /** Delete checkpoint metadata and snapshot files for `name`. */
   async deleteCheckpoint(name) {
     this.requireReady();
     const metaPath = this.metaPath(name);
@@ -7681,6 +8094,7 @@ Ensure Wolbarg has been initialized and the database path is correct.`
     }
     return removed;
   }
+  /** List all checkpoints sorted by creation time. */
   async listCheckpoints() {
     this.requireReady();
     if (!fs6__default.default.existsSync(this.directory)) {
@@ -7697,6 +8111,7 @@ Ensure Wolbarg has been initialized and the database path is correct.`
     }
     return out.sort((a, b) => a.createdAt.localeCompare(b.createdAt));
   }
+  /** Load checkpoint metadata by name, or `null` if missing / corrupt. */
   async getCheckpoint(name) {
     this.requireReady();
     const metaPath = this.metaPath(name);
@@ -7881,6 +8296,13 @@ var SqliteSubscribeEmitter = class {
       }
     });
   }
+  /**
+   * Register a filtered callback for in-process memory change events.
+   *
+   * @param filter - Organization / agent / event-type filter.
+   * @param callback - Invoked synchronously on each matching emit.
+   * @returns Unsubscribe function.
+   */
   subscribe(filter, callback) {
     if (this.closed) {
       throw new Error("Subscribe backend is closed");
@@ -7891,12 +8313,14 @@ var SqliteSubscribeEmitter = class {
       this.subscriptions.delete(id);
     };
   }
+  /** Emit a memory change event to registered subscribers. */
   emit(event) {
     if (this.closed) {
       return;
     }
     this.emitter.emit("change", event);
   }
+  /** Remove all listeners and mark the emitter closed. */
   async close() {
     this.closed = true;
     this.subscriptions.clear();
@@ -7934,6 +8358,20 @@ var Wolbarg = class {
   memoryDedupe = resolveMemoryDedupeConfig();
   embeddingCacheConfig = resolveEmbeddingCacheConfig();
   rawEmbedding = null;
+  /**
+   * @param options - Full {@link WolbargOptions}. Key fields:
+   * - `organization` — namespace isolating memories in a shared DB
+   * - `database` / `storage` — SQLite/Postgres config **or** a custom
+   *   {@link StorageProvider} instance
+   * - `embedding` — {@link EmbeddingProvider} instance **or**
+   *   {@link EmbeddingConfig} / {@link openaiEmbedding} (etc.)
+   * - `llm` — optional {@link LlmProvider} or {@link LlmConfig} / {@link openaiLlm};
+   *   required for {@link Wolbarg.compress} and extract-mode
+   *   {@link Wolbarg.rememberFromMessages}
+   * - `graph`, `telemetry`, `reranker`, `keywordSearch`, `ocr`, `vision`,
+   *   `compression`, `chunking`, `retrieval`, `concurrency`, `embeddingCache`,
+   *   `memory.dedupe` — optional plugins / tuning
+   */
   constructor(options) {
     this.telemetry = new TelemetryEmitter(null, { enabled: false, level: "off" });
     if (!options) {
@@ -7992,6 +8430,12 @@ var Wolbarg = class {
   }
   /**
    * Backwards-compatible initialization (v0.1 API).
+   * Prefer constructing with options + {@link Wolbarg.ready} instead.
+   *
+   * @param options - Organization, database, embedding, and optional LLM config.
+   * @returns Resolves when storage is open and the vector schema is ready.
+   * @throws {InitializationError} If already initialized.
+   * @throws {ConfigurationError} | {ValidationError} On invalid options.
    */
   async init(options) {
     if (this.initialized || this.storage) {
@@ -8023,7 +8467,14 @@ var Wolbarg = class {
     }
     await this.ready();
   }
-  /** Ensure storage (and optional telemetry) are open. */
+  /**
+   * Open storage, optional telemetry / checkpoint / graph providers, wrap the
+   * embedding cache, and probe embedding dimensions. Safe to call multiple times;
+   * concurrent callers share one boot promise.
+   *
+   * @returns Resolves when the instance is ready for remember/recall.
+   * @throws {InitializationError} If neither constructor options nor {@link init} were used.
+   */
   async ready() {
     if (this.initialized) {
       return;
@@ -8039,6 +8490,7 @@ var Wolbarg = class {
       this.booting = null;
     }
   }
+  /** Internal boot sequence invoked by {@link Wolbarg.ready}. */
   async boot() {
     if (!this.storage || !this.embedding || !this.organization) {
       throw new InitializationError(
@@ -8114,7 +8566,17 @@ var Wolbarg = class {
       );
     }
   }
-  /** Store a semantic memory for an agent (may upsert when dedupe is enabled). */
+  /**
+   * Store a semantic memory for an agent. Embeds `content.text`, writes the row,
+   * and may **upsert** an existing active memory when dedupe is enabled
+   * (constructor `memory.dedupe` or per-call `options.dedupe`).
+   *
+   * @param options - Agent id, text content, optional metadata / dedupe overrides.
+   *   See {@link RememberOptions}.
+   * @returns The stored record plus `action` (`"created"` | `"updated"`).
+   * @throws {ValidationError} On empty agent/content.
+   * @throws {InitializationError} If not configured / ready.
+   */
   async remember(options) {
     const trace = this.telemetry.start("remember");
     try {
@@ -8136,7 +8598,15 @@ var Wolbarg = class {
       throw wrapOperationError("remember", error);
     }
   }
-  /** Batch remember — sequential when dedupe enabled; otherwise one TX batch. */
+  /**
+   * Remember many memories in one call. Runs sequentially when any item (or the
+   * global config) enables dedupe; otherwise embeds in batch and inserts in one
+   * transaction for throughput.
+   *
+   * @param items - Non-empty list of {@link RememberOptions}.
+   * @returns One {@link RememberResult} per input, same order.
+   * @throws {ValidationError} If `items` is empty or an entry is invalid.
+   */
   async rememberBatch(items) {
     const parent = this.telemetry.start("rememberBatch");
     try {
@@ -8262,7 +8732,15 @@ var Wolbarg = class {
    * **Experimental** until 1.0 — API shape may change.
    *
    * - `mode: "raw"` (default) — remember user message text (no LLM).
-   * - `mode: "extract"` — require configured `llm`; extract atomic facts then remember each.
+   * - `mode: "extract"` — requires configured `llm`; extracts atomic facts then
+   *   remembers each. Pass a custom {@link LlmProvider} or {@link openaiLlm}
+   *   in the constructor.
+   *
+   * @param messages - Conversation turns (`role` + `content`).
+   * @param options - Agent, mode, optional metadata/dedupe. See
+   *   {@link RememberFromMessagesOptions}.
+   * @returns One {@link RememberResult} per remembered fact/message.
+   * @throws {ProviderNotConfiguredError} When `mode: "extract"` but no `llm` was configured.
    */
   async rememberFromMessages(messages, options) {
     const parent = this.telemetry.start("rememberFromMessages");
@@ -8332,7 +8810,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");
@@ -8402,10 +8887,18 @@ var Wolbarg = class {
     }
   }
   /**
-   * Subscribe to memory change events.
+   * Subscribe to memory change events (remember / update / forget / compress / clear).
    *
    * **SQLite:** delivers events only within this Node.js process.
    * A second process writing the same `memory.db` will not notify subscribers here.
+   *
+   * **Postgres:** uses LISTEN/NOTIFY across processes (lazy connection on first subscribe).
+   *
+   * @param filter - Scope by `organization` (defaults to this instance’s org),
+   *   optional `agent`, and optional `events` allow-list. See {@link SubscribeFilter}.
+   * @param callback - Invoked with each {@link MemoryChangeEvent}.
+   * @returns {@link Unsubscribe} function — call to stop receiving events.
+   * @throws {ValidationError} If organization cannot be resolved.
    */
   subscribe(filter, callback) {
     const org = filter.organization || this.organization;
@@ -8434,6 +8927,7 @@ var Wolbarg = class {
     }
     return this.subscribeBackend.subscribe(normalized, callback);
   }
+  /** Broadcast a memory change event to in-process or Postgres NOTIFY subscribers. */
   emitChange(event) {
     try {
       if (this.storage instanceof PostgresStorageProvider) {
@@ -8659,6 +9153,17 @@ var Wolbarg = class {
       throw error;
     }
   }
+  /**
+   * Find the best active near-duplicate memory for upsert (cosine similarity ≥ threshold).
+   *
+   * @param storage - Open storage provider.
+   * @param organization - Org namespace.
+   * @param agent - Agent scope for the search.
+   * @param vector - Embedding of the candidate text.
+   * @param threshold - Minimum similarity (0–1) to treat as a duplicate.
+   * @param limit - Max vector candidates to inspect.
+   * @returns Matching memory row, or `null` if none qualify.
+   */
   async findNearDuplicate(storage, organization, agent, vector, threshold, limit) {
     if (typeof storage.searchVectorsWithMemories === "function") {
       const hits2 = await storage.searchVectorsWithMemories(
@@ -8996,7 +9501,13 @@ var Wolbarg = class {
       throw wrapOperationError("recall", error);
     }
   }
-  /** Batch recall — parent event + child traces. */
+  /**
+   * Run multiple recalls sequentially under one parent telemetry span.
+   *
+   * @param queries - Non-empty list of recall options (`explain` is forced off).
+   * @returns One hit array per query, same order.
+   * @throws {ValidationError} If `queries` is empty.
+   */
   async recallBatch(queries) {
     const parent = this.telemetry.start("recallBatch");
     try {
@@ -9030,10 +9541,21 @@ var Wolbarg = class {
       throw wrapOperationError("recallBatch", error);
     }
   }
+  /**
+   * Compress the newest active memories for an agent into one summary memory
+   * and archive the sources. Requires an `llm` (or custom `compression`) at
+   * construction — typed only on `Wolbarg<true>`.
+   *
+   * @param options - `agent` required; optional `limit` (default 50, min 2).
+   *   See {@link CompressOptions}.
+   * @returns Summary record plus archived source ids. See {@link CompressResult}.
+   * @throws {ProviderNotConfiguredError} If no LLM/compression provider is set.
+   * @throws {ValidationError} If fewer than 2 active memories exist for the agent.
+   */
   async compress(options) {
     return this.runCompress(options);
   }
-  /** @internal */
+  /** @internal Runs compress for both typed and untyped call sites. */
   async runCompress(options) {
     const trace = this.telemetry.start("compress");
     try {
@@ -9122,6 +9644,16 @@ var Wolbarg = class {
       throw wrapOperationError("compress", error);
     }
   }
+  /**
+   * Ingest a document (path, URL, Buffer, or text), chunk it, embed chunks, and
+   * store each as a memory. Images use optional `ocr` / `vision` providers from
+   * the constructor.
+   *
+   * @param options - `agent`, `source`, optional chunking overrides / metadata.
+   *   See {@link IngestOptions}.
+   * @returns Counts and created memory ids. See {@link IngestResult}.
+   * @throws {ValidationError} If no text can be extracted or chunking yields zero chunks.
+   */
   async ingest(options) {
     const trace = this.telemetry.start("ingest");
     try {
@@ -9292,8 +9824,14 @@ var Wolbarg = class {
     }
   }
   /**
-   * Link two memories in the optional graph layer.
-   * Throws {@link ProviderNotConfiguredError} when no graph provider is set.
+   * Link two memories in the optional graph layer with a typed relation edge.
+   *
+   * @param fromId - Source memory id.
+   * @param toId - Target memory id.
+   * @param relation - Edge label (e.g. `"supports"`, `"caused_by"`).
+   * @param metadata - Optional edge properties stored on the graph provider.
+   * @throws {ProviderNotConfiguredError} When no `graph` was configured.
+   * @throws {ValidationError} On empty ids/relation.
    */
   async linkMemories(fromId, toId, relation, metadata) {
     const trace = this.telemetry.start("linkMemories");
@@ -9323,8 +9861,13 @@ var Wolbarg = class {
   }
   /**
    * Traverse related memories via the optional graph layer.
-   * Throws {@link ProviderNotConfiguredError} when no graph provider is set.
-   * Results are re-hydrated from SQL storage when available.
+   * Neighbor stubs from the graph are re-hydrated from SQL storage when available.
+   *
+   * @param memoryId - Seed memory id.
+   * @param options - Optional `relation`, `direction`, `depth`, `limit`.
+   *   See {@link GetRelatedOptions}.
+   * @returns Related {@link MemoryRecord} list (may be empty).
+   * @throws {ProviderNotConfiguredError} When no `graph` was configured.
    */
   async getRelated(memoryId, options) {
     const trace = this.telemetry.start("getRelated");
@@ -9361,6 +9904,14 @@ var Wolbarg = class {
       throw wrapOperationError("getRelated", error);
     }
   }
+  /**
+   * Delete memories by id or by agent filter. Cascades graph nodes/edges when
+   * a graph provider is configured.
+   *
+   * @param options - Either `{ id }` or `{ filter: { agent } }`. See {@link ForgetOptions}.
+   * @returns Number of memories deleted.
+   * @throws {ValidationError} If neither `id` nor `filter.agent` is provided.
+   */
   async forget(options) {
     const trace = this.telemetry.start("forget");
     try {
@@ -9425,6 +9976,13 @@ var Wolbarg = class {
       throw wrapOperationError("forget", error);
     }
   }
+  /**
+   * Return the audit/history timeline for a single memory.
+   *
+   * @param options - `{ id }` of the memory. See {@link HistoryOptions}.
+   * @returns Memory record plus ordered {@link HistoryEvent} list.
+   * @throws {MemoryNotFoundError} If the id is unknown.
+   */
   async history(options) {
     const trace = this.telemetry.start("history");
     try {
@@ -9452,6 +10010,11 @@ var Wolbarg = class {
       throw wrapOperationError("history", error);
     }
   }
+  /**
+   * Aggregate counts for this organization (active / archived / agents / etc.).
+   *
+   * @returns {@link StatsResult} snapshot.
+   */
   async stats() {
     const trace = this.telemetry.start("stats");
     try {
@@ -9479,6 +10042,13 @@ var Wolbarg = class {
       throw wrapOperationError("stats", error);
     }
   }
+  /**
+   * Delete all memories for this organization (optionally scoped by agent).
+   * Cascades graph cleanup when a graph provider is configured.
+   *
+   * @param options - Optional `{ agent }` scope. See {@link ClearOptions}.
+   * @returns Number of memories deleted.
+   */
   async clear(options) {
     const trace = this.telemetry.start("clear");
     try {
@@ -9507,7 +10077,16 @@ var Wolbarg = class {
       throw wrapOperationError("clear", error);
     }
   }
-  /** Create an immutable named checkpoint of the memory database. */
+  /**
+   * Create an immutable named checkpoint of the file-backed SQLite memory DB
+   * (and SQLite graph snapshot when applicable).
+   *
+   * @param name - Checkpoint name (unique).
+   * @param options - Optional metadata. See {@link CheckpointOptions}.
+   * @returns {@link CheckpointInfo} for the new checkpoint.
+   * @throws {ProviderNotConfiguredError} Without a checkpoint provider / file DB.
+   * @throws {GraphCheckpointNotSupportedError} For Neo4j graph backends.
+   */
   async checkpoint(name, options) {
     const trace = this.telemetry.start("checkpoint");
     try {
@@ -9538,7 +10117,12 @@ var Wolbarg = class {
       throw wrapOperationError("checkpoint", error);
     }
   }
-  /** Restore the memory database from a named checkpoint. */
+  /**
+   * Restore the memory database from a named checkpoint (replaces the live DB file).
+   *
+   * @param name - Checkpoint name previously created with {@link Wolbarg.checkpoint}.
+   * @returns {@link CheckpointInfo} of the restored checkpoint.
+   */
   async rollback(name) {
     const trace = this.telemetry.start("rollback");
     let storageClosed = false;
@@ -9584,6 +10168,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 {
@@ -9610,6 +10200,11 @@ var Wolbarg = class {
       throw wrapOperationError("deleteCheckpoint", error);
     }
   }
+  /**
+   * List all known checkpoints for this instance.
+   *
+   * @returns Array of {@link CheckpointInfo} (may be empty).
+   */
   async listCheckpoints() {
     const trace = this.telemetry.start("listCheckpoints");
     try {
@@ -9628,6 +10223,12 @@ var Wolbarg = class {
       throw wrapOperationError("listCheckpoints", error);
     }
   }
+  /**
+   * Look up a single checkpoint by name.
+   *
+   * @param name - Checkpoint name.
+   * @returns {@link CheckpointInfo} or `null` if missing.
+   */
   async getCheckpoint(name) {
     const trace = this.telemetry.start("getCheckpoint");
     try {
@@ -9647,7 +10248,13 @@ var Wolbarg = class {
       throw wrapOperationError("getCheckpoint", error);
     }
   }
-  /** Export the memory database to a portable SQLite + manifest bundle. */
+  /**
+   * Export the memory database to a portable SQLite + manifest bundle
+   * (includes SQLite graph sidecar when applicable).
+   *
+   * @param exportPath - Destination file path for the export bundle.
+   * @returns {@link ExportResult} with path, size, and timestamp.
+   */
   async export(exportPath) {
     const trace = this.telemetry.start("export");
     try {
@@ -9678,7 +10285,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;
@@ -9728,11 +10341,17 @@ var Wolbarg = class {
       throw wrapOperationError("import", error);
     }
   }
-  /** Flush pending telemetry (useful in tests). */
+  /**
+   * Flush pending telemetry writes (useful in tests / before process exit).
+   *
+   * @returns Resolves when the telemetry provider has flushed.
+   */
   async flushTelemetry() {
     await this.telemetry.flush();
   }
-  /** Session id for this SDK instance (telemetry traces). */
+  /**
+   * Session id for this SDK instance (attached to telemetry traces and change events).
+   */
   get sessionId() {
     return this.telemetry.sessionId;
   }
@@ -9747,6 +10366,12 @@ var Wolbarg = class {
     }
     return fn();
   }
+  /**
+   * Close storage, graph, telemetry, checkpoints, and subscribe backends.
+   * The instance can be discarded afterward; construct a new one to reopen.
+   *
+   * @returns Resolves when all providers have closed (errors are swallowed per-provider).
+   */
   async close() {
     if (this.storage) {
       this.telemetry.emitShutdown(this.storage.name);
@@ -9771,9 +10396,11 @@ var Wolbarg = class {
     this.embeddingDimensions = null;
     this.initialized = false;
   }
+  /** Whether {@link Wolbarg.ready} / {@link Wolbarg.init} has completed successfully. */
   get isInitialized() {
     return this.initialized;
   }
+  /** Ensure {@link Wolbarg.ready} completed and core providers are available. */
   async requireReady() {
     await this.ready();
     if (!this.initialized || !this.storage || !this.embedding || !this.organization) {
@@ -9787,6 +10414,7 @@ var Wolbarg = class {
       organization: this.organization
     };
   }
+  /** Reject embeddings whose dimensionality differs from the initialized model. */
   assertEmbeddingDimensions(dimensions) {
     if (this.embeddingDimensions !== null && dimensions !== this.embeddingDimensions) {
       throw new ValidationError(
@@ -9794,6 +10422,7 @@ var Wolbarg = class {
       );
     }
   }
+  /** Return the configured checkpoint provider or throw {@link ProviderNotConfiguredError}. */
   requireCheckpointProvider() {
     if (!this.checkpointProvider) {
       throw new ProviderNotConfiguredError(
@@ -9804,6 +10433,7 @@ var Wolbarg = class {
     }
     return this.checkpointProvider;
   }
+  /** Return the configured graph provider or throw with a setup hint for `method`. */
   requireGraph(method) {
     if (!this.graph) {
       throw new ProviderNotConfiguredError(
@@ -9814,20 +10444,24 @@ var Wolbarg = class {
     }
     return this.graph;
   }
+  /** Throw when graph checkpoint pairing is requested on a non-file-backed graph backend. */
   assertGraphCheckpointSupported(operation) {
     if (!this.graph) return;
     if (!this.graph.supportsFileSnapshot()) {
       throw new GraphCheckpointNotSupportedError(this.graph.name, operation);
     }
   }
+  /** Directory path where a graph file snapshot is stored alongside a memory checkpoint. */
   graphSnapshotDir(alongsidePath) {
     return `${alongsidePath}.graph`;
   }
+  /** Close the graph provider before copying files; returns whether a close occurred. */
   async closeGraphForSnapshot() {
     if (!this.graph || !this.graph.supportsFileSnapshot()) return false;
     await this.graph.close();
     return true;
   }
+  /** Copy the SQLite graph database next to a memory checkpoint directory. */
   async snapshotGraphAlongside(alongsidePath, operation) {
     if (!this.graph) return;
     if (!this.graph.supportsFileSnapshot()) {
@@ -9866,6 +10500,7 @@ var Wolbarg = class {
       await this.graph.open();
     }
   }
+  /** Restore a graph file snapshot written by {@link snapshotGraphAlongside}. */
   async restoreGraphAlongside(alongsidePath, operation) {
     if (!this.graph) return;
     if (!this.graph.supportsFileSnapshot()) {
@@ -9889,6 +10524,7 @@ var Wolbarg = class {
       fs6__default.default.cpSync(src, dataPath, { recursive: true });
     }
   }
+  /** Run graph traversal then re-hydrate stub records from storage when rows exist. */
   async hydrateRelated(memoryId, options) {
     const graph = this.requireGraph("getRelated");
     const related = await graph.getRelated(memoryId, options);
@@ -9904,6 +10540,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(
@@ -9955,6 +10592,7 @@ function commonTags(metadata) {
 
 // src/filters/types.ts
 var meta = {
+  /** Field equals value (strict equality). */
   eq: (field, value) => ({
     field,
     op: { eq: value }
@@ -10038,16 +10676,23 @@ function createTelemetryProvider(config) {
 function wolbarg2(options) {
   return new Wolbarg(options);
 }
+var createWolbarg = wolbarg2;
 
 // src/keyword/index.ts
 var Bm25KeywordSearchProvider = class {
   name = "bm25";
   k1;
   b;
+  /**
+   * @param options - BM25 tuning parameters.
+   * @param options.k1 - Term frequency saturation (default `1.2`).
+   * @param options.b - Length normalization (default `0.75`).
+   */
   constructor(options) {
     this.k1 = options?.k1 ?? 1.2;
     this.b = options?.b ?? 0.75;
   }
+  /** @inheritdoc */
   async search(query, documents, topK) {
     if (documents.length === 0 || topK <= 0) {
       return [];
@@ -10500,9 +11145,279 @@ function percentile(sorted, p) {
   return sorted[idx];
 }
 
+// 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 path7.isAbsolute(rel) ? rel : path7.resolve(cwd, rel);
+}
+function resolveEnvPath(cwd = process.cwd(), envPath) {
+  const rel = envPath ?? DEFAULT_ENV_PATH;
+  return path7.isAbsolute(rel) ? rel : path7.resolve(cwd, rel);
+}
+function loadProjectConfig(cwd = process.cwd(), configPath) {
+  const full = resolveConfigPath(cwd, configPath);
+  if (!fs6.existsSync(full)) return null;
+  const raw = JSON.parse(fs6.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 = path7.dirname(configPath);
+  if (!fs6.existsSync(dir)) fs6.mkdirSync(dir, { recursive: true });
+  if (fs6.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 } : {}
+    }
+  };
+  fs6.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 = path7.isAbsolute(config.database.url) ? config.database.url : path7.resolve(cwd, config.database.url);
+    ensureParent(dbPath);
+  }
+  return { configPath, envPath };
+}
+function ensureParent(filePath) {
+  const dir = path7.dirname(filePath);
+  if (!fs6.existsSync(dir)) fs6.mkdirSync(dir, { recursive: true });
+}
+function upsertEnvVar(envPath, key, value) {
+  ensureParent(envPath);
+  let text = fs6.existsSync(envPath) ? fs6.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}
+`;
+  }
+  fs6.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 = path7.join(cwd, ".gitignore");
+  let text = fs6.existsSync(gi) ? fs6.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) fs6.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 (!fs6.existsSync(envPath)) return out;
+  const text = fs6.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("://") && !path7.isAbsolute(config.database.url)) {
+    config.database = {
+      ...config.database,
+      url: path7.resolve(cwd, config.database.url)
+    };
+  }
+  return wolbarg(projectConfigToWolbargOptions(config, env));
+}
+
 exports.CompressionError = CompressionError;
 exports.ConfigurationError = ConfigurationError;
+exports.DEFAULT_CONFIG_PATH = DEFAULT_CONFIG_PATH;
+exports.DEFAULT_ENV_PATH = DEFAULT_ENV_PATH;
+exports.DEFAULT_ORGANIZATION = DEFAULT_ORGANIZATION;
+exports.DEFAULT_SQLITE_DB_PATH = DEFAULT_SQLITE_DB_PATH;
 exports.DatabaseError = DatabaseError;
+exports.EMBEDDING_PROVIDER_PRESETS = EMBEDDING_PROVIDER_PRESETS;
 exports.EmbeddingError = EmbeddingError;
 exports.FixedChunkingStrategy = FixedChunkingStrategy;
 exports.GraphCheckpointNotSupportedError = GraphCheckpointNotSupportedError;
@@ -10530,6 +11445,8 @@ exports.ValidationError = ValidationError;
 exports.Wolbarg = Wolbarg;
 exports.WolbargError = WolbargError;
 exports.WolbargLogger = WolbargLogger;
+exports.applyEnvFile = applyEnvFile;
+exports.assertEmbeddingPreset = assertEmbeddingPreset;
 exports.bgeReranker = bgeReranker;
 exports.bm25 = bm25;
 exports.cohereReranker = cohereReranker;
@@ -10540,12 +11457,16 @@ exports.createEmbeddingProvider = createEmbeddingProvider;
 exports.createLlmProvider = createLlmProvider;
 exports.createStorageProvider = createStorageProvider;
 exports.createTelemetryProvider = createTelemetryProvider;
-exports.createWolbarg = wolbarg2;
+exports.createWolbarg = createWolbarg;
+exports.createWolbargFromProjectConfig = createWolbargFromProjectConfig;
 exports.crossEncoder = crossEncoder;
+exports.defaultProjectConfig = defaultProjectConfig;
 exports.geminiEmbedding = geminiEmbedding;
 exports.geminiVision = geminiVision;
+exports.getEmbeddingProviderPreset = getEmbeddingProviderPreset;
 exports.jinaReranker = jinaReranker;
 exports.lmStudioEmbedding = lmStudioEmbedding;
+exports.loadProjectConfig = loadProjectConfig;
 exports.meta = meta;
 exports.neo4jGraph = neo4jGraph;
 exports.ollamaEmbedding = ollamaEmbedding;
@@ -10560,7 +11481,12 @@ exports.openaiReranker = openaiReranker;
 exports.openaiVision = openaiVision;
 exports.postgres = postgres;
 exports.postgresConfig = postgresConfig;
+exports.projectConfigToWolbargOptions = projectConfigToWolbargOptions;
+exports.resolveConfigPath = resolveConfigPath;
+exports.resolveEmbeddingApiKey = resolveEmbeddingApiKey;
+exports.resolveEnvPath = resolveEnvPath;
 exports.runBenchmark = runBenchmark;
+exports.saveProjectConfig = saveProjectConfig;
 exports.sqlite = sqlite;
 exports.sqliteCheckpoint = sqliteCheckpoint;
 exports.sqliteConfig = sqliteConfig;
@@ -10569,6 +11495,7 @@ exports.sqliteTelemetry = sqliteTelemetry;
 exports.summarizeBenchmark = summarizeBenchmark;
 exports.tesseract = tesseract;
 exports.togetherEmbedding = togetherEmbedding;
+exports.upsertEnvVar = upsertEnvVar;
 exports.vllmEmbedding = vllmEmbedding;
 exports.wolbarg = wolbarg;
 exports.wrapOperationError = wrapOperationError;