Vector Stores Guide¶
Copyright 2026 Firefly Software Foundation. Licensed under the Apache License 2.0.
The Vector Stores module provides pluggable storage and retrieval backends for embedding vectors. It ships six backends -- in-memory, ChromaDB, Pinecone, Qdrant, PostgreSQL/pgvector, and sqlite-vec -- behind a unified API for upserting, searching, and deleting documents, plus a tenant/workspace-scoped wrapper. Applications must authorize scopes and qualify each backend's isolation behavior.
Architecture¶
graph TD
VP[VectorStoreProtocol] --> BVS[BaseVectorStore]
BVS --> IM[InMemoryVectorStore]
BVS --> CH[ChromaVectorStore]
BVS --> PC[PineconeVectorStore]
BVS --> QD[QdrantVectorStore]
BVS --> PG[PgVectorVectorStore]
BVS --> SV[SqliteVecVectorStore]
REG[VectorStoreRegistry] --> VP
BVS --> |auto-embed| EMB[EmbeddingProtocol]
TS[TenantScopedVectorStore] --> |wraps| VP
- VectorStoreProtocol -- Duck-typed protocol with
upsert(),search(),search_text(),delete(). - BaseVectorStore -- Abstract base providing auto-embedding,
search_textconvenience, and error wrapping. - Concrete Backends -- Backend-specific implementations that override
_upsert(),_search(),_delete(). - VectorStoreRegistry -- Named registry for managing multiple store instances.
- TenantScopedVectorStore -- Requires
(tenant_id, workspace_id)and maps that scope to a backend namespace.
Quick Start¶
from fireflyframework_agentic.embeddings.providers import OpenAIEmbedder
from fireflyframework_agentic.vectorstores import InMemoryVectorStore, VectorDocument
# Create a store with auto-embedding
embedder = OpenAIEmbedder()
store = InMemoryVectorStore(embedder=embedder)
# Upsert documents (auto-embeds if embedding is None)
docs = [
VectorDocument(id="1", text="Python is great for AI"),
VectorDocument(id="2", text="JavaScript runs in browsers"),
VectorDocument(id="3", text="Rust is fast and safe"),
]
await store.upsert(docs)
# Search by text (embeds the query, then searches)
results = await store.search_text("programming languages for machine learning", top_k=2)
for r in results:
print(f"{r.document.text} (score: {r.score:.3f})")
Backends¶
In-Memory¶
Zero-dependency, brute-force cosine similarity. Ideal for development and testing.
from fireflyframework_agentic.vectorstores import InMemoryVectorStore
store = InMemoryVectorStore(embedder=my_embedder)
No extra install required.
ChromaDB¶
from fireflyframework_agentic.vectorstores import ChromaVectorStore
# Ephemeral (in-process)
store = ChromaVectorStore(collection_name="my_docs", embedder=my_embedder)
# With a persistent/remote client
import chromadb
client = chromadb.HttpClient(host="localhost", port=8000)
store = ChromaVectorStore(collection_name="my_docs", client=client, embedder=my_embedder)
Install: pip install fireflyframework-agentic[vectorstores-chroma]
ChromaDB 1.5.9 retains known upstream advisories. Keep embedded use within one trust domain and restrict any remote server to trusted application access. Metadata namespaces, caller-provided filters and collection-wide document IDs do not provide the PostgreSQL adapter's namespace-write guarantee. Read the security restrictions before using Chroma for shared data.
Pinecone¶
from fireflyframework_agentic.vectorstores import PineconeVectorStore
store = PineconeVectorStore(
index_name="my-index",
# Reads PINECONE_API_KEY from the environment.
embedder=my_embedder,
)
Install: pip install fireflyframework-agentic[vectorstores-pinecone]
Qdrant¶
from fireflyframework_agentic.vectorstores import QdrantVectorStore
store = QdrantVectorStore(
collection_name="my_collection",
url="http://localhost:6333", # default
# For Qdrant Cloud, pass api_key from your secret store.
vector_size=1536, # must match your embedder dimensions
embedder=my_embedder,
)
Install: pip install fireflyframework-agentic[vectorstores-qdrant]
PostgreSQL / pgvector¶
A PostgreSQL-backed store using the pgvector extension, so production
deployments can co-locate vectors with an existing Postgres instance instead of
operating a separate vector database. ANN search uses an HNSW index over cosine
distance.
from fireflyframework_agentic.vectorstores import PgVectorVectorStore
store = PgVectorVectorStore(
"postgresql://user:pass@host/db", # connection string (first positional)
dimension=1536, # must match your embedder; sizes the vector column
table_name="vector_documents", # default
hnsw_m=16, # HNSW build params
hnsw_ef_construction=64,
hnsw_ef_search=200, # set per query for recall/latency tuning
pool_min_size=1,
pool_max_size=10,
embedder=my_embedder,
)
await store.initialise() # opens the asyncpg pool and creates the table/indexes (idempotent)
await store.upsert(docs)
results = await store.search_text("query")
await store.close() # closes the connection pool
The store owns one table (created on first use) and supports all seven
SearchFilter operators on metadata. _prepare_session(conn, *, namespace) is an
overridable per-transaction hook (default no-op) for callers that need
SET LOCAL session setup -- e.g. Postgres Row-Level Security GUCs. Connection
and pool failures raise VectorStoreConnectionError.
Document IDs are unique across the table. Upserting an existing ID updates it
only within its original namespace. A conflicting namespace raises
VectorStoreError and rolls back the entire batch, including earlier inserts
and updates. This also applies when TenantScopedVectorStore supplies the
namespace. Use globally unique document IDs when multiple scopes share a table.
The store does not install PostgreSQL row-level security policies; applications
must bind scopes to authenticated callers and manage database permissions.
Install: pip install fireflyframework-agentic[vectorstores-pgvector]
For an existing application, follow the 26.10.0 upgrade notes
and pinned release installation.
create_schema=False leaves schema creation to migrations and checks that the
vector extension and table exist. Operators must separately verify the table's
dimensions, indexes, permissions, and any RLS policies.
There is no supported PRISM selector or prism.nprobe setting in this adapter.
The pg_vectorsearch evaluation records the
compatibility and filtered-recall reasons for retaining pgvector/HNSW. Adding a
second index manually does not guarantee which index PostgreSQL will choose.
sqlite-vec¶
A sqlite-vec (vec0 virtual table) backend that co-resides inside an existing
SQLite file via the storage module's DatabaseStore. Useful for embedded,
file-based deployments.
from fireflyframework_agentic.vectorstores import SqliteVecVectorStore
# From a path (wrapped in a DatabaseStore/LocalBackend automatically)
store = SqliteVecVectorStore("vectors.db", dimension=1536, embedder=my_embedder)
# Or from a pre-built DatabaseStore (to share a SQLite file with other data)
from fireflyframework_agentic.storage import DatabaseStore, LocalBackend
db = DatabaseStore(LocalBackend("app.db"), store_id="local:app.db")
store = SqliteVecVectorStore(db, dimension=1536, table_name="vec_chunks", embedder=my_embedder)
await store.upsert(docs)
results = await store.search_text("query")
await store.close()
upsert() and delete() accept an optional keyword-only session: WriteSession
to enlist the operation in a coordinated DatabaseStore write batch. search()
returns results carrying only the document id and score (text/metadata are not
stored by this backend).
Install: pip install fireflyframework-agentic[vectorstores-sqlite-vec]
Core Types¶
VectorDocument¶
from fireflyframework_agentic.vectorstores import VectorDocument
doc = VectorDocument(
id="unique-id", # required
text="The document text", # required
embedding=[0.1, 0.2, 0.3], # all vectors must match the configured embedding dimension
metadata={"source": "web"}, # optional key-value metadata
namespace="default", # optional namespace scoping
)
SearchResult¶
from fireflyframework_agentic.vectorstores import SearchResult
# Returned by search() and search_text()
result.document # VectorDocument
result.score # float (0.0 to 1.0, higher = more similar)
SearchFilter¶
from fireflyframework_agentic.vectorstores import SearchFilter
# Supported operators: eq, ne, gt, lt, gte, lte, in
filters = [
SearchFilter(field="source", operator="eq", value="web"),
SearchFilter(field="year", operator="gte", value=2024),
]
results = await store.search(query_embedding, filters=filters)
Note: Filter operator support varies by backend. eq is universally supported.
InMemoryVectorStore and PgVectorVectorStore support all 7 operators;
PgVectorVectorStore binds both the metadata key and value as parameters
(no SQL interpolation). Other external backends support a narrower subset.
Namespaces¶
All operations accept a namespace parameter to scope documents. Use distinct
IDs when writing to different namespaces in a shared PostgreSQL table:
from fireflyframework_agentic.vectorstores import VectorDocument
project_a_docs = [VectorDocument(id="project-a:1", text="Project A notes")]
project_b_docs = [VectorDocument(id="project-b:1", text="Project B notes")]
await store.upsert(project_a_docs, namespace="project-a")
await store.upsert(project_b_docs, namespace="project-b")
# Search only within a namespace
results = await store.search_text("query", namespace="project-a")
# Delete only within a namespace
await store.delete(["project-a:1"], namespace="project-a")
Auto-Embedding¶
When a BaseVectorStore has an embedder configured, documents without embeddings
are automatically embedded during upsert():
store = InMemoryVectorStore(embedder=my_embedder)
# These docs have no embedding -- they'll be auto-embedded
docs = [VectorDocument(id="1", text="Hello")]
await store.upsert(docs) # embedder.embed() called automatically
The search_text() method embeds the query string before searching:
# Equivalent to: embedding = await embedder.embed_one(query); store.search(embedding)
results = await store.search_text("my query")
Registry¶
from fireflyframework_agentic.vectorstores import VectorStoreRegistry, InMemoryVectorStore
registry = VectorStoreRegistry()
registry.register("memory", InMemoryVectorStore(embedder=my_embedder))
store = registry.get("memory") # raises KeyError if the name is not registered
await store.upsert(docs)
registry.list_names() # -> ["memory"]
registry.unregister("memory") # remove (no-op if absent)
Tenant/Workspace Scoping¶
The VectorStoreProtocol is single-namespace: a store partitions documents by one
opaque namespace string. Multi-tenant applications need stronger guarantees --
every read and write must be confined to a (tenant_id, workspace_id) scope, and
forgetting the scope must fail loudly rather than silently leak across tenants.
TenantScopedVectorStore wraps any VectorStoreProtocol backend and folds the
scope into the canonical "t/<tenant_id>/w/<workspace_id>" namespace. The wrapper
requires explicit scope on each operation; the application must authorize that
scope and choose a backend whose storage behavior meets its isolation needs.
from fireflyframework_agentic.vectorstores import (
InMemoryVectorStore,
TenantScopedVectorStore,
)
inner = InMemoryVectorStore(embedder=my_embedder)
store = TenantScopedVectorStore(inner) # stamp_metadata=True by default
# tenant_id and workspace_id are required keyword-only arguments on every op
await store.upsert(docs, tenant_id="acme", workspace_id="prod")
results = await store.search(query_embedding, top_k=5, tenant_id="acme", workspace_id="prod")
await store.delete(["id-1"], tenant_id="acme", workspace_id="prod")
await store.initialise() # passes through to the wrapped store's lifecycle hook
await store.close()
On upsert, each document is copied (never mutating the caller's objects), its
namespace is set to the scope, and -- when stamp_metadata=True (default) -- the
scope is also stamped onto metadata["tenant_id"] / metadata["workspace_id"].
These stamps describe the scope; they are not an authorization boundary. A caller
that forgets tenant_id/workspace_id fails with TypeError. Document IDs are
preserved, so PostgreSQL's table-wide uniqueness rule still applies.
The namespace codec is exported directly:
from fireflyframework_agentic.vectorstores import scope_namespace, parse_scope_namespace
scope_namespace("acme", "prod") # -> "t/acme/w/prod"
parse_scope_namespace("t/acme/w/prod") # -> ("acme", "prod")
Both raise ValueError if a component is empty or contains /. ScopedVectorStore
is the fail-loud Protocol that TenantScopedVectorStore satisfies.
Configuration¶
Global defaults via environment variables (prefix FIREFLY_AGENTIC_):
| Setting | Env Variable | Default |
|---|---|---|
default_vector_store |
FIREFLY_AGENTIC_DEFAULT_VECTOR_STORE |
memory |
vector_store_namespace |
FIREFLY_AGENTIC_VECTOR_STORE_NAMESPACE |
default |
Pipeline Integration (RAG)¶
Build retrieval-augmented generation workflows by wiring a RetrievalStep into a
pipeline via PipelineBuilder / PipelineEngine:
from fireflyframework_agentic.pipeline import PipelineBuilder, RetrievalStep
# RetrievalStep embeds the query text (via embedder) and searches the store
retrieval = RetrievalStep(my_store, embedder=my_embedder, top_k=5)
engine = (
PipelineBuilder("rag")
.add_node("retrieve", retrieval)
# .add_node("answer", agent) # e.g. an AgentStep that consumes the results
# .chain("retrieve", "answer")
.build()
)
result = await engine.run(inputs="What is RAG?")
RetrievalStep(store, *, embedder=None, top_k=5, input_key="input") reads the
query from inputs[input_key] (falling back to the pipeline's initial inputs). It
embeds the query with embedder.embed_one(...) then calls store.search(...); if
no embedder is supplied, the input is assumed to already be an embedding.
Custom Backend¶
Subclass BaseVectorStore and implement _upsert, _search, and _delete for a
new storage driver. For an existing backend, you can extend its implemented hooks.
This complete in-memory variant validates every document before accepting the batch:
from fireflyframework_agentic.vectorstores import InMemoryVectorStore, VectorDocument
class AttributedVectorStore(InMemoryVectorStore):
async def _upsert(self, documents: list[VectorDocument], namespace: str) -> None:
missing = [doc.id for doc in documents if not doc.metadata.get("source")]
if missing:
raise ValueError(f"Documents require source metadata: {', '.join(missing)}")
await super()._upsert(documents, namespace)
store = AttributedVectorStore()
await store.upsert([
VectorDocument(id="guide-1", text="Bound retry attempts.", embedding=[1.0, 0.0], metadata={"source": "guide.md"}),
])
results = await store.search([1.0, 0.0], top_k=1)
assert results[0].document.id == "guide-1"
The inherited backend implements search, filtering, namespace isolation, and deletion.
The base class fills in the contract for you: all public ops default to
namespace="default"; search()/search_text() default to top_k=5; upsert()
auto-embeds documents lacking an embedding via embedder.embed(texts) (batch);
search_text() uses embedder.embed_one(query) and raises VectorStoreError if no
embedder is configured. Every public method wraps any non-VectorStoreError
exception from your _upsert/_search/_delete in a VectorStoreError.
See also: Embeddings Guide for embedding provider setup.