Configuration Reference
All configuration in ContextOS is handled via environment variables (or a .env file) using Pydantic Settings.
Core Settings
DATABASE_URL
The SQLAlchemy connection string for the PostgreSQL database.
- Required: Yes
- Default:
postgresql+asyncpg://postgres:postgres@localhost:5433/contextos
MAX_CONTEXT_TOKENS
The global default token budget for context planning if not specified dynamically per request.
- Required: No
- Default:
4000
Embedding Providers
EMBEDDING_PROVIDER
Which embedding model to use for semantic search.
- Valid Values:
openai,local - Default:
openai
OPENAI_API_KEY
Required if EMBEDDING_PROVIDER=openai.
- Required: Conditional
LOCAL_EMBEDDING_MODEL
The huggingface model ID to use if EMBEDDING_PROVIDER=local.
- Default:
BAAI/bge-small-en-v1.5
Pipeline Tuning
ENABLE_BM25
Whether to perform lexical BM25 retrieval alongside dense retrieval.
- Default:
False
ENABLE_RERANKER
Whether to apply cross-encoder reranking to the top candidates before planning.
- Default:
False
RERANKER_MODEL
The huggingface model ID to use for cross-encoder reranking.
- Default:
BAAI/bge-reranker-base
DENSE_CANDIDATE_K
How many candidates to retrieve from the dense index.
- Default:
500
BM25_CANDIDATE_K
How many candidates to retrieve from the BM25 index.
- Default:
500
RRF_K
The smoothing constant used in Reciprocal Rank Fusion.
- Default:
60
PRE_RERANK_K
How many fused candidates to hydrate and send to the reranker.
- Default:
500
RERANKER_TOP_N
How many reranked candidates to pass to the memory planner.
- Default:
50