Required and optional constructor options for Wolbarg — organization, storage, embedding, providers, concurrency, embeddingCache, memory.dedupe, and AbortSignal.

What is it?

The constructor API for new Wolbarg(options) / wolbarg(options). Three options are required; everything else is optional and enables a specific capability.

Wolbarg uses constructor dependency injection so you compose only the backends you need — no global config files, no hidden services. Keep factories in a dedicated folder so swaps stay local — see Project layout.

Required

Option	Type	Description
`organization`	`string`	Namespace isolating memories in a shared database
`storage` / `database`	`StorageProvider \| StorageConfig \| DatabaseConfig`	`sqlite(...)` / `postgres(...)` or `{ provider, url }`
`embedding`	`EmbeddingProvider \| EmbeddingConfig`	Any OpenAI-compatible embedding factory or custom provider

Optional

Option	Enables
`llm`	`compress()` (typed at compile time)
`keywordSearch`	Hybrid recall — required when `hybrid: true` (fail-closed)
`reranker`	`recall({ rerank: true })` — required when `rerank: true` (fail-closed)
`ocr` / `vision`	Image ingest enrichment
`chunking`	Default ingest chunking strategy
`compression`	Custom compression provider (overrides llm default)
`retrieval`	Default hybrid / MMR / over-fetch settings
`telemetry`	Independent EventDatabase observability
`checkpoint` / `checkpointDirectory`	SQLite first-party snapshots
`concurrency`	SQLite multi-writer retries / busy_timeout
`embeddingCache`	Transparent embedding reuse (default on)
`memory.dedupe`	Write-time upsert / near-dup detection (default off)

Storage options

SQLite

sqlite("./data/memory.db")
// or
{ provider: "sqlite", url: "./data/memory.db" }

Prefer one file per organization when using export/checkpoint. See Production.

PostgreSQL

postgres({
  connectionString: process.env.DATABASE_URL!,
  schema: "wolbarg",   // optional namespaced deployment
  maxPoolSize: 20,     // default; raise only if the host allows
  // ssl: false,       // opt out of default require for remote (not recommended)
})

Non-loopback hosts without sslmode / ssl in the URL get sslmode=require
Loopback (localhost, 127.0.0.1, ::1) is left unchanged
schema creates a dedicated Postgres schema for tables, indexes, and a suffixed NOTIFY channel
Schema names: ^[A-Za-z_][A-Za-z0-9_$]*$, max 48 characters

AbortSignal

Pass signal?: AbortSignal (or AbortSignal.timeout(ms)) on:

remember / rememberFromMessages
recall
update
compress
forget

Cancellation throws CancellationError; in-flight embedding HTTP aborts.

await ctx.recall({
  query: "billing",
  signal: AbortSignal.timeout(5_000),
});

Concurrency

concurrency: {
  maxRetries?: number;      // default 5
  baseBackoffMs?: number;   // default 50
  maxBackoffMs?: number;    // default 2000
  lockTimeoutMs?: number;   // default 5000 — SQLite busy_timeout
  multiProcess?: boolean;   // longer timeouts when multiple OS processes share one file
}

Ignored for Postgres. Guide: Concurrency.

Embedding cache

embeddingCache: {
  enabled?: boolean;    // default true
  ttlMs?: number;       // optional lazy TTL
  maxEntries?: number;  // optional LRU
}

Guide: Embedding cache.

Memory dedupe

memory: {
  dedupe: {
    enabled?: boolean;              // default false
    strategy?: "exact" | "near" | "exact-or-near";
    nearThreshold?: number;         // default 0.92
    nearCandidateLimit?: number;    // default 8
  },
}

Guide: Memory upsert.

Telemetry

telemetry: {
  enabled: true,
  database: { provider: "sqlite", url: "./telemetry.db" },
  captureQueries: false, // default since 0.6.0
}

Full example

import {
  wolbarg, sqlite, openaiEmbedding, openaiLlm,
  bm25, jinaReranker, tesseract, geminiVision,
} from "wolbarg";

const ctx = 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",
  }),
  keywordSearch: bm25(),
  reranker: jinaReranker({ apiKey: process.env.JINA_API_KEY! }),
  ocr: tesseract(),
  vision: geminiVision({ apiKey: process.env.GEMINI_API_KEY! }),
  retrieval: {
    overFetchFactor: 4,
    hybrid: { semanticWeight: 0.7, keywordWeight: 0.3 },
  },
  concurrency: { maxRetries: 5, lockTimeoutMs: 5000 },
  embeddingCache: { enabled: true, maxEntries: 10_000 },
  memory: {
    dedupe: { enabled: true, strategy: "exact-or-near" },
  },
});

Lazy initialization

Storage opens and embedding dimensions are probed on the first API call, or when you call await ctx.ready(). Optional providers are not probed until used. Embedding cache wraps the provider after construction.

Configuration