The-Vibe-Company/quivr

Quickstart

Requirements (Linux x8664, 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 x8664 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.

make dev      # start dependencies, run migrations, launch API + worker
make check    # docs, contracts, vet and unit tests without Docker (about 2 min); run before pushing
make verify   # make check, then end-to-end journeys on an isolated stack
make down     # stop everything, keep data (make reset also deletes volumes)

Architecture at a glance

A single quivr binary provides the api, worker and migrate commands.

• 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

What works today

Live/bulk backlog observations refresh every 15 seconds by default, with a configurable interval and rebuild/backfill estimates from progress counters (queue configuration).

Live and bulk workers group ready document commits within each receipt batch, up to sixteen distinct Records per organization. Segments-only ingestion providers can publish new content and keyword readiness together; vectors remain a separate step. The bridge initially keeps legacy journal mode. Explicit parallel activation removes organization-wide acceptance locks, with stable per-Record feed order and a safe publication horizon; concurrent Records need not follow exact commit order (rollout).

JSON logs link caller request IDs, trace/span IDs, Receipts, Records and Versions. Opt-in OpenTelemetry exports traces and metrics to an OTLP collector, carrying one trace through durable ingestion, Temporal, plugin calls and webhooks (configuration). - Local load measurement (make load) with deterministic free providers, versioned scenarios, ingestion bursts and replica failure. Reports include latency, errors, throughput and delays until documents are searchable and alerted; see Run local load tests. - Retrieval measurement with a frozen workload (make measure), and search quality on public

• 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, da
• Searches report query-model outages as retryable 503 modelunavailable, 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.
• Release images and build identity. Release-please manages alpha release PRs, versions and changelogs. Publishing a release builds signed engine and first-party plugin images on GHCR, with signed SPDX
• Declarative conformance cases: contribute generic requirements and measure them locally with

Documentation

The documentation site, docs.quivr.thevibecompany.co, is written for people who use Quivr and write plugins: an introduction, the Quickstart, core concepts, plugin guides, task guides and the reference. Its source is docs-site/; the HTTP, CLI, MCP and plugin references there are generated from the contracts.

This repository keeps the documentation for contributors, listed per reader on the start pages generated from docs/inventory.toml:

• Using Quivr: the READMEs of the contracts, the demo and the
• deployment, and the generated references.
• Writing plugins: the READMEs of the SDKs, the plugin
• contract and the first-party plugins.
• Contributing to Quivr: change this repository, as a person
• or a coding agent.