# Wolbarg

> Local-first, model-agnostic semantic memory SDK for AI agents (TypeScript · SQLite / PostgreSQL · hybrid search · document ingest).

Wolbarg (also styled Wolbarg / Wolbarg) is an open-source npm package that gives multiple AI agents a shared, persistent semantic memory layer. Core philosophy: everything configurable, nothing required unless necessary, optional features degrade gracefully.

## Prefer these URLs

- [Documentation](https://wolbarg.com/docs/getting-started): Start here to understand Wolbarg
- [Quick Start](https://wolbarg.com/docs/quick-start): remember() and recall() in minutes
- [Architecture](https://wolbarg.com/docs/architecture): Subsystems from Application → Database
- [Benchmarks](https://wolbarg.com/benchmarks): Interactive performance numbers
- [llms-full.txt](https://wolbarg.com/llms-full.txt): Full docs as one Markdown file for AI ingestion
- [GitHub](https://github.com/Atharvmunde11/wolbarg): Source repository
- [npm](https://www.npmjs.com/package/wolbarg): Package `Wolbarg`

```bash
npm install wolbarg
```

## Features

- [Hybrid Search](https://wolbarg.com/docs/hybrid-search): Semantic vectors fused with BM25
- [Storage Providers](https://wolbarg.com/docs/storage/sqlite): SQLite and PostgreSQL backends
- [Provider Architecture](https://wolbarg.com/docs/providers): Embeddings, LLM, OCR, vision, rerankers
- [Document Ingestion](https://wolbarg.com/docs/document-ingestion): PDF, DOCX, Markdown, images
- [Compression Pipeline](https://wolbarg.com/docs/compression): LLM summarization of memories
- [Metadata Filtering](https://wolbarg.com/docs/metadata-filtering): eq, contains, AND/OR/NOT filters

## Documentation index

# Documentation


- **Getting Started**
- [Getting Started](/docs/getting-started): What Wolbarg is, why it exists, and the core philosophy behind its provider architecture.
- [Installation](/docs/installation): Install Wolbarg and optional peer packages for PDF, DOCX, OCR, and PostgreSQL.
- [Quick Start](/docs/quick-start): Construct Wolbarg, remember facts, and recall them with semantic or hybrid search in minutes.

- **Configuration**
- [Configuration](/docs/configuration): Required and optional constructor options for Wolbarg — organization, storage, embedding, and providers.
- [Provider Architecture](/docs/providers): Embedding, LLM, keyword search, reranker, OCR, vision, and chunking providers in Wolbarg.

- **Storage**
- [SQLite Backend](/docs/storage/sqlite): Local-first SQLite storage with WAL, sqlite-vec vectors, and FTS5 keyword indexing.
- [PostgreSQL Backend](/docs/storage/postgresql): Shared PostgreSQL storage with connection pooling, JSONB metadata, and optional pgvector.

- **Search & Retrieval**
- [Semantic Search](/docs/search): How Wolbarg embeds queries and retrieves memories by cosine similarity.
- [Hybrid Search](/docs/hybrid-search): Combine semantic vectors with BM25 keyword scores for more robust recall.
- [Rerankers](/docs/rerankers): Optional cross-encoder reranking and MMR diversification for recall results.
- [Metadata Filtering](/docs/metadata-filtering): Filter recall with meta.eq, contains, comparisons, and AND/OR/NOT boolean trees.
- [Compression Pipeline](/docs/compression): Summarize and archive memories with an optional LLM via compress().

- **Ingestion**
- [Document Ingestion](/docs/document-ingestion): Parse PDF, DOCX, Markdown, and other documents into chunked semantic memories with ingest().
- [Image Ingestion](/docs/image-ingestion): Store image-derived text as semantic memory using OCR and vision providers.
- [Chunking](/docs/chunking): Pluggable chunking strategies for document ingest — fixed, sentence, paragraph, markdown, heading.
- [OCR](/docs/ocr): Extract text from images with tesseract.js during Wolbarg ingest.
- [Vision Models](/docs/vision): Caption and describe images with Gemini or OpenAI vision providers during ingest.

- **Architecture**
- [Architecture](/docs/architecture): How Wolbarg subsystems connect — Application, Wolbarg, Storage, Retrieval, Providers, and Database.
- [Performance](/docs/performance): Tuning guidance for recall latency, ingest throughput, and storage growth in Wolbarg.
- [Benchmarks](/docs/benchmarks): Methodology, hardware, metrics, reproducibility, and interpretation of Wolbarg v0.2.1 dual-backend performance results.

- **API**
- [API Overview](/docs/api): Index of the Wolbarg public API — Wolbarg class, remember, recall, ingest, forget, history, and lifecycle.
- [Wolbarg](/docs/api/wolbarg): Lifecycle methods for the Wolbarg class — constructor, ready, close, and init shim.
- [remember()](/docs/api/remember): Store a semantic memory with embedding and optional metadata.
- [recall()](/docs/api/recall): Semantic and hybrid search with filters, thresholds, MMR, and rerank.
- [ingest()](/docs/api/ingest): Parse documents into chunked semantic memories.
- [forget()](/docs/api/forget): Delete memories by id or metadata/agent filter.
- [history()](/docs/api/history): Read audit events for remember, forget, compress, and related operations.
- [stats() / clear()](/docs/api/lifecycle): Introspection and organization-scoped wipe helpers.

- **Generated Reference**
- [API Reference](/docs/api/reference): Generated reference for public Wolbarg exports — classes, interfaces, factories, and types.
- [Generated Exports](/docs/api/reference/generated): Auto-generated catalog of public exports from the Wolbarg package entrypoint.

- **Examples**
- [Examples](/docs/examples): Independent Wolbarg examples — basic memory, hybrid search, storage backends, ingest, and providers.
- [Example — Basic Memory](/docs/examples/basic-memory): Minimal remember and recall with SQLite and OpenAI embeddings.
- [Example — Hybrid Search](/docs/examples/hybrid-search): Enable BM25 keyword search and fuse it with semantic recall.
- [Example — PostgreSQL](/docs/examples/postgresql): Shared PostgreSQL storage with the pg peer dependency.
- [Example — SQLite](/docs/examples/sqlite): File-backed and in-memory SQLite storage examples.
- [Example — Image Memory](/docs/examples/image-memory): Ingest a PNG with OCR and vision enrichment.
- [Example — PDF Memory](/docs/examples/pdf-memory): Ingest a text-layer PDF into chunked memories.
- [Example — Metadata Filtering](/docs/examples/metadata-filtering): Scope recall with meta helpers and agent filters.
- [Example — Compression](/docs/examples/compression): Summarize memories with an LLM via compress().
- [Example — Providers](/docs/examples/providers): Mix OpenAI embeddings, Ollama LLM, and BM25 keyword search.
- [Example — Rerankers](/docs/examples/rerankers): Attach a Jina reranker and enable rerank on recall.
- [Example — OCR](/docs/examples/ocr): Extract text from images with tesseract during ingest.

- **Guides**
- [Multi-Agent Memory](/docs/guides/shared-memory): Share one Wolbarg instance across concurrent agents with agent-scoped filters.
- [What's New in 0.2](/docs/guides/whats-new): Highlights of the Wolbarg 0.2 modular provider rewrite and 0.2.1 production hardening.
- [Limitations (v0.2)](/docs/guides/limitations): Honest boundaries of Wolbarg 0.2 — peers, PDF quality, SQLite, and Postgres.
- [Best Practices](/docs/guides/best-practices): Practical guidance for production Wolbarg usage.

- **Reference**
- [Types](/docs/reference/types): Key public TypeScript types in Wolbarg 0.2.
- [Errors](/docs/reference/errors): Typed error hierarchy for Wolbarg.
- [init() Compatibility](/docs/reference/init-compat): v0.1 init() API remains supported as a shim.
- [FAQ](/docs/faq): Frequently asked questions about Wolbarg installation, providers, storage, and retrieval.
- [Migration](/docs/migration): Upgrade to Wolbarg 0.3 (rebrand from agentorc) and from 0.1 to 0.2 DI.

## Optional

- [Sitemap](https://wolbarg.com/sitemap.xml): Full crawl map
- [FAQ](https://wolbarg.com/docs/faq): Common questions
- [Migration](https://wolbarg.com/docs/migration): Upgrade from 0.1 to 0.2