Second Brain AI: Deploy Quivr Core v0.0.33 (2025 Guide)

If you’ve searched for second brain AI tutorials in the last year, you’ve probably hit a wall. Every guide says: clone the Quivr repo, run docker compose up, wire in Supabase, chat with your files through a Streamlit UI. Then you try it. Docker throws No such image: backend-base:latest. The frontend never comes up. Something in the Supabase migration silently fails and there’s no error worth debugging.

Those tutorials aren’t lying – they’re just outdated. Quivr shifted its center of gravity. The flagship distribution now is the quivr-core Python library, not the full-stack Docker deployment. This guide covers the current path: core-0.0.33, released Feb 4, 2025. Check the releases page before you start – newer tags may exist.

Why the Library Instead of the Stack

Quivr describes itself as “Opiniated RAG for integrating GenAI in your apps.” The old positioning was a self-hosted second-brain product. The new positioning: a ready-to-go RAG engine you drop into your own code. Same core idea – ingest documents, ask questions, get grounded answers – but you own the interface.

The library cuts the real overhead. No Supabase, no Redis, no Postgres vector container, no Next.js frontend just to prototype. You need pip install and an API key. It works with any LLM (GPT-4, Groq, Llama) and any vectorstore (PGVector, Faiss) – you’re not tied to a stack that some future release breaks.

System Requirements

Python 3.10 – that’s the hard floor (per the official docs). Everything else scales with your ambition. Cloud LLM? 8 GB RAM is fine. Running Llama locally through Ollama? Budget 16 GB minimum, and a GPU with at least 8 GB VRAM for anything above 7B parameters – those are rough estimates, not specs from the Quivr docs.

Windows works, but use WSL2. Native Windows Python plus tokenizer wheels is a fight you don’t want.

The Install (Four Real Commands)

Two packages named quivr exist on PyPI. Turns out the one simply called quivr (v0.8.1 as of this writing, per PyPI) is a Python library for Arrow data containers – completely unrelated to the second brain project. The one you want is quivr-core.

# 1. Create an isolated environment
python3 -m venv .venv
source .venv/bin/activate # Windows: .venvScriptsactivate

# 2. Install the library
pip install quivr-core

# 3. Set your API key (OpenAI shown; Anthropic/Mistral also work)
export OPENAI_API_KEY="sk-..."

# 4. Verify
python -c "from quivr_core import Brain; print('ok')"

Step 4 prints ok – you’re done. No Docker, no compose file, no waiting for Supabase migrations.

First Run: A 5-Line Second Brain

The simplest working example from the official README:

from quivr_core import Brain

brain = Brain.from_files(
 name="my_second_brain",
 file_paths=["./notes.md", "./meeting_2025.pdf"],
)

print(brain.ask("What did we decide about the Q3 roadmap?").answer)

What’s actually happening: files get parsed, chunked, embedded, stored in a vectorstore. brain.ask() runs retrieval, stuffs the top chunks into a prompt, calls your LLM. Swap the env variable and model name to use Anthropic or Mistral instead – all three are supported per the official README.

Configuration Worth Knowing

Defaults get you running. They won’t get you good answers on 500-page technical PDFs – that’s what the YAML config is for.

# basic_rag_workflow.yaml
llm_config:
 model: "gpt-4o-mini"
 temperature: 0.2
retrieval_config:
 k: 8 # chunks retrieved per query
 chunk_size: 800
 chunk_overlap: 120

from quivr_core.config import RetrievalConfig
retrieval_config = RetrievalConfig.from_yaml("basic_rag_workflow.yaml")

About k: bumping from 4 to 8 usually helps recall on longer docs. Past 12 you’re paying for tokens and handing the model off-topic chunks. Tune it against your actual questions.

Save your brain after ingestion.brain.save("./brains/my_second_brain") – then reload with Brain.load(). Re-embedding a 200 MB document set costs real money on OpenAI and real time on local models. Don’t re-index every run.

Here’s a question worth sitting with before you go further: at what point does a RAG pipeline become a crutch for not organizing your information? Quivr is good at surfacing buried answers – but if your meeting notes contradict each other, it’ll surface contradictions. Garbage in, confused answers out. The tool doesn’t fix the upstream problem.

Errors You Will Actually Hit

All of these come from the GitHub issue tracker. Not hypotheticals.

• No such image: backend-base:latest – the backend-base image is gone. GitHub Issue #2950 confirmed it: fresh Ubuntu and POP!_OS installs fail because the image can’t be pulled. Manual pull attempts also fail. The fix is to abandon docker-compose and use quivr-core directly, as shown above.
• apt-get fetch failures during Docker build – if you’re running the legacy stack and hit this after a Docker Desktop update, Issue #1544 has the answer (confirmed by a maintainer): docker system prune clears the certificate cache that the update corrupted. Not a re-clone, not a rebuild – just prune.
• Port 3000 already allocated – Grafana, other Next.js apps, anything squatting on 3000. Changing to 3002:3000 in docker-compose.yml triggers permission errors instead of fixing it (Issue #651). Kill the conflicting service. Don’t remap the port.
• ImportError: cannot import name 'Brain' – wrong package. You installed the Arrow library quivr instead of quivr-core. Run pip uninstall quivr then pip install quivr-core.
• 401 from OpenAI on first brain.ask() – the env var was set in a different shell, or your virtualenv inherited an empty value. Print os.environ.get("OPENAI_API_KEY") inside the script to confirm before debugging anything else.

Upgrading and Uninstalling

Pin your version in production. The release cadence is fast – from a version in late 2024 to core-0.0.33 in Feb 2025, there were multiple minor releases in that window. Breaking changes have shown up between minor versions. Before upgrading a working project, read the release notes for every tag between yours and the target on the releases page.

# Upgrade
pip install --upgrade quivr-core

# Pin in requirements.txt
quivr-core==0.0.33

# Uninstall
pip uninstall quivr-core

# Remove persisted brains
rm -rf ./brains

Where This Actually Fits

Here’s the honest positioning: Quivr is not a notes app. Want a polished inbox with daily review? That’s Obsidian with a chat plugin, or Notion AI. Quivr is for when you want to build that experience – a chatbot for your company handbook, a research assistant over your PDF library, a support agent grounded in your docs. It’s an engine.

“Should I use Quivr or LangChain?” Wrong question. The real split: do you want to assemble a RAG pipeline yourself or start from an opinionated default? Already built two RAG systems and know exactly where the seams are? LangChain. Haven’t? Quivr gets you to a working baseline faster – and you can replace pieces later once you know which ones don’t fit.

FAQ

Is Quivr free?

The library is open source, MIT licensed. You pay for whatever LLM and embedding provider you connect – that bill goes to OpenAI, Anthropic, Mistral, or your electricity meter if you run local models.

Can I run it entirely offline?

Yes – point it at a local model server (Ollama, LM Studio) for the LLM, use a local embedding model like sentence-transformers, and store vectors in Faiss on disk. Anecdotally, on a MacBook with Ollama running a small Llama model and a local embedding model, a brain over a few hundred markdown files answers in a few seconds per query with zero network traffic. Ingestion is the slow part – local embedding of large PDF sets takes significantly longer than using OpenAI’s API. Plan accordingly if you’re batching hundreds of documents at setup.

What happened to the old Quivr web app?

It’s not gone. The hosted version still exists at quivr.com and the repo still has the full-stack code. What shifted is which path the maintainers actively point new users toward. Most install failures reported on GitHub today trace back to 2023-era tutorials applied against the current repo layout – the stack works if you’re careful with versions, but the library is the recommended self-host path as of early 2025. This may have changed by the time you read it; check the README’s getting-started section first.

Next step: run the 5-line example above against three real files from your own workflow – a meeting note, a PDF you actually need to search, and a markdown doc. That single test tells you more about fit than any comparison table.