> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cognee.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Setup Configuration
> Configure Cognee to use your preferred LLM, embedding engine, and storage backends
Configure Cognee to use your preferred LLM, embedding engine, relational database, vector store, and graph store via environment variables in a local `.env` file.
This section provides beginner-friendly guides for setting up different backends, with detailed technical information available in expandable sections.
## What You Can Configure
Cognee uses a flexible architecture that lets you choose the best tools for your needs. We recommend starting with the defaults to get familiar with Cognee, then customizing each component as needed:
* **[LLM Providers](./llm-providers)** — Choose from OpenAI, Azure OpenAI, Google Gemini, Anthropic, Ollama, or custom providers (like vLLM) for text generation and reasoning tasks
* **[Structured Output Backends](./structured-output-backends)** — Configure LiteLLM + Instructor or BAML for reliable data extraction from LLM responses
* **[Embedding Providers](./embedding-providers)** — Select from OpenAI, Azure OpenAI, Google Gemini, Mistral, Ollama, Fastembed, or custom embedding services to create vector representations for semantic search
* **[Relational Databases](./relational-databases)** — Use SQLite for local development or Postgres for production to store metadata, documents, and system state
* **[Vector Stores](./vector-stores)** — Store embeddings in LanceDB, PGVector, Qdrant, Redis, ChromaDB, FalkorDB, or Neptune Analytics for similarity search
* **[Graph Stores](./graph-stores)** — Build knowledge graphs with Kuzu, Kuzu-remote, Neo4j, Neptune, Neptune Analytics, or Memgraph to manage relationships and reasoning
* **[Dataset Separation & Access Control](./permissions)** — Configure dataset-level permissions and isolation
* **[Sessions & Caching](../core-concepts/sessions-and-caching)** — Enable conversational memory with Redis or filesystem cache adapters
Want to run Cognee without a cloud API key? See the [Local Setup guide](/guides/local-setup) for step-by-step instructions using Ollama and Fastembed.
## Environment Variable Quick Reference
The tables below list the most commonly used configuration variables. For full details on each group, follow the links to the dedicated guides.
Only a small number of internal variables use the `COGNEE_` prefix: `COGNEE_LOGS_DIR`, `COGNEE_TRACING_ENABLED`, `COGNEE_CLOUD_API_URL`, and `COGNEE_CLOUD_AUTH_TOKEN`. All other configuration keys (LLM, embedding, database, etc.) are used without any prefix.
| Variable | Default | Description |
| ----------------- | -------------------- | -------------------------------------------------------------------------------------------- |
| `LLM_PROVIDER` | `openai` | Provider: `openai`, `azure`, `gemini`, `anthropic`, `ollama`, `mistral`, `bedrock`, `custom` |
| `LLM_MODEL` | `openai/gpt-4o-mini` | Model in `provider/model-name` format |
| `LLM_API_KEY` | — | API key for the LLM provider |
| `LLM_ENDPOINT` | — | Custom endpoint URL (required for Ollama, vLLM, etc.) |
| `LLM_API_VERSION` | — | API version (required for Azure) |
| `LLM_TEMPERATURE` | `0.0` | Response temperature (0.0–2.0) |
| Variable | Default | Description |
| ------------------------ | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `EMBEDDING_PROVIDER` | `openai` | Provider: `openai`, `ollama`, `fastembed`, `gemini`, `mistral`, `bedrock`, `custom` |
| `EMBEDDING_MODEL` | `openai/text-embedding-3-large` | Model in `provider/model-name` format |
| `EMBEDDING_DIMENSIONS` | `3072` | Vector dimension size (must match your vector store) |
| `EMBEDDING_API_KEY` | — | API key (falls back to `LLM_API_KEY` if unset) |
| `EMBEDDING_ENDPOINT` | — | Custom endpoint URL (required for Ollama, etc.) |
| `HUGGINGFACE_TOKENIZER` | — | HuggingFace Hub model ID for token counting with Ollama (e.g. `nomic-ai/nomic-embed-text-v1.5`) |
| `TOKENIZERS_PARALLELISM` | — | Optional environment variable used by Hugging Face tokenizers. If Cognee loads a Hugging Face tokenizer, setting this to `false` can suppress the "tokenizers parallelism" warning that may appear in forked or multi-process environments. |
| Variable | Default | Description |
| ----------------------------------------------------- | --------- | ------------------------------------------------------------------------------- |
| `DB_PROVIDER` | `sqlite` | Relational DB: `sqlite`, `postgres` |
| `DB_HOST` / `DB_PORT` / `DB_USERNAME` / `DB_PASSWORD` | — | Postgres connection details |
| `VECTOR_DB_PROVIDER` | `lancedb` | Vector store: `lancedb`, `pgvector`, `qdrant`, `chromadb`, `weaviate`, `milvus` |
| `VECTOR_DB_URL` | — | Vector store connection URL |
| `GRAPH_DATABASE_PROVIDER` | `kuzu` | Graph store: `kuzu`, `kuzu-remote`, `neo4j`, `neptune` |
| `GRAPH_DATABASE_URL` | — | Graph store connection URL |
| `GRAPH_DATABASE_USERNAME` / `GRAPH_DATABASE_PASSWORD` | — | Graph store credentials |
| Variable | Default | Description |
| ----------------------- | ---------------- | -------------------------------------------------- |
| `STORAGE_BACKEND` | `local` | Storage backend: `local`, `s3` |
| `DATA_ROOT_DIRECTORY` | `.data_storage` | Root directory for data files |
| `SYSTEM_ROOT_DIRECTORY` | `.cognee_system` | Root directory for system files |
| `COGNEE_LOGS_DIR` | `{package}/logs` | Override the logs directory path |
| `LOG_LEVEL` | `INFO` | Logging level: `DEBUG`, `INFO`, `WARNING`, `ERROR` |
| `TELEMETRY_DISABLED` | `false` | Set `true` to disable anonymous telemetry |
Cognee uses a cache backend to store session history (Q\&A turns) so that searches with the same `session_id` can include prior interactions as conversational context. See [Sessions and Caching](/core-concepts/sessions-and-caching) for the full guide.
| Variable | Default | Description |
| --------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `CACHING` | `true` | Enable session caching. Set to `false` to run searches without conversational memory. |
| `CACHE_BACKEND` | `fs` | Cache backend: `fs` (local disk via diskcache), `redis` (shared, multi-process), or `tapes` (local cache plus Tapes mirroring). |
| `CACHE_HOST` | `localhost` | Redis hostname (used when `CACHE_BACKEND=redis`). |
| `CACHE_PORT` | `6379` | Redis port. |
| `CACHE_USERNAME` | — | Optional Redis username. |
| `CACHE_PASSWORD` | — | Optional Redis password. |
| `SESSION_TTL_SECONDS` | `604800` | Expiry for cached session entries (7 days). Set to `0` to disable expiry. |
Use `fs` for local development or single-process setups. Use `redis` for production, distributed deployments, or when multiple processes need to share session state. Use `tapes` when you want filesystem-backed sessions plus mirroring of new Q\&A turns to a running Tapes ingest service.
To enable verbose logging in a self-hosted Cognee instance, set `LOG_LEVEL` in your `.env`:
```dotenv theme={null}
LOG_LEVEL="DEBUG"
```
Verbose logging covers pipeline execution, LLM calls, database queries, and graph operations—useful when troubleshooting data processing or provider configuration.
## Docker Environment Variables
Use the same variable names as in your `.env`; pass them with `docker run -e` or load them from a file with `--env-file`.
```bash theme={null}
docker run \
-e LLM_PROVIDER=ollama \
-e LLM_MODEL=ollama/llama3.2 \
-e LLM_ENDPOINT=http://host.docker.internal:11434 \
-e EMBEDDING_PROVIDER=ollama \
-e EMBEDDING_MODEL=nomic-embed-text:latest \
-e EMBEDDING_ENDPOINT=http://host.docker.internal:11434/api/embed \
-e EMBEDDING_DIMENSIONS=768 \
-e HUGGINGFACE_TOKENIZER=nomic-ai/nomic-embed-text-v1.5 \
cognee/cognee:main
```
Or using an env file:
```bash theme={null}
docker run --env-file .env cognee/cognee:main
```
## Observability & Telemetry
Cognee includes built-in telemetry to help you monitor and debug your knowledge graph operations. You can control telemetry behavior with environment variables:
* **`TELEMETRY_DISABLED`** (boolean, optional): Set to `true` to disable all telemetry collection (default: `false`)
When telemetry is enabled, Cognee automatically collects:
* Search query performance metrics
* Processing pipeline execution times
* Error rates and debugging information
* System resource usage
Telemetry data helps improve Cognee's performance and reliability. It's collected anonymously and doesn't include your actual data content.
## Configuration Workflow
1. Install Cognee with all optional dependencies:
* **Local setup**: `uv sync --all-extras`
* **Library**: `pip install "cognee[all]"`
2. Create a `.env` file in your project root (if you haven't already) — see [Installation](/getting-started/installation) for details
3. Choose your preferred providers and follow the configuration instructions from the guides below
**Configuration Changes**: If you've already run Cognee with default settings and are now changing your configuration (e.g., switching from SQLite to Postgres, or changing vector stores), you should call pruning operations before the next cognification to ensure data consistency.
**LLM/Embedding Configuration**: If you configure only LLM or only embeddings, the other defaults to OpenAI. Ensure you have a working OpenAI API key, or configure both LLM and embeddings to avoid unexpected defaults.
Configure OpenAI, Azure, Gemini, Anthropic, Ollama, or custom LLM providers (like vLLM)
Configure LiteLLM + Instructor or BAML for reliable data extraction
Set up OpenAI, Mistral, Ollama, Fastembed, or custom embedding services
Choose between SQLite for local development or Postgres for production
Configure LanceDB, PGVector, Qdrant, Redis, ChromaDB, FalkorDB, or Neptune Analytics
Set up Kuzu, Neo4j, or Neptune for knowledge graph storage