Install & config guide: a vector store (Chroma)

Needed from M7 onward. A vector store is a database that finds text by meaning, not just by keyword, the engine behind RAG (giving an AI your own documents). We use Chroma: it's a single pip install, and it turns your text into searchable "embeddings" for you, with a small model it downloads once, no extra API key.

Official docs (verify they open): Chroma, https://docs.trychroma.com. (FAISS is a popular alternative but lower-level, you manage embeddings yourself. Chroma is friendlier to start with.)

Read this first: Python version

Chroma ships ready-to-install builds for Python 3.10, 3.11, and 3.12. The very newest Python releases (e.g. 3.13/3.14) often don't have builds yet for Chroma's dependencies, and the install fails trying to compile them. If you hit a build error, the fix is almost always to use Python 3.12. Check yours with python --version (or python3 --version). This is a real-world lesson: bleeding-edge Python breaks many AI libraries, pros stay one or two versions back.

Step 1: Activate your virtual environment

From your project folder (see python-venv.md):

source .venv/bin/activate        # Windows: .\.venv\Scripts\Activate.ps1

You should now see: (.venv) at the start of your prompt.

Step 2: Install Chroma

pip install chromadb

This pulls in Chroma and a small embedding model toolkit. It's a bigger download than earlier libraries, give it a minute.

You should now see: lines ending in Successfully installed chromadb-… …. If instead you see a build error mentioning pandas, numpy, or "failed to build wheel", your Python is too new, see Troubleshooting.

Step 3: Check it worked

python -c "import chromadb; print('Chroma', chromadb.__version__)"

You should now see: Chroma 1.x.x (some version number). If it prints a version, you're ready.

Step 4: Know the first-run download

The first time you add documents, Chroma downloads its small embedding model (a one-time ~80 MB). You need internet for that first run; after that it's cached and works offline.

You should now see (on first run of the app): a short one-time download message, then normal output. Later runs skip it.

Troubleshooting

Symptom	Fix
Install fails building `pandas`/`numpy`, or "failed to build wheel"	Your Python is too new. Install Python 3.12 (python.org), make a fresh venv with it (`python3.12 -m venv .venv`), activate, and `pip install chromadb` again.
`ModuleNotFoundError: chromadb`	The venv isn't active (no `(.venv)` in the prompt) or the install didn't finish. Re-activate and re-run Step 2.
First run hangs / "downloading" then errors	The one-time model download needs internet. Check your connection and run once more; it caches afterward.
Install is very slow	Normal, Chroma has several dependencies. Let it finish; it's a one-time cost.

No key needed here. Chroma embeds your text locally with the model it downloaded, so the vector store costs nothing and works offline after the first run. Your Claude API key (M4) is still what pays for the answer step in RAG.