How to Configure Your LLM API Key in Cognee: Environment, Dotenv, and CLI Methods

Set your LLM API key in Cognee by defining the LLM_API_KEY environment variable, adding it to a .env file, or using the cognee config set CLI command.

Cognee is an open-source AI memory framework that transforms documents into searchable knowledge graphs. To enable LLM-powered features like document ingestion and cognitive processing, you must configure your LLM API key in Cognee using the centralized LLMConfig class.

Understanding Cognee's LLM Configuration System

Cognee manages LLM credentials through the LLMConfig class located in cognee/infrastructure/llm/config.py. This is a pydantic-settings model that automatically loads values from environment variables and optional .env files.

When the application starts, it creates a cached configuration instance via get_llm_config(). This singleton pattern ensures that all LLM-dependent components—such as the Ollama embedding engine in cognee/infrastructure/databases/vector/embeddings/OllamaEmbeddingEngine.py—access the same credentials consistently.

Methods to Configure Your LLM API Key in Cognee

Option 1: Environment Variables

The most direct method to configure your LLM API key in Cognee is exporting environment variables in your shell. Cognee recognizes three primary variables:

• LLM_API_KEY – Your provider's secret API key (OpenAI, Anthropic, etc.)
• LLM_MODEL – The model identifier (e.g., openai/gpt-4o)
• LLM_ENDPOINT – Optional custom base URL for the API

The validator in LLMConfig enforces an all-or-nothing policy: all three variables must be set together, or none at all. If you provide only partial configuration, Cognee raises a ValueError at startup (see the validation block at lines 190-206 of cognee/infrastructure/llm/config.py).

export LLM_API_KEY=sk-abc123def456ghi789jkl
export LLM_MODEL=openai/gpt-4o-mini
export LLM_ENDPOINT=https://api.openai.com/v1

cognee add "Cognee turns documents into AI memory."

Option 2: Using a .env File

For local development or containerized deployments, you can store your LLM API key in a .env file at the project root. The LLMConfig class explicitly configures env_file=".env" in its model_config settings (lines 61-63 of cognee/infrastructure/llm/config.py).

Create a .env file with your credentials:

# .env (place at the repository root)

LLM_API_KEY=sk-abc123def456ghi789jkl
LLM_MODEL=openai/gpt-4o-mini
LLM_ENDPOINT=https://api.openai.com/v1

Cognee automatically loads these values when get_llm_config() is first called. This method keeps sensitive keys out of your shell history and version control (ensure .env is listed in .gitignore).

Option 3: CLI Configuration (Temporary)

Cognee provides a CLI command for temporary, in-process configuration changes. The cognee config set command updates the in-memory configuration but does not persist values to the .env file.

Implementation resides in cognee/cli/commands/config_command.py, where the "set" action calls cognee.config.set(key, value) (lines 31-42).

cognee config set llm_api_key sk-abc123def456ghi789jkl
cognee config set llm_model openai/gpt-4o-mini
cognee config set llm_endpoint https://api.openai.com/v1

cognee add "Add a sample document."

Use this approach for quick experimentation or CI/CD pipelines where you want to avoid creating files, but note that the configuration resets when the process terminates.

Validating Your LLM API Key Configuration

To verify that your LLM API key is properly loaded before running expensive operations, access the configuration object directly:

from cognee.infrastructure.llm.config import get_llm_config

cfg = get_llm_config()
print("LLM provider:", cfg.llm_provider)
print("Model:", cfg.llm_model)
print("API key is set:", bool(cfg.llm_api_key))

If the configuration is invalid (e.g., only partial variables set), this code raises a ValueError with a descriptive message pointing to the validation rules in cognee/infrastructure/llm/config.py.

Summary

• Environment variables (LLM_API_KEY, LLM_MODEL, LLM_ENDPOINT) provide the primary configuration method, requiring all three to be set simultaneously.
• .env files at the project root offer a file-based alternative that keeps secrets out of shell history, loaded automatically by LLMConfig.
• CLI commands (cognee config set) allow temporary in-process configuration for testing but do not persist to disk.
• The LLMConfig class in cognee/infrastructure/llm/config.py validates that configuration is complete, preventing partial setups that would cause authentication failures at runtime.

Frequently Asked Questions

What environment variables are required to configure the LLM API key in Cognee?

You must set three variables together: LLM_API_KEY for your provider's secret key, LLM_MODEL for the model identifier (e.g., openai/gpt-4o), and LLM_ENDPOINT for the API base URL. The LLMConfig validator in cognee/infrastructure/llm/config.py enforces an all-or-nothing policy; setting only one or two will raise a ValueError.

Can I use a .env file instead of exporting environment variables?

Yes. Cognee's LLMConfig class automatically reads from a .env file located at the project root because its model_config specifies env_file=".env". Place your LLM_API_KEY, LLM_MODEL, and LLM_ENDPOINT values in this file, and ensure .env is listed in .gitignore to prevent committing secrets.

Why does Cognee require all three LLM variables to be set together?

This design prevents partial configuration that would lead to cryptic runtime authentication errors. The validator in cognee/infrastructure/llm/config.py (lines 190-206) checks that llm_api_key, llm_model, and llm_endpoint are either all present or all absent. This guarantees that any LLM-dependent operation, such as embedding generation or document cognification, has complete credentials before executing.

How do I verify that my LLM API key is properly loaded in Cognee?

Import get_llm_config from cognee.infrastructure.llm.config and inspect the returned object. This cached singleton contains the validated configuration values. If the configuration is invalid, calling get_llm_config() will immediately raise a ValueError with details about the validation failure, allowing you to catch setup errors before running expensive LLM operations.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}