wolbarg 0.3.0

package/dist/index.d.cts

@@ -0,0 +1,1149 @@
+/**
+ * Metadata filter AST for advanced recall filtering.
+ */
+/** Comparison operators on a single metadata field. */
+type MetadataComparison = {
+    eq: unknown;
+} | {
+    contains: string;
+} | {
+    gt: number | string;
+} | {
+    gte: number | string;
+} | {
+    lt: number | string;
+} | {
+    lte: number | string;
+} | {
+    between: [number | string, number | string];
+};
+/** Recursive metadata filter supporting boolean combinators. */
+type MetadataFilter = {
+    field: string;
+    op: MetadataComparison;
+} | {
+    and: MetadataFilter[];
+} | {
+    or: MetadataFilter[];
+} | {
+    not: MetadataFilter;
+};
+/** Helpers for building filters fluently. */
+declare const meta: {
+    eq: (field: string, value: unknown) => MetadataFilter;
+    contains: (field: string, value: string) => MetadataFilter;
+    gt: (field: string, value: number | string) => MetadataFilter;
+    gte: (field: string, value: number | string) => MetadataFilter;
+    lt: (field: string, value: number | string) => MetadataFilter;
+    lte: (field: string, value: number | string) => MetadataFilter;
+    between: (field: string, lo: number | string, hi: number | string) => MetadataFilter;
+    and: (...filters: MetadataFilter[]) => MetadataFilter;
+    or: (...filters: MetadataFilter[]) => MetadataFilter;
+    not: (filter: MetadataFilter) => MetadataFilter;
+};
+
+/**
+ * Public configuration and domain types for Wolbarg v0.2.
+ */
+
+/** Opaque, user-defined metadata. Never validated or modified by the SDK. */
+type MemoryMetadata = Record<string, unknown>;
+/** Memory content payload. */
+interface MemoryContent {
+    /** Plain-text content used for embedding generation. */
+    text: string;
+}
+/** Supported storage / database providers. */
+type DatabaseProviderName = "sqlite" | "postgres";
+/** @deprecated Prefer `StorageProviderName`. */
+type StorageProviderName = DatabaseProviderName;
+/** SQLite database configuration. */
+interface SqliteDatabaseConfig {
+    provider: "sqlite";
+    /**
+     * Path to the SQLite database file, or `:memory:` for an in-memory database.
+     * Relative paths are resolved from `process.cwd()`.
+     */
+    connectionString: string;
+}
+/** PostgreSQL database configuration. */
+interface PostgresDatabaseConfig {
+    provider: "postgres";
+    /** Postgres connection string (e.g. `postgres://user:pass@host:5432/db`). */
+    connectionString: string;
+    /** Optional max pool size. Defaults to 10. */
+    maxPoolSize?: number;
+}
+/** Discriminated union of database configs. */
+type DatabaseConfig = SqliteDatabaseConfig | PostgresDatabaseConfig;
+/** Alias used by the constructor-based API. */
+type StorageConfig = DatabaseConfig;
+/**
+ * OpenAI-compatible embedding endpoint configuration.
+ * Works with OpenAI, Ollama, LM Studio, OpenRouter, Azure OpenAI, Gemini, etc.
+ */
+interface EmbeddingConfig {
+    /** Base URL of the OpenAI-compatible API (e.g. `https://api.openai.com/v1`). */
+    baseUrl: string;
+    /** API key sent as `Authorization: Bearer <apiKey>`. */
+    apiKey: string;
+    /** Embedding model identifier. */
+    model: string;
+    /** Optional request timeout in milliseconds. Defaults to 30_000. */
+    timeoutMs?: number;
+}
+/**
+ * OpenAI-compatible chat completion endpoint used for compression.
+ * May differ from the embedding provider.
+ */
+interface LlmConfig {
+    /** Base URL of the OpenAI-compatible API. */
+    baseUrl: string;
+    /** API key sent as `Authorization: Bearer <apiKey>`. */
+    apiKey: string;
+    /** Chat model identifier. */
+    model: string;
+    /** Sampling temperature. Defaults to 0.2. */
+    temperature?: number;
+    /** Maximum tokens for the completion. Defaults to 4096. */
+    maxTokens?: number;
+    /** Optional request timeout in milliseconds. Defaults to 60_000. */
+    timeoutMs?: number;
+}
+/** Hybrid score fusion weights. */
+interface HybridConfig {
+    /** Weight for semantic similarity. Defaults to 0.7. */
+    semanticWeight?: number;
+    /** Weight for keyword relevance. Defaults to 0.3. */
+    keywordWeight?: number;
+}
+/** MMR diversification options. */
+interface MmrConfig {
+    /** Trade-off between relevance and diversity (0–1). Defaults to 0.5. */
+    lambda?: number;
+}
+/** Retrieval pipeline defaults applied when constructing Wolbarg. */
+interface RetrievalConfig {
+    /** Default over-fetch multiplier for candidate generation. Defaults to 4. */
+    overFetchFactor?: number;
+    /** Default hybrid fusion weights. */
+    hybrid?: HybridConfig;
+    /** Default MMR lambda. */
+    mmr?: MmrConfig;
+}
+/**
+ * Full SDK initialization options (v0.1 compat + v0.2 extensions).
+ * Prefer the constructor API with `storage` / provider instances.
+ */
+interface InitOptions {
+    /** Organization namespace isolating memories within a shared database. */
+    organization: string;
+    /** Database provider configuration. */
+    database: DatabaseConfig;
+    /** Embedding provider configuration. */
+    embedding: EmbeddingConfig;
+    /**
+     * LLM provider configuration used for compression.
+     * Optional in v0.2 — required only when calling `compress`.
+     */
+    llm?: LlmConfig;
+}
+/** Input for {@link Wolbarg.remember}. */
+interface RememberOptions {
+    /** Agent identifier that owns this memory. */
+    agent: string;
+    /** Content to store and embed. */
+    content: MemoryContent;
+    /** Optional opaque metadata. Stored and returned as-is. */
+    metadata?: MemoryMetadata;
+}
+/** Optional filter applied to recall / forget / compress operations. */
+interface MemoryFilter {
+    /** Restrict results to a specific agent. */
+    agent?: string;
+    /**
+     * When `true`, include archived memories.
+     * Defaults to `false` for recall and compress.
+     */
+    includeArchived?: boolean;
+    /** Structured metadata filter (AND/OR/NOT + comparisons). */
+    metadata?: MetadataFilter;
+}
+/** Input for {@link Wolbarg.recall}. */
+interface RecallOptions {
+    /** Natural-language query to embed and search against. */
+    query: string;
+    /** Maximum number of results to return. Defaults to 5. */
+    topK?: number;
+    /**
+     * Minimum cosine similarity (0–1) required for a result.
+     * Defaults to `0` (no threshold).
+     */
+    threshold?: number;
+    /** Optional filters. */
+    filter?: MemoryFilter;
+    /**
+     * When `true`, apply the configured reranker if available.
+     * Skips silently when no reranker is configured.
+     */
+    rerank?: boolean;
+    /** Enable MMR diversification. */
+    mmr?: boolean | MmrConfig;
+    /**
+     * Enable hybrid (semantic + keyword) search when a keyword provider exists.
+     * Falls back to semantic-only when keyword search is not configured.
+     */
+    hybrid?: boolean | HybridConfig;
+}
+/** A single recalled memory with similarity score. */
+interface RecallResult {
+    id: string;
+    organization: string;
+    agent: string;
+    content: MemoryContent;
+    metadata: MemoryMetadata;
+    archived: boolean;
+    similarity: number;
+    createdAt: Date;
+    updatedAt: Date;
+}
+/** Persisted memory record (without embedding vector). */
+interface MemoryRecord {
+    id: string;
+    organization: string;
+    agent: string;
+    content: MemoryContent;
+    metadata: MemoryMetadata;
+    archived: boolean;
+    /** ID of the summary memory this was compressed into, if any. */
+    compressedInto: string | null;
+    createdAt: Date;
+    updatedAt: Date;
+}
+/** Input for {@link Wolbarg.compress}. */
+interface CompressOptions {
+    /** Agent whose memories should be compressed. */
+    agent: string;
+    /**
+     * Maximum number of active memories to include in compression.
+     * Defaults to 50.
+     */
+    limit?: number;
+}
+/** Result of a successful compression. */
+interface CompressResult {
+    /** Newly created summary memory. */
+    summary: MemoryRecord;
+    /** IDs of memories that were archived. */
+    archivedIds: string[];
+}
+/** Forget by exact memory ID. */
+interface ForgetByIdOptions {
+    id: string;
+    filter?: never;
+}
+/** Forget by filter (e.g. all memories for an agent). */
+interface ForgetByFilterOptions {
+    id?: never;
+    filter: MemoryFilter & {
+        agent: string;
+    };
+}
+/** Input for {@link Wolbarg.forget}. */
+type ForgetOptions = ForgetByIdOptions | ForgetByFilterOptions;
+/** Input for {@link Wolbarg.history}. */
+interface HistoryOptions {
+    /** Memory ID whose lineage should be returned. */
+    id: string;
+}
+/** A single event in a memory's history. */
+interface HistoryEvent {
+    id: string;
+    memoryId: string;
+    eventType: "created" | "archived" | "compressed";
+    relatedMemoryId: string | null;
+    createdAt: Date;
+}
+/** Full history response for a memory. */
+interface HistoryResult {
+    memory: MemoryRecord;
+    events: HistoryEvent[];
+}
+/** Input for {@link Wolbarg.clear}. */
+interface ClearOptions {
+    /**
+     * Must be `true` to confirm irreversible deletion of all memories
+     * in the current organization.
+     */
+    confirm: true;
+}
+/** Aggregate statistics for the current organization. */
+interface StatsResult {
+    /**
+     * Total memory rows including archived (historical) memories.
+     * Prefer {@link activeMemories} for “live set” size.
+     */
+    totalMemories: number;
+    /** Non-archived memories currently eligible for recall / compression. */
+    activeMemories: number;
+    /** Soft-archived memories retained for lineage after compression. */
+    archivedMemories: number;
+    totalAgents: number;
+    databaseSizeBytes: number;
+    embeddingModel: string;
+    /** Configured LLM model, or `null` when compression is not configured. */
+    llmModel: string | null;
+    organization: string;
+    embeddingDimensions: number;
+}
+/** Supported document input for {@link Wolbarg.ingest}. */
+interface IngestOptions {
+    /** Agent that owns the ingested chunks. */
+    agent: string;
+    /**
+     * File path, Buffer, or raw text content.
+     * When `text` is provided, parsing is skipped.
+     */
+    source: {
+        path: string;
+        mimeType?: string;
+    } | {
+        buffer: Buffer;
+        filename?: string;
+        mimeType?: string;
+    } | {
+        text: string;
+        filename?: string;
+    };
+    /** Optional metadata attached to every produced chunk memory. */
+    metadata?: MemoryMetadata;
+    /** Override chunking for this call. */
+    chunking?: {
+        strategy?: "fixed" | "sentence" | "paragraph" | "markdown" | "heading";
+        chunkSize?: number;
+        overlap?: number;
+    };
+}
+/** Result of document ingestion. */
+interface IngestResult {
+    /** Memory records created from document chunks. */
+    memories: MemoryRecord[];
+    /** Extracted text length before chunking. */
+    extractedChars: number;
+    /** Chunk count produced. */
+    chunkCount: number;
+    /** Whether OCR contributed text. */
+    usedOcr: boolean;
+    /** Whether vision contributed captions. */
+    usedVision: boolean;
+}
+
+/**
+ * Chunking strategies for document ingestion.
+ */
+interface Chunk {
+    text: string;
+    index: number;
+}
+interface ChunkingOptions {
+    chunkSize?: number;
+    overlap?: number;
+}
+interface ChunkingStrategy {
+    readonly name: string;
+    chunk(text: string, options?: ChunkingOptions): Chunk[];
+}
+declare class FixedChunkingStrategy implements ChunkingStrategy {
+    readonly name = "fixed";
+    chunk(text: string, options?: ChunkingOptions): Chunk[];
+}
+declare class SentenceChunkingStrategy implements ChunkingStrategy {
+    readonly name = "sentence";
+    chunk(text: string, options?: ChunkingOptions): Chunk[];
+}
+declare class ParagraphChunkingStrategy implements ChunkingStrategy {
+    readonly name = "paragraph";
+    chunk(text: string, options?: ChunkingOptions): Chunk[];
+}
+declare class MarkdownChunkingStrategy implements ChunkingStrategy {
+    readonly name = "markdown";
+    chunk(text: string, options?: ChunkingOptions): Chunk[];
+}
+declare class HeadingChunkingStrategy implements ChunkingStrategy {
+    readonly name = "heading";
+    chunk(text: string, options?: ChunkingOptions): Chunk[];
+}
+declare function createChunkingStrategy(name?: "fixed" | "sentence" | "paragraph" | "markdown" | "heading"): ChunkingStrategy;
+
+/**
+ * LLM provider abstractions and OpenAI-compatible chat implementation.
+ * Used exclusively for memory compression (and future ORC features).
+ */
+
+interface ChatMessage {
+    role: "system" | "user" | "assistant";
+    content: string;
+}
+/** Contract for any chat completion backend. */
+interface LlmProvider {
+    readonly model: string;
+    complete(messages: ChatMessage[]): Promise<string>;
+    /** Lightweight connectivity probe. */
+    validate(): Promise<void>;
+}
+declare function createLlmProvider(config: LlmConfig): LlmProvider;
+declare const openaiCompatibleLlm: (config: LlmConfig) => LlmProvider;
+declare const openaiLlm: (config: Omit<LlmConfig, "baseUrl"> & {
+    baseUrl?: string;
+}) => LlmProvider;
+declare const ollamaLlm: (config: Omit<LlmConfig, "baseUrl"> & {
+    baseUrl?: string;
+}) => LlmProvider;
+declare const openRouterLlm: (config: Omit<LlmConfig, "baseUrl"> & {
+    baseUrl?: string;
+}) => LlmProvider;
+
+/**
+ * Memory compression — provider-based summarization.
+ */
+
+/** Contract for memory compression backends. */
+interface CompressionProvider {
+    readonly name: string;
+    compress(memories: MemoryRecord[]): Promise<string>;
+}
+/** Default compression provider wrapping an {@link LlmProvider}. */
+declare class LlmCompressionProvider implements CompressionProvider {
+    readonly name = "llm";
+    private readonly llm;
+    constructor(llm: LlmProvider);
+    compress(memories: MemoryRecord[]): Promise<string>;
+}
+declare function createCompressionProvider(llm: LlmProvider): CompressionProvider;
+
+/**
+ * Embedding providers and named factories.
+ */
+
+/** Contract for any embedding backend. */
+interface EmbeddingProvider {
+    readonly model: string;
+    /** Produce a float embedding for the given text. */
+    embed(text: string): Promise<Float32Array>;
+    /** Optional batch embedding. SDK falls back to parallel `embed` when absent. */
+    embedBatch?(texts: string[]): Promise<Float32Array[]>;
+    /** Lightweight connectivity + dimension probe. */
+    validate(): Promise<{
+        dimensions: number;
+    }>;
+}
+declare function createEmbeddingProvider(config: EmbeddingConfig): EmbeddingProvider;
+declare const openaiCompatibleEmbedding: (config: EmbeddingConfig) => EmbeddingProvider;
+declare const openaiEmbedding: (config: Omit<EmbeddingConfig, "baseUrl"> & {
+    baseUrl?: string;
+}) => EmbeddingProvider;
+declare const ollamaEmbedding: (config: Omit<EmbeddingConfig, "baseUrl"> & {
+    baseUrl?: string;
+}) => EmbeddingProvider;
+declare const openRouterEmbedding: (config: Omit<EmbeddingConfig, "baseUrl"> & {
+    baseUrl?: string;
+}) => EmbeddingProvider;
+declare const lmStudioEmbedding: (config: Omit<EmbeddingConfig, "baseUrl"> & {
+    baseUrl?: string;
+}) => EmbeddingProvider;
+declare const geminiEmbedding: (config: Omit<EmbeddingConfig, "baseUrl"> & {
+    baseUrl?: string;
+}) => EmbeddingProvider;
+declare const togetherEmbedding: (config: Omit<EmbeddingConfig, "baseUrl"> & {
+    baseUrl?: string;
+}) => EmbeddingProvider;
+declare const vllmEmbedding: (config: Omit<EmbeddingConfig, "baseUrl"> & {
+    baseUrl?: string;
+}) => EmbeddingProvider;
+
+/**
+ * Keyword / BM25 search providers.
+ */
+interface KeywordSearchHit {
+    memoryId: string;
+    score: number;
+}
+interface KeywordDocument {
+    id: string;
+    text: string;
+}
+/** Contract for keyword / lexical search. */
+interface KeywordSearchProvider {
+    readonly name: string;
+    search(query: string, documents: KeywordDocument[], topK: number): Promise<KeywordSearchHit[]>;
+}
+/** Factory for in-memory BM25 keyword search. */
+declare function bm25(options?: {
+    k1?: number;
+    b?: number;
+}): KeywordSearchProvider;
+
+/**
+ * Optional OCR provider — extract text from images.
+ */
+interface OcrResult {
+    text: string;
+}
+interface OCRProvider {
+    readonly name: string;
+    recognize(image: Buffer, mimeType?: string): Promise<OcrResult>;
+}
+/**
+ * Placeholder Tesseract adapter.
+ * Requires optional peer packages (`tesseract.js`) when used.
+ */
+declare function tesseract(): OCRProvider;
+
+/**
+ * Reranker provider abstractions.
+ */
+interface RerankDocument {
+    id: string;
+    text: string;
+}
+interface RerankHit {
+    id: string;
+    score: number;
+}
+/** Contract for cross-encoder / API rerankers. */
+interface RerankerProvider {
+    readonly name: string;
+    rerank(query: string, documents: RerankDocument[], topK: number): Promise<RerankHit[]>;
+}
+/** Lightweight local cross-encoder proxy (OpenAI-compatible score endpoint fallback = identity order). */
+declare function crossEncoder(options: {
+    baseUrl: string;
+    apiKey: string;
+    model?: string;
+    timeoutMs?: number;
+}): RerankerProvider;
+declare function jinaReranker(options: {
+    apiKey: string;
+    model?: string;
+    timeoutMs?: number;
+}): RerankerProvider;
+declare function cohereReranker(options: {
+    apiKey: string;
+    model?: string;
+    timeoutMs?: number;
+}): RerankerProvider;
+/** Alias for BGE-style remote rerank endpoints that speak the Jina/Cohere shape. */
+declare function bgeReranker(options: {
+    apiKey: string;
+    baseUrl: string;
+    model?: string;
+    timeoutMs?: number;
+}): RerankerProvider;
+/**
+ * OpenAI chat-based reranker (no Cohere/Jina key required).
+ * Scores query–document relevance via chat completions and reorders hits.
+ */
+declare function openaiReranker(options: {
+    apiKey: string;
+    model?: string;
+    baseUrl?: string;
+    timeoutMs?: number;
+}): RerankerProvider;
+
+/**
+ * Shared provider contracts for Wolbarg v0.2.
+ */
+
+/** Row shape returned from the memories table. */
+interface MemoryRow {
+    id: string;
+    organization: string;
+    agent: string;
+    content_text: string;
+    metadata_json: string;
+    archived: number;
+    compressed_into: string | null;
+    created_at: string;
+    updated_at: string;
+    rowid?: number;
+}
+/** Row shape for memory history events. */
+interface HistoryRow {
+    id: string;
+    memory_id: string;
+    event_type: "created" | "archived" | "compressed";
+    related_memory_id: string | null;
+    created_at: string;
+}
+/** Payload for inserting a new memory. */
+interface InsertMemoryInput {
+    id: string;
+    organization: string;
+    agent: string;
+    contentText: string;
+    metadata: MemoryMetadata;
+    embedding: Float32Array;
+    createdAt: string;
+    updatedAt: string;
+}
+/** Payload for updating memory content / metadata. */
+interface UpdateMemoryInput {
+    id: string;
+    organization: string;
+    contentText?: string;
+    metadata?: MemoryMetadata;
+    embedding?: Float32Array;
+    updatedAt: string;
+}
+/** Filters used by repository queries. */
+interface RepositoryFilter {
+    organization: string;
+    agent?: string;
+    includeArchived?: boolean;
+    metadata?: MetadataFilter;
+}
+/** Semantic search hit from the vector index. */
+interface VectorSearchHit {
+    memoryRowid: number;
+    distance: number;
+}
+/**
+ * Low-level storage provider contract.
+ * Public API never depends on a specific engine.
+ */
+interface StorageProvider {
+    readonly name: string;
+    /** Open connection, enable WAL / pragmas, run migrations, prepare statements. */
+    open(): Promise<void>;
+    /** Close the underlying connection. */
+    close(): Promise<void>;
+    /** Ensure the vector table exists for the given embedding dimensionality. */
+    ensureVectorSchema(dimensions: number): Promise<void>;
+    /** Current embedding dimensionality stored in meta, or null if unset. */
+    getEmbeddingDimensions(): Promise<number | null>;
+    /** Persist embedding dimensionality in the meta table. */
+    setEmbeddingDimensions(dimensions: number): Promise<void>;
+    /** Insert a memory + embedding inside a single ACID transaction. */
+    insertMemory(input: InsertMemoryInput): Promise<MemoryRow>;
+    /** Batch insert memories + embeddings in one transaction. */
+    insertMemoriesBatch(inputs: InsertMemoryInput[]): Promise<MemoryRow[]>;
+    /** Update memory fields and optionally replace embedding. */
+    updateMemory(input: UpdateMemoryInput): Promise<MemoryRow | null>;
+    /** Fetch a memory by UUID. */
+    getMemoryById(id: string, organization: string): Promise<MemoryRow | null>;
+    /** Fetch a memory by its integer rowid. */
+    getMemoryByRowid(rowid: number, organization: string): Promise<MemoryRow | null>;
+    /**
+     * Batch fetch memories by rowids (one query). Optional — Wolbarg falls
+     * back to parallel getMemoryByRowid when absent.
+     */
+    getMemoriesByRowids?(rowids: number[], organization: string): Promise<Map<number, MemoryRow>>;
+    /** List memories matching a filter. */
+    listMemories(filter: RepositoryFilter, limit?: number): Promise<MemoryRow[]>;
+    /** Search memories by metadata filter only. */
+    searchByMetadata(filter: RepositoryFilter, limit?: number): Promise<MemoryRow[]>;
+    /** KNN search against the vector index. */
+    searchVectors(embedding: Float32Array, topK: number): Promise<VectorSearchHit[]>;
+    /**
+     * Optional: KNN + memory rows in one round-trip, org-scoped.
+     */
+    searchVectorsWithMemories?(embedding: Float32Array, topK: number, organization: string, options?: {
+        agent?: string;
+        includeArchived?: boolean;
+    }): Promise<Array<{
+        row: MemoryRow;
+        distance: number;
+    }>>;
+    /**
+     * Optional: native keyword / BM25 search (e.g. SQLite FTS5).
+     * When present, hybrid recall can skip loading the full corpus.
+     */
+    searchKeyword?(query: string, organization: string, topK: number): Promise<Array<{
+        memoryId: string;
+        score: number;
+    }>>;
+    /**
+     * Soft-archive memories and record lineage linking them to a summary.
+     * Returns the archived memory IDs.
+     */
+    archiveMemories(ids: string[], organization: string, compressedIntoId: string, archivedAt: string): Promise<string[]>;
+    /** Hard-delete a single memory and its embedding. */
+    deleteMemoryById(id: string, organization: string): Promise<boolean>;
+    /** Hard-delete memories matching a filter. Returns deleted count. */
+    deleteMemoriesByFilter(filter: RepositoryFilter): Promise<number>;
+    /** Delete every memory for an organization. Returns deleted count. */
+    clearOrganization(organization: string): Promise<number>;
+    /** History events for a memory, oldest first. */
+    getHistory(memoryId: string): Promise<HistoryRow[]>;
+    /** Append a history event. */
+    insertHistoryEvent(event: HistoryRow): Promise<void>;
+    /** Count memories / distinct agents for an organization. */
+    getStats(organization: string): Promise<{
+        totalMemories: number;
+        activeMemories: number;
+        archivedMemories: number;
+        totalAgents: number;
+    }>;
+    /** Approximate on-disk database size in bytes. */
+    getDatabaseSizeBytes(): Promise<number>;
+    /** Run `fn` inside a single ACID transaction. */
+    withTransaction<T>(fn: () => T | Promise<T>): T | Promise<T>;
+}
+/** Back-compat alias. */
+type DatabaseProvider = StorageProvider;
+
+/**
+ * Optional vision provider — captions / descriptions / entities from images.
+ */
+interface VisionResult {
+    caption: string;
+    description: string;
+    entities: string[];
+}
+interface VisionProvider {
+    readonly name: string;
+    analyze(image: Buffer, mimeType?: string): Promise<VisionResult>;
+}
+declare function geminiVision(options: {
+    apiKey: string;
+    model?: string;
+    baseUrl?: string;
+    timeoutMs?: number;
+}): VisionProvider;
+declare function openaiVision(options: {
+    apiKey: string;
+    model?: string;
+    baseUrl?: string;
+    timeoutMs?: number;
+}): VisionProvider;
+
+/**
+ * Constructor options for Wolbarg v0.2.
+ */
+
+type EmbeddingInput = EmbeddingProvider | EmbeddingConfig;
+type LlmInput = LlmProvider | LlmConfig;
+type StorageInput = StorageProvider | StorageConfig;
+interface WolbargOptionsBase {
+    /** Organization namespace isolating memories within a shared database. */
+    organization: string;
+    /** Storage provider instance or config. */
+    storage: StorageInput;
+    /** Embedding provider instance or config. */
+    embedding: EmbeddingInput;
+    /** Optional reranker — skipped when absent. */
+    reranker?: RerankerProvider;
+    /** Optional keyword search — enables hybrid recall when present. */
+    keywordSearch?: KeywordSearchProvider;
+    /** Optional OCR for image ingest. */
+    ocr?: OCRProvider;
+    /** Optional vision model for image captions. */
+    vision?: VisionProvider;
+    /** Optional compression provider (overrides llm-backed default). */
+    compression?: CompressionProvider;
+    /** Optional default chunking strategy for ingest. */
+    chunking?: ChunkingStrategy;
+    /** Optional retrieval defaults. */
+    retrieval?: RetrievalConfig;
+}
+interface WolbargOptionsWithoutLlm extends WolbargOptionsBase {
+    llm?: undefined;
+}
+interface WolbargOptionsWithLlm extends WolbargOptionsBase {
+    /** Chat model used for compression. */
+    llm: LlmInput;
+}
+type WolbargOptions = WolbargOptionsWithoutLlm | WolbargOptionsWithLlm;
+
+/**
+ * Wolbarg — modular semantic memory SDK for AI agents (v0.2).
+ *
+ * @example
+ * ```ts
+ * import { Wolbarg, sqlite, openaiEmbedding, openaiLlm } from "wolbarg";
+ *
+ * const ctx = new Wolbarg({
+ *   organization: "my-org",
+ *   storage: sqlite("./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-4.1-mini",
+ *   }),
+ * });
+ *
+ * await ctx.ready();
+ * await ctx.remember({ agent: "research", content: { text: "…" } });
+ * const hits = await ctx.recall({ query: "…", topK: 5 });
+ * ```
+ */
+
+declare class Wolbarg<HasLlm extends boolean = false> {
+    /** Compile-time capability flag — `true` when constructed with `llm`. */
+    readonly __hasLlm: HasLlm;
+    private initialized;
+    private booting;
+    private organization;
+    private storage;
+    private embedding;
+    private llm;
+    private compression;
+    private reranker;
+    private keywordSearch;
+    private ocr;
+    private vision;
+    private chunking;
+    private retrievalConfig;
+    private embeddingDimensions;
+    private readonly writeMutex;
+    /**
+     * Create an Wolbarg instance.
+     * When options are provided, providers are wired immediately and
+     * storage opens lazily on the first API call (or {@link ready}).
+     *
+     * Pass `llm` to enable {@link compress} (typed at compile time).
+     */
+    constructor(options: WolbargOptionsWithLlm);
+    constructor(options: WolbargOptionsWithoutLlm);
+    constructor();
+    /**
+     * Backwards-compatible initialization (v0.1 API).
+     * Prefer the constructor with `storage` / `embedding` / optional `llm`.
+     */
+    init(options: InitOptions): Promise<void>;
+    /** Ensure storage is open and embedding dimensions are known. */
+    ready(): Promise<void>;
+    private boot;
+    /** Store a semantic memory for an agent. */
+    remember(options: RememberOptions): Promise<MemoryRecord>;
+    /**
+     * Semantic / hybrid search over stored memories.
+     * Optional keyword, metadata, MMR, and rerank stages degrade gracefully.
+     */
+    recall(options: RecallOptions): Promise<RecallResult[]>;
+    /**
+     * Compress related memories for an agent into a single summarized memory.
+     * Only available when `llm` (or `compression`) was configured at construction.
+     */
+    compress(this: Wolbarg<true>, options: CompressOptions): Promise<CompressResult>;
+    /** @internal */
+    private runCompress;
+    /** Ingest a document: parse → OCR/vision (optional) → chunk → embed → store. */
+    ingest(options: IngestOptions): Promise<IngestResult>;
+    /** Delete memories by ID or filter. */
+    forget(options: ForgetOptions): Promise<number>;
+    /** Return the history of a memory. */
+    history(options: HistoryOptions): Promise<HistoryResult>;
+    /** Aggregate statistics for the current organization. */
+    stats(): Promise<StatsResult>;
+    /** Delete every memory in the current organization. */
+    clear(options: ClearOptions): Promise<number>;
+    /**
+     * Serialize writes for SQLite (single connection). Postgres uses a pool and
+     * per-statement atomic CTEs — locking here only serializes throughput.
+     */
+    private withWriteLock;
+    /** Close the database connection and release resources. */
+    close(): Promise<void>;
+    /** Whether providers are ready for API calls. */
+    get isInitialized(): boolean;
+    private requireReady;
+    private assertEmbeddingDimensions;
+}
+
+/**
+ * Custom error hierarchy for Wolbarg.
+ * Raw SQLite / network errors are never exposed to consumers.
+ */
+/** Base class for all Wolbarg errors. */
+declare class WolbargError extends Error {
+    readonly code: string;
+    constructor(message: string, code: string, options?: ErrorOptions);
+}
+/** Thrown when SDK initialization fails. */
+declare class InitializationError extends WolbargError {
+    constructor(message: string, options?: ErrorOptions);
+}
+/** Thrown when configuration values are missing or invalid. */
+declare class ConfigurationError extends WolbargError {
+    constructor(message: string, options?: ErrorOptions);
+}
+/** Thrown when method arguments fail validation. */
+declare class ValidationError extends WolbargError {
+    constructor(message: string, options?: ErrorOptions);
+}
+/** Thrown when a database operation fails. */
+declare class DatabaseError extends WolbargError {
+    constructor(message: string, options?: ErrorOptions);
+}
+/** Thrown when an embedding request fails. */
+declare class EmbeddingError extends WolbargError {
+    constructor(message: string, options?: ErrorOptions);
+}
+/** Thrown when compression (LLM summarization) fails. */
+declare class CompressionError extends WolbargError {
+    constructor(message: string, options?: ErrorOptions);
+}
+/** Thrown when a requested memory does not exist. */
+declare class MemoryNotFoundError extends WolbargError {
+    constructor(message: string, options?: ErrorOptions);
+}
+/**
+ * Thrown when a method requires an optional provider that was not configured.
+ * Prefer TypeScript narrowing (e.g. compress without llm) when possible.
+ */
+declare class ProviderNotConfiguredError extends ConfigurationError {
+    readonly provider: string;
+    constructor(provider: string, method: string, hint: string);
+}
+
+/**
+ * Public factory helpers for storage / providers.
+ */
+
+/** Create a SQLite storage provider from a path or `:memory:`. */
+declare function sqlite(connectionString: string): StorageProvider;
+/** Create a SQLite storage config object (for init / options). */
+declare function sqliteConfig(connectionString: string): SqliteDatabaseConfig;
+/** Create a PostgreSQL storage provider. Requires optional peer dependency `pg`. */
+declare function postgres(options: string | {
+    connectionString: string;
+    maxPoolSize?: number;
+}): StorageProvider;
+/** Create a PostgreSQL storage config object. */
+declare function postgresConfig(connectionString: string, options?: {
+    maxPoolSize?: number;
+}): PostgresDatabaseConfig;
+
+/**
+ * SQLite + sqlite-vec database provider (Node.js built-in `node:sqlite`).
+ *
+ * Responsibilities:
+ * - WAL mode + crash-safe pragmas
+ * - Automatic migrations / schema creation
+ * - Prepared statements
+ * - ACID transactions
+ * - Vector index via sqlite-vec vec0 when available
+ * - Blob + cosine fallback on unsupported platforms (e.g. win32-arm64)
+ */
+
+interface SqliteProviderOptions {
+    connectionString: string;
+}
+declare class SqliteStorageProvider implements StorageProvider {
+    readonly name = "sqlite";
+    private readonly connectionString;
+    private db;
+    private statements;
+    private vectorDimensions;
+    private vectorBackend;
+    private sqliteVecLoaded;
+    /** Hot in-process ANN for blob backend (sqlite-vec unavailable platforms). */
+    private memoryIndex;
+    private memoryIndexDirty;
+    /** Resolved absolute path (or `:memory:`) — avoid re-resolving on size checks. */
+    private resolvedPath;
+    constructor(options: SqliteProviderOptions);
+    open(): Promise<void>;
+    close(): Promise<void>;
+    ensureVectorSchema(dimensions: number): Promise<void>;
+    getEmbeddingDimensions(): Promise<number | null>;
+    setEmbeddingDimensions(dimensions: number): Promise<void>;
+    insertMemory(input: InsertMemoryInput): Promise<MemoryRow>;
+    insertMemoriesBatch(inputs: InsertMemoryInput[]): Promise<MemoryRow[]>;
+    updateMemory(input: UpdateMemoryInput): Promise<MemoryRow | null>;
+    searchByMetadata(filter: RepositoryFilter, limit?: number): Promise<MemoryRow[]>;
+    /** Keyword search via FTS5 BM25. Returns memory IDs ranked by relevance. */
+    searchKeyword(query: string, organization: string, topK: number): Promise<Array<{
+        memoryId: string;
+        score: number;
+    }>>;
+    getMemoryById(id: string, organization: string): Promise<MemoryRow | null>;
+    getMemoryByRowid(rowid: number, organization: string): Promise<MemoryRow | null>;
+    getMemoriesByRowids(rowids: number[], organization: string): Promise<Map<number, MemoryRow>>;
+    listMemories(filter: RepositoryFilter, limit?: number): Promise<MemoryRow[]>;
+    searchVectors(embedding: Float32Array, topK: number): Promise<VectorSearchHit[]>;
+    /**
+     * Org-scoped KNN + memory rows.
+     * Caller (Wolbarg.recall) already passes an overfetched topK — do not multiply again.
+     */
+    searchVectorsWithMemories(embedding: Float32Array, topK: number, organization: string, options?: {
+        agent?: string;
+        includeArchived?: boolean;
+    }): Promise<Array<{
+        row: MemoryRow;
+        distance: number;
+    }>>;
+    archiveMemories(ids: string[], organization: string, compressedIntoId: string, archivedAt: string): Promise<string[]>;
+    deleteMemoryById(id: string, organization: string): Promise<boolean>;
+    deleteMemoriesByFilter(filter: RepositoryFilter): Promise<number>;
+    clearOrganization(organization: string): Promise<number>;
+    getHistory(memoryId: string): Promise<HistoryRow[]>;
+    insertHistoryEvent(event: HistoryRow): Promise<void>;
+    getStats(organization: string): Promise<{
+        totalMemories: number;
+        activeMemories: number;
+        archivedMemories: number;
+        totalAgents: number;
+    }>;
+    getDatabaseSizeBytes(): Promise<number>;
+    withTransaction<T>(fn: () => T): T;
+    private tryLoadSqliteVec;
+    private runMigrations;
+    /**
+     * Rebuild FTS from active (non-archived) memories when counts diverge.
+     * Guarantees keyword/hybrid correctness after crashes or interrupted writes.
+     */
+    private ensureFtsConsistency;
+    private backfillFts;
+    private prepareStatements;
+    private listMemoriesSync;
+    /** Insert-only FTS row (new memory IDs never collide). */
+    private insertFtsRow;
+    private upsertFts;
+    private deleteFts;
+    private ensureVectorStorage;
+    private hydrateMemoryIndex;
+    private reprepareVectorStatements;
+    private insertEmbedding;
+    private deleteEmbedding;
+    private searchWithSqliteVec;
+    private searchWithBlobFallback;
+    private setMeta;
+    private readMetaNumber;
+    private readMetaString;
+    private readMetaNumberFromDb;
+    private resolvePath;
+    private requireDb;
+    private requireStatements;
+    private requireVectorReady;
+    private toVectorParam;
+    private describe;
+}
+/** @deprecated Prefer {@link SqliteStorageProvider}. */
+declare const SqliteDatabaseProvider: typeof SqliteStorageProvider;
+
+/**
+ * PostgreSQL storage provider with optional pgvector support.
+ * Requires the optional `pg` peer dependency.
+ *
+ * Performance design:
+ * - Per-operation pool queries (no global write lock / shared tx client race)
+ * - AsyncLocalStorage for nested transactions
+ * - Single-statement CTE inserts (no BEGIN/COMMIT for one memory)
+ * - Named prepared statements (parse/plan once per connection)
+ * - Concurrent insert coalescing into unnest batches; sequential path is immediate
+ * - COPY protocol for large ingest batches
+ * - Org-filtered ANN with adaptive overfetch + HNSW iterative scan when available
+ * - Joined vector search returning memories in one round-trip when possible
+ */
+
+interface PostgresProviderOptions {
+    connectionString: string;
+    maxPoolSize?: number;
+}
+declare class PostgresStorageProvider implements StorageProvider {
+    readonly name = "postgres";
+    private readonly connectionString;
+    private readonly maxPoolSize;
+    private pool;
+    private vectorDimensions;
+    private hasPgvector;
+    private hnswIndexEnsured;
+    private hnswCreateFailures;
+    private hasContentTsv;
+    private iterativeScanEnabled;
+    /** Coalesce concurrent insertMemory callers into one unnest batch. */
+    private insertQueue;
+    private insertFlushScheduled;
+    private insertFlushInFlight;
+    constructor(options: PostgresProviderOptions);
+    getPoolStats(): {
+        max: number;
+        total: number;
+        idle: number;
+        waiting: number;
+    };
+    open(): Promise<void>;
+    close(): Promise<void>;
+    ensureVectorSchema(dimensions: number): Promise<void>;
+    private ensureVectorTables;
+    /**
+     * 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.
+     */
+    resetOrganization(organization: string): Promise<void>;
+    /**
+     * Wipe all Wolbarg tables (explicit opt-in). Prefer {@link resetOrganization}.
+     */
+    wipeAllData(): Promise<void>;
+    /** Build HNSW once before the first KNN query (bulk-friendly inserts). */
+    private ensureHnswIndex;
+    getEmbeddingDimensions(): Promise<number | null>;
+    setEmbeddingDimensions(dimensions: number): Promise<void>;
+    insertMemory(input: InsertMemoryInput): Promise<MemoryRow>;
+    private flushInsertQueue;
+    /** Single-row insert without coalescing (used by flush + batch of 1). */
+    private insertMemoryImmediate;
+    insertMemoriesBatch(inputs: InsertMemoryInput[]): Promise<MemoryRow[]>;
+    private insertBatchPgvector;
+    /** Split large ingest batches into parallel unnest chunks (pool pipelining). */
+    private insertBatchChunked;
+    private insertOneBlob;
+    updateMemory(input: UpdateMemoryInput): Promise<MemoryRow | null>;
+    getMemoryById(id: string, organization: string): Promise<MemoryRow | null>;
+    getMemoryByRowid(rowid: number, organization: string): Promise<MemoryRow | null>;
+    getMemoriesByRowids(rowids: number[], organization: string): Promise<Map<number, MemoryRow>>;
+    listMemories(filter: RepositoryFilter, limit?: number): Promise<MemoryRow[]>;
+    searchByMetadata(filter: RepositoryFilter, limit?: number): Promise<MemoryRow[]>;
+    searchKeyword(query: string, organization: string, topK: number): Promise<Array<{
+        memoryId: string;
+        score: number;
+    }>>;
+    searchVectors(embedding: Float32Array, topK: number): Promise<VectorSearchHit[]>;
+    searchVectorsWithMemories(embedding: Float32Array, topK: number, organization: string, options?: {
+        agent?: string;
+        includeArchived?: boolean;
+    }): Promise<Array<{
+        row: MemoryRow;
+        distance: number;
+    }>>;
+    archiveMemories(ids: string[], organization: string, compressedIntoId: string, archivedAt: string): Promise<string[]>;
+    deleteMemoryById(id: string, organization: string): Promise<boolean>;
+    deleteMemoriesByFilter(filter: RepositoryFilter): Promise<number>;
+    clearOrganization(organization: string): Promise<number>;
+    getHistory(memoryId: string): Promise<HistoryRow[]>;
+    insertHistoryEvent(event: HistoryRow): Promise<void>;
+    getStats(organization: string): Promise<{
+        totalMemories: number;
+        activeMemories: number;
+        archivedMemories: number;
+        totalAgents: number;
+    }>;
+    getDatabaseSizeBytes(): Promise<number>;
+    withTransaction<T>(fn: () => T | Promise<T>): Promise<T>;
+    private runMigrations;
+    private tryEnablePgvector;
+    private insertEmbedding;
+    private deleteEmbedding;
+    private query;
+    /** Named prepared statement — parse/plan cached per pool connection. */
+    private queryNamed;
+    private mapRow;
+    private requirePool;
+    private requireVectorReady;
+    private describe;
+}
+
+/**
+ * Storage provider factory and re-exports.
+ */
+
+declare function createStorageProvider(config: StorageConfig | DatabaseConfig): StorageProvider;
+/** @deprecated Prefer {@link createStorageProvider}. */
+declare function createDatabaseProvider(config: DatabaseConfig): StorageProvider;
+
+export { type ChatMessage, type Chunk, type ChunkingOptions, type ChunkingStrategy, type ClearOptions, type CompressOptions, type CompressResult, CompressionError, type CompressionProvider, ConfigurationError, type DatabaseConfig, DatabaseError, type DatabaseProvider, type DatabaseProviderName, type EmbeddingConfig, EmbeddingError, type EmbeddingProvider, FixedChunkingStrategy, type ForgetByFilterOptions, type ForgetByIdOptions, type ForgetOptions, HeadingChunkingStrategy, type HistoryEvent, type HistoryOptions, type HistoryResult, type HybridConfig, type IngestOptions, type IngestResult, type InitOptions, InitializationError, type KeywordDocument, type KeywordSearchHit, type KeywordSearchProvider, LlmCompressionProvider, type LlmConfig, type LlmProvider, MarkdownChunkingStrategy, type MemoryContent, type MemoryFilter, type MemoryMetadata, MemoryNotFoundError, type MemoryRecord, type MetadataFilter as MetaFilter, type MetadataComparison, type MetadataFilter, type MmrConfig, type OCRProvider, type OcrResult, ParagraphChunkingStrategy, type PostgresDatabaseConfig, PostgresStorageProvider, ProviderNotConfiguredError, type RecallOptions, type RecallResult, type RememberOptions, type RerankDocument, type RerankHit, type RerankerProvider, type RetrievalConfig, SentenceChunkingStrategy, type SqliteDatabaseConfig, SqliteDatabaseProvider, SqliteStorageProvider, type StatsResult, type StorageConfig, type StorageProvider, type StorageProviderName, ValidationError, type VisionProvider, type VisionResult, Wolbarg, WolbargError, type WolbargOptions, type WolbargOptionsWithLlm, type WolbargOptionsWithoutLlm, bgeReranker, bm25, cohereReranker, createChunkingStrategy, createCompressionProvider, createDatabaseProvider, createEmbeddingProvider, createLlmProvider, createStorageProvider, crossEncoder, geminiEmbedding, geminiVision, jinaReranker, lmStudioEmbedding, meta, ollamaEmbedding, ollamaLlm, openRouterEmbedding, openRouterLlm, openaiCompatibleEmbedding, openaiCompatibleLlm, openaiEmbedding, openaiLlm, openaiReranker, openaiVision, postgres, postgresConfig, sqlite, sqliteConfig, tesseract, togetherEmbedding, vllmEmbedding };