cognee: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Cognee is an open-source AI memory platform that transforms raw data into persistent knowledge graphs for AI agents. It replaces traditional RAG (Retrieval-Augmented Generation) with an ECL (Extract, Cognify, Load) pipeline combining vector search, graph databases, and LLM-powered entity extraction.

Requirements: Python 3.10 - 3.14

Design Principles

1. Don't overengineer: Simple beats complex.
2. No fallbacks: One correct path, no alternatives.
3. One way: One way to do things, not many.
4. Throw errors: Fail fast when the operation's preconditions aren't met. Observability (telemetry, logging) is best-effort and never changes the outcome of the operation.
5. No backups: Trust the primary mechanism.
6. Separation of concerns: Each function has a single responsibility.
7. Be concise but informative: No essays, but the docstrings and comments a reader needs.
8. No invented limits: Never add a cutoff (max_n, [:k], "older than X") or an expiry (TTL, cooldown, eviction) the task did not ask for — both are silent data loss. If you believe one is unavoidable, stop and ask, stating what would be dropped and why; never add it first and justify it afterwards. Existing bounds (lock leases, recovery floors, batch caps) are deliberate: removing or changing one is the same question.

Methodology: surgical changes only; evidence-based debugging (minimal, targeted logging); fix root causes, not symptoms. Debug like a detective: form the theory of the crime, collect evidence, and change code only once the evidence proves it.

Development Commands

Setup

# Create virtual environment (recommended: uv)
uv venv && source .venv/bin/activate

# Install with pip or uv
uv pip install -e .

# Install with dev dependencies
uv pip install -e ".[dev]"

# Install with specific extras
uv pip install -e ".[postgres,neo4j,docs]"

# Set up pre-commit hooks
pre-commit install