Practical guidance for production Wolbarg usage — scoping, filters, peers, lifecycle, and provider isolation.

Scope memories

Use stable agent ids and meaningful metadata keys (topic, source, collection).

Prefer metadata filters

Narrow recall with meta.* before increasing topK. Combine with hybrid search for exact token matches. Model relationships with metadata when you need structure — graph APIs were removed in 0.6.0.

Isolate providers

Keep sqlite / postgres / embedding factories in a providers/ folder. Agents import one memory client. That way switching databases is a one-file change — see Project layout.

Configure hybrid and rerank before enabling flags

Since 0.6.0, hybrid: true and rerank: true fail closed. Pass keywordSearch: bm25() and a reranker before setting those flags, or catch ValidationError / RerankError.

Peers on demand

Do not install pg / pdf-parse / mammoth / tesseract.js unless you need them. If you ingest those formats or use Postgres, peers are required.

Lifecycle

Call ready() at process start to fail fast
Always close() on shutdown
One Wolbarg instance per process / org is enough
Pass AbortSignal on long-running remember/recall when callers may cancel

Production checklist

See the full Production guide for SSL, pool sizing, backups, and troubleshooting.

Best Practices