Your First Persistent Vector Store in 10 Minutes: Getting Started with Chroma

Chroma gives you a persistent, auto-embedding vector store in three commands — data survives restarts, grows with upserts, filters with metadata, and flips to a shared server without changing your app code.

What you'll be able to do after this:

• Run a persistent vector store on your laptop that survives restarts without re-indexing
• Add documents in plain text and query with natural language — Chroma handles embedding automatically using sentence-transformers
• Switch from a local disk store to a shared server mode when you need to scale, with zero changes to your application code

You've already seen pgvector (embedded in Postgres) and FAISS (in-memory C++ index). Chroma sits between them for local development: it persists to disk, has built-in embedding, and exposes a higher-level collections API — without requiring a running Postgres server.

Three client modes:

Mode	When to use
chromadb.EphemeralClient()	Testing, notebooks — data is in memory only
chromadb.PersistentClient(path="./db")	Local dev — data survives restarts
chromadb.HttpClient(host=..., port=...)	Production — shared store across services

Walk-through: build a persistent knowledge base

pip install chromadb

import chromadb

# Persistent client — data survives restarts
client = chromadb.PersistentClient(path="./knowledge-base")

# Create or open a collection
# Default embedding: sentence-transformers/all-MiniLM-L6-v2 (auto-downloaded)
collection = client.get_or_create_collection("docs")

# Add documents — Chroma embeds them automatically
collection.add(
    documents=[
        "Engineering owns the software development lifecycle and technical architecture.",
        "Product management defines the roadmap and prioritizes features based on user research.",
        "Design creates the visual language, interaction patterns, and component library.",
    ],
    ids=["eng", "pm", "design"],   # stable, unique ids required
)

print(collection.count())  # → 3

Query with natural language:

results = collection.query(
    query_texts=["who decides what features to build next?"],
    n_results=2
)
print(results["documents"])
# → [["Product management defines the roadmap...", "Engineering owns..."]]

Maintaining the knowledge base over time:

# Update a document (Chroma re-embeds automatically)
collection.update(
    ids=["pm"],
    documents=["Product management owns the roadmap and quarterly OKRs."]
)

# Upsert — add if new, update if exists
collection.upsert(
    ids=["security"],
    documents=["The security team owns threat modeling, pen testing, and incident response."]
)

# Delete a stale entry
collection.delete(ids=["design"])

Metadata filtering (scope queries to a subset):

collection.add(
    documents=["Our API is rate-limited to 100 req/s per tenant."],
    metadatas=[{"team": "infra", "updated": "2026-08"}],
    ids=["api-limits"]
)

# Filter by metadata in the query
results = collection.query(
    query_texts=["rate limits"],
    where={"team": "infra"},
    n_results=1
)

Switching to server mode:

# Start the Chroma server — same ./knowledge-base directory
chroma run --path ./knowledge-base --port 8000

# Switch the client — zero changes to the rest of your app code
client = chromadb.HttpClient(host="localhost", port=8000)
# The collection API is identical; app code doesn't need to know

The same collection.add(), collection.query(), and collection.upsert() calls work whether you're hitting an in-process store, a local disk, or a remote Chroma server — so you can prototype locally and deploy without a rewrite.

Sources: Getting Started — Chroma Docs · Usage Guide — Chroma Docs · Chroma Integrations