Skip to main content
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 — Choose from OpenAI, Azure OpenAI, Google Gemini, Anthropic, Ollama, or custom providers (like vLLM) for text generation and reasoning tasks
  • Structured Output Backends — Configure LiteLLM + Instructor or BAML for reliable data extraction from LLM responses
  • 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 — Use SQLite for local development or Postgres for production to store metadata, documents, and system state
  • 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 — Build knowledge graphs with Kuzu, Kuzu-remote, Neo4j, Neptune, Neptune Analytics, or Memgraph to manage relationships and reasoning
  • Dataset Separation & Access Control — Configure dataset-level permissions and isolation
  • Sessions & Caching — Enable conversational memory with Redis or filesystem cache adapters
Want to run Cognee without a cloud API key? See the Local Setup guide 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 <SYSTEM_ROOT_DIRECTORY>/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.
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.
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:
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:
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:If you need to change supported runtime settings after import, use cognee.config.set(...) because it updates Cognee’s in-memory runtime config directly:
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.
cognee.config.set(key, value) supports these generic keys: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, TELEMETRY_DISABLED, 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.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:
.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 <SYSTEM_ROOT_DIRECTORY>/databases. See the Python API config reference for the setter signatures.
For path-mismatch troubleshooting, see Graph Stores. For backup and migration details, see Backing up local data and 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: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: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:
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, PGVector, or Neo4j — 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.
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 for the full guide.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:
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.
Or using an env file:

​
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 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.

LLM Providers

Configure OpenAI, Azure, Gemini, Anthropic, Ollama, or custom LLM providers (like vLLM)

Structured Output Backends

Configure LiteLLM + Instructor or BAML for reliable data extraction

Embedding Providers

Set up OpenAI, Mistral, Ollama, Fastembed, or custom embedding services

Relational Databases

Choose between SQLite for local development or Postgres for production

Vector Stores

Configure LanceDB, PGVector, Qdrant, Redis, ChromaDB, FalkorDB, or Neptune Analytics

Graph Stores

Set up Kuzu, Neo4j, or Neptune for knowledge graph storage