cognee 1.5.2__tar.gz → 1.5.3.dev1__tar.gz

cognee-1.5.3.dev1/.env.template

@@ -0,0 +1,916 @@
+###############################################################################
+# TIER 1 — QUICK START
+# Set this one variable and you're done. Everything else has working defaults.
+# Default databases (SQLite, LanceDB, KuzuDB) are file-based, no setup needed.
+###############################################################################
+LLM_API_KEY="your_api_key"
+
+
+###############################################################################
+# TIER 2 — COMMON OVERRIDES (uncomment to customize)
+# Most users only need a few of these.
+###############################################################################
+
+# -- LLM Provider & Model ----------------------------------------------------
+#LLM_MODEL="openai/gpt-5-mini"
+#LLM_PROVIDER="openai"
+#LLM_ENDPOINT=""
+
+# -- Embedding Provider -------------------------------------------------------
+#EMBEDDING_PROVIDER="openai"
+#EMBEDDING_MODEL="openai/text-embedding-3-large"
+#EMBEDDING_DIMENSIONS=3072
+
+# -- Tokenizer (chunk sizing) -------------------------------------------------
+# The tokenizer used to count tokens for chunking is auto-selected to match the
+# embedding model: openai/gemini use TikToken, mistral uses the Mistral
+# tokenizer, and fastembed / openai-compatible models use the embedding model's
+# own HuggingFace tokenizer. cognee warns (and falls back to TikToken) when it
+# cannot match one, since a mismatched tokenizer mis-sizes chunks and skews the
+# --dry-run estimate. For providers whose model id is not a HuggingFace repo
+# (e.g. Ollama), set HUGGINGFACE_TOKENIZER to a tokenizer matching your model:
+#HUGGINGFACE_TOKENIZER="Salesforce/SFR-Embedding-Mistral"
+
+# -- Database Providers (switch from file-based defaults) ---------------------
+#DB_PROVIDER="postgres"
+#DB_HOST=127.0.0.1
+#DB_PORT=5432
+#DB_USERNAME=cognee
+#DB_PASSWORD=cognee
+#DB_NAME=cognee_db
+
+#GRAPH_DATABASE_PROVIDER="neo4j"
+#VECTOR_DB_PROVIDER="lancedb"
+
+
+###############################################################################
+# TIER 3 — ADVANCED (grouped by subsystem)
+# Most users never need to change anything below this line.
+###############################################################################
+
+################################################################################
+#  LLM — Advanced Settings
+#  Tune these when switching providers, adjusting structured output, or
+#  rate-limiting LLM calls.
+################################################################################
+
+# Structured output framework: "litellm_native" (default, plain litellm — schema-native
+# response_format with prompted-JSON fallback), "instructor" (legacy), or "baml"
+STRUCTURED_OUTPUT_FRAMEWORK="litellm_native"
+
+# Instructor's mode determines how structured data is extracted from LLM responses
+# (only used when STRUCTURED_OUTPUT_FRAMEWORK="instructor").
+# Each LLM has its own default (e.g. gpt-5 models use "json_schema_mode").
+#LLM_INSTRUCTOR_MODE=""
+
+# Cognee uses this to determine optimal chunk size (not forwarded in LLM calls).
+#LLM_MAX_COMPLETION_TOKENS="16384"
+
+# LLM API version (needed for Azure OpenAI)
+#LLM_API_VERSION=""
+
+# Extra kwargs passed to every LLM completion call (JSON string).
+# Examples: LLM_ARGS='{"max_tokens": 16384, "temperature": 0.7}'
+#LLM_ARGS='{}'
+
+# LLM rate limiting. When LLM_RATE_LIMIT_REQUESTS is not set, the limiter
+# budget defaults to 60 requests per interval for cloud providers and 10 for
+# serial local inference servers (Ollama, LM Studio, llama.cpp); vLLM
+# batches like a cloud endpoint and keeps the regular settings.
+#LLM_RATE_LIMIT_ENABLED=true
+#LLM_RATE_LIMIT_REQUESTS=60
+#LLM_RATE_LIMIT_INTERVAL=60
+# Run at full speed, but when LLM requests hit rate limits (or time out), log
+# a warning and turn on the RPM limiter (with the budget above) until issues
+# stop. On by default; set to false to opt out.
+#AUTO_RATE_LIMIT=true
+
+# Per-stage model routing (optional). Unset means the stage uses the base LLM_* config above.
+# Route a cheap or local model to extraction (it runs per chunk and dominates token use),
+# and keep a stronger model for summarization and query-time reasoning.
+#LLM_EXTRACTION_MODEL="ollama_chat/llama3.1"
+#LLM_EXTRACTION_PROVIDER="ollama"
+#LLM_EXTRACTION_ENDPOINT="http://localhost:11434"
+#LLM_EXTRACTION_API_KEY=""
+#LLM_SUMMARIZATION_MODEL="openai/gpt-5-mini"
+#LLM_SUMMARIZATION_PROVIDER="openai"
+#LLM_QUERY_MODEL="openai/gpt-5-mini"
+#LLM_QUERY_PROVIDER="openai"
+
+################################################################################
+#  Embedding — Advanced Settings
+#  Tune these when using non-default embedding providers.
+################################################################################
+
+#EMBEDDING_ENDPOINT=""
+#EMBEDDING_API_VERSION=""
+#EMBEDDING_MAX_COMPLETION_TOKENS=8191
+#EMBEDDING_BATCH_SIZE=36
+# If not provided, LLM_API_KEY is used for embeddings too.
+#EMBEDDING_API_KEY="your_api_key"
+
+################################################################################
+#  BAML Structured Output
+#  Only needed when STRUCTURED_OUTPUT_FRAMEWORK="baml".
+################################################################################
+
+#BAML_LLM_PROVIDER=openai
+#BAML_LLM_MODEL="gpt-5-mini"
+#BAML_LLM_ENDPOINT=""
+#BAML_LLM_API_KEY="your_api_key"
+#BAML_LLM_API_VERSION=""
+
+################################################################################
+#  Root Directories
+#  Override where Cognee stores files and databases (default: .venv).
+################################################################################
+
+#DATA_ROOT_DIRECTORY='/Users/<user>/Desktop/cognee/.cognee_data/'
+#SYSTEM_ROOT_DIRECTORY='/Users/<user>/Desktop/cognee/.cognee_system/'
+
+################################################################################
+#  Storage Backend
+#  Switch from local filesystem to S3.
+################################################################################
+
+#STORAGE_BACKEND="local"
+#STORAGE_BACKEND="s3"
+#STORAGE_BUCKET_NAME="your-bucket-name"
+#AWS_REGION="us-east-1"
+#AWS_ACCESS_KEY_ID="your-access-key"
+#AWS_SECRET_ACCESS_KEY="your-secret-key"
+#DATA_ROOT_DIRECTORY="s3://your-bucket/cognee/data"
+#SYSTEM_ROOT_DIRECTORY="s3://your-bucket/cognee/system"
+#CACHE_ROOT_DIRECTORY="s3://your-bucket/cognee/cache"
+
+################################################################################
+#  Relational Database — Advanced
+#  Connection tuning, pool sizes, SSL.
+################################################################################
+
+DB_PROVIDER="sqlite"
+DB_NAME=cognee_db
+
+# Custom connection arguments (JSON). Useful for SSL, timeouts.
+#DATABASE_CONNECT_ARGS='{"sslmode": "require", "connect_timeout": 10}'
+
+# Connection pool tuning (JSON).
+#POOL_ARGS='{"pool_size": 5, "max_overflow": 10, "pool_recycle": -1, "pool_timeout": 30}'
+
+# Turso (libSQL) — requires: pip install cognee"[turso]"
+# A libSQL database is SQLite-compatible, so Turso is a drop-in for the SQLite
+# backend (same aiosqlite driver, dialect and migrations).
+# Local / embedded (a libSQL file stored under the data dir, named by DB_NAME):
+#DB_PROVIDER="turso"
+# Remote Turso: also set DB_PROVIDER="turso", then point at a hosted database.
+# A local replica is kept in sync with the remote primary in the background.
+#DB_TURSO_URL="libsql://<your-db>.turso.io"
+#DB_TURSO_AUTH_TOKEN="<your-token>"
+
+################################################################################
+#  Graph Database — Advanced
+#  Provider-specific connection details.
+################################################################################
+
+GRAPH_DATABASE_PROVIDER="kuzu"
+# Handler for multi-user access control (per-dataset isolation).
+#   postgres_graph        -> one Postgres database per dataset (needs CREATE DATABASE)
+#   postgres_graph_shared -> one schema (ds_<dataset_id>) per dataset in the shared
+#                            Postgres database (needs only CREATE SCHEMA)
+GRAPH_DATASET_DATABASE_HANDLER="kuzu"
+
+# Remote Kuzu
+#GRAPH_DATABASE_PROVIDER="kuzu-remote"
+#GRAPH_DATABASE_URL="http://localhost:8000"
+#GRAPH_DATABASE_USERNAME=XXX
+#GRAPH_DATABASE_PASSWORD=YYY
+
+# Neo4j
+#GRAPH_DATABASE_PROVIDER="neo4j"
+#GRAPH_DATABASE_URL=bolt://localhost:7687
+#GRAPH_DATABASE_NAME="neo4j"
+#GRAPH_DATABASE_USERNAME=neo4j
+#GRAPH_DATABASE_PASSWORD=pleaseletmein
+
+# Neo4j Community + multi-user access control (per-dataset isolation without
+# Enterprise/Aura). Community edition allows only ONE database per server, so
+# this handler runs one Docker container per dataset (auto-start on access,
+# auto-stop when the dataset's engine leaves the LRU cache, data persisted on
+# a named volume). Requires a reachable Docker daemon.
+#GRAPH_DATABASE_PROVIDER="neo4j"
+#GRAPH_DATASET_DATABASE_HANDLER="neo4j_community"
+# Key used to encrypt the generated per-dataset passwords at rest (shared with
+# the neo4j_aura_dev handler).
+#NEO4J_ENCRYPTION_KEY="your_encryption_key"
+# Max concurrently RUNNING containers (default: DATABASE_MAX_LRU_CACHE_SIZE).
+#NEO4J_COMMUNITY_MAX_CONTAINERS=6
+# Docker image and startup wait.
+#NEO4J_COMMUNITY_IMAGE="neo4j:5-community"
+#NEO4J_COMMUNITY_STARTUP_TIMEOUT=120
+
+# Turso / libSQL (local, graph-as-tables over a single libSQL file — no extra
+# dependency; a libSQL file is a SQLite file, read through the aiosqlite driver).
+# GRAPH_DATABASE_URL is optional: set it to an absolute libSQL file path to
+# override the default location under the system databases directory.
+#GRAPH_DATABASE_PROVIDER="turso"
+#GRAPH_DATABASE_URL=/absolute/path/to/graph.db
+
+################################################################################
+#  Vector Database — Advanced
+#  Provider-specific connection details.
+################################################################################
+
+# Supported (built-in): pgvector | lancedb | turso
+# Community adapters (separate packages): qdrant | weaviate | milvus | chromadb
+VECTOR_DB_PROVIDER="lancedb"
+#VECTOR_DB_URL=
+#VECTOR_DB_KEY=
+# Handler for multi-user access control (per-dataset isolation).
+#   pgvector        -> one Postgres database per dataset (needs CREATE DATABASE)
+#   pgvector_shared -> one schema (ds_<dataset_id>) per dataset in the shared
+#                      Postgres database (needs only CREATE SCHEMA)
+VECTOR_DATASET_DATABASE_HANDLER="lancedb"
+
+# Turso / libSQL (requires the turso extra: pip install cognee"[turso]")
+# Embedded (local file):
+#VECTOR_DB_PROVIDER="turso"
+#VECTOR_DB_URL="/absolute/path/to/cognee.turso.db"
+# Remote Turso cloud:
+#VECTOR_DB_PROVIDER="turso"
+#VECTOR_DB_URL="libsql://your-db.turso.io"
+#VECTOR_DB_KEY="your_turso_auth_token"
+
+# Connection pool tuning for PGVector per-dataset engines (JSON).
+# When ENABLE_BACKEND_ACCESS_CONTROL=true each dataset gets its own engine; this controls
+# its pool size independently from POOL_ARGS (default: pool_size=2, max_overflow=2).
+#VECTOR_POOL_ARGS='{"pool_size": 2, "max_overflow": 5, "pool_recycle": 1800}'
+
+################################################################################
+#  Ontology Resolver
+#  Use when grounding extraction against an OWL ontology.
+################################################################################
+
+#ONTOLOGY_RESOLVER=rdflib
+#MATCHING_STRATEGY=fuzzy
+#ONTOLOGY_FILE_PATH=YOUR_FULL_FILE_PATH
+
+################################################################################
+#  Database Adapter Caching
+#  Max graph / vector / relational engine instances held in the LRU cache
+#  (one per unique connection key, e.g. per dataset in multi-tenant mode).
+#  In subprocess mode, this also caps how many child processes (Kuzu/LanceDB
+#  workers) can be alive at once — eviction shuts down the subprocess.
+#  Also the default for DATASET_QUEUE_MAX_CONCURRENT when that is unset.
+#  Engines of datasets currently admitted by the dataset queue are pinned and
+#  never evicted by capacity pressure; when every entry is pinned the cache
+#  briefly exceeds this size (bounded by DATASET_QUEUE_MAX_CONCURRENT).
+#  Lower values save memory; raise when running many datasets concurrently.
+################################################################################
+
+#DATABASE_MAX_LRU_CACHE_SIZE=6
+
+################################################################################
+#  Dataset Queue
+#  Semaphore-backed queue that limits how many datasets can be processed at
+#  once (cognify, search, etc.). Prevents resource exhaustion when many
+#  datasets run in parallel. When the limit is reached, new datasets wait
+#  until a slot is freed.
+################################################################################
+
+#DATASET_QUEUE_ENABLED=true
+# Max concurrent dataset slots. Defaults to DATABASE_MAX_LRU_CACHE_SIZE.
+#DATASET_QUEUE_MAX_CONCURRENT=6
+
+################################################################################
+#  Translation
+#  Use when ingesting non-English content.
+################################################################################
+
+TRANSLATION_PROVIDER="llm"
+TARGET_LANGUAGE="en"
+CONFIDENCE_THRESHOLD=0.8
+#GOOGLE_TRANSLATE_API_KEY="your-google-api-key"
+#GOOGLE_PROJECT_ID="your-google-project-id"
+#AZURE_TRANSLATOR_KEY="your-azure-translator-key"
+#AZURE_TRANSLATOR_REGION="westeurope"
+#AZURE_TRANSLATOR_ENDPOINT="https://api.cognitive.microsofttranslator.com"
+#TRANSLATION_BATCH_SIZE=10
+#TRANSLATION_MAX_RETRIES=3
+#TRANSLATION_TIMEOUT_SECONDS=30
+
+################################################################################
+#  Image Loader — OCR
+#  Append local OCR-extracted text to the image vision-LLM transcription.
+################################################################################
+
+# Enable an extra OCR pass when ingesting images (screenshots, scanned documents).
+# Requires the optional dependency: pip install "cognee[rapidocr]" (no system binary).
+#IMAGE_OCR_ENABLED="false"
+
+################################################################################
+#  Image Loader — Structured extraction
+################################################################################
+
+# Transcribe images with an extraction-oriented prompt (richer text for graph
+# extraction). On by default; set to "false" for the legacy caption prompt.
+#IMAGE_EXTRACTION_ENABLED="true"
+
+# Prompt template (in cognee/infrastructure/llm/prompts), token cap, and reasoning effort,
+# applied only when IMAGE_EXTRACTION_ENABLED is on.
+#IMAGE_TRANSCRIPTION_PROMPT_PATH="transcribe_image_prompt.txt"
+#IMAGE_TRANSCRIPTION_MAX_COMPLETION_TOKENS="1024"
+#IMAGE_TRANSCRIPTION_REASONING_EFFORT="low" # minimal | low | medium | high
+
+################################################################################
+#  Data Migrations (graph/vector revision chain)
+################################################################################
+
+# Cognee runs its data migrations automatically on startup (FastAPI lifespan,
+# first remember()/cognify() call in an SDK process). Set to false to disable
+# ALL automatic runs and migrate explicitly via `cognee-cli upgrade` instead
+# (e.g. operator-driven deployments, or tests on deliberately old-format data).
+#ENABLE_AUTO_MIGRATIONS=true
+
+################################################################################
+#  Migration (Relational -> Graph)
+################################################################################
+
+MIGRATION_DB_PATH="/path/to/migration/directory"
+MIGRATION_DB_NAME="migration_database.sqlite"
+MIGRATION_DB_PROVIDER="sqlite"
+#MIGRATION_DB_USERNAME=cognee
+#MIGRATION_DB_PASSWORD=cognee
+#MIGRATION_DB_HOST="127.0.0.1"
+#MIGRATION_DB_PORT=5432
+
+################################################################################
+#  Security
+################################################################################
+
+# -- JWT Authentication -------------------------------------------------------
+# Secret used to sign and verify JWT tokens. Must be the same across all instances
+# (e.g. all Kubernetes pods) for tokens issued by one instance to be accepted by another.
+# Change this to a long random string in production. Never commit the real value to git.
+FASTAPI_USERS_JWT_SECRET="super_secret"
+
+# How long a JWT token remains valid, in seconds. After expiry the user must log in again.
+# The same lifetime applies to both cookie and bearer token auth.
+# Default: 3600 (1 hour)
+JWT_LIFETIME_SECONDS=3600
+
+# -- API Key Authentication ---------------------------------------------------
+# When HASH_API_KEY=true, API keys are hashed with SHA-256 before being stored in the database.
+# This means the raw key is shown to the user only once at creation time and cannot be recovered.
+#
+# ⚠️  Migration note: if you enable this on a running system that already has API keys stored
+#     in plaintext, those existing keys will stop working immediately because the lookup will
+#     hash the incoming value and find no match. You must either:
+#       1. Delete and re-issue all existing API keys, or
+#       2. Write a one-off migration to SHA-256 hash the existing api_key column values.
+#
+# Default: false (keys are stored in plaintext)
+HASH_API_KEY="False"
+
+# When set to false don't allow adding of local system files to Cognee. Should be set to False when Cognee is used as a backend.
+ACCEPT_LOCAL_FILE_PATH=True
+ALLOW_HTTP_REQUESTS=True
+ALLOW_CYPHER_QUERY=True
+RAISE_INCREMENTAL_LOADING_ERRORS=True
+
+########## Recall tool calls (text-to-SQL on authorized databases) ###########
+# Master gate for recall(scope=["tools"]). Default OFF: recall never executes
+# LLM-generated SQL against an external database unless a deployment opts in.
+# The "tools" scope is explicit per call — never implied by scope="auto"/"all".
+#TOOL_CALLS_ENABLED=false
+#
+# Register connections per user with cognee.tools.register_sql_connection(...)
+# (the DSN is AES-256-GCM encrypted at rest — requires the integrations
+# keyring, e.g. INTEGRATION_CREDENTIALS_KEYS='{"1": "<base64 32-byte key>"}').
+# Alternatively, deployment-level connections visible to EVERY authenticated
+# caller (single-tenant only!) can be configured via JSON:
+#TOOL_SQL_CONNECTIONS='{"analytics": {"connection_string": "postgresql://ro_user:pw@host:5432/analytics", "allowed_tables": ["orders"], "max_rows": 100}}'
+#
+# Always point connections at a SELECT-only database role: cognee enforces a
+# SELECT-only SQL guard and read-only, rollback-only execution, but the DB
+# role is the final safety layer.
+#TEXT_TO_SQL_MAX_ROWS=100
+#TEXT_TO_SQL_MAX_ATTEMPTS=3
+#TEXT_TO_SQL_STATEMENT_TIMEOUT_MS=5000
+#TEXT_TO_SQL_MAX_SCHEMA_TABLES=50
+#
+# Write-back (correction proposals). Separate gate, also default OFF. Even
+# when enabled, writes are approval-gated: a proposal (single UPDATE with a
+# mandatory WHERE, dry-run affected-row estimate) is stored for review and
+# executes only via cognee.tools.apply_write_proposal(...). The connection
+# must additionally be registered with allow_writes=True, on a role with
+# UPDATE grants scoped to the correctable tables.
+#TOOL_WRITE_CALLS_ENABLED=false
+#TEXT_TO_SQL_MAX_AFFECTED_ROWS=50
+
+########## Recall warm-up short-circuit ########################################
+# When the target datasets have never been through any pipeline, recall's
+# graph lane returns a single "memory_warming_up" marker entry (or, in
+# multi-source recalls, an empty graph contribution) instead of running the
+# search machinery. Warm verdicts are cached in-process for the TTL; cold
+# verdicts are re-probed on every recall.
+#RECALL_WARMUP_SHORTCIRCUIT=true
+#RECALL_WARMUP_THRESHOLD=1
+#RECALL_WARMUP_CACHE_TTL=60
+
+# Authentication & access control.
+#
+# ENABLE_BACKEND_ACCESS_CONTROL is the canonical posture switch:
+#   true  (default) - multi-tenant mode: per-user/dataset isolated DBs AND
+#                     API endpoints require an authenticated user.
+#   false           - single-user mode: shared DB AND auth requirement off.
+#
+# REQUIRE_AUTHENTICATION is an explicit override on the auth requirement only:
+#   unset (default) - follow ENABLE_BACKEND_ACCESS_CONTROL.
+#   true            - force auth on (sane for single-user behind a token).
+#   false           - force auth off — IGNORED if ENABLE_BACKEND_ACCESS_CONTROL
+#                     is true (multi-tenant always requires auth; a warning is
+#                     logged at startup).
+#
+# Startup logs an "auth posture: ..." line with the resolved decision so you
+# can verify what's actually in effect.
+REQUIRE_AUTHENTICATION=False
+
+# Set this variable to True to enforce usage of backend access control for Cognee
+# Note: This is only currently supported by the following databases:
+#       Relational: SQLite, Postgres
+#       Vector: LanceDB, pgvector
+#       Graph: KuzuDB, neo4j_aura_dev
+#
+# It enforces creation of databases per Cognee user + dataset. Does not work with some graph and database providers.
+# Disable mode when using not supported graph/vector databases.
+ENABLE_BACKEND_ACCESS_CONTROL=True
+
+################################################################################
+#  Cloud Sync
+################################################################################
+
+COGNEE_CLOUD_API_URL="http://localhost:8001"
+COGNEE_CLOUD_AUTH_TOKEN="your-api-key"
+
+################################################################################
+#  UI
+################################################################################
+
+UI_APP_URL=http://localhost:3000
+
+################################################################################
+#  DLT Ingestion
+################################################################################
+
+#DLT_MAX_ROWS_PER_TABLE=50
+
+################################################################################
+#  Dev / Debug
+################################################################################
+
+ENV="local"
+#ENABLE_LAST_ACCESSED="false"
+TOKENIZERS_PARALLELISM="false"
+
+# -- Search History ------------------------------------------------------------
+# Set to false to disable search query/result logging (recommended for daemons)
+#COGNEE_LOG_SEARCH_HISTORY="true"
+
+# LITELLM Logging Level. Set to quiet down logging
+LITELLM_LOG="ERROR"
+#TELEMETRY_DISABLED=1
+#DEFAULT_USER_EMAIL=""
+#DEFAULT_USER_PASSWORD=""
+
+# -- Cognee Logging -----------------------------------------------------------
+# Console log level: DEBUG, INFO, WARNING, ERROR, CRITICAL (default: INFO)
+#LOG_LEVEL="INFO"
+# Set to false to disable file logging entirely (console-only)
+#COGNEE_LOG_FILE="true"
+# Override the log directory (default: ~/.cognee/logs)
+#COGNEE_LOGS_DIR="/var/log/cognee"
+# Max size per log file before rotation, in bytes (default: 50 MB)
+#COGNEE_LOG_MAX_BYTES=52428800
+# Number of rotated log files to keep (default: 5 → 300 MB total cap)
+#COGNEE_LOG_BACKUP_COUNT=5
+
+################################################################################
+#  AWS
+################################################################################
+
+#AWS_REGION=""
+#AWS_ENDPOINT_URL=""
+#AWS_ACCESS_KEY_ID=""
+#AWS_SECRET_ACCESS_KEY=""
+#AWS_SESSION_TOKEN=""
+
+################################################################################
+#  Web Scraper
+################################################################################
+
+WEB_SCRAPER_TIMEOUT=15.0
+WEB_SCRAPER_MAX_DELAY=10.0
+
+# -- API-based URL fetching. Tavily is used when TAVILY_API_KEY is set,
+#    otherwise Keenable when KEENABLE_API_KEY is set, otherwise the default crawler.
+#TAVILY_API_KEY=""
+#KEENABLE_API_KEY=""
+#KEENABLE_BASE_URL="https://api.keenable.ai"
+#KEENABLE_LIVE_FETCH="false"
+
+################################################################################
+#  OpenTelemetry / Tracing
+################################################################################
+
+# -- To export traces to an OTLP-compatible backend (Dash0, Grafana, Jaeger, etc.),
+#    set the endpoint and optional auth headers: ---------------------
+# COGNEE_TRACING_ENABLED=true
+# OTEL_EXPORTER_OTLP_ENDPOINT="https://ingress.eu-west.dash0.com:4317"
+# OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer <your-token>"
+
+# Override the service name reported in traces (default: "cognee")
+# OTEL_SERVICE_NAME="cognee"
+
+# Add extra resource attributes (useful for Kubernetes, multi-instance deployments)
+# OTEL_RESOURCE_ATTRIBUTES="service.namespace=my-team,service.version=1.0"
+
+# -- Langfuse rides the same OTLP pipeline (no separate SDK). Setting these keys
+#    builds the OTLP endpoint + Basic-auth header and turns tracing on; LLM calls
+#    show up as generations. Optional and off by default. Requires cognee[tracing]. --
+# LANGFUSE_PUBLIC_KEY="pk-lf-..."
+# LANGFUSE_SECRET_KEY="sk-lf-..."
+# Defaults to https://cloud.langfuse.com; set for a region or self-hosted instance.
+# LANGFUSE_BASE_URL is accepted as an alias when LANGFUSE_HOST is unset.
+# LANGFUSE_HOST="https://us.cloud.langfuse.com"
+
+# Session cache settings
+# To switch to Redis caching check our documentation page sessions-and-caching
+# CACHING=true
+# Backends: sqlite (default), postgres, redis, fs, tapes
+# CACHE_BACKEND=sqlite
+# CACHE_BACKEND=postgres
+# Optional explicit SQLAlchemy async URL for the sqlite/postgres backends.
+# sqlite default: cache.db next to the relational SQLite database.
+# postgres default: falls back to DB_* settings when DB_PROVIDER=postgres.
+# CACHE_DB_URL=sqlite+aiosqlite:///path/to/databases/cache.db
+# CACHE_DB_URL=postgresql+asyncpg://cognee:cognee@localhost:5432/cognee_db
+# Minimum seconds between global TTL purge sweeps (sqlite/postgres backends)
+# CACHE_PURGE_INTERVAL_SECONDS=900
+
+
+################################################################################
+#  ADDITIONAL MANAGED SETTINGS (previously undocumented)
+#  These are all read by Cognee's config classes (pydantic BaseSettings) but
+#  were missing from this template. Defaults shown; uncomment to override.
+################################################################################
+
+# -- LLM tuning ---------------------------------------------------------------
+# Sampling temperature, sent with every LLM call when set. Leave unset to use
+# the provider's default — note gpt-5 models reject any value other than 1.
+# Exception: on local inference servers (Ollama, llama.cpp, LM Studio) an unset
+# value sends 0.0, since those accept the field and extraction needs
+# deterministic output. Set a value explicitly to override.
+#LLM_TEMPERATURE=0.0
+# Sampling seed for reproducible outputs, sent when set (provider support varies).
+#LLM_SEED=42
+#LLM_STREAMING=false
+# Optional fallback model used when the primary completion fails.
+#FALLBACK_MODEL=""
+#FALLBACK_API_KEY=""
+#FALLBACK_ENDPOINT=""
+# Audio transcription model.
+#TRANSCRIPTION_MODEL="whisper-1"
+
+# -- Embedding rate limiting (mirrors the LLM_RATE_LIMIT_* knobs) -------------
+#EMBEDDING_RATE_LIMIT_ENABLED=false
+#EMBEDDING_RATE_LIMIT_REQUESTS=60
+#EMBEDDING_RATE_LIMIT_INTERVAL=60
+#EMBEDDING_RATE_LIMIT_TOKENS=0
+# Token-based LLM limit (0 = disabled; requests/interval already documented above).
+#LLM_RATE_LIMIT_TOKENS=0
+
+# -- Chunking -----------------------------------------------------------------
+#CHUNK_SIZE=1500
+#CHUNK_OVERLAP=10
+#CHUNK_STRATEGY="paragraph"
+
+# -- Triplet embedding (extra triplet-level vectors during cognify) -----------
+#TRIPLET_EMBEDDING=false
+
+# -- Contradiction detection (opt-in LLM check at the end of cognify) ---------
+# When on, cognify compares the facts this ingestion touched against the facts
+# already stored around them and records each conflict as a "contradicts" edge.
+# Applies to remember() too, which builds its graph through cognify().
+# Default off — when off the cognify pipeline is unchanged.
+#CONTRADICTION_DETECTION=false
+# Minimum LLM confidence required to flag a pair as contradictory.
+#CONTRADICTION_CONFIDENCE_THRESHOLD=0.5
+# Cap on the facts sent to the LLM in a single check (the rest are logged and skipped).
+#CONTRADICTION_MAX_FACTS=500
+
+# -- Session cache (Redis backend + session/usage tuning) ---------------------
+# Used when CACHE_BACKEND=redis; also the host/port for a remote cache.
+#CACHE_HOST="localhost"
+#CACHE_PORT=6379
+#CACHE_USERNAME=""
+#CACHE_PASSWORD=""
+# Session lifetime in the cache (default 7 days) and per-turn context cap.
+# Set to 0 to disable expiry entirely: rows are stored without an expiry and
+# nothing is ever purged — sliding-TTL writes are skipped too, which is the
+# lightest-I/O setting for long-lived agent sessions on the SQLite backend.
+#SESSION_TTL_SECONDS=604800
+#MAX_SESSION_CONTEXT_CHARS=
+# Self-improvement: absorb per-turn feedback/guidance automatically (default on).
+#AUTO_FEEDBACK=true
+# Session-search execution mode. concurrent (default) analyzes the turn
+# concurrently with retrieval and answering, so a turn costs one answer call of
+# wall-clock time; sequential analyzes first and lets the analysis rewrite the
+# retrieval query and update context before the answer is generated.
+#SESSION_SEARCH_MODE=concurrent
+# Per-process LLM usage logging into the cache.
+#USAGE_LOGGING=false
+#USAGE_LOGGING_TTL=604800
+# Cross-process locks for file-based embedded graph backends.
+#SHARED_KUZU_LOCK=false
+#SHARED_LADYBUG_LOCK=false
+
+# -- Per-user preference personalization ---------------------------------------
+# Master switch: personalize retrieval ranking and prompts from each user's
+# per-dataset preference node. Off by default so a default deployment stays
+# byte-identical to today.
+#PERSONALIZATION_ENABLED=false
+# The most personalization may move a ranking score, as a fraction: 0.3 means
+# at most 30%. Valid range [0, 1] — values outside it are rejected at startup
+# (above 1 the ranking factor would go negative and invert order among
+# preferred items).
+#PERSONALIZATION_INFLUENCE=0.3
+# How far one 1-5 rating pulls a personal prefers-edge weight toward its
+# target (higher = more reactive). Valid range (0, 1] — zero would silently
+# stop learning, so it is rejected at startup.
+#PREFERENCE_ALPHA=0.3
+# How much an untouched prefers-edge weight fades toward neutral per
+# conversation turn — decay is counted in turns, not wall-clock time. Valid
+# range [0, 1) — values outside it are rejected at startup.
+#PREFERENCE_BETA=0.02
+
+# -- Graph database — advanced connection / Kuzu tuning -----------------------
+#GRAPH_DATABASE_HOST=""
+#GRAPH_DATABASE_PORT=
+#GRAPH_DATABASE_KEY=""
+#GRAPH_DATABASE_ALLOW_ANONYMOUS=false
+# Run the embedded graph engine (Kuzu/Ladybug) in a worker subprocess.
+#GRAPH_DATABASE_SUBPROCESS_ENABLED=true
+# Kuzu performance tuning (0/auto by default).
+#KUZU_NUM_THREADS=0
+#KUZU_BUFFER_POOL_SIZE=
+#KUZU_MAX_DB_SIZE=
+
+# -- Vector database — advanced connection ------------------------------------
+#VECTOR_DB_HOST=""
+#VECTOR_DB_PORT=1234
+#VECTOR_DB_NAME=""
+#VECTOR_DB_USERNAME=""
+#VECTOR_DB_PASSWORD=""
+#VECTOR_DB_SUBPROCESS_ENABLED=true
+
+# -- Database subprocess workers — advanced tuning ----------------------------
+# The embedded DB engines (Kuzu/Ladybug graph, LanceDB vector) run their native
+# client in a dedicated worker process. These knobs tune that harness.
+# Per-RPC deadline guarding against a hung native call (seconds; <=0 disables).
+#SUBPROCESS_CALL_TIMEOUT=300
+# How many times a failed subprocess RPC is retried (respawning the worker).
+#SUBPROCESS_MAX_RETRIES=2
+# Backstop for the brief window where one graph worker is still releasing a
+# file lock while another opens the same DB path: the worker retries the open
+# this many times, with exponential backoff starting at this many seconds
+# (per-attempt backoff is capped internally).
+#SUBPROCESS_OPEN_LOCK_RETRIES=10
+#SUBPROCESS_OPEN_LOCK_BACKOFF=0.1
+# Keep idle workers alive this many seconds before closing them (0 = close at
+# each release). Idle workers hold their DB file locks and memory.
+#SUBPROCESS_IDLE_TTL_SECONDS=600
+
+# -- AWS / Bedrock extras (in addition to the AWS section above) --------------
+#AWS_PROFILE_NAME=""
+#AWS_BEDROCK_RUNTIME_ENDPOINT=""
+
+# -- Local llama.cpp provider -------------------------------------------------
+#LLAMA_CPP_MODEL_PATH=""
+#LLAMA_CPP_N_CTX=2048
+#LLAMA_CPP_N_GPU_LAYERS=0
+#LLAMA_CPP_CHAT_FORMAT="chatml"
+
+# -- Security: additional auth-token secrets ----------------------------------
+# Like FASTAPI_USERS_JWT_SECRET above, these default to the INSECURE value
+# "super_secret". Override BOTH with long random strings in production.
+#FASTAPI_USERS_VERIFICATION_TOKEN_SECRET="change_me_in_production"
+#FASTAPI_USERS_RESET_PASSWORD_TOKEN_SECRET="change_me_in_production"
+
+
+################################################################################
+#  Integrations
+#  Third-party OAuth integrations (cognee/modules/integrations/). Each
+#  provider registers itself at startup; one whose secrets are left unset
+#  responds 503 "not configured" to connect attempts and rejects inbound
+#  webhooks, so unset deployments effectively cannot use it. See
+#  cognee/api/v1/integrations/routers/get_integrations_router.py for the
+#  generic install-flow endpoints every provider shares.
+################################################################################
+
+# -- Slack ---------------------------------------------------------------------
+# Create a Slack app at https://api.slack.com/apps to get these values.
+# CLIENT_ID/CLIENT_SECRET: OAuth & Permissions > your app's Basic Information.
+# SIGNING_SECRET: Basic Information > App Credentials — verifies inbound
+# requests (slash commands, events, interactive callbacks) via X-Slack-Signature.
+# REDIRECT_URI: must match a URL registered under OAuth & Permissions >
+# Redirect URLs exactly, and point at this server's
+# /api/v1/integrations/slack/callback.
+# FRONTEND_BASE_URL: where the browser is redirected back to after
+# connect/cancel/error (appends ?slack=<outcome> to /integrations).
+#SLACK_CLIENT_ID=""
+#SLACK_CLIENT_SECRET=""
+#SLACK_SIGNING_SECRET=""
+#SLACK_REDIRECT_URI="http://localhost:8000/api/v1/integrations/slack/callback"
+#SLACK_FRONTEND_BASE_URL="http://localhost:3000"
+
+# -- GitHub --------------------------------------------------------------------
+# Create a GitHub App at https://github.com/settings/apps to get these values.
+# Required app configuration: "Request user authorization (OAuth) during
+# installation" enabled; Callback URL pointing at this server's
+# /api/v1/integrations/github/callback; Webhook URL pointing at
+# /api/v1/integrations/github/events; repository permission
+# "Contents: Read-only"; subscribed events: Push, Installation repositories.
+# APP_ID: the numeric id from the app settings page.
+# APP_SLUG: the app's URL slug (github.com/apps/<slug>).
+# APP_PRIVATE_KEY: the app's PEM private key ("\n" escapes accepted).
+# WEBHOOK_SECRET: verifies inbound deliveries via X-Hub-Signature-256, and
+# signs the OAuth state parameter.
+#GITHUB_APP_ID=""
+#GITHUB_APP_SLUG=""
+#GITHUB_APP_PRIVATE_KEY=""
+#GITHUB_CLIENT_ID=""
+#GITHUB_CLIENT_SECRET=""
+#GITHUB_WEBHOOK_SECRET=""
+#GITHUB_FRONTEND_BASE_URL="http://localhost:3000"
+
+# -- Linear --------------------------------------------------------------------
+# Create a Linear OAuth app at https://linear.app/settings/api/applications.
+# This is an *agent* app: the authorize URL uses actor=app, which installs an
+# app user into the workspace that members can @mention or delegate issues to
+# — the agent answers from cognee memory. Enable "Agent session events" on
+# the app and point its webhook URL at this server's
+# /api/v1/integrations/linear/events.
+# CLIENT_ID/CLIENT_SECRET: from the app's settings page.
+# WEBHOOK_SECRET: the app's webhook signing secret — verifies inbound
+# deliveries via the Linear-Signature header, and signs the OAuth state
+# parameter.
+# REDIRECT_URI: must match a callback URL registered on the app exactly, and
+# point at this server's /api/v1/integrations/linear/callback.
+# FRONTEND_BASE_URL: where the browser is redirected back to after
+# connect/cancel/error (appends ?linear=<outcome> to /integrations).
+#LINEAR_CLIENT_ID=""
+#LINEAR_CLIENT_SECRET=""
+#LINEAR_WEBHOOK_SECRET=""
+#LINEAR_REDIRECT_URI="http://localhost:8000/api/v1/integrations/linear/callback"
+#LINEAR_FRONTEND_BASE_URL="http://localhost:3000"
+
+
+################################################################################
+#  Docker / MCP Runtime
+#  Configure the cognee API image (cognee/cognee) and the MCP image
+#  (cognee/cognee-mcp) when running `docker run` / `docker compose`.
+#  Unless noted "read by the app", these are consumed by the container
+#  entrypoints/compose and have defaults baked into the images — set them only
+#  to override. (docker-compose.yml already sets sensible values for most.)
+################################################################################
+
+# -- API server (cognee/cognee image) ----------------------------------------
+# CORS allow-list for the FastAPI server: comma-separated origins. Read by the
+# app (cognee/api/client.py). Default '*' (all origins) — set explicit domains
+# in production.
+#CORS_ALLOWED_ORIGINS="https://yourdomain.com,https://another.com"
+# Server bind/port inside the container (entrypoint defaults shown).
+#HTTP_PORT=8000
+#BIND_ADDRESS=0.0.0.0
+
+# -- MCP server (cognee/cognee-mcp image) -------------------------------------
+# Transport the MCP container serves. The Docker image reads TRANSPORT_MODE;
+# the direct `cognee-mcp` CLI uses --transport instead.
+#TRANSPORT_MODE=stdio          # stdio | sse | http
+# Comma-separated optional extras to pip-install at container startup.
+#EXTRAS=aws,postgres
+# MCP "API mode": point the MCP server at an already-running cognee API server.
+#API_URL=http://localhost:8000
+#API_TOKEN=""
+# MCP "Cloud mode": point the MCP server at a managed Cognee Cloud instance.
+# These are the canonical cloud-connection variables, shared across serve(),
+# push(), the MCP server, and sync. COGNEE_CLOUD_API_URL / COGNEE_CLOUD_AUTH_TOKEN
+# (above) remain as deprecated fallbacks.
+#COGNEE_SERVICE_URL=""
+#COGNEE_API_KEY=""
+
+# -- Debug (both images) ------------------------------------------------------
+# DEBUG=true together with ENV in {dev,local} starts the container under
+# debugpy, listening on DEBUG_PORT. ENV is the canonical environment variable
+# (set it in the Dev/Debug section above); ENVIRONMENT is a deprecated alias
+# still accepted by the container entrypoints.
+#DEBUG=false
+#DEBUG_PORT=5678
+
+# -- Frontend (cognee-frontend image / compose `ui` profile) ------------------
+#NEXT_PUBLIC_BACKEND_API_URL=http://localhost:8000
+
+
+###############################################################################
+# TIER 4 — EXAMPLE PROVIDER OVERRIDES (commented out)
+# Uncomment + fill values to switch providers.
+###############################################################################
+
+########## Azure OpenAI (API key auth) ########################################
+#LLM_PROVIDER="azure"
+#LLM_MODEL="azure/gpt-5-mini"
+#LLM_ENDPOINT="https://YOUR-RESOURCE.openai.azure.com"
+#LLM_API_KEY="your-azure-api-key"
+#LLM_API_VERSION="2024-12-01-preview"
+#LLM_MAX_COMPLETION_TOKENS="16384"
+
+########## Azure OpenAI (managed identity / DefaultAzureCredential) ###########
+# Uses DefaultAzureCredential - no API key needed (for Azure VMs, App Service, etc.)
+# Requires: pip install azure-identity
+#LLM_PROVIDER="azure"
+#LLM_MODEL="azure/gpt-5-mini"
+#LLM_ENDPOINT="https://YOUR-RESOURCE.openai.azure.com"
+#LLM_API_VERSION="2024-12-01-preview"
+#LLM_AZURE_USE_MANAGED_IDENTITY=true
+
+#EMBEDDING_MODEL="azure/text-embedding-3-large"
+#EMBEDDING_ENDPOINT="https://YOUR-RESOURCE.openai.azure.com/openai/deployments/text-embedding-3-large"
+#EMBEDDING_API_KEY="your-azure-api-key"
+#EMBEDDING_API_VERSION="2024-12-01-preview"
+#EMBEDDING_DIMENSIONS=3072
+#EMBEDDING_MAX_COMPLETION_TOKENS=8191
+
+########## Local LLM via Ollama ###############################################
+#LLM_API_KEY ="ollama"
+#LLM_MODEL="llama3.1:8b"
+#LLM_PROVIDER="ollama"
+#LLM_ENDPOINT="http://localhost:11434/v1"
+#EMBEDDING_PROVIDER="ollama"
+#EMBEDDING_MODEL="nomic-embed-text:latest"
+#EMBEDDING_ENDPOINT="http://localhost:11434/api/embed"
+#EMBEDDING_DIMENSIONS=768
+#HUGGINGFACE_TOKENIZER="nomic-ai/nomic-embed-text-v1.5"
+
+########## OpenRouter (has a free tier) #######################################
+# One API key, hundreds of models. Get a key at https://openrouter.ai/keys.
+# Model ids change over time — OpenRouter adds and retires models, and the
+# free (":free") tier rotates especially fast — so treat the id below as an
+# example and confirm a current one before using it:
+#   curl -s https://openrouter.ai/api/v1/models | jq -r '.data[].id'
+# Prefix the slug you pick with "openrouter/" so LiteLLM routes it.
+#LLM_API_KEY="sk-or-..."
+#LLM_PROVIDER="custom"
+#LLM_MODEL="openrouter/deepseek/deepseek-r1"
+#LLM_ENDPOINT="https://openrouter.ai/api/v1"
+# Embeddings must be configured too. Setting only the LLM_* vars above leaves
+# EMBEDDING_* on the OpenAI defaults, so the LLM connects fine and ingestion
+# then fails at embedding time on a missing or invalid OpenAI key.
+# OpenRouter does serve embedding models, but they are a separate catalogue —
+# the /models call above does NOT list them. List them with:
+#   curl -s https://openrouter.ai/api/v1/embeddings/models | jq -r '.data[].id'
+# Pointing EMBEDDING_* at OpenAI or a local provider instead works just as
+# well. EMBEDDING_DIMENSIONS must be set explicitly: "custom" models are not
+# in the auto-derive registry and otherwise fall back to 3072, which causes a
+# vector-store shape mismatch. Leave EMBEDDING_ENDPOINT unset — the
+# "openrouter/" prefix already tells LiteLLM the base URL.
+#EMBEDDING_PROVIDER="custom"
+#EMBEDDING_MODEL="openrouter/openai/text-embedding-3-small"
+#EMBEDDING_API_KEY="sk-or-..."
+#EMBEDDING_DIMENSIONS=1536
+
+########## DeepInfra ##########################################################
+#LLM_API_KEY="<<>>"
+#LLM_PROVIDER="custom"
+#LLM_MODEL="deepinfra/meta-llama/Meta-Llama-3-8B-Instruct"
+#LLM_ENDPOINT="https://api.deepinfra.com/v1/openai"
+#EMBEDDING_PROVIDER="openai"
+#EMBEDDING_API_KEY="<<>>"
+#EMBEDDING_MODEL="deepinfra/BAAI/bge-base-en-v1.5"
+#EMBEDDING_ENDPOINT=""
+#EMBEDDING_API_VERSION=""
+#EMBEDDING_DIMENSIONS=3072
+#EMBEDDING_MAX_COMPLETION_TOKENS=8191
+
+########## MCP sampling (reuse the host harness LLM, no API key) ##############
+# Only for running cognee AS an MCP server (cognee-mcp) inside a host that
+# grants the `sampling` capability. LLM completions are delegated to the host
+# via `sampling/createMessage`, so no LLM_API_KEY is needed. Structured output
+# is done by embedding the JSON Schema in the prompt and validating/repairing
+# the reply (the protocol returns free text only).
+# Host support varies: as of early 2026 Claude Code does NOT yet grant sampling
+# (github.com/anthropics/claude-code/issues/1785); check your host's MCP docs.
+# Note: embeddings are NOT covered by sampling; set an embedding provider (or a
+# local one) if you use vector search. Falls back to a clear error when no host
+# sampling session is available.
+#LLM_PROVIDER="mcp-sampling"
+#LLM_MODEL="host-default"  # hint only; the host chooses the actual model