Skip to main content
Cognee writes structured logs to two destinations simultaneously: the console and a log file. A new log file is created each time Cognee starts. The file captures everything from DEBUG upward. The console shows only the level you configure.

​
How Logging Works in Cognee

When you import or start Cognee, setup_logging() is called automatically. It configures two handlers:
  • Console handler — writes colored output to stderr, filtered by LOG_LEVEL (default: INFO)
  • File handler — writes plain text to a timestamped .log file, always at DEBUG level
One log file is created per startup and shared across all sub-processes. Cognee keeps the 10 most recent log files and deletes older ones automatically.
The default logs/ directory is created next to the cognee package directory, one level above it. The exact path depends on how Cognee is installed.Installed via pip (e.g. pip install cognee):
~/.venv/lib/python3.x/site-packages/logs/
Running from source (cloned repository):
<repo-root>/logs/
Using the MCP server: The MCP server uses the same logging setup. The log directory is the same as above, depending on your environment. When a background task is launched, the MCP server returns the full path to the active log file in its response.
When Cognee is installed via pip or used as an MCP server, log files end up inside your virtual environment’s site-packages/ directory. Set COGNEE_LOGS_DIR to write logs to a predictable location instead.

​
Controlling Logging

​
Environment Variables

  • COGNEE_LOGS_DIR — Absolute path to a custom log directory. Cognee creates it if it does not exist. Must be an absolute path — relative paths cause a startup error. Default: logs/ next to the cognee package.
  • LOG_LEVEL — Console log verbosity. One of DEBUG, INFO, WARNING, ERROR, CRITICAL. Default: INFO. Does not affect the log file, which always captures DEBUG and above.

​
Configuration Examples

# Write logs to a predictable absolute path
COGNEE_LOGS_DIR="/home/user/my-project/logs"

# Reduce console noise in production
LOG_LEVEL="ERROR"

# Show all output during development
LOG_LEVEL="DEBUG"

​
Fallback Behavior

If Cognee cannot write to COGNEE_LOGS_DIR, it falls back to /tmp/cognee_logs. If that also fails, file logging is skipped silently and only console output is produced.

​
Log Files and Their Content

​
File Format

Log files use plain text, one entry per line. Timestamps are in UTC: 
2025-02-14T15:32:47.123456 [WARNING ] From version 0.5.0 onwards... [cognee.shared.logging_utils]
2025-02-14T15:32:47.234567 [INFO    ] Log file created at: /path/to/logs/2025-02-14_15-32-47.log [cognee.shared.logging_utils]
2025-02-14T15:32:47.345678 [INFO    ] Logging initialized python_version=3.11.0 cognee_version=0.x.x os_info=... database_path=... graph_database_name=... vector_config=... relational_config=... [cognee.shared.logging_utils]
2025-02-14T15:32:47.456789 [INFO    ] Database storage: /path/to/.cognee_system/databases [cognee.shared.logging_utils]

​
Console Format

The console uses structlog’s colored renderer, written to stderr. Level colors: DEBUG blue, INFO green, WARNING yellow, ERROR and CRITICAL red.

​
What to Expect at Startup

Every time Cognee initializes, the following four messages are logged in order:
  1. WARNING — A notice that multi-user access control is on by default since version 0.5.0. This is expected and not an error.
  2. INFO — The full path to the log file created for this session.
  3. INFO — System metadata: Python version, Cognee version, OS, database paths, and the active graph, vector, and relational providers.
  4. INFO — The database storage path.
If messages 2–4 are missing from the console, file logging may have failed. Check whether the log directory is writable or set COGNEE_LOGS_DIR to a path you control.

​
File Naming

Each log file is named after the startup timestamp: 
YYYY-MM-DD_HH-MM-SS.log
Example: 2025-02-14_15-32-47.log

​
Troubleshooting

Run this snippet after importing cognee to get the exact path:
from cognee.shared.logging_utils import get_log_file_location
print(get_log_file_location())
Cognee falls back to console-only logging if the log directory is not writable. This is common in managed environments where site-packages/ is read-only.Set COGNEE_LOGS_DIR to an absolute path you own:
COGNEE_LOGS_DIR="/home/user/my-project/logs"

Overview

Return to setup configuration overview

Relational Databases

Configure metadata and state storage

Installation

Install Cognee and set up your environment