wolbarg 0.5.3 → 0.5.5

package/dist/index.d.cts

@@ -2,6 +2,19 @@ import { DatabaseSync } from 'node:sqlite';
 
 /**
  * Metadata filter AST for advanced recall filtering.
+ *
+ * Build filters with the {@link meta} helper or compose `{ field, op }` nodes directly.
+ * Filters compile to SQL JSON predicates when possible ({@link compileMetadataFilterToSql}).
+ *
+ * @example
+ * ```ts
+ * import { meta } from "wolbarg/filters";
+ *
+ * const filter = meta.and(
+ *   meta.eq("category", "billing"),
+ *   meta.gte("priority", 2),
+ * );
+ * ```
  */
 /** Comparison operators on a single metadata field. */
 type MetadataComparison = {
@@ -30,8 +43,9 @@ type MetadataFilter = {
 } | {
     not: MetadataFilter;
 };
-/** Helpers for building filters fluently. */
+/** Fluent builders for {@link MetadataFilter} AST nodes. */
 declare const meta: {
+    /** Field equals value (strict equality). */
     eq: (field: string, value: unknown) => MetadataFilter;
     contains: (field: string, value: string) => MetadataFilter;
     gt: (field: string, value: number | string) => MetadataFilter;
@@ -49,8 +63,10 @@ declare const meta: {
  * Schema is intentionally extensible for future providers (Postgres, cloud).
  */
 /** Public operation names recorded as telemetry events. */
-type TelemetryOperation = "remember" | "recall" | "forget" | "compress" | "rememberBatch" | "recallBatch" | "export" | "import" | "checkpoint" | "rollback" | "error" | "startup" | "shutdown" | "ingest" | "history" | "stats" | "clear" | "deleteCheckpoint" | "listCheckpoints" | "getCheckpoint" | "linkMemories" | "getRelated" | "graphQuery" | "rememberFromMessages";
+type TelemetryOperation = "remember" | "update" | "recall" | "forget" | "compress" | "rememberBatch" | "recallBatch" | "export" | "import" | "checkpoint" | "rollback" | "error" | "startup" | "shutdown" | "ingest" | "history" | "stats" | "clear" | "deleteCheckpoint" | "listCheckpoints" | "getCheckpoint" | "linkMemories" | "getRelated" | "graphQuery" | "rememberFromMessages";
+/** Outcome recorded on each telemetry event. */
 type TelemetryStatus = "ok" | "error" | "cancelled";
+/** Minimum log level for {@link WolbargLogger} and telemetry console output. */
 type TelemetryLogLevel = "off" | "error" | "warn" | "info" | "debug" | "trace";
 /** Stage-level latency breakdown recorded on each event. */
 interface LatencyBreakdown {
@@ -149,46 +165,78 @@ interface TelemetryEvent extends Required<Pick<TelemetryEventInput, "id" | "time
     explain: PersistedRecallExplainPayload | null;
     spans: StageSpan[] | null;
 }
+/** Filter and pagination options for querying persisted telemetry events. */
 interface TelemetryQuery {
+    /** Filter by one or more operation names. */
     operation?: TelemetryOperation | TelemetryOperation[];
+    /** Filter by completion status. */
     status?: TelemetryStatus;
+    /** Match events whose trace or parent trace equals this id. */
     traceId?: string;
+    /** Filter by Wolbarg instance session id. */
     sessionId?: string;
+    /** Filter by organization namespace. */
     organization?: string;
+    /** Filter by agent id recorded on the event. */
     agentId?: string;
+    /** Require a tag in the event's `tags` array. */
     tag?: string;
+    /** Filter by checkpoint id when the operation touched checkpoints. */
     checkpointId?: string;
+    /** Require the memory id in the event's `memoryIds` list. */
     memoryId?: string;
+    /** Case-sensitive substring match on the recorded query text. */
     queryText?: string;
+    /** ISO-8601 lower bound (inclusive). */
     since?: string;
+    /** ISO-8601 upper bound (inclusive). */
     until?: string;
+    /** Page size (default 50). */
     limit?: number;
+    /** Page offset (default 0). */
     offset?: number;
+    /** Sort column. */
     sortBy?: "timestamp" | "duration_ms";
+    /** Sort direction. */
     sortDir?: "asc" | "desc";
 }
+/** Paginated telemetry query result. */
 interface TelemetryQueryResult {
+    /** Matching events for the current page. */
     events: TelemetryEvent[];
+    /** Total rows matching filters (ignoring limit/offset). */
     total: number;
+    /** Applied page size. */
     limit: number;
+    /** Applied page offset. */
     offset: number;
 }
 /** Database config for the independent telemetry EventDatabase. */
 interface TelemetryDatabaseConfig {
+    /** Storage engine for telemetry (SQLite today; Postgres planned). */
     provider: "sqlite" | "postgres";
-    /** Preferred v0.3 field. */
+    /** Preferred v0.3 field — filesystem path or Postgres URL. */
     url?: string;
-    /** Back-compat alias for url. */
+    /** Back-compat alias for {@link TelemetryDatabaseConfig.url}. */
     connectionString?: string;
 }
+/** Wolbarg constructor `telemetry` option — independent observability database. */
 interface TelemetryConfig {
+    /** Master switch (default `true` when a provider is configured). */
     enabled?: boolean;
+    /** Separate SQLite (or future Postgres) database for event storage. */
     database: TelemetryDatabaseConfig;
+    /** Console log level for {@link WolbargLogger}. */
     level?: TelemetryLogLevel;
+    /** Persist recall/remember query strings on events. */
     captureQueries?: boolean;
+    /** Persist {@link LatencyBreakdown} and stage spans. */
     captureLatency?: boolean;
+    /** Persist error message and stack on failed operations. */
     captureErrors?: boolean;
+    /** Persist per-hit similarity scores on recall events. */
     captureSimilarity?: boolean;
+    /** Persist raw embedding vectors (off by default — large payloads). */
     captureEmbeddings?: boolean;
 }
 
@@ -282,7 +330,7 @@ interface MmrConfig {
 }
 /** Retrieval pipeline defaults applied when constructing Wolbarg. */
 interface RetrievalConfig {
-    /** Default over-fetch multiplier for candidate generation. Defaults to 4. */
+    /** Default over-fetch multiplier for candidate generation. Defaults to 2 (no filters) or 4 (with metadata filters). */
     overFetchFactor?: number;
     /** Default hybrid fusion weights. */
     hybrid?: HybridConfig;
@@ -645,19 +693,29 @@ interface IngestResult {
 /** Direction for {@link GraphProvider.getRelated}. */
 type GraphDirection = "in" | "out" | "both";
 interface GetRelatedOptions {
+    /** Relation type filter (e.g. `"follows"`, `"references"`). Omit for any relation. */
     relation?: string;
-    /** Traversal depth (default 1). */
+    /** Traversal depth from the start memory (default `1`). */
     depth?: number;
+    /** Edge direction: incoming, outgoing, or both (default `"both"`). */
     direction?: GraphDirection;
 }
+/** Input for {@link GraphProvider.upsertEntity}. */
 interface GraphEntityInput {
+    /** Human-readable entity name. */
     name: string;
+    /** Entity type label (e.g. `"person"`, `"project"`). */
     type: string;
+    /** Optional opaque metadata stored on the entity node. */
     metadata?: Record<string, unknown>;
 }
+/** Result of {@link GraphProvider.health}. */
 interface GraphHealthResult {
+    /** Whether the graph backend is reachable and schema-ready. */
     ok: boolean;
+    /** Backend identifier (e.g. `"sqlite-graph"`, `"neo4j"`). */
     backend: string;
+    /** Backend-specific details (file path, cluster info, etc.). */
     details?: unknown;
 }
 /**
@@ -671,250 +729,863 @@ interface GraphProvider {
     readonly name: string;
     /** Open connection / embedded database and ensure schema. */
     open(): Promise<void>;
-    /** Close the underlying connection. */
+    /** Close the underlying connection and release resources. */
     close(): Promise<void>;
     /**
      * Create (or ensure) a directed relation between two memory nodes.
      * Implementations create stub Memory nodes when missing.
+     *
+     * @param fromId - Source memory UUID.
+     * @param toId - Target memory UUID.
+     * @param relation - Relation type label (e.g. `"references"`).
+     * @param metadata - Optional edge properties.
      */
     linkMemories(fromId: string, toId: string, relation: string, metadata?: Record<string, unknown>): Promise<void>;
-    /** Remove relation(s) between two memory nodes. */
+    /**
+     * Remove relation(s) between two memory nodes.
+     *
+     * @param fromId - Source memory UUID.
+     * @param toId - Target memory UUID.
+     * @param relation - When set, only remove edges of this type; omit to remove all between the pair.
+     */
     unlinkMemories(fromId: string, toId: string, relation?: string): Promise<void>;
     /**
      * Traverse from a memory node and return related Memory records as stored
      * in the graph (facade may re-hydrate from SQL storage).
+     *
+     * @param memoryId - Start memory UUID.
+     * @param options - Relation filter, depth, and direction.
+     * @returns Related memories in graph-native form.
      */
     getRelated(memoryId: string, options?: GetRelatedOptions): Promise<MemoryRecord[]>;
-    /** Upsert an entity node; returns stable entity id. */
+    /**
+     * Upsert an entity node; returns stable entity id.
+     *
+     * @param entity - Entity name, type, and optional metadata.
+     * @returns Stable entity UUID for {@link linkEntityToMemory}.
+     */
     upsertEntity(entity: GraphEntityInput): Promise<string>;
-    /** Link an entity to a memory with an optional role. */
+    /**
+     * Link an entity to a memory with an optional role.
+     *
+     * @param entityId - Entity UUID from {@link upsertEntity}.
+     * @param memoryId - Memory UUID to link.
+     * @param role - Optional relationship role (e.g. `"author"`, `"subject"`).
+     */
     linkEntityToMemory(entityId: string, memoryId: string, role?: string): Promise<void>;
     /**
      * Hard-delete a memory node and all incident edges (cascade for forget/clear).
+     *
+     * @param memoryId - Memory UUID to remove from the graph.
      */
     deleteMemory(memoryId: string): Promise<void>;
     /**
      * Raw Cypher escape hatch. Supported on Neo4j only — the SQLite provider
      * throws a typed error. See module portability contract above.
+     *
+     * @param cypher - Cypher query string.
+     * @param params - Bound parameters for the query.
+     * @returns Driver-specific result rows.
      */
     query(cypher: string, params?: Record<string, unknown>): Promise<unknown>;
+    /**
+     * Lightweight connectivity / schema health check.
+     * @returns {@link GraphHealthResult} with `ok`, `backend`, and optional `details`.
+     */
     health(): Promise<GraphHealthResult>;
     /**
      * When true, checkpoint/export may snapshot {@link getDataPath}.
      * Network-backed providers (Neo4j) return false.
      */
     supportsFileSnapshot(): boolean;
-    /** Absolute path to the embedded graph data directory/file, if any. */
+    /**
+     * Absolute path to the embedded graph data directory/file, if any.
+     * Returns `null` for networked backends (Neo4j).
+     */
     getDataPath(): string | null;
 }
 /** Config shape accepted by `wolbarg({ graph: … })` when not passing an instance. */
 type GraphConfig = {
     provider: "sqlite";
+    /** File path for the embedded SQLite graph database. */
     path: string;
 } | {
     provider: "neo4j";
+    /** Bolt or Neo4j URI (e.g. `bolt://localhost:7687`). */
     url: string;
+    /** Neo4j username. */
     username: string;
+    /** Neo4j password. */
     password: string;
+    /** Optional Neo4j database name (default database when omitted). */
     database?: string;
 };
+/** Either a {@link GraphProvider} instance or a {@link GraphConfig} object. */
 type GraphInput$1 = GraphProvider | GraphConfig;
 
 /**
  * Chunking strategies for document ingestion.
+ *
+ * Long documents are split into overlapping chunks before embedding and storage.
+ * Choose a strategy via {@link createChunkingStrategy} or let ingest auto-detect
+ * with {@link inferChunkingStrategy}.
+ *
+ * @example
+ * ```ts
+ * import { createChunkingStrategy } from "wolbarg/chunking";
+ *
+ * const chunker = createChunkingStrategy("sentence");
+ * const chunks = chunker.chunk(documentText, { chunkSize: 800, overlap: 100 });
+ * ```
  */
+/** A single text chunk with stable index for ordering. */
 interface Chunk {
+    /** Chunk body text. */
     text: string;
+    /** Zero-based position in the original document. */
     index: number;
 }
+/** Options controlling chunk size and overlap. */
 interface ChunkingOptions {
+    /** Target characters per chunk (default `800`, minimum `32`). */
     chunkSize?: number;
+    /** Overlap between consecutive chunks (default `100`, capped at half of chunkSize). */
     overlap?: number;
 }
+/**
+ * Contract for document chunking strategies.
+ *
+ * Implement this interface for custom splitters (token-based, semantic, etc.).
+ * Wolbarg ingest calls {@link ChunkingStrategy.chunk} after parsing a document.
+ */
 interface ChunkingStrategy {
+    /** Strategy name (e.g. `"sentence"`, `"markdown"`). */
     readonly name: string;
+    /**
+     * Split `text` into ordered chunks.
+     * @param text - Full document text.
+     * @param options - Optional size and overlap overrides.
+     * @returns Non-overlapping or sliding-window chunks with indices.
+     */
     chunk(text: string, options?: ChunkingOptions): Chunk[];
 }
+/** Character-based fixed window chunking (ignores sentence boundaries). */
 declare class FixedChunkingStrategy implements ChunkingStrategy {
     readonly name = "fixed";
+    /** @inheritdoc */
     chunk(text: string, options?: ChunkingOptions): Chunk[];
 }
+/** Sentence-boundary-aware chunking (splits on `.!?` followed by whitespace). */
 declare class SentenceChunkingStrategy implements ChunkingStrategy {
     readonly name = "sentence";
+    /** @inheritdoc */
     chunk(text: string, options?: ChunkingOptions): Chunk[];
 }
+/** Paragraph-boundary-aware chunking (splits on blank lines). */
 declare class ParagraphChunkingStrategy implements ChunkingStrategy {
     readonly name = "paragraph";
+    /** @inheritdoc */
     chunk(text: string, options?: ChunkingOptions): Chunk[];
 }
+/** Markdown heading-aware chunking (splits on `#` headings; falls back to paragraph). */
 declare class MarkdownChunkingStrategy implements ChunkingStrategy {
     readonly name = "markdown";
+    /** @inheritdoc */
     chunk(text: string, options?: ChunkingOptions): Chunk[];
 }
+/** Alias for {@link MarkdownChunkingStrategy}. */
 declare class HeadingChunkingStrategy implements ChunkingStrategy {
     readonly name = "heading";
+    /** @inheritdoc */
     chunk(text: string, options?: ChunkingOptions): Chunk[];
 }
+/**
+ * Factory for built-in chunking strategies.
+ *
+ * @param name - Strategy name (default `"sentence"`).
+ * @returns A {@link ChunkingStrategy} instance.
+ *
+ * @example
+ * ```ts
+ * const chunker = createChunkingStrategy("markdown");
+ * ```
+ */
 declare function createChunkingStrategy(name?: "fixed" | "sentence" | "paragraph" | "markdown" | "heading"): ChunkingStrategy;
 
 /**
  * LLM provider abstractions and OpenAI-compatible chat implementation.
- * Used for memory compression and experimental rememberFromMessages extract mode.
+ *
+ * Used for memory compression ({@link Wolbarg.compress}) and experimental
+ * {@link Wolbarg.rememberFromMessages} extract mode.
+ *
+ * ## Custom LLM providers
+ *
+ * Pass any object that implements {@link LlmProvider} as `llm` in
+ * {@link WolbargOptions}:
+ *
+ * ```ts
+ * const myLlm: LlmProvider = {
+ *   model: "my-model",
+ *   async complete(messages) {
+ *     // Call your backend; return the assistant text
+ *     return "...";
+ *   },
+ *   async validate() {
+ *     await this.complete([{ role: "user", content: "ok" }]);
+ *   },
+ * };
+ *
+ * const ctx = wolbarg({
+ *   organization: "acme",
+ *   database: { provider: "sqlite", url: "./memory.db" },
+ *   embedding: openaiEmbedding({ apiKey: "...", model: "text-embedding-3-small" }),
+ *   llm: myLlm, // or openaiLlm({ ... }) / openaiCompatibleLlm({ ... })
+ * });
+ * ```
+ *
+ * Built-in factories (`openaiLlm`, `ollamaLlm`, `openRouterLlm`,
+ * `openaiCompatibleLlm`) wrap any OpenAI-compatible `/v1/chat/completions` API.
  */
 
+/**
+ * One message in a chat completion request.
+ *
+ * @property role - Speaker role. Use `"system"` for instructions, `"user"` for
+ *   prompts, `"assistant"` for prior model turns.
+ * @property content - Plain-text message body (non-empty for useful completions).
+ */
 interface ChatMessage {
     role: "system" | "user" | "assistant";
     content: string;
 }
-/** Contract for any chat completion backend. */
+/**
+ * Contract for any chat completion backend used by Wolbarg.
+ *
+ * Implement this interface to plug in a custom LLM (Anthropic, local GGUF via
+ * a custom HTTP bridge, Azure OpenAI with extra headers, etc.). The SDK only
+ * requires {@link LlmProvider.complete} to return the assistant reply as a
+ * string; streaming is not used.
+ *
+ * @example Custom provider
+ * ```ts
+ * const anthropicLike: LlmProvider = {
+ *   model: "claude-sonnet",
+ *   async complete(messages) {
+ *     const res = await fetch("https://api.example.com/complete", {
+ *       method: "POST",
+ *       body: JSON.stringify({ messages }),
+ *     });
+ *     const data = await res.json();
+ *     return String(data.text);
+ *   },
+ *   async validate() {
+ *     const reply = await this.complete([{ role: "user", content: "ping" }]);
+ *     if (!reply.trim()) throw new Error("empty reply");
+ *   },
+ * };
+ * ```
+ */
 interface LlmProvider {
+    /** Model identifier reported in telemetry / logs (any non-empty string). */
     readonly model: string;
+    /**
+     * Run a chat completion and return the assistant message text.
+     *
+     * @param messages - Ordered conversation turns. The last message is typically
+     *   the user (or system+user) prompt the SDK builds for compression / extract.
+     * @returns Trimmed assistant text. Empty responses should throw.
+     * @throws When the backend fails, times out, or returns no text.
+     */
     complete(messages: ChatMessage[]): Promise<string>;
-    /** Lightweight connectivity probe. */
+    /**
+     * Lightweight connectivity probe invoked during boot when an LLM is configured.
+     * Implementations typically call {@link LlmProvider.complete} with a tiny prompt.
+     *
+     * @throws When the endpoint is unreachable or misconfigured.
+     */
     validate(): Promise<void>;
 }
+/**
+ * Build an {@link LlmProvider} from {@link LlmConfig}.
+ *
+ * Prefer named helpers ({@link openaiLlm}, {@link ollamaLlm}, …) when the
+ * default `baseUrl` matches your host; use this (or {@link openaiCompatibleLlm})
+ * when you need a fully custom base URL.
+ *
+ * @param config - Full OpenAI-compatible config including `baseUrl`.
+ * @returns A ready-to-use {@link OpenAICompatibleLlmProvider}.
+ *
+ * @example
+ * ```ts
+ * const llm = createLlmProvider({
+ *   baseUrl: "https://api.openai.com/v1",
+ *   apiKey: process.env.OPENAI_API_KEY!,
+ *   model: "gpt-4o-mini",
+ *   temperature: 0.2,
+ *   maxTokens: 4096,
+ * });
+ * ```
+ */
 declare function createLlmProvider(config: LlmConfig): LlmProvider;
+/**
+ * OpenAI-compatible LLM with an explicit `baseUrl` (any compatible host).
+ *
+ * @param config - Full {@link LlmConfig} including `baseUrl`, `apiKey`, `model`.
+ * @returns {@link LlmProvider} instance.
+ *
+ * @example
+ * ```ts
+ * llm: openaiCompatibleLlm({
+ *   baseUrl: "https://my-proxy.example.com/v1",
+ *   apiKey: process.env.API_KEY!,
+ *   model: "gpt-4o-mini",
+ * })
+ * ```
+ */
 declare const openaiCompatibleLlm: (config: LlmConfig) => LlmProvider;
+/**
+ * OpenAI Chat Completions (`https://api.openai.com/v1`).
+ *
+ * @param config - `apiKey` and `model` required; optional `temperature`,
+ *   `maxTokens`, `timeoutMs`, and override `baseUrl`.
+ * @returns {@link LlmProvider} for use as `llm` in {@link WolbargOptions}.
+ *
+ * @example
+ * ```ts
+ * llm: openaiLlm({
+ *   apiKey: process.env.OPENAI_API_KEY!,
+ *   model: "gpt-4o-mini",
+ * })
+ * ```
+ */
 declare const openaiLlm: (config: Omit<LlmConfig, "baseUrl"> & {
     baseUrl?: string;
 }) => LlmProvider;
+/**
+ * Local Ollama OpenAI-compatible API (`http://127.0.0.1:11434/v1`).
+ *
+ * @param config - `apiKey` may be any non-empty string (Ollama often ignores it);
+ *   `model` is the Ollama model name (e.g. `"llama3.2"`).
+ * @returns {@link LlmProvider} pointing at the local Ollama server.
+ *
+ * @example
+ * ```ts
+ * llm: ollamaLlm({ apiKey: "ollama", model: "llama3.2" })
+ * ```
+ */
 declare const ollamaLlm: (config: Omit<LlmConfig, "baseUrl"> & {
     baseUrl?: string;
 }) => LlmProvider;
+/**
+ * OpenRouter chat API (`https://openrouter.ai/api/v1`).
+ *
+ * @param config - Use your OpenRouter API key and a routed model id
+ *   (e.g. `"openai/gpt-4o-mini"`).
+ * @returns {@link LlmProvider} for OpenRouter.
+ *
+ * @example
+ * ```ts
+ * llm: openRouterLlm({
+ *   apiKey: process.env.OPENROUTER_API_KEY!,
+ *   model: "openai/gpt-4o-mini",
+ * })
+ * ```
+ */
 declare const openRouterLlm: (config: Omit<LlmConfig, "baseUrl"> & {
     baseUrl?: string;
 }) => LlmProvider;
 
 /**
- * Memory compression — provider-based summarization.
+ * Memory compression — provider-based summarization of related memories.
+ *
+ * Compression collapses multiple memories into one summary via an LLM, archiving
+ * the originals with lineage. Use {@link createCompressionProvider} or call
+ * {@link compressMemories} directly when building custom pipelines.
+ *
+ * @example
+ * ```ts
+ * import { createCompressionProvider } from "wolbarg/compression";
+ * import { openaiLlm } from "wolbarg/llm";
+ *
+ * const compression = createCompressionProvider(openaiLlm({ apiKey, model: "gpt-4o-mini" }));
+ * const summary = await compression.compress(memories);
+ * ```
  */
 
-/** Contract for memory compression backends. */
+/**
+ * Contract for memory compression backends.
+ *
+ * Implement this interface to swap LLM vendors or use rule-based summarizers.
+ * Wolbarg's `compress()` facade delegates to the configured provider.
+ *
+ * @example Custom provider
+ * ```ts
+ * const rules: CompressionProvider = {
+ *   name: "truncate",
+ *   async compress(memories) {
+ *     return memories.map((m) => m.content.text).join(" | ").slice(0, 500);
+ *   },
+ * };
+ * ```
+ */
 interface CompressionProvider {
+    /** Provider identifier (e.g. `"llm"`, `"truncate"`). */
     readonly name: string;
+    /**
+     * Produce a single summary string from related memories.
+     * @param memories - Non-empty list of memories to collapse.
+     * @returns Plain-text summary.
+     * @throws {@link CompressionError} when compression fails or input is empty.
+     */
     compress(memories: MemoryRecord[]): Promise<string>;
 }
-/** Default compression provider wrapping an {@link LlmProvider}. */
+/**
+ * Default compression provider wrapping an {@link LlmProvider}.
+ *
+ * Delegates to {@link compressMemories} with the standard system prompt.
+ */
 declare class LlmCompressionProvider implements CompressionProvider {
     readonly name = "llm";
     private readonly llm;
+    /** @param llm - Configured LLM used for summarization. */
     constructor(llm: LlmProvider);
+    /** @inheritdoc */
     compress(memories: MemoryRecord[]): Promise<string>;
 }
+/**
+ * Factory for the default LLM-backed {@link CompressionProvider}.
+ *
+ * @param llm - LLM used for summarization.
+ * @returns A {@link CompressionProvider} named `"llm"`.
+ */
 declare function createCompressionProvider(llm: LlmProvider): CompressionProvider;
 
 /**
  * Embedding providers and named factories.
+ *
+ * ## Custom embedding providers
+ *
+ * Pass any object that implements {@link EmbeddingProvider} as `embedding` in
+ * {@link WolbargOptions}:
+ *
+ * ```ts
+ * const myEmbedder: EmbeddingProvider = {
+ *   model: "my-embed-model",
+ *   async embed(text) {
+ *     // Return a Float32Array of fixed dimensionality
+ *     return new Float32Array([...]);
+ *   },
+ *   // Optional — if omitted, the SDK parallelizes `embed` via embedMany
+ *   async embedBatch(texts) {
+ *     return Promise.all(texts.map((t) => this.embed(t)));
+ *   },
+ *   async validate() {
+ *     const v = await this.embed("health check");
+ *     return { dimensions: v.length };
+ *   },
+ * };
+ *
+ * const ctx = wolbarg({
+ *   organization: "acme",
+ *   database: { provider: "sqlite", url: "./memory.db" },
+ *   embedding: myEmbedder, // or openaiEmbedding({ ... })
+ * });
+ * ```
+ *
+ * Built-in factories wrap OpenAI-compatible `POST {baseUrl}/embeddings` APIs.
+ * **Important:** keep the same model (and dimensions) for the lifetime of a
+ * database — mixing models will cause dimension mismatch errors.
  */
 
-/** Contract for any embedding backend. */
+/**
+ * Contract for any embedding backend used by Wolbarg.
+ *
+ * Implement this to plug in Voyage, Cohere, a local ONNX model, etc. Vectors
+ * must be finite floats; dimensionality is fixed after the first successful
+ * {@link EmbeddingProvider.validate} / remember.
+ */
 interface EmbeddingProvider {
+    /** Embedding model id (telemetry + cache key namespace). */
     readonly model: string;
-    /** Produce a float embedding for the given text. */
+    /**
+     * Produce a float embedding for the given text.
+     *
+     * @param text - Non-empty content to embed (memory text or recall query).
+     * @returns Dense vector as `Float32Array` (same length for every call).
+     */
     embed(text: string): Promise<Float32Array>;
-    /** Optional batch embedding. SDK falls back to parallel `embed` when absent. */
+    /**
+     * Optional batch embedding. When present, {@link embedMany} and ingest prefer it.
+     * When absent, the SDK falls back to concurrent single {@link embed} calls.
+     *
+     * @param texts - Texts to embed in one request when the API supports batching.
+     * @returns One vector per input text, same order as `texts`.
+     */
     embedBatch?(texts: string[]): Promise<Float32Array[]>;
-    /** Lightweight connectivity + dimension probe. */
+    /**
+     * Connectivity + dimension probe used during {@link Wolbarg.ready}.
+     *
+     * @returns Object with `dimensions` equal to the vector length.
+     * @throws When the endpoint is unreachable or returns an empty vector.
+     */
     validate(): Promise<{
         dimensions: number;
     }>;
 }
+/**
+ * Build an {@link EmbeddingProvider} from {@link EmbeddingConfig}.
+ *
+ * @param config - Full config including `baseUrl`, `apiKey`, and `model`.
+ * @returns A ready-to-use {@link OpenAICompatibleEmbeddingProvider}.
+ *
+ * @example
+ * ```ts
+ * const embedding = createEmbeddingProvider({
+ *   baseUrl: "https://api.openai.com/v1",
+ *   apiKey: process.env.OPENAI_API_KEY!,
+ *   model: "text-embedding-3-small",
+ * });
+ * ```
+ */
 declare function createEmbeddingProvider(config: EmbeddingConfig): EmbeddingProvider;
+/**
+ * OpenAI-compatible embeddings with an explicit `baseUrl`.
+ *
+ * @param config - Full {@link EmbeddingConfig} including `baseUrl`.
+ * @returns {@link EmbeddingProvider} instance.
+ *
+ * @example
+ * ```ts
+ * embedding: openaiCompatibleEmbedding({
+ *   baseUrl: "https://my-proxy.example.com/v1",
+ *   apiKey: process.env.API_KEY!,
+ *   model: "text-embedding-3-small",
+ * })
+ * ```
+ */
 declare const openaiCompatibleEmbedding: (config: EmbeddingConfig) => EmbeddingProvider;
+/**
+ * OpenAI Embeddings API (`https://api.openai.com/v1`).
+ *
+ * @param config - `apiKey` and `model` required (e.g. `"text-embedding-3-small"`);
+ *   optional `timeoutMs` and override `baseUrl`.
+ * @returns {@link EmbeddingProvider} for use as `embedding` in {@link WolbargOptions}.
+ *
+ * @example
+ * ```ts
+ * embedding: openaiEmbedding({
+ *   apiKey: process.env.OPENAI_API_KEY!,
+ *   model: "text-embedding-3-small",
+ * })
+ * ```
+ */
 declare const openaiEmbedding: (config: Omit<EmbeddingConfig, "baseUrl"> & {
     baseUrl?: string;
 }) => EmbeddingProvider;
+/**
+ * Local Ollama embeddings (`http://127.0.0.1:11434/v1`).
+ *
+ * @param config - `apiKey` may be any non-empty string; `model` is the Ollama
+ *   embedding model (e.g. `"nomic-embed-text"`).
+ * @returns {@link EmbeddingProvider} for local Ollama.
+ */
 declare const ollamaEmbedding: (config: Omit<EmbeddingConfig, "baseUrl"> & {
     baseUrl?: string;
 }) => EmbeddingProvider;
+/**
+ * OpenRouter embeddings (`https://openrouter.ai/api/v1`).
+ *
+ * @param config - OpenRouter API key and routed embedding model id.
+ * @returns {@link EmbeddingProvider} for OpenRouter.
+ */
 declare const openRouterEmbedding: (config: Omit<EmbeddingConfig, "baseUrl"> & {
     baseUrl?: string;
 }) => EmbeddingProvider;
+/**
+ * LM Studio local server embeddings (`http://127.0.0.1:1234/v1`).
+ *
+ * @param config - Local API key (often unused) and the loaded embedding model name.
+ * @returns {@link EmbeddingProvider} for LM Studio.
+ */
 declare const lmStudioEmbedding: (config: Omit<EmbeddingConfig, "baseUrl"> & {
     baseUrl?: string;
 }) => EmbeddingProvider;
+/**
+ * Google Gemini embeddings via the OpenAI-compatible endpoint.
+ * Default base: `https://generativelanguage.googleapis.com/v1beta/openai`.
+ *
+ * @param config - Gemini API key and embedding model (e.g. `"text-embedding-004"`).
+ * @returns {@link EmbeddingProvider} for Gemini.
+ */
 declare const geminiEmbedding: (config: Omit<EmbeddingConfig, "baseUrl"> & {
     baseUrl?: string;
 }) => EmbeddingProvider;
+/**
+ * Together AI embeddings (`https://api.together.xyz/v1`).
+ *
+ * @param config - Together API key and embedding model id.
+ * @returns {@link EmbeddingProvider} for Together.
+ */
 declare const togetherEmbedding: (config: Omit<EmbeddingConfig, "baseUrl"> & {
     baseUrl?: string;
 }) => EmbeddingProvider;
+/**
+ * vLLM OpenAI-compatible embeddings (`http://127.0.0.1:8000/v1`).
+ *
+ * @param config - Local/server API key (if required) and the served model name.
+ * @returns {@link EmbeddingProvider} for vLLM.
+ */
 declare const vllmEmbedding: (config: Omit<EmbeddingConfig, "baseUrl"> & {
     baseUrl?: string;
 }) => EmbeddingProvider;
 
 /**
- * Keyword / BM25 search providers.
+ * Keyword / BM25 search providers for hybrid recall.
+ *
+ * Use these when you want lexical (BM25) scoring alongside semantic vector search.
+ * Pass a {@link KeywordSearchProvider} to Wolbarg retrieval config, or rely on
+ * native FTS when the storage backend supports it.
+ *
+ * @example
+ * ```ts
+ * import { bm25 } from "wolbarg/keyword";
+ *
+ * const keyword = bm25({ k1: 1.2, b: 0.75 });
+ * const hits = await keyword.search("billing issue", documents, 10);
+ * ```
  */
+/** A single keyword search hit with memory id and BM25 score. */
 interface KeywordSearchHit {
+    /** Memory UUID that matched the query. */
     memoryId: string;
+    /** BM25 relevance score (higher is better). */
     score: number;
 }
+/** Document passed to keyword search — typically memory id + text body. */
 interface KeywordDocument {
+    /** Memory UUID. */
     id: string;
+    /** Searchable text content. */
     text: string;
 }
-/** Contract for keyword / lexical search. */
+/**
+ * Contract for keyword / lexical search backends.
+ *
+ * Implement this interface to plug in a custom BM25, Elasticsearch, or FTS adapter.
+ * Wolbarg calls {@link KeywordSearchProvider.search} during hybrid recall when no
+ * native storage keyword index is available.
+ *
+ * @example Custom provider
+ * ```ts
+ * const myKeyword: KeywordSearchProvider = {
+ *   name: "my-fts",
+ *   async search(query, documents, topK) {
+ *     // score documents and return topK hits
+ *     return [{ memoryId: documents[0]!.id, score: 1.0 }];
+ *   },
+ * };
+ * ```
+ */
 interface KeywordSearchProvider {
+    /** Provider identifier (e.g. `"bm25"`, `"fts5"`). */
     readonly name: string;
+    /**
+     * Rank documents by lexical relevance to `query`.
+     * @param query - User search string.
+     * @param documents - Candidate memories to score.
+     * @param topK - Maximum hits to return.
+     * @returns Hits sorted by score descending.
+     */
     search(query: string, documents: KeywordDocument[], topK: number): Promise<KeywordSearchHit[]>;
 }
-/** Factory for in-memory BM25 keyword search. */
+/**
+ * Factory for the default in-memory BM25 keyword provider.
+ *
+ * @param options - Optional BM25 tuning (`k1`, `b`).
+ * @returns A {@link KeywordSearchProvider} ready for hybrid recall.
+ *
+ * @example
+ * ```ts
+ * const keyword = bm25();
+ * ```
+ */
 declare function bm25(options?: {
     k1?: number;
     b?: number;
 }): KeywordSearchProvider;
 
 /**
- * Optional OCR provider — extract text from images.
+ * Optional OCR providers — extract text from images during ingest.
+ *
+ * OCR is used when ingesting image files without accompanying text. Install the
+ * optional peer `tesseract.js` before calling {@link tesseract}.
+ *
+ * @example
+ * ```ts
+ * import { tesseract } from "wolbarg/ocr";
+ *
+ * const ocr = tesseract();
+ * const { text } = await ocr.recognize(imageBuffer, "image/png");
+ * ```
  */
+/** Result of optical character recognition on an image. */
 interface OcrResult {
+    /** Extracted plain text (may be empty if OCR finds nothing). */
     text: string;
 }
+/**
+ * Contract for OCR backends.
+ *
+ * Implement this interface to plug in Google Vision, Azure OCR, or another engine.
+ * Wolbarg calls {@link OCRProvider.recognize} during ingest when a document parser
+ * marks the source as an image.
+ *
+ * @example Custom provider
+ * ```ts
+ * const myOcr: OCRProvider = {
+ *   name: "cloud-ocr",
+ *   async recognize(image, mimeType) {
+ *     const text = await callMyApi(image, mimeType);
+ *     return { text };
+ *   },
+ * };
+ * ```
+ */
 interface OCRProvider {
+    /** Provider identifier (e.g. `"tesseract"`, `"cloud-ocr"`). */
     readonly name: string;
+    /**
+     * Extract text from a raster image buffer.
+     * @param image - Raw image bytes.
+     * @param mimeType - Optional MIME hint (e.g. `"image/png"`).
+     * @returns Recognized text.
+     */
     recognize(image: Buffer, mimeType?: string): Promise<OcrResult>;
 }
 /**
- * Placeholder Tesseract adapter.
- * Requires optional peer packages (`tesseract.js`) when used.
+ * Tesseract.js OCR adapter.
+ *
+ * Requires the optional peer package `tesseract.js`. Throws
+ * {@link ConfigurationError} with install instructions when the peer is missing.
+ *
+ * @returns An {@link OCRProvider} using English (`"eng"`) by default.
+ *
+ * @example
+ * ```ts
+ * // npm install tesseract.js
+ * const ocr = tesseract();
+ * const result = await ocr.recognize(buffer);
+ * ```
  */
 declare function tesseract(): OCRProvider;
 
 /**
- * Reranker provider abstractions.
+ * Reranker provider abstractions for second-stage recall ranking.
+ *
+ * Rerankers reorder vector/keyword candidates using cross-encoders or LLM scoring.
+ * Pass a {@link RerankerProvider} to Wolbarg retrieval config or call factories
+ * directly in custom pipelines.
+ *
+ * @example
+ * ```ts
+ * import { cohereReranker } from "wolbarg/rerank";
+ *
+ * const reranker = cohereReranker({ apiKey: process.env.COHERE_API_KEY! });
+ * const hits = await reranker.rerank(query, documents, 5);
+ * ```
  */
+/** Document passed to a reranker — memory id + searchable text. */
 interface RerankDocument {
+    /** Memory UUID. */
     id: string;
+    /** Text body used for relevance scoring. */
     text: string;
 }
+/** A reranked hit with relevance score. */
 interface RerankHit {
+    /** Memory UUID. */
     id: string;
+    /** Relevance score (higher is better; provider-specific scale). */
     score: number;
 }
-/** Contract for cross-encoder / API rerankers. */
+/**
+ * Contract for cross-encoder and API rerankers.
+ *
+ * Implement this interface to plug in Cohere, Jina, local cross-encoders, or
+ * custom scoring. On failure, built-in HTTP adapters fall back to identity order
+ * so recall never returns zero hits.
+ *
+ * @example Custom provider
+ * ```ts
+ * const myReranker: RerankerProvider = {
+ *   name: "local-ce",
+ *   async rerank(query, documents, topK) {
+ *     return documents.slice(0, topK).map((d, i) => ({ id: d.id, score: 1 - i * 0.1 }));
+ *   },
+ * };
+ * ```
+ */
 interface RerankerProvider {
+    /** Provider identifier (e.g. `"cohere"`, `"openai"`). */
     readonly name: string;
+    /**
+     * Reorder documents by query relevance.
+     * @param query - User search string.
+     * @param documents - Candidate memories to rerank.
+     * @param topK - Maximum hits to return.
+     * @returns Hits sorted by score descending.
+     */
     rerank(query: string, documents: RerankDocument[], topK: number): Promise<RerankHit[]>;
 }
-/** Lightweight local cross-encoder proxy (OpenAI-compatible score endpoint fallback = identity order). */
+/**
+ * Generic cross-encoder reranker for OpenAI-compatible `/rerank` endpoints.
+ *
+ * Falls back to identity order when the HTTP call fails or returns an unexpected shape.
+ *
+ * @param options - Remote endpoint configuration.
+ * @param options.baseUrl - API base URL (appends `/rerank`).
+ * @param options.apiKey - Bearer token for authorization.
+ * @param options.model - Optional model name sent in the request body.
+ * @param options.timeoutMs - Request timeout (default `30000`).
+ */
 declare function crossEncoder(options: {
     baseUrl: string;
     apiKey: string;
     model?: string;
     timeoutMs?: number;
 }): RerankerProvider;
+/**
+ * Jina AI reranker (`jina-reranker-v2-base-multilingual` by default).
+ *
+ * @param options.apiKey - Jina API key.
+ * @param options.model - Model id override.
+ * @param options.timeoutMs - Request timeout (default `30000`).
+ */
 declare function jinaReranker(options: {
     apiKey: string;
     model?: string;
     timeoutMs?: number;
 }): RerankerProvider;
+/**
+ * Cohere Rerank v3.5 API adapter.
+ *
+ * @param options.apiKey - Cohere API key.
+ * @param options.model - Model id (default `"rerank-v3.5"`).
+ * @param options.timeoutMs - Request timeout (default `30000`).
+ */
 declare function cohereReranker(options: {
     apiKey: string;
     model?: string;
     timeoutMs?: number;
 }): RerankerProvider;
-/** Alias for BGE-style remote rerank endpoints that speak the Jina/Cohere shape. */
+/**
+ * BGE-style remote reranker for self-hosted endpoints with Jina/Cohere response shape.
+ *
+ * @param options.apiKey - Bearer token for the remote service.
+ * @param options.baseUrl - Service base URL (appends `/rerank`).
+ * @param options.model - Optional model name.
+ * @param options.timeoutMs - Request timeout (default `30000`).
+ */
 declare function bgeReranker(options: {
     apiKey: string;
     baseUrl: string;
@@ -922,8 +1593,20 @@ declare function bgeReranker(options: {
     timeoutMs?: number;
 }): RerankerProvider;
 /**
- * OpenAI chat-based reranker (no Cohere/Jina key required).
- * Scores query–document relevance via chat completions and reorders hits.
+ * OpenAI chat-based reranker (no dedicated rerank API key required).
+ *
+ * Scores query–document relevance via JSON-mode chat completions and reorders hits.
+ * Falls back to identity order on parse or network errors.
+ *
+ * @param options.apiKey - OpenAI API key.
+ * @param options.model - Chat model (default `"gpt-4.1-mini"`).
+ * @param options.baseUrl - API base (default `"https://api.openai.com/v1"`).
+ * @param options.timeoutMs - Request timeout (default `60000`).
+ *
+ * @example
+ * ```ts
+ * const reranker = openaiReranker({ apiKey: process.env.OPENAI_API_KEY! });
+ * ```
  */
 declare function openaiReranker(options: {
     apiKey: string;
@@ -933,21 +1616,36 @@ declare function openaiReranker(options: {
 }): RerankerProvider;
 
 /**
- * Shared provider contracts for Wolbarg v0.2.
+ * Shared provider contracts for Wolbarg storage layer.
+ *
+ * {@link StorageProvider} is the low-level contract implemented by SQLite and
+ * PostgreSQL backends. Custom storage engines must implement every required method;
+ * optional methods enable performance optimizations (batch fetch, native keyword search).
  */
 
-/** Row shape returned from the memories table. */
+/** Row shape returned from the `memories` table. */
 interface MemoryRow {
+    /** Memory UUID primary key. */
     id: string;
+    /** Organization namespace. */
     organization: string;
+    /** Owning agent id. */
     agent: string;
+    /** Plain-text memory body. */
     content_text: string;
+    /** Serialized JSON metadata. */
     metadata_json: string;
+    /** `1` when soft-archived, `0` when active. */
     archived: number;
+    /** Summary memory id when archived via compression, else `null`. */
     compressed_into: string | null;
+    /** SHA-256 of normalized content for exact dedupe, when present. */
     content_hash?: string | null;
+    /** ISO-8601 creation timestamp. */
     created_at: string;
+    /** ISO-8601 last update timestamp. */
     updated_at: string;
+    /** SQLite integer rowid used by vec0 / vector index (when applicable). */
     rowid?: number;
 }
 /** Row shape for memory history events. */
@@ -994,48 +1692,112 @@ interface VectorSearchHit {
 }
 /**
  * Low-level storage provider contract.
- * Public API never depends on a specific engine.
+ *
+ * Public Wolbarg API never depends on a specific engine — implement this interface
+ * to add a custom backend (e.g. another SQL dialect or hosted vector store wrapper).
+ *
+ * @example Implementing a custom provider
+ * ```ts
+ * class MyStorage implements StorageProvider {
+ *   readonly name = "my-storage";
+ *   async open() { /* connect + migrate *\/ }
+ *   async close() { /* disconnect *\/ }
+ *   // ... implement remaining required methods
+ * }
+ * ```
  */
 interface StorageProvider {
+    /** Backend identifier (e.g. `"sqlite"`, `"postgres"`). */
     readonly name: string;
     /** Open connection, enable WAL / pragmas, run migrations, prepare statements. */
     open(): Promise<void>;
-    /** Close the underlying connection. */
+    /** Close the underlying connection pool or file handle. */
     close(): Promise<void>;
-    /** Ensure the vector table exists for the given embedding dimensionality. */
+    /**
+     * Ensure the vector table exists for the given embedding dimensionality.
+     * @param dimensions - Embedding vector length from the configured model.
+     */
     ensureVectorSchema(dimensions: number): Promise<void>;
-    /** Current embedding dimensionality stored in meta, or null if unset. */
+    /** @returns Stored embedding dimensions from meta table, or `null` if unset. */
     getEmbeddingDimensions(): Promise<number | null>;
-    /** Persist embedding dimensionality in the meta table. */
+    /**
+     * Persist embedding dimensionality in the meta table.
+     * @param dimensions - Vector length to record.
+     */
     setEmbeddingDimensions(dimensions: number): Promise<void>;
-    /** Insert a memory + embedding inside a single ACID transaction. */
+    /**
+     * Insert a memory + embedding inside a single ACID transaction.
+     * @param input - Full insert payload including embedding vector.
+     * @returns Inserted row including generated `rowid` when applicable.
+     */
     insertMemory(input: InsertMemoryInput): Promise<MemoryRow>;
-    /** Batch insert memories + embeddings in one transaction. */
+    /**
+     * Batch insert memories + embeddings in one transaction.
+     * @param inputs - Non-empty array of insert payloads.
+     */
     insertMemoriesBatch(inputs: InsertMemoryInput[]): Promise<MemoryRow[]>;
-    /** Update memory fields and optionally replace embedding. */
+    /**
+     * Update memory fields and optionally replace embedding.
+     * @param input - Fields to patch; omitted fields are left unchanged.
+     * @returns Updated row, or `null` when id not found.
+     */
     updateMemory(input: UpdateMemoryInput): Promise<MemoryRow | null>;
     /**
      * Find an active (non-archived) memory by content hash within org+agent.
-     * Used by write-time exact dedupe.
+     * Used by write-time exact dedupe. Optional — omit when dedupe is disabled.
+     *
+     * @param organization - Organization namespace.
+     * @param agent - Agent id scope.
+     * @param contentHash - SHA-256 from {@link hashMemoryContent}.
      */
     findActiveByContentHash?(organization: string, agent: string, contentHash: string): Promise<MemoryRow | null>;
-    /** Fetch a memory by UUID. */
+    /**
+     * Fetch a memory by UUID.
+     * @param id - Memory id.
+     * @param organization - Organization namespace (authorization scope).
+     */
     getMemoryById(id: string, organization: string): Promise<MemoryRow | null>;
-    /** Fetch a memory by its integer rowid. */
+    /**
+     * Fetch a memory by its integer rowid (vector index key).
+     * @param rowid - SQLite rowid or equivalent.
+     * @param organization - Organization namespace.
+     */
     getMemoryByRowid(rowid: number, organization: string): Promise<MemoryRow | null>;
     /**
      * Batch fetch memories by rowids (one query). Optional — Wolbarg falls
-     * back to parallel getMemoryByRowid when absent.
+     * back to parallel `getMemoryByRowid` when absent.
+     *
+     * @param rowids - Vector index row identifiers.
+     * @param organization - Organization namespace.
+     * @returns Map from rowid to row for hits only.
      */
     getMemoriesByRowids?(rowids: number[], organization: string): Promise<Map<number, MemoryRow>>;
-    /** List memories matching a filter. */
+    /**
+     * List memories matching a filter.
+     * @param filter - Organization, optional agent, archive, and metadata scope.
+     * @param limit - Maximum rows (backend default when omitted).
+     */
     listMemories(filter: RepositoryFilter, limit?: number): Promise<MemoryRow[]>;
-    /** Search memories by metadata filter only. */
+    /**
+     * Search memories by metadata filter only (no vector query).
+     * @param filter - Must include organization; optional metadata AST.
+     * @param limit - Maximum rows to return.
+     */
     searchByMetadata(filter: RepositoryFilter, limit?: number): Promise<MemoryRow[]>;
-    /** KNN search against the vector index. */
+    /**
+     * KNN search against the vector index.
+     * @param embedding - Query vector (same dimensionality as stored memories).
+     * @param topK - Number of nearest neighbors.
+     * @returns Hits with cosine distance (lower is more similar for sqlite-vec).
+     */
     searchVectors(embedding: Float32Array, topK: number): Promise<VectorSearchHit[]>;
     /**
      * Optional: KNN + memory rows in one round-trip, org-scoped.
+     *
+     * @param embedding - Query vector.
+     * @param topK - Neighbor count.
+     * @param organization - Organization filter applied in SQL.
+     * @param options - Optional agent filter and archive inclusion.
      */
     searchVectorsWithMemories?(embedding: Float32Array, topK: number, organization: string, options?: {
         agent?: string;
@@ -1047,6 +1809,10 @@ interface StorageProvider {
     /**
      * Optional: native keyword / BM25 search (e.g. SQLite FTS5).
      * When present, hybrid recall can skip loading the full corpus.
+     *
+     * @param query - User search string.
+     * @param organization - Organization namespace.
+     * @param topK - Maximum lexical hits.
      */
     searchKeyword?(query: string, organization: string, topK: number): Promise<Array<{
         memoryId: string;
@@ -1054,20 +1820,40 @@ interface StorageProvider {
     }>>;
     /**
      * Soft-archive memories and record lineage linking them to a summary.
-     * Returns the archived memory IDs.
+     *
+     * @param ids - Memory UUIDs to archive.
+     * @param organization - Organization namespace.
+     * @param compressedIntoId - New summary memory id.
+     * @param archivedAt - ISO timestamp for the archive event.
+     * @returns The archived memory ids actually updated.
      */
     archiveMemories(ids: string[], organization: string, compressedIntoId: string, archivedAt: string): Promise<string[]>;
-    /** Hard-delete a single memory and its embedding. */
+    /**
+     * Hard-delete a single memory and its embedding.
+     * @returns `true` when a row was deleted.
+     */
     deleteMemoryById(id: string, organization: string): Promise<boolean>;
-    /** Hard-delete memories matching a filter. Returns deleted count. */
+    /**
+     * Hard-delete memories matching a filter.
+     * @returns Count of deleted rows.
+     */
     deleteMemoriesByFilter(filter: RepositoryFilter): Promise<number>;
-    /** Delete every memory for an organization. Returns deleted count. */
+    /**
+     * Delete every memory for an organization.
+     * @returns Count of deleted rows.
+     */
     clearOrganization(organization: string): Promise<number>;
-    /** History events for a memory, oldest first. */
+    /**
+     * History events for a memory, oldest first.
+     * @param memoryId - Memory UUID.
+     */
     getHistory(memoryId: string): Promise<HistoryRow[]>;
-    /** Append a history event. */
+    /** Append a history event (created, archived, compressed, updated). */
     insertHistoryEvent(event: HistoryRow): Promise<void>;
-    /** Count memories / distinct agents for an organization. */
+    /**
+     * Count memories / distinct agents for an organization.
+     * @param organization - Organization namespace.
+     */
     getStats(organization: string): Promise<{
         totalMemories: number;
         activeMemories: number;
@@ -1076,55 +1862,121 @@ interface StorageProvider {
     }>;
     /** Approximate on-disk database size in bytes. */
     getDatabaseSizeBytes(): Promise<number>;
-    /** Run `fn` inside a single ACID transaction. */
+    /**
+     * Run `fn` inside a single ACID transaction.
+     * @param fn - Synchronous or async work executed atomically.
+     * @returns Value returned by `fn`.
+     */
     withTransaction<T>(fn: () => T | Promise<T>): T | Promise<T>;
 }
-/** Back-compat alias. */
+/** Back-compat alias for {@link StorageProvider}. */
 type DatabaseProvider = StorageProvider;
 
 /**
- * Database-agnostic checkpoint contract.
- * Snapshots memory state so callers can rollback without third-party libs.
+ * Database-agnostic checkpoint contract for memory snapshots.
+ *
+ * Checkpoints copy file-backed SQLite memory databases so callers can rollback
+ * without third-party backup libraries.
  */
+/** Metadata recorded for each named checkpoint. */
 interface CheckpointMeta {
+    /** User-provided checkpoint name (unique). */
     name: string;
+    /** Optional human description. */
     description: string | null;
+    /** ISO-8601 creation time. */
     createdAt: string;
+    /** Wolbarg SDK version that created the checkpoint. */
     sdkVersion: string;
+    /** Storage provider name (e.g. `"sqlite"`). */
     provider: string;
     /** Absolute path or URI of the snapshot artifact. */
     snapshotPath: string;
     /** Absolute path or URI of the source memory database at creation time. */
     sourcePath: string;
+    /** On-disk snapshot size in bytes. */
     sizeBytes: number;
 }
+/** Options passed to {@link CheckpointProvider.checkpoint}. */
 interface CreateCheckpointOptions {
+    /** Optional description stored in {@link CheckpointMeta}. */
     description?: string;
 }
+/**
+ * Checkpoint provider contract — create, list, restore, and delete snapshots.
+ *
+ * Implement this interface for custom snapshot storage (S3, tarball, etc.).
+ * Built-in: {@link SqliteCheckpointProvider}.
+ *
+ * @example
+ * ```ts
+ * await checkpointProvider.checkpoint("pre-migration", sourceDbPath, {
+ *   description: "Before schema migration",
+ * });
+ * ```
+ */
 interface CheckpointProvider {
+    /** Provider identifier. */
     readonly name: string;
     /** Prepare checkpoint storage (directories / tables). */
     open(): Promise<void>;
+    /** Close checkpoint storage handles. */
     close(): Promise<void>;
     /**
      * Create a named snapshot of the current memory database.
      * Must fail if the name already exists (never overwrite).
+     *
+     * @param name - Unique checkpoint name.
+     * @param sourcePath - Live memory database path to snapshot.
+     * @param options - Optional description.
      */
     checkpoint(name: string, sourcePath: string, options?: CreateCheckpointOptions): Promise<CheckpointMeta>;
-    /** Restore the memory database from a named checkpoint. */
+    /**
+     * Restore the memory database from a named checkpoint.
+     *
+     * @param name - Existing checkpoint name.
+     * @param targetPath - Path to overwrite with the snapshot.
+     */
     rollback(name: string, targetPath: string): Promise<CheckpointMeta>;
-    /** Permanently remove a checkpoint and its snapshot files. */
+    /**
+     * Permanently remove a checkpoint and its snapshot files.
+     * @returns `true` when a checkpoint was deleted.
+     */
     deleteCheckpoint(name: string): Promise<boolean>;
+    /** List all checkpoints ordered by creation time. */
     listCheckpoints(): Promise<CheckpointMeta[]>;
+    /**
+     * Fetch metadata for one checkpoint.
+     * @param name - Checkpoint name.
+     */
     getCheckpoint(name: string): Promise<CheckpointMeta | null>;
 }
 
 /**
  * Database-agnostic telemetry persistence contract.
- * Telemetry MUST use a separate database from memory storage.
+ *
+ * Telemetry MUST use a separate database from memory storage — never share tables.
  */
 
+/**
+ * Telemetry provider contract — async, non-blocking event emission.
+ *
+ * Implement this interface for custom observability sinks (OpenTelemetry export,
+ * cloud logging, etc.). Built-in: SQLite telemetry via {@link SqliteTelemetryProvider}.
+ *
+ * @example Custom write-only provider
+ * ```ts
+ * const provider: TelemetryProvider = {
+ *   name: "console",
+ *   async open() {},
+ *   async close() {},
+ *   emit(event) { console.log(event.operation, event.durationMs); },
+ *   async flush() {},
+ * };
+ * ```
+ */
 interface TelemetryProvider {
+    /** Provider identifier (e.g. `"sqlite-telemetry"`, `"noop"`). */
     readonly name: string;
     /** Open the independent event database connection. */
     open(): Promise<void>;
@@ -1133,34 +1985,106 @@ interface TelemetryProvider {
     /**
      * Persist a telemetry event. Must not block callers of memory operations.
      * Implementations may queue and flush asynchronously.
+     *
+     * @param event - Fully or partially populated event input.
      */
     emit(event: TelemetryEventInput): void;
-    /** Wait until the write queue is empty (used by tests / shutdown). */
+    /** Wait until the write queue is empty (used by tests / graceful shutdown). */
     flush(): Promise<void>;
-    /** Read events (primarily for Studio / debugging). Optional for write-only backends. */
+    /**
+     * Read events (primarily for Studio / debugging). Optional for write-only backends.
+     * @param options - Query filters and pagination.
+     */
     query?(options: TelemetryQuery): Promise<TelemetryQueryResult>;
-    /** Fetch a single event by id. */
+    /**
+     * Fetch a single event by id.
+     * @param id - Event UUID.
+     */
     getEvent?(id: string): Promise<TelemetryEvent | null>;
 }
 
 /**
- * Optional vision provider — captions / descriptions / entities from images.
+ * Optional vision providers — captions, descriptions, and entities from images.
+ *
+ * Vision analysis enriches image ingest when OCR alone is insufficient. Both
+ * {@link openaiVision} and {@link geminiVision} use OpenAI-compatible chat
+ * endpoints with multimodal messages.
+ *
+ * @example
+ * ```ts
+ * import { openaiVision } from "wolbarg/vision";
+ *
+ * const vision = openaiVision({ apiKey: process.env.OPENAI_API_KEY! });
+ * const result = await vision.analyze(imageBuffer, "image/jpeg");
+ * console.log(result.caption, result.entities);
+ * ```
  */
+/** Structured output from a vision analysis call. */
 interface VisionResult {
+    /** Short one-line caption. */
     caption: string;
+    /** Longer natural-language description. */
     description: string;
+    /** Named entities or objects detected in the image. */
     entities: string[];
 }
+/**
+ * Contract for vision / multimodal analysis backends.
+ *
+ * Implement this interface to plug in Claude, local VLMs, or custom APIs.
+ * Wolbarg merges vision output into ingest metadata when processing images.
+ *
+ * @example Custom provider
+ * ```ts
+ * const myVision: VisionProvider = {
+ *   name: "my-vlm",
+ *   async analyze(image, mimeType) {
+ *     return { caption: "...", description: "...", entities: ["cat"] };
+ *   },
+ * };
+ * ```
+ */
 interface VisionProvider {
+    /** Provider identifier (e.g. `"openai-vision"`, `"gemini"`). */
     readonly name: string;
+    /**
+     * Analyze an image and return structured caption data.
+     * @param image - Raw image bytes.
+     * @param mimeType - MIME type for the data URL (default `"image/png"`).
+     */
     analyze(image: Buffer, mimeType?: string): Promise<VisionResult>;
 }
+/**
+ * Google Gemini vision via the OpenAI-compatible Generative Language API.
+ *
+ * @param options - API credentials and model selection.
+ * @param options.apiKey - Gemini API key.
+ * @param options.model - Model id (default `"gemini-2.0-flash"`).
+ * @param options.baseUrl - Override API base (default Google OpenAI-compat endpoint).
+ * @param options.timeoutMs - Request timeout in milliseconds (default `60000`).
+ * @returns A {@link VisionProvider} instance.
+ */
 declare function geminiVision(options: {
     apiKey: string;
     model?: string;
     baseUrl?: string;
     timeoutMs?: number;
 }): VisionProvider;
+/**
+ * OpenAI vision via `/chat/completions` with image_url content parts.
+ *
+ * @param options - API credentials and model selection.
+ * @param options.apiKey - OpenAI API key.
+ * @param options.model - Vision-capable model (default `"gpt-4o-mini"`).
+ * @param options.baseUrl - Override API base (default `"https://api.openai.com/v1"`).
+ * @param options.timeoutMs - Request timeout in milliseconds (default `60000`).
+ * @returns A {@link VisionProvider} instance.
+ *
+ * @example
+ * ```ts
+ * const vision = openaiVision({ apiKey: process.env.OPENAI_API_KEY! });
+ * ```
+ */
 declare function openaiVision(options: {
     apiKey: string;
     model?: string;
@@ -1169,40 +2093,104 @@ declare function openaiVision(options: {
 }): VisionProvider;
 
 /**
- * Constructor options for Wolbarg v0.3.
+ * Constructor options for Wolbarg (v0.5.5).
+ *
+ * Pass **provider instances** (custom implementations of the interfaces) or
+ * **config objects / factory helpers**. Discriminated at runtime via
+ * {@link isEmbeddingProvider}, {@link isLlmProvider}, {@link isStorageProvider},
+ * {@link isTelemetryProvider}, and {@link isGraphProvider}.
  */
 
+/**
+ * Embedding input: a live {@link EmbeddingProvider} **or** an
+ * {@link EmbeddingConfig} / factory result (`openaiEmbedding(...)`, etc.).
+ *
+ * Custom provider example:
+ * ```ts
+ * const embedding: EmbeddingProvider = {
+ *   model: "custom",
+ *   embed: async (text) => { /* return Float32Array *\/ },
+ *   validate: async () => ({ dimensions: 768 }),
+ * };
+ * ```
+ */
 type EmbeddingInput = EmbeddingProvider | EmbeddingConfig;
+/**
+ * LLM input: a live {@link LlmProvider} **or** an {@link LlmConfig} /
+ * factory result (`openaiLlm(...)`, `ollamaLlm(...)`, etc.).
+ *
+ * Required for {@link Wolbarg.compress} and `rememberFromMessages({ mode: "extract" })`.
+ *
+ * Custom provider example:
+ * ```ts
+ * const llm: LlmProvider = {
+ *   model: "my-model",
+ *   complete: async (messages) => { /* return assistant text *\/ },
+ *   validate: async () => { /* ping endpoint *\/ },
+ * };
+ * ```
+ */
 type LlmInput = LlmProvider | LlmConfig;
+/**
+ * Storage input: a live {@link StorageProvider} **or** a
+ * {@link StorageConfig} / {@link DatabaseConfig} (`{ provider: "sqlite", url }`).
+ */
 type StorageInput = StorageProvider | StorageConfig | DatabaseConfig;
+/**
+ * Graph input: a live {@link GraphProvider} **or** a {@link GraphConfig}
+ * (`sqliteGraph({ path })` / `neo4jGraph({ url, username, password })`).
+ */
 type GraphInput = GraphProvider | GraphConfig;
+/**
+ * Shared constructor fields (with or without LLM).
+ */
 interface WolbargOptionsBase {
     /** Organization namespace isolating memories within a shared database. */
     organization: string;
     /**
      * Storage provider instance or config.
-     * Prefer `database` in v0.3 docs; `storage` remains fully supported.
+     * Prefer `database` in docs; `storage` remains fully supported.
      */
     storage?: StorageInput;
     /**
-     * v0.3 alias for `storage`. Accepts `{ provider, url }` or `{ provider, connectionString }`.
+     * Alias for `storage`. Accepts `{ provider, url }` or `{ provider, connectionString }`,
+     * or a custom {@link StorageProvider}.
      */
     database?: StorageInput;
-    /** Embedding provider instance or config. */
+    /**
+     * Embedding provider instance or config.
+     * Use {@link openaiEmbedding} / {@link ollamaEmbedding} / etc., raw
+     * {@link EmbeddingConfig}, or any custom {@link EmbeddingProvider}.
+     */
     embedding: EmbeddingInput;
-    /** Optional independent telemetry system (separate database). */
+    /**
+     * Optional independent telemetry system (separate database or custom
+     * {@link TelemetryProvider}).
+     */
     telemetry?: TelemetryConfig | TelemetryProvider;
     /** Optional checkpoint provider override (defaults to SQLite when file-backed). */
     checkpoint?: CheckpointProvider;
     /** Optional directory for SQLite checkpoints. */
     checkpointDirectory?: string;
-    /** Optional reranker — skipped when absent. */
+    /**
+     * Optional reranker — skipped when absent.
+     * Implement {@link RerankerProvider} or use `jinaReranker` / `cohereReranker` / etc.
+     */
     reranker?: RerankerProvider;
-    /** Optional keyword search — enables hybrid recall when present. */
+    /**
+     * Optional keyword search — enables hybrid recall when present.
+     * Implement {@link KeywordSearchProvider} or use {@link bm25}.
+     */
     keywordSearch?: KeywordSearchProvider;
-    /** Optional OCR for image ingest. */
+    /**
+     * Optional OCR for image ingest.
+     * Implement {@link OCRProvider} or use {@link tesseract}.
+     */
     ocr?: OCRProvider;
-    /** Optional vision model for image captions. */
+    /**
+     * Optional vision model for image captions during ingest.
+     * Implement {@link VisionProvider} or use {@link openaiVision} / {@link geminiVision}.
+     */
     vision?: VisionProvider;
     /**
      * Optional graph memory layer (SQLite embedded or Neo4j networked).
@@ -1210,11 +2198,17 @@ interface WolbargOptionsBase {
      * Accepts a {@link GraphProvider} instance or a recognized config shape.
      */
     graph?: GraphInput;
-    /** Optional compression provider (overrides llm-backed default). */
+    /**
+     * Optional compression provider (overrides the default LLM-backed compressor).
+     * Implement {@link CompressionProvider} for a fully custom compress pipeline.
+     */
     compression?: CompressionProvider;
-    /** Optional default chunking strategy for ingest. */
+    /**
+     * Optional default chunking strategy for ingest.
+     * Implement {@link ChunkingStrategy} or use `createChunkingStrategy(...)`.
+     */
     chunking?: ChunkingStrategy;
-    /** Optional retrieval defaults. */
+    /** Optional retrieval defaults (over-fetch, hybrid weights, MMR). */
     retrieval?: RetrievalConfig;
     /** SQLite multi-writer concurrency tuning (ignored for Postgres). */
     concurrency?: ConcurrencyConfig$1;
@@ -1222,43 +2216,86 @@ interface WolbargOptionsBase {
     embeddingCache?: EmbeddingCacheConfig;
     /** Memory write-path options (dedupe / upsert). */
     memory?: {
+        /** Exact / near-duplicate detection on remember. See {@link MemoryDedupeConfig}. */
         dedupe?: MemoryDedupeConfig;
     };
 }
+/**
+ * Options when no LLM is configured (`compress` / extract mode unavailable).
+ */
 interface WolbargOptionsWithoutLlm extends WolbargOptionsBase {
     llm?: undefined;
 }
+/**
+ * Options when an LLM is configured (enables {@link Wolbarg.compress}).
+ */
 interface WolbargOptionsWithLlm extends WolbargOptionsBase {
-    /** Chat model used for compression. */
+    /**
+     * Chat model used for compression and extract-mode rememberFromMessages.
+     * Pass a custom {@link LlmProvider} (`complete` + `validate`) or a config /
+     * factory such as {@link openaiLlm} / {@link ollamaLlm} /
+     * {@link openaiCompatibleLlm}.
+     */
     llm: LlmInput;
 }
+/** Discriminated union of constructor options. */
 type WolbargOptions = WolbargOptionsWithoutLlm | WolbargOptionsWithLlm;
 
 /**
  * Public subscribe() types for real-time memory change events.
+ *
+ * Agents and dashboards use these types with `wolbarg.subscribe()` to receive
+ * push notifications when memories are created, updated, forgotten, compressed, or ingested.
+ *
+ * @example
+ * ```ts
+ * const unsub = wolbarg.subscribe(
+ *   { organization: "acme", event: "remember" },
+ *   (event) => console.log(event.memoryId),
+ * );
+ * ```
  */
+/** Event names that can be filtered in {@link SubscribeFilter.event}. */
 type SubscribableEvent = "remember" | "update" | "forget" | "compress" | "ingest" | "*";
+/** Filter passed to `wolbarg.subscribe()` to scope notifications. */
 interface SubscribeFilter {
+    /** Organization namespace (required). */
     organization: string;
+    /** Optional agent id — omit to receive events for all agents. */
     agent?: string;
+    /** Single event, list of events, or `"*"` for all (default all when omitted). */
     event?: SubscribableEvent | SubscribableEvent[];
 }
+/** Payload delivered to {@link MemoryChangeCallback} listeners. */
 interface MemoryChangeEvent {
+    /** Operation that triggered the notification. */
     event: Exclude<SubscribableEvent, "*">;
+    /** Organization namespace. */
     organization: string;
+    /** Agent that performed the operation. */
     agent: string;
+    /** Affected memory id, or multiple ids for batch operations. */
     memoryId: string | string[];
+    /** ISO-8601 timestamp when the change occurred. */
     timestamp: string;
+    /** Optional telemetry trace id linking to observability events. */
     traceId?: string;
+    /** Optional session id from the originating SDK instance. */
     sessionId?: string;
     /** Present when upsert path ran during remember/ingest. */
     upsertAction?: "created" | "updated" | "skipped";
 }
+/** Callback invoked for each matching memory change event. */
 type MemoryChangeCallback = (event: MemoryChangeEvent) => void;
+/** Function returned from subscribe — call to remove the listener. */
 type Unsubscribe = () => void;
 
 /**
- * Wolbarg — modular semantic memory SDK for AI agents (v0.3).
+ * Wolbarg — modular semantic memory SDK for AI agents (v0.5.5).
+ *
+ * Construct with {@link wolbarg} or `new Wolbarg(options)`. Pass provider
+ * **instances** (custom implementations) or **configs / factory helpers**
+ * for embedding, LLM, storage, graph, and optional plugins.
  *
  * @example
  * ```ts
@@ -1271,6 +2308,11 @@ type Unsubscribe = () => void;
  *     apiKey: process.env.OPENAI_API_KEY!,
  *     model: "text-embedding-3-small",
  *   }),
+ *   // Optional — required for compress() and rememberFromMessages({ mode: "extract" })
+ *   llm: openaiLlm({
+ *     apiKey: process.env.OPENAI_API_KEY!,
+ *     model: "gpt-4o-mini",
+ *   }),
  *   telemetry: {
  *     enabled: true,
  *     database: { provider: "sqlite", url: "./telemetry.db" },
@@ -1284,7 +2326,14 @@ type Unsubscribe = () => void;
  * ```
  */
 
+/**
+ * Main Wolbarg facade: remember / recall / ingest / graph / checkpoints.
+ *
+ * @typeParam HasLlm - `true` when constructed with an `llm` (enables
+ *   {@link Wolbarg.compress} at the type level).
+ */
 declare class Wolbarg<HasLlm extends boolean = false> {
+    /** Compile-time marker: `true` when an LLM was configured at construction. */
     readonly __hasLlm: HasLlm;
     private initialized;
     private booting;
@@ -1311,19 +2360,67 @@ declare class Wolbarg<HasLlm extends boolean = false> {
     private memoryDedupe;
     private embeddingCacheConfig;
     private rawEmbedding;
+    /**
+     * Create a Wolbarg instance with an LLM (enables {@link Wolbarg.compress}).
+     *
+     * @param options - See {@link WolbargOptionsWithLlm}. `llm` may be a custom
+     *   {@link LlmProvider} (`{ model, complete, validate }`) or a config /
+     *   factory result such as {@link openaiLlm}.
+     */
     constructor(options: WolbargOptionsWithLlm);
+    /**
+     * Create a Wolbarg instance without an LLM (compress / extract mode unavailable).
+     *
+     * @param options - See {@link WolbargOptionsWithoutLlm}.
+     */
     constructor(options: WolbargOptionsWithoutLlm);
+    /**
+     * Empty constructor for the legacy {@link Wolbarg.init} flow.
+     * Prefer passing options to the constructor or {@link wolbarg}.
+     */
     constructor();
     /**
      * 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.
      */
     init(options: InitOptions): Promise<void>;
-    /** 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.
+     */
     ready(): Promise<void>;
+    /** Internal boot sequence invoked by {@link Wolbarg.ready}. */
     private boot;
-    /** 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.
+     */
     remember(options: RememberOptions): Promise<RememberResult>;
-    /** 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.
+     */
     rememberBatch(items: RememberOptions[]): Promise<RememberResult[]>;
     /**
      * Store memories from a chat transcript.
@@ -1331,11 +2428,26 @@ declare class Wolbarg<HasLlm extends boolean = false> {
      * **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.
      */
     rememberFromMessages(messages: ConversationMessage[], options: RememberFromMessagesOptions): Promise<RememberResult[]>;
     /**
-     * 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.
      */
     update(options: {
         id: string;
@@ -1345,62 +2457,206 @@ declare class Wolbarg<HasLlm extends boolean = false> {
         metadata?: MemoryMetadata;
     }): Promise<RememberResult>;
     /**
-     * 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: SubscribeFilter, callback: (event: MemoryChangeEvent) => void): Unsubscribe;
+    /** Broadcast a memory change event to in-process or Postgres NOTIFY subscribers. */
     private emitChange;
     /** Internal remember with optional upsert/dedupe. */
     private rememberOne;
+    /**
+     * 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.
+     */
     private findNearDuplicate;
     /**
-     * Semantic / hybrid search over stored memories.
+     * Semantic (and optional hybrid / MMR / rerank / graph) search over stored memories.
      * Pass `{ explain: true }` for enriched ranking diagnostics.
+     *
+     * @param options - Query text plus optional `topK` (default 5), `threshold`,
+     *   `filter`, `hybrid`, `mmr`, `rerank`, `includeGraph`, `explain`.
+     *   See {@link RecallOptions}.
+     * @returns Ranked {@link RecallResult}[] normally, or {@link RecallExplainResponse}
+     *   when `explain: true`.
      */
     recall(options: RecallOptions & {
         explain: true;
     }): Promise<RecallExplainResponse>;
+    /**
+     * @param options - Recall options with `explain` omitted or `false`.
+     * @returns Ranked memory hits.
+     */
     recall(options: RecallOptions & {
         explain?: false;
     }): Promise<RecallResult[]>;
     recall(options: RecallOptions): Promise<RecallResult[] | RecallExplainResponse>;
-    /** 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.
+     */
     recallBatch(queries: Array<Omit<RecallOptions, "explain">>): Promise<RecallResult[][]>;
+    /**
+     * 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.
+     */
     compress(this: Wolbarg<true>, options: CompressOptions): Promise<CompressResult>;
-    /** @internal */
+    /** @internal Runs compress for both typed and untyped call sites. */
     private runCompress;
+    /**
+     * 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.
+     */
     ingest(options: IngestOptions): Promise<IngestResult>;
     /**
-     * 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.
      */
     linkMemories(fromId: string, toId: string, relation: string, metadata?: Record<string, unknown>): Promise<void>;
     /**
      * 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.
      */
     getRelated(memoryId: string, options?: GetRelatedOptions): Promise<MemoryRecord[]>;
+    /**
+     * 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.
+     */
     forget(options: ForgetOptions): Promise<number>;
+    /**
+     * 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.
+     */
     history(options: HistoryOptions): Promise<HistoryResult>;
+    /**
+     * Aggregate counts for this organization (active / archived / agents / etc.).
+     *
+     * @returns {@link StatsResult} snapshot.
+     */
     stats(): Promise<StatsResult>;
+    /**
+     * 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.
+     */
     clear(options: ClearOptions): Promise<number>;
-    /** 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.
+     */
     checkpoint(name: string, options?: CheckpointOptions): Promise<CheckpointInfo>;
-    /** 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.
+     */
     rollback(name: string): Promise<CheckpointInfo>;
+    /**
+     * Delete a named checkpoint from disk / the checkpoint store.
+     *
+     * @param name - Checkpoint name.
+     * @returns `true` if a checkpoint was removed.
+     */
     deleteCheckpoint(name: string): Promise<boolean>;
+    /**
+     * List all known checkpoints for this instance.
+     *
+     * @returns Array of {@link CheckpointInfo} (may be empty).
+     */
     listCheckpoints(): Promise<CheckpointInfo[]>;
+    /**
+     * Look up a single checkpoint by name.
+     *
+     * @param name - Checkpoint name.
+     * @returns {@link CheckpointInfo} or `null` if missing.
+     */
     getCheckpoint(name: string): Promise<CheckpointInfo | null>;
-    /** 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.
+     */
     export(exportPath: string): Promise<ExportResult>;
-    /** 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.
+     */
     import(exportPath: string): Promise<ImportResult>;
-    /** Flush pending telemetry (useful in tests). */
+    /**
+     * Flush pending telemetry writes (useful in tests / before process exit).
+     *
+     * @returns Resolves when the telemetry provider has flushed.
+     */
     flushTelemetry(): Promise<void>;
-    /** Session id for this SDK instance (telemetry traces). */
+    /**
+     * Session id for this SDK instance (attached to telemetry traces and change events).
+     */
     get sessionId(): string;
     /**
      * Optional process-wide lock for SQLite read-modify-write (dedupe upsert).
@@ -1408,67 +2664,144 @@ declare class Wolbarg<HasLlm extends boolean = false> {
      * insertMemory calls under a single BEGIN IMMEDIATE for multi-writer throughput.
      */
     private withWriteLock;
+    /**
+     * 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).
+     */
     close(): Promise<void>;
+    /** Whether {@link Wolbarg.ready} / {@link Wolbarg.init} has completed successfully. */
     get isInitialized(): boolean;
+    /** Ensure {@link Wolbarg.ready} completed and core providers are available. */
     private requireReady;
+    /** Reject embeddings whose dimensionality differs from the initialized model. */
     private assertEmbeddingDimensions;
+    /** Return the configured checkpoint provider or throw {@link ProviderNotConfiguredError}. */
     private requireCheckpointProvider;
+    /** Return the configured graph provider or throw with a setup hint for `method`. */
     private requireGraph;
+    /** Throw when graph checkpoint pairing is requested on a non-file-backed graph backend. */
     private assertGraphCheckpointSupported;
+    /** Directory path where a graph file snapshot is stored alongside a memory checkpoint. */
     private graphSnapshotDir;
+    /** Close the graph provider before copying files; returns whether a close occurred. */
     private closeGraphForSnapshot;
+    /** Copy the SQLite graph database next to a memory checkpoint directory. */
     private snapshotGraphAlongside;
+    /** Restore a graph file snapshot written by {@link snapshotGraphAlongside}. */
     private restoreGraphAlongside;
+    /** Run graph traversal then re-hydrate stub records from storage when rows exist. */
     private hydrateRelated;
+    /** Resolve the on-disk SQLite memory database path (throws for Postgres / `:memory:`). */
     private requireMemoryDbPath;
 }
-/** Preferred v0.3 entry — re-exported from factories as well. */
+/**
+ * Preferred factory — equivalent to `new Wolbarg(options)`.
+ *
+ * @param options - Full {@link WolbargOptions}. Pass custom provider instances
+ *   (`embedding`, `llm`, `storage`, `graph`, …) or factory helpers
+ *   (`openaiEmbedding`, `openaiLlm`, `sqliteGraph`, …). See constructor docs
+ *   on {@link Wolbarg} for every option field.
+ * @returns A configured {@link Wolbarg} instance (call {@link Wolbarg.ready} before use).
+ *
+ * @example
+ * ```ts
+ * const memory = wolbarg({
+ *   organization: "acme",
+ *   database: { provider: "sqlite", url: "./memory.db" },
+ *   embedding: openaiEmbedding({
+ *     apiKey: process.env.OPENAI_API_KEY!,
+ *     model: "text-embedding-3-small",
+ *   }),
+ *   llm: openaiLlm({
+ *     apiKey: process.env.OPENAI_API_KEY!,
+ *     model: "gpt-4o-mini",
+ *   }),
+ * });
+ * await memory.ready();
+ * ```
+ */
 declare function wolbarg$1(options: WolbargOptions): Wolbarg;
 
-/** Published SDK semver — keep in sync with package.json `version`. */
-declare const SDK_VERSION = "0.5.3";
+/** Published SDK semver — keep in sync with `package.json` `version`. */
+declare const SDK_VERSION = "0.5.5";
 
 /**
- * Operation-scoped errors with reason + suggestion for developer experience.
+ * Operation-scoped errors with stable `code`, human `reason`, and actionable `suggestion`.
+ *
+ * All Wolbarg errors extend {@link WolbargError} so callers can use `instanceof`
+ * checks and read structured fields in IDE hover docs.
+ */
+/**
+ * Base class for all Wolbarg SDK errors.
+ *
+ * @property code - Stable machine-readable error code (e.g. `"VALIDATION_ERROR"`).
+ * @property reason - Short explanation of why the operation failed.
+ * @property suggestion - Actionable fix hint for developers.
+ * @property operation - Facade method name when applicable (e.g. `"recall"`).
  */
-/** Base class for all Wolbarg errors. */
 declare class WolbargError extends Error {
     readonly code: string;
     readonly reason?: string;
     readonly suggestion?: string;
     readonly operation?: string;
+    /**
+     * @param message - Human-readable error message.
+     * @param code - Stable error code string.
+     * @param options - Optional cause, reason, suggestion, and operation name.
+     */
     constructor(message: string, code: string, options?: ErrorOptions & {
         reason?: string;
         suggestion?: string;
         operation?: string;
     });
 }
-/** Thrown when SDK initialization fails. */
+/** Thrown when SDK initialization or `open()` fails. */
 declare class InitializationError extends WolbargError {
+    /**
+     * @param message - Description of the initialization failure.
+     * @param options - Optional cause and structured hints.
+     */
     constructor(message: string, options?: ErrorOptions & {
         reason?: string;
         suggestion?: string;
         operation?: string;
     });
 }
-/** Thrown when configuration values are missing or invalid. */
+/**
+ * Thrown when configuration values are missing, invalid, or incompatible.
+ * Also used for missing optional peer packages (PDF, OCR, Neo4j, etc.).
+ */
 declare class ConfigurationError extends WolbargError {
+    /**
+     * @param message - Description of the misconfiguration.
+     * @param options - Optional cause, reason, suggestion, and operation name.
+     */
     constructor(message: string, options?: ErrorOptions & {
         reason?: string;
         suggestion?: string;
         operation?: string;
     });
 }
-/** Thrown when method arguments fail validation. */
+/** Thrown when method arguments fail validation before reaching storage. */
 declare class ValidationError extends WolbargError {
+    /**
+     * @param message - Which argument failed and why.
+     * @param options - Optional cause and structured hints.
+     */
     constructor(message: string, options?: ErrorOptions & {
         reason?: string;
         suggestion?: string;
         operation?: string;
     });
 }
-/** Thrown when a database operation fails. */
+/** Thrown when a low-level database read/write fails. */
 declare class DatabaseError extends WolbargError {
+    /**
+     * @param message - Operation-scoped failure message.
+     * @param options - Optional underlying `cause` and hints.
+     */
     constructor(message: string, options?: ErrorOptions & {
         reason?: string;
         suggestion?: string;
@@ -1477,33 +2810,49 @@ declare class DatabaseError extends WolbargError {
 }
 /**
  * Thrown when SQLite write-lock retries are exhausted.
- * Stable code: WOLBARG_STORAGE_LOCKED
+ * Stable code: `WOLBARG_STORAGE_LOCKED`.
  */
 declare class StorageLockedError extends WolbargError {
+    /**
+     * @param message - Lock contention description.
+     * @param options - Typically includes suggestion to tune concurrency or use Postgres.
+     */
     constructor(message: string, options?: ErrorOptions & {
         reason?: string;
         suggestion?: string;
         operation?: string;
     });
 }
-/** Thrown when an embedding request fails. */
+/** Thrown when an embedding API request fails or returns invalid vectors. */
 declare class EmbeddingError extends WolbargError {
+    /**
+     * @param message - Embedding failure description.
+     * @param options - Optional HTTP cause and provider hints.
+     */
     constructor(message: string, options?: ErrorOptions & {
         reason?: string;
         suggestion?: string;
         operation?: string;
     });
 }
-/** Thrown when compression (LLM summarization) fails. */
+/** Thrown when LLM-based memory compression (summarization) fails. */
 declare class CompressionError extends WolbargError {
+    /**
+     * @param message - Compression failure description.
+     * @param options - Optional LLM cause chain.
+     */
     constructor(message: string, options?: ErrorOptions & {
         reason?: string;
         suggestion?: string;
         operation?: string;
     });
 }
-/** Thrown when a requested memory does not exist. */
+/** Thrown when a requested memory id does not exist or is archived. */
 declare class MemoryNotFoundError extends WolbargError {
+    /**
+     * @param message - Which memory was not found.
+     * @param options - Optional operation context.
+     */
     constructor(message: string, options?: ErrorOptions & {
         reason?: string;
         suggestion?: string;
@@ -1511,10 +2860,16 @@ declare class MemoryNotFoundError extends WolbargError {
     });
 }
 /**
- * Thrown when a method requires an optional provider that was not configured.
+ * Thrown when a method requires an optional provider that was not configured
+ * (reranker, OCR, graph, LLM for extract mode, etc.).
  */
 declare class ProviderNotConfiguredError extends ConfigurationError {
     readonly provider: string;
+    /**
+     * @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: string, method: string, hint: string);
 }
 /**
@@ -1523,52 +2878,161 @@ declare class ProviderNotConfiguredError extends ConfigurationError {
  * snapshots; Neo4j does not in v1 — we refuse rather than silently skip.
  */
 declare class GraphCheckpointNotSupportedError extends WolbargError {
+    /**
+     * @param backend - Graph backend name (e.g. `"neo4j"`).
+     * @param operation - Requested operation (e.g. `"checkpoint"`).
+     */
     constructor(backend: string, operation: string);
 }
-/** Map low-level SQLite / driver errors into actionable operation errors. */
+/**
+ * Map low-level SQLite / driver errors into actionable {@link WolbargError} subclasses.
+ *
+ * Preserves existing {@link WolbargError} instances unchanged. Recognizes lock
+ * contention, missing files, and read-only database errors.
+ *
+ * @param operation - Facade method name for the error message (e.g. `"remember"`).
+ * @param error - Raw thrown value from the driver.
+ * @returns A typed {@link WolbargError} subclass with `reason` and `suggestion`.
+ */
 declare function wrapOperationError(operation: string, error: unknown): WolbargError;
 
 /**
- * Public factory helpers for storage / providers.
+ * Public factory helpers for storage, telemetry, checkpoints, and graph providers (v0.5.5).
  */
 
-/** Create a SQLite storage provider from a path or `:memory:`. */
+/**
+ * Create a SQLite {@link StorageProvider} from a filesystem path or `:memory:`.
+ *
+ * @param connectionString - Absolute/relative `.db` path, or `":memory:"` for ephemeral.
+ * @returns Ready-to-pass storage provider (Wolbarg still calls `open()` via `ready()`).
+ *
+ * @example
+ * ```ts
+ * wolbarg({ organization: "acme", storage: sqlite("./memory.db"), embedding: ... })
+ * ```
+ */
 declare function sqlite(connectionString: string): StorageProvider;
-/** Create a SQLite storage config object (for init / options). */
+/**
+ * Create a SQLite storage **config object** (for `database` / `init` options).
+ *
+ * @param connectionString - Path or `:memory:`.
+ * @returns `{ provider: "sqlite", connectionString, url }`.
+ */
 declare function sqliteConfig(connectionString: string): SqliteDatabaseConfig;
-/** Create a PostgreSQL storage provider. Requires optional peer dependency `pg`. */
+/**
+ * Create a PostgreSQL {@link StorageProvider}. Requires optional peer `pg`.
+ *
+ * @param options - Connection string, or an object with:
+ *   - `connectionString` — Postgres URL
+ *   - `maxPoolSize` — optional pool size
+ *   - `durableWrites` — default `true`; set `false` for higher write throughput (async commit)
+ * @returns Postgres storage provider instance.
+ *
+ * @example
+ * ```ts
+ * postgres(process.env.DATABASE_URL!)
+ * postgres({ connectionString: process.env.DATABASE_URL!, maxPoolSize: 10 })
+ * ```
+ */
 declare function postgres(options: string | {
     connectionString: string;
     maxPoolSize?: number;
     /** Default true. Set false for higher write throughput (async commit). */
     durableWrites?: boolean;
 }): StorageProvider;
-/** Create a PostgreSQL storage config object. */
+/**
+ * Create a PostgreSQL storage **config object**.
+ *
+ * @param connectionString - Postgres connection URL.
+ * @param options.maxPoolSize - Optional pool size.
+ * @param options.durableWrites - Optional durability flag (default true).
+ * @returns `{ provider: "postgres", connectionString, url, ... }`.
+ */
 declare function postgresConfig(connectionString: string, options?: {
     maxPoolSize?: number;
     durableWrites?: boolean;
 }): PostgresDatabaseConfig;
-/** Create a SQLite telemetry provider for an independent event database. */
+/**
+ * Create a SQLite {@link TelemetryProvider} for an independent event database.
+ *
+ * @param url - Path to the telemetry SQLite file (separate from memory DB).
+ * @returns Telemetry provider for `telemetry:` constructor option.
+ */
 declare function sqliteTelemetry(url: string): TelemetryProvider;
-/** Create a SQLite checkpoint provider. */
+/**
+ * Create a SQLite {@link CheckpointProvider}.
+ *
+ * @param directory - Optional directory for checkpoint files (default under cwd).
+ * @returns Checkpoint provider for `checkpoint:` constructor option.
+ */
 declare function sqliteCheckpoint(directory?: string): CheckpointProvider;
-/** Create an embedded SQLite graph provider (file-backed, local/dev). */
+/**
+ * Create an embedded SQLite {@link GraphProvider} (file-backed, local/dev).
+ *
+ * @param options.path - Filesystem path for the graph SQLite database
+ *   (separate from the memory DB).
+ * @returns Graph provider for `graph:` in {@link WolbargOptions}.
+ *
+ * @example
+ * ```ts
+ * graph: sqliteGraph({ path: "./graph.db" })
+ * ```
+ */
 declare function sqliteGraph(options: {
     path: string;
 }): GraphProvider;
-/** Create a Neo4j graph provider (networked). Requires optional peer `neo4j-driver`. */
+/**
+ * Create a Neo4j {@link GraphProvider} (networked). Requires optional peer `neo4j-driver`.
+ *
+ * @param options.url - Bolt URL, e.g. `neo4j://localhost:7687` or `bolt://…`.
+ * @param options.username - Neo4j username.
+ * @param options.password - Neo4j password.
+ * @param options.database - Optional database name (Neo4j 4+ multi-DB).
+ * @returns Graph provider for `graph:` in {@link WolbargOptions}.
+ *
+ * @example
+ * ```ts
+ * graph: neo4jGraph({
+ *   url: "neo4j://localhost:7687",
+ *   username: "neo4j",
+ *   password: process.env.NEO4J_PASSWORD!,
+ * })
+ * ```
+ */
 declare function neo4jGraph(options: {
     url: string;
     username: string;
     password: string;
     database?: string;
 }): GraphProvider;
-/** Create a telemetry provider from config (SQLite only in v0.3). */
+/**
+ * Create a {@link TelemetryProvider} from {@link TelemetryConfig}.
+ * Currently only SQLite telemetry databases are implemented.
+ *
+ * @param config - Telemetry config with `database.provider` and `database.url`.
+ * @returns SQLite telemetry provider instance.
+ * @throws {ConfigurationError} If provider is not `"sqlite"` or url is missing.
+ */
 declare function createTelemetryProvider(config: TelemetryConfig): TelemetryProvider;
 /**
- * Preferred v0.3 factory. Equivalent to `new Wolbarg(options)`.
+ * Preferred factory. Equivalent to `new Wolbarg(options)`.
+ *
+ * @param options - Full {@link WolbargOptions} (providers, database, embedding, optional llm).
+ * @returns Configured {@link Wolbarg} instance — call `ready()` before use.
+ *
+ * @example
+ * ```ts
+ * const ctx = wolbarg({
+ *   organization: "acme",
+ *   database: sqliteConfig("./memory.db"),
+ *   embedding: openaiEmbedding({ apiKey: "...", model: "text-embedding-3-small" }),
+ * });
+ * await ctx.ready();
+ * ```
  */
 declare function wolbarg(options: WolbargOptions): Wolbarg;
+/** @deprecated Alias of {@link wolbarg}. */
+declare const createWolbarg: typeof wolbarg;
 
 /**
  * SQLite multi-writer concurrency defaults and validation.
@@ -1597,9 +3061,14 @@ interface ConcurrencyConfig {
  */
 
 interface SqliteProviderOptions {
+    /** Filesystem path or `:memory:` connection string. */
     connectionString: string;
+    /** Optional write-lock tuning for concurrent async callers. */
     concurrency?: ConcurrencyConfig;
 }
+/**
+ * SQLite + sqlite-vec {@link StorageProvider} (Node.js built-in `node:sqlite`).
+ */
 declare class SqliteStorageProvider implements StorageProvider {
     readonly name = "sqlite";
     private readonly connectionString;
@@ -1609,6 +3078,10 @@ declare class SqliteStorageProvider implements StorageProvider {
     private vectorDimensions;
     private vectorBackend;
     private sqliteVecLoaded;
+    /** Tracks nesting depth for {@link withTransaction} so we can use savepoints. */
+    private transactionDepth;
+    /** Incrementing counter for deterministic savepoint names. */
+    private savepointCounter;
     /** Hot in-process ANN for blob backend (sqlite-vec unavailable platforms). */
     private memoryIndex;
     private memoryIndexDirty;
@@ -1630,40 +3103,65 @@ declare class SqliteStorageProvider implements StorageProvider {
     /** Coalesce concurrent insertMemory callers into one IMMEDIATE transaction. */
     private insertQueue;
     private insertFlushScheduled;
+    /**
+     * @param options - SQLite path / `:memory:` and optional concurrency config.
+     */
     constructor(options: SqliteProviderOptions);
     /** Absolute or relative path / `:memory:` used by this provider. */
     get path(): string;
     /** Expose DB for embedding cache store (same connection). */
     getDatabase(): DatabaseSync | null;
+    /** Register a callback invoked when SQLite busy retries occur (tests / diagnostics). */
     setRetryLogger(fn: ((msg: string) => void) | null): void;
+    /** Open the database, run migrations, and prepare statements. */
     open(): Promise<void>;
+    /** Drain pending inserts, optimize, and close the SQLite connection. */
     close(): Promise<void>;
+    /**
+     * Create or validate vec0 / blob vector storage for the given dimensionality.
+     *
+     * @param dimensions - Embedding length from the configured model.
+     */
     ensureVectorSchema(dimensions: number): Promise<void>;
+    /** @inheritdoc StorageProvider.getEmbeddingDimensions */
     getEmbeddingDimensions(): Promise<number | null>;
+    /** @inheritdoc StorageProvider.setEmbeddingDimensions */
     setEmbeddingDimensions(dimensions: number): Promise<void>;
+    /** Insert a single memory row (coalesced under concurrent writers). */
     insertMemory(input: InsertMemoryInput): Promise<MemoryRow>;
     private scheduleInsertFlush;
     private flushInsertQueue;
     /** Single-row insert without coalescing (used by flush of size 1). */
     private insertMemoryImmediate;
+    /** Batch insert memories in chunked multi-row transactions. */
     insertMemoriesBatch(inputs: InsertMemoryInput[]): Promise<MemoryRow[]>;
+    /** Update memory content, metadata, embedding, and content hash. */
     updateMemory(input: UpdateMemoryInput): Promise<MemoryRow | null>;
+    /** Find an active memory by org, agent, and content hash (dedupe). */
     findActiveByContentHash(organization: string, agent: string, contentHash: string): Promise<MemoryRow | null>;
+    /** Scan memories matching metadata filters (may paginate in SQL). */
     searchByMetadata(filter: RepositoryFilter, limit?: number): Promise<MemoryRow[]>;
     /** Keyword search via FTS5 BM25. Returns memory IDs ranked by relevance. */
+    /** BM25 keyword search via FTS5 (`memories_fts`). */
     searchKeyword(query: string, organization: string, topK: number): Promise<Array<{
         memoryId: string;
         score: number;
     }>>;
+    /** Fetch a memory row by UUID within an organization. */
     getMemoryById(id: string, organization: string): Promise<MemoryRow | null>;
+    /** Fetch a memory row by SQLite integer rowid within an organization. */
     getMemoryByRowid(rowid: number, organization: string): Promise<MemoryRow | null>;
+    /** Batch-fetch memory rows by SQLite rowids within an organization. */
     getMemoriesByRowids(rowids: number[], organization: string): Promise<Map<number, MemoryRow>>;
+    /** List memories matching repository filters with optional limit. */
     listMemories(filter: RepositoryFilter, limit?: number): Promise<MemoryRow[]>;
+    /** Approximate nearest-neighbor search (vec0 or in-memory blob index). */
     searchVectors(embedding: Float32Array, topK: number): Promise<VectorSearchHit[]>;
     /**
      * 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. */
     searchVectorsWithMemories(embedding: Float32Array, topK: number, organization: string, options?: {
         agent?: string;
         includeArchived?: boolean;
@@ -1671,18 +3169,26 @@ declare class SqliteStorageProvider implements StorageProvider {
         row: MemoryRow;
         distance: number;
     }>>;
+    /** Soft-archive memories (compression / forget paths). */
     archiveMemories(ids: string[], organization: string, compressedIntoId: string, archivedAt: string): Promise<string[]>;
+    /** Hard-delete a single memory by id; returns whether a row was removed. */
     deleteMemoryById(id: string, organization: string): Promise<boolean>;
+    /** Hard-delete memories matching org / agent / metadata filters. */
     deleteMemoriesByFilter(filter: RepositoryFilter): Promise<number>;
+    /** Remove all memories (and side tables) for an organization. */
     clearOrganization(organization: string): Promise<number>;
+    /** List audit history events for a memory id. */
     getHistory(memoryId: string): Promise<HistoryRow[]>;
+    /** Append a history row (created / archived / compressed / updated). */
     insertHistoryEvent(event: HistoryRow): Promise<void>;
+    /** Aggregate memory counts for an organization (single-pass SQL). */
     getStats(organization: string): Promise<{
         totalMemories: number;
         activeMemories: number;
         archivedMemories: number;
         totalAgents: number;
     }>;
+    /** On-disk database file size in bytes (0 for `:memory:`). */
     getDatabaseSizeBytes(): Promise<number>;
     withTransaction<T>(fn: () => T | Promise<T>): Promise<T>;
     private tryLoadSqliteVec;
@@ -1795,6 +3301,7 @@ interface PostgresProviderOptions {
      */
     durableWrites?: boolean;
 }
+/** PostgreSQL + pgvector {@link StorageProvider} (`pg` optional peer). */
 declare class PostgresStorageProvider implements StorageProvider {
     readonly name = "postgres";
     private readonly connectionString;
@@ -1813,7 +3320,11 @@ declare class PostgresStorageProvider implements StorageProvider {
     private insertFlushScheduled;
     private insertFlushTimer;
     private insertFlushInFlight;
+    /**
+     * @param options - Connection string, pool size, and durability flags.
+     */
     constructor(options: PostgresProviderOptions);
+    /** Current pg pool occupancy stats (for diagnostics / subscribe setup). */
     getPoolStats(): {
         max: number;
         total: number;
@@ -1822,7 +3333,9 @@ declare class PostgresStorageProvider implements StorageProvider {
     };
     /** Dedicated pool accessor for LISTEN/NOTIFY subscribe backend. */
     getPool(): PgPool | null;
+    /** Open the connection pool and run migrations. */
     open(): Promise<void>;
+    /** Drain coalesced inserts and end the connection pool. */
     close(): Promise<void>;
     /**
      * Run a search query. HNSW GUCs are baked into pool startup options —
@@ -1836,24 +3349,39 @@ declare class PostgresStorageProvider implements StorageProvider {
     dropVectorIndex(): Promise<void>;
     /** Force HNSW build now (e.g. before timed recall benches). */
     ensureVectorIndex(): Promise<void>;
+    /**
+     * Create pgvector tables and HNSW index for the given dimensionality.
+     *
+     * @param dimensions - Embedding length from the configured model.
+     */
     ensureVectorSchema(dimensions: number): Promise<void>;
     private ensureVectorTables;
     /** 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).
+     */
     notifyChange(event: MemoryChangeEvent): Promise<void>;
     /**
      * 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). */
     resetOrganization(organization: string): Promise<void>;
     /**
      * Wipe all Wolbarg tables (explicit opt-in). Prefer {@link resetOrganization}.
      */
+    /** Truncate all Wolbarg tables (dev / test helper). */
     wipeAllData(): Promise<void>;
     /** Build HNSW once before the first KNN query (bulk-friendly inserts). */
     private ensureHnswIndex;
     private buildHnswIndex;
+    /** @inheritdoc StorageProvider.getEmbeddingDimensions */
     getEmbeddingDimensions(): Promise<number | null>;
+    /** @inheritdoc StorageProvider.setEmbeddingDimensions */
     setEmbeddingDimensions(dimensions: number): Promise<void>;
+    /** Insert a single memory row (coalesced under concurrent writers). */
     insertMemory(input: InsertMemoryInput): Promise<MemoryRow>;
     private clearInsertFlushTimer;
     /** Flush coalesced inserts after a turn so concurrent remember() can join. */
@@ -1861,23 +3389,34 @@ declare class PostgresStorageProvider implements StorageProvider {
     private flushInsertQueue;
     /** Single-row insert without coalescing (used by flush + batch of 1). */
     private insertMemoryImmediate;
+    /** Batch insert via unnest / COPY paths with optional HNSW deferral. */
     insertMemoriesBatch(inputs: InsertMemoryInput[]): Promise<MemoryRow[]>;
     private insertBatchPgvector;
     /** Parallel unnest when HNSW is absent; sequential when index must stay consistent. */
     private insertBatchChunked;
     private insertOneBlob;
+    /** Update memory content, metadata, embedding, and content hash. */
     updateMemory(input: UpdateMemoryInput): Promise<MemoryRow | null>;
+    /** Find an active memory by org, agent, and content hash (dedupe). */
     findActiveByContentHash(organization: string, agent: string, contentHash: string): Promise<MemoryRow | null>;
+    /** Fetch a memory row by UUID within an organization. */
     getMemoryById(id: string, organization: string): Promise<MemoryRow | null>;
+    /** Fetch a memory row by internal rowid within an organization. */
     getMemoryByRowid(rowid: number, organization: string): Promise<MemoryRow | null>;
+    /** Batch-fetch memory rows by rowids within an organization. */
     getMemoriesByRowids(rowids: number[], organization: string): Promise<Map<number, MemoryRow>>;
+    /** List memories matching repository filters with optional limit. */
     listMemories(filter: RepositoryFilter, limit?: number): Promise<MemoryRow[]>;
+    /** Scan memories matching metadata filters. */
     searchByMetadata(filter: RepositoryFilter, limit?: number): Promise<MemoryRow[]>;
+    /** Full-text keyword search via `tsvector` / GIN index. */
     searchKeyword(query: string, organization: string, topK: number): Promise<Array<{
         memoryId: string;
         score: number;
     }>>;
+    /** pgvector cosine ANN search (HNSW when index is present). */
     searchVectors(embedding: Float32Array, topK: number): Promise<VectorSearchHit[]>;
+    /** ANN search joined with memory rows and org/archived post-filters. */
     searchVectorsWithMemories(embedding: Float32Array, topK: number, organization: string, options?: {
         agent?: string;
         includeArchived?: boolean;
@@ -1885,18 +3424,26 @@ declare class PostgresStorageProvider implements StorageProvider {
         row: MemoryRow;
         distance: number;
     }>>;
+    /** Soft-archive memories (compression / forget paths). */
     archiveMemories(ids: string[], organization: string, compressedIntoId: string, archivedAt: string): Promise<string[]>;
+    /** Hard-delete a single memory by id; returns whether a row was removed. */
     deleteMemoryById(id: string, organization: string): Promise<boolean>;
+    /** Hard-delete memories matching org / agent / metadata filters. */
     deleteMemoriesByFilter(filter: RepositoryFilter): Promise<number>;
+    /** Remove all memories for an organization. */
     clearOrganization(organization: string): Promise<number>;
+    /** List audit history events for a memory id. */
     getHistory(memoryId: string): Promise<HistoryRow[]>;
+    /** Append a history row (created / archived / compressed / updated). */
     insertHistoryEvent(event: HistoryRow): Promise<void>;
+    /** Aggregate memory counts for an organization. */
     getStats(organization: string): Promise<{
         totalMemories: number;
         activeMemories: number;
         archivedMemories: number;
         totalAgents: number;
     }>;
+    /** Approximate on-disk database size in bytes (`pg_database_size`). */
     getDatabaseSizeBytes(): Promise<number>;
     withTransaction<T>(fn: () => T | Promise<T>): Promise<T>;
     private runMigrations;
@@ -1914,10 +3461,31 @@ declare class PostgresStorageProvider implements StorageProvider {
     private describe;
 }
 
+/**
+ * Create a storage provider from SQLite or PostgreSQL configuration.
+ *
+ * @param config - Storage or database config with `provider` and connection URL.
+ * @param options - Optional SQLite concurrency tuning.
+ * @param options.concurrency - Lock retry / timeout settings for SQLite writes.
+ * @returns An unopened {@link StorageProvider} — call `open()` before use.
+ * @throws {@link ConfigurationError} when URL or provider is invalid.
+ *
+ * @example
+ * ```ts
+ * const storage = createStorageProvider(
+ *   { provider: "postgres", url: process.env.DATABASE_URL! },
+ *   { concurrency: { maxRetries: 5 } },
+ * );
+ * ```
+ */
 declare function createStorageProvider(config: StorageConfig | DatabaseConfig, options?: {
     concurrency?: ConcurrencyConfig$1;
 }): StorageProvider;
-/** @deprecated Prefer {@link createStorageProvider}. */
+/**
+ * @deprecated Prefer {@link createStorageProvider}.
+ * @param config - Legacy database configuration object.
+ * @returns A {@link StorageProvider} instance.
+ */
 declare function createDatabaseProvider(config: DatabaseConfig): StorageProvider;
 
 /**
@@ -1938,18 +3506,43 @@ interface SqliteGraphProviderOptions {
     /** Optional write-concurrency tuning (same shape as memory SQLite). */
     concurrency?: ConcurrencyConfig;
 }
+/**
+ * File-backed {@link GraphProvider} using recursive SQL CTEs over `graph_nodes` / `graph_edges`.
+ */
 declare class SqliteGraphProvider implements GraphProvider {
     readonly name = "sqlite";
     private readonly dbPath;
     private readonly concurrency;
     private db;
     private opened;
+    /**
+     * @param options - Graph SQLite path and optional concurrency tuning.
+     */
     constructor(options: SqliteGraphProviderOptions);
+    /** Whether this provider supports file snapshots for checkpoint / export. */
     supportsFileSnapshot(): boolean;
+    /** Absolute graph database path, or `null` for `:memory:`. */
     getDataPath(): string | null;
+    /** Open the graph SQLite file, apply pragmas, and create schema if needed. */
     open(): Promise<void>;
+    /** Close the graph database connection. */
     close(): Promise<void>;
+    /**
+     * 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.
+     */
     linkMemories(fromId: string, toId: string, relation: string, metadata?: Record<string, unknown>): Promise<void>;
+    /**
+     * 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.
+     */
     unlinkMemories(fromId: string, toId: string, relation?: string): Promise<void>;
     /**
      * Bounded recursive CTE over `graph_edges`.
@@ -1962,14 +3555,33 @@ declare class SqliteGraphProvider implements GraphProvider {
      * re-hydrates full rows via `toMemoryRecord` from storage when possible.
      */
     getRelated(memoryId: string, options?: GetRelatedOptions): Promise<MemoryRecord[]>;
+    /**
+     * Insert or update a named entity node.
+     *
+     * @param entity - Entity name, type, and optional metadata.
+     * @returns Stable entity id ({@link entityIdFrom}).
+     */
     upsertEntity(entity: GraphEntityInput): Promise<string>;
+    /**
+     * 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.
+     */
     linkEntityToMemory(entityId: string, memoryId: string, role?: string): Promise<void>;
+    /**
+     * Remove the memory node and incident edges when a memory is hard-deleted.
+     *
+     * @param memoryId - Wolbarg memory UUID.
+     */
     deleteMemory(memoryId: string): Promise<void>;
     /**
      * Raw Cypher escape hatch — **not supported** on the SQLite graph provider.
      * Use the typed methods, or open the underlying SQLite file yourself for raw SQL.
      */
     query(_cypher: string, _params?: Record<string, unknown>): Promise<unknown>;
+    /** Lightweight connectivity and schema statistics check. */
     health(): Promise<GraphHealthResult>;
     private withTx;
     private requireDb;
@@ -1988,11 +3600,18 @@ declare class SqliteGraphProvider implements GraphProvider {
  */
 
 interface Neo4jGraphProviderOptions {
+    /** Bolt / Neo4j URI (e.g. `neo4j://localhost:7687`). */
     url: string;
+    /** Neo4j username. */
     username: string;
+    /** Neo4j password. */
     password: string;
+    /** Optional multi-database name (Neo4j 4+). */
     database?: string;
 }
+/**
+ * Networked {@link GraphProvider} backed by Neo4j (`neo4j-driver` optional peer).
+ */
 declare class Neo4jGraphProvider implements GraphProvider {
     readonly name = "neo4j";
     private readonly url;
@@ -2001,53 +3620,156 @@ declare class Neo4jGraphProvider implements GraphProvider {
     private readonly database;
     private driver;
     private opened;
+    /**
+     * @param options - Bolt URL, credentials, and optional database name.
+     */
     constructor(options: Neo4jGraphProviderOptions);
+    /** Neo4j does not support local file snapshots for checkpoint pairing. */
     supportsFileSnapshot(): boolean;
+    /** Always `null` — graph data lives in the remote Neo4j cluster. */
     getDataPath(): string | null;
+    /** Connect to Neo4j, verify connectivity, and ensure uniqueness constraints. */
     open(): Promise<void>;
+    /** Close the neo4j-driver connection. */
     close(): Promise<void>;
     private requireDriver;
     private withSession;
     private run;
+    private runOnSession;
     private ensureMemoryNode;
+    /**
+     * 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.
+     */
     linkMemories(fromId: string, toId: string, relation: string, metadata?: Record<string, unknown>): Promise<void>;
+    /**
+     * 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.
+     */
     unlinkMemories(fromId: string, toId: string, relation?: string): Promise<void>;
     /**
      * Native Neo4j variable-length path traversal.
      * Relationship filter uses RELATED.relation property for parity with Kuzu.
      */
     getRelated(memoryId: string, options?: GetRelatedOptions): Promise<MemoryRecord[]>;
+    /**
+     * MERGE an `Entity` node keyed by deterministic id.
+     *
+     * @param entity - Entity name, type, and optional metadata.
+     * @returns Stable entity id ({@link entityIdFrom}).
+     */
     upsertEntity(entity: GraphEntityInput): Promise<string>;
+    /**
+     * 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.
+     */
     linkEntityToMemory(entityId: string, memoryId: string, role?: string): Promise<void>;
+    /**
+     * DETACH DELETE the memory node and all incident relationships.
+     *
+     * @param memoryId - Wolbarg memory UUID.
+     */
     deleteMemory(memoryId: string): Promise<void>;
+    /**
+     * 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.
+     */
     query(cypher: string, params?: Record<string, unknown>): Promise<unknown>;
+    /** Verify connectivity and return server metadata when available. */
     health(): Promise<GraphHealthResult>;
 }
 
 /**
  * Database-agnostic memory persistence contract.
- * Alias of StorageProvider for the v0.3 provider architecture.
+ *
+ * Alias of {@link StorageProvider} for the v0.3+ provider architecture naming.
+ * Custom memory backends should implement {@link StorageProvider} in
+ * `sdk/src/storage/types.ts` — this type is a semantic alias only.
  */
 
-/** Memory / vector storage provider. Implementations: SQLite, PostgreSQL. */
+/**
+ * Memory / vector storage provider.
+ *
+ * Built-in implementations: {@link SqliteStorageProvider}, {@link PostgresStorageProvider}.
+ *
+ * @example
+ * ```ts
+ * import type { MemoryProvider } from "wolbarg/providers";
+ *
+ * function useStorage(provider: MemoryProvider) {
+ *   return provider.getMemoryById(id, org);
+ * }
+ * ```
+ */
 type MemoryProvider = StorageProvider;
 
 /**
- * Internal event persistence contract.
- * Distinct from MemoryDatabase / StorageProvider — telemetry never shares tables.
+ * Internal event persistence contract for telemetry storage.
+ *
+ * Distinct from {@link MemoryProvider} — telemetry MUST use separate tables/database.
  */
 
+/**
+ * Low-level event database used by {@link TelemetryProvider} implementations.
+ *
+ * Implement this interface when adding a new telemetry backend (e.g. Postgres events).
+ *
+ * @example
+ * ```ts
+ * class MyEventDb implements EventDatabase {
+ *   readonly name = "my-events";
+ *   async open() { /* migrate schema *\/ }
+ *   async close() {}
+ *   async insertEvent(input) { /* persist *\/ return { ...input, id: "...", timestamp: "..." }; }
+ *   async query(options) { return { events: [], total: 0, limit: 0, offset: 0 }; }
+ *   async getEvent(id) { return null; }
+ * }
+ * ```
+ */
 interface EventDatabase {
+    /** Backend identifier. */
     readonly name: string;
+    /** Open connection and ensure event schema. */
     open(): Promise<void>;
+    /** Close connection and flush pending writes. */
     close(): Promise<void>;
-    /** Insert one event row. */
+    /**
+     * Insert one telemetry event row.
+     * @param event - Event input (id/timestamp may be assigned by the backend).
+     */
     insertEvent(event: TelemetryEventInput): Promise<TelemetryEvent>;
-    /** Insert many events in one batch (optional optimization). */
+    /**
+     * Batch insert events (optional optimization).
+     * @param events - Non-empty event batch.
+     */
     insertEvents?(events: TelemetryEventInput[]): Promise<TelemetryEvent[]>;
+    /**
+     * Query persisted events (Studio / debugging).
+     * @param options - Filters, pagination, and sort order.
+     */
     query(options: TelemetryQuery): Promise<TelemetryQueryResult>;
+    /**
+     * Fetch a single event by id.
+     * @param id - Event UUID.
+     */
     getEvent(id: string): Promise<TelemetryEvent | null>;
-    /** Aggregate helpers used by Studio backends. */
+    /**
+     * Aggregate helpers used by Studio dashboards (optional).
+     * @param filter - Optional time and operation filters.
+     */
     countEvents?(filter?: {
         since?: string;
         operation?: string;
@@ -2070,13 +3792,24 @@ declare class SqliteEventDatabase implements EventDatabase {
     private db;
     private insertStmt;
     private columns;
+    /**
+     * @param options.url - Path to the telemetry SQLite file.
+     * @param options.readonly - Open read-only (Studio / analytics).
+     */
     constructor(options: SqliteEventDatabaseOptions);
+    /** Open the telemetry database and run schema migrations. */
     open(): Promise<void>;
+    /** Close the telemetry database connection. */
     close(): Promise<void>;
+    /** Insert one normalized telemetry event row. */
     insertEvent(input: TelemetryEventInput): Promise<TelemetryEvent>;
+    /** Insert many events in a single transaction. */
     insertEvents(inputs: TelemetryEventInput[]): Promise<TelemetryEvent[]>;
+    /** Query telemetry events with filters, sort, and pagination. */
     query(options: TelemetryQuery): Promise<TelemetryQueryResult>;
+    /** Fetch one event by primary key. */
     getEvent(id: string): Promise<TelemetryEvent | null>;
+    /** Count events optionally filtered by time and operation. */
     countEvents(filter?: {
         since?: string;
         operation?: string;
@@ -2102,12 +3835,27 @@ declare class SqliteTelemetryProvider implements TelemetryProvider {
     private flushing;
     private closed;
     private openPromise;
+    private warnedQueueDrop;
+    private warnedFlushFailure;
+    /**
+     * @param options.url - Path to the independent telemetry SQLite database file.
+     */
     constructor(options: SqliteTelemetryProviderOptions);
+    /** Open the telemetry EventDatabase (lazy — also invoked on first emit). */
     open(): Promise<void>;
+    /** Flush pending events and close the telemetry database. */
     close(): Promise<void>;
+    /**
+     * Enqueue a telemetry event for async persistence (never throws).
+     *
+     * @param event - Partial or complete {@link TelemetryEventInput}.
+     */
     emit(event: TelemetryEventInput): void;
+    /** Block until all queued events are written (or dropped on failure). */
     flush(): Promise<void>;
+    /** Query persisted telemetry events with filters and pagination. */
     query(options: TelemetryQuery): Promise<TelemetryQueryResult>;
+    /** Fetch a single telemetry event by id. */
     getEvent(id: string): Promise<TelemetryEvent | null>;
     private scheduleFlush;
     private runFlush;
@@ -2126,13 +3874,34 @@ declare class SqliteCheckpointProvider implements CheckpointProvider {
     readonly name = "sqlite";
     private readonly directory;
     private ready;
+    /**
+     * @param options.directory - Folder for `.json` metadata and `.db` snapshot files.
+     */
     constructor(options?: SqliteCheckpointProviderOptions);
+    /** Ensure the checkpoint directory exists. */
     open(): Promise<void>;
+    /** Mark the provider closed (does not delete snapshots). */
     close(): Promise<void>;
+    /**
+     * 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.
+     */
     checkpoint(name: string, sourcePath: string, options?: CreateCheckpointOptions): Promise<CheckpointMeta>;
+    /**
+     * Restore a named checkpoint over `targetPath` (replaces WAL/SHM side files).
+     *
+     * @param name - Existing checkpoint name.
+     * @param targetPath - Live memory database path to overwrite.
+     */
     rollback(name: string, targetPath: string): Promise<CheckpointMeta>;
+    /** Delete checkpoint metadata and snapshot files for `name`. */
     deleteCheckpoint(name: string): Promise<boolean>;
+    /** List all checkpoints sorted by creation time. */
     listCheckpoints(): Promise<CheckpointMeta[]>;
+    /** Load checkpoint metadata by name, or `null` if missing / corrupt. */
     getCheckpoint(name: string): Promise<CheckpointMeta | null>;
     /**
      * Consistent SQLite file backup (WAL checkpoint + backup API / copy).
@@ -2156,28 +3925,56 @@ declare class SqliteCheckpointProvider implements CheckpointProvider {
 }
 
 /**
- * Cross-platform structured logger gated by TelemetryLogLevel.
+ * Cross-platform structured logger gated by {@link TelemetryLogLevel}.
+ *
+ * Used internally by {@link TelemetryEmitter}; also exported for adapter packages.
  */
 
 declare class WolbargLogger {
     private level;
+    /** @param level - Minimum level to print (default `"info"`). */
     constructor(level?: TelemetryLogLevel);
+    /** Change the minimum log level at runtime. */
     setLevel(level: TelemetryLogLevel): void;
+    /** @returns Current minimum log level. */
     getLevel(): TelemetryLogLevel;
+    /** Log at error level. */
     error(message: string, extra?: unknown): void;
+    /** Log at warn level.
+     * @param message - Primary log line.
+     * @param extra - Optional structured payload.
+     */
     warn(message: string, extra?: unknown): void;
+    /** Log at info level.
+     * @param message - Primary log line.
+     * @param extra - Optional structured payload.
+     */
     info(message: string, extra?: unknown): void;
+    /** Log at debug level.
+     * @param message - Primary log line.
+     * @param extra - Optional structured payload.
+     */
     debug(message: string, extra?: unknown): void;
+    /** Log at trace level.
+     * @param message - Primary log line.
+     * @param extra - Optional structured payload.
+     */
     trace(message: string, extra?: unknown): void;
     private write;
 }
 
 /**
- * Trace context helpers — session_id, trace_id, parent_trace_id.
+ * Trace context helpers — `session_id`, `trace_id`, `parent_trace_id`.
+ *
+ * Used by {@link TelemetryEmitter} to correlate memory operations in Studio.
  */
+/** Distributed trace context attached to telemetry events. */
 interface TraceContext {
+    /** Wolbarg instance session id (stable for process lifetime). */
     sessionId: string;
+    /** Unique id for this operation span. */
     traceId: string;
+    /** Parent span id when nested, else `null`. */
     parentTraceId: string | null;
 }
 
@@ -2185,56 +3982,114 @@ interface TraceContext {
  * Async telemetry emitter that never blocks memory operations.
  */
 
+/** No-op telemetry provider used when observability is disabled. */
 declare class NoopTelemetryProvider implements TelemetryProvider {
     readonly name = "noop";
+    /** @inheritdoc TelemetryProvider.open */
     open(): Promise<void>;
+    /** @inheritdoc TelemetryProvider.close */
     close(): Promise<void>;
+    /** @inheritdoc TelemetryProvider.emit */
     emit(_event: TelemetryEventInput): void;
+    /** @inheritdoc TelemetryProvider.flush */
     flush(): Promise<void>;
 }
+/**
+ * Handle for an in-flight traced operation.
+ *
+ * Created by {@link TelemetryEmitter.start}. Call `success()` or `failure()`
+ * exactly once when the operation completes.
+ */
 interface OperationTraceHandle {
+    /** Distributed trace context (session, trace, parent ids). */
     context: TraceContext;
+    /** `performance.now()` at operation start. */
     startedAt: number;
+    /** Partial latency breakdown filled via {@link OperationTraceHandle.mark}. */
     latency: Partial<LatencyBreakdown>;
+    /** Start a child trace for nested operations. */
     child(operation: TelemetryOperation): OperationTraceHandle;
+    /** Record stage latency in milliseconds. */
     mark(stage: keyof Omit<LatencyBreakdown, "totalMs">, ms: number): void;
+    /** Emit a successful completion event. */
     success(fields?: Partial<TelemetryEventInput>): void;
+    /** Emit a failed completion event. */
     failure(error: unknown, fields?: Partial<TelemetryEventInput>): void;
 }
+/** Default organization injected into events when not overridden per-call. */
 interface TelemetryEmitterContext {
+    /** Organization namespace from Wolbarg constructor. */
     organization?: string | null;
 }
+/**
+ * Async telemetry emitter — never blocks memory operations.
+ *
+ * Wraps a {@link TelemetryProvider} with session/trace lifecycle helpers and
+ * configurable capture flags (queries, latency, errors, similarity scores).
+ */
 declare class TelemetryEmitter {
+    /** Stable session id for this Wolbarg instance lifetime. */
     readonly sessionId: string;
+    /** Structured logger gated by telemetry log level. */
     readonly logger: WolbargLogger;
     private provider;
     private readonly config;
     private readonly 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: TelemetryProvider | null, config?: Partial<TelemetryConfig>, context?: TelemetryEmitterContext);
+    /** Whether telemetry is enabled and backed by a non-noop provider. */
     get enabled(): boolean;
+    /** Replace the underlying telemetry provider (e.g. after lazy init). */
     setProvider(provider: TelemetryProvider): void;
+    /** Open the underlying telemetry provider when enabled. */
     open(): Promise<void>;
+    /** Flush pending events and close the telemetry provider. */
     close(): Promise<void>;
+    /** Flush pending telemetry events without closing the provider. */
     flush(): Promise<void>;
+    /**
+     * 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: TelemetryOperation, parent?: TraceContext): OperationTraceHandle;
+    /** Emit a startup telemetry event. */
     emitStartup(provider: string): void;
+    /** Emit a shutdown telemetry event. */
     emitShutdown(provider: string): void;
 }
 
 /**
- * Internal benchmark helpers for CLI / Studio later.
- * @internal
+ * Internal benchmark helpers for CLI and Studio performance tooling.
+ *
+ * @internal Exported for harness scripts — not part of the stable public API surface.
  */
+/** Single timed iteration result. */
 interface BenchmarkSample {
+    /** Benchmark scenario name. */
     name: string;
+    /** Wall-clock duration in milliseconds. */
     durationMs: number;
+    /** Whether the iteration completed without throwing. */
     ok: boolean;
+    /** Error message when `ok` is false. */
     error?: string;
 }
+/** Aggregated benchmark report with percentile summary. */
 interface BenchmarkReport {
+    /** ISO-8601 start timestamp. */
     startedAt: string;
+    /** ISO-8601 end timestamp. */
     finishedAt: string;
+    /** Raw per-iteration samples. */
     samples: BenchmarkSample[];
+    /** Rollup statistics across successful iterations. */
     summary: {
         count: number;
         ok: number;
@@ -2245,7 +4100,23 @@ interface BenchmarkReport {
         p99Ms: number;
     };
 }
+/**
+ * Run a benchmark function for a fixed number of iterations.
+ *
+ * @param name - Scenario label attached to each sample.
+ * @param iterations - Number of times to invoke `fn`.
+ * @param fn - Async or sync work to measure.
+ * @returns One {@link BenchmarkSample} per iteration (failures captured, not thrown).
+ */
 declare function runBenchmark(name: string, iterations: number, fn: () => Promise<void> | void): Promise<BenchmarkSample[]>;
+/**
+ * Summarize benchmark samples into a report with avg / p50 / p95 / p99 latencies.
+ *
+ * @param samples - Output from {@link runBenchmark}.
+ * @param startedAt - ISO start time for the run.
+ * @param finishedAt - ISO end time for the run.
+ * @returns {@link BenchmarkReport} suitable for JSON export.
+ */
 declare function summarizeBenchmark(samples: BenchmarkSample[], startedAt: string, finishedAt: string): BenchmarkReport;
 
-export { type BenchmarkReport, type BenchmarkSample, type ChatMessage, type CheckpointInfo, type CheckpointMeta, type CheckpointOptions, type CheckpointProvider, type Chunk, type ChunkingOptions, type ChunkingStrategy, type ClearOptions, type CompressOptions, type CompressResult, CompressionError, type CompressionProvider, type ConcurrencyConfig$1 as ConcurrencyConfig, ConfigurationError, type ConversationMessage, type CreateCheckpointOptions, type DatabaseConfig, DatabaseError, type DatabaseProvider, type DatabaseProviderName, type EmbeddingCacheConfig, type EmbeddingConfig, EmbeddingError, type EmbeddingProvider, type EventDatabase, type ExportResult, FixedChunkingStrategy, type ForgetByFilterOptions, type ForgetByIdOptions, type ForgetOptions, type GetRelatedOptions, GraphCheckpointNotSupportedError, type GraphConfig, type GraphDirection, type GraphEntityInput, type GraphHealthResult, type GraphInput$1 as GraphInput, type GraphProvider, HeadingChunkingStrategy, type HistoryEvent, type HistoryOptions, type HistoryResult, type HybridConfig, type ImportResult, type IngestOptions, type IngestResult, type InitOptions, InitializationError, type KeywordDocument, type KeywordSearchHit, type KeywordSearchProvider, type LatencyBreakdown, LlmCompressionProvider, type LlmConfig, type LlmProvider, MarkdownChunkingStrategy, type MemoryChangeCallback, type MemoryChangeEvent, type MemoryContent, type MemoryDedupeConfig, type MemoryDedupeStrategy, type MemoryFilter, type MemoryMetadata, MemoryNotFoundError, type MemoryProvider, type MemoryRecord, type MetadataFilter as MetaFilter, type MetadataComparison, type MetadataFilter, type MmrConfig, Neo4jGraphProvider, NoopTelemetryProvider, type OCRProvider, type OcrResult, ParagraphChunkingStrategy, type PersistedRecallExplainPayload, type PostgresDatabaseConfig, PostgresStorageProvider, ProviderNotConfiguredError, type RecallExplainResponse, type RecallExplanationHit, type RecallOptions, type RecallResult, type RememberAction, type RememberFromMessagesOptions, type RememberFromMessagesRawStrategy, type RememberOptions, type RememberResult, type RerankDocument, type RerankHit, type RerankerProvider, type RetrievalConfig, SDK_VERSION, SentenceChunkingStrategy, SqliteCheckpointProvider, type SqliteDatabaseConfig, SqliteDatabaseProvider, SqliteEventDatabase, SqliteGraphProvider, SqliteStorageProvider, SqliteTelemetryProvider, type StageSpan, type StatsResult, type StorageConfig, StorageLockedError, type StorageProvider, type StorageProviderName, type SubscribableEvent, type SubscribeFilter, type TelemetryConfig, TelemetryEmitter, type TelemetryEvent, type TelemetryEventInput, type TelemetryLogLevel, type TelemetryOperation, type TelemetryProvider, type TelemetryQuery, type TelemetryQueryResult, type TelemetryStatus, type Unsubscribe, ValidationError, type VisionProvider, type VisionResult, Wolbarg, WolbargError, WolbargLogger, type WolbargOptions, type WolbargOptionsWithLlm, type WolbargOptionsWithoutLlm, bgeReranker, bm25, cohereReranker, createChunkingStrategy, createCompressionProvider, createDatabaseProvider, createEmbeddingProvider, createLlmProvider, createStorageProvider, createTelemetryProvider, wolbarg 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$1 as wolbarg, wrapOperationError };
+export { type BenchmarkReport, type BenchmarkSample, type ChatMessage, type CheckpointInfo, type CheckpointMeta, type CheckpointOptions, type CheckpointProvider, type Chunk, type ChunkingOptions, type ChunkingStrategy, type ClearOptions, type CompressOptions, type CompressResult, CompressionError, type CompressionProvider, type ConcurrencyConfig$1 as ConcurrencyConfig, ConfigurationError, type ConversationMessage, type CreateCheckpointOptions, type DatabaseConfig, DatabaseError, type DatabaseProvider, type DatabaseProviderName, type EmbeddingCacheConfig, type EmbeddingConfig, EmbeddingError, type EmbeddingProvider, type EventDatabase, type ExportResult, FixedChunkingStrategy, type ForgetByFilterOptions, type ForgetByIdOptions, type ForgetOptions, type GetRelatedOptions, GraphCheckpointNotSupportedError, type GraphConfig, type GraphDirection, type GraphEntityInput, type GraphHealthResult, type GraphInput$1 as GraphInput, type GraphProvider, HeadingChunkingStrategy, type HistoryEvent, type HistoryOptions, type HistoryResult, type HybridConfig, type ImportResult, type IngestOptions, type IngestResult, type InitOptions, InitializationError, type KeywordDocument, type KeywordSearchHit, type KeywordSearchProvider, type LatencyBreakdown, LlmCompressionProvider, type LlmConfig, type LlmProvider, MarkdownChunkingStrategy, type MemoryChangeCallback, type MemoryChangeEvent, type MemoryContent, type MemoryDedupeConfig, type MemoryDedupeStrategy, type MemoryFilter, type MemoryMetadata, MemoryNotFoundError, type MemoryProvider, type MemoryRecord, type MetadataFilter as MetaFilter, type MetadataComparison, type MetadataFilter, type MmrConfig, Neo4jGraphProvider, NoopTelemetryProvider, type OCRProvider, type OcrResult, ParagraphChunkingStrategy, type PersistedRecallExplainPayload, type PostgresDatabaseConfig, PostgresStorageProvider, ProviderNotConfiguredError, type RecallExplainResponse, type RecallExplanationHit, type RecallOptions, type RecallResult, type RememberAction, type RememberFromMessagesOptions, type RememberFromMessagesRawStrategy, type RememberOptions, type RememberResult, type RerankDocument, type RerankHit, type RerankerProvider, type RetrievalConfig, SDK_VERSION, SentenceChunkingStrategy, SqliteCheckpointProvider, type SqliteDatabaseConfig, SqliteDatabaseProvider, SqliteEventDatabase, SqliteGraphProvider, SqliteStorageProvider, SqliteTelemetryProvider, type StageSpan, type StatsResult, type StorageConfig, StorageLockedError, type StorageProvider, type StorageProviderName, type SubscribableEvent, type SubscribeFilter, type TelemetryConfig, TelemetryEmitter, type TelemetryEvent, type TelemetryEventInput, type TelemetryLogLevel, type TelemetryOperation, type TelemetryProvider, type TelemetryQuery, type TelemetryQueryResult, type TelemetryStatus, type Unsubscribe, ValidationError, type VisionProvider, type VisionResult, Wolbarg, WolbargError, WolbargLogger, type WolbargOptions, type WolbargOptionsWithLlm, type WolbargOptionsWithoutLlm, bgeReranker, bm25, cohereReranker, createChunkingStrategy, createCompressionProvider, createDatabaseProvider, createEmbeddingProvider, createLlmProvider, createStorageProvider, createTelemetryProvider, createWolbarg, crossEncoder, geminiEmbedding, geminiVision, jinaReranker, lmStudioEmbedding, meta, neo4jGraph, ollamaEmbedding, ollamaLlm, openRouterEmbedding, openRouterLlm, openaiCompatibleEmbedding, openaiCompatibleLlm, openaiEmbedding, openaiLlm, openaiReranker, openaiVision, postgres, postgresConfig, runBenchmark, sqlite, sqliteCheckpoint, sqliteConfig, sqliteGraph, sqliteTelemetry, summarizeBenchmark, tesseract, togetherEmbedding, vllmEmbedding, wolbarg$1 as wolbarg, wrapOperationError };