quivr

**An open-source engine that turns continuous content streams into search and monitoring.**
Quivr V2 ingests content durably, makes it searchable within seconds, enriches it in
the background and lets you follow a topic over time. The core stays generic: formats,
AI models and business rules belong in plugins, so you can adapt Quivr to your domain
without forking the platform.
> **Status: evaluation stage.** The API is v0 and may change without notice. Do not
> run it in production yet.
Why Quivr V2
- **Durable before fast.** A write is acknowledged only once it is committed; outages
delay processing, they never lose or silently fail content.
- **Idempotent everywhere.** Every write carries an idempotency key. Replays return the
same result, changed replays are conflicts, and corrections create new immutable
Versions instead of overwriting history.
- **Useful early, richer later.** Text is lexically searchable as soon as it is
segmented; embeddings and other enrichments arrive afterwards without blocking it.
Hybrid search keeps keyword results while vectors are rebuilt and reports the affected Corpora.
- **Rebuildable indexes.** PostgreSQL and S3 hold the canonical data; the search index
is a projection that can be rebuilt from durable artifacts.
- **Honest search.** Every hit is rehydrated from canonical storage and re-authorized.
A dependency outage returns an error, never an empty "success".
- **Generic core, extensible edges.** Connectors, normalizers, enrichers, retrievers and
delivery channels are plugin capabilities, not core code.
Architecture at a glance
A single quivr binary provides the api, worker and migrate commands.
| Concern | Choice |
| --- | --- |
| Core | Go modular monolith (cmd/quivr, internal/…) |
| Transactional catalog | PostgreSQL 17 |
| Canonical bytes and artifacts | S3-compatible storage (SeaweedFS locally) |
| Durable orchestration | Temporal |
| Lexical and vector search | Weaviate |
| Embeddings | Local TEI serving pinned multilingual-e5-small (384 dimensions) |
| Contract | OpenAPI 3.1 in contracts/http/v0 |
| Local runtime | Docker Compose |
Quickstart
Requirements (Linux x86_64, or macOS on Apple Silicon for make dev): Go 1.27.2, Docker with Compose v2, Python 3 with venv,
Node.js 22+ and jq. The first run downloads pinned images and the E5 model (~1 GB).
make verify runs every feature's acceptance suite and one assembled monitoring
journey on an isolated stack. It removes only its own project, even after a
failure or Ctrl+C. It then prints the path of a report.md that names any failed
step, the pinned versions and the dependency inventory. It runs on Linux x86_64
only, as in CI; see the remaining limits.
make dev prints the API address and the path of a generated config.json holding
throwaway local keys; eval "$(make -s env)" exports the address, a key and a webhook
destination. Then follow the Quickstart:
create a Corpus, add an article, search it and get an alert, with commands that
make verify replays against a real stack.
For a browser UI over the same API, run make demo and open http://127.0.0.1:5183
(see quivr-search/).
What works today
- Run Quivr on one machine from release images with one Compose file, CPU embeddings, persistent storage and an optional demo interface.
- Run the vector index on a dedicated host with authenticated HTTPS, a persistent data disk, and an idempotent Azure CLI provisioning example.
- Reset and reload an installation from private JSON declarations, with a preview and idempotent public API replay.
- Choose an embedding model for local inference, your own model server or a hosted API, with rebuild requirements and execution-only tuning. Run a large import covers bulk workers, provider capacity, database sizing and queue monitoring.
- Searches report query-model outages as retryable 503 model_unavailable, separately from overload and other search dependency failures. See Search errors.
- Worker autoscaling follows the bulk or live queue backlog, with KEDA, the quivr-autoscaler binary (Kubernetes or Railway) or by hand. Live workers keep separate capacity.
- Rolling application upgrades use additive schema expansions; destructive cleanup
runs only with quivr migrate --contract. API and worker retry performance-index
builds in the background, so their busy index builds do not delay startup. An
older binary's index build can still hold the migration lock until it finishes
or is stopped. CI checks the merge-base binary against
expansions. See Upgrade Quivr.