​
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.
DirectoryProject namePurpose
/cogneeCore library & SDK
cognee-mcp/cognee-mcpModel-Context-Protocol (MCP) server
cognee-starter-kit/cognee-starterMinimal starter template
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.

​
Note on psycopg2

Cognee supports both the source-built psycopg2 (requires a system pg_config) and the precompiled wheel psycopg2-binary. To give users explicit choice: When installing your Postgres extras, choose based on your environment:
  • Non-production/local dev environment: install the postgres-binary extra
# When using uv
uv sync --extra postgres-binary

# When using poetry
poetry install --extras postgres-binary
  • Production environment: install the postgres extra (requires pg_config)
# When using uv
uv sync --extra postgres

# When using poetry
poetry install --extras postgres
Without pg_config uv or poetry (all extras) may fail, therefore we suggest using postgres with pg_config installed.

​
Quick install commands

ContextCommand
End-users (pip)pip install cognee
Core devsuv sync --dev --all-extras in the project dir
MCP servercd cognee-mcp && uv sync --dev --all-extras --reinstall
Starter kitcd cognee-starter-kit && uv sync
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.