Repository Guidelines

This document summarizes how to work with the cognee repository: how it’s organized, how to build, test, lint, and contribute. It mirrors our actual tooling and CI while providing quick commands for local development.

Project Structure & Module Organization

• cognee/: Core Python library and API.
  • api/: FastAPI application and versioned routers (add, cognify, memify, search, delete, users, datasets, responses, visualize, settings, sync, update, checks).
  • cli/: CLI entry points and subcommands invoked via cognee / cognee-cli.
  • infrastructure/: Databases, LLM providers, embeddings, loaders, and storage adapters.
  • modules/: Domain logic (graph, retrieval, ontology, users, processing, observability, etc.).
  • tasks/: Reusable tasks (e.g., code graph, web scraping, storage). Extend with new tasks here.
  • eval_framework/: Evaluation utilities and adapters.
  • shared/: Cross-cutting helpers (logging, settings, utils).
  • tests/: Unit, integration, CLI, and end-to-end tests organized by feature.
  • __main__.py: Entrypoint to route to CLI.
• cognee-mcp/: Model Context Protocol server exposing cognee as MCP tools (SSE/HTTP/stdio). Contains its own README and Dockerfile.
• cognee-frontend/: Next.js UI for local development and demos.
• distributed/: Utilities for distributed execution (Modal, workers, queues).
• examples/: Example scripts demonstrating the public APIs and features (graph, code graph, multimodal, permissions, etc.).
• notebooks/: Jupyter notebooks for demos and tutorials.
• alembic/: Database migrations for relational backends.

Notes:

• Co-locate feature-specific helpers under their respective package (modules/, infrastructure/, or tasks/).
• Extend the system by adding new tasks, loaders, or retrievers rather than modifying core pipeline mechanisms.

Build, Test, and Development Commands

Python (root) – requires Python >= 3.10 and < 3.14. We recommend uv for speed and reproducibility.

• Create/refresh env and install dev deps:

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

• Run the CLI (examples):

uv run cognee-cli add "Cognee turns documents into AI memory."
uv run cognee-cli cognify
uv run cognee-cli search "What does cognee do?"
uv run cognee-cli -ui   # Launches UI, backend API, and MCP server together

• Start the FastAPI server directly:

uv run python -m cognee.api.client

• Run tests (CI mirrors these commands):

uv run pytest cognee/tests/unit/ -v
uv run pytest cognee/tests/integration/ -v

• Lint and format (ruff):

uv run ruff check .
uv run ruff format .

• Optional static type checks (ty):

uv run ty check .

MCP Server (cognee-mcp/):

• Install and run locally:

cd cognee-mcp
uv sync --dev --all-extras --reinstall
uv run python src/server.py               # stdio (default)
uv run python src/server.py --transport sse
uv run python src/server.py --transport http --host 127.0.0.1 --port 8000 --path /mcp

• API Mode (connect to a running Cognee API):

uv run python src/server.py --transport sse --api-url http://localhost:8000 --api-token YOUR_TOKEN

• Docker quickstart (examples): see cognee-mcp/README.md for full details

docker run -e TRANSPORT_MODE=http --env-file ./.env -p 8000:8000 --rm -it cognee/cognee-mcp:main

Frontend (cognee-frontend/):

cd cognee-frontend
npm install
npm run dev     # Next.js dev server
npm run lint    # ESLint
npm run build && npm start

Coding Style & Naming Conventions

Python:

• 4-space indentation, modules and functions in snake_case, classes in PascalCase.
• Public APIs should be type-annotated where practical. Make sure type defined in API signature will be properly displayed in Swagger UI docs. For example this definition: content_type: Optional[str] = Form(default=None) maps to "string" as the default in Swagger docs for content_type, but it should be None/null instead.
• Use ruff format before committing; ruff check enforces import hygiene and style (line-length 100 configured in pyproject.toml).
• Prefer explicit, structured error handling. Use shared logging utilities in cognee.shared.logging_utils.

MCP server and Frontend:

• Follow the local README.md and ESLint/TypeScript configuration in cognee-frontend/.

Testing Guidelines

• Place Python tests under cognee/tests/.
  • Unit tests: cognee/tests/unit/
  • Integration tests: cognee/tests/integration/
  • CLI tests: cognee/tests/cli_tests/
• Name test files test_*.py. Use pytest.mark.asyncio for async tests.
• Avoid external state; rely on test fixtures and the CI-provided env vars when LLM/embedding providers are required. See CI workflows under .github/workflows/ for expected environment variables.
• When adding public APIs, provide/update targeted examples under examples/python/.

Commit & Pull Request Guidelines

• Use clear, imperative subjects (≤ 72 chars) and conventional commit styling in PR titles. Our CI validates semantic PR titles (see .github/workflows/pr_lint). Examples:
  • feat(graph): add temporal edge weighting
  • fix(api): handle missing auth cookie
  • docs: update installation instructions
• Reference related issues/discussions in the PR body and provide brief context.
• PRs should describe scope, list local test commands run, and mention any impacts on MCP server or UI if applicable.
• Sign commits and affirm the DCO (see CONTRIBUTING.md).

CI Mirrors Local Commands

Our GitHub Actions run the same ruff checks and pytest suites shown above (.github/workflows/basic_tests.yml and related workflows). Use the commands in this document locally to minimize CI surprises.

Source: AGENTS.md