Quivr: Your second brain in the cloud (Apache 2.0, 36k stars)

The Problem

Every knowledge worker has the same problem: the information you need lives in documents, PDFs, databases, Notion pages, Slack threads, and Google Drive files scattered across a dozen tools. Finding a specific answer means opening each tool, searching with different syntax, scanning results, and piecing together context. A single question — “What was the Q3 revenue forecast from the board meeting deck?” — can take 20 minutes of file hunting.

The RAG (Retrieval-Augmented Generation) ecosystem has exploded to solve this, but most solutions fall into one of two camps. Camp one: heavyweight enterprise platforms (Glean, Sinequa) that cost $50+/user/month and require a sales cycle. Camp two: developer frameworks (LangChain, LlamaIndex) that give you building blocks but require you to assemble the entire system yourself — document parsing, chunking, embedding, retrieval, reranking, prompt engineering, and a UI. Neither camp serves the individual developer or small team who wants a working RAG assistant in five minutes.

Dimension	Manual Document Search	LangChain (DIY)	Glean	Quivr
Time to first answer	15-30 min per query	2-5 days (build)	2-4 weeks (sales cycle)	5 minutes (pip install)
Lines of code needed	N/A	200-500	N/A	3-5
Self-host option	N/A	Yes (you build it)	No	Yes (Apache 2.0)
LLM agnostic	N/A	Yes	No (proprietary)	Yes (any provider)
Vector store choice	N/A	Yes (you wire it)	No	Yes (PGVector, Faiss, Supabase)
Document parsing	N/A	You integrate	Built-in	Built-in (MegaParse)
UI included	N/A	No (you build it)	Yes	Yes (React frontend)
Cost	$0 (time cost)	$0 (your engineering time)	$50+/user/month	$0 (self-host)
GitHub stars	N/A	98k	N/A	39k

Why this matters: The gap between “I want to chat with my documents” and “I have a working RAG system” should be measured in minutes, not weeks. Quivr closes that gap by being opinionated — it makes the 90% decisions for you (chunk size, embedding model, retrieval strategy) so you can focus on the 10% that matters (your data, your LLM, your use case). It is not as flexible as LangChain, but it is 100x faster to get running.

The Investigation

Quivr was created by Stan Girard, a French AI engineer who wanted a “second brain” that could chat with his personal knowledge base. The project launched in mid-2023, hit 10,000 GitHub stars within months, and has grown to over 39,000 stars as of mid-2026. It is now maintained by QuivrHQ, a company that also produces MegaParse (7,400 stars, document parsing) and Le Juge (RAG evaluation framework).

Finding 1: Opinionated RAG is the right default for 80% of use cases.

The RAG landscape is dominated by frameworks that give you maximum flexibility: LangChain (98k stars) has 500+ integrations but adds ~39% latency overhead versus direct API calls. LlamaIndex (38k stars) has 160+ data connectors and multiple indexing strategies but requires 2-3 days to configure for production. Both are excellent tools, but they are frameworks, not applications.

Quivr takes the opposite approach: it is an opinionated RAG engine that makes the architectural decisions for you. Default chunk size of 500 tokens with 100-token overlap. Default embedding model via the configured LLM provider. Default retrieval of top-40 chunks with Cohere reranking. These defaults are not arbitrary — they are the result of thousands of production deployments. You can override every default through YAML configuration, but you do not have to.

What this means: If you are building a custom RAG pipeline with exotic data sources or non-standard retrieval strategies, use LangChain or LlamaIndex. If you want to chat with your documents in five minutes, use Quivr. The opinionated approach is a feature, not a limitation.

Finding 2: The Brain abstraction is the right level of granularity.

Quivr’s core abstraction is the “Brain” — a curated knowledge reservoir that provides topic-specific context to the LLM. Each Brain has its own set of documents, its own retrieval configuration, and optionally its own LLM endpoint. You create one Brain for your personal notes, another for your team’s technical documentation, and another for your client’s project files.

This is a fundamentally different approach from the “one index to rule them all” pattern used by most RAG systems. By scoping each Brain to a specific knowledge domain, Quivr improves retrieval precision (the vector search only searches relevant documents) and reduces token costs (the LLM only receives context from the selected Brain). It also enables natural permission boundaries — each Brain can have its own access controls.

What this means: The Brain abstraction maps directly to how humans organize knowledge. You do not ask “what does my entire company know about X?” — you ask “what does the engineering team’s documentation say about X?” Quivr’s Brain model reflects this cognitive reality.

Finding 3: Document parsing quality is the hidden bottleneck in RAG.

Most RAG tutorials use clean, well-formatted text files. Real-world documents are PDFs with scanned pages, PowerPoint decks with embedded images, Word files with tracked changes, and Excel spreadsheets with merged cells. The quality of your RAG system is bounded by the quality of your document parser — garbage in, garbage out.

Quivr addresses this through MegaParse, its companion document parsing library. MegaParse uses a per-page heuristic: if more than 50% of a page consists of images, it uses OCR (Tesseract + Poppler). Otherwise, it falls back to fast text extraction via pdfminer.six. For complex layouts (tables, multi-column text), it offers a Vision mode that uses GPT-4o or Claude to reconstruct the document structure. In benchmarks, MegaParse Vision achieves a 0.87 similarity score against ground truth, compared to 0.59 for basic unstructured parsing.

What this means: Document parsing is not a solved problem, but MegaParse gets you 80-90% of the way there with zero configuration. For the remaining 10-20% — complex tables, handwritten annotations, multi-column layouts — the Vision mode provides a fallback that uses the LLM’s visual understanding to reconstruct the document.

The Solution

Quivr is a ~50,000-line Python/TypeScript application (Apache 2.0, 39,000+ GitHub stars) that provides a complete RAG stack: document ingestion, vector storage, retrieval, reranking, LLM orchestration, and a web UI. It runs as a set of Docker containers or as a Python library that you embed in your own application.

┌──────────────────────────────────────────────────────────────────────────────┐
│                          Quivr Architecture                                   │
│                                                                               │
│  ┌─────────────────────┐    ┌─────────────────────┐    ┌──────────────────┐  │
│  │   Document Ingestion │    │   Brain / Storage   │    │   Query & Chat   │  │
│  │   (MegaParse)       │    │                     │    │                  │  │
│  │                     │    │  ┌───────────────┐  │    │  ┌────────────┐  │  │
│  │  • PDF (OCR/Text)  │───▶│  │   Brain A     │  │───▶│  │  LLM       │  │  │
│  │  • DOCX / PPTX     │    │  │  (docs, config)│  │    │  │ (OpenAI,   │  │  │
│  │  • TXT / Markdown  │    │  └───────────────┘  │    │  │  Anthropic,│  │  │
│  │  • Images (Vision) │    │  ┌───────────────┐  │    │  │  Mistral,  │  │  │
│  │  • CSV / Excel     │    │  │   Brain B     │  │    │  │  Ollama)   │  │  │
│  │  • Notion / Drive  │    │  │  (docs, config)│  │    │  └────────────┘  │  │
│  │  • GitHub / Slack  │    │  └───────────────┘  │    │         │         │  │
│  │                     │    │                     │    │  ┌────────────┐  │  │
│  └──────────┬──────────┘    │  ┌───────────────┐  │    │  │ Reranker   │  │  │
│             │               │  │   Brain C     │  │    │  │ (Cohere /  │  │  │
│             │               │  │  (docs, config)│  │    │  │  Jina)     │  │  │
│             │               │  └───────────────┘  │    │  └────────────┘  │  │
│             │               │                     │    │         │         │  │
│             │               │  ┌───────────────┐  │    │  ┌────────────┐  │  │
│             │               │  │  Vector Store  │  │    │  │  Web UI    │  │  │
│             │               │  │ (PGVector /    │  │    │  │ (React /   │  │  │
│             │               │  │  Faiss /       │  │    │  │  Next.js)  │  │  │
│             │               │  │  Supabase)     │  │    │  └────────────┘  │  │
│             │               │  └───────────────┘  │    │                  │  │
│  ┌──────────┴──────────┐    └─────────────────────┘    └──────────────────┘  │
│  │   Workflow Engine   │                                                      │
│  │   (YAML-defined)   │                                                      │
│  │                     │                                                      │
│  │  START → filter_    │                                                      │
│  │  history → rewrite  │                                                      │
│  │  → retrieve →       │                                                      │
│  │  generate_rag → END │                                                      │
│  └─────────────────────┘                                                      │
└──────────────────────────────────────────────────────────────────────────────┘

Here is what each layer does:

• Document Ingestion (MegaParse): Parses PDFs, DOCX, PPTX, TXT, Markdown, CSV, Excel, and images into LLM-friendly text. Uses per-page OCR heuristics and optional Vision mode for complex layouts. Handles tables, headers, footers, and document structure.
• Brain / Storage: Each Brain encapsulates a set of documents, a retrieval configuration, and optionally a dedicated LLM endpoint. Documents are chunked (default 500 tokens, 100 overlap), embedded, and stored in the configured vector store (PGVector, Faiss, or Supabase).
• Query & Chat: The user asks a question against a specific Brain. The query is embedded, top-40 chunks are retrieved, reranked by Cohere (or Jina), and the top-5 are passed to the LLM with the original question. The LLM generates a grounded answer with source citations.
• Workflow Engine: A YAML-defined, node-based pipeline that orchestrates the RAG flow. Nodes include filter_history (trim conversation context), rewrite (transform query for retrieval), retrieve (vector search), and generate_rag (LLM answer). Advanced workflows add conditional edges, tool routing, and web search integration.

Setup

# Option 1: Python library (embed in your app)
pip install quivr-core

# Option 2: Docker Compose (full stack with UI)
git clone --depth 1 https://github.com/QuivrHQ/quivr.git
cd quivr
docker compose up -d

# Access the web UI at http://localhost:3000

Minimal Code Example

from quivr_core import Brain

# Create a Brain from a file — 3 lines, 30 seconds
brain = Brain.from_files(
    name="my_research_papers",
    file_paths=["./paper.pdf", "./notes.txt"],
)

# Ask a question
answer = brain.ask("What methodology did the paper use?")
print(answer)
# Output: "The paper used a randomized controlled trial with 1,200 participants..."

Custom LLM and Embedding Configuration

from quivr_core import Brain, LLMEndpoint, LLMEndpointConfig
from langchain_core.embeddings import Embeddings

# Use Mistral instead of the default OpenAI
brain = Brain.from_files(
    name="my_smart_brain",
    file_paths=["./my_first_doc.pdf", "./my_second_doc.txt"],
    llm=LLMEndpoint(
        llm_config=LLMEndpointConfig(
            model="mistral-small-latest",
            llm_base_url="https://api.mistral.ai/v1/chat/completions",
        ),
    ),
    embedder=Embeddings(size=64),
)

answer = brain.ask("Summarize the key findings.")

YAML Workflow Configuration

Quivr’s RAG pipeline is defined in YAML. Here is the standard workflow:

# basic_rag_workflow.yaml
workflow_config:
  name: "standard RAG"
  nodes:
    - name: "START"
      edges: ["filter_history"]
    - name: "filter_history"
      edges: ["rewrite"]
    - name: "rewrite"
      edges: ["retrieve"]
    - name: "retrieve"
      edges: ["generate_rag"]
    - name: "generate_rag"
      edges: ["END"]

max_history: 10

reranker_config:
  supplier: "cohere"
  model: "rerank-multilingual-v3.0"
  top_n: 5
  relevance_score_threshold: 0.01

llm_config:
  max_input_tokens: 4000
  temperature: 0.7

Load and use the config:

from quivr_core.config import RetrievalConfig

retrieval_config = RetrievalConfig.from_yaml("./basic_rag_workflow.yaml")
answer = brain.ask("What were the revenue numbers?", retrieval_config=retrieval_config)

Advanced Workflow with Web Search and Conditional Routing

# rag_with_web_search_workflow.yaml
workflow_config:
  name: "RAG with web search"
  available_tools:
    - "web search"
  nodes:
    - name: "START"
      conditional_edge:
        routing_function: "routing_split"
        conditions: ["edit_system_prompt", "filter_history"]
    - name: "edit_system_prompt"
      edges: ["filter_history"]
    - name: "filter_history"
      edges: ["dynamic_retrieve"]
    - name: "dynamic_retrieve"
      conditional_edge:
        routing_function: "tool_routing"
        conditions: ["run_tool", "generate_rag"]
    - name: "run_tool"
      edges: ["generate_rag"]
    - name: "generate_rag"
      edges: ["END"]

tools:
  - name: "cited_answer"

max_history: 10
k: 40

reranker_config:
  supplier: "cohere"
  model: "rerank-multilingual-v3.0"
  top_n: 5
  relevance_score_threshold: 0.01

llm_config:
  max_input_tokens: 8000
  temperature: 0.7

How to Use Effectively

Step 1: Install and create your first Brain

pip install quivr-core

Create a Brain from your documents:

from quivr_core import Brain

brain = Brain.from_files(
    name="quarterly_reports",
    file_paths=[
        "./Q1_report.pdf",
        "./Q2_forecast.docx",
        "./meeting_notes.txt",
    ],
)

Step 2: Configure the ingestion pipeline

For production use, control how documents are parsed and chunked:

from quivr_core.config import IngestionConfig

ingestion_config = IngestionConfig.from_yaml("./basic_ingestion_workflow.yaml")
# basic_ingestion_workflow.yaml:
#   parser_config:
#     megaparse_config:
#       strategy: "auto"
#       pdf_parser: "unstructured"
#     splitter_config:
#       chunk_size: 400
#       chunk_overlap: 100

brain = Brain.from_files(
    name="production_brain",
    file_paths=["./large_report.pdf"],
    processor_kwargs={
        "megaparse_config": ingestion_config.parser_config.megaparse_config,
        "splitter_config": ingestion_config.parser_config.splitter_config,
    },
)

Step 3: Choose your LLM provider

Quivr supports any LangChain-compatible LLM:

from quivr_core import LLMEndpoint
from langchain_openai import ChatOpenAI
from langchain_anthropic import ChatAnthropic
from langchain_ollama import ChatOllama

# OpenAI
openai_llm = LLMEndpoint(llm=ChatOpenAI(model="gpt-4o"))

# Anthropic
claude_llm = LLMEndpoint(llm=ChatAnthropic(model="claude-sonnet-4-20250514"))

# Local with Ollama
local_llm = LLMEndpoint(llm=ChatOllama(model="llama3.2:8b"))

Step 4: Use MegaParse for complex documents

For scanned PDFs, complex tables, or image-heavy documents:

from megaparse import MegaParse
from megaparse.parser.megaparse_vision import MegaParseVision
from langchain_openai import ChatOpenAI

# Auto mode (text extraction with OCR fallback)
parser = MegaParse()
result = parser.load("./scanned_report.pdf")

# Vision mode (LLM-based reconstruction for complex layouts)
vision_parser = MegaParseVision(model=ChatOpenAI(model="gpt-4o"))
result = vision_parser.convert("./complex_table_report.pdf")

Step 5: Deploy the full stack with Docker

# Clone and start
git clone --depth 1 https://github.com/QuivrHQ/quivr.git
cd quivr
docker compose up -d

# Configure environment variables
# Set your LLM API key in the Admin UI at http://localhost:3000
# Upload documents through the web interface
# Create multiple Brains for different knowledge domains

Production pitfall: The Docker Compose stack uses SQLite by default. For production, configure PostgreSQL and a proper vector store (PGVector or Supabase). SQLite works for evaluation but will not survive concurrent users or large document volumes.

Use Cases

1. Personal Knowledge Management

When you’d use this: You have a collection of research papers, technical books, meeting notes, and blog drafts. You want to ask questions across all of them without re-reading or manually tagging.

Why Quivr fits: Create a single Brain with all your documents. The Brain abstraction maps naturally to personal knowledge management — one Brain for “Research,” another for “Work Notes,” another for “Book Highlights.” The 3-line API means you can script ingestion from your note-taking app, RSS reader, or bookmark manager.

2. Team Documentation Q&A

When you’d use this: Your team has a shared Google Drive folder, a Notion workspace, and a GitHub wiki. New members spend weeks learning where information lives.

Why Quivr fits: Deploy the Docker stack, create a “Team Docs” Brain, and upload your shared documents. The web UI provides a ChatGPT-like interface that anyone on the team can use. The Brain abstraction keeps team knowledge separate from personal knowledge. Source citations in every answer teach users which document contains which information.

3. Legal Document Analysis

When you’d use this: A legal team needs to review hundreds of contracts, identify clauses that deviate from standard terms, and answer questions about specific provisions.

Why Quivr fits: MegaParse handles scanned PDFs and complex table layouts. The Vision mode reconstructs tables from contract exhibits. Create separate Brains for each client or matter. The reranker ensures the most relevant clauses are surfaced first. The configurable relevance_score_threshold (default 0.01) filters out low-confidence matches.

4. Academic Research Assistant

When you’d use this: A researcher needs to synthesize findings across 50+ papers, identify methodological patterns, and answer specific questions about experimental setups.

Why Quivr fits: Upload PDFs of all papers to a single Brain. The chunking strategy (500 tokens, 100 overlap) preserves context across section boundaries. The rewrite node transforms natural language questions into retrieval-optimized queries. The Cohere reranker prioritizes the most relevant passages. The LLM generates answers that cite specific sections of specific papers.

5. Customer-Facing Knowledge Base

When you’d use this: A SaaS company wants to provide a chat interface over their product documentation, API reference, and support articles.

Why Quivr fits: Deploy the Docker stack, create a “Product Docs” Brain, and upload your documentation. The web UI can be embedded or white-labeled. The model-agnostic LLM layer lets you use a cheap model (GPT-4o-mini, Gemini Flash) for high-volume queries and a premium model (GPT-4o, Claude Sonnet 4) for complex questions. The YAML workflow system lets you customize the retrieval strategy for your specific content types.

Cheat Sheet

Aspect	Detail
Repository	github.com/QuivrHQ/quivr
License	Apache 2.0
Language	Python (core) + TypeScript/React (frontend)
GPU Requirements	None (API-based LLMs); optional for self-hosted models via Ollama
Setup Time	5 minutes (pip install) / 15 minutes (Docker Compose)
Key Features	Brain abstraction, YAML-defined workflows, MegaParse document parsing, model-agnostic LLM, Cohere reranking, web UI, streaming, multi-lingual
Default Chunk Size	500 tokens with 100-token overlap
Default Retrieval	Top-40 chunks, reranked to top-5
Supported LLMs	OpenAI, Anthropic, Mistral, Groq, Ollama, any LangChain-compatible
Supported Vector Stores	PGVector, Faiss, Supabase
Supported File Types	PDF, DOCX, PPTX, TXT, Markdown, CSV, Excel, images (via Vision)
Common Gotchas	SQLite default in Docker (use PostgreSQL for production); forgetting to set TAVILY_API_KEY for web search; under-estimating chunk size for long documents
Best LLMs	GPT-4o (best overall), Claude Sonnet 4 (best for long context), Mistral Small (best cost/quality), Llama 3.2 8B (best local)
Cost (Self-Host)	Server costs only (~$20-100/mo on a cloud VM)
Cost (API)	LLM API costs only (~$0.01-0.05 per query depending on model)
Missing Features	No built-in permission system (single-user by default); no incremental sync for file changes; no native mobile app; no Teams/Slack integration in core

Vibe Coding Projects

Project 1: Personal Research Assistant

What it does: Install Quivr as a Python library, create a Brain with your research papers (PDFs), and build a simple CLI that accepts questions and returns grounded answers with source citations.

What you’ll learn: The Brain.from_files() API, MegaParse document parsing, the brain.ask() method, and how to configure the LLM endpoint. You will see the full RAG pipeline from document ingestion to answer generation in under 50 lines of code.

Effort: 30 minutes. No server costs (uses API-based LLM).

# research_cli.py
import sys
from quivr_core import Brain

brain = Brain.from_files(
    name="research_papers",
    file_paths=sys.argv[1:],  # Pass PDF paths as arguments
)

while True:
    question = input("\nAsk a question (or 'quit'): ")
    if question.lower() == "quit":
        break
    answer = brain.ask(question)
    print(f"\nAnswer: {answer}")

Project 2: Multi-Brain Document Q&A System

What it does: Deploy the Quivr Docker stack and create three Brains: “Engineering” (technical docs, API specs, architecture decisions), “Product” (PRDs, user research, roadmaps), and “Business” (financial reports, board decks, meeting notes). Build a simple web page that lets users select a Brain and ask questions.

What you’ll learn: Docker Compose deployment, multi-Brain management, the web UI, and how to organize knowledge domains. You will understand why the Brain abstraction matters and how to design a knowledge management system around it.

Effort: 2-3 hours. Server costs only (~$20-50/mo for a cloud VM).

Project 3: Custom Workflow with Web Search Augmentation

What it does: Configure a Quivr Brain with the advanced RAG workflow that includes web search. When a user asks a question, the system first searches the Brain’s documents, then augments the answer with web search results if the documents are insufficient. The conditional routing node decides whether web search is needed based on the retrieval relevance scores.

What you’ll learn: YAML workflow configuration, conditional edges, tool routing, the routing_split and tool_routing functions, and how to integrate external data sources (Tavily web search) into the RAG pipeline. You will understand the full power of Quivr’s workflow system.

Effort: 4-6 hours. Requires a Tavily API key (free tier available).

Problems Solved Efficiently

Problem Type	Why Quivr Fits	When to Look Elsewhere
Personal document Q&A	3-line API, instant setup, any file type	Use Obsidian + local LLM for fully offline use
Team knowledge base	Docker stack, web UI, multi-Brain	Use Danswer for permission-aware enterprise search
Research paper synthesis	MegaParse handles PDFs, reranker prioritizes relevant passages	Use LlamaIndex for complex multi-strategy indexing
Legal document review	Vision mode for scanned docs, configurable relevance threshold	Use Haystack for auditable, compliance-grade pipelines
Customer-facing docs	Model-agnostic, YAML workflows, embeddable UI	Use Vectara for managed RAG with 0.9% hallucination rate
Prototyping RAG features	Fastest path from idea to working RAG	Use LangChain for production agentic workflows
Local/offline RAG	Ollama support, self-hosted Docker	Use privateGPT for fully air-gapped deployment

Architectural Tradeoffs

What we gained:

• Opinionated defaults that work. Quivr’s default chunk size (500 tokens), overlap (100 tokens), retrieval count (40), and reranker (Cohere) are the result of thousands of production deployments. You can override them, but you do not have to. This is the single biggest time saver — you get a production-quality RAG pipeline without tuning a single parameter.
• The Brain abstraction. Scoping each Brain to a specific knowledge domain improves retrieval precision (the vector search only searches relevant documents) and reduces token costs (the LLM only receives context from the selected Brain). It also maps naturally to how humans organize knowledge.
• Model-agnostic LLM layer. Swap between OpenAI, Anthropic, Mistral, Groq, or Ollama without changing your code. This prevents vendor lock-in and lets you optimize cost per use case — use GPT-4o for complex questions, Mistral Small for routine queries, and Llama 3.2 for local/offline scenarios.
• YAML-defined workflows. The node-based pipeline is declarative, version-controllable, and inspectable. You can see exactly what the RAG pipeline does by reading the YAML file. Advanced workflows add conditional edges, tool routing, and web search without changing Python code.
• MegaParse integration. Document parsing is the hidden bottleneck in RAG, and MegaParse handles it well. The per-page OCR heuristic balances speed and accuracy. The Vision mode provides a fallback for complex layouts. Both are available with zero configuration.
• Apache 2.0 license. No restrictions on commercial use, no copyleft concerns, no dual-license traps. You can embed Quivr in a proprietary product, deploy it for internal use, or build a SaaS offering on top of it.

What we sacrificed:

• No built-in permission system. Quivr is single-user by default. There is no ACL mirroring, no RBAC, no multi-tenant isolation. If you need permission-aware enterprise search, use Danswer (Onyx) or Glean. Quivr is designed for individuals and small teams, not enterprises with compliance requirements.
• No incremental sync. Quivr does not watch files for changes. If you update a document, you must re-upload it and recreate the Brain. There is no connector framework for pulling from external sources (Confluence, Google Drive, Slack) on a schedule. This limits Quivr to static document sets.
• Smaller ecosystem than LangChain or LlamaIndex. Quivr has fewer integrations, fewer community extensions, and fewer production battle scars. If you need a connector for an obscure data source or a custom retrieval strategy, you will need to build it yourself or use a more flexible framework.
• Python-only core. The Quivr core library is Python-only. There is no TypeScript/JS SDK, no REST API for the core RAG engine (the Docker stack has a REST API for the web UI, but the Python library is the primary interface). Teams that work primarily in TypeScript will need to run a Python sidecar.
• No commercial support. QuivrHQ offers no paid support tier, no SLA, no enterprise license. If something breaks in production, you are on your own. The community Discord is active, but it is not a replacement for a support contract.
• Limited evaluation tooling. Le Juge (Quivr’s evaluation framework) has only 8 GitHub stars. It is not production-ready. If you need rigorous RAG evaluation — faithfulness scores, recall/precision metrics, A/B testing — you will need to build your own evaluation pipeline or use a dedicated tool like RAGAS or TruLens.

The real lesson: Quivr is the fastest path from “I have documents” to “I can chat with my documents.” It is not the most flexible, the most scalable, or the most feature-rich RAG tool. It is the most opinionated — and for the 80% of use cases that fit its opinionated model, that is exactly what you want. Use Quivr when you want a working RAG system in five minutes. Use LangChain or LlamaIndex when you need to build something that Quivr’s opinions do not accommodate.

Course-Style Deep Dive

How the RAG Pipeline Works Under the Hood

Quivr’s RAG pipeline is a six-stage process orchestrated by the YAML-defined workflow engine. Here is the complete flow:

1. Query Reception. The user submits a question through the web UI or the brain.ask() API. The question enters the workflow at the START node.

2. History Filtering. The filter_history node trims the conversation context to fit within the max_input_tokens limit (default 4,000 tokens, configurable). It keeps the most recent N turns (default 10) and discards older context. This prevents the LLM from being overwhelmed by long conversation histories.

3. Query Rewriting. The rewrite node transforms the user’s natural language question into a retrieval-optimized query. For example, “What did they say about the revenue forecast?” becomes “revenue forecast Q3 2025 quarterly report financial projections.” This step is critical because users ask conversational questions that do not contain the keywords needed for effective vector search. The rewrite is performed by a lightweight LLM call (typically GPT-4o-mini or a local model).

4. Retrieval. The retrieve node embeds the rewritten query using the configured embedding model (default: the LLM provider’s embedding model). It performs a vector similarity search against the Brain’s document chunks, returning the top-K chunks (default 40). The search is scoped to the selected Brain — only chunks from that Brain’s documents are searched.

5. Reranking. The retrieved chunks are passed to the reranker (default: Cohere rerank-multilingual-v3.0). The reranker scores each chunk for relevance to the original question (not the rewritten query). Only the top-N chunks (default 5) above the relevance_score_threshold (default 0.01) are passed to the LLM. This two-stage retrieval (vector search + reranking) significantly improves answer quality by filtering out chunks that are semantically similar but not actually relevant.

6. Answer Generation. The generate_rag node constructs a prompt that includes the original question, the conversation history, and the retrieved chunks. The LLM generates a grounded answer that cites specific chunks. The answer is streamed back to the user in real time.

Advanced Pattern 1: Custom Workflow with Conditional Routing

Quivr’s workflow engine supports conditional edges that route the query based on runtime conditions. Here is how the web search workflow works:

# The START node uses routing_split to detect user intent
# If the user is asking a new question (not a follow-up), it edits the system prompt
# If the user is following up, it skips directly to history filtering

# The dynamic_retrieve node uses tool_routing to decide if web search is needed
# If the reranker scores are below the threshold, it routes to run_tool (web search)
# If the reranker scores are above the threshold, it routes directly to generate_rag

The routing_split function analyzes the conversation history to determine if the user is asking a new question or following up on a previous one. The tool_routing function checks the reranker’s relevance scores — if the top chunk’s score is below a threshold, it assumes the Brain does not contain the answer and routes to web search.

This conditional routing is what makes Quivr’s advanced workflows “agentic” — the system decides at runtime whether to use its internal knowledge or fetch external information.

Advanced Pattern 2: Custom Node Development

You can extend Quivr’s workflow engine with custom nodes:

# custom_nodes.py
from quivr_core.workflow import WorkflowNode

class SentimentAnalysisNode(WorkflowNode):
    """Analyze the sentiment of the user's question before retrieval."""

    def __init__(self, name: str):
        super().__init__(name)
        self.sentiment_model = self._load_model()

    def run(self, context: dict) -> dict:
        question = context["question"]
        sentiment = self.sentiment_model.predict(question)
        context["sentiment"] = sentiment
        return context

# Register the node in your workflow YAML:
# nodes:
#   - name: "sentiment_analysis"
#     edges: ["filter_history"]

Advanced Pattern 3: Multi-Modal RAG (Upcoming)

As of mid-2026, Quivr has an open feature request (Issue #3684) for multi-modal RAG — ingesting video and audio files via Whisper transcription and Vision models. The planned architecture:

1. Audio/Video Ingestion: Whisper transcribes audio to text. The transcript is chunked and embedded like any other document.
2. Visual Frame Extraction: Key frames are extracted from video and processed by a Vision model (GPT-4o, Claude) to generate text descriptions.
3. Unified Index: Both transcripts and visual descriptions are stored in the same vector store, searchable alongside text documents.

This is not yet implemented, but the architecture is straightforward: treat audio and video as document sources that produce text (transcripts and descriptions) that feed into the existing RAG pipeline.

Production Considerations

Horizontal scaling. Quivr’s Docker stack can be scaled horizontally by running multiple API server instances behind a load balancer. The vector store (PGVector, Faiss, Supabase) is the bottleneck — ensure it is properly indexed and has sufficient resources. For high-throughput deployments, use Supabase (managed PostgreSQL with pgvector) rather than self-hosted PGVector.

LLM cost management. Each query costs one embedding call (query encoding) plus one LLM call (answer generation). At current API pricing, a query costs approximately $0.01-0.05 depending on the model. For a team of 50 users making 20 queries/day, that is $10-50/day in API costs. Use a cheaper model (GPT-4o-mini, Gemini Flash, Mistral Small) for routine queries and reserve expensive models for complex questions.

Chunk size tuning. The default chunk size of 500 tokens works well for most documents, but you should tune it for your content:

• Short documents (emails, notes, code snippets): 200-300 tokens
• Standard documents (reports, articles, papers): 500-1000 tokens
• Long documents (books, legal contracts, technical manuals): 1000-2000 tokens

The overlap should be 20-25% of the chunk size to preserve context across chunk boundaries.

Monitoring. Quivr does not ship with built-in monitoring. For production deployments, set up:

• Application monitoring: Prometheus + Grafana for API latency, error rates, and throughput
• LLM cost tracking: Track token usage per query, per Brain, per user
• Vector store health: Monitor index size, query latency, and cache hit rates
• Document freshness: Track when each document was last ingested and flag stale documents

The Results

Metric	Before Quivr	After Quivr	Improvement
Time to first RAG answer	2-5 days (build from scratch with LangChain)	5 minutes (pip install + 3 lines of code)	500-1500x faster
Lines of code for basic RAG	200-500 (LangChain)	3-5 (Quivr)	40-100x less code
Document parsing accuracy	0.59 similarity (basic unstructured)	0.87 similarity (MegaParse Vision)	47% improvement
Query latency (p50)	2-5 seconds (DIY pipeline)	1-3 seconds (optimized pipeline)	2x faster
Retrieval precision	Variable (depends on implementation)	Consistent (reranker + threshold)	Significant
LLM provider flexibility	Locked to one provider (DIY)	Any provider (swap in 1 line)	Full flexibility
Setup cost	$0 (engineering time: 2-5 days)	$0 (self-host, 5 minutes)	100x faster setup
Production deployment	1-2 weeks (Docker + infra)	15 minutes (Docker Compose)	100x faster deploy
Multi-document support	Custom implementation	Built-in (Brain abstraction)	Built-in

What this means for you: Quivr is not the most powerful RAG framework — LangChain and LlamaIndex have more integrations, more flexibility, and more production battle scars. But Quivr is the fastest path from zero to a working RAG system. If you are an individual developer, a small team, or a prototyper who wants to chat with documents today, Quivr is the right tool. If you are building a production RAG system for 10,000 users with complex data pipelines and compliance requirements, you will outgrow Quivr — but you will outgrow it faster than you would build the equivalent system from scratch.

What to Watch Out For

1. SQLite is not for production. The default Docker Compose configuration uses SQLite. It works for evaluation but will corrupt under concurrent writes. Configure PostgreSQL and PGVector before going live. The migration is straightforward but must be done before you have real data.

2. Chunk size matters more than you think. The default 500 tokens works for most documents, but if your documents have long sections (legal contracts, technical specifications), increase it to 1000-2000 tokens. If your documents are short (emails, notes), decrease it to 200-300 tokens. The wrong chunk size produces fragmented or overly broad answers.

3. The reranker threshold is a precision/recall knob. The default relevance_score_threshold of 0.01 is very permissive — almost any chunk passes. Increase it to 0.1-0.3 for higher precision (fewer irrelevant chunks, but risk of missing relevant ones). Decrease it to 0.001 for higher recall (more chunks, but more noise). Tune this based on your use case.

4. MegaParse Vision mode is slow and expensive. Each page processed by Vision mode makes an LLM API call. For a 100-page document, that is 100 API calls at $0.01-0.03 each — $1-3 per document. Use Vision mode only for pages that need it (complex tables, scanned images) and use the fast text parser for the rest.

5. No built-in document versioning. Quivr does not track document versions. If you upload a new version of a document, the old chunks remain in the vector store until you recreate the Brain. For frequently updated documents, you need a process for re-ingesting and verifying the new chunks replaced the old ones.

6. The web UI is basic. Quivr’s React frontend is functional but not polished. It provides a ChatGPT-like chat interface, document upload, and Brain management. It does not have advanced features like document preview, chunk visualization, or analytics dashboards. For a production-facing application, you will likely build your own UI on top of the Python library.

7. No streaming in the Python library (yet). The brain.ask() method blocks until the full answer is generated. For real-time streaming, you need to use the Docker stack’s REST API or build your own streaming wrapper. This is a known limitation that the Quivr team is working on.

Lesson 1: “I spent three days building a RAG pipeline with LangChain. It worked, but it was fragile — every time I changed a parameter, something broke. I switched to Quivr and had a working system in 30 minutes. The opinionated defaults are not a limitation; they are the whole point.” — Quivr user, Hacker News

Lesson 2: “MegaParse Vision mode saved me hours of manual data entry. I had a 200-page scanned report with complex tables. The Vision mode reconstructed every table perfectly. It cost $6 in API calls but saved me two days of work.” — Quivr user, Reddit

Lesson 3: “The Brain abstraction is brilliant but easy to misuse. I created one Brain with 500 documents and wondered why retrieval was slow. The answer: each Brain’s vector search searches all its documents. Split large document sets into multiple Brains by topic. My Brain with 50 documents is 10x faster than the one with 500.” — Quivr user, Discord

Advice for Getting Started

1. Start with pip install quivr-core and the 3-line example. Get a working RAG system before you worry about configuration.
2. Use the default chunk size (500 tokens) and reranker (Cohere) for your first Brain. Only tune parameters when you have a specific problem to solve.
3. Create separate Brains for different knowledge domains. One Brain per topic, not one Brain for everything.
4. Use MegaParse’s auto mode for most documents. Switch to Vision mode only for documents with complex tables or scanned pages.
5. Deploy the Docker stack only when you need the web UI or multi-user access. The Python library is sufficient for personal use.
6. Set up PostgreSQL and PGVector before going to production. SQLite is fine for prototyping but will not scale.
7. Monitor your LLM API costs. A few queries are cheap, but 1,000 queries/day on GPT-4o costs $10-30/day. Use a cheaper model for routine queries.

---

Next in the Open-Source AI Tools Mastery series: Lobe Chat