How Wolbarg subsystems connect — Application, Wolbarg, Storage, Retrieval, Providers, and Database.

What is it?

The structural model of Wolbarg: a thin orchestration layer over storage, retrieval, and swappable providers.

Why does it exist?

Understanding the pipeline makes configuration and failure modes predictable.

How does it work?

Application

Your agents, tools, or server. They hold one Wolbarg instance per process / organization and call the public API. Keep provider factories in a dedicated folder — see Project layout.

Owns lifecycle (ready, close), validates options, selects providers, and exposes remember, recall, ingest, compress, forget, history, stats, clear, subscribe, and related helpers.

Memory operations

remember — embed + insert + optional keyword index update
ingest — parse → enrich → chunk → batch embed → batch insert
compress — LLM summarize + optional archive
forget — archive / delete by id or filter

Retrieval pipeline

Embed query
Vector search (+ optional BM25 when hybrid: true and keywordSearch is configured)
Metadata / agent filters
Optional MMR
Optional rerank (requires reranker; fail-closed)
Return RecallResult[]

Storage provider

Abstracts SQLite vs PostgreSQL: vectors, metadata, history, transactions, migrations.

Providers

Network or local adapters for embeddings, LLM, keyword search, rerank, OCR, vision, chunking, compression. Missing hybrid/rerank providers fail closed when those flags are set; other optional features fail cleanly per method.

Database

Physical persistence — a SQLite file with WAL / FTS5 / sqlite-vec, or PostgreSQL with JSONB / optional pgvector.

When should you read this?

Before choosing backends, tuning retrieval, or debugging hybrid/rerank errors (usually missing keywordSearch / reranker).

Architecture