Package Management in the Cognee Monorepo

Cognee is organised as a small monorepo that contains three independent Python projects, each with its own pyproject.toml and dependency set.

Because every sub-project is self-contained you should always run your package-manager inside the directory you intend to work with.

Supported package managers

1. pip – works everywhere, nothing special.
2. uv – recommended for local development; extremely fast resolver/installer.
3. Poetry – fully compatible; useful if you already use it elsewhere.

Each project ships plain PEP 621 metadata (via hatchling) so nothing locks you in to a single tool.

Using uv

uv sync (and any other uv command) follows these rules:

• Looks for the nearest pyproject.toml.
• If it can’t find an active virtual environment it will create .venv/ inside that directory.
• The --reinstall flag wipes the target venv before reinstalling.

Common pitfall – invisible venv overwrite

Users sometimes already have a virtual environment active and then call

uv sync --dev --all-extras --reinstall

inside cognee-mcp/. uv happily creates/overwrites .venv/ in that folder which may “corrupt” the environment you were using.

Safe patterns

# Pattern 1 – Re-use your currently active venv (uv ≥ 0.6.14)
source /path/to/myenv/bin/activate        # or "conda activate …"
uv sync --dev --all-extras --reinstall --active

# Pattern 2 – Let uv install into a *separate* directory so nothing else is touched
cd cognee-mcp
python -m venv .venv-mcp                  # any name that isn't .venv
source .venv-mcp/bin/activate
uv sync --dev --all-extras               # uv detects the active venv

# Pattern 3 – Skip uv and fall back to pip
cd cognee-mcp
pip install -e ".[postgres,codegraph,gemini,huggingface,docs,neo4j]"

Using Poetry

If Poetry is already on your machine you can simply run:

poetry install --all-extras

in the project directory; Poetry will honour the same extras and dev-groups defined in pyproject.toml.

Tips & Troubleshooting

• Editor picks wrong interpreter – point VS Code / PyCharm to $(pwd)/.venv/bin/python (or whatever env you created).
• Docker builds – run uv sync --inexact --no-editable during the image build and copy the resulting .venv into the final image for faster layers.
• Only need a subset of extras? Use uv sync --extra postgres --extra chromadb instead of --all-extras.

Quick install commands

Heads-up: uv sync will create (or reset) a .venv in the current directory. If you already have a virtual-env you want to keep, activate it first and add --active.