cognee.config

Static class for configuring Cognee’s runtime settings. All setters persist for the duration of the process (or until overridden). Use cognee.config.set(...) for supported runtime-safe settings inside a Python process. Cognee can also be configured through .env or process environment variables before import. Use those for process-level settings such as auth, logging, cache backend, storage backend, telemetry, API server settings, and deployment credentials. For the full environment variable reference and precedence rules, see Setup Configuration.

Configuration Types

LLM Configuration

cognee.config.set_llm_provider("openai")          # "openai", "anthropic", "ollama", "gemini", "mistral", "bedrock"
cognee.config.set_llm_model("gpt-4o-mini")
cognee.config.set_llm_api_key("sk-...")
cognee.config.set_llm_endpoint("https://custom-endpoint.example.com")

# Or set all at once — keys must match LLMConfig attribute names exactly
cognee.config.set_llm_config({
    "llm_provider": "openai",
    "llm_model": "gpt-4o",
    "llm_api_key": "sk-...",
})

set_llm_config() keys must match the internal attribute names on LLMConfig. The exact internal attributes name are displayed in the table below.

Internal LLM Configuration attributes

Key	Type	Default	Description
`structured_output_framework`	`str`	`"litellm_native"`	Structured output backend: `"litellm_native"`, `"instructor"`, or `"baml"`. See Structured Output Backends
`llm_instructor_mode`	`str`	`""`	Instructor `Mode` string (e.g. `"json_schema_mode"`, `"json_mode"`, `"tool_call"`). Empty = provider default
`llm_provider`	`str`	`"openai"`	Provider: `"openai"`, `"anthropic"`, `"ollama"`, `"gemini"`, `"mistral"`, `"bedrock"`, `"azure"`, `"custom"`
`llm_model`	`str`	`"openai/gpt-5.6-luna"`	Model identifier
`llm_api_key`	`str`	`None`	API key for the provider
`llm_endpoint`	`str`	`""`	Custom endpoint URL (required for Ollama, vLLM, etc.)
`llm_api_version`	`str`	`None`	API version (required for Azure)
`llm_temperature`	`float`	unset	Response temperature (0.0–2.0). Takes effect via the `LLM_TEMPERATURE` env var when you set it explicitly — leave it unset and nothing is sent, so the provider’s default applies rather than `0.0`. Local inference servers (`ollama`, `llama_cpp`, and LM Studio models, identified by an `lm_studio/` prefix) are the exception: there an unset value is folded in as `0.0`. Setting it through `set_llm_config()` has no effect; at runtime use `llm_args` instead. gpt-5 models (including the default `openai/gpt-5.6-luna`) reject any temperature but their own default
`llm_seed`	`int`	`None`	Sampling seed for reproducible outputs. Takes effect via the `LLM_SEED` env var; setting it through `set_llm_config()` has no effect — at runtime use `llm_args` instead. Provider support varies
`llm_streaming`	`bool`	`False`	Legacy flag, and not the one that streams recall’s answer. It reaches only the OpenAI, Azure, and Bedrock adapters on the `instructor` path, where nothing consumes a token stream — and because it is part of the adapter cache key, flipping it rebuilds the adapter. For a streamed answer use `llm_answer_streaming`
`llm_answer_streaming`	`bool`	`False`	Stream the answer tokens of recall’s final answer call to a client reading the REST API’s SSE response (env `LLM_ANSWER_STREAMING`). Inert unless a client is reading that stream — the returned value is identical either way. Supported on the default `litellm_native` backend; on `instructor` only by the OpenAI-compatible adapters (`openai`, `custom`, and Azure without managed identity), and never by `baml`
`llm_max_completion_tokens`	`int`	`16384`	Maximum tokens in the response
`llm_args`	`dict`	`{}`	Arbitrary provider-specific kwargs merged into every LLM call. Set as a JSON string in `.env` (e.g. `LLM_ARGS='{"top_p": 0.9}'`). The `LLM_TEMPERATURE` and `LLM_SEED` env vars are folded in here at startup, and a `temperature`/`seed` key set directly in `llm_args` takes precedence over them — this is also the key to use for temperature/seed with `set_llm_config()`
`llm_rate_limit_enabled`	`bool`	`False`	Enable client-side rate limiting for LLM calls
`llm_rate_limit_requests`	`int`	`60`	Max LLM requests allowed per interval
`llm_rate_limit_interval`	`int`	`60`	Duration of the rate limit window in seconds
`llm_rate_limit_tokens`	`int`	`0`	Max tokens per interval (`0` = disabled)

Embedding Configuration

cognee.config.set_embedding_provider("fastembed")
cognee.config.set_embedding_model("BAAI/bge-small-en-v1.5")
cognee.config.set_embedding_dimensions(384)

# Or set all at once — keys must match EmbeddingConfig attribute names exactly
cognee.config.set_embedding_config({
    "embedding_provider": "fastembed",
    "embedding_model": "BAAI/bge-small-en-v1.5",
    "embedding_dimensions": 384,
})

Internal Embedding Configuration attributes

Key	Type	Default	Description
`embedding_provider`	`str`	`"openai"`	Provider: `"openai"`, `"ollama"`, `"fastembed"`, `"gemini"`, `"mistral"`, `"bedrock"`, `"custom"`
`embedding_model`	`str`	`"openai/text-embedding-3-large"`	Model identifier
`embedding_dimensions`	`int`	`3072`	Vector dimension size (must match your vector store)
`embedding_api_key`	`str`	`None`	API key (falls back to `LLM_API_KEY` if unset)
`embedding_endpoint`	`str`	`None`	Custom endpoint URL
`embedding_api_version`	`str`	`None`	API version
`embedding_max_completion_tokens`	`int`	`None` — `4096`	Ceiling on input tokens per embedded text. `None` means `4096`; the effective limit is the lower of this and the embedding model’s own input limit
`embedding_batch_size`	`int`	`36`	Batch size for embedding requests
`huggingface_tokenizer`	`str`	`None`	HuggingFace Hub model ID for token counting with Ollama
`embedding_rate_limit_enabled`	`bool`	`False`	Enable client-side rate limiting for embedding calls
`embedding_rate_limit_requests`	`int`	`60`	Max embedding requests allowed per interval
`embedding_rate_limit_interval`	`int`	`60`	Duration of the rate limit window in seconds
`embedding_rate_limit_tokens`	`int`	`0`	Max tokens per interval (`0` = disabled)

Graph Database Configuration

cognee.config.set_graph_database_provider("kuzu")  # "kuzu", "neo4j", "kuzu-remote", "neptune", "neptune_analytics"

# Keys must match GraphConfig attribute names exactly
cognee.config.set_graph_db_config({
    "graph_database_provider": "neo4j",
    "graph_database_url": "bolt://localhost:7687",
    "graph_database_username": "neo4j",
    "graph_database_password": "password",
})

Vector Database Configuration

cognee.config.set_vector_db_provider("lancedb")    # "lancedb", "pgvector", "qdrant", "chromadb"
cognee.config.set_vector_db_url("http://localhost:6333")
cognee.config.set_vector_db_key("your-key")

# Keys must match VectorConfig attribute names exactly
cognee.config.set_vector_db_config({
    "vector_db_provider": "qdrant",
    "vector_db_url": "http://localhost:6333",
    "vector_db_key": "...",
})

Chunking Configuration

cognee.config.set_chunk_size(1024)
cognee.config.set_chunk_overlap(128)
cognee.config.set_chunk_strategy("PARAGRAPH")      # "EXACT", "PARAGRAPH", "SENTENCE", "CODE"
cognee.config.set_chunk_engine("DEFAULT_ENGINE")    # "DEFAULT_ENGINE", "LANGCHAIN_ENGINE"

Model Configuration

cognee.config.set_classification_model(MyClassifier)
cognee.config.set_summarization_model(MySummarizer)
cognee.config.set_graph_model(MyGraphModel)

Other Settings

cognee.config.system_root_directory("/custom/path")
cognee.config.data_root_directory("/data/path")
cognee.config.set_translation_provider("google")  # "llm", "google", "azure"
cognee.config.set_translation_target_language("en")

# Generic setter for supported keys
cognee.config.set("llm_model", "openai/gpt-5-mini")

# Generic getters for the same keys
cognee.config.get("llm_model")                    # "openai/gpt-5-mini"
cognee.config.get_all()                           # dict of every known setting

Reading configuration

get(key) returns the current value of any key set() accepts, and get_all() returns all of them as a dict. Both mask secret values (llm_api_key, embedding_api_key, vector_db_key) by default, keeping only the first three and last four characters as a hint (values of eight characters or fewer are masked entirely); pass reveal_secrets=True to get the raw value. get() raises InvalidConfigAttributeError for an unrecognized key.

cognee.config.get("llm_api_key")                       # "sk-...c3d4"
cognee.config.get("llm_api_key", reveal_secrets=True)  # "sk-proj-9f2a7b41c3d4"

cognee.config.get_all(reveal_secrets=True)             # unmasked dict

Persisting a value to `.env`

set() normally only updates the in-process configuration. Pass persist=True to also write the resolved value into the .env file this process loaded, so it is picked up by the next process that resolves the same file. That target may be a file pinned with COGNEE_ENV_FILE or a .env found in a parent directory — see How .env Is Loaded. Only when no .env was resolved does it fall back to .env in the current working directory, creating it if missing. This is what cognee-cli config set does. When persisting, set() returns a dict describing where the value was written:

cognee.config.set("llm_model", "openai/gpt-5-mini", persist=True)
# {"path": "/home/you/project/.env", "created": True, "env_var": "LLM_MODEL"}

Without persist=True, set() returns None and changes nothing on disk.

Persisting a secret writes it in plaintext to the .env this process loaded, which may sit in a parent directory rather than the one you are running from. Check the returned path (or the resolved-.env line in the startup log) to see where it landed, keep that file out of version control, and restrict its permissions.

cognee.config.set(key, value) is not a free-form setter. Use it for supported runtime-safe settings such as LLMs, embeddings, graph/vector databases, chunking, model overrides, and root directories. Use .env, shell variables, deployment variables, or pre-import os.environ for process-level settings such as auth, logging, cache backend, storage backend, API server settings, telemetry, and cloud credentials.

All Configuration Methods

Configuration Methods

Method	Description
`set_llm_provider(provider)`	Set the LLM provider
`set_llm_model(model)`	Set the LLM model name
`set_llm_api_key(key)`	Set the LLM API key
`set_llm_endpoint(url)`	Set a custom LLM endpoint
`set_llm_config(dict)`	Set all LLM config at once
`set_embedding_provider(provider)`	Set the embedding provider
`set_embedding_model(model)`	Set the embedding model name
`set_embedding_dimensions(dimensions)`	Set embedding vector dimensions
`set_embedding_endpoint(url)`	Set a custom embedding endpoint
`set_embedding_api_key(key)`	Set the embedding API key
`set_embedding_config(dict)`	Set all embedding config at once
`set_graph_database_provider(provider)`	Set the graph DB provider
`set_relational_db_config(dict)`	Set relational DB config
`set_migration_db_config(dict)`	Set migration DB config
`set_graph_db_config(dict)`	Set all graph DB config
`set_vector_db_provider(provider)`	Set the vector DB provider
`set_vector_db_url(url)`	Set the vector DB URL
`set_vector_db_key(key)`	Set the vector DB API key
`set_vector_db_config(dict)`	Set all vector DB config
`set_chunk_size(size)`	Set chunk size in tokens
`set_chunk_overlap(overlap)`	Set chunk overlap
`set_chunk_strategy(strategy)`	Set chunking strategy
`set_chunk_engine(engine)`	Set chunking engine
`set_classification_model(model)`	Set classification model
`set_summarization_model(model)`	Set summarization model
`set_graph_model(model)`	Set graph extraction model
`system_root_directory(path)`	Set system root directory
`data_root_directory(path)`	Set data root directory
`monitoring_tool(tool)`	Set the monitoring tool
`set_translation_provider(provider)`	Set translation provider
`set_translation_target_language(lang)`	Set translation target language
`set_translation_config(dict)`	Set translation config
`set(key, value, persist=False)`	Generic config setter. With `persist=True`, also writes the value to the `.env` this process loaded (falling back to `.env` in the current directory when none was resolved) and returns `{"path", "created", "env_var"}`
`get(key, reveal_secrets=False)`	Generic config getter. Secret values are masked unless `reveal_secrets=True`
`get_all(reveal_secrets=False)`	Return every known setting as a dict. Secret values are masked unless `reveal_secrets=True`

​cognee.config

​Configuration Types

​Reading configuration

​Persisting a value to .env

​All Configuration Methods

cognee.config

Configuration Types

Reading configuration

Persisting a value to `.env`

All Configuration Methods