cognee: Instructions file for Claude Code

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.

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.

Project Structure & Module Organization

• cognee/: Core Python library and API.
  • api/: FastAPI application and versioned routers under api/v1/ — memory API (remember, recall, improve, forget), low-level operations (add, cognify, search, delete, update), and supporting routers (datasets, users, permissions, settings, sync, visualize, health, skills, sessions, …). Each router package has a routers/ folder; api/client.py registers them.
  • 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/deploy/: One-click deployment templates (Modal, Fly.io, Railway, Render, Daytona).
• examples/: Example scripts demonstrating the public APIs and features (graph, code graph, multimodal, permissions, etc.).
• notebooks/: Jupyter notebooks for demos and tutorials.
• .agents/skills/: Task-specific agent skills. This is the only copy; add and edit skills here (Codex reads this folder directly).
• .claude/skills/: Symlink to ../.agents/skills so Claude Code finds the same skills. On Windows clones without symlink support, the SessionStart hook in .claude/settings.json (.claude/hooks/link-skills.sh) replaces it with a directory junction automatically; no manual step is needed. That hook marks the path skip-worktree, so on those clones only, a later change to the .claude/skills entry itself makes git refuse to update it — run git update-index --no-skip-worktree .claude/skills && git checkout -- .claude/skills, then start a new session.
• cognee/alembic/: Relational (Alembic) schema migrations; alembic.ini is in cognee/. Graph/vector data migrations live in cognee/modules/migrations/.