> ## 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 built-in backends such as LanceDB, PGVector, ChromaDB, or Neptune Analytics, or use community adapters such as Qdrant, Redis, and FalkorDB
* **[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.
## Data Flow And Verification
For the default local setup, user content stays on the local machine:
* Raw source files live under `DATA_ROOT_DIRECTORY`
* Cognee-managed state lives under `/databases`
* The default `SYSTEM_ROOT_DIRECTORY` is `.cognee_system` when the variable is unset
That means the local defaults do not require a Cognee-managed backend. If you switch to remote LLM, embedding, database, object-storage, or cloud-connection settings, Cognee will contact the endpoints you configured instead.
For deployment-specific connection checks, see the local setup guide and the cloud SDK connection guide.
## How `.env` Is Loaded
Cognee loads `.env` values when the Python package is imported. Keep the file in your project root, or in the directory from which you run Python, so it is available before Cognee creates its runtime configuration objects.
Cognee loads `.env` with overwrite behavior enabled. If the same key is set in both your shell and `.env`, the value from `.env` is the one Cognee uses after import.
| Priority | Source | When to use |
| -------- | ------------------------------------------------------------------------------ | --------------------------------------------------------------- |
| 1 | Runtime configuration methods, such as `cognee.config.set("llm_model", "...")` | Temporary changes inside one Python process |
| 2 | Values in `.env` | Persistent local development configuration |
| 3 | Shell, deployment, or `os.environ` variables | CI, containers, hosted deployments, secrets managers, and tests |
| 4 | Cognee defaults | Local defaults when nothing is configured |
Runtime configuration methods update Cognee's in-memory config objects and stay active for the duration of the current Python process, or until you call another setter. They do not write changes back to `.env` unless you pass `persist=True` to `cognee.config.set(...)` — which is what `cognee-cli config set` does. See the [Python API config reference](/python-api/config) for details.
Setting `os.environ["KEY"] = "value"` changes the current Python process environment. Use it for Cognee only before importing Cognee, and mainly for process or deployment settings:
```python theme={null}
import os
os.environ["LOG_LEVEL"] = "ERROR"
os.environ["COGNEE_LOG_FILE"] = "false"
import cognee
```
After `import cognee`, do not rely on `os.environ` to change Cognee behavior. Some code paths read environment variables lazily, but others read them during import, application startup, or cached config creation. Post-import `os.environ` changes are therefore inconsistent.
If the same key also exists in `.env`, Cognee's import-time `.env` loading overwrites the earlier `os.environ` value:
```python theme={null}
import os
os.environ["LLM_MODEL"] = "openai/gpt-4o-mini"
import cognee
```
```dotenv theme={null}
# .env
LLM_MODEL="openai/gpt-5-mini"
```
In this case, Cognee uses `openai/gpt-5-mini` after import. Use `os.environ` before importing Cognee only for keys that are not also defined in `.env`.
Use `.env`, shell variables, deployment variables, or pre-import `os.environ` for settings such as:
| Area | Environment variables |
| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Auth and access control | `ENABLE_BACKEND_ACCESS_CONTROL`, `REQUIRE_AUTHENTICATION`, `FASTAPI_USERS_JWT_SECRET`, `JWT_LIFETIME_SECONDS`, `HASH_API_KEY`, `ALLOW_HTTP_REQUESTS`, `ALLOW_CYPHER_QUERY`, `ACCEPT_LOCAL_FILE_PATH` |
| Logging | `LOG_LEVEL`, `COGNEE_LOG_FILE`, `COGNEE_LOGS_DIR`, `COGNEE_LOG_MAX_BYTES`, `COGNEE_LOG_BACKUP_COUNT`, `COGNEE_LOG_SEARCH_HISTORY` |
| Cache and sessions | `CACHING`, `AUTO_FEEDBACK`, `SESSION_SEARCH_MODE`, `CACHE_BACKEND`, `CACHE_HOST`, `CACHE_PORT`, `CACHE_USERNAME`, `CACHE_PASSWORD`, `CACHE_SSL`, `CACHE_SSL_CERT_REQS`, `SESSION_TTL_SECONDS` |
| Recall warm-up | `RECALL_WARMUP_SHORTCIRCUIT`, `RECALL_WARMUP_THRESHOLD`, `RECALL_WARMUP_CACHE_TTL` |
| Storage and cloud credentials | `STORAGE_BACKEND`, `STORAGE_BUCKET_NAME`, `AWS_REGION`, `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_ENDPOINT_URL`, `COGNEE_SERVICE_URL`, `COGNEE_API_KEY` (legacy fallbacks: `COGNEE_CLOUD_API_URL`, `COGNEE_CLOUD_AUTH_TOKEN`) |
| Web/API/telemetry | `HTTP_API_HOST`, `HTTP_API_PORT`, `CORS_ALLOWED_ORIGINS`, `TAVILY_API_KEY`, `KEENABLE_API_KEY`, `KEENABLE_BASE_URL`, `KEENABLE_LIVE_FETCH`, `WEB_SCRAPER_TIMEOUT`, `TELEMETRY_DISABLED`, `TELEMETRY_ORIGIN`, `ENV` |
If you need to change supported runtime settings after import, use `cognee.config.set(...)` because it updates Cognee's in-memory runtime config directly:
```python theme={null}
import cognee
cognee.config.set("llm_model", "openai/gpt-5-mini")
```
Use `cognee.config.set(...)` for runtime-safe Cognee settings: values that can be changed inside the current Python process without reinitializing the whole application. This mainly covers LLMs, embeddings, graph databases, vector databases, chunking, model overrides, and data/system root directories. For the full method list and the exact internal key names accepted by bulk setters, see the [Python API config reference](/python-api/config).
```python theme={null}
import cognee
cognee.config.set("llm_model", "openai/gpt-5-mini")
cognee.config.set("embedding_provider", "fastembed")
cognee.config.set("vector_db_provider", "lancedb")
cognee.config.set("vector_db_url", "./.cognee_system/databases/cognee.lancedb")
```
`cognee.config.set(key, value)` supports these generic keys:
| Area | Supported keys |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| LLM | `llm_provider`, `llm_model`, `llm_api_key`, `llm_endpoint` |
| Embeddings | `embedding_provider`, `embedding_model`, `embedding_dimensions`, `embedding_endpoint`, `embedding_api_key`, `embedding_api_version`, `embedding_max_completion_tokens`, `embedding_batch_size`, `huggingface_tokenizer` |
| Graph database | `graph_database_provider`, `graph_database_subprocess_enabled`, `kuzu_num_threads`, `kuzu_buffer_pool_size`, `kuzu_max_db_size` |
| Vector database | `vector_db_provider`, `vector_db_subprocess_enabled`, `vector_db_url`, `vector_db_key` |
| Chunking | `chunk_size`, `chunk_overlap`, `chunk_strategy`, `chunk_engine` |
| Models | `classification_model`, `summarization_model`, `graph_model` |
| Storage paths | `system_root_directory`, `data_root_directory` |
`cognee.config.set(...)` can replace `.env` or `os.environ` only for the supported runtime config keys above. It does not replace process-level environment variables.
Keep these in `.env`, shell/deployment variables, or pre-import `os.environ`: `ENABLE_BACKEND_ACCESS_CONTROL`, `REQUIRE_AUTHENTICATION`, `CACHING`, `CACHE_BACKEND`, `LOG_LEVEL`, `COGNEE_LOG_FILE`, `STORAGE_BACKEND`, `TAVILY_API_KEY`, `KEENABLE_API_KEY`, `TELEMETRY_DISABLED`, `TELEMETRY_ORIGIN`, `HTTP_API_HOST`, `HTTP_API_PORT`, and cloud or AWS credentials.
`cognee.config.set(key, value)` is not a free-form setter. Unsupported keys raise an error instead of silently creating new settings.
Restart your Python process, server, notebook kernel, or container after editing `.env` if Cognee has already been imported. Runtime setters are useful for short-lived overrides, but `.env` changes are safest when applied before import.
When changing storage backends, database providers, embedding dimensions, or other settings that affect persisted data, review the pruning warning in the Configuration Workflow section before running ingestion again.
Cognee uses two top-level storage roots. The short version: `SYSTEM_ROOT_DIRECTORY` is for Cognee-managed databases and internal state, while `DATA_ROOT_DIRECTORY` is for source files and filesystem-backed cache/session data.
| Directory | Env var | Default | What it stores |
| --------------- | ----------------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **System root** | `SYSTEM_ROOT_DIRECTORY` | `.cognee_system` | Cognee's **internal** files: the `/databases/` subfolder holding the relational store, vector store, and graph store. This is data Cognee generates and manages for you. |
| **Data root** | `DATA_ROOT_DIRECTORY` | `.data_storage` | **Your** data: the raw source files that `add()` copies into Cognee (text, PDFs, CSVs, images, audio, etc.), plus filesystem session/cache data. |
These defaults are not automatically placed in your project root. They resolve relative to the installed `cognee` package, which often means a path inside your virtual environment. For portable local projects, pin both values in `.env`:
```bash theme={null}
SYSTEM_ROOT_DIRECTORY="/abs/path/to/project/.cognee_system"
DATA_ROOT_DIRECTORY="/abs/path/to/project/.data_storage"
```
`.env` values must be **absolute paths** (or `s3://...` URLs). Relative `.env` values raise a configuration error during config loading. Runtime setters such as `cognee.config.system_root_directory(...)` and `cognee.config.data_root_directory(...)` should also receive absolute paths. Setting `system_root_directory` cascades to the default relational, vector, and graph database paths under `/databases`. See the [Python API config reference](/python-api/config) for the setter signatures.
For path-mismatch troubleshooting, see [Graph Stores](/setup-configuration/graph-stores#troubleshooting-no-nodes-found). For backup and migration details, see [Backing up local data](#backing-up-local-data) and [Migrating to Another Instance](/how-to-guides/cognee-sdk/deployment#migrating-to-another-instance).
With a plain `pip install cognee` (no extras), Cognee uses three bundled, file-based backends. None of them require a separate server, and no extra dependencies are needed:
| Role | Default provider | Where data lives |
| --------------------------------------- | ------------------------------------------------------------------------------- | -------------------------------------------------------- |
| Relational (metadata, documents, state) | [SQLite](./relational-databases) (`DB_PROVIDER=sqlite`, database `cognee_db`) | `/databases/cognee_db` |
| Vector (embeddings, semantic search) | [LanceDB](./vector-stores) (`VECTOR_DB_PROVIDER=lancedb`) | `/databases/cognee.lancedb` |
| Graph (entities, relationships) | [Ladybug (Kuzu-compatible)](./graph-stores) (`GRAPH_DATABASE_PROVIDER=ladybug`) | `/databases/cognee_graph_ladybug` |
Extras such as `cognee[postgres]`, `cognee[neo4j]`, `cognee[chromadb]`, or `cognee[neptune]` are only required when you switch a backend to one of those providers. The defaults above work without any of them.
**Connections are not opened at import.** `import cognee` only loads `.env` and builds in-memory configuration objects — it does not connect to any database. Each backend engine is created lazily, the first time an operation actually needs it (for example during `add()`, `cognify()`, or `search()`), and is then cached and reused for the rest of the process. For the file-based defaults, the database files are created automatically under `SYSTEM_ROOT_DIRECTORY` on first use, so there is no startup connection step to configure.
With the default file-based backends, all of Cognee's persistent state lives in two directories on disk, so a backup is just a copy of those two trees:
| Directory | Default | Contents |
| ----------------------- | ---------------- | ------------------------------------------------------------------------------------------------- |
| `SYSTEM_ROOT_DIRECTORY` | `.cognee_system` | The relational, vector, and graph stores under `/databases/` |
| `DATA_ROOT_DIRECTORY` | `.data_storage` | The raw ingested source files that `add()` copies into Cognee, plus filesystem session/cache data |
Back up **both** directories together so the graph, vectors, relational metadata, and the source files they reference stay consistent with each other.
**Stop writes before copying.** SQLite, LanceDB, and the Kuzu-compatible graph store are embedded databases that write directly to these files. Copying them while an `add()`, `cognify()`, `memify()`, or `delete()` operation is in progress can capture a half-written, corrupt snapshot. For a safe, consistent backup, make sure no Cognee process is actively ingesting or mutating data — stop your Cognee service (or wait for all pipelines to finish), then copy the directories:
```bash theme={null}
# With the Cognee process stopped / idle
cp -r .cognee_system .cognee_system.backup
cp -r .data_storage .data_storage.backup
```
Operations that only read from the stores are safe, but default graph-completion searches with session caching can write session/cache data. To get a fully consistent backup, keep Cognee idle while copying. To restore, stop Cognee and replace the two directories with your backed-up copies.
If you have moved a backend off the file-based defaults — for example to [Postgres](./relational-databases), [PGVector](./vector-stores), or [Neo4j](./graph-stores) — back up that external database using its own tooling instead; only the file-based stores live under these directories.
## 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.
Most configuration keys (LLM, embedding, database, etc.) are used without a `COGNEE_` prefix, but several Cognee-specific controls do use one, including logging, tracing, and cloud connection variables. The cloud-sync credentials `COGNEE_SERVICE_URL` and `COGNEE_API_KEY` are canonical; the older `COGNEE_CLOUD_API_URL` and `COGNEE_CLOUD_AUTH_TOKEN` names are still accepted as legacy fallbacks.
| Variable | Default | Description |
| ----------------- | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `LLM_PROVIDER` | `openai` | Provider: `openai`, `azure`, `gemini`, `anthropic`, `ollama`, `mistral`, `bedrock`, `custom` |
| `LLM_MODEL` | `openai/gpt-5-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` | unset | Response temperature (0.0–2.0), sent with every LLM call when you set it — unset means the provider's own default applies, except on local inference servers (Ollama, llama.cpp, LM Studio), where an unset value sends `0.0`. gpt-5 models, including the default `openai/gpt-5-mini`, reject any other value |
| `LLM_SEED` | unset | Sampling seed for reproducible outputs, sent only when set (provider support varies) |
| 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; leaving the whole embedding section at its defaults while `LLM_PROVIDER` is non-OpenAI is rejected up front — see [LLM/Embedding Configuration](#configuration-workflow)) |
| `EMBEDDING_ENDPOINT` | — | Custom endpoint URL (required for Ollama, etc.) |
| `HUGGINGFACE_TOKENIZER` | — | HuggingFace Hub model ID that overrides the tokenizer Cognee uses for token counting when the embedding model is not itself a HuggingFace repo. Commonly used with Ollama embeddings (for example, `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 |
| `POOL_ARGS` | — | JSON SQLAlchemy connection-pool args for the relational engine (Postgres **and** SQLite) and the Postgres graph adapter **(demo)**, and — when `VECTOR_POOL_ARGS` is unset — for per-dataset PGVector engines. On SQLite only the pool keys (`pool_size`, `max_overflow`, `pool_recycle`, `pool_timeout`, `pool_pre_ping`, `poolclass`) are applied, and leaving it unset keeps the `NullPool` default — see [SQLite connection pooling](/setup-configuration/relational-databases#advanced-options). Must be a JSON object. |
| `VECTOR_DB_PROVIDER` | `lancedb` | Vector store provider. Built-in options include `lancedb`, `pgvector`, `chromadb`, and `neptune_analytics`; community adapters add providers such as `qdrant`, `redis`, and `falkordb`. |
| `VECTOR_DB_URL` | — | Vector store connection URL |
| `VECTOR_POOL_ARGS` | — | JSON connection-pool args for per-dataset PGVector engines in multi-user mode. Must be a JSON object; invalid JSON raises a configuration error. When unset, PGVector per-dataset engines inherit the relational `POOL_ARGS`, falling back to `pool_size=2` and `max_overflow=20` under backend access control when neither is set. |
| `GRAPH_DATABASE_PROVIDER` | `ladybug` | Graph store: `ladybug`, `ladybug-remote`, `kuzu`, `kuzu-remote`, `neo4j`, `neptune` |
| `GRAPH_DATABASE_URL` | — | Graph store connection URL |
| `GRAPH_DATABASE_USERNAME` / `GRAPH_DATABASE_PASSWORD` | — | Graph store credentials |
Optional tasks `cognify()` appends to its default pipeline. Both are off by default — with the flags unset the task list is exactly the standard pipeline. The cognify config is cached for the lifetime of the process, so set these before the first `cognify()` call.
| Variable | Default | Description |
| ------------------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `CONTRADICTION_DETECTION` | `false` | Set `true` to compare the facts each run touched against the facts already stored around them and record every conflict as a `contradicts` edge. See [Contradiction detection](/python-api/cognify#contradiction-detection). |
| `CONTRADICTION_CONFIDENCE_THRESHOLD` | `0.5` | Minimum LLM confidence for a fact pair to be flagged. |
| `CONTRADICTION_MAX_FACTS` | `500` | Cap on the facts sent to the LLM in a single check. |
| `PROVENANCE_TRACKING` | `false` | Set `true` to append the opt-in provenance-ledger task, writing document → chunk → entity → relationship lineage into the append-only `provenance_entries` table in the relational database. Adds relational writes on every `cognify()` run, so plan for disk and backup sizing. The table ships as Alembic revision `b8c1d3e5f7a9` — run migrations before enabling it on an existing deployment. See [Provenance ledger](/python-api/cognify#provenance-ledger). |
Before `recall()` runs graph retrieval, it checks whether the target datasets have ever been through a pipeline — a single indexed relational query, with no graph or vector engine spin-up. Datasets that have not return an instant `memory_warming_up` marker instead of a graph search plus an LLM call that could only come back empty. See [Warming-up marker](/python-api/recall#warming-up-marker) for the response shape and its exceptions.
| Variable | Default | Description |
| ---------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `RECALL_WARMUP_SHORTCIRCUIT` | `true` | Kill switch. Set `false` to skip the check entirely and have recall's graph lane behave exactly as it did before. |
| `RECALL_WARMUP_THRESHOLD` | `1` | Minimum datapoint count treated as warm. The default means only never-processed datasets short-circuit; the probe is binary, so raising it cannot make a populated dataset read as cold. |
| `RECALL_WARMUP_CACHE_TTL` | `60` | Seconds a *warm* verdict is cached in-process, so repeated recalls against a populated dataset skip even the probe. Cold verdicts are never cached, so the first recall after `cognify()` sees the new data immediately. |
All three are also settable at runtime with `cognee.config.set(...)` (`recall_warmup_shortcircuit`, `recall_warmup_threshold`, `recall_warmup_cache_ttl`). The check fails open: a probe or configuration error — including a malformed `RECALL_WARMUP_*` value — falls through to a normal search rather than failing the recall.
| 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 |
| `TELEMETRY_ORIGIN` | `sdk` | Value stamped on every telemetry event as `telemetry_origin`, so events can be segmented by where they come from |
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. |
| `AUTO_FEEDBACK` | `true` | Enable automatic session-context guidance for session-capable completion searches. Set to `false` to disable the extra turn-analysis LLM call and use plain conversation history. |
| `SESSION_SEARCH_MODE` | `concurrent` | How a session turn executes: `concurrent` runs the turn analysis alongside retrieval and answer generation (retrieving with both the raw question and a deterministic rewrite), `sequential` runs the analysis before a single retrieval so its outputs affect the same turn. See [Sessions and Caching](/core-concepts/sessions-and-caching#session-context-guidance-auto-feedback). |
| `CACHE_BACKEND` | `sqlite` | Cache backend: `sqlite` (local SQL `cache.db` file), `postgres` (external SQL database), `redis` (external in-memory store), `fs` (local disk via diskcache), or `tapes` (local cache plus Tapes mirroring). |
| `CACHE_DB_URL` | — | Optional SQLAlchemy async URL for the SQL cache backends. When unset, `sqlite` uses a `cache.db` file next to the relational SQLite database and `postgres` falls back to the relational `DB_*` settings. |
| `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. |
| `CACHE_SSL` | `false` | Connect to Redis over TLS (used when `CACHE_BACKEND=redis`). Enable for managed Redis with in-transit encryption (AWS ElastiCache, GCP Memorystore, Azure Cache for Redis). |
| `CACHE_SSL_CERT_REQS` | `required` | TLS certificate verification when `CACHE_SSL` is enabled: `required`, `optional`, or `none`. |
| `SESSION_TTL_SECONDS` | `604800` | Expiry for cached session entries (7 days). Set to `0` to disable expiry. |
The default `sqlite` needs no setup and suits local development. Use `postgres` or `redis` when you want the session cache in an external service — for example in production, so the cache outlives the Cognee host. 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`)
* **`TELEMETRY_ORIGIN`** (string, optional): Labels where the events come from. Every event carries its value as a `telemetry_origin` property, so telemetry can be segmented by origin — the Cognee-managed cloud sets `TELEMETRY_ORIGIN=cloud`, and anything else reports the default `sdk`. It is read from the environment on each event, so it cannot be set through `cognee.config.set(...)` (default: `sdk`)
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
If you would rather start from a working combination than assemble one, [Store Configurations](/guides/store-configurations) gives a complete `.env` block per supported relational + vector + graph stack, with the extras and Docker commands each one needs.
**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. Cognee checks for the two mismatches this causes **before any ingestion work happens**: `add()` and `remember()` run a zero-network provider-consistency check at the top of the call and raise `ProviderConfigMismatchError` when they find one, instead of letting the mismatch surface minutes later as an opaque authentication error mid-cognify.
* **Only the LLM is configured** — `LLM_PROVIDER` is set to something other than `openai` while the embedding settings are still untouched (`EMBEDDING_PROVIDER=openai`, `EMBEDDING_MODEL=openai/text-embedding-3-large`, no `EMBEDDING_API_KEY`, no `EMBEDDING_ENDPOINT`). Your provider key — or, with `LLM_PROVIDER=custom`, no key at all — would otherwise be sent to the OpenAI embeddings endpoint. Fix it by setting `EMBEDDING_PROVIDER`, `EMBEDDING_MODEL`, and `EMBEDDING_API_KEY` (or `EMBEDDING_ENDPOINT` for a local embedder such as Ollama), or by providing an OpenAI `EMBEDDING_API_KEY` to keep the default embedder.
* **Only embeddings are configured** — embedding settings are customised but `LLM_API_KEY` is unset for a provider that requires one. `bedrock` and `llama_cpp` are exempt (they authenticate with AWS credentials or run locally), as is `azure` with managed identity.
The check compares settings only — it never verifies that the credentials work. Run [`cognee-cli doctor`](/cognee-cli/overview#diagnose-your-setup) to see the same report before you ingest anything, and `cognee-cli doctor --probe` to also test live LLM and embedding calls.
To skip the check, set `COGNEE_SKIP_PREFLIGHT`, `COGNEE_SKIP_CONNECTION_TEST`, or `MOCK_EMBEDDING` to `true`, `1`, or `yes` (case-insensitive), so CI, mocked, and offline runs with deliberately partial provider config are unaffected. A passing check is cached for the lifetime of the process; a failing one is not, so a config fix applied in-process is picked up on the next `add()` / `remember()` call without a restart.
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