# Table of Contents - [Introduction - Cognee Documentation](#introduction-cognee-documentation) - [Add - Cognee Documentation](#add-cognee-documentation) - [Local Mode & Sync - Cognee Documentation](#local-mode-sync-cognee-documentation) - [Cognee Cloud Architecture - Cognee Documentation](#cognee-cloud-architecture-cognee-documentation) - [Sign Up & Prerequisites - Cognee Documentation](#sign-up-prerequisites-cognee-documentation) - [Cognee Cloud Notebooks - Cognee Documentation](#cognee-cloud-notebooks-cognee-documentation) - [Cognee Cloud UI - Cognee Documentation](#cognee-cloud-ui-cognee-documentation) - [Cursor - Cognee Documentation](#cursor-cognee-documentation) - [Claude Code - Cognee Documentation](#claude-code-cognee-documentation) - [Deployment Overview - Cognee Documentation](#deployment-overview-cognee-documentation) - [Permissions & Security - Cognee Documentation](#permissions-security-cognee-documentation) - [Overview - Cognee Documentation](#overview-cognee-documentation) - [Quickstart - Cognee Documentation](#quickstart-cognee-documentation) - [Roo Code - Cognee Documentation](#roo-code-cognee-documentation) - [Continue - Cognee Documentation](#continue-cognee-documentation) - [Cline - Cognee Documentation](#cline-cognee-documentation) - [Evaluation with DeepEval - Cognee Documentation](#evaluation-with-deepeval-cognee-documentation) - [Modal Deployment - Cognee Documentation](#modal-deployment-cognee-documentation) - [Python API Documentation - Cognee Documentation](#python-api-documentation-cognee-documentation) - [Observability with Keywords AI - Cognee Documentation](#observability-with-keywords-ai-cognee-documentation) - [Cognee Cloud SDK - Cognee Documentation](#cognee-cloud-sdk-cognee-documentation) - [Observability with Langfuse - Cognee Documentation](#observability-with-langfuse-cognee-documentation) - [Local Setup - Cognee Documentation](#local-setup-cognee-documentation) - [AWS Bedrock Integration - Cognee Documentation](#aws-bedrock-integration-cognee-documentation) - [Tools Reference - Cognee Documentation](#tools-reference-cognee-documentation) - [Agent Memory with LangGraph - Cognee Documentation](#agent-memory-with-langgraph-cognee-documentation) - [Integrations - Cognee Documentation](#integrations-cognee-documentation) - [Quickstart - Cognee Documentation](#quickstart-cognee-documentation) - [Kubernetes (Helm) - Cognee Documentation](#kubernetes-helm-cognee-documentation) - [Cognee CLI Overview - Cognee Documentation](#cognee-cli-overview-cognee-documentation) - [Cognee Cloud Overview - Cognee Documentation](#cognee-cloud-overview-cognee-documentation) - [EC2 Deployment - Cognee Documentation](#ec2-deployment-cognee-documentation) - [Pipelines - Cognee Documentation](#pipelines-cognee-documentation) - [Tasks - Cognee Documentation](#tasks-cognee-documentation) - [Cognify - Cognee Documentation](#cognify-cognee-documentation) - [Memify - Cognee Documentation](#memify-cognee-documentation) - [Ontologies - Cognee Documentation](#ontologies-cognee-documentation) - [Code Assistants - Cognee Documentation](#code-assistants-cognee-documentation) - [Human Resources - Cognee Documentation](#human-resources-cognee-documentation) - [NodeSets - Cognee Documentation](#nodesets-cognee-documentation) - [Chatbots - Cognee Documentation](#chatbots-cognee-documentation) - [Search - Cognee Documentation](#search-cognee-documentation) - [Datasets - Cognee Documentation](#datasets-cognee-documentation) - [Adapters Overview - Cognee Documentation](#adapters-overview-cognee-documentation) - [DataPoints - Cognee Documentation](#datapoints-cognee-documentation) - [Add - Cognee Documentation](#add-cognee-documentation) - [Installation - Cognee Documentation](#installation-cognee-documentation) - [Documentation Intelligence - Cognee Documentation](#documentation-intelligence-cognee-documentation) - [Structured Output Backends - Cognee Documentation](#structured-output-backends-cognee-documentation) - [Architecture - Cognee Documentation](#architecture-cognee-documentation) - [LLM Providers - Cognee Documentation](#llm-providers-cognee-documentation) - [Graph Stores - Cognee Documentation](#graph-stores-cognee-documentation) - [Relational Databases - Cognee Documentation](#relational-databases-cognee-documentation) - [Embedding Providers - Cognee Documentation](#embedding-providers-cognee-documentation) - [ACL - Cognee Documentation](#acl-cognee-documentation) - [Principals - Cognee Documentation](#principals-cognee-documentation) - [Tenants - Cognee Documentation](#tenants-cognee-documentation) - [Overview - Cognee Documentation](#overview-cognee-documentation) - [Roles - Cognee Documentation](#roles-cognee-documentation) - [Users - Cognee Documentation](#users-cognee-documentation) - [Qdrant - Cognee Documentation](#qdrant-cognee-documentation) - [Overview - Cognee Documentation](#overview-cognee-documentation) - [Permissions Setup - Cognee Documentation](#permissions-setup-cognee-documentation) - [Datasets - Cognee Documentation](#datasets-cognee-documentation) - [Custom Tasks and Pipelines - Cognee Documentation](#custom-tasks-and-pipelines-cognee-documentation) - [Setup Configuration - Cognee Documentation](#setup-configuration-cognee-documentation) - [Vector Stores - Cognee Documentation](#vector-stores-cognee-documentation) - [Custom Data Models - Cognee Documentation](#custom-data-models-cognee-documentation) - [Custom Prompts - Cognee Documentation](#custom-prompts-cognee-documentation) - [Graph Visualization - Cognee Documentation](#graph-visualization-cognee-documentation) - [S3 Storage - Cognee Documentation](#s3-storage-cognee-documentation) - [Low-Level LLM - Cognee Documentation](#low-level-llm-cognee-documentation) - [Ontology Quickstart - Cognee Documentation](#ontology-quickstart-cognee-documentation) - [Code Graph - Cognee Documentation](#code-graph-cognee-documentation) - [Distributed Execution - Cognee Documentation](#distributed-execution-cognee-documentation) - [Memify Quickstart - Cognee Documentation](#memify-quickstart-cognee-documentation) - [Temporal Cognify - Cognee Documentation](#temporal-cognify-cognee-documentation) - [Deploy REST API Server - Cognee Documentation](#deploy-rest-api-server-cognee-documentation) - [Cognee Walkthrough - Cognee Documentation](#cognee-walkthrough-cognee-documentation) - [Search Basics - Cognee Documentation](#search-basics-cognee-documentation) - [Feedback System - Cognee Documentation](#feedback-system-cognee-documentation) - [Permission Snippets - Cognee Documentation](#permission-snippets-cognee-documentation) - [Page Not Found](#page-not-found) - [Page Not Found](#page-not-found) - [Client Integrations - Cognee Documentation](#client-integrations-cognee-documentation) - [Cognee Cloud - Cognee Documentation](#cognee-cloud-cognee-documentation) --- # Introduction - Cognee Documentation [Skip to main content](https://docs.cognee.ai/getting-started/introduction#content-area) [Cognee Documentation home page![light logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20black.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=ea48b52be1df02b5909f780e6cd6856e)![dark logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20white.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=9f5bc18c4897c6e58b5cfa2b09bc079d)](https://docs.cognee.ai/) Search... ⌘K Search... Navigation Getting Started Introduction [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) ![How does AI memory work?](https://mintcdn.com/cognee/SLlciL7PTYZfGdB1/images/how-does-ai-memory-work.png?w=2500&fit=max&auto=format&n=SLlciL7PTYZfGdB1&q=85&s=06682afcd72a23bb9d76a94d04273d0d) Give Cognee your documents, and it creates a graph of raw information, extracted concepts, and meaningful relationships you can query. [​](https://docs.cognee.ai/getting-started/introduction#why-ai-memory-matters) Why AI memory matters ------------------------------------------------------------------------------------------------------- When you call an LLM, each request is stateless: it doesn’t remember what happened in the last call, and it doesn’t know about the rest of your documents. That makes it hard to build applications that actually use your documents and carry context forward. You need a memory layer that can link your documents together and create the right context for every LLM call. [​](https://docs.cognee.ai/getting-started/introduction#how-cognee-works) How Cognee works --------------------------------------------------------------------------------------------- When it comes to your data, Cognee knows what matters. There are three key operations in Cognee: * **`.add` — Prepare for cognification** Send in your data asynchronously. Cognee cleans and prepares your data so that the memory layer can be created. * **`.cognify` — Build a knowledge graph with embeddings** Cognee splits your documents into chunks, extract entities, relations, and links it all into a queryable graph, that serves as the basis for the memory layer. * **`.search` — Query with context** Queries combine vector similarity with graph traversal. Depending on the mode, cognee can fetch raw nodes, explore relationships, or generate natural-language answers through RAG. It always creates the right context for the LLM. * **`.memify` — Semantic enrichment of the graph** _(coming soon, stay tuned)_ Enhance the knowledge graph with semantic understanding and deeper contextual relationships. [​](https://docs.cognee.ai/getting-started/introduction#ready-to-get-started) Ready to get started? ------------------------------------------------------------------------------------------------------ [Set up your environment\ -----------------------\ \ **Installation Guide**Set up your environment and install Cognee to start building AI memory.](https://docs.cognee.ai/getting-started/installation) [Run your first example\ ----------------------\ \ **Quickstart Tutorial**Get started with Cognee by running your first knowledge graph example.](https://docs.cognee.ai/getting-started/quickstart) [Keep exploring\ --------------\ \ **Core Concepts**Dive deeper into Cognee’s powerful features and capabilities.](https://docs.cognee.ai/core-concepts/overview) Was this page helpful? YesNo [InstallationSet up your environment and install Cognee\ \ Next](https://docs.cognee.ai/getting-started/installation) ⌘I On this page * [Why AI memory matters](https://docs.cognee.ai/getting-started/introduction#why-ai-memory-matters) * [How Cognee works](https://docs.cognee.ai/getting-started/introduction#how-cognee-works) * [Ready to get started?](https://docs.cognee.ai/getting-started/introduction#ready-to-get-started) --- # Add - Cognee Documentation [Skip to main content](https://docs.cognee.ai/api-reference/add/add#content-area) [Cognee Documentation home page![light logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20black.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=ea48b52be1df02b5909f780e6cd6856e)![dark logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20white.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=9f5bc18c4897c6e58b5cfa2b09bc079d)](https://docs.cognee.ai/) Search... ⌘K Search... Navigation add Add [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) POST https://api.cognee.aihttp://localhost:8000 / api / v1 / add Try it Add cURL Copy curl --request POST \ --url https://api.cognee.ai/api/v1/add \ --header 'Content-Type: multipart/form-data' \ --form 'datasetName=' \ --form datasetId= 200 422 Copy {} #### Body multipart/form-data [​](https://docs.cognee.ai/api-reference/add/add#body-data) data file\[\] List of files to upload (max 10MB per file, max 10 files) Maximum length: `10` [​](https://docs.cognee.ai/api-reference/add/add#body-dataset-name) datasetName string | null [​](https://docs.cognee.ai/api-reference/add/add#body-dataset-id) datasetId string | nullstring | null Examples: `""` #### Response 200 application/json Successful Response The response is of type `object`. Was this page helpful? YesNo [Previous](https://docs.cognee.ai/api-reference/auth/verify:verify) [CognifyTransform datasets into structured knowledge graphs through cognitive processing. This endpoint is the core of Cognee's intelligence layer, responsible for converting raw text, documents, and data added through the add endpoint into semantic knowledge graphs. It performs deep analysis to extract entities, relationships, and insights from ingested content. ## Processing Pipeline 1. Document classification and permission validation 2. Text chunking and semantic segmentation 3. Entity extraction using LLM-powered analysis 4. Relationship detection and graph construction 5. Vector embeddings generation for semantic search 6. Content summarization and indexing ## Request Parameters - \*\*datasets\*\* (Optional\[List\[str\]\]): List of dataset names to process. Dataset names are resolved to datasets owned by the authenticated user. - \*\*dataset\_ids\*\* (Optional\[List\[UUID\]\]): List of existing dataset UUIDs to process. UUIDs allow processing of datasets not owned by the user (if permitted). - \*\*run\_in\_background\*\* (Optional\[bool\]): Whether to execute processing asynchronously. Defaults to False (blocking). ## Response - \*\*Blocking execution\*\*: Complete pipeline run information with entity counts, processing duration, and success/failure status - \*\*Background execution\*\*: Pipeline run metadata including pipeline\_run\_id for status monitoring via WebSocket subscription ## Error Codes - \*\*400 Bad Request\*\*: When neither datasets nor dataset\_ids are provided, or when specified datasets don't exist - \*\*409 Conflict\*\*: When processing fails due to system errors, missing LLM API keys, database connection failures, or corrupted content ## Example Request \`\`\`json { "datasets": \["research\_papers", "documentation"\], "run\_in\_background": false } \`\`\` ## Notes To cognify data in datasets not owned by the user and for which the current user has write permission, the dataset\_id must be used (when ENABLE\_BACKEND\_ACCESS\_CONTROL is set to True). ## Next Steps After successful processing, use the search endpoints to query the generated knowledge graph for insights, relationships, and semantic search.\ \ Next](https://docs.cognee.ai/api-reference/cognify/cognify) ⌘I Add cURL Copy curl --request POST \ --url https://api.cognee.ai/api/v1/add \ --header 'Content-Type: multipart/form-data' \ --form 'datasetName=' \ --form datasetId= 200 422 Copy {} --- # Local Mode & Sync - Cognee Documentation [Skip to main content](https://docs.cognee.ai/cognee-cloud/local-mode-and-sync#content-area) [Cognee Documentation home page![light logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20black.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=ea48b52be1df02b5909f780e6cd6856e)![dark logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20white.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=9f5bc18c4897c6e58b5cfa2b09bc079d)](https://docs.cognee.ai/) Search... ⌘K Search... Navigation Cognee Cloud Platform Local Mode & Sync [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) Cognee Cloud can connect to your local Cognee instance, allowing you to work with local data through the cloud interface and sync between environments. [​](https://docs.cognee.ai/cognee-cloud/local-mode-and-sync#local-mode) Local Mode ------------------------------------------------------------------------------------- Cognee Cloud automatically detects and connects to local Cognee instances: * **Connection Status**: When connected, the “Local Cognee” section shows “Connected” in the UI * **Full Functionality**: Browse datasets, upload files, run cognify, and execute notebook cells against your local engine * **Same Interface**: All operations use the same UI whether working with local or cloud data Local mode requires a running Cognee server on `localhost:8000`. Start your local server with `cognee serve` to enable local mode features. [​](https://docs.cognee.ai/cognee-cloud/local-mode-and-sync#data-sync) Data Sync ----------------------------------------------------------------------------------- Cognee Cloud provides powerful sync capabilities for moving data between local and cloud environments: ### [​](https://docs.cognee.ai/cognee-cloud/local-mode-and-sync#sync-features) Sync Features * **Binary file handling** — Upload and download files for data connectors * **Hash-based synchronization** — Only syncs files that have changed, reducing unnecessary transfers * **Dataset-specific storage** — Files are organized by dataset with proper isolation ### [​](https://docs.cognee.ai/cognee-cloud/local-mode-and-sync#how-sync-works) How sync works 1. **Detect changes** — Compare file hashes to identify what needs to be synchronized 2. **Upload changes** — Transfer only modified files to the target environment 3. **Verify integrity** — Confirm files are properly stored and accessible 4. **Update metadata** — Sync dataset information and permissions **Sync is currently experiencing issues and is under construction.** Some sync features may not work as expected. We’re working to resolve these problems and will update this documentation once sync is fully operational. [​](https://docs.cognee.ai/cognee-cloud/local-mode-and-sync#related-resources) Related resources --------------------------------------------------------------------------------------------------- [Cognee Cloud architecture\ -------------------------\ \ Understand how Cognee Cloud pipelines stay online once you migrate.](https://docs.cognee.ai/cognee-cloud/cognee-cloud-architecture) [Permissions & Security\ ----------------------\ \ Map local user roles to Cognee Cloud workspaces and dataset permissions.](https://docs.cognee.ai/cognee-cloud/permissions-security) Was this page helpful? YesNo [Previous](https://docs.cognee.ai/cognee-cloud/cognee-cloud-sdk) [Permissions & SecurityDataset isolation and security features in Cognee Cloud\ \ Next](https://docs.cognee.ai/cognee-cloud/permissions-security) ⌘I On this page * [Local Mode](https://docs.cognee.ai/cognee-cloud/local-mode-and-sync#local-mode) * [Data Sync](https://docs.cognee.ai/cognee-cloud/local-mode-and-sync#data-sync) * [Sync Features](https://docs.cognee.ai/cognee-cloud/local-mode-and-sync#sync-features) * [How sync works](https://docs.cognee.ai/cognee-cloud/local-mode-and-sync#how-sync-works) * [Related resources](https://docs.cognee.ai/cognee-cloud/local-mode-and-sync#related-resources) --- # Cognee Cloud Architecture - Cognee Documentation [Skip to main content](https://docs.cognee.ai/cognee-cloud/cognee-cloud-architecture#content-area) [Cognee Documentation home page![light logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20black.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=ea48b52be1df02b5909f780e6cd6856e)![dark logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20white.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=9f5bc18c4897c6e58b5cfa2b09bc079d)](https://docs.cognee.ai/) Search... ⌘K Search... Navigation Cognee Cloud Platform Cognee Cloud Architecture [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) Cognee Cloud layers orchestration and managed services on top of the open-source Cognee storage model. This document explains how the main components fit together. Behind the scenes, every pipeline step runs as a Modal job that talks to managed LanceDB, Kuzu, and PostgreSQL clusters. [​](https://docs.cognee.ai/cognee-cloud/cognee-cloud-architecture#system-overview) System Overview ----------------------------------------------------------------------------------------------------- Cognee Cloud’s architecture centers around three main layers that work together to provide a managed knowledge processing platform: ### [​](https://docs.cognee.ai/cognee-cloud/cognee-cloud-architecture#modal-managed-infrastructure) Modal (Managed Infrastructure) Modal provides the compute foundation for all Cognee Cloud operations: * **API Services**: Hosts the FastAPI service that handles all REST endpoints and authentication (see [Cognee Cloud SDK](https://docs.cognee.ai/cognee-cloud/cognee-cloud-sdk) ) * **Notebook Sandbox**: Provides isolated environments for running user code with 24-hour timeout support (see [Cognee Cloud Notebooks](https://docs.cognee.ai/cognee-cloud/cognee-cloud-notebooks) ) * **Container Orchestration**: Every API request runs inside a Modal container with secrets managed internally by Cognee Cloud * **Code Execution**: Notebook code runs in short-lived sandboxes that forward the user’s Cognee Cloud API key to the managed API This infrastructure ensures reliable, scalable execution while keeping all compute resources managed by Cognee Cloud. ### [​](https://docs.cognee.ai/cognee-cloud/cognee-cloud-architecture#storage-services-managed-by-cognee-cloud) Storage Services (Managed by Cognee Cloud) All data persistence is handled through Cognee Cloud’s managed storage infrastructure: * **S3** – Central storage for all raw uploads, LanceDB tables, and Kuzu graph files in Cognee Cloud’s managed S3 infrastructure * **LanceDB** – Vector database that stores embeddings generated during the [cognify process](https://docs.cognee.ai/cognee-cloud/cognee-cloud-sdk#cognify) * **Kuzu** – Graph database that maintains knowledge graph relationships and entities * **PostgreSQL** – Relational database for users, datasets, permissions, quotas, and billing records Each dataset maintains separate storage namespaces for isolation, and all workers share the same state through Cognee Cloud’s managed S3 infrastructure. [​](https://docs.cognee.ai/cognee-cloud/cognee-cloud-architecture#key-architectural-principles) Key Architectural Principles ------------------------------------------------------------------------------------------------------------------------------- * **Dataset Isolation**: All processing happens at the dataset level, with separate storage namespaces (see [permissions & security](https://docs.cognee.ai/cognee-cloud/permissions-security) for details) * **Managed Infrastructure**: Users don’t configure Modal, S3, or database credentials—everything is managed by Cognee Cloud * **Compatibility**: Storage schemas remain compatible with [self-hosted Cognee](https://docs.cognee.ai/getting-started/installation) for easy [migration](https://docs.cognee.ai/cognee-cloud/local-mode-and-sync) [​](https://docs.cognee.ai/cognee-cloud/cognee-cloud-architecture#continue-exploring) Continue exploring ----------------------------------------------------------------------------------------------------------- [Permissions & Security\ ----------------------\ \ See how tenant isolation and RBAC layer onto the storage services.](https://docs.cognee.ai/cognee-cloud/permissions-security) Was this page helpful? YesNo [Previous\ \ Permissions & SecurityDataset isolation and security features in Cognee Cloud](https://docs.cognee.ai/cognee-cloud/permissions-security) ⌘I On this page * [System Overview](https://docs.cognee.ai/cognee-cloud/cognee-cloud-architecture#system-overview) * [Modal (Managed Infrastructure)](https://docs.cognee.ai/cognee-cloud/cognee-cloud-architecture#modal-managed-infrastructure) * [Storage Services (Managed by Cognee Cloud)](https://docs.cognee.ai/cognee-cloud/cognee-cloud-architecture#storage-services-managed-by-cognee-cloud) * [Key Architectural Principles](https://docs.cognee.ai/cognee-cloud/cognee-cloud-architecture#key-architectural-principles) * [Continue exploring](https://docs.cognee.ai/cognee-cloud/cognee-cloud-architecture#continue-exploring) --- # Sign Up & Prerequisites - Cognee Documentation [Skip to main content](https://docs.cognee.ai/cognee-cloud/sign-up#content-area) [Cognee Documentation home page![light logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20black.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=ea48b52be1df02b5909f780e6cd6856e)![dark logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20white.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=9f5bc18c4897c6e58b5cfa2b09bc079d)](https://docs.cognee.ai/) Search... ⌘K Search... Navigation Cognee Cloud Platform Sign Up & Prerequisites [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) Get access to the Cognee Cloud console, enable billing, and prepare everything you need before uploading data. Cognee Cloud currently supports **Google** OAuth. Have access to a Google account plus a payment method ready. [​](https://docs.cognee.ai/cognee-cloud/sign-up#checklist-before-you-start) Checklist before you start --------------------------------------------------------------------------------------------------------- * Google account for authentication * Payment card for the subscription prompt on first login * Optional: AWS credentials if you plan to connect an S3 bucket via the notebook [​](https://docs.cognee.ai/cognee-cloud/sign-up#account-and-api-key-setup) Account and API key setup ------------------------------------------------------------------------------------------------------- 1 Open the console Visit [https://platform.cognee.ai/](https://platform.cognee.ai/) and choose **Continue with Google**. **Prerequisites**: A Google account and a valid credit/debit card. 2 Authorize access Approve the OAuth request. Cognee Cloud uses the provider for sign-in only—no passwords to manage. 3 Pick a workspace name The workspace name appears in the notebook UI and API responses. You can update it later in **Settings → Workspace**. 4 Subscribe & Payment On first sign-in, you’ll be prompted to subscribe and add a payment method. Enter your card details and click **Save** to activate your account. 5 Go to API Keys In the console, go to **Settings → API Keys**. 6 Create an API Key Click **Create API Key** and give it a recognizable name. Copy the key when you need it—you can always access it later from the settings page. [​](https://docs.cognee.ai/cognee-cloud/sign-up#what-you-can-do-now) What you can do now ------------------------------------------------------------------------------------------- With your [API key](https://docs.cognee.ai/cognee-cloud/permissions-security) , you can: 1. **Use the UI to upload files and create Cognee’s AI memory** — [Try the Cognee Cloud UI](https://docs.cognee.ai/cognee-cloud/cognee-cloud-ui) to upload your first dataset and explore it through the interface. 2. **Use the notebook interface to run pipelines and core operations** — Learn how to use `add`, `cognify`, `memify`, and `search` operations with [Cognee Cloud Notebooks](https://docs.cognee.ai/cognee-cloud/cognee-cloud-notebooks) . 3. **Use the platform programmatically via cogwit-sdk** — Automate ingestion and search using the [Cognee Cloud SDK](https://docs.cognee.ai/cognee-cloud/cognee-cloud-sdk) . [​](https://docs.cognee.ai/cognee-cloud/sign-up#next-steps) Next steps ------------------------------------------------------------------------- [Cognee Cloud UI\ ---------------\ \ Upload your first dataset and explore it through the interface.](https://docs.cognee.ai/cognee-cloud/cognee-cloud-ui) [Cognee Cloud Notebooks\ ----------------------\ \ Run code against datasets using Cognee Cloud notebooks.](https://docs.cognee.ai/cognee-cloud/cognee-cloud-notebooks) [Automate with the SDK\ ---------------------\ \ Ingest and search programmatically using the Python SDK.](https://docs.cognee.ai/cognee-cloud/cognee-cloud-sdk) Was this page helpful? YesNo [Previous](https://docs.cognee.ai/cognee-cloud/overview) [Cognee Cloud UIWork with datasets and data ingestion through the Cognee Cloud UI\ \ Next](https://docs.cognee.ai/cognee-cloud/cognee-cloud-ui) ⌘I On this page * [Checklist before you start](https://docs.cognee.ai/cognee-cloud/sign-up#checklist-before-you-start) * [Account and API key setup](https://docs.cognee.ai/cognee-cloud/sign-up#account-and-api-key-setup) * [What you can do now](https://docs.cognee.ai/cognee-cloud/sign-up#what-you-can-do-now) * [Next steps](https://docs.cognee.ai/cognee-cloud/sign-up#next-steps) --- # Cognee Cloud Notebooks - Cognee Documentation [Skip to main content](https://docs.cognee.ai/cognee-cloud/cognee-cloud-notebooks#content-area) [Cognee Documentation home page![light logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20black.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=ea48b52be1df02b5909f780e6cd6856e)![dark logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20white.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=9f5bc18c4897c6e58b5cfa2b09bc079d)](https://docs.cognee.ai/) Search... ⌘K Search... Navigation Cognee Cloud Platform Cognee Cloud Notebooks [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) Notebooks let you use all four Cognee operations: **add()**, **cognify()**, **memify()**, and **search()**. You’ll need an [API key](https://docs.cognee.ai/cognee-cloud/sign-up) to get started. [​](https://docs.cognee.ai/cognee-cloud/cognee-cloud-notebooks#open-or-create-a-notebook) Open or create a notebook ---------------------------------------------------------------------------------------------------------------------- * Expand **Notebooks** in the sidebar. * Open the example notebook (_Python Development with Cognee Tutorial_) or create a new one with **+**. [​](https://docs.cognee.ai/cognee-cloud/cognee-cloud-notebooks#using-operations) Using operations ---------------------------------------------------------------------------------------------------- * **add()** and **cognify()** can also be run in the UI, but in notebooks you can call them programmatically. * **memify()** and **search()** are available only in notebooks. We’ll cover each operation below, and to see them in action, you can run the example notebook that is available when you sign up for Cognee Cloud. [​](https://docs.cognee.ai/cognee-cloud/cognee-cloud-notebooks#add-data) Add data ------------------------------------------------------------------------------------ Upload files or text content into your dataset: Copy # Add a single text string await cognee.add("Your text content here", node_set=["my_data"]) # Add from a local file await cognee.add( "/path/to/your/local/file.txt", node_set=["guido_data"] ) You can only add `.txt` files in notebooks. In particular, you should convert PDFs to text before adding them. [​](https://docs.cognee.ai/cognee-cloud/cognee-cloud-notebooks#cognify-data) Cognify data -------------------------------------------------------------------------------------------- Transform your data into a knowledge graph: Copy # Basic cognify await cognee.cognify() # With temporal processing await cognee.cognify(temporal_cognify=True) [​](https://docs.cognee.ai/cognee-cloud/cognee-cloud-notebooks#memify-data) Memify data ------------------------------------------------------------------------------------------ Enrich your knowledge graph with semantic relationships: Copy # Run memify to infer new connections await cognee.memify() [​](https://docs.cognee.ai/cognee-cloud/cognee-cloud-notebooks#search-your-data) Search your data ---------------------------------------------------------------------------------------------------- Query your knowledge graph with natural language: Copy # Basic search results = await cognee.search("What does our product aim to deliver?") print(results[0]) # Graph completion search results = await cognee.search( "What Python type hinting challenges did I face?", query_type=cognee.SearchType.GRAPH_COMPLETION ) # Temporal search results = await cognee.search( "What can we learn from recent contributions?", query_type=cognee.SearchType.TEMPORAL ) [​](https://docs.cognee.ai/cognee-cloud/cognee-cloud-notebooks#next-steps) Next steps ---------------------------------------------------------------------------------------- * Explore memify to infer new relationships. * Automate ingestion and analysis with the [Cognee Cloud SDK](https://docs.cognee.ai/cognee-cloud/cognee-cloud-sdk) . [Cognee Cloud UI\ ---------------\ \ Learn to manage datasets and upload files through the UI.](https://docs.cognee.ai/cognee-cloud/cognee-cloud-ui) [Cognee Cloud SDK\ ----------------\ \ Explore advanced SDK examples and automation patterns.](https://docs.cognee.ai/cognee-cloud/cognee-cloud-sdk) Was this page helpful? YesNo [Previous](https://docs.cognee.ai/cognee-cloud/cognee-cloud-ui) [Cognee Cloud SDKUse the Cognee Cloud SDK to upload data, cognify it, and search your knowledge graph\ \ Next](https://docs.cognee.ai/cognee-cloud/cognee-cloud-sdk) ⌘I On this page * [Open or create a notebook](https://docs.cognee.ai/cognee-cloud/cognee-cloud-notebooks#open-or-create-a-notebook) * [Using operations](https://docs.cognee.ai/cognee-cloud/cognee-cloud-notebooks#using-operations) * [Add data](https://docs.cognee.ai/cognee-cloud/cognee-cloud-notebooks#add-data) * [Cognify data](https://docs.cognee.ai/cognee-cloud/cognee-cloud-notebooks#cognify-data) * [Memify data](https://docs.cognee.ai/cognee-cloud/cognee-cloud-notebooks#memify-data) * [Search your data](https://docs.cognee.ai/cognee-cloud/cognee-cloud-notebooks#search-your-data) * [Next steps](https://docs.cognee.ai/cognee-cloud/cognee-cloud-notebooks#next-steps) --- # Cognee Cloud UI - Cognee Documentation [Skip to main content](https://docs.cognee.ai/cognee-cloud/cognee-cloud-ui#content-area) [Cognee Documentation home page![light logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20black.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=ea48b52be1df02b5909f780e6cd6856e)![dark logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20white.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=9f5bc18c4897c6e58b5cfa2b09bc079d)](https://docs.cognee.ai/) Search... ⌘K Search... Navigation Cognee Cloud Platform Cognee Cloud UI [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) Use the Cognee Cloud UI to manage datasets, upload files, and trigger cognify. This page explains what you can do directly in the UI, and where notebooks come into play. [​](https://docs.cognee.ai/cognee-cloud/cognee-cloud-ui#cognee-instances) Cognee instances --------------------------------------------------------------------------------------------- * **Cloud instance** — Your Cognee Cloud workspace with managed infrastructure * **Local instance** — Your local Cognee installation for development and testing * Both instances contain **[datasets](https://docs.cognee.ai/core-concepts/further-concepts/datasets) ** that can be [synced between environments](https://docs.cognee.ai/cognee-cloud/local-mode-and-sync) [​](https://docs.cognee.ai/cognee-cloud/cognee-cloud-ui#adding-datasets) Adding datasets ------------------------------------------------------------------------------------------- * Use the **+** button next to an instance to create a new dataset. * Datasets are containers for your documents and all subsequent operations (add, cognify, memify, search). See [permissions & security](https://docs.cognee.ai/cognee-cloud/permissions-security) for how datasets are isolated. [​](https://docs.cognee.ai/cognee-cloud/cognee-cloud-ui#adding-data) Adding data ----------------------------------------------------------------------------------- When you upload a file into a dataset, Cognee performs **add + cognify** under the hood: * **Dataset menu (three dots)** — choose **Add files** to upload files into that dataset. * Uploaded files appear as documents under the dataset, already cognified into the knowledge graph. Since add + cognify runs together, file processing can take a bit of time to complete. Be patient while your files are being processed into the knowledge graph. [​](https://docs.cognee.ai/cognee-cloud/cognee-cloud-ui#notebooks-overview) Notebooks overview ------------------------------------------------------------------------------------------------- Notebooks are interactive coding environments connected to your datasets. In a notebook you can: * Run all four operations (**add, cognify, memify, search**) programmatically. * By default, notebook operations run on the same datasets as the UI. See the separate [Cognee Cloud Notebooks](https://docs.cognee.ai/cognee-cloud/cognee-cloud-notebooks) for details on creating and working inside notebooks. [​](https://docs.cognee.ai/cognee-cloud/cognee-cloud-ui#next-steps) Next steps --------------------------------------------------------------------------------- [Cognee Cloud Notebooks\ ----------------------\ \ Learn to run code against datasets using Cognee Cloud notebooks.](https://docs.cognee.ai/cognee-cloud/cognee-cloud-notebooks) [Cognee Cloud SDK\ ----------------\ \ Automate ingestion and search using the Python SDK.](https://docs.cognee.ai/cognee-cloud/cognee-cloud-sdk) Was this page helpful? YesNo [Previous](https://docs.cognee.ai/cognee-cloud/sign-up) [Cognee Cloud NotebooksRun code against datasets using Cognee Cloud notebooks\ \ Next](https://docs.cognee.ai/cognee-cloud/cognee-cloud-notebooks) ⌘I On this page * [Cognee instances](https://docs.cognee.ai/cognee-cloud/cognee-cloud-ui#cognee-instances) * [Adding datasets](https://docs.cognee.ai/cognee-cloud/cognee-cloud-ui#adding-datasets) * [Adding data](https://docs.cognee.ai/cognee-cloud/cognee-cloud-ui#adding-data) * [Notebooks overview](https://docs.cognee.ai/cognee-cloud/cognee-cloud-ui#notebooks-overview) * [Next steps](https://docs.cognee.ai/cognee-cloud/cognee-cloud-ui#next-steps) --- # Cursor - Cognee Documentation [Skip to main content](https://docs.cognee.ai/cognee-mcp/integrations/cursor#content-area) [Cognee Documentation home page![light logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20black.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=ea48b52be1df02b5909f780e6cd6856e)![dark logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20white.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=9f5bc18c4897c6e58b5cfa2b09bc079d)](https://docs.cognee.ai/) Search... ⌘K Search... Navigation Integrations Cursor [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) [​](https://docs.cognee.ai/cognee-mcp/integrations/cursor#cursor-integration) Cursor Integration =================================================================================================== Cursor is an AI-powered code editor built on VS Code with native support for the Model Context Protocol. It provides AI assistance through its Composer interface and chat panel. [​](https://docs.cognee.ai/cognee-mcp/integrations/cursor#prerequisites) Prerequisites ----------------------------------------------------------------------------------------- * Cursor installed on your machine * Cognee MCP server running (see [Quickstart](https://docs.cognee.ai/cognee-mcp/mcp-quickstart) or [Local Setup](https://docs.cognee.ai/cognee-mcp/mcp-local-setup) ) * OpenAI API key [​](https://docs.cognee.ai/cognee-mcp/integrations/cursor#setup-steps) Setup Steps ------------------------------------------------------------------------------------- 1 Open MCP Settings 1. Launch Cursor 2. Click the gear icon to open Settings 3. Navigate to **Tools & MCP** 4. Click **\+ Add MCP Server** This opens the `mcp.json` configuration file. 2 Add Cognee Server Configuration Choose the configuration that matches how you started the Cognee MCP server: * Docker (HTTP) * Local (stdio) Use this if you started the server with Docker: Copy { "mcpServers": { "cognee": { "url": "http://localhost:8000/mcp" } } } This configuration tells Cursor to connect to the HTTP endpoint exposed by the Docker container. Save the file after adding your configuration. 3 Verify Connection Use the toggle in MCP Tools to refresh the connection. You should see a list of available tools from Cognee, confirming the server is connected. 4 Use Cognee Tools 1. Open the Chat panel in Cursor 2. Make sure **Agent** mode is selected 3. Issue prompts that use Cognee tools Example prompts: * “Add this file to memory using cognify” * “Search my code for authentication logic” * “Codify this repository” [​](https://docs.cognee.ai/cognee-mcp/integrations/cursor#where-to-use-this-configuration) Where to Use This Configuration ----------------------------------------------------------------------------------------------------------------------------- The `mcp.json` file is located in your Cursor settings directory. Cursor reads this file at startup and when you refresh the MCP connection. The configuration applies to all projects you open in Cursor. [​](https://docs.cognee.ai/cognee-mcp/integrations/cursor#need-help) Need Help? ---------------------------------------------------------------------------------- [Join Our Community\ ------------------\ \ Get support and connect with other developers using Cognee MCP.](https://discord.gg/m63hxKsp4p) Was this page helpful? YesNo [Previous](https://docs.cognee.ai/cognee-mcp/integrations/claude-code) [Continue\ \ Next](https://docs.cognee.ai/cognee-mcp/integrations/continue) ⌘I On this page * [Cursor Integration](https://docs.cognee.ai/cognee-mcp/integrations/cursor#cursor-integration) * [Prerequisites](https://docs.cognee.ai/cognee-mcp/integrations/cursor#prerequisites) * [Setup Steps](https://docs.cognee.ai/cognee-mcp/integrations/cursor#setup-steps) * [Where to Use This Configuration](https://docs.cognee.ai/cognee-mcp/integrations/cursor#where-to-use-this-configuration) * [Need Help?](https://docs.cognee.ai/cognee-mcp/integrations/cursor#need-help) --- # Claude Code - Cognee Documentation [Skip to main content](https://docs.cognee.ai/cognee-mcp/integrations/claude-code#content-area) [Cognee Documentation home page![light logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20black.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=ea48b52be1df02b5909f780e6cd6856e)![dark logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20white.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=9f5bc18c4897c6e58b5cfa2b09bc079d)](https://docs.cognee.ai/) Search... ⌘K Search... Navigation Integrations Claude Code [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) [​](https://docs.cognee.ai/cognee-mcp/integrations/claude-code#claude-code-integration) Claude Code Integration ================================================================================================================== Claude Code is Anthropic’s command-line AI assistant with built-in MCP support. It runs in your terminal and can access MCP servers configured in your project or user settings. [​](https://docs.cognee.ai/cognee-mcp/integrations/claude-code#prerequisites) Prerequisites ---------------------------------------------------------------------------------------------- * Node.js and npm installed * Cognee MCP server running (see [Quickstart](https://docs.cognee.ai/cognee-mcp/mcp-quickstart) or [Local Setup](https://docs.cognee.ai/cognee-mcp/mcp-local-setup) ) * OpenAI API key (for Cognee’s LLM operations) [​](https://docs.cognee.ai/cognee-mcp/integrations/claude-code#setup-steps) Setup Steps ------------------------------------------------------------------------------------------ 1 Install Claude Code Copy npm install -g @anthropic-ai/claude-code 2 Navigate to Your Project Copy cd /path/to/your/project 3 Add Cognee Server Choose the command that matches how you started the Cognee MCP server: * Docker (HTTP) * Local (stdio) Use this if you started the server with Docker: Copy claude mcp add --transport http cognee http://localhost:8000/mcp -s project This creates a configuration in your project’s `.mcp.json` file that connects to the HTTP endpoint.**Options:** * `-s project`: Stores configuration in the project (requires approval per project) * Omit `-s project` to store at user level (applies to all projects) 4 Start Claude Code and Approve Copy claude On first run in this project, you will see: Copy Approve project MCP servers? • cognee /path/to/cognee-mcp Select **Enable** or press Enter. Claude Code can now call Cognee tools automatically. 5 Use Cognee Tools Claude Code will use Cognee tools when relevant to your requests. You can explicitly ask: * “Add this code to Cognee memory” * “Search Cognee for authentication patterns” * “Use Cognee to codify this repository” [​](https://docs.cognee.ai/cognee-mcp/integrations/claude-code#where-to-use-this-configuration) Where to Use This Configuration ---------------------------------------------------------------------------------------------------------------------------------- The configuration is stored in `.mcp.json` in your project directory (with `-s project`) or in your user settings (without it). Claude Code reads this file when starting a session in that directory. [​](https://docs.cognee.ai/cognee-mcp/integrations/claude-code#need-help) Need Help? --------------------------------------------------------------------------------------- [Join Our Community\ ------------------\ \ Get support and connect with other developers using Cognee MCP.](https://discord.gg/m63hxKsp4p) Was this page helpful? YesNo [Previous](https://docs.cognee.ai/cognee-mcp/mcp-local-setup) [Cursor\ \ Next](https://docs.cognee.ai/cognee-mcp/integrations/cursor) ⌘I On this page * [Claude Code Integration](https://docs.cognee.ai/cognee-mcp/integrations/claude-code#claude-code-integration) * [Prerequisites](https://docs.cognee.ai/cognee-mcp/integrations/claude-code#prerequisites) * [Setup Steps](https://docs.cognee.ai/cognee-mcp/integrations/claude-code#setup-steps) * [Where to Use This Configuration](https://docs.cognee.ai/cognee-mcp/integrations/claude-code#where-to-use-this-configuration) * [Need Help?](https://docs.cognee.ai/cognee-mcp/integrations/claude-code#need-help) --- # Deployment Overview - Cognee Documentation [Skip to main content](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment#content-area) [Cognee Documentation home page![light logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20black.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=ea48b52be1df02b5909f780e6cd6856e)![dark logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20white.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=9f5bc18c4897c6e58b5cfa2b09bc079d)](https://docs.cognee.ai/) Search... ⌘K Search... Navigation Self-Hosting Deployment Overview [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) Cognee is designed for flexible deployment across development and production environments, with configurable data storage backends that scale with your needs. [​](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment#data-storage-architecture) Data Storage Architecture ---------------------------------------------------------------------------------------------------------------------- Cognee operates on a three-tier data storage model, each optimized for specific data types and query patterns: Graph Database -------------- **Relationships & Entities**Stores knowledge graph structure, entity relationships, and semantic connections. Vector Database --------------- **Embeddings & Search**Handles semantic embeddings for similarity search and content retrieval. Relational Database ------------------- **Metadata & State**Manages datasets, user permissions, pipeline state, and operational data. Each storage layer can be deployed as managed services, self-hosted servers, or file-based systems (like S3 buckets), giving you complete flexibility over your infrastructure. [​](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment#deployment-options) Deployment Options -------------------------------------------------------------------------------------------------------- Choose the deployment strategy that matches your requirements: * Development * Production * Hybrid **Local & Testing** * **Docker**: Containerized local deployment with embedded databases * **MCP**: Direct integration with code editors and IDEs * **File-based**: SQLite, local files, and embedded vector stores [​](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment#storage-configuration-examples) Storage Configuration Examples -------------------------------------------------------------------------------------------------------------------------------- Local Development **Embedded & File-based** Copy # All data stored locally GRAPH_DATABASE=networkx VECTOR_DATABASE=lancedb RELATIONAL_DATABASE=sqlite://./cognee.db **Multi-Agent Limitation**: Default Kuzu graph store uses file-based locking and is not suitable for concurrent access from multiple agents. Use Neo4j or FalkorDB for multi-agent deployments. Cloud Production **Managed Services** Copy # Fully managed cloud services GRAPH_DATABASE=neo4j://your-aura-instance VECTOR_DATABASE=pinecone://your-index RELATIONAL_DATABASE=postgresql://your-rds-instance Hybrid S3 **S3 + Managed Databases** Copy # Vector data in S3, databases managed VECTOR_DATABASE=s3://your-bucket/vectors/ GRAPH_DATABASE=neo4j://managed-instance RELATIONAL_DATABASE=postgresql://rds-instance [​](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment#quick-start-guide) Quick Start Guide ------------------------------------------------------------------------------------------------------ 1 Choose Deployment Select your deployment method based on scale and requirements 2 Configure Storage Set up your preferred combination of graph, vector, and relational databases 3 Deploy & Test Launch Cognee and verify connectivity to all storage backends 4 Scale Adjust storage and compute resources based on usage patterns [​](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment#deployment-methods) Deployment Methods -------------------------------------------------------------------------------------------------------- [Modal Deployment\ ----------------\ \ **Serverless & Auto-scaling**Perfect for variable workloads with automatic resource management.](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment/modal) [Kubernetes (Helm)\ -----------------\ \ **Enterprise & Production**Container orchestration with full control and high availability.](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment/helm) [EC2 Deployment\ --------------\ \ **Traditional Cloud**Standard server deployment with custom configurations.](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment/ec2) [​](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment#architecture-benefits) Architecture Benefits -------------------------------------------------------------------------------------------------------------- **Flexible Data Tiers**: Each storage layer can be independently scaled, managed, or migrated without affecting others. **Cost Optimization**: Use file-based storage (S3) for archival data and managed services for active workloads. **Security**: Ensure proper network security and access controls across all storage tiers in production deployments. [​](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment#need-help) Need Help? --------------------------------------------------------------------------------------- [Join Our Community\ ------------------\ \ Get deployment support, share configurations, and connect with other Cognee users.](https://discord.gg/m63hxKsp4p) Was this page helpful? YesNo [EC2 DeploymentDeploy Cognee on Amazon EC2 for traditional cloud server deployments with custom configurations\ \ Next](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment/ec2) ⌘I On this page * [Data Storage Architecture](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment#data-storage-architecture) * [Deployment Options](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment#deployment-options) * [Storage Configuration Examples](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment#storage-configuration-examples) * [Quick Start Guide](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment#quick-start-guide) * [Deployment Methods](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment#deployment-methods) * [Architecture Benefits](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment#architecture-benefits) * [Need Help?](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment#need-help) --- # Permissions & Security - Cognee Documentation [Skip to main content](https://docs.cognee.ai/cognee-cloud/permissions-security#content-area) [Cognee Documentation home page![light logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20black.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=ea48b52be1df02b5909f780e6cd6856e)![dark logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20white.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=9f5bc18c4897c6e58b5cfa2b09bc079d)](https://docs.cognee.ai/) Search... ⌘K Search... Navigation Cognee Cloud Platform Permissions & Security [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) Cognee Cloud provides dataset-level isolation and security features to keep your data organized and protected. [​](https://docs.cognee.ai/cognee-cloud/permissions-security#dataset-isolation) Dataset Isolation ---------------------------------------------------------------------------------------------------- Cognee Cloud automatically creates separate knowledge graphs and vector stores for each dataset: * **Separate storage**: Each dataset gets its own Kùzu graph database and LanceDB vector store * **Data isolation**: Documents and their processed knowledge graphs are completely isolated by dataset * **Search flexibility**: Choose to search within a single dataset or across all datasets ### [​](https://docs.cognee.ai/cognee-cloud/permissions-security#working-with-datasets) Working with datasets **Single dataset search** (default): Copy # Search within a specific dataset results = cognee.search("your query", dataset_names=["my_dataset"]) **Combined search** (across all datasets): Copy # Search across all your datasets results = cognee.search("your query", use_combined_context=True) [​](https://docs.cognee.ai/cognee-cloud/permissions-security#advanced-rbac-coming-to-cognee-cloud) Advanced RBAC (Coming to Cognee Cloud) -------------------------------------------------------------------------------------------------------------------------------------------- Cognee’s comprehensive role-based access control (RBAC) system will be available in Cognee Cloud soon: * **User management** — Create and manage users, roles, and tenants * **Granular permissions** — Read, write, delete, and share permissions at the dataset level * **Team collaboration** — Multi-user workspaces with role-based access * **Audit logging** — Complete activity tracking and compliance reporting These features are already available in [self-hosted Cognee](https://docs.cognee.ai/getting-started/installation) and will be enabled in Cognee Cloud’s cloud platform. See the [Cognee Permissions System](https://docs.cognee.ai/core-concepts/permissions-system/overview) for complete documentation. [​](https://docs.cognee.ai/cognee-cloud/permissions-security#related-docs) Related docs ------------------------------------------------------------------------------------------ [Cognee Cloud architecture\ -------------------------\ \ Understand where permissions enforcement happens in the stack.](https://docs.cognee.ai/cognee-cloud/cognee-cloud-architecture) Was this page helpful? YesNo [Previous](https://docs.cognee.ai/cognee-cloud/local-mode-and-sync) [Cognee Cloud ArchitectureUnderstanding Cognee's managed infrastructure and how components work together\ \ Next](https://docs.cognee.ai/cognee-cloud/cognee-cloud-architecture) ⌘I On this page * [Dataset Isolation](https://docs.cognee.ai/cognee-cloud/permissions-security#dataset-isolation) * [Working with datasets](https://docs.cognee.ai/cognee-cloud/permissions-security#working-with-datasets) * [Advanced RBAC (Coming to Cognee Cloud)](https://docs.cognee.ai/cognee-cloud/permissions-security#advanced-rbac-coming-to-cognee-cloud) * [Related docs](https://docs.cognee.ai/cognee-cloud/permissions-security#related-docs) --- # Overview - Cognee Documentation [Skip to main content](https://docs.cognee.ai/cognee-mcp/mcp-overview#content-area) [Cognee Documentation home page![light logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20black.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=ea48b52be1df02b5909f780e6cd6856e)![dark logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20white.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=9f5bc18c4897c6e58b5cfa2b09bc079d)](https://docs.cognee.ai/) Search... ⌘K Search... Navigation Setup Overview [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) Cognee MCP brings persistent AI memory to your workflow through the Model Context Protocol. [​](https://docs.cognee.ai/cognee-mcp/mcp-overview#what-is-mcp) What is MCP? ------------------------------------------------------------------------------- The [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) is a standard for adding specialized tools to AI assistants. It allows AI tools like Claude or Cursor to work with external systems such as databases, APIs, and AI platforms. Without MCP, each AI assistant needs custom integrations for every external system. This creates duplication and inconsistency across tools. MCP provides a single method for extending AI assistants with: * **Standardized connections** between AI tools and external systems * **Secure data access** with built-in authentication and permissions * **Tool interoperability** so you can switch between AI providers * **Persistent memory** that survives across conversations and sessions [​](https://docs.cognee.ai/cognee-mcp/mcp-overview#how-cognee-mcp-works) How Cognee MCP Works ------------------------------------------------------------------------------------------------ Cognee MCP exposes 11 specialized tools through the MCP protocol. These tools handle memory management, code intelligence, and data operations. You access them through MCP-compatible AI assistants like Cursor, Claude Desktop, Continue, Cline, and Roo Code. The tools enable your AI assistant to: * Store and retrieve knowledge from previous conversations * Build persistent understanding of your codebase and projects * Access structured memories across different sessions See the [Tools Reference](https://docs.cognee.ai/cognee-mcp/mcp-tools) for all available operations. [​](https://docs.cognee.ai/cognee-mcp/mcp-overview#architecture-modes) Architecture Modes -------------------------------------------------------------------------------------------- Cognee MCP can run in two modes: **Standalone Mode**: The MCP server manages its own database and processing. Each MCP instance maintains separate data. Use this for personal development or when clients need isolated environments. **API Mode**: The MCP server connects to a centralized Cognee backend via API. Multiple MCP instances can share the same knowledge graph. Use this when you want team members to access shared memory or when running multiple AI clients that need consistent data. [​](https://docs.cognee.ai/cognee-mcp/mcp-overview#setup-options) Setup Options ---------------------------------------------------------------------------------- Choose your deployment method: [Docker Quickstart\ -----------------\ \ **Recommended for most users**Get running in minutes with a pre-built container.](https://docs.cognee.ai/cognee-mcp/mcp-quickstart) [API Mode (Shared)\ -----------------\ \ **For teams**Connect multiple clients to a shared knowledge graph.](https://docs.cognee.ai/cognee-mcp/mcp-quickstart#api-mode-shared-knowledge-graph) [Local Setup\ -----------\ \ **For development**Build from source for full control and latest features.](https://docs.cognee.ai/cognee-mcp/mcp-local-setup) [​](https://docs.cognee.ai/cognee-mcp/mcp-overview#next-steps) Next Steps ---------------------------------------------------------------------------- [Tools Reference\ ---------------\ \ See all available MCP tools and operations](https://docs.cognee.ai/cognee-mcp/mcp-tools) [Client Integrations\ -------------------\ \ Connect with Cursor, Claude, Continue, and more](https://docs.cognee.ai/cognee-mcp/integrations) Was this page helpful? YesNo [QuickstartGet Cognee MCP running in minutes with Docker\ \ Next](https://docs.cognee.ai/cognee-mcp/mcp-quickstart) ⌘I On this page * [What is MCP?](https://docs.cognee.ai/cognee-mcp/mcp-overview#what-is-mcp) * [How Cognee MCP Works](https://docs.cognee.ai/cognee-mcp/mcp-overview#how-cognee-mcp-works) * [Architecture Modes](https://docs.cognee.ai/cognee-mcp/mcp-overview#architecture-modes) * [Setup Options](https://docs.cognee.ai/cognee-mcp/mcp-overview#setup-options) * [Next Steps](https://docs.cognee.ai/cognee-mcp/mcp-overview#next-steps) --- # Quickstart - Cognee Documentation [Skip to main content](https://docs.cognee.ai/cognee-mcp/mcp-quickstart#content-area) [Cognee Documentation home page![light logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20black.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=ea48b52be1df02b5909f780e6cd6856e)![dark logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20white.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=9f5bc18c4897c6e58b5cfa2b09bc079d)](https://docs.cognee.ai/) Search... ⌘K Search... Navigation Setup Quickstart [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) Start the Cognee MCP server using Docker to quickly test AI memory integration. [​](https://docs.cognee.ai/cognee-mcp/mcp-quickstart#prerequisites) Prerequisites ------------------------------------------------------------------------------------ * Docker installed and running * OpenAI API key [​](https://docs.cognee.ai/cognee-mcp/mcp-quickstart#setup-steps) Setup Steps -------------------------------------------------------------------------------- 1 Set Your API Key Copy export LLM_API_KEY=your_api_key_here 2 Create Environment File Copy echo "LLM_API_KEY=your_api_key_here" > .env 3 Start the Server Copy docker run -e TRANSPORT_MODE=http --env-file ./.env -p 8000:8000 --rm -it cognee/cognee-mcp:main The server starts on port 8000 with HTTP transport mode. 4 Verify the Server Copy curl http://localhost:8000/health You should see a healthy response from the server. The container removes all data when stopped. Use volume mounts for persistent storage. [​](https://docs.cognee.ai/cognee-mcp/mcp-quickstart#api-mode-shared-knowledge-graph) API Mode (Shared Knowledge Graph) -------------------------------------------------------------------------------------------------------------------------- To connect multiple clients to a shared knowledge graph, run MCP in API mode pointing to a centralized Cognee backend: 1 Start Cognee Backend First, start a Cognee backend instance: Copy docker run -e LLM_API_KEY=your_api_key_here -p 8080:8000 --rm -it cognee/cognee:main 2 Start MCP in API Mode Start the MCP server and point it to the backend: Copy docker run -e TRANSPORT_MODE=sse -e API_URL=http://localhost:8080 -p 8000:8000 --rm -it cognee/cognee-mcp:main The container automatically converts `localhost` to `host.docker.internal` so the MCP container can reach your host machine. The MCP server now acts as an interface to the shared backend. 3 Connect Additional Clients (Optional) If you need to support multiple clients, start additional MCP instances on different ports: Copy docker run -e TRANSPORT_MODE=sse -e API_URL=http://localhost:8080 -p 8001:8000 --rm -it cognee/cognee-mcp:main Each client connects to its own MCP instance, but all share the same knowledge graph through the backend. * The API mode requires SSE or HTTP transport * The `localhost` in `API_URL` is automatically mapped to work from inside the container * Add `-e API_TOKEN=your_token` if your backend requires authentication [​](https://docs.cognee.ai/cognee-mcp/mcp-quickstart#connect-to-ai-clients) Connect to AI Clients ---------------------------------------------------------------------------------------------------- After starting the server, connect it to your AI development tool: [Cursor\ ------\ \ AI-powered code editor with native MCP support](https://docs.cognee.ai/cognee-mcp/integrations/cursor) [Claude Code\ -----------\ \ Command-line AI assistant from Anthropic](https://docs.cognee.ai/cognee-mcp/integrations/claude-code) [Cline\ -----\ \ VS Code extension for AI-assisted development](https://docs.cognee.ai/cognee-mcp/integrations/cline) [Continue\ --------\ \ Open-source AI coding assistant](https://docs.cognee.ai/cognee-mcp/integrations/continue) [Roo Code\ --------\ \ AI-powered development environment](https://docs.cognee.ai/cognee-mcp/integrations/roo-code) [​](https://docs.cognee.ai/cognee-mcp/mcp-quickstart#next-steps) Next Steps ------------------------------------------------------------------------------ [Tools Reference\ ---------------\ \ See all available MCP tools and operations](https://docs.cognee.ai/cognee-mcp/mcp-tools) [Local Setup\ -----------\ \ Run from source for customization and development](https://docs.cognee.ai/cognee-mcp/mcp-local-setup) Was this page helpful? YesNo [Previous](https://docs.cognee.ai/cognee-mcp/mcp-overview) [Tools ReferenceComplete reference for all Cognee MCP tools and operations\ \ Next](https://docs.cognee.ai/cognee-mcp/mcp-tools) ⌘I On this page * [Prerequisites](https://docs.cognee.ai/cognee-mcp/mcp-quickstart#prerequisites) * [Setup Steps](https://docs.cognee.ai/cognee-mcp/mcp-quickstart#setup-steps) * [API Mode (Shared Knowledge Graph)](https://docs.cognee.ai/cognee-mcp/mcp-quickstart#api-mode-shared-knowledge-graph) * [Connect to AI Clients](https://docs.cognee.ai/cognee-mcp/mcp-quickstart#connect-to-ai-clients) * [Next Steps](https://docs.cognee.ai/cognee-mcp/mcp-quickstart#next-steps) --- # Roo Code - Cognee Documentation [Skip to main content](https://docs.cognee.ai/cognee-mcp/integrations/roo-code#content-area) [Cognee Documentation home page![light logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20black.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=ea48b52be1df02b5909f780e6cd6856e)![dark logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20white.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=9f5bc18c4897c6e58b5cfa2b09bc079d)](https://docs.cognee.ai/) Search... ⌘K Search... Navigation Integrations Roo Code [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) [​](https://docs.cognee.ai/cognee-mcp/integrations/roo-code#roo-code-integration) Roo Code Integration ========================================================================================================= Roo Code is a VS Code extension that provides AI-powered development assistance with support for MCP servers. It enables direct interaction with external tools through natural language. [​](https://docs.cognee.ai/cognee-mcp/integrations/roo-code#prerequisites) Prerequisites ------------------------------------------------------------------------------------------- * Visual Studio Code installed * Cognee MCP server running (see [Quickstart](https://docs.cognee.ai/cognee-mcp/mcp-quickstart) or [Local Setup](https://docs.cognee.ai/cognee-mcp/mcp-local-setup) ) * OpenAI API key [​](https://docs.cognee.ai/cognee-mcp/integrations/roo-code#setup-steps) Setup Steps --------------------------------------------------------------------------------------- 1 Install Roo Code 1. Open Visual Studio Code 2. Go to the Extensions panel 3. Search for “Roo Code” or visit the [Marketplace page](https://marketplace.visualstudio.com/items?itemName=RooVeterinaryInc.roo-cline) 4. Click Install 5. Complete the authentication process 2 Open MCP Settings Follow the [Roo Code MCP documentation](https://docs.roocode.com/features/mcp/using-mcp-in-roo) to access settings: 1. Click the MCP Servers icon in the top navigation of the Roo Code pane 2. Scroll to the bottom of the MCP settings view 3. Choose your configuration level: * **Edit Global MCP**: Opens `mcp_settings.json` (applies to all workspaces) * **Edit Project MCP**: Opens `.roo/mcp.json` (project-specific, can be committed to version control) The file will have the base structure: Copy { "mcpServers": { } } 3 Add Cognee Server Configuration Add the Cognee server inside the `mcpServers` object. Choose the configuration that matches how you started the Cognee MCP server: * Docker (SSE) * Local (stdio) Use this if you started the server with Docker: Copy { "mcpServers": { "cognee": { "type": "sse", "url": "http://localhost:8000/sse", "disabled": false } } } This configuration tells Roo Code to connect to the SSE endpoint exposed by the Docker container. Save the file after adding your configuration. The Cognee server will appear in the MCP servers list and connect automatically. 4 Use Cognee Tools Open the Roo Code interface and interact with Cognee:Example commands: * “Codify this codebase using Cognee” - Generate a knowledge graph from your code * “Use Cognee CODE search to find authentication logic” - Query the code graph * “List my Cognee datasets” - View stored data [​](https://docs.cognee.ai/cognee-mcp/integrations/roo-code#where-to-use-this-configuration) Where to Use This Configuration ------------------------------------------------------------------------------------------------------------------------------- **Global Configuration** (`mcp_settings.json`): Settings apply across all your workspaces unless overridden by project configuration. Accessed via “Edit Global MCP” button. **Project Configuration** (`.roo/mcp.json`): Defined in your project root. Allows project-specific servers and can be committed to version control for team sharing. Accessed via “Edit Project MCP” button. If a server exists in both configurations, the project-level configuration takes precedence. You can manage servers through the Roo Code UI - use the toggle to enable/disable servers, click restart if needed, or adjust the network timeout. See the [Roo Code MCP documentation](https://docs.roocode.com/features/mcp/using-mcp-in-roo) for details. [​](https://docs.cognee.ai/cognee-mcp/integrations/roo-code#need-help) Need Help? ------------------------------------------------------------------------------------ [Join Our Community\ ------------------\ \ Get support and connect with other developers using Cognee MCP.](https://discord.gg/m63hxKsp4p) Was this page helpful? YesNo [Previous\ \ Cline](https://docs.cognee.ai/cognee-mcp/integrations/cline) ⌘I On this page * [Roo Code Integration](https://docs.cognee.ai/cognee-mcp/integrations/roo-code#roo-code-integration) * [Prerequisites](https://docs.cognee.ai/cognee-mcp/integrations/roo-code#prerequisites) * [Setup Steps](https://docs.cognee.ai/cognee-mcp/integrations/roo-code#setup-steps) * [Where to Use This Configuration](https://docs.cognee.ai/cognee-mcp/integrations/roo-code#where-to-use-this-configuration) * [Need Help?](https://docs.cognee.ai/cognee-mcp/integrations/roo-code#need-help) --- # Continue - Cognee Documentation [Skip to main content](https://docs.cognee.ai/cognee-mcp/integrations/continue#content-area) [Cognee Documentation home page![light logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20black.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=ea48b52be1df02b5909f780e6cd6856e)![dark logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20white.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=9f5bc18c4897c6e58b5cfa2b09bc079d)](https://docs.cognee.ai/) Search... ⌘K Search... Navigation Integrations Continue [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) [​](https://docs.cognee.ai/cognee-mcp/integrations/continue#continue-integration) Continue Integration ========================================================================================================= Continue is an open-source AI coding assistant for VS Code and JetBrains IDEs. It supports MCP servers through YAML configuration files in your workspace. [​](https://docs.cognee.ai/cognee-mcp/integrations/continue#prerequisites) Prerequisites ------------------------------------------------------------------------------------------- * VS Code or JetBrains IDE installed * Continue extension installed * Cognee MCP server running (see [Quickstart](https://docs.cognee.ai/cognee-mcp/mcp-quickstart) or [Local Setup](https://docs.cognee.ai/cognee-mcp/mcp-local-setup) ) * OpenAI API key [​](https://docs.cognee.ai/cognee-mcp/integrations/continue#setup-steps) Setup Steps --------------------------------------------------------------------------------------- 1 Install Continue 1. Open your IDE 2. Install the Continue extension from the marketplace ([documentation](https://www.continue.dev/) ) 2 Create MCP Configuration Directory Create a folder called `.continue/mcpServers` at the top level of your workspace: Copy mkdir -p .continue/mcpServers 3 Add Cognee MCP Configuration Choose the configuration that matches how you started the Cognee MCP server: * Docker (SSE) * Local (stdio) Create a file `.continue/mcpServers/cognee.yaml` with: Copy name: Cognee MCP Server version: 0.0.1 schema: v1 mcpServers: - name: Cognee type: sse url: http://localhost:8000/sse This connects to the SSE endpoint exposed by the Docker container. 4 Use Cognee Tools in Agent Mode Open Continue and switch to **Agent mode** (MCP only works in agent mode).Example prompts: * “Codify this repository using Cognee” * “Use Cognee CODE search to find authentication logic” * “Search my code for database connections” [​](https://docs.cognee.ai/cognee-mcp/integrations/continue#where-to-use-this-configuration) Where to Use This Configuration ------------------------------------------------------------------------------------------------------------------------------- The `.continue/mcpServers/` directory is at the workspace level. Each workspace can have its own MCP server configurations. Continue automatically detects YAML files in this directory. [​](https://docs.cognee.ai/cognee-mcp/integrations/continue#alternative:-using-json-format) Alternative: Using JSON Format ----------------------------------------------------------------------------------------------------------------------------- If you have JSON MCP configuration from another tool, you can copy it directly: Copy # Copy from Cursor, Claude, or Cline cp ~/.cursor/mcp.json .continue/mcpServers/cognee.json Continue automatically picks up both YAML and JSON configurations. [​](https://docs.cognee.ai/cognee-mcp/integrations/continue#need-help) Need Help? ------------------------------------------------------------------------------------ [Join Our Community\ ------------------\ \ Get support and connect with other developers using Cognee MCP.](https://discord.gg/m63hxKsp4p) Was this page helpful? YesNo [Previous](https://docs.cognee.ai/cognee-mcp/integrations/cursor) [Cline\ \ Next](https://docs.cognee.ai/cognee-mcp/integrations/cline) ⌘I On this page * [Continue Integration](https://docs.cognee.ai/cognee-mcp/integrations/continue#continue-integration) * [Prerequisites](https://docs.cognee.ai/cognee-mcp/integrations/continue#prerequisites) * [Setup Steps](https://docs.cognee.ai/cognee-mcp/integrations/continue#setup-steps) * [Where to Use This Configuration](https://docs.cognee.ai/cognee-mcp/integrations/continue#where-to-use-this-configuration) * [Alternative: Using JSON Format](https://docs.cognee.ai/cognee-mcp/integrations/continue#alternative:-using-json-format) * [Need Help?](https://docs.cognee.ai/cognee-mcp/integrations/continue#need-help) --- # Cline - Cognee Documentation [Skip to main content](https://docs.cognee.ai/cognee-mcp/integrations/cline#content-area) [Cognee Documentation home page![light logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20black.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=ea48b52be1df02b5909f780e6cd6856e)![dark logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20white.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=9f5bc18c4897c6e58b5cfa2b09bc079d)](https://docs.cognee.ai/) Search... ⌘K Search... Navigation Integrations Cline [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) [​](https://docs.cognee.ai/cognee-mcp/integrations/cline#cline-integration) Cline Integration ================================================================================================ Cline is a VS Code extension that provides AI assistance with support for MCP servers. It enables natural language interactions with external tools directly in your development environment. [​](https://docs.cognee.ai/cognee-mcp/integrations/cline#prerequisites) Prerequisites ---------------------------------------------------------------------------------------- * Visual Studio Code installed * Cognee MCP server running (see [Quickstart](https://docs.cognee.ai/cognee-mcp/mcp-quickstart) or [Local Setup](https://docs.cognee.ai/cognee-mcp/mcp-local-setup) ) * OpenAI API key [​](https://docs.cognee.ai/cognee-mcp/integrations/cline#setup-steps) Setup Steps ------------------------------------------------------------------------------------ 1 Install Cline 1. Open Visual Studio Code 2. Go to the Extensions panel 3. Search for “Cline” or visit the [Marketplace page](https://marketplace.visualstudio.com/items?itemName=saoudrizwan.claude-dev) 4. Click Install 2 Open Cline MCP Settings Follow the [Cline MCP configuration guide](https://docs.cline.bot/mcp/configuring-mcp-servers) to access settings: 1. Click the “MCP Servers” icon in the top navigation bar of the Cline extension 2. Select the “Configure” tab 3. Click the “Configure MCP Servers” button at the bottom of the pane Cline will open the `cline_mcp_settings.json` file with the base structure: Copy { "mcpServers": { } } 3 Add Cognee Server Configuration Add the Cognee server inside the `mcpServers` object. Choose the configuration that matches how you started the Cognee MCP server: * Docker (SSE) * Local (stdio) Use this if you started the server with Docker: Copy { "mcpServers": { "cognee": { "url": "http://localhost:8000/sse", "disabled": false } } } This configuration tells Cline to connect to the SSE endpoint exposed by the Docker container. Save the file after adding your configuration. The Cognee server will appear in the MCP Servers panel. You can use the toggle to enable/disable it or click Restart if needed. 4 Use Cognee Tools Open the Cline interface.Example commands: * “Prune cognee” - Clear the database * “Run codify in this repo” - Build a code knowledge graph * “Find dependencies with CODE search” - Query the code graph [​](https://docs.cognee.ai/cognee-mcp/integrations/cline#where-to-use-this-configuration) Where to Use This Configuration ---------------------------------------------------------------------------------------------------------------------------- The `cline_mcp_settings.json` file is in your VS Code global storage directory. Cline reads this file when the extension starts and applies the configuration to all projects. You can manage servers through the Cline UI - click the “MCP Servers” icon to enable/disable servers, restart them, or adjust settings without editing JSON directly. See the [Cline MCP documentation](https://docs.cline.bot/mcp/configuring-mcp-servers) for details. [​](https://docs.cognee.ai/cognee-mcp/integrations/cline#need-help) Need Help? --------------------------------------------------------------------------------- [Join Our Community\ ------------------\ \ Get support and connect with other developers using Cognee MCP.](https://discord.gg/m63hxKsp4p) Was this page helpful? YesNo [Previous](https://docs.cognee.ai/cognee-mcp/integrations/continue) [Roo Code\ \ Next](https://docs.cognee.ai/cognee-mcp/integrations/roo-code) ⌘I On this page * [Cline Integration](https://docs.cognee.ai/cognee-mcp/integrations/cline#cline-integration) * [Prerequisites](https://docs.cognee.ai/cognee-mcp/integrations/cline#prerequisites) * [Setup Steps](https://docs.cognee.ai/cognee-mcp/integrations/cline#setup-steps) * [Where to Use This Configuration](https://docs.cognee.ai/cognee-mcp/integrations/cline#where-to-use-this-configuration) * [Need Help?](https://docs.cognee.ai/cognee-mcp/integrations/cline#need-help) --- # Evaluation with DeepEval - Cognee Documentation [Skip to main content](https://docs.cognee.ai/integrations/deepeval-integration#content-area) [Cognee Documentation home page![light logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20black.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=ea48b52be1df02b5909f780e6cd6856e)![dark logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20white.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=9f5bc18c4897c6e58b5cfa2b09bc079d)](https://docs.cognee.ai/) Search... ⌘K Search... Navigation Evaluation Evaluation with DeepEval [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) [​](https://docs.cognee.ai/integrations/deepeval-integration#why-deepeval) Why DeepEval? ------------------------------------------------------------------------------------------- [DeepEval](https://deepeval.com/) is an open-source evaluation framework that provides ready-made metrics (both traditional and LLM-as-a-judge) for LLM pipelines. Compared with hand-rolled evaluation scripts, DeepEval lets you: * Track **Contextual Relevancy**, **Contextual Precision/Recall**, **Coverage** and more. * Swap between automatic string-based metrics (EM/F1) and LLM-based scoring with a single flag. * Re-use the same metrics across different projects and datasets. > DeepEval stores no data – it simply runs metrics locally or via your preferred LLM. That makes it a perfect drop-in evaluator for Cognee’s pipelines. [​](https://docs.cognee.ai/integrations/deepeval-integration#deepeval-inside-cognee) DeepEval inside Cognee -------------------------------------------------------------------------------------------------------------- Cognee ships with a dedicated **`DeepEvalAdapter`**. When enabled, every answer produced by your pipeline is scored with the metrics you choose. Copy evaluating_answers: bool = True evaluating_contexts: bool = True evaluation_engine: str = "DeepEval" # Options: 'DeepEval', 'DirectLLM' evaluation_metrics: list[str] = [\ "correctness", # LLM-based correctness\ "EM", # Exact-Match\ "f1", # Token-level precision / recall\ ] deepeval_model: str = "gpt-4o-mini" # Any OpenAI-compatible LLM Behind the scenes the adapter: 1. Transforms Cognee’s `Answer` objects into DeepEval’s `LLMTestCase` format. 2. Runs the selected metrics. 3. Stores the raw scores alongside rationales so they appear in Cognee’s HTML dashboard. [​](https://docs.cognee.ai/integrations/deepeval-integration#quick-start) Quick Start ---------------------------------------------------------------------------------------- 1. **Install Cognee** (DeepEval is declared in `pyproject.toml` so you automatically get the dependency). 2. Set your LLM API key so DeepEval can run LLM-based metrics: Copy import os os.environ["LLM_API_KEY"] = "" You can also export the variable in your shell (`export LLM_API_KEY=...`). 3. (Optional) Configure the model DeepEval should call: Copy export DEEPEVAL_MODEL=gpt-4o 4. Run a standard Cognee pipeline (add → cognify → search). The evaluation executor will automatically invoke DeepEval. [​](https://docs.cognee.ai/integrations/deepeval-integration#useful-links) Useful Links ------------------------------------------------------------------------------------------ * DeepEval integration guide – [deepeval.com » Cognee](https://deepeval.com/integrations/vector-databases/cognee) * DeepEval docs – [deepeval.com/docs](https://deepeval.com/docs/getting-started) * * * Join the conversation on [Discord](https://discord.gg/m63hxKsp4p) and let us know how DeepEval works for you! Was this page helpful? YesNo [Previous](https://docs.cognee.ai/integrations/keywordsai-integration) [Agent Memory with LangGraph\ \ Next](https://docs.cognee.ai/integrations/langgraph-integration) ⌘I On this page * [Why DeepEval?](https://docs.cognee.ai/integrations/deepeval-integration#why-deepeval) * [DeepEval inside Cognee](https://docs.cognee.ai/integrations/deepeval-integration#deepeval-inside-cognee) * [Quick Start](https://docs.cognee.ai/integrations/deepeval-integration#quick-start) * [Useful Links](https://docs.cognee.ai/integrations/deepeval-integration#useful-links) --- # Modal Deployment - Cognee Documentation [Skip to main content](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment/modal#content-area) [Cognee Documentation home page![light logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20black.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=ea48b52be1df02b5909f780e6cd6856e)![dark logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20white.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=9f5bc18c4897c6e58b5cfa2b09bc079d)](https://docs.cognee.ai/) Search... ⌘K Search... Navigation Self-Hosting Modal Deployment [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) [​](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment/modal#modal-deployment) Modal Deployment ========================================================================================================== Deploy Cognee on Modal for serverless, auto-scaling knowledge graph processing with minimal infrastructure management. Modal is a cloud platform that lets you run code remotely with automatic scaling, perfect for variable Cognee workloads. [​](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment/modal#why-modal) Why Modal? --------------------------------------------------------------------------------------------- Serverless Scaling ------------------ Automatically scales based on workload without server management Cost Efficient -------------- Pay only for compute time used, ideal for batch processing Fast Deployment --------------- Deploy within seconds with minimal configuration GPU Support ----------- Access to powerful GPUs for LLM processing when needed [​](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment/modal#prerequisites) Prerequisites ---------------------------------------------------------------------------------------------------- 1 Modal Account Create a free account at [modal.com](https://modal.com/) 2 Install Modal CLI Copy pip install modal modal token new 3 Environment Variables Set up your environment variables: Copy # Required export OPENAI_API_KEY="your-openai-api-key" # Optional - for external databases export POSTGRES_URL="postgresql://user:pass@host:5432/db" export NEO4J_URL="bolt://user:pass@host:7687" export QDRANT_URL="http://host:6333" [​](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment/modal#quick-deployment) Quick Deployment ---------------------------------------------------------------------------------------------------------- 1 Clone Repository Copy git clone https://github.com/topoteretes/cognee.git cd cognee 2 Install Dependencies Copy # Install with uv (recommended) uv sync --dev --all-extras --reinstall # Activate virtual environment source .venv/bin/activate 3 Deploy to Modal Copy # Run the Modal deployment script modal run -d modal_deployment.py The `-d` flag runs the deployment in detached mode. Monitor progress in your Modal dashboard. 4 Monitor Deployment Visit your [Modal dashboard](https://modal.com/apps) to monitor the deployment status and view logs. [​](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment/modal#configuration-options) Configuration Options -------------------------------------------------------------------------------------------------------------------- * Basic Setup * Production Setup * Hybrid Setup **Default Configuration**Uses embedded databases for quick testing: Copy # modal_deployment.py configuration GRAPH_DATABASE = "networkx" VECTOR_DATABASE = "lancedb" RELATIONAL_DATABASE = "sqlite" [​](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment/modal#deployment-architecture) Deployment Architecture ------------------------------------------------------------------------------------------------------------------------ Compute Resources Modal automatically provisions compute resources based on your workload: * **CPU**: 2-16 cores per container * **Memory**: 4-64 GB RAM per container * **GPU**: Optional NVIDIA GPUs for LLM processing * **Storage**: Ephemeral storage per container Auto-scaling Modal scales your deployment automatically: * **Cold Start**: ~2-5 seconds to spin up new containers * **Concurrent Processing**: Multiple containers for parallel workloads * **Auto-shutdown**: Containers shut down when idle to save costs Data Persistence Configure persistent storage for your data: * **Volumes**: Modal volumes for persistent file storage * **External DBs**: Connect to managed database services * **S3 Integration**: Direct S3 access for large datasets [​](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment/modal#monitoring-&-debugging) Monitoring & Debugging ---------------------------------------------------------------------------------------------------------------------- Modal Dashboard --------------- **Real-time Monitoring**View logs, metrics, and container status in the Modal web interface. Log Streaming ------------- **Live Logs**Stream logs directly to your terminal: Copy modal logs cognee-app [​](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment/modal#video-tutorial) Video Tutorial ------------------------------------------------------------------------------------------------------ [​](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment/modal#cost-optimization) Cost Optimization ------------------------------------------------------------------------------------------------------------ **Batch Processing**: Group multiple documents together to maximize container utilization and reduce cold start costs. **Database Costs**: Consider using Modal’s built-in storage for development and external managed services for production. [​](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment/modal#troubleshooting) Troubleshooting -------------------------------------------------------------------------------------------------------- Common Issues **Container Timeout** * Increase timeout limits in `modal_deployment.py` * Break large datasets into smaller batches **Memory Errors** * Increase container memory allocation * Use streaming processing for large files Environment Variables **Missing API Keys** * Ensure all required environment variables are set * Use Modal secrets for sensitive data **Database Connections** * Verify database URLs and credentials * Check network connectivity from Modal containers [​](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment/modal#next-steps) Next Steps ---------------------------------------------------------------------------------------------- Scale Up -------- **Production Deployment**Configure external databases and optimize for production workloads. Monitor Usage ------------- **Track Costs**Monitor compute usage and optimize batch sizes for cost efficiency. [Need Help?\ ----------\ \ Join our community for Modal deployment support and best practices.](https://discord.gg/m63hxKsp4p) Was this page helpful? YesNo [Previous\ \ Kubernetes (Helm)Deploy Cognee on Kubernetes with Helm charts for enterprise-grade, production-ready deployments](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment/helm) ⌘I On this page * [Modal Deployment](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment/modal#modal-deployment) * [Why Modal?](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment/modal#why-modal) * [Prerequisites](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment/modal#prerequisites) * [Quick Deployment](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment/modal#quick-deployment) * [Configuration Options](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment/modal#configuration-options) * [Deployment Architecture](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment/modal#deployment-architecture) * [Monitoring & Debugging](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment/modal#monitoring-&-debugging) * [Video Tutorial](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment/modal#video-tutorial) * [Cost Optimization](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment/modal#cost-optimization) * [Troubleshooting](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment/modal#troubleshooting) * [Next Steps](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment/modal#next-steps) --- # Python API Documentation - Cognee Documentation [Skip to main content](https://docs.cognee.ai/python-api#content-area) [Cognee Documentation home page![light logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20black.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=ea48b52be1df02b5909f780e6cd6856e)![dark logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20white.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=9f5bc18c4897c6e58b5cfa2b09bc079d)](https://docs.cognee.ai/) Search... ⌘K Search... Navigation Coming Soon Python API Documentation [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) [​](https://docs.cognee.ai/python-api#python-api-documentation) Python API Documentation =========================================================================================== Coming soon! We’re working on comprehensive Python API documentation that will include: * Complete function and class references * Interactive code examples * Type hints and parameter descriptions * Usage patterns and best practices In the meantime, you can explore our [Guides](https://docs.cognee.ai/guides) for practical examples and tutorials. The Python API documentation is currently under development. Check back soon for updates! Was this page helpful? YesNo ⌘I On this page * [Python API Documentation](https://docs.cognee.ai/python-api#python-api-documentation) --- # Observability with Keywords AI - Cognee Documentation [Skip to main content](https://docs.cognee.ai/integrations/keywordsai-integration#content-area) [Cognee Documentation home page![light logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20black.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=ea48b52be1df02b5909f780e6cd6856e)![dark logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20white.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=9f5bc18c4897c6e58b5cfa2b09bc079d)](https://docs.cognee.ai/) Search... ⌘K Search... Navigation Observability Observability with Keywords AI [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) [​](https://docs.cognee.ai/integrations/keywordsai-integration#observability-with-keywords-ai) Observability with Keywords AI -------------------------------------------------------------------------------------------------------------------------------- [Keywords AI](https://www.keywordsai.co/) provides observability and tracing for LLM-powered and agentic applications. In Cognee, it captures spans for tasks and workflows via the same `@observe` decorator used across providers. [​](https://docs.cognee.ai/integrations/keywordsai-integration#keywords-ai-inside-cognee) Keywords AI inside Cognee ---------------------------------------------------------------------------------------------------------------------- Cognee exposes a single abstraction for observability: `get_observe()` returning the `@observe` decorator. The Keywords AI integration is provided via the `cognee-community` extension hub as `cognee-community-observability-keywordsai`. * **About `cognee-community`**: This is Cognee’s extension hub. Adapters for third‑party databases, pipelines, and community-contributed tasks live here, evolving independently from core. Installs stay slim (only what you need), and a predictable layout under `packages/*` keeps providers consistent. * **Drop-in**: Importing the package patches Cognee’s `get_observe()` to return a Keywords AI–backed decorator when `MONITORING_TOOL=keywordsai`. * **Decorator mapping**: `@observe` and `@observe(workflow=True)` map to Keywords AI’s `task()` and `workflow()` decorators from `keywordsai-tracing`. ### [​](https://docs.cognee.ai/integrations/keywordsai-integration#installation-and-configuration) Installation and Configuration Copy pip install cognee-community-observability-keywordsai # Required export MONITORING_TOOL=keywordsai export KEYWORDSAI_API_KEY= # If your pipeline elsewhere calls LLMs (optional) export LLM_API_KEY= ### [​](https://docs.cognee.ai/integrations/keywordsai-integration#minimal-example) Minimal Example Copy # 1) Import to patch Cognee import cognee_community_observability_keywordsai # noqa: F401 # 2) Use Cognee's abstraction from cognee.modules.observability.get_observe import get_observe observe = get_observe() # returns Keywords AI decorator when MONITORING_TOOL=keywordsai # 3) Decorate a task @observe def ingest_files(data: list[dict]): ... # 4) Decorate a workflow @observe(workflow=True) async def main(): ... Behind the scenes, Cognee’s community adapter: 1. Patches `get_observe()` so it returns a Keywords AI–aware decorator when configured. 2. Initializes telemetry via `KeywordsAITelemetry()` once on import. 3. Wraps tasks with `task()` and workflows with `workflow()` from `keywordsai-tracing`. [​](https://docs.cognee.ai/integrations/keywordsai-integration#quick-start) Quick Start ------------------------------------------------------------------------------------------ 1. Install the integration: Copy pip install cognee-community-observability-keywordsai 2. Configure your environment: Copy export MONITORING_TOOL=keywordsai export KEYWORDSAI_API_KEY= export LLM_API_KEY= 3. Import the package early (so `get_observe()` is patched), decorate your tasks/workflows, and run your pipeline. 4. Open your Keywords AI dashboard to inspect spans across tasks and workflows. [​](https://docs.cognee.ai/integrations/keywordsai-integration#useful-links) Useful Links -------------------------------------------------------------------------------------------- * Get a Keywords AI API key: [Keywords AI Platform](https://platform.keywordsai.co/) * Community package: [cognee-community/packages/observability/keywordsai](https://github.com/topoteretes/cognee-community/tree/main/packages/observability/keywordsai) * * * Join the conversation on [Discord](https://discord.gg/m63hxKsp4p) and let us know how the Keywords AI integration works for you! Was this page helpful? YesNo [Previous](https://docs.cognee.ai/integrations/langfuse-integration) [Evaluation with DeepEval\ \ Next](https://docs.cognee.ai/integrations/deepeval-integration) ⌘I On this page * [Observability with Keywords AI](https://docs.cognee.ai/integrations/keywordsai-integration#observability-with-keywords-ai) * [Keywords AI inside Cognee](https://docs.cognee.ai/integrations/keywordsai-integration#keywords-ai-inside-cognee) * [Installation and Configuration](https://docs.cognee.ai/integrations/keywordsai-integration#installation-and-configuration) * [Minimal Example](https://docs.cognee.ai/integrations/keywordsai-integration#minimal-example) * [Quick Start](https://docs.cognee.ai/integrations/keywordsai-integration#quick-start) * [Useful Links](https://docs.cognee.ai/integrations/keywordsai-integration#useful-links) --- # Cognee Cloud SDK - Cognee Documentation [Skip to main content](https://docs.cognee.ai/cognee-cloud/cognee-cloud-sdk#content-area) [Cognee Documentation home page![light logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20black.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=ea48b52be1df02b5909f780e6cd6856e)![dark logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20white.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=9f5bc18c4897c6e58b5cfa2b09bc079d)](https://docs.cognee.ai/) Search... ⌘K Search... Navigation Cognee Cloud Platform Cognee Cloud SDK [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) The Cognee Cloud SDK is the recommended way to interact with Cognee Cloud programmatically. It is open source and provides a clean Python interface for working with the Cognee Cloud platform. In particular, it makes it easy to perform core Cognee operations—add, cognify, memify, and search—that power Cognee Cloud. You’ll need an [API key](https://docs.cognee.ai/cognee-cloud/sign-up) to get started. While you can call Cognee Cloud API endpoints directly, the SDK is recommended for its error handling, type safety, and overall developer experience. [​](https://docs.cognee.ai/cognee-cloud/cognee-cloud-sdk#install-and-configure) Install and configure -------------------------------------------------------------------------------------------------------- Copy # 1. Create a virtual environment (optional) uv venv && source .venv/bin/activate # 2. Install the SDK uv pip install cogwit-sdk # 3. Store your key and base URL export COGWIT_API_KEY="" [​](https://docs.cognee.ai/cognee-cloud/cognee-cloud-sdk#complete-example) Complete example ---------------------------------------------------------------------------------------------- Let’s jump straight in with a full code example of Cognee Cloud in action. We’ll then go over the code piece by piece and explain all the relevant parts in detail. Copy import asyncio import os from cogwit_sdk import cogwit, CogwitConfig from cogwit_sdk.responses import ( AddResponse, CognifyResponse, CombinedSearchResult, SearchResult, ) # Create configuration with your API key cogwit_config = CogwitConfig( api_key=os.getenv("COGWIT_API_KEY", ""), ) # Create the client instance cogwit_instance = cogwit(cogwit_config) async def main(): # Add data to your dataset result = await cogwit_instance.add( data="Cognee Cloud automates knowledge graph creation in the cloud.", dataset_name="demo_dataset", ) print(f"Added data: {result.status}") dataset_id = result.dataset_id # Transform data into knowledge graph cognify_result = await cogwit_instance.cognify( dataset_ids=[dataset_id], ) print(f"Cognify status: {cognify_result[str(dataset_id)].status}") # Search with graph completion search_results = await cogwit_instance.search( query_text="What does Cognee Cloud automate?", query_type=cogwit_instance.SearchType.GRAPH_COMPLETION, ) for result in search_results: print(f" {result.search_result}") # Search for raw chunks chunk_results = await cogwit_instance.search( query_text="What does Cognee Cloud automate?", query_type=cogwit_instance.SearchType.CHUNKS, ) for result in chunk_results: print(f" {result.search_result[0]['text']}") asyncio.run(main()) [​](https://docs.cognee.ai/cognee-cloud/cognee-cloud-sdk#what-just-happened) What just happened -------------------------------------------------------------------------------------------------- ### [​](https://docs.cognee.ai/cognee-cloud/cognee-cloud-sdk#client-setup) Client setup Copy cogwit_config = CogwitConfig( api_key=os.getenv("COGWIT_API_KEY", ""), ) cogwit_instance = cogwit(cogwit_config) The SDK uses a client pattern to manage your connection to Cognee Cloud. The client handles authentication, request formatting, and response parsing for you. All SDK operations are async, so we wrap everything in `async def main()` and run it with `asyncio.run(main())`. ### [​](https://docs.cognee.ai/cognee-cloud/cognee-cloud-sdk#adding-data) Adding data Copy result = await cogwit_instance.add( data="Cognee Cloud automates knowledge graph creation in the cloud.", dataset_name="demo_dataset", ) The `add` operation uploads text to Cognee Cloud and schedules preprocessing. All data is organized by [dataset](https://docs.cognee.ai/cognee-cloud/permissions-security) for proper isolation. It returns an `AddResponse` with: * `status` - Whether the operation completed successfully * `dataset_id` - Unique identifier for your dataset (save this!) * `dataset_name` - The name you provided ### [​](https://docs.cognee.ai/cognee-cloud/cognee-cloud-sdk#cognifying-data) Cognifying data Copy cognify_result = await cogwit_instance.cognify( dataset_ids=[dataset_id], ) The `cognify` operation transforms your data into a knowledge graph. It returns a `CognifyResponse` that maps dataset IDs to their processing status. Wait for `PipelineRunCompleted` before searching. ### [​](https://docs.cognee.ai/cognee-cloud/cognee-cloud-sdk#searching-your-data) Searching your data Copy # Graph completion search search_results = await cogwit_instance.search( query_text="What does Cognee Cloud automate?", query_type=cogwit_instance.SearchType.GRAPH_COMPLETION, ) The `search` operation queries your knowledge graph. By default it uses `GRAPH_COMPLETION`, but you can use any of the [Cognee search types](https://docs.cognee.ai/core-concepts/main-operations/search) . See also [Search Basics](https://docs.cognee.ai/guides/search-basics) for detailed parameter explanations. [​](https://docs.cognee.ai/cognee-cloud/cognee-cloud-sdk#next-steps) Next steps ---------------------------------------------------------------------------------- [Cognee Cloud architecture\ -------------------------\ \ Design end-to-end add → cognify → memify → search automations.](https://docs.cognee.ai/cognee-cloud/cognee-cloud-architecture) [Cognee Cloud UI\ ---------------\ \ Learn to manage datasets and upload files through the UI.](https://docs.cognee.ai/cognee-cloud/cognee-cloud-ui) Was this page helpful? YesNo [Previous](https://docs.cognee.ai/cognee-cloud/cognee-cloud-notebooks) [Local Mode & SyncConnect to local Cognee instances and sync data between local and cloud environments\ \ Next](https://docs.cognee.ai/cognee-cloud/local-mode-and-sync) ⌘I On this page * [Install and configure](https://docs.cognee.ai/cognee-cloud/cognee-cloud-sdk#install-and-configure) * [Complete example](https://docs.cognee.ai/cognee-cloud/cognee-cloud-sdk#complete-example) * [What just happened](https://docs.cognee.ai/cognee-cloud/cognee-cloud-sdk#what-just-happened) * [Client setup](https://docs.cognee.ai/cognee-cloud/cognee-cloud-sdk#client-setup) * [Adding data](https://docs.cognee.ai/cognee-cloud/cognee-cloud-sdk#adding-data) * [Cognifying data](https://docs.cognee.ai/cognee-cloud/cognee-cloud-sdk#cognifying-data) * [Searching your data](https://docs.cognee.ai/cognee-cloud/cognee-cloud-sdk#searching-your-data) * [Next steps](https://docs.cognee.ai/cognee-cloud/cognee-cloud-sdk#next-steps) --- # Observability with Langfuse - Cognee Documentation [Skip to main content](https://docs.cognee.ai/integrations/langfuse-integration#content-area) [Cognee Documentation home page![light logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20black.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=ea48b52be1df02b5909f780e6cd6856e)![dark logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20white.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=9f5bc18c4897c6e58b5cfa2b09bc079d)](https://docs.cognee.ai/) Search... ⌘K Search... Navigation Observability Observability with Langfuse [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) [​](https://docs.cognee.ai/integrations/langfuse-integration#observability-with-langfuse) Observability with Langfuse ------------------------------------------------------------------------------------------------------------------------ [Langfuse](https://langfuse.com/) is an open-source observability and analytics platform for LLM-powered applications. It collects traces, generations, and custom metrics so that you can debug, evaluate, and monitor your AI features in production. [​](https://docs.cognee.ai/integrations/langfuse-integration#integration-inside-cognee) Integration inside Cognee -------------------------------------------------------------------------------------------------------------------- Cognee ships with Langfuse support out of the box. The integration is intentionally lightweight and consists of just a few lines of code. Anywhere in the codebase where we want observability we add: Copy from cognee.modules.observability.get_observe import get_observe observe = get_observe() @observe(as_type="generation") # optional label async def acreate_structured_output(...): ... > The decorator is a thin wrapper around Langfuse and automatically creates a **span** every time the function is executed. The data is sent to the Langfuse backend specified via environment variables and can be inspected in the Langfuse UI. [​](https://docs.cognee.ai/integrations/langfuse-integration#quick-start) Quick start ---------------------------------------------------------------------------------------- 1. Install cognee (it comes with Langfuse) Langfuse is already declared in `pyproject.toml`, so you can skip this step if you already installed cognee. 2. Create a project at [Langfuse Cloud](https://cloud.langfuse.com/) and copy the _public_ and _secret_ keys. 3. Export the following environment variables (for example in your `.env` file): Copy LANGFUSE_PUBLIC_KEY= LANGFUSE_SECRET_KEY= LANGFUSE_HOST=https://cloud.langfuse.com `BaseConfig` reads these values on startup, so nothing else is required. Start Cognee as usual and open the Langfuse UI – traces will appear in real time. [​](https://docs.cognee.ai/integrations/langfuse-integration#run-your-regular-cognee-workflows:) Run your regular Cognee workflows: -------------------------------------------------------------------------------------------------------------------------------------- Copy import cognee import asyncio from cognee.modules.observability.get_observe import get_observe observe = get_observe() @observe(name="simple_example_run", as_type="example") async def main(): await cognee.add("Natural language processing (NLP) is ...") await cognee.cognify() results = await cognee.search("Tell me about NLP") for r in results: print(r) asyncio.run(main()) [​](https://docs.cognee.ai/integrations/langfuse-integration#adding-your-own-spans) Adding your own spans ------------------------------------------------------------------------------------------------------------ You can instrument **any** function in your codebase: Copy from cognee.modules.observability.get_observe import get_observe observe = get_observe() @observe(as_type="my_tool", metadata={"foo": "bar"}) def my_helper(arg1, arg2): ... All keyword arguments accepted by `langfuse.decorators.observe` (`name`, `as_type`, `metadata`, …) are forwarded unchanged – see the [Langfuse Python SDK docs](https://langfuse.com/docs/sdk/python) for the full reference. * * * Join [Langfuse](https://discord.langfuse.com/) and [cognee](https://discord.gg/cqF6RhDYWz) communities on Discord for any questions. Was this page helpful? YesNo [Previous](https://docs.cognee.ai/integrations/aws-bedrock-integration) [Observability with Keywords AI\ \ Next](https://docs.cognee.ai/integrations/keywordsai-integration) ⌘I On this page * [Observability with Langfuse](https://docs.cognee.ai/integrations/langfuse-integration#observability-with-langfuse) * [Integration inside Cognee](https://docs.cognee.ai/integrations/langfuse-integration#integration-inside-cognee) * [Quick start](https://docs.cognee.ai/integrations/langfuse-integration#quick-start) * [Run your regular Cognee workflows:](https://docs.cognee.ai/integrations/langfuse-integration#run-your-regular-cognee-workflows:) * [Adding your own spans](https://docs.cognee.ai/integrations/langfuse-integration#adding-your-own-spans) --- # Local Setup - Cognee Documentation [Skip to main content](https://docs.cognee.ai/cognee-mcp/mcp-local-setup#content-area) [Cognee Documentation home page![light logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20black.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=ea48b52be1df02b5909f780e6cd6856e)![dark logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20white.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=9f5bc18c4897c6e58b5cfa2b09bc079d)](https://docs.cognee.ai/) Search... ⌘K Search... Navigation Setup Local Setup [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) Build and run Cognee MCP from source to access advanced customization, multiple transport options, and the latest development features. [​](https://docs.cognee.ai/cognee-mcp/mcp-local-setup#advantages-of-local-setup) Advantages of Local Setup ------------------------------------------------------------------------------------------------------------- * **Full Control**: Customize server configuration, add providers, and modify behavior * **Latest Features**: Access development features before they reach Docker releases * **Multiple Transports**: Choose stdio, SSE, or HTTP transport modes * **Development Ready**: Debug, modify, and contribute to the codebase [​](https://docs.cognee.ai/cognee-mcp/mcp-local-setup#setup-steps) Setup Steps --------------------------------------------------------------------------------- 1 Clone Repository Copy git clone https://github.com/topoteretes/cognee.git cd cognee 2 Create Environment File Create a `.env` file with your configuration: Copy LLM_API_KEY="your-openai-api-key" 3 Install Dependencies Copy # Install uv package manager brew install uv # Install project dependencies cd cognee-mcp uv sync --dev --all-extras --reinstall 4 Activate and Run Copy # Activate virtual environment source .venv/bin/activate # Run with default stdio transport python src/server.py [​](https://docs.cognee.ai/cognee-mcp/mcp-local-setup#transport-modes) Transport Modes ----------------------------------------------------------------------------------------- Choose the transport mode based on your client requirements: * stdio * HTTP * SSE Default mode for most MCP clients. The client starts the server as a subprocess and communicates through standard input/output. Copy python src/server.py Use this with Cursor, Claude Code, Cline, and Roo Code when running from source. If you encounter errors on first run, reset your MCP configuration and restart. [​](https://docs.cognee.ai/cognee-mcp/mcp-local-setup#running-in-api-mode) Running in API Mode ------------------------------------------------------------------------------------------------- To connect the MCP server to an existing Cognee backend instead of running standalone: Copy # Set the backend API URL export API_URL=http://localhost:8080 # Optional: Set authentication token if backend requires it export API_TOKEN=your_backend_token # Start MCP in HTTP or SSE mode pointing to the backend python src/server.py --transport http When `API_URL` is set, the MCP server acts as an interface to the centralized backend. This allows multiple MCP instances and clients to share the same knowledge graph. You can also pass these as command-line arguments: Copy python src/server.py --transport http --api-url http://localhost:8080 --api-token your_token **Use cases:** * Team collaboration with shared memory * Multiple AI clients accessing consistent data * Centralized knowledge graph management [​](https://docs.cognee.ai/cognee-mcp/mcp-local-setup#next-steps) Next Steps ------------------------------------------------------------------------------- After starting the server, configure your AI client to connect to it. See the [integrations](https://docs.cognee.ai/cognee-mcp/integrations) section for client-specific setup instructions. [​](https://docs.cognee.ai/cognee-mcp/mcp-local-setup#need-help) Need Help? ------------------------------------------------------------------------------ [Join Our Community\ ------------------\ \ Get support and connect with other developers using Cognee MCP.](https://discord.gg/m63hxKsp4p) Was this page helpful? YesNo [Previous](https://docs.cognee.ai/cognee-mcp/mcp-tools) [Claude Code\ \ Next](https://docs.cognee.ai/cognee-mcp/integrations/claude-code) ⌘I On this page * [Advantages of Local Setup](https://docs.cognee.ai/cognee-mcp/mcp-local-setup#advantages-of-local-setup) * [Setup Steps](https://docs.cognee.ai/cognee-mcp/mcp-local-setup#setup-steps) * [Transport Modes](https://docs.cognee.ai/cognee-mcp/mcp-local-setup#transport-modes) * [Running in API Mode](https://docs.cognee.ai/cognee-mcp/mcp-local-setup#running-in-api-mode) * [Next Steps](https://docs.cognee.ai/cognee-mcp/mcp-local-setup#next-steps) * [Need Help?](https://docs.cognee.ai/cognee-mcp/mcp-local-setup#need-help) --- # AWS Bedrock Integration - Cognee Documentation [Skip to main content](https://docs.cognee.ai/integrations/aws-bedrock-integration#content-area) [Cognee Documentation home page![light logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20black.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=ea48b52be1df02b5909f780e6cd6856e)![dark logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20white.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=9f5bc18c4897c6e58b5cfa2b09bc079d)](https://docs.cognee.ai/) Search... ⌘K Search... Navigation Cloud LLM Providers AWS Bedrock Integration [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) Integrate AWS Bedrock LLMs with Cognee using **LiteLLM Proxy** (not the SDK) for seamless access to Anthropic Claude, Amazon Titan, and other Bedrock models. The proxy acts as a server that Cognee connects to, providing a unified interface for all Bedrock models. [​](https://docs.cognee.ai/integrations/aws-bedrock-integration#prerequisites) Prerequisites ----------------------------------------------------------------------------------------------- * AWS account with Bedrock access * Python 3.8+ * Cognee 0.2.0+ [​](https://docs.cognee.ai/integrations/aws-bedrock-integration#setup) Setup ------------------------------------------------------------------------------- ### [​](https://docs.cognee.ai/integrations/aws-bedrock-integration#1-install-litellm-proxy) 1\. Install LiteLLM Proxy Use **LiteLLM Proxy** (not the SDK) for this integration. The proxy acts as a server that Cognee can connect to. Copy pip install litellm[proxy] For detailed setup instructions, refer to the [official LiteLLM Bedrock tutorial](https://docs.litellm.ai/docs/providers/bedrock) . ### [​](https://docs.cognee.ai/integrations/aws-bedrock-integration#2-configure-litellm-proxy) 2\. Configure LiteLLM Proxy Create a `config.yaml` file: Copy model_list: - model_name: bedrock-claude-3-5-sonnet litellm_params: model: bedrock/anthropic.claude-3-5-sonnet-20240620-v1:0 aws_access_key_id: your_aws_id aws_secret_access_key: your_aws_key aws_region_name: your_aws_region_name drop_params: true The `drop_params: true` setting is important for proper Bedrock integration. ### [​](https://docs.cognee.ai/integrations/aws-bedrock-integration#3-start-litellm-proxy) 3\. Start LiteLLM Proxy Copy litellm --config config.yaml The proxy will run on `http://localhost:4000` by default. ### [​](https://docs.cognee.ai/integrations/aws-bedrock-integration#4-configure-cognee) 4\. Configure Cognee Create a `.env` file: Copy LLM_API_KEY = "doesn't matter" LLM_MODEL = "litellm_proxy/bedrock-claude-3-5-sonnet" LLM_PROVIDER = "openai" LLM_ENDPOINT = "http://localhost:4000" EMBEDDING_PROVIDER=fastembed EMBEDDING_MODEL=sentence-transformers/all-MiniLM-L6-v2 EMBEDDING_DIMENSIONS=384 EMBEDDING_MAX_TOKENS=256 Set `LLM_PROVIDER = "openai"` - LiteLLM works with this format for Bedrock models. ### [​](https://docs.cognee.ai/integrations/aws-bedrock-integration#5-install-cognee) 5\. Install Cognee Copy pip install cognee==0.2.0 [​](https://docs.cognee.ai/integrations/aws-bedrock-integration#usage-example) Usage Example ----------------------------------------------------------------------------------------------- Copy import cognee import asyncio async def main(): # Add text to cognee await cognee.add("Natural language processing (NLP) is an interdisciplinary subfield of computer science and information retrieval.") # Generate the knowledge graph await cognee.cognify() # Query the knowledge graph results = await cognee.search("Tell me about NLP") # Display the results for result in results: print(result) if __name__ == '__main__': asyncio.run(main()) [​](https://docs.cognee.ai/integrations/aws-bedrock-integration#supported-bedrock-models) Supported Bedrock Models --------------------------------------------------------------------------------------------------------------------- * **Anthropic Claude**: `bedrock/anthropic.claude-3-5-sonnet-20240620-v1:0` * **Amazon Titan**: `bedrock/amazon.titan-text-express-v1` * **Cohere Command**: `bedrock/cohere.command-text-v14` * **AI21 Jurassic**: `bedrock/ai21.j2-ultra-v1` [​](https://docs.cognee.ai/integrations/aws-bedrock-integration#troubleshooting) Troubleshooting --------------------------------------------------------------------------------------------------- ### [​](https://docs.cognee.ai/integrations/aws-bedrock-integration#common-issues) Common Issues 1. **Authentication Errors**: Verify your AWS credentials and Bedrock permissions 2. **Model Not Found**: Ensure the model name matches exactly in your config 3. **Connection Issues**: Check that LiteLLM proxy is running on the correct port ### [​](https://docs.cognee.ai/integrations/aws-bedrock-integration#debug-mode) Debug Mode Enable debug logging in LiteLLM: Copy litellm --config config.yaml --debug [​](https://docs.cognee.ai/integrations/aws-bedrock-integration#resources) Resources --------------------------------------------------------------------------------------- [LiteLLM Bedrock Setup\ ---------------------\ \ **Official LiteLLM Tutorial**Complete setup guide for LiteLLM proxy with AWS Bedrock integration.](https://docs.litellm.ai/docs/providers/bedrock) [AWS Bedrock Models\ ------------------\ \ **Available Models**Explore all available Bedrock models including Claude, Titan, and Cohere.](https://docs.aws.amazon.com/bedrock/latest/userguide/models.html) Was this page helpful? YesNo [Previous](https://docs.cognee.ai/integrations) [Observability with Langfuse\ \ Next](https://docs.cognee.ai/integrations/langfuse-integration) ⌘I On this page * [Prerequisites](https://docs.cognee.ai/integrations/aws-bedrock-integration#prerequisites) * [Setup](https://docs.cognee.ai/integrations/aws-bedrock-integration#setup) * [1\. Install LiteLLM Proxy](https://docs.cognee.ai/integrations/aws-bedrock-integration#1-install-litellm-proxy) * [2\. Configure LiteLLM Proxy](https://docs.cognee.ai/integrations/aws-bedrock-integration#2-configure-litellm-proxy) * [3\. Start LiteLLM Proxy](https://docs.cognee.ai/integrations/aws-bedrock-integration#3-start-litellm-proxy) * [4\. Configure Cognee](https://docs.cognee.ai/integrations/aws-bedrock-integration#4-configure-cognee) * [5\. Install Cognee](https://docs.cognee.ai/integrations/aws-bedrock-integration#5-install-cognee) * [Usage Example](https://docs.cognee.ai/integrations/aws-bedrock-integration#usage-example) * [Supported Bedrock Models](https://docs.cognee.ai/integrations/aws-bedrock-integration#supported-bedrock-models) * [Troubleshooting](https://docs.cognee.ai/integrations/aws-bedrock-integration#troubleshooting) * [Common Issues](https://docs.cognee.ai/integrations/aws-bedrock-integration#common-issues) * [Debug Mode](https://docs.cognee.ai/integrations/aws-bedrock-integration#debug-mode) * [Resources](https://docs.cognee.ai/integrations/aws-bedrock-integration#resources) --- # Tools Reference - Cognee Documentation [Skip to main content](https://docs.cognee.ai/cognee-mcp/mcp-tools#content-area) [Cognee Documentation home page![light logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20black.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=ea48b52be1df02b5909f780e6cd6856e)![dark logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20white.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=9f5bc18c4897c6e58b5cfa2b09bc079d)](https://docs.cognee.ai/) Search... ⌘K Search... Navigation Setup Tools Reference [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) Cognee MCP provides 11 tools that MCP-compatible AI assistants can use for memory management, code intelligence, and data operations. [​](https://docs.cognee.ai/cognee-mcp/mcp-tools#available-tools) Available Tools ----------------------------------------------------------------------------------- Memory Management * **`add`**: Store new memory objects and documents in Cognee * **`cognify`**: Transform raw data into structured memories and knowledge graphs * **`search`**: Retrieve relevant memories using semantic search * **`list_datasets`**: View all stored memory datasets * **`prune`**: Clear all memory for a fresh start Code Intelligence * **`codify`**: Generate code-specific knowledge graphs from source code * **`save_interaction`**: Store user-assistant exchanges to build development rules * **`get_developer_rules`**: Retrieve stored developer rules and patterns Data Management * **`list_data`**: List existing datasets for the current user * **`delete`**: Remove specific data items from datasets * **`cloud_info`**: Get information about cloud configuration [​](https://docs.cognee.ai/cognee-mcp/mcp-tools#usage-notes) Usage Notes --------------------------------------------------------------------------- * Run `codify` before using `search` with the CODE search type * Use `prune` to reset the database when testing or starting fresh * The `cognify` tool processes general documents while `codify` is optimized for source code [​](https://docs.cognee.ai/cognee-mcp/mcp-tools#next-steps) Next Steps ------------------------------------------------------------------------- [Client Integrations\ -------------------\ \ Learn how to use these tools with your AI development environment](https://docs.cognee.ai/cognee-mcp/integrations) Was this page helpful? YesNo [Previous](https://docs.cognee.ai/cognee-mcp/mcp-quickstart) [Local SetupDeploy Cognee MCP server from source for development and customization\ \ Next](https://docs.cognee.ai/cognee-mcp/mcp-local-setup) ⌘I On this page * [Available Tools](https://docs.cognee.ai/cognee-mcp/mcp-tools#available-tools) * [Usage Notes](https://docs.cognee.ai/cognee-mcp/mcp-tools#usage-notes) * [Next Steps](https://docs.cognee.ai/cognee-mcp/mcp-tools#next-steps) --- # Agent Memory with LangGraph - Cognee Documentation [Skip to main content](https://docs.cognee.ai/integrations/langgraph-integration#content-area) [Cognee Documentation home page![light logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20black.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=ea48b52be1df02b5909f780e6cd6856e)![dark logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20white.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=9f5bc18c4897c6e58b5cfa2b09bc079d)](https://docs.cognee.ai/) Search... ⌘K Search... Navigation Agent Frameworks Agent Memory with LangGraph [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) Give your [LangGraph](https://langchain-ai.github.io/langgraph/) agents persistent semantic memory that survives across sessions. Store data in cognee’s knowledge graph and retrieve it via natural language—no manual state management required. [​](https://docs.cognee.ai/integrations/langgraph-integration#why-use-this-integration) Why Use This Integration ------------------------------------------------------------------------------------------------------------------- * **Cross-Session Memory**: Context persists across agent instances and conversation sessions * **Semantic Search**: Retrieve information using natural language queries * **Session Isolation**: Multi-tenant support with per-user data separation * **Zero Setup**: Works with LangGraph’s `create_react_agent` out of the box [​](https://docs.cognee.ai/integrations/langgraph-integration#installation) Installation ------------------------------------------------------------------------------------------- Copy pip install cognee-integration-langgraph [​](https://docs.cognee.ai/integrations/langgraph-integration#quick-start) Quick Start ----------------------------------------------------------------------------------------- Before using the integration, configure your environment variables: Copy export OPENAI_API_KEY="your-openai-api-key-here" # for LangGraph export LLM_API_KEY="your-openai-api-key-here" # for cognee export LLM_MODEL="gpt-4o-mini" Add memory tools to your LangGraph agent: Copy from langgraph.prebuilt import create_react_agent from cognee_integration_langgraph import get_sessionized_cognee_tools from langchain_core.messages import HumanMessage # Get memory tools add_tool, search_tool = get_sessionized_cognee_tools() # Create agent with memory agent = create_react_agent( "openai:gpt-4o-mini", tools=[add_tool, search_tool], ) # Store and retrieve information response = agent.invoke({ "messages": [\ HumanMessage(content="Remember: Acme Corp, healthcare, $1.2M contract"),\ HumanMessage(content="What healthcare contracts do we have?")\ ], }) [​](https://docs.cognee.ai/integrations/langgraph-integration#cross-session-persistence) Cross-Session Persistence --------------------------------------------------------------------------------------------------------------------- Memory persists across different agent instances: Copy # Session 1: Store information add_tool, search_tool = get_sessionized_cognee_tools("session-1") agent_1 = create_react_agent( "openai:gpt-4o-mini", tools=[add_tool, search_tool], ) agent_1.invoke({ "messages": [HumanMessage(content="I'm working on authentication")] }) # Session 2: Different instance, same memory add_tool, search_tool = get_sessionized_cognee_tools("session-2") agent_2 = create_react_agent( "openai:gpt-4o-mini", tools=[add_tool, search_tool], ) response = agent_2.invoke({ "messages": [HumanMessage(content="What was I working on?")] }) # Returns: "authentication module" [​](https://docs.cognee.ai/integrations/langgraph-integration#custom-session-management) Custom Session Management --------------------------------------------------------------------------------------------------------------------- Control session isolation with custom session IDs: Copy # User-specific memory user_tools = get_sessionized_cognee_tools(session_id="user_123") # Org-specific memory org_tools = get_sessionized_cognee_tools(session_id="org_acme") # Generate unique session automatically auto_tools = get_sessionized_cognee_tools() # Uses UUID-based session ID Each session maintains separate memory clusters while allowing global data access when needed. Data added outside sessions forms separate clusters. [​](https://docs.cognee.ai/integrations/langgraph-integration#how-it-works) How It Works ------------------------------------------------------------------------------------------- 1. **Add Tool**: Stores data in cognee’s knowledge graph with embeddings 2. **Search Tool**: Retrieves relevant information via semantic search 3. **Auto-Processing**: cognee extracts entities, relationships, and context automatically 4. **Session Scoping**: Data is organized by session clusters but globally accessible [​](https://docs.cognee.ai/integrations/langgraph-integration#use-cases) Use Cases ------------------------------------------------------------------------------------- Knowledge Accumulation Build domain knowledge incrementally over multiple sessions: Copy # Add knowledge from sessions for doc in knowledge_base: agent.invoke({"messages": [HumanMessage(content=f"Learn: {doc}")]}) # Add multiple documents for doc_path in document_paths: with open(doc_path, 'r') as f: content = f.read() await cognee.add(content) await cognee.cognify() # Query across all response = agent.invoke({ "messages": [HumanMessage(content="Find information about contract terms")] }) Context-Aware Assistance Maintain user context across work sessions: Copy # Monday agent.invoke({"messages": [HumanMessage(content="Debugging payment flow")]}) # Wednesday agent.invoke({"messages": [HumanMessage(content="What was I debugging?")]}) Multi-Tenant Applications Isolate data per user/organization while sharing global knowledge: Copy # Per-user isolation user_tools = get_sessionized_cognee_tools(session_id=user_id) agent = create_react_agent("openai:gpt-4o-mini", tools=user_tools) * * * [GitHub Repository\ -----------------\ \ View source code and examples](https://github.com/topoteretes/cognee-integration-langgraph) [Example Notebook\ ----------------\ \ Step-by-step tutorial with demos](https://github.com/topoteretes/cognee-integration-langgraph/blob/main/examples/guide.ipynb) Was this page helpful? YesNo [Previous\ \ Evaluation with DeepEval](https://docs.cognee.ai/integrations/deepeval-integration) ⌘I On this page * [Why Use This Integration](https://docs.cognee.ai/integrations/langgraph-integration#why-use-this-integration) * [Installation](https://docs.cognee.ai/integrations/langgraph-integration#installation) * [Quick Start](https://docs.cognee.ai/integrations/langgraph-integration#quick-start) * [Cross-Session Persistence](https://docs.cognee.ai/integrations/langgraph-integration#cross-session-persistence) * [Custom Session Management](https://docs.cognee.ai/integrations/langgraph-integration#custom-session-management) * [How It Works](https://docs.cognee.ai/integrations/langgraph-integration#how-it-works) * [Use Cases](https://docs.cognee.ai/integrations/langgraph-integration#use-cases) --- # Integrations - Cognee Documentation [Skip to main content](https://docs.cognee.ai/integrations#content-area) [Cognee Documentation home page![light logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20black.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=ea48b52be1df02b5909f780e6cd6856e)![dark logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20white.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=9f5bc18c4897c6e58b5cfa2b09bc079d)](https://docs.cognee.ai/) Search... ⌘K Search... Navigation Overview Integrations [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) Cognee works seamlessly with AI Agent frameworks and popular tools in the AI ecosystem. These integrations help you **observe**, **evaluate**, **use** your AI Memory. All integrations are designed to be lightweight and easy to configure, requiring minimal setup to get started. [​](https://docs.cognee.ai/integrations#observability-&-monitoring) Observability & Monitoring ------------------------------------------------------------------------------------------------- Track performance, debug issues, and monitor your knowledge graph operations in production. [Langfuse\ --------\ \ **Open-source LLM observability**Distributed tracing and metrics for every Cognee task with granular pipeline performance insights.](https://docs.cognee.ai/integrations/langfuse-integration) [Keywords AI\ -----------\ \ **LLM application tracing**Span-level tracing across tasks and workflows with minimal code using Cognee’s observe abstraction.](https://docs.cognee.ai/integrations/keywordsai-integration) [​](https://docs.cognee.ai/integrations#evaluation-&-testing) Evaluation & Testing ------------------------------------------------------------------------------------- Measure and improve the quality of your knowledge graph outputs with comprehensive evaluation frameworks. [DeepEval\ --------\ \ **Comprehensive RAG evaluation**Run QA & RAG metrics including Contextual Relevancy, Precision/Recall, and Coverage using LLM-as-a-judge workflows.](https://docs.cognee.ai/integrations/deepeval-integration) [​](https://docs.cognee.ai/integrations#cloud-llm-providers) Cloud LLM Providers ----------------------------------------------------------------------------------- Connect to enterprise-grade LLM services through Cognee’s flexible integration layer. [AWS Bedrock\ -----------\ \ **Enterprise LLM access**Use AWS Bedrock models including Claude, Titan, and Cohere through LiteLLM proxy integration.](https://docs.cognee.ai/integrations/aws-bedrock-integration) [​](https://docs.cognee.ai/integrations#agent-frameworks) Agent Frameworks ----------------------------------------------------------------------------- Build stateful AI agents with persistent semantic memory that endures across sessions. [LangGraph\ ---------\ \ **Persistent agent memory**Equip LangGraph agents with cross-session semantic memory using cognee’s graph-backed storage and natural language retrieval.](https://docs.cognee.ai/integrations/langgraph-integration) [​](https://docs.cognee.ai/integrations#agent-ides-&-development-tools) Agent IDEs & Development Tools --------------------------------------------------------------------------------------------------------- Integrate Cognee directly into your development workflow with MCP-compatible tools and AI assistants. MCP Integrations [Cursor\ ------\ \ AI-powered code editor integration](https://docs.cognee.ai/cognee-mcp/integrations/cursor) [Continue\ --------\ \ VS Code AI assistant plugin](https://docs.cognee.ai/cognee-mcp/integrations/continue) [Claude Code\ -----------\ \ Anthropic’s Claude integration](https://docs.cognee.ai/cognee-mcp/integrations/claude-code) [Cline\ -----\ \ Command-line AI assistant](https://docs.cognee.ai/cognee-mcp/integrations/cline) [Roo Code\ --------\ \ Advanced coding assistant](https://docs.cognee.ai/cognee-mcp/integrations/roo-code) Cognee’s Model Context Protocol (MCP) adapter enables seamless integration with AI assistants, providing direct access to your knowledge graphs for in-context assistance. [​](https://docs.cognee.ai/integrations#contributing-integrations) Contributing Integrations ----------------------------------------------------------------------------------------------- Don’t see your favorite tool? Cognee is open and extensible—help us grow the ecosystem! All community database integrations are maintained in the [cognee-community](https://github.com/topoteretes/cognee-community) repository, keeping the core Cognee package lean while providing extensibility. Was this page helpful? YesNo [AWS Bedrock IntegrationUse AWS Bedrock LLMs with Cognee through LiteLLM proxy\ \ Next](https://docs.cognee.ai/integrations/aws-bedrock-integration) ⌘I On this page * [Observability & Monitoring](https://docs.cognee.ai/integrations#observability-&-monitoring) * [Evaluation & Testing](https://docs.cognee.ai/integrations#evaluation-&-testing) * [Cloud LLM Providers](https://docs.cognee.ai/integrations#cloud-llm-providers) * [Agent Frameworks](https://docs.cognee.ai/integrations#agent-frameworks) * [Agent IDEs & Development Tools](https://docs.cognee.ai/integrations#agent-ides-&-development-tools) * [Contributing Integrations](https://docs.cognee.ai/integrations#contributing-integrations) --- # Quickstart - Cognee Documentation [Skip to main content](https://docs.cognee.ai/getting-started/quickstart#content-area) [Cognee Documentation home page![light logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20black.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=ea48b52be1df02b5909f780e6cd6856e)![dark logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20white.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=9f5bc18c4897c6e58b5cfa2b09bc079d)](https://docs.cognee.ai/) Search... ⌘K Search... Navigation Getting Started Quickstart [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) After completing the [installation steps](https://docs.cognee.ai/getting-started/installation) successfully, run your first Cognee example to see AI memory in action. [​](https://docs.cognee.ai/getting-started/quickstart#basic-usage) Basic Usage --------------------------------------------------------------------------------- This minimal example shows how to add content, process it, and perform a search: Copy import cognee import asyncio async def main(): # Create a clean slate for cognee -- reset data and system state await cognee.prune.prune_data() await cognee.prune.prune_system(metadata=True) # Add sample content text = "Cognee turns documents into AI memory." await cognee.add(text) # Process with LLMs to build the knowledge graph await cognee.cognify() # Search the knowledge graph results = await cognee.search( query_text="What does Cognee do?" ) # Print for result in results: print(result) if __name__ == '__main__': asyncio.run(main()) [​](https://docs.cognee.ai/getting-started/quickstart#what-just-happened) What just happened ----------------------------------------------------------------------------------------------- The code demonstrates Cognee’s three core operations: * **`.add`** — Adds data to Cognee so they can be cognified. In this case, we added a single string (“Cognee turns documents into AI memory”); from Cognee’s perspective, this string is a document. * **`.cognify`** — This is where the cognification happens. All documents are chunked, entities are extracted, relationships are made, and summaries are generated. In this case, we can expect entities like Frodo, One Ring, and Mordor. * **`.search`** — Queries the knowledge graph using vector similarity and graph traversal to find relevant information and return contextual results. [​](https://docs.cognee.ai/getting-started/quickstart#about-async-/-await-in-cognee) About `async` / `await` in Cognee ------------------------------------------------------------------------------------------------------------------------- **Cognee uses asynchronous code extensively.** That means many of its functions are defined with `async` and must be called with `await`. This lets Python handle waiting (e.g. for I/O or network calls) without blocking the rest of your program. Async basics This example uses `async` / `await`, Python’s way of doing asynchronous programming. Asynchronous programming is used when functions may block because they are waiting for something (for example, a reply from an API call). By writing `async def`, you define a function that can pause at certain points. The `await` keyword marks those calls that may need to pause. To run such functions, Python provides the `asyncio` library. It uses a loop, called the event loop, which executes your code in order but, whenever a function is waiting, can temporarily run another one. From inside your function, though, everything still runs top-to-bottom: each line after an `await` only executes once the awaited call has finished. Async resources * A good starting point is this [guide](https://realpython.com/async-io-python/) . * Official documentation is available [here](https://docs.python.org/3/library/asyncio.html) . [​](https://docs.cognee.ai/getting-started/quickstart#next-steps) Next Steps ------------------------------------------------------------------------------- [Cognee core concepts\ --------------------\ \ Learn about Cognee’s core concepts, architecture, building blocks, and main operations.](https://docs.cognee.ai/core-concepts/overview) Was this page helpful? YesNo [Previous](https://docs.cognee.ai/getting-started/installation) [OverviewLearn about Cognee's core concepts, architecture, and how to get started\ \ Next](https://docs.cognee.ai/core-concepts/overview) ⌘I On this page * [Basic Usage](https://docs.cognee.ai/getting-started/quickstart#basic-usage) * [What just happened](https://docs.cognee.ai/getting-started/quickstart#what-just-happened) * [About async / await in Cognee](https://docs.cognee.ai/getting-started/quickstart#about-async-/-await-in-cognee) * [Next Steps](https://docs.cognee.ai/getting-started/quickstart#next-steps) --- # Kubernetes (Helm) - Cognee Documentation [Skip to main content](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment/helm#content-area) [Cognee Documentation home page![light logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20black.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=ea48b52be1df02b5909f780e6cd6856e)![dark logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20white.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=9f5bc18c4897c6e58b5cfa2b09bc079d)](https://docs.cognee.ai/) Search... ⌘K Search... Navigation Self-Hosting Kubernetes (Helm) [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) [​](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment/helm#kubernetes-deployment-with-helm) Kubernetes Deployment with Helm ======================================================================================================================================= Deploy Cognee on Kubernetes using Helm charts for enterprise-grade, production-ready deployments with full control and high availability. Kubernetes deployment provides container orchestration, auto-healing, and horizontal scaling for production workloads. [​](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment/helm#why-kubernetes-+-helm) Why Kubernetes + Helm? -------------------------------------------------------------------------------------------------------------------- Enterprise Ready ---------------- Production-grade deployment with security, monitoring, and compliance High Availability ----------------- Multi-replica deployments with automatic failover and load balancing Resource Management ------------------- Fine-grained control over CPU, memory, and storage allocation GitOps Integration ------------------ Version-controlled infrastructure with automated deployment pipelines [​](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment/helm#prerequisites) Prerequisites --------------------------------------------------------------------------------------------------- 1 Kubernetes Cluster You need a running Kubernetes cluster: * **Local**: Minikube, Kind, or Docker Desktop * **Cloud**: GKE, EKS, AKS, or DigitalOcean Kubernetes * **On-premise**: Self-managed Kubernetes cluster Minimum requirements: 3 nodes, 4 CPU cores, 8GB RAM per node 2 Install Tools Copy # Install kubectl curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl" sudo install kubectl /usr/local/bin/ # Install Helm curl https://get.helm.sh/helm-v3.12.0-linux-amd64.tar.gz | tar xz sudo mv linux-amd64/helm /usr/local/bin/ # Verify installations kubectl version --client helm version 3 Configure Access Copy # Test cluster connectivity kubectl cluster-info kubectl get nodes [​](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment/helm#quick-deployment) Quick Deployment --------------------------------------------------------------------------------------------------------- 1 Clone Repository Copy git clone https://github.com/topoteretes/cognee.git cd cognee 2 Configure Values Create a `values.yaml` file to customize your deployment: Copy # values.yaml cognee: image: repository: cognee/cognee tag: latest pullPolicy: Always replicas: 3 env: OPENAI_API_KEY: "your-api-key" POSTGRES_URL: "postgresql://user:pass@postgres:5432/cognee" NEO4J_URL: "bolt://neo4j:password@neo4j:7687" QDRANT_URL: "http://qdrant:6333" # Database configurations postgresql: enabled: true auth: database: cognee username: cognee password: secure-password neo4j: enabled: true auth: password: neo4j-password qdrant: enabled: true 3 Deploy with Helm Copy # Install the Helm chart helm install cognee ./deployment/helm -f values.yaml # Check deployment status kubectl get pods -l app=cognee kubectl get services 4 Verify Deployment Copy # Check pod status kubectl get pods # View logs kubectl logs -f deployment/cognee # Test connectivity kubectl port-forward svc/cognee 8000:8000 curl http://localhost:8000/health [​](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment/helm#architecture-components) Architecture Components ----------------------------------------------------------------------------------------------------------------------- * Application Tier * Data Tier * Infrastructure **Cognee Services** * **Cognee API**: Main application pods (3+ replicas) * **Worker Pods**: Background processing (auto-scaling) * **Load Balancer**: Service distribution and health checks * **Ingress**: External traffic routing with SSL termination [​](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment/helm#production-configuration) Production Configuration ------------------------------------------------------------------------------------------------------------------------- High Availability Setup Copy # Production values.yaml cognee: replicas: 5 resources: requests: cpu: 1000m memory: 2Gi limits: cpu: 2000m memory: 4Gi autoscaling: enabled: true minReplicas: 3 maxReplicas: 20 targetCPUUtilizationPercentage: 70 postgresql: primary: persistence: size: 100Gi storageClass: fast-ssd readReplicas: replicaCount: 2 Security Configuration Copy # Security settings securityContext: runAsNonRoot: true runAsUser: 1000 fsGroup: 1000 networkPolicy: enabled: true ingress: - from: - namespaceSelector: matchLabels: name: cognee-namespace podSecurityPolicy: enabled: true Monitoring & Observability Copy # Monitoring configuration monitoring: enabled: true serviceMonitor: enabled: true namespace: monitoring grafana: dashboards: enabled: true prometheus: rules: enabled: true logging: level: INFO format: json aggregation: enabled: true endpoint: "http://loki:3100" [​](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment/helm#database-management) Database Management --------------------------------------------------------------------------------------------------------------- PostgreSQL ---------- **Relational Data** * Persistent metadata storage * User management and permissions * Pipeline state and configuration Neo4j ----- **Graph Database** * Knowledge graph relationships * Entity connections * Semantic network storage Qdrant ------ **Vector Database** * Embeddings storage * Similarity search * Semantic retrieval [​](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment/helm#scaling-&-performance) Scaling & Performance ------------------------------------------------------------------------------------------------------------------- 1 Horizontal Pod Autoscaler Copy # Enable autoscaling kubectl autoscale deployment cognee --cpu-percent=70 --min=3 --max=20 # Check HPA status kubectl get hpa 2 Vertical Pod Autoscaler Copy # VPA configuration apiVersion: autoscaling.k8s.io/v1 kind: VerticalPodAutoscaler metadata: name: cognee-vpa spec: targetRef: apiVersion: apps/v1 kind: Deployment name: cognee updatePolicy: updateMode: "Auto" 3 Node Autoscaling Configure cluster autoscaling for dynamic node provisioning based on workload demands. [​](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment/helm#maintenance-operations) Maintenance Operations --------------------------------------------------------------------------------------------------------------------- Updates & Rollbacks Copy # Update deployment helm upgrade cognee ./deployment/helm -f values.yaml # Check rollout status kubectl rollout status deployment/cognee # Rollback if needed helm rollback cognee 1 Backup & Recovery Copy # Database backups kubectl create job --from=cronjob/postgres-backup backup-$(date +%Y%m%d) # Persistent volume snapshots kubectl apply -f backup-volumesnapshot.yaml Health Monitoring Copy # Check pod health kubectl describe pods -l app=cognee # View resource usage kubectl top pods kubectl top nodes # Check service endpoints kubectl get endpoints [​](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment/helm#troubleshooting) Troubleshooting ------------------------------------------------------------------------------------------------------- * Common Issues * Database Issues * Performance Issues **Pod Failures** Copy # Check pod status and events kubectl describe pod kubectl logs --previous # Resource constraints kubectl top pods kubectl describe nodes [​](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment/helm#uninstalling) Uninstalling ------------------------------------------------------------------------------------------------- 1 Remove Helm Release Copy helm uninstall cognee 2 Clean Up Resources Copy # Remove persistent volumes (if desired) kubectl delete pvc -l app=cognee # Remove secrets kubectl delete secret -l app=cognee Uninstalling will permanently delete all data unless you have backups. Ensure you have proper backup procedures in place. [​](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment/helm#next-steps) Next Steps --------------------------------------------------------------------------------------------- Monitoring Setup ---------------- **Observability Stack**Configure Prometheus, Grafana, and alerting for production monitoring. CI/CD Integration ----------------- **GitOps Deployment**Set up automated deployments with ArgoCD or Flux. [Need Help?\ ----------\ \ Join our community for Kubernetes deployment support and production best practices.](https://discord.gg/m63hxKsp4p) Was this page helpful? YesNo [Previous](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment/ec2) [Modal DeploymentDeploy Cognee on Modal for serverless, auto-scaling knowledge graph processing\ \ Next](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment/modal) ⌘I On this page * [Kubernetes Deployment with Helm](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment/helm#kubernetes-deployment-with-helm) * [Why Kubernetes + Helm?](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment/helm#why-kubernetes-+-helm) * [Prerequisites](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment/helm#prerequisites) * [Quick Deployment](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment/helm#quick-deployment) * [Architecture Components](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment/helm#architecture-components) * [Production Configuration](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment/helm#production-configuration) * [Database Management](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment/helm#database-management) * [Scaling & Performance](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment/helm#scaling-&-performance) * [Maintenance Operations](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment/helm#maintenance-operations) * [Troubleshooting](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment/helm#troubleshooting) * [Uninstalling](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment/helm#uninstalling) * [Next Steps](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment/helm#next-steps) --- # Cognee CLI Overview - Cognee Documentation [Skip to main content](https://docs.cognee.ai/cognee-cli/overview#content-area) [Cognee Documentation home page![light logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20black.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=ea48b52be1df02b5909f780e6cd6856e)![dark logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20white.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=9f5bc18c4897c6e58b5cfa2b09bc079d)](https://docs.cognee.ai/) Search... ⌘K Search... Navigation CLI Cognee CLI Overview [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) The `cognee-cli` command lets you run Cognee from the terminal so you can add data, build the knowledge graph, and ask questions without opening a Python file. The commands are designed to be short, use friendly defaults, and are safe for people who are just starting out. [​](https://docs.cognee.ai/cognee-cli/overview#setup) Setup -------------------------------------------------------------- Before using the CLI, you need to configure your API key. The recommended approach is to store it in a `.env` file: Copy # Create a .env file in your project root echo "LLM_API_KEY=your_openai_api_key" > .env Alternatively, you can export it in your terminal session: Copy export LLM_API_KEY=your_openai_api_key Use the `cognee-cli config set` command only for temporary tweaks during a long-running session. For persistent configuration, use `.env` files or environment variables. [​](https://docs.cognee.ai/cognee-cli/overview#quick-tour-of-commands) Quick Tour of Commands ------------------------------------------------------------------------------------------------ * `cognee-cli add ` loads documents or text into a dataset * `cognee-cli cognify` turns datasets into a knowledge graph * `cognee-cli search "question"` asks the graph for answers * `cognee-cli delete` removes stored data when you no longer need it * `cognee-cli config` reads and updates saved settings * `cognee-cli -ui` launches the local web app Add `--help` after any command (for example, `cognee-cli search --help`) to see every option. [​](https://docs.cognee.ai/cognee-cli/overview#add-data) Add Data -------------------------------------------------------------------- Start by loading something the graph can learn from. You can add files, folders, URLs, or even plain text. Copy # Add a single file to the default dataset cognee-cli add docs/company-handbook.pdf # Pick a dataset name so you can separate topics later cognee-cli add docs/policies.docx --dataset-name onboarding # Add multiple files at once cognee-cli add docs/policies.docx docs/faq.md --dataset-name onboarding # Add a short text note (wrap the note in quotes) cognee-cli add "Kickoff call notes: customer wants faster onboarding" --dataset-name sales_calls Add Command Options * `data`: One or more file paths, URLs, or text strings. Mix and match as needed * `--dataset-name` (`-d`): Defaults to `main_dataset`. Use clear names so the team remembers what each dataset holds [​](https://docs.cognee.ai/cognee-cli/overview#cognify-data) Cognify Data ---------------------------------------------------------------------------- Cognify builds the knowledge graph. Run it whenever you add new data or change the ontology. Copy # Process every dataset cognee-cli cognify # Process specific datasets only cognee-cli cognify --datasets onboarding sales_calls # Increase chunk size and show more logs cognee-cli cognify --datasets onboarding --chunk-size 1500 --chunker TextChunker --verbose # Kick off a long job and return immediately cognee-cli cognify --datasets onboarding --background Cognify Command Options * `--datasets` (`-d`): Space-separated list. Skip it to process everything * `--chunk-size`: Token limit for each chunk. Leave blank to let Cognee choose * `--chunker`: `TextChunker` (default) or `LangchainChunker` if installed * `--background` (`-b`): Handy for large datasets; the CLI exits while the job keeps running * `--verbose` (`-v`): Prints progress messages * `--ontology-file`: Path to a custom ontology (`.owl`, `.rdf`, etc.) [​](https://docs.cognee.ai/cognee-cli/overview#search-the-graph) Search the Graph ------------------------------------------------------------------------------------ Once cognify finishes, you can question the graph. Start with a simple natural-language question, then experiment with search types. Copy # Default search (GRAPH_COMPLETION) cognee-cli search "Who owns the rollout plan?" # Limit the scope to one dataset cognee-cli search "What is the onboarding timeline?" --datasets onboarding # Return three answers at most cognee-cli search "List the key risks" --top-k 3 # Save a JSON response for another tool cognee-cli search "Which documents mention security?" --output-format json Search Types Try these quick examples to feel the differences: Copy # Conversational answer with reasoning (default) cognee-cli search "Give me a summary of onboarding" --query-type GRAPH_COMPLETION # Shorter answer based on chunks cognee-cli search "Show the onboarding steps" --query-type RAG_COMPLETION # Highlight relationships and insights cognee-cli search "How do onboarding tasks connect?" --query-type INSIGHTS # Raw text passages you can copy cognee-cli search "Find security requirements" --query-type CHUNKS --top-k 5 # Summaries only (great for reviews) cognee-cli search "Summarise the onboarding handbooks" --query-type SUMMARIES # Code-aware search for repos cognee-cli search "Where is the email parser?" --query-type CODE # Advanced graph query (requires Cypher skills) cognee-cli search "MATCH (n) RETURN COUNT(n)" --query-type CYPHER Search Command Options * `--query-type`: Choose from GRAPH\_COMPLETION, RAG\_COMPLETION, INSIGHTS, CHUNKS, SUMMARIES, CODE, or CYPHER * `--datasets`: Limit search to specific datasets * `--top-k`: Maximum number of results to return * `--system-prompt`: Point to a custom prompt file for LLM-backed modes * `--output-format` (`-f`): `pretty` (friendly layout), `simple` (minimal text), or `json` (structured output for scripts) [​](https://docs.cognee.ai/cognee-cli/overview#delete-data) Delete Data -------------------------------------------------------------------------- Clean up when a dataset is outdated or when you reset the environment. Copy # Remove one dataset (asks for confirmation) cognee-cli delete --dataset-name onboarding # Remove everything for a specific user cognee-cli delete --user-id 123e4567 # Wipe all data (add --force to skip the question) cognee-cli delete --all --force Delete Command Options * `--dataset-name`: Remove a specific dataset * `--user-id`: Remove all data for a specific user * `--all`: Remove all data (use with caution) * `--force`: Skip confirmation prompts [​](https://docs.cognee.ai/cognee-cli/overview#manage-configuration) Manage Configuration -------------------------------------------------------------------------------------------- The CLI stores its settings so you do not have to repeat them. Configuration updates line up with the Python API. Copy # See the list of supported keys cognee-cli config list # Check one value (if implemented) cognee-cli config get llm_model # Update your LLM provider and model cognee-cli config set llm_provider openai cognee-cli config set llm_model gpt-4o-mini # Store an API key (quotes are optional) cognee-cli config set llm_api_key sk-yourkey # Reset a key back to its default value cognee-cli config unset chunk_size Config Command Options * `list`: Print the common keys * `get [key]`: Show the saved value; omit the key to list everything * `set `: Save a new value. JSON strings such as `{}` or `true` are parsed automatically * `unset `: Reset to the default. Add `--force` to skip confirmation * `reset`: Placeholder for a future “reset everything” command Useful Configuration Keys * Language model: `llm_provider`, `llm_model`, `llm_api_key`, `llm_endpoint` * Storage: `graph_database_provider`, `vector_db_provider`, `vector_db_url`, `vector_db_key` * Chunking: `chunk_size`, `chunk_overlap` [​](https://docs.cognee.ai/cognee-cli/overview#launch-the-ui) Launch the UI ------------------------------------------------------------------------------ Prefer a browser view? Launch the UI with one flag. Copy cognee-cli -ui The CLI starts the backend on `http://localhost:8000` and the React app on `http://localhost:3000`. Leave the window open and press `Ctrl+C` to stop everything. [​](https://docs.cognee.ai/cognee-cli/overview#next-steps) Next Steps ------------------------------------------------------------------------ [Installation Guide\ ------------------\ \ **Set up your environment**Install Cognee and configure your environment to start using the CLI.](https://docs.cognee.ai/getting-started/installation) [Quickstart Tutorial\ -------------------\ \ **Run your first example**Get started with Cognee by running your first knowledge graph example.](https://docs.cognee.ai/getting-started/quickstart) Was this page helpful? YesNo [Previous\ \ Cognee WalkthroughFrom Data to Interactive Memory: End-to-end tutorial with nodesets, ontologies, memify, graph visualization, and feedback system using a coding assistant example](https://docs.cognee.ai/examples/getting-started-with-cognee) ⌘I On this page * [Setup](https://docs.cognee.ai/cognee-cli/overview#setup) * [Quick Tour of Commands](https://docs.cognee.ai/cognee-cli/overview#quick-tour-of-commands) * [Add Data](https://docs.cognee.ai/cognee-cli/overview#add-data) * [Cognify Data](https://docs.cognee.ai/cognee-cli/overview#cognify-data) * [Search the Graph](https://docs.cognee.ai/cognee-cli/overview#search-the-graph) * [Delete Data](https://docs.cognee.ai/cognee-cli/overview#delete-data) * [Manage Configuration](https://docs.cognee.ai/cognee-cli/overview#manage-configuration) * [Launch the UI](https://docs.cognee.ai/cognee-cli/overview#launch-the-ui) * [Next Steps](https://docs.cognee.ai/cognee-cli/overview#next-steps) --- # Cognee Cloud Overview - Cognee Documentation [Skip to main content](https://docs.cognee.ai/cognee-cloud/overview#content-area) [Cognee Documentation home page![light logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20black.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=ea48b52be1df02b5909f780e6cd6856e)![dark logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20white.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=9f5bc18c4897c6e58b5cfa2b09bc079d)](https://docs.cognee.ai/) Search... ⌘K Search... Navigation Cognee Cloud Platform Cognee Cloud Overview [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) Cognee Cloud gives you the functionality of Cognee without local installation and offers a clear path to persistent, production-ready, and collaborative workflows. Below is an overview of the core parts of the Cognee Cloud environment. ### [​](https://docs.cognee.ai/cognee-cloud/overview#managed-environment) Managed Environment * Persistent cloud storage for AI memory—documents, [knowledge graphs](https://docs.cognee.ai/core-concepts/knowledge-graphs) , and [embeddings](https://docs.cognee.ai/guides/search-basics#embeddings-and-vector-search) . * Preconfigured [Modal](https://modal.com/) environment instead of local installation, configuration, and maintenance. * Backed by managed [PostgreSQL](https://postgresql.org/) , [LanceDB](https://lancedb.com/) , and [Kuzu](https://kuzudb.com/) stores. * Access is provided through a Cognee Cloud [subscription and API keys](https://docs.cognee.ai/cognee-cloud/sign-up) used by the UI and SDK. ### [​](https://docs.cognee.ai/cognee-cloud/overview#pipeline-execution) Pipeline execution * Trigger [add](https://docs.cognee.ai/core-concepts/main-operations/add) → [cognify](https://docs.cognee.ai/core-concepts/main-operations/cognify) → [memify](https://docs.cognee.ai/core-concepts/main-operations/memify) pipelines from the [Cloud UI](https://docs.cognee.ai/cognee-cloud/cognee-cloud-ui) , [notebooks](https://docs.cognee.ai/cognee-cloud/cognee-cloud-notebooks) , or the [Python SDK](https://docs.cognee.ai/cognee-cloud/cognee-cloud-sdk) . * Execution and scheduling run in an isolated workspace context within the cloud runtime. * [Multi-tenancy and audit logging](https://docs.cognee.ai/cognee-cloud/permissions-security) keep each workspace’s data and activity separate. ### [​](https://docs.cognee.ai/cognee-cloud/overview#python-sdk) Python SDK * Dedicated [`cogwit-sdk`](https://docs.cognee.ai/cognee-cloud/cognee-cloud-sdk) library with API-key authentication. * Mirrors the [open-source Cognee API](https://docs.cognee.ai/core-concepts/overview) signature and behavior. * Supports uploads, pipeline execution, and [graph-backed search](https://docs.cognee.ai/guides/search-basics) . ### [​](https://docs.cognee.ai/cognee-cloud/overview#ui) UI * Notebook-style [web console](https://docs.cognee.ai/cognee-cloud/cognee-cloud-ui) for uploading files and reviewing memory. * Surfaces pipeline runs, statuses, and outputs in one place. * Enables interactive search, browsing, and [dataset management](https://docs.cognee.ai/core-concepts/further-concepts/datasets) . ### [​](https://docs.cognee.ai/cognee-cloud/overview#relationship-to-cognee-oss) Relationship to Cognee OSS * Cognee Cloud uses the same concepts, operations, and API patterns as [open-source Cognee](https://docs.cognee.ai/core-concepts/overview) , but differs in deployment and use. * Cognee Cloud provides hosted persistence and collaboration. * Open-source Cognee is for local development, custom infrastructure, or air-gapped needs. * Local setups can sync with Cognee Cloud for combined workflows. [​](https://docs.cognee.ai/cognee-cloud/overview#explore-cognee-cloud) Explore Cognee Cloud ---------------------------------------------------------------------------------------------- [Create account & API key\ ------------------------\ \ Complete the sign-up checklist, billing, and key creation steps.](https://docs.cognee.ai/cognee-cloud/sign-up) [Use the Cloud UI\ ----------------\ \ Manage datasets, upload files, and trigger cognify from the console.](https://docs.cognee.ai/cognee-cloud/cognee-cloud-ui) [Use the Python SDK\ ------------------\ \ Install `cogwit-sdk` and run add, cognify, and search from Python.](https://docs.cognee.ai/cognee-cloud/cognee-cloud-sdk) [Review the architecture\ -----------------------\ \ See how Modal compute, storage services, and datasets fit together.](https://docs.cognee.ai/cognee-cloud/cognee-cloud-architecture) [Check permissions & security\ ----------------------------\ \ Understand dataset isolation today and the planned RBAC rollout.](https://docs.cognee.ai/cognee-cloud/permissions-security) [Connect local mode & sync\ -------------------------\ \ Link a local instance and review current sync behavior and limits.](https://docs.cognee.ai/cognee-cloud/local-mode-and-sync) Was this page helpful? YesNo [Sign Up & PrerequisitesCreate your Cognee Cloud account, subscription, and API key\ \ Next](https://docs.cognee.ai/cognee-cloud/sign-up) ⌘I On this page * [Managed Environment](https://docs.cognee.ai/cognee-cloud/overview#managed-environment) * [Pipeline execution](https://docs.cognee.ai/cognee-cloud/overview#pipeline-execution) * [Python SDK](https://docs.cognee.ai/cognee-cloud/overview#python-sdk) * [UI](https://docs.cognee.ai/cognee-cloud/overview#ui) * [Relationship to Cognee OSS](https://docs.cognee.ai/cognee-cloud/overview#relationship-to-cognee-oss) * [Explore Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview#explore-cognee-cloud) --- # EC2 Deployment - Cognee Documentation [Skip to main content](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment/ec2#content-area) [Cognee Documentation home page![light logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20black.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=ea48b52be1df02b5909f780e6cd6856e)![dark logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20white.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=9f5bc18c4897c6e58b5cfa2b09bc079d)](https://docs.cognee.ai/) Search... ⌘K Search... Navigation Self-Hosting EC2 Deployment [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) [​](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment/ec2#ec2-deployment) EC2 Deployment ==================================================================================================== Deploy Cognee on Amazon EC2 for traditional cloud server deployments with full control over the infrastructure and custom configurations. EC2 deployment is ideal for organizations that need direct server access, custom networking, or integration with existing AWS infrastructure. [​](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment/ec2#why-ec2) Why EC2? --------------------------------------------------------------------------------------- Full Control ------------ Complete control over server configuration, networking, and security AWS Integration --------------- Native integration with AWS services like RDS, S3, and VPC Cost Predictable ---------------- Fixed costs with reserved instances and predictable billing Custom Networking ----------------- Advanced networking configurations and security groups [​](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment/ec2#prerequisites) Prerequisites -------------------------------------------------------------------------------------------------- 1 AWS Account * Active AWS account with EC2 permissions * AWS CLI installed and configured * Key pair created for SSH access 2 Network Setup * VPC with public/private subnets * Security groups configured for HTTP/HTTPS traffic * Internet Gateway for public access 3 Domain & SSL * Domain name (optional but recommended) * SSL certificate (Let’s Encrypt or AWS Certificate Manager) [​](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment/ec2#instance-configuration) Instance Configuration -------------------------------------------------------------------------------------------------------------------- * Development * Production * High Performance **Small Scale Setup** * **Instance Type**: `t3.medium` (2 vCPU, 4GB RAM) * **Storage**: 20GB GP3 SSD * **OS**: Ubuntu 22.04 LTS * **Databases**: Local SQLite, embedded vector DB [​](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment/ec2#quick-deployment) Quick Deployment -------------------------------------------------------------------------------------------------------- 1 Launch EC2 Instance Copy # Using AWS CLI aws ec2 run-instances \ --image-id ami-0c02fb55956c7d316 \ --instance-type t3.medium \ --key-name your-key-pair \ --security-group-ids sg-12345678 \ --subnet-id subnet-12345678 \ --block-device-mappings '[{\ "DeviceName": "/dev/sda1",\ "Ebs": {\ "VolumeSize": 20,\ "VolumeType": "gp3"\ }\ }]' \ --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=cognee-server}]' Replace the AMI ID, security group, and subnet with your specific values. 2 Connect to Instance Copy # Get instance public IP aws ec2 describe-instances --filters "Name=tag:Name,Values=cognee-server" \ --query 'Reservations[*].Instances[*].PublicIpAddress' # SSH into the instance ssh -i /path/to/your-key.pem ubuntu@YOUR-INSTANCE-IP 3 Install Dependencies Copy # Update system sudo apt update && sudo apt upgrade -y # Install Python and pip sudo apt install python3 python3-pip python3-venv git curl -y # Install uv for faster Python package management curl -LsSf https://astral.sh/uv/install.sh | sh source $HOME/.cargo/env 4 Deploy Cognee Copy # Clone repository git clone https://github.com/topoteretes/cognee.git cd cognee # Run automated setup script chmod +x deployment/setup_ubuntu_instance.sh source deployment/setup_ubuntu_instance.sh [​](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment/ec2#manual-setup-process) Manual Setup Process ---------------------------------------------------------------------------------------------------------------- Environment Setup Copy # Create virtual environment python3 -m venv cognee-env source cognee-env/bin/activate # Install Cognee with all dependencies uv sync --dev --all-extras --reinstall # Set up environment variables cat > .env << EOF OPENAI_API_KEY=your-openai-api-key POSTGRES_URL=postgresql://user:pass@localhost:5432/cognee NEO4J_URL=bolt://neo4j:password@localhost:7687 QDRANT_URL=http://localhost:6333 COGNEE_HOST=0.0.0.0 COGNEE_PORT=8000 EOF Database Installation Copy # Install PostgreSQL sudo apt install postgresql postgresql-contrib -y sudo -u postgres createuser --interactive cognee sudo -u postgres createdb cognee # Install Neo4j wget -O - https://debian.neo4j.com/neotechnology.gpg.key | sudo apt-key add - echo 'deb https://debian.neo4j.com stable 4.4' | sudo tee /etc/apt/sources.list.d/neo4j.list sudo apt update && sudo apt install neo4j -y # Install and configure Qdrant docker run -d --name qdrant -p 6333:6333 qdrant/qdrant Service Configuration Copy # Create systemd service sudo tee /etc/systemd/system/cognee.service << EOF [Unit] Description=Cognee Knowledge Graph Service After=network.target postgresql.service neo4j.service [Service] Type=simple User=ubuntu WorkingDirectory=/home/ubuntu/cognee Environment=PATH=/home/ubuntu/cognee/cognee-env/bin ExecStart=/home/ubuntu/cognee/cognee-env/bin/python -m cognee.api.server Restart=always RestartSec=10 [Install] WantedBy=multi-user.target EOF # Enable and start service sudo systemctl daemon-reload sudo systemctl enable cognee sudo systemctl start cognee [​](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment/ec2#aws-service-integration) AWS Service Integration ---------------------------------------------------------------------------------------------------------------------- RDS Integration --------------- **Managed PostgreSQL** Copy # Connect to RDS instance POSTGRES_URL=postgresql://user:pass@your-rds-endpoint:5432/cognee S3 Storage ---------- **Object Storage** Copy # Configure S3 for file storage AWS_S3_BUCKET=your-cognee-bucket AWS_ACCESS_KEY_ID=your-access-key AWS_SECRET_ACCESS_KEY=your-secret-key [​](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment/ec2#security-configuration) Security Configuration -------------------------------------------------------------------------------------------------------------------- 1 Security Groups Copy # Create security group aws ec2 create-security-group \ --group-name cognee-sg \ --description "Security group for Cognee server" # Allow SSH (port 22) aws ec2 authorize-security-group-ingress \ --group-id sg-12345678 \ --protocol tcp \ --port 22 \ --cidr 0.0.0.0/0 # Allow HTTP/HTTPS (ports 80/443) aws ec2 authorize-security-group-ingress \ --group-id sg-12345678 \ --protocol tcp \ --port 80 \ --cidr 0.0.0.0/0 aws ec2 authorize-security-group-ingress \ --group-id sg-12345678 \ --protocol tcp \ --port 443 \ --cidr 0.0.0.0/0 2 SSL/TLS Setup Copy # Install Nginx sudo apt install nginx certbot python3-certbot-nginx -y # Configure Nginx reverse proxy sudo tee /etc/nginx/sites-available/cognee << EOF server { listen 80; server_name your-domain.com; location / { proxy_pass http://localhost:8000; proxy_set_header Host \$host; proxy_set_header X-Real-IP \$remote_addr; } } EOF # Enable site and get SSL certificate sudo ln -s /etc/nginx/sites-available/cognee /etc/nginx/sites-enabled/ sudo certbot --nginx -d your-domain.com 3 Firewall Configuration Copy # Configure UFW firewall sudo ufw allow OpenSSH sudo ufw allow 'Nginx Full' sudo ufw --force enable [​](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment/ec2#monitoring-&-maintenance) Monitoring & Maintenance ------------------------------------------------------------------------------------------------------------------------ * System Monitoring * Log Management * Backup Strategy Copy # Install monitoring tools sudo apt install htop iotop nethogs -y # Check system resources htop df -h free -m # Monitor Cognee service sudo systemctl status cognee sudo journalctl -u cognee -f [​](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment/ec2#scaling-&-performance) Scaling & Performance ------------------------------------------------------------------------------------------------------------------ Vertical Scaling Copy # Stop instance aws ec2 stop-instances --instance-ids i-1234567890abcdef0 # Change instance type aws ec2 modify-instance-attribute \ --instance-id i-1234567890abcdef0 \ --instance-type Value=m5.xlarge # Start instance aws ec2 start-instances --instance-ids i-1234567890abcdef0 Load Balancing Copy # Create Application Load Balancer aws elbv2 create-load-balancer \ --name cognee-alb \ --subnets subnet-12345678 subnet-87654321 \ --security-groups sg-12345678 # Create target group aws elbv2 create-target-group \ --name cognee-targets \ --protocol HTTP \ --port 8000 \ --vpc-id vpc-12345678 Auto Scaling Copy # Create launch template aws ec2 create-launch-template \ --launch-template-name cognee-template \ --launch-template-data '{ "ImageId": "ami-0c02fb55956c7d316", "InstanceType": "t3.medium", "KeyName": "your-key-pair", "SecurityGroupIds": ["sg-12345678"], "UserData": "base64-encoded-startup-script" }' [​](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment/ec2#troubleshooting) Troubleshooting ------------------------------------------------------------------------------------------------------ * Common Issues * Database Issues * Performance Issues **Service Won’t Start** Copy # Check service status sudo systemctl status cognee sudo journalctl -u cognee --no-pager # Check port availability sudo netstat -tlnp | grep :8000 # Verify environment variables cat .env [​](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment/ec2#cost-optimization) Cost Optimization ---------------------------------------------------------------------------------------------------------- Reserved Instances ------------------ **Save up to 75%**Purchase reserved instances for predictable workloads to reduce costs significantly. Spot Instances -------------- **Development/Testing**Use spot instances for non-critical workloads to save up to 90% on compute costs. Use AWS Cost Explorer to monitor your EC2 spending and optimize instance types based on actual usage patterns. [​](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment/ec2#next-steps) Next Steps -------------------------------------------------------------------------------------------- High Availability ----------------- **Multi-AZ Setup**Deploy across multiple availability zones for improved resilience. Monitoring Stack ---------------- **CloudWatch Integration**Set up comprehensive monitoring with CloudWatch and custom metrics. [Need Help?\ ----------\ \ Join our community for EC2 deployment support and AWS best practices.](https://discord.gg/m63hxKsp4p) Was this page helpful? YesNo [Previous](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Kubernetes (Helm)Deploy Cognee on Kubernetes with Helm charts for enterprise-grade, production-ready deployments\ \ Next](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment/helm) ⌘I On this page * [EC2 Deployment](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment/ec2#ec2-deployment) * [Why EC2?](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment/ec2#why-ec2) * [Prerequisites](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment/ec2#prerequisites) * [Instance Configuration](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment/ec2#instance-configuration) * [Quick Deployment](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment/ec2#quick-deployment) * [Manual Setup Process](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment/ec2#manual-setup-process) * [AWS Service Integration](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment/ec2#aws-service-integration) * [Security Configuration](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment/ec2#security-configuration) * [Monitoring & Maintenance](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment/ec2#monitoring-&-maintenance) * [Scaling & Performance](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment/ec2#scaling-&-performance) * [Troubleshooting](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment/ec2#troubleshooting) * [Cost Optimization](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment/ec2#cost-optimization) * [Next Steps](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment/ec2#next-steps) --- # Pipelines - Cognee Documentation [Skip to main content](https://docs.cognee.ai/core-concepts/building-blocks/pipelines#content-area) [Cognee Documentation home page![light logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20black.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=ea48b52be1df02b5909f780e6cd6856e)![dark logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20white.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=9f5bc18c4897c6e58b5cfa2b09bc079d)](https://docs.cognee.ai/) Search... ⌘K Search... Navigation Building Blocks Pipelines [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) [​](https://docs.cognee.ai/core-concepts/building-blocks/pipelines#what-pipelines-are) What pipelines are ------------------------------------------------------------------------------------------------------------ Pipelines coordinate ordered [Tasks](https://docs.cognee.ai/core-concepts/building-blocks/tasks) into a reproducible workflow. Default Cognee operations like [Add](https://docs.cognee.ai/core-concepts/main-operations/add) and [Cognify](https://docs.cognee.ai/core-concepts/main-operations/cognify) run on top of the same execution layer. You typically do not call low-level functions directly; you trigger pipelines through these operations. [​](https://docs.cognee.ai/core-concepts/building-blocks/pipelines#prerequisites) Prerequisites -------------------------------------------------------------------------------------------------- * **Dataset**: a container (name or UUID) where your data is stored and processed. Every document added to cognee belongs to a dataset. * **User**: the identity for ownership and access control. A default user is created and used if none is provided. * More details are available below [​](https://docs.cognee.ai/core-concepts/building-blocks/pipelines#how-pipelines-run) How pipelines run ---------------------------------------------------------------------------------------------------------- Somewhat unsurprisingly, the function used to run pipelines is called `run_pipeline`. Cognee uses a **layered execution model**: a single call to `run_pipeline` orchestrates **multi-dataset processing** by running **per-file pipelines** through the sequence of tasks. * **Statuses** are yielded as the pipeline runs and written to **databases** where appropriate * **User access** to datasets and files is carefully verified at each layer * **Pipeline run information** includes dataset IDs, completion status, and error handling * **Background execution** uses queues to manage status updates and avoid database conflicts Layered execution * Innermost layer: individual task execution with telemetry and recursive task running in batches * Middle layer: per-dataset pipeline management and task orchestration * Outermost layer: multi-dataset orchestration and overall pipeline execution * Execution modes: blocking (wait for completion) or background (return immediately with “started” status) Customization approaches and tips * Use [Cognify](https://docs.cognee.ai/core-concepts/main-operations/cognify) with custom tasks after [Add](https://docs.cognee.ai/core-concepts/main-operations/add) * Modify transformation steps without touching low-level functions, avoid going below `run_pipeline` * Custom tasks let you extend or replace default behavior Users * Identity: represents who owns and acts on data. If omitted, a default user is used * Ownership: every ingested item is tied to a user; content is deduplicated per owner * Permissions: enforced per dataset (read/write/delete/share) during processing and API access Datasets * Container: a named or UUID-scoped collection of related data and derived knowledge * Scoping: Add writes into a specific dataset; Cognify processes the dataset(s) you pass * Lifecycle: new names create datasets and grant the calling user permissions; UUIDs let you target existing datasets (given permission) [Tasks\ -----\ \ Learn about the individual processing units that make up pipelines](https://docs.cognee.ai/core-concepts/building-blocks/tasks) [DataPoints\ ----------\ \ Understand the structured outputs that pipelines produce](https://docs.cognee.ai/core-concepts/building-blocks/datapoints) [Main Operations\ ---------------\ \ See how pipelines are used in Add, Cognify, and Search workflows](https://docs.cognee.ai/core-concepts/main-operations/add) Was this page helpful? YesNo [Previous](https://docs.cognee.ai/core-concepts/building-blocks/tasks) [AddIngesting and preparing data for processing in Cognee\ \ Next](https://docs.cognee.ai/core-concepts/main-operations/add) ⌘I On this page * [What pipelines are](https://docs.cognee.ai/core-concepts/building-blocks/pipelines#what-pipelines-are) * [Prerequisites](https://docs.cognee.ai/core-concepts/building-blocks/pipelines#prerequisites) * [How pipelines run](https://docs.cognee.ai/core-concepts/building-blocks/pipelines#how-pipelines-run) --- # Tasks - Cognee Documentation [Skip to main content](https://docs.cognee.ai/core-concepts/building-blocks/tasks#content-area) [Cognee Documentation home page![light logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20black.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=ea48b52be1df02b5909f780e6cd6856e)![dark logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20white.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=9f5bc18c4897c6e58b5cfa2b09bc079d)](https://docs.cognee.ai/) Search... ⌘K Search... Navigation Building Blocks Tasks [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) [​](https://docs.cognee.ai/core-concepts/building-blocks/tasks#tasks:-smallest-executable-units) Tasks: Smallest Executable Units ==================================================================================================================================== Tasks are Cognee’s **smallest executable units** — they wrap any Python callable and give it a uniform interface for batching, error handling, and logging. While they can work with anything, Tasks are most powerful when creating or enriching [DataPoints](https://docs.cognee.ai/core-concepts/building-blocks/datapoints) . [​](https://docs.cognee.ai/core-concepts/building-blocks/tasks#what-are-tasks) What are Tasks ------------------------------------------------------------------------------------------------ Tasks are Cognee’s **smallest executable units**. * They wrap any Python callable (function, coroutine, generator, async generator). * Give a **uniform interface** for batching, error handling, and logging. * Can work with anything, but are **most powerful when creating or enriching [DataPoints](https://docs.cognee.ai/core-concepts/building-blocks/datapoints) **. [​](https://docs.cognee.ai/core-concepts/building-blocks/tasks#why-tasks-exist) Why Tasks Exist -------------------------------------------------------------------------------------------------- * Normalize different kinds of Python functions so they behave consistently. * Enable **stream-based processing**: outputs flow directly into the next step. * Provide **batching controls** for efficiency, especially with LLM or I/O-heavy operations. * Form the **building blocks** of higher-level [Pipelines](https://docs.cognee.ai/core-concepts/building-blocks/pipelines) . [​](https://docs.cognee.ai/core-concepts/building-blocks/tasks#core-concepts) Core Concepts ---------------------------------------------------------------------------------------------- * **Execution**: run functions in a consistent way, regardless of sync/async/gen. * **Batching**: configurable with `task_config`. * **Composition**: Tasks can be chained — one Task’s output is the next Task’s input. * **Flexibility**: Tasks don’t need to handle DataPoints, but Cognee’s defaults encourage it. [​](https://docs.cognee.ai/core-concepts/building-blocks/tasks#dependencies-&-ordering) Dependencies & Ordering ------------------------------------------------------------------------------------------------------------------ Tasks often assume a certain **input type** and produce an expected **output type**. Example flow (educational, not exhaustive): * Raw data → Documents * Documents → Chunks * Chunks → Entities and relationships * Entities/Chunks → Summaries * Any DataPoint → Storage [​](https://docs.cognee.ai/core-concepts/building-blocks/tasks#built-in-tasks) Built-in Tasks ------------------------------------------------------------------------------------------------ * **Ingestion**: `resolve_data_directories`, `ingest_data` * **Classification**: `classify_documents` * **Access control**: `check_permissions_on_dataset` * **Chunking**: `extract_chunks_from_documents` * **Graph extraction**: `extract_graph_from_data` * **Summarization**: `summarize_text`, `summarize_code` * **Persistence**: `add_data_points` [​](https://docs.cognee.ai/core-concepts/building-blocks/tasks#examples-and-details) Examples and details ------------------------------------------------------------------------------------------------------------ Task API & Constructor Copy Task(executable, *args, task_config={...}, **kwargs) **Key parameters:** * `executable`: Any Python callable (function, coroutine, generator, async generator) * `task_config`: Configuration for batching, error handling, and logging * `default_params`: Parameters that are always passed to the executable Supported Task Types Cognee automatically detects and handles different Python function types: * **Functions**: Standard synchronous functions * **Coroutines**: Async functions using `async def` * **Generators**: Functions that yield multiple values * **Async Generators**: Async functions that yield multiple values Each type is executed appropriately within Cognee’s task system. Writing a Custom Task Copy def my_custom_task(data_chunk): # Process the data chunk processed_data = process_chunk(data_chunk) # Create or enrich DataPoints datapoint = DataPoint( content=processed_data, metadata={"source": "custom_task"} ) return datapoint # Wrap it in a Task my_task = Task(my_custom_task) **Why idempotent, DataPoint-focused functions are easiest to compose:** * Predictable inputs and outputs * Easy to chain together * Clear data flow between steps Execution Flow Tasks execute in sequence within [Pipelines](https://docs.cognee.ai/core-concepts/building-blocks/pipelines) , with each Task’s output becoming the next Task’s input. This creates a data transformation pipeline that builds up to the final knowledge graph. [DataPoints\ ----------\ \ The structured units that Tasks create and process](https://docs.cognee.ai/core-concepts/building-blocks/datapoints) [Pipelines\ ---------\ \ How Tasks are orchestrated into workflows](https://docs.cognee.ai/core-concepts/building-blocks/pipelines) [Main Operations\ ---------------\ \ See Tasks in action during data ingestion and processing](https://docs.cognee.ai/core-concepts/main-operations/add) Was this page helpful? YesNo [Previous](https://docs.cognee.ai/core-concepts/building-blocks/datapoints) [PipelinesOrchestrating tasks into coordinated workflows for data processing\ \ Next](https://docs.cognee.ai/core-concepts/building-blocks/pipelines) ⌘I On this page * [Tasks: Smallest Executable Units](https://docs.cognee.ai/core-concepts/building-blocks/tasks#tasks:-smallest-executable-units) * [What are Tasks](https://docs.cognee.ai/core-concepts/building-blocks/tasks#what-are-tasks) * [Why Tasks Exist](https://docs.cognee.ai/core-concepts/building-blocks/tasks#why-tasks-exist) * [Core Concepts](https://docs.cognee.ai/core-concepts/building-blocks/tasks#core-concepts) * [Dependencies & Ordering](https://docs.cognee.ai/core-concepts/building-blocks/tasks#dependencies-&-ordering) * [Built-in Tasks](https://docs.cognee.ai/core-concepts/building-blocks/tasks#built-in-tasks) * [Examples and details](https://docs.cognee.ai/core-concepts/building-blocks/tasks#examples-and-details) --- # Cognify - Cognee Documentation [Skip to main content](https://docs.cognee.ai/core-concepts/main-operations/cognify#content-area) [Cognee Documentation home page![light logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20black.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=ea48b52be1df02b5909f780e6cd6856e)![dark logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20white.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=9f5bc18c4897c6e58b5cfa2b09bc079d)](https://docs.cognee.ai/) Search... ⌘K Search... Navigation Main Operations Cognify [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) [​](https://docs.cognee.ai/core-concepts/main-operations/cognify#what-is-the-cognify-operation) What is the cognify operation -------------------------------------------------------------------------------------------------------------------------------- The `.cognify` operation takes the data you ingested with [Add](https://docs.cognee.ai/core-concepts/main-operations/add) and turns plain text into structured knowledge: chunks, embeddings, summaries, nodes, and edges that live in Cognee’s vector and graph stores. It prepares your data for downstream operations like [Search](https://docs.cognee.ai/core-concepts/main-operations/search) . * **Transforms ingested data**: builds chunks, embeddings, and summaries; always comes **after [Add](https://docs.cognee.ai/core-concepts/main-operations/add) ** * **Graph creation**: extracts entities and relationships to form a knowledge graph * **Vector indexing**: makes everything searchable via embeddings * **Dataset-scoped**: runs per dataset, respecting ownership and permissions * **Incremental loading**: you can run `.cognify` multiple times as your dataset grows, and Cognee will skip what’s already processed [​](https://docs.cognee.ai/core-concepts/main-operations/cognify#what-happens-under-the-hood) What happens under the hood ---------------------------------------------------------------------------------------------------------------------------- The `.cognify` pipeline is made of six ordered [Tasks](https://docs.cognee.ai/core-concepts/building-blocks/tasks) . Each task takes the output of the previous one and moves your data closer to becoming a searchable knowledge graph. 1. **Classify documents** — wrap each ingested file as a `Document` object with metadata and optional node sets 2. **Check permissions** — enforce that you have the right to modify the target dataset 3. **Extract chunks** — split documents into smaller pieces (paragraphs, sections) 4. **Extract graph** — use LLMs to identify entities and relationships, inserting them into the graph DB 5. **Summarize text** — generate summaries for each chunk, stored as `TextSummary` [DataPoints](https://docs.cognee.ai/core-concepts/building-blocks/datapoints) 6. **Add data points** — embed nodes and summaries, write them into the vector store, and update graph edges The result is a fully searchable, structured knowledge graph connected to your data. [​](https://docs.cognee.ai/core-concepts/main-operations/cognify#after-cognify-finishes) After cognify finishes ------------------------------------------------------------------------------------------------------------------ When `.cognify` completes for a dataset: * **DocumentChunks** exist in memory as the granular breakdown of your files * **Summaries** are stored and indexed in the vector database for semantic search * **Knowledge graph nodes and edges** are committed to the graph database * **Dataset metadata** is updated with token counts and pipeline status * Your dataset is now **query-ready**: you can run [Search](https://docs.cognee.ai/core-concepts/main-operations/search) or graph queries immediately [​](https://docs.cognee.ai/core-concepts/main-operations/cognify#examples-and-details) Examples and details -------------------------------------------------------------------------------------------------------------- Pipeline tasks (detailed) 1. **Classify documents** * Turns raw `Data` rows into `Document` objects * Chooses the right document type (PDF, text, image, audio, etc.) * Attaches metadata and optional node sets 2. **Check permissions** * Verifies that the user has write access to the dataset 3. **Extract chunks** * Splits documents into `DocumentChunk`s using a chunker * Updates token counts in the relational DB 4. **Extract graph** * Calls the LLM to extract entities and relationships * Deduplicates nodes and edges, commits to the graph DB 5. **Summarize text** * Generates concise summaries per chunk * Stores them as `TextSummary` [DataPoints](https://docs.cognee.ai/core-concepts/building-blocks/datapoints) for vector search 6. **Add data points** * Converts summaries and other [DataPoints](https://docs.cognee.ai/core-concepts/building-blocks/datapoints) into graph + vector nodes * Embeds them in the vector store, persists in the graph DB Datasets and permissions * Cognify always runs on a dataset * You must have **write access** to the dataset * Permissions are enforced at pipeline start * Each dataset maintains its own cognify status and token counts Incremental loading * By default, `.cognify` processes all data in a dataset * With `incremental_loading=True`, only new or updated files are processed * Saves time and compute for large, evolving datasets Final outcome * Vector database contains embeddings for summaries and nodes * Graph database contains entities and relationships * Relational database tracks token counts and pipeline run status * Your dataset is now ready for [Search](https://docs.cognee.ai/core-concepts/main-operations/search) (semantic or graph-based) [Add\ ---\ \ First bring data into Cognee](https://docs.cognee.ai/core-concepts/main-operations/add) [Search\ ------\ \ Query embeddings or graph structures built by Cognify](https://docs.cognee.ai/core-concepts/main-operations/search) [Building Blocks\ ---------------\ \ Learn about DataPoints, Tasks, and Pipelines](https://docs.cognee.ai/core-concepts/building-blocks/datapoints) Was this page helpful? YesNo [Previous](https://docs.cognee.ai/core-concepts/main-operations/add) [SearchQuery your AI memory with vectors, graphs, and LLMs\ \ Next](https://docs.cognee.ai/core-concepts/main-operations/search) ⌘I On this page * [What is the cognify operation](https://docs.cognee.ai/core-concepts/main-operations/cognify#what-is-the-cognify-operation) * [What happens under the hood](https://docs.cognee.ai/core-concepts/main-operations/cognify#what-happens-under-the-hood) * [After cognify finishes](https://docs.cognee.ai/core-concepts/main-operations/cognify#after-cognify-finishes) * [Examples and details](https://docs.cognee.ai/core-concepts/main-operations/cognify#examples-and-details) --- # Memify - Cognee Documentation [Skip to main content](https://docs.cognee.ai/core-concepts/main-operations/memify#content-area) [Cognee Documentation home page![light logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20black.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=ea48b52be1df02b5909f780e6cd6856e)![dark logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20white.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=9f5bc18c4897c6e58b5cfa2b09bc079d)](https://docs.cognee.ai/) Search... ⌘K Search... Navigation Main Operations Memify [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) [​](https://docs.cognee.ai/core-concepts/main-operations/memify#what-is-the-memify-operation) What is the memify operation ----------------------------------------------------------------------------------------------------------------------------- The `.memify` operation enriches existing knowledge graphs by extracting derived facts and creating new associations from your already-processed data. Unlike [Add](https://docs.cognee.ai/core-concepts/main-operations/add) and [Cognify](https://docs.cognee.ai/core-concepts/main-operations/cognify) , memify works on existing graph structures to add semantic understanding and deeper contextual relationships. * **Graph enrichment**: operates on existing knowledge graphs created by [Cognify](https://docs.cognee.ai/core-concepts/main-operations/cognify) * **Derived facts**: creates new nodes and edges from existing context without re-ingesting data * **Semantic enhancement**: adds coding rules, associations, and other derived knowledge * **Pipeline-based**: uses extraction and enrichment tasks to process subgraphs * **Incremental**: can be run multiple times to add new derived facts as needed [​](https://docs.cognee.ai/core-concepts/main-operations/memify#where-memify-fits) Where memify fits ------------------------------------------------------------------------------------------------------- Use `.memify` after you’ve completed the [Add](https://docs.cognee.ai/core-concepts/main-operations/add) → [Cognify](https://docs.cognee.ai/core-concepts/main-operations/cognify) workflow: * **Prerequisites**: requires an existing knowledge graph with chunks, embeddings, and graph structure * **Enhancement phase**: adds semantic understanding and derived facts to your existing data * **Optional enrichment**: not required for basic search, but adds valuable context and associations [​](https://docs.cognee.ai/core-concepts/main-operations/memify#what-happens-under-the-hood) What happens under the hood --------------------------------------------------------------------------------------------------------------------------- The `.memify` pipeline processes your existing knowledge graph through two main phases: 1. **Extraction phase** — pulls relevant subgraphs or chunks from your existing knowledge graph 2. **Enrichment phase** — applies enrichment tasks to create new nodes and edges from existing context The default memify tasks include: * **Extract subgraph chunks**: identifies relevant portions of your graph for processing * **Add rule associations**: creates coding rules and other derived facts from the extracted context [​](https://docs.cognee.ai/core-concepts/main-operations/memify#after-memify-finishes) After memify finishes --------------------------------------------------------------------------------------------------------------- When `.memify` completes: * **New derived facts** are added to your knowledge graph as additional nodes and edges * **Enhanced searchability**: specialized search types like `SearchType.CODING_RULES` become available * **Richer context**: your existing data now includes semantic associations and derived knowledge * **No data re-ingestion**: all enrichment happens on your existing graph structure [​](https://docs.cognee.ai/core-concepts/main-operations/memify#examples-and-details) Examples and details ------------------------------------------------------------------------------------------------------------- Default behavior * **Extraction**: `extract_subgraph_chunks` - pulls relevant chunks from your graph * **Enrichment**: `add_rule_associations` - creates coding rules and associations * **Output**: new nodes and edges added to your existing knowledge graph Custom tasks * You can specify custom extraction and enrichment tasks * Extraction tasks determine what parts of the graph to process * Enrichment tasks define what derived facts to create * Tasks can be chained together for complex enrichment workflows Search integration * Enriched graphs support specialized search types * `SearchType.CODING_RULES` for finding coding guidelines * Other search modes can leverage the new derived facts * Enhanced context improves answer quality and relevance Incremental processing * Can be run multiple times on the same dataset * Only processes new or updated graph elements by default * Safe to re-run as it adds rather than replaces existing data [Cognify\ -------\ \ Build the knowledge graph that memify enriches](https://docs.cognee.ai/core-concepts/main-operations/cognify) [Search\ ------\ \ Query the enriched graph with specialized search types](https://docs.cognee.ai/core-concepts/main-operations/search) [Custom Tasks\ ------------\ \ Learn how to create custom memify tasks](https://docs.cognee.ai/guides/custom-tasks-pipelines) Was this page helpful? YesNo [Previous](https://docs.cognee.ai/core-concepts/main-operations/search) [DatasetsProject-level containers for organization, permissions, and processing\ \ Next](https://docs.cognee.ai/core-concepts/further-concepts/datasets) ⌘I On this page * [What is the memify operation](https://docs.cognee.ai/core-concepts/main-operations/memify#what-is-the-memify-operation) * [Where memify fits](https://docs.cognee.ai/core-concepts/main-operations/memify#where-memify-fits) * [What happens under the hood](https://docs.cognee.ai/core-concepts/main-operations/memify#what-happens-under-the-hood) * [After memify finishes](https://docs.cognee.ai/core-concepts/main-operations/memify#after-memify-finishes) * [Examples and details](https://docs.cognee.ai/core-concepts/main-operations/memify#examples-and-details) --- # Ontologies - Cognee Documentation [Skip to main content](https://docs.cognee.ai/core-concepts/further-concepts/ontologies#content-area) [Cognee Documentation home page![light logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20black.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=ea48b52be1df02b5909f780e6cd6856e)![dark logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20white.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=9f5bc18c4897c6e58b5cfa2b09bc079d)](https://docs.cognee.ai/) Search... ⌘K Search... Navigation Further Concepts Ontologies [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) [​](https://docs.cognee.ai/core-concepts/further-concepts/ontologies#what-is-an-ontology-in-cognee) What is an ontology in Cognee? ------------------------------------------------------------------------------------------------------------------------------------- An **ontology** is an optional RDF/OWL file you can provide to Cognee. It acts as a **reference vocabulary**, making sure that entity types (“classes”) and entity mentions (“individuals”) extracted from your data are linked to canonical, well-defined concepts. [​](https://docs.cognee.ai/core-concepts/further-concepts/ontologies#how-it-works) How it works -------------------------------------------------------------------------------------------------- * You pass `ontology_file_path="my_ontology.owl"` when running [Cognify](https://docs.cognee.ai/core-concepts/main-operations/cognify) . * Cognee parses the file with [RDFLib](https://rdflib.dev/) and loads its classes and relationships. * During graph extraction, entities and types are checked against the ontology: * If a match is found, the node is marked `ontology_valid=True`. * Parent classes and object-property links from the ontology are attached as extra edges. * If no ontology is provided, extraction still works, just without validation or enrichment. [​](https://docs.cognee.ai/core-concepts/further-concepts/ontologies#why-use-an-ontology) Why use an ontology ---------------------------------------------------------------------------------------------------------------- * **Consistency**: standardize how entities and types are represented * **Enrichment**: bring in inherited relationships from a domain schema * **Control**: align Cognee’s graph with existing enterprise or scientific vocabularies [​](https://docs.cognee.ai/core-concepts/further-concepts/ontologies#where-to-get-ontologies) Where to get ontologies ------------------------------------------------------------------------------------------------------------------------ Ontologies are an art and science on their own. Cognee works best with **manually curated, focused ontologies** that fit your dataset. The simplest way to start is to **create a small ontology yourself** — just a few classes and relationships that match the entities you expect. Public resources like **Wikidata** or **DBpedia** define millions of classes and entities, which makes them too big to use directly in Cognee. If you are not creating an ontology from scratch, you can start from a public one — but always work with a subset, not the full ontology: * **Select only the pieces you need** (specific classes, properties, or individuals) * **Save the subset** in a format Cognee can parse with [`rdflib`](https://rdflib.readthedocs.io/) * **If needed, enrich the subset manually** by adding extra classes or relationships relevant to your domain * **Keep it small and relevant** so matching stays precise and performance remains fast Common sources * **General vocabularies**: schema.org, Dublin Core Terms (DC/Terms), SKOS, PROV-O, FOAF * **Knowledge graph backbones**: DBpedia Ontology, Wikidata (Wikibase RDF ontology) * **Domain examples**: * Healthcare: SNOMED CT (licensed), ICD, UMLS, MeSH, HL7/FHIR RDF * Finance: FIBO (Financial Industry Business Ontology) * Geo/IoT: GeoSPARQL, SOSA/SSN, GeoNames * Units: QUDT Why subsetting is essential Every public ontology is **too broad to ingest wholesale**. Creating a subset is what makes them usable in Cognee: * Improves matching precision (fewer false matches when mapping LLM output) * Keeps performance acceptable (smaller graphs → faster resolution) * Lets you curate only the relevant parts of a domain How subsetting works Different communities provide different ways to extract subsets (e.g., “slims” in OBO ontologies, WDumper for Wikidata, module extraction in Protégé). The details vary, but the general principle is the same: 1. Pick the terms (classes or properties) you care about 2. Extract those terms plus their immediate context (e.g. parent classes, related properties) 3. Save the result in an `rdflib`\-readable RDF format [​](https://docs.cognee.ai/core-concepts/further-concepts/ontologies#supported-formats) Supported formats ------------------------------------------------------------------------------------------------------------ Any format [RDFLib](https://rdflib.readthedocs.io/) can parse: * RDF/XML (`.owl`, `.rdf`) * Turtle (`.ttl`) * N-Triples, JSON-LD, and others [​](https://docs.cognee.ai/core-concepts/further-concepts/ontologies#practical-example) Practical example ------------------------------------------------------------------------------------------------------------ Once you have your subset file, integrating it into Cognee is simple: Copy import cognee await cognee.cognify( datasets=["my_dataset"], ontology_file_path="subset.owl", # your curated subset here ) For more detailed examples of working with ontologies in Cognee, check out the demo scripts in the repository: * [Basic ontology demo](https://github.com/topoteretes/cognee/blob/main/examples/python/ontology_demo_example.py) - Shows fundamental ontology integration * [Advanced ontology demo](https://github.com/topoteretes/cognee/blob/main/examples/python/ontology_demo_example_2.py) - Demonstrates more complex ontology workflows Was this page helpful? YesNo [Previous](https://docs.cognee.ai/core-concepts/further-concepts/node-sets) [OverviewIntroduction to Cognee's permission system and access control architecture\ \ Next](https://docs.cognee.ai/core-concepts/permissions-system/overview) ⌘I On this page * [What is an ontology in Cognee?](https://docs.cognee.ai/core-concepts/further-concepts/ontologies#what-is-an-ontology-in-cognee) * [How it works](https://docs.cognee.ai/core-concepts/further-concepts/ontologies#how-it-works) * [Why use an ontology](https://docs.cognee.ai/core-concepts/further-concepts/ontologies#why-use-an-ontology) * [Where to get ontologies](https://docs.cognee.ai/core-concepts/further-concepts/ontologies#where-to-get-ontologies) * [Supported formats](https://docs.cognee.ai/core-concepts/further-concepts/ontologies#supported-formats) * [Practical example](https://docs.cognee.ai/core-concepts/further-concepts/ontologies#practical-example) --- # Code Assistants - Cognee Documentation [Skip to main content](https://docs.cognee.ai/examples/code-assistants#content-area) [Cognee Documentation home page![light logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20black.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=ea48b52be1df02b5909f780e6cd6856e)![dark logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20white.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=9f5bc18c4897c6e58b5cfa2b09bc079d)](https://docs.cognee.ai/) Search... ⌘K Search... Navigation Use Cases Code Assistants [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) [​](https://docs.cognee.ai/examples/code-assistants#codegraph:-enhancing-codebase-understanding-with-graphs-and-llms) CodeGraph: Enhancing Codebase Understanding with Graphs and LLMs ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### [​](https://docs.cognee.ai/examples/code-assistants#scenario:) Scenario: Modern software development often involves massive codebases spread across multiple repositories, teams, and services. Engineers and AI-based coding copilots struggle to maintain a clear mental model of how components interrelate. For instance: * **Large Repositories:** A large software project might have a large of GitHub repository, containing thousands of files. * **Complex Dependencies:** Services often call each other via APIs, share data models, or rely on specific configuration files. Finding the right function, class, or module can become tedious. * **Evolving Code:** As code evolves, comments get stale, architectural assumptions shift, and documentation becomes outdated, making it hard for coding copilots to reliably generate correct, context-aware suggestions. ### [​](https://docs.cognee.ai/examples/code-assistants#challenges:) Challenges: 1. **Fragmented Knowledge:** It’s difficult to piece together the entire dependency graph across the entire repository. 2. **Limited Context for LLMs:** Large Language Models struggle with providing accurate code completions or refactoring suggestions if they lack a broader view of the project’s architecture. 3. **Time Lost:** Developers spend significant time searching through repositories, reading documentation, and attempting to piece together the “big picture” of the codebase. ### [​](https://docs.cognee.ai/examples/code-assistants#solution:-creating-a-codegraph) Solution: Creating a CodeGraph A **CodeGraph** is a knowledge graph that models the Python codebase at multiple levels of granularity. It goes beyond just indexing code: it captures entities and relationships within and across repositories. * **Entities:** Functions, classes, modules, services, configuration files, APIs, tests, CI/CD pipelines, and documentation pages. * **Relationships:** Who-calls-what (function call graphs), import dependencies, version histories, code ownership, and semantic links (e.g., “this module implements a particular design pattern” or “this API endpoint is deprecated and replaced by another”). How we constructed a CodeGraph: * Build chain access direct dependency * Build init mediated direct dependency * Define pydantic data structures that describe a single knowledge nodes for all nodes * Create a knowledge graph * Write an in-memory retriever that gets the graphs skeletons and extracts triplets Here is an example graph generated with cognee: ![code_assistants_graph_example](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/code_assistants_graph_example.png?w=2500&fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=1be7037a7f30be598f352c2fbd5a5257) Read more about our approach in our [blog](https://www.cognee.ai/blog/deep-dives/repo_to_knowledge_graph) . **Enriching CodeGraph with LLMs:** To make this knowledge even more actionable, integrate Large Language Models that understand code semantics and developer documentation. The LLM can: 1. **Ingest the Graph:** The LLM has access to structured context from the CodeGraph, so when a developer asks, _“Where is the function that parses user inputs for our search engine?”_, the LLM can quickly locate that function by following the graph’s relationships rather than brute-forcing file searches. 2. **Provide Context-Rich Suggestions:** When the coding copilot suggests a code snippet, it can reference related modules, highlight deprecations, or warn about known compatibility issues. For example, _“You might want to call `FunctionParseUserInput` from `Utils/InputProcessor.js`. It’s used in `SearchEngine.js` and depends on `InputSchema.json`.”_ 3. **Explain Architectural Decisions:** Developers can query the LLM about architectural choices: _“Why does `ServiceD` depend on `ServiceE`?”_. The LLM, using the CodeGraph, responds: _“ServiceD calls `ServiceE`’s authentication endpoint to validate tokens, as documented in `ServiceE/docs/auth.md`.”_ 4. **Link to Documentation and Commit Histories:** The LLM can connect a piece of code to its associated design docs, recent commit messages, or open pull requests. If a developer asks, _“How has `UserProfileAPI.js` changed over the last quarter?”_ the LLM can summarize major refactoring steps, point to relevant issues that were closed, and link to architectural decision records. ### [​](https://docs.cognee.ai/examples/code-assistants#outcomes:) Outcomes: * **Improved Developer Productivity:** Instead of wading through multiple repositories, developers get immediate, context-aware guidance, saving countless hours of manual searching and guesswork. * **More Accurate Code Suggestions:** Coding copilots armed with a CodeGraph context deliver more reliable and secure code completions, better refactoring strategies, and insightful recommendations. * **Evolving with the Codebase:** As repositories grow, the CodeGraph and the LLM continuously update. This ensures that as code evolves, the memory and context available to developers—and their automated assistants—stays fresh and relevant. #### [​](https://docs.cognee.ai/examples/code-assistants#run-a-demo-yourself) Run a Demo Yourself! Curious about how this works with cognee? Try it out in our notebook [here](https://github.com/topoteretes/cognee/blob/291f1c5a55abacdef3356fabd37ee0a677db34e1/notebooks/cognee_code_graph_demo.ipynb) . #### [​](https://docs.cognee.ai/examples/code-assistants#join-the-conversation) Join the Conversation! Have questions? Join our community now to connect with professionals, share insights, and get your questions answered! [Join the community](https://discord.gg/m63hxKsp4p) Was this page helpful? YesNo [Previous](https://docs.cognee.ai/examples/chatbots) [Documentation Intelligence\ \ Next](https://docs.cognee.ai/examples/documentation-intelligence) ⌘I On this page * [CodeGraph: Enhancing Codebase Understanding with Graphs and LLMs](https://docs.cognee.ai/examples/code-assistants#codegraph:-enhancing-codebase-understanding-with-graphs-and-llms) * [Scenario:](https://docs.cognee.ai/examples/code-assistants#scenario:) * [Challenges:](https://docs.cognee.ai/examples/code-assistants#challenges:) * [Solution: Creating a CodeGraph](https://docs.cognee.ai/examples/code-assistants#solution:-creating-a-codegraph) * [Outcomes:](https://docs.cognee.ai/examples/code-assistants#outcomes:) * [Run a Demo Yourself!](https://docs.cognee.ai/examples/code-assistants#run-a-demo-yourself) * [Join the Conversation!](https://docs.cognee.ai/examples/code-assistants#join-the-conversation) --- # Human Resources - Cognee Documentation [Skip to main content](https://docs.cognee.ai/examples/human-resources#content-area) [Cognee Documentation home page![light logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20black.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=ea48b52be1df02b5909f780e6cd6856e)![dark logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20white.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=9f5bc18c4897c6e58b5cfa2b09bc079d)](https://docs.cognee.ai/) Search... ⌘K Search... Navigation Use Cases Human Resources [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) [​](https://docs.cognee.ai/examples/human-resources#hr-and-talent-management:-aligning-cvs-and-job-posts-with-entity-resolution) HR and Talent Management: Aligning CVs and Job Posts with Entity Resolution --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### [​](https://docs.cognee.ai/examples/human-resources#scenario:) Scenario: A large enterprise’s HR team is inundated with job applications. Recruiters need to quickly find the best candidates for specific roles, but the data they must sift through is unstructured and scattered: * **CVs (Resumes):** Arrive in various formats (PDFs, Word docs, online profiles) and contain a mix of structured (degree names, job titles) and unstructured elements (summaries, personal statements). * **Job Posts:** Stored in a centralized system, with each role described in terms of required skills, qualifications, and experience. Yet, this system doesn’t consistently align with the language or formats used by applicants on their CVs. * **Internal Talent Databases:** Contain historical performance data, training records, and skill endorsements for existing employees who might be suitable for open roles. ### [​](https://docs.cognee.ai/examples/human-resources#challenges:) Challenges: 1. **Inconsistent Terminology:** A “Business Analyst” role might be titled as “Data Insights Specialist” in a CV, and the required skill “SQL proficiency” might appear as “database querying” or “familiarity with SQL-based tools.” 2. **Entity Resolution Complexity:** Different representations of the same entity (e.g., a skill like “machine learning” vs. “ML engineering,” or a company name spelled differently) need to be unified so recruiters see a clear, accurate view. 3. **Volume and Velocity:** With hundreds or thousands of applicants per role and multiple roles open at once, it’s challenging to quickly identify the right candidates without a reliable way to standardize and query this information. ### [​](https://docs.cognee.ai/examples/human-resources#solution-with-kgs-&-llms:) Solution with KGs & LLMs: 1. **Building a Knowledge Graph:** A KG connects roles, skills, qualifications, and experience levels to one another. For instance: * Skills like “SQL,” “Python,” and “Data Visualization” are captured as nodes. * Job roles link to these skills, indicating required proficiency levels. * Educational qualifications, certifications, and industry experience are recorded similarly. 2. **Entity Resolution for Skills & Titles:** Using entity resolution techniques, the system normalizes various mentions of the same skill or title. For example: * “SQL experience” in one CV and “database querying” in another CV map to a single “SQL” skill node. * Different job titles that effectively mean the same role (e.g., “Data Analyst” and “Junior Data Analyst”) link back to a standard role entity. 3. **LLM-Driven Text-to-SQL Queries:** With the KG in place, recruiters can use natural language questions against the structured data: * _“Show me candidates applying for the Business Analyst role who have demonstrated SQL proficiency and at least 3 years of experience in data analytics.”_ An LLM translates this into an SQL query that retrieves candidates matching these criteria. The KG ensures that the query understands synonyms and resolves variations in terminology across CVs and job postings. 4. **Explaining Results & Candidate Matching:** When presenting results, the system can explain why certain candidates are a good fit—highlighting the linked entities (skills, certifications, job titles) and showing how they map to the job’s requirements. This transparency builds trust and speeds up the selection process. ### [​](https://docs.cognee.ai/examples/human-resources#outcomes:) Outcomes: * **Faster Shortlisting:** Recruiters spend less time manually parsing CVs and searching through databases. * **Better Candidate-Role Alignment:** By unifying entities, the system ensures no qualified candidate goes overlooked due to mismatched terminology or formatting. * **Scalable & Fair Hiring:** As the organization grows, the approach scales to thousands of roles and applicants, maintaining consistency and potentially reducing bias by focusing on structured, contextually rich data. In essence, applying LLM-driven Text-to-SQL solutions, powered by a well-structured KG and robust entity resolution, helps HR teams instantly understand candidate profiles in relation to job requirements, saving time, reducing complexity, and improving the quality of hiring decisions. #### [​](https://docs.cognee.ai/examples/human-resources#run-a-demo-yourself) Run a Demo Yourself! Curious about how this works with cognee? Try it out in our notebook [here](https://github.com/topoteretes/cognee/blob/dev/notebooks/hr_demo.ipynb) . #### [​](https://docs.cognee.ai/examples/human-resources#join-the-conversation) Join the Conversation! Have questions? Join our community now to connect with professionals, share insights, and get your questions answered! [Join the community](https://discord.gg/m63hxKsp4p) Was this page helpful? YesNo [Previous](https://docs.cognee.ai/examples/documentation-intelligence) [Cognee WalkthroughFrom Data to Interactive Memory: End-to-end tutorial with nodesets, ontologies, memify, graph visualization, and feedback system using a coding assistant example\ \ Next](https://docs.cognee.ai/examples/getting-started-with-cognee) ⌘I On this page * [HR and Talent Management: Aligning CVs and Job Posts with Entity Resolution](https://docs.cognee.ai/examples/human-resources#hr-and-talent-management:-aligning-cvs-and-job-posts-with-entity-resolution) * [Scenario:](https://docs.cognee.ai/examples/human-resources#scenario:) * [Challenges:](https://docs.cognee.ai/examples/human-resources#challenges:) * [Solution with KGs & LLMs:](https://docs.cognee.ai/examples/human-resources#solution-with-kgs-&-llms:) * [Outcomes:](https://docs.cognee.ai/examples/human-resources#outcomes:) * [Run a Demo Yourself!](https://docs.cognee.ai/examples/human-resources#run-a-demo-yourself) * [Join the Conversation!](https://docs.cognee.ai/examples/human-resources#join-the-conversation) --- # NodeSets - Cognee Documentation [Skip to main content](https://docs.cognee.ai/core-concepts/further-concepts/node-sets#content-area) [Cognee Documentation home page![light logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20black.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=ea48b52be1df02b5909f780e6cd6856e)![dark logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20white.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=9f5bc18c4897c6e58b5cfa2b09bc079d)](https://docs.cognee.ai/) Search... ⌘K Search... Navigation Further Concepts NodeSets [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) [​](https://docs.cognee.ai/core-concepts/further-concepts/node-sets#what-are-nodesets) What are NodeSets? ------------------------------------------------------------------------------------------------------------ A **NodeSet** lets you group parts of your AI memory at the dataset level. You create them as a simple list of tags when adding data to Cognee: await cognee.add(…, node\_set=\[“projectA”,“finance”\]) These tags travel with your data into the knowledge graph, where they become first-class nodes connected with belongs\_to\_set edges — and you can later filter searches to only those subsets. [​](https://docs.cognee.ai/core-concepts/further-concepts/node-sets#how-they-flow-through-cognee) How they flow through Cognee --------------------------------------------------------------------------------------------------------------------------------- * **[Add](https://docs.cognee.ai/core-concepts/main-operations/add) **: * NodeSets are attached as simple tags to datasets or documents * This happens when you first ingest data * **[Cognify](https://docs.cognee.ai/core-concepts/main-operations/cognify) **: * carried into Documents and Chunks * materialized as real `NodeSet` nodes in the graph * connected with `belongs_to_set` edges * **[Search](https://docs.cognee.ai/core-concepts/main-operations/search) **: * NodeSets act as entry points into the graph * Queries can be scoped to only nodes linked to specific NodeSets * This lets you search within a tagged subset of your data [​](https://docs.cognee.ai/core-concepts/further-concepts/node-sets#why-they-matter) Why they matter ------------------------------------------------------------------------------------------------------- * Provide a lightweight way to organize and tag your data * Enable graph-based filtering, traversal, and reporting * Ideal for creating project-, domain-, or user-defined subsets of your knowledge graph [​](https://docs.cognee.ai/core-concepts/further-concepts/node-sets#example) Example --------------------------------------------------------------------------------------- Copy import asyncio import cognee async def main(): # reset Cognee’s memory and metadata for a clean run await cognee.prune.prune_data() await cognee.prune.prune_system(metadata=True) # add a document linked only to the "AI_Memory" node set await cognee.add( "Cognee builds AI memory from raw documents.", node_set=["AI_Memory"] ) # add a document linked to both "AI_Memory" and "Graph_RAG" node sets await cognee.add( "Cognee combines vector search with graph reasoning.", node_set=["AI_Memory", "Graph_RAG"] ) # build the knowledge graph by extracting entities and relationships await cognee.cognify() if __name__ == "__main__": asyncio.run(main()) [​](https://docs.cognee.ai/core-concepts/further-concepts/node-sets#what-just-happened) What just happened? -------------------------------------------------------------------------------------------------------------- * You reset Cognee’s memory so you’re working with a clean graph. * You added two documents, each tagged with one or more `NodeSet` labels. * The first document is only linked to `AI_Memory`. * The second document is linked to both `AI_Memory` and `Graph_RAG`. * When you ran `cognify()`, Cognee: * Created `NodeSet` nodes (`AI_Memory`, `Graph_RAG`) in the graph. * Attached each document to the corresponding NodeSets. * Extracted entities and relationships from the documents, then linked those entities back to the same NodeSets. This means the tags you add flow down into the extracted entities: * **“Cognee”** appears in both documents → connects to **both NodeSets**. * **“AI memory”** appears only in the first → connects only to **AI\_Memory**. * **“Vector search”** appears only in the second → connects to **both** since that document belongs to **AI\_Memory** and **Graph\_RAG**. Your NodeSets now unlock powerful search and navigation capabilities: * You can filter searches by NodeSet. * You can scope queries to specific NodeSets. * You can navigate data by project or domain using NodeSets. [Add\ ---\ \ Where NodeSets are first attached](https://docs.cognee.ai/core-concepts/main-operations/add) [Cognify\ -------\ \ How NodeSets are promoted into graph nodes](https://docs.cognee.ai/core-concepts/main-operations/cognify) [Search\ ------\ \ Use NodeSets as anchors in queries](https://docs.cognee.ai/core-concepts/main-operations/search) Was this page helpful? YesNo [Previous](https://docs.cognee.ai/core-concepts/further-concepts/datasets) [OntologiesEnrich your knowledge graph with external vocabularies\ \ Next](https://docs.cognee.ai/core-concepts/further-concepts/ontologies) ⌘I On this page * [What are NodeSets?](https://docs.cognee.ai/core-concepts/further-concepts/node-sets#what-are-nodesets) * [How they flow through Cognee](https://docs.cognee.ai/core-concepts/further-concepts/node-sets#how-they-flow-through-cognee) * [Why they matter](https://docs.cognee.ai/core-concepts/further-concepts/node-sets#why-they-matter) * [Example](https://docs.cognee.ai/core-concepts/further-concepts/node-sets#example) * [What just happened?](https://docs.cognee.ai/core-concepts/further-concepts/node-sets#what-just-happened) --- # Chatbots - Cognee Documentation [Skip to main content](https://docs.cognee.ai/examples/chatbots#content-area) [Cognee Documentation home page![light logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20black.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=ea48b52be1df02b5909f780e6cd6856e)![dark logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20white.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=9f5bc18c4897c6e58b5cfa2b09bc079d)](https://docs.cognee.ai/) Search... ⌘K Search... Navigation Use Cases Chatbots [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) [​](https://docs.cognee.ai/examples/chatbots#case-study:-personalizing-chatbots-with-timeseries,-behaviors,-and-more) Case Study: Personalizing Chatbots with Timeseries, Behaviors, and More ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ Chatbots powered by LLMs are redefining **customer service**, **internal communication**, and **personalized recommendations** across industries. In financial services, pharma, and even other industries, these chatbots can leverage provide more relevant, customized interactions - beyond direct Text-to-SQL querying. ### [​](https://docs.cognee.ai/examples/chatbots#scenario:-an-investment-advisory-chatbot-assists-clients-with-portfolio-decisions) Scenario: An Investment Advisory Chatbot Assists Clients with Portfolio Decisions * Uses **time-series data** to identify spending patterns. * Leverages **user behavior** to suggest savings plans. * Integrates **business logic** to enforce compliance with financial regulations. Queries might include: > _“What’s my portfolio’s performance trend over the last year?”_ > _“Suggest adjustments to reduce volatility while maintaining similar returns.”_ ### [​](https://docs.cognee.ai/examples/chatbots#challenges:) Challenges: * **Dynamic Personalization:** Each user’s investment history, risk profile, and interactions form a personal data layer. * **Temporal Data Understanding:** Time-series analysis is needed to interpret trends, volatility shifts, and performance changes over specific periods. * **Multi-Modal Context:** The chatbot should integrate behavior analytics, market conditions, and portfolio constraints into a cohesive response. ### [​](https://docs.cognee.ai/examples/chatbots#solution:) Solution: **Knowledge Graphs (KG) & Contextualization:** By building a KG enriched with user segments, product categories, and historic interaction patterns, the LLM can provide responses rooted in the individual’s context. When paired with Text-to-SQL capabilities, it can surface data-driven recommendations, filtering queries through the lens of each user’s unique financial journey or, in the case of pharma, clinical patterns relevant to individual practitioners or researchers. Read more about our approach in our [blog](https://www.cognee.ai/blog/case-studies/cognee-case-study-with-dynamo) where we achieved a great improvement. ![chatbots_eval_example_dynamo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/chatbots_eval_example_dynamo.png?w=2500&fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=27e80ddb18b2475e2c0ac1abe5e4af3c) ### [​](https://docs.cognee.ai/examples/chatbots#a-simple-example-with-cognee) A simple example with cognee ![chatbot_code_example](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/chatbots_code_example.png?w=2500&fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=f7a08a2b17bedfad1346d8ecc0420afd) #### [​](https://docs.cognee.ai/examples/chatbots#run-a-demo-yourself) Run a Demo Yourself! Curious about how this works with cognee? Try it out in our notebook [here](https://github.com/topoteretes/cognee/blob/291f1c5a55abacdef3356fabd37ee0a677db34e1/notebooks/cognee_demo.ipynb) . #### [​](https://docs.cognee.ai/examples/chatbots#join-the-conversation) Join the Conversation! Have questions? Join our community now to connect with professionals, share insights, and get your questions answered! [Join the community](https://discord.gg/m63hxKsp4p) Was this page helpful? YesNo [Previous](https://docs.cognee.ai/guides/custom-prompts) [Code Assistants\ \ Next](https://docs.cognee.ai/examples/code-assistants) ⌘I On this page * [Case Study: Personalizing Chatbots with Timeseries, Behaviors, and More](https://docs.cognee.ai/examples/chatbots#case-study:-personalizing-chatbots-with-timeseries,-behaviors,-and-more) * [Scenario: An Investment Advisory Chatbot Assists Clients with Portfolio Decisions](https://docs.cognee.ai/examples/chatbots#scenario:-an-investment-advisory-chatbot-assists-clients-with-portfolio-decisions) * [Challenges:](https://docs.cognee.ai/examples/chatbots#challenges:) * [Solution:](https://docs.cognee.ai/examples/chatbots#solution:) * [A simple example with cognee](https://docs.cognee.ai/examples/chatbots#a-simple-example-with-cognee) * [Run a Demo Yourself!](https://docs.cognee.ai/examples/chatbots#run-a-demo-yourself) * [Join the Conversation!](https://docs.cognee.ai/examples/chatbots#join-the-conversation) --- # Search - Cognee Documentation [Skip to main content](https://docs.cognee.ai/core-concepts/main-operations/search#content-area) [Cognee Documentation home page![light logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20black.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=ea48b52be1df02b5909f780e6cd6856e)![dark logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20white.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=9f5bc18c4897c6e58b5cfa2b09bc079d)](https://docs.cognee.ai/) Search... ⌘K Search... Navigation Main Operations Search [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) [​](https://docs.cognee.ai/core-concepts/main-operations/search#what-is-search) What is search ------------------------------------------------------------------------------------------------- `search` lets you ask questions over everything you’ve ingested and cognified. Under the hood, Cognee blends **vector similarity**, **graph structure**, and **LLM reasoning** to return answers with context and provenance. [​](https://docs.cognee.ai/core-concepts/main-operations/search#the-big-picture) The big picture --------------------------------------------------------------------------------------------------- * **Dataset-aware**: searches run against one or more datasets you can read _(requires `ENABLE_BACKEND_ACCESS_CONTROL=true`)_ * **Multiple modes**: from simple chunk lookup to graph-aware Q&A * **Hybrid retrieval**: vectors find relevant pieces; graphs provide structure; LLMs compose answers * **Safe by default**: permissions are checked before any retrieval * **Observability**: telemetry is emitted for query start/completion **Dataset scoping** requires specific configuration. See [permissions system](https://docs.cognee.ai/core-concepts/permissions-system/datasets#dataset-isolation) for details on access control requirements and supported database setups. [​](https://docs.cognee.ai/core-concepts/main-operations/search#where-search-fits) Where search fits ------------------------------------------------------------------------------------------------------- Use `search` after you’ve run `.add` and `.cognify`. At that point, your dataset has chunks, summaries, embeddings, and a knowledge graph—so queries can leverage both **similarity** and **structure**. [​](https://docs.cognee.ai/core-concepts/main-operations/search#how-it-works-conceptually) How it works (conceptually) ------------------------------------------------------------------------------------------------------------------------- 1. **Scope & permissions** Resolve target datasets (by name or id) and enforce read access. 2. **Mode dispatch** Pick a search mode (default: **graph-aware completion**) and route to its retriever. 3. **Retrieve → (optional) generate** Collect context via vectors and/or graph traversal; some modes then ask an LLM to compose a final answer. 4. **Return results** Depending on mode: answers, chunks/summaries with metadata, graph records, Cypher results, or code contexts. For a practical guide to using search with examples and detailed parameter explanations, see [Search Basics](https://docs.cognee.ai/guides/search-basics) . GRAPH\_COMPLETION (default) Graph-aware question answering. * **What it does**: Finds relevant graph triplets using vector hints across indexed fields, resolves them into readable context, and asks an LLM to answer your question grounded in that context. * **Why it’s useful**: Combines fuzzy matching (vectors) with precise structure (graph) so answers reflect relationships, not just nearby text. * **Typical output**: A natural-language answer with references to the supporting graph context. RAG\_COMPLETION Retrieve-then-generate over text chunks. * **What it does**: Pulls top-k chunks via vector search, stitches a context window, then asks an LLM to answer. * **When to use**: You want fast, text-only RAG without graph structure. * **Output**: An LLM answer grounded in retrieved chunks. CHUNKS Direct chunk retrieval. * **What it does**: Returns the most similar text chunks to your query via vector search. * **When to use**: You want raw passages/snippets to display or post-process. * **Output**: Chunk objects with metadata. SUMMARIES Search over precomputed summaries. * **What it does**: Vector search on `TextSummary` content for concise, high-signal hits. * **When to use**: You prefer short summaries instead of full chunks. * **Output**: Summary objects with provenance. GRAPH\_SUMMARY\_COMPLETION Graph-aware summary answering. * **What it does**: Builds graph context like GRAPH\_COMPLETION, then condenses it before answering. * **When to use**: You want a tighter, summary-first response. * **Output**: A concise answer grounded in graph context. GRAPH\_COMPLETION\_COT Chain-of-thought over the graph. * **What it does**: Iterative rounds of graph retrieval and LLM reasoning to refine the answer. * **When to use**: Complex questions that benefit from stepwise reasoning. * **Output**: A refined answer produced through multiple reasoning steps. GRAPH\_COMPLETION\_CONTEXT\_EXTENSION Iterative context expansion. * **What it does**: Starts with initial graph context, lets the LLM suggest follow-ups, fetches more graph context, repeats. * **When to use**: Open-ended queries that need broader exploration. * **Output**: An answer assembled after expanding the relevant subgraph. NATURAL\_LANGUAGE Natural language to Cypher to execution. * **What it does**: Infers a Cypher query from your question using the graph schema, runs it, returns the results. * **When to use**: You want structured graph answers without writing Cypher. * **Output**: Executed graph results. CYPHER Run Cypher directly. * **What it does**: Executes your Cypher query against the graph database. * **When to use**: You know the schema and want full control. * **Output**: Raw query results. CODE Code-focused retrieval. * **What it does**: Interprets your intent (files/snippets), searches code embeddings and related graph nodes, and assembles relevant source. * **When to use**: Codebases indexed by Cognee. * **Output**: Structured code contexts and related graph information. FEELING\_LUCKY Automatic mode selection. * **What it does**: Uses an LLM to pick the most suitable search mode for your query, then runs it. * **When to use**: You’re not sure which mode fits best. * **Output**: Results from the selected mode. FEEDBACK Store feedback on recent interactions. * **What it does**: Records user feedback on recent answers and links it to the associated graph elements for future tuning. * **When to use**: Closing the loop on quality and relevance. * **Output**: A feedback record tied to recent interactions. [Add\ ---\ \ First bring data into Cognee](https://docs.cognee.ai/core-concepts/main-operations/add) [Cognify\ -------\ \ Build the knowledge graph that search queries](https://docs.cognee.ai/core-concepts/main-operations/cognify) [Architecture\ ------------\ \ Understand how vector and graph stores work together](https://docs.cognee.ai/core-concepts/architecture) Was this page helpful? YesNo [Previous](https://docs.cognee.ai/core-concepts/main-operations/cognify) [MemifySemantic enrichment of existing knowledge graphs with derived facts\ \ Next](https://docs.cognee.ai/core-concepts/main-operations/memify) ⌘I On this page * [What is search](https://docs.cognee.ai/core-concepts/main-operations/search#what-is-search) * [The big picture](https://docs.cognee.ai/core-concepts/main-operations/search#the-big-picture) * [Where search fits](https://docs.cognee.ai/core-concepts/main-operations/search#where-search-fits) * [How it works (conceptually)](https://docs.cognee.ai/core-concepts/main-operations/search#how-it-works-conceptually) --- # Datasets - Cognee Documentation [Skip to main content](https://docs.cognee.ai/core-concepts/further-concepts/datasets#content-area) [Cognee Documentation home page![light logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20black.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=ea48b52be1df02b5909f780e6cd6856e)![dark logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20white.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=9f5bc18c4897c6e58b5cfa2b09bc079d)](https://docs.cognee.ai/) Search... ⌘K Search... Navigation Further Concepts Datasets [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) [​](https://docs.cognee.ai/core-concepts/further-concepts/datasets#what-is-a-dataset-in-cognee) What is a dataset in Cognee? ------------------------------------------------------------------------------------------------------------------------------- A dataset is a named container that groups documents and their metadata. It is the main boundary for: * Organizing content * Running pipelines * Applying permissions **Dataset isolation** requires specific configuration. See [permissions system](https://docs.cognee.ai/core-concepts/permissions-system/datasets#dataset-isolation) for details on access control requirements and supported database setups. * **[Add](https://docs.cognee.ai/core-concepts/main-operations/add) **: * Direct new content into a specific dataset (by name or ID) * If it doesn’t exist, Cognee creates it and associates your permissions * Items ingested are linked to that dataset and deduplicated within it * **[Cognify](https://docs.cognee.ai/core-concepts/main-operations/cognify) **: * Choose which dataset(s) to transform into a knowledge graph * Loads the dataset’s content, checks rights, and runs the pipeline per dataset * If none are specified, processes all datasets you’re authorized to use * Progress is tracked per dataset for reliable re-runs * **[Search](https://docs.cognee.ai/core-concepts/main-operations/search) **: * Queries can be scoped by dataset * Results and metrics remain separated by dataset [​](https://docs.cognee.ai/core-concepts/further-concepts/datasets#access-control) Access control ---------------------------------------------------------------------------------------------------- * Permissions (read, write, share, delete) are enforced at the dataset level * Share one dataset with a team, keep another private * Independently manage who can modify or distribute content [​](https://docs.cognee.ai/core-concepts/further-concepts/datasets#incremental-processing) Incremental processing -------------------------------------------------------------------------------------------------------------------- * Processing status is tracked per dataset * After you add more data, Cognify focuses on new or changed items * Skips what’s already completed for that dataset [​](https://docs.cognee.ai/core-concepts/further-concepts/datasets#datasets-vs-nodesets) Datasets vs NodeSets ---------------------------------------------------------------------------------------------------------------- **Datasets** scope storage, permissions, and pipeline execution; **[NodeSets](https://docs.cognee.ai/core-concepts/further-concepts/node-sets) ** are semantic tags within a dataset. * During Add, you can label items with one or more NodeSet names (e.g., “AI”, “FinTech”) * Cognify propagates those labels into the graph by creating `NodeSet` nodes and linking derived chunks and entities via `belongs_to_set` relationships * This lets you slice a single dataset’s graph by topic or team without creating new datasets, while dataset-level permissions still control overall access [Add\ ---\ \ Direct content into a dataset](https://docs.cognee.ai/core-concepts/main-operations/add) [Cognify\ -------\ \ Run pipelines per dataset](https://docs.cognee.ai/core-concepts/main-operations/cognify) [Search\ ------\ \ Scope queries by dataset](https://docs.cognee.ai/core-concepts/main-operations/search) Was this page helpful? YesNo [Previous](https://docs.cognee.ai/core-concepts/main-operations/memify) [NodeSetsTagging and grouping data in Cognee\ \ Next](https://docs.cognee.ai/core-concepts/further-concepts/node-sets) ⌘I On this page * [What is a dataset in Cognee?](https://docs.cognee.ai/core-concepts/further-concepts/datasets#what-is-a-dataset-in-cognee) * [Access control](https://docs.cognee.ai/core-concepts/further-concepts/datasets#access-control) * [Incremental processing](https://docs.cognee.ai/core-concepts/further-concepts/datasets#incremental-processing) * [Datasets vs NodeSets](https://docs.cognee.ai/core-concepts/further-concepts/datasets#datasets-vs-nodesets) --- # Adapters Overview - Cognee Documentation [Skip to main content](https://docs.cognee.ai/setup-configuration/community-maintained/overview#content-area) [Cognee Documentation home page![light logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20black.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=ea48b52be1df02b5909f780e6cd6856e)![dark logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20white.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=9f5bc18c4897c6e58b5cfa2b09bc079d)](https://docs.cognee.ai/) Search... ⌘K Search... Navigation Cognee Community Adapters Adapters Overview [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) Community-maintained integrations are adapters built and maintained by the Cognee community. These extend Cognee’s functionality with additional providers and services. Community integrations are maintained separately from the core Cognee package. For issues or contributions, visit the [cognee-community repository](https://github.com/topoteretes/cognee-community) . [​](https://docs.cognee.ai/setup-configuration/community-maintained/overview#available-integrations) Available Integrations ------------------------------------------------------------------------------------------------------------------------------ ### [​](https://docs.cognee.ai/setup-configuration/community-maintained/overview#vector-stores) Vector Stores * **[Qdrant](https://docs.cognee.ai/setup-configuration/community-maintained/qdrant) ** — High-performance vector search engine * **[Milvus](https://github.com/topoteretes/cognee-community/tree/main/packages/vector/milvus) ** — Cloud-native vector database (docs coming soon) * **[Pinecone](https://github.com/topoteretes/cognee-community/tree/main/packages/vector/pinecone) ** — Managed vector database (docs coming soon) * **[Weaviate](https://github.com/topoteretes/cognee-community/tree/main/packages/vector/weaviate) ** — Open-source vector search engine (docs coming soon) * **[Redis](https://github.com/topoteretes/cognee-community/tree/main/packages/vector/redis) ** — Redis with vector search capabilities (docs coming soon) * **[Azure AI Search](https://github.com/topoteretes/cognee-community/tree/main/packages/vector/azureaisearch) ** — Azure cognitive search service (docs coming soon) * **[OpenSearch](https://github.com/topoteretes/cognee-community/tree/main/packages/vector/opensearch) ** — OpenSearch vector engine (docs coming soon) ### [​](https://docs.cognee.ai/setup-configuration/community-maintained/overview#hybrid-stores) Hybrid Stores * **[DuckDB](https://github.com/topoteretes/cognee-community/tree/main/packages/hybrid/duckdb) ** — In-process analytical database (docs coming soon) * **[FalkorDB](https://github.com/topoteretes/cognee-community/tree/main/packages/hybrid/falkordb) ** — Graph database with vector support (docs coming soon) ### [​](https://docs.cognee.ai/setup-configuration/community-maintained/overview#graph-stores) Graph Stores * **[Memgraph](https://github.com/topoteretes/cognee-community/tree/main/packages/graph/memgraph) ** — In-memory graph database (docs coming soon) * **[NetworkX](https://github.com/topoteretes/cognee-community/tree/main/packages/graph/networkx) ** — Python graph library adapter (docs coming soon) ### [​](https://docs.cognee.ai/setup-configuration/community-maintained/overview#observability) Observability * **[KeywordsAI](https://github.com/topoteretes/cognee-community/tree/main/packages/observability/keywordsai) ** — LLM monitoring and analytics (docs coming soon) [​](https://docs.cognee.ai/setup-configuration/community-maintained/overview#contributing) Contributing ---------------------------------------------------------------------------------------------------------- To contribute a new community integration: 1. Fork the [cognee-community repository](https://github.com/topoteretes/cognee-community) 2. Follow the adapter development guide 3. Submit a pull request with your integration 4. Add documentation following the existing patterns [​](https://docs.cognee.ai/setup-configuration/community-maintained/overview#support) Support ------------------------------------------------------------------------------------------------ For community integration support: * Check the integration’s README in the repository * Open issues in the cognee-community repository * Join the [Discord community](https://discord.gg/m63hKsp4p) for help [Vector Stores\ -------------\ \ Official vector store providers](https://docs.cognee.ai/setup-configuration/vector-stores) [Setup Overview\ --------------\ \ Configuration overview](https://docs.cognee.ai/setup-configuration/overview) Was this page helpful? YesNo [Previous](https://docs.cognee.ai/setup-configuration/permissions) [QdrantUse Qdrant as a vector store through a community-maintained adapter\ \ Next](https://docs.cognee.ai/setup-configuration/community-maintained/qdrant) ⌘I On this page * [Available Integrations](https://docs.cognee.ai/setup-configuration/community-maintained/overview#available-integrations) * [Vector Stores](https://docs.cognee.ai/setup-configuration/community-maintained/overview#vector-stores) * [Hybrid Stores](https://docs.cognee.ai/setup-configuration/community-maintained/overview#hybrid-stores) * [Graph Stores](https://docs.cognee.ai/setup-configuration/community-maintained/overview#graph-stores) * [Observability](https://docs.cognee.ai/setup-configuration/community-maintained/overview#observability) * [Contributing](https://docs.cognee.ai/setup-configuration/community-maintained/overview#contributing) * [Support](https://docs.cognee.ai/setup-configuration/community-maintained/overview#support) --- # DataPoints - Cognee Documentation [Skip to main content](https://docs.cognee.ai/core-concepts/building-blocks/datapoints#content-area) [Cognee Documentation home page![light logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20black.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=ea48b52be1df02b5909f780e6cd6856e)![dark logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20white.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=9f5bc18c4897c6e58b5cfa2b09bc079d)](https://docs.cognee.ai/) Search... ⌘K Search... Navigation Building Blocks DataPoints [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) [​](https://docs.cognee.ai/core-concepts/building-blocks/datapoints#datapoints:-atomic-units-of-knowledge) DataPoints: Atomic Units of Knowledge =================================================================================================================================================== DataPoints are the smallest building blocks in Cognee. They represent **atomic units of knowledge** — carrying both your actual content and the context needed to process, index, and connect it. They’re the reason Cognee can turn raw documents into something that’s both **searchable** (via vectors) and **connected** (via graphs). [​](https://docs.cognee.ai/core-concepts/building-blocks/datapoints#what-are-datapoints) What are DataPoints --------------------------------------------------------------------------------------------------------------- * **Atomic** — each DataPoint represents one concept or unit of information. * **Structured** — implemented as [Pydantic](https://docs.pydantic.dev/) models for validation and serialization. * **Contextual** — carry provenance, versioning, and indexing hints so every step downstream knows where data came from and how to use it. [​](https://docs.cognee.ai/core-concepts/building-blocks/datapoints#core-structure) Core Structure ----------------------------------------------------------------------------------------------------- A DataPoint is just a Pydantic model with a set of standard fields. See example class definition Copy class DataPoint(BaseModel): id: UUID = Field(default_factory=uuid4) created_at: int = ... updated_at: int = ... version: int = 1 topological_rank: Optional[int] = 0 metadata: Optional[dict] = {"index_fields": []} type: str = "DataPoint" belongs_to_set: Optional[List["DataPoint"]] = None Key fields: * `id` — unique identifier * `created_at`, `updated_at` — timestamps (ms since epoch) * `version` — for tracking changes and schema evolution * `metadata.index_fields` — critical: determines which fields are embedded for vector search * `type` — class name * `belongs_to_set` — groups related DataPoints [​](https://docs.cognee.ai/core-concepts/building-blocks/datapoints#indexing-&-embeddings) Indexing & Embeddings ------------------------------------------------------------------------------------------------------------------- The `metadata.index_fields` tells Cognee which fields to embed into the vector store. This is the mechanism behind semantic search. * Fields in `index_fields` → converted into embeddings * Each indexed field → its own vector collection (`Class_field`) * Non-indexed fields → stay as regular properties * Choosing what to index controls search granularity [​](https://docs.cognee.ai/core-concepts/building-blocks/datapoints#from-datapoints-to-the-graph) From DataPoints to the Graph --------------------------------------------------------------------------------------------------------------------------------- When you call `add_data_points()`, Cognee automatically: * Embeds the indexed fields into vectors * Converts the object into **nodes** and **edges** in the knowledge graph * Stores provenance in the relational store This is how Cognee creates both **semantic similarity** (vector) and **structural reasoning** (graph) from the same unit. [​](https://docs.cognee.ai/core-concepts/building-blocks/datapoints#examples-and-details) Examples and details ----------------------------------------------------------------------------------------------------------------- Example: indexing only one field Copy class Person(DataPoint): name: str age: int metadata: dict = {"index_fields": ["name"]} Only `"name"` is semantically searchable Example: Book → Author transformation Copy class Book(DataPoint): title: str author: Author metadata: dict = {"index_fields": ["title"]} # Produces: # `Node(Book)` with `{title, type, ...}` # Node(Author) with {name, type, ...} # Edge(Book → Author, type="author") Relationship syntax options Copy # Simple relationship `author: Author` # With edge metadata `has_items: (Edge(weight=0.8), list[Item])` # List relationship `chapters: list[Chapter]` Built-in DataPoint types Cognee ships with several built-in DataPoint types: * **Documents** — wrappers for source files (Text, PDF, Audio, Image) * `Document` (`metadata.index_fields=["name"]`) * **Chunks** — segmented portions of documents * `DocumentChunk` (`metadata.index_fields=["text"]`) * **Summaries** — generated text or code summaries * `TextSummary` / `CodeSummary` (`metadata.index_fields=["text"]`) * **Entities** — named objects (people, places, concepts) * `Entity`, `EntityType` (`metadata.index_fields=["name"]`) * **Edges** — relationships between DataPoints * `Edge` — links between DataPoints Example: custom DataPoint with best practices Copy class Product(DataPoint): name: str description: str price: float category: Category # Index name + description for search metadata: dict = {"index_fields": ["name", "description"]} **Best Practices:** * **Keep it small** — one concept per DataPoint * **Index carefully** — only fields that matter for semantic search * **Use built-in types first** — extend with custom subclasses when needed * **Version deliberately** — track changes with `version` * **Group related points** — with `belongs_to_set` [Tasks\ -----\ \ Learn how DataPoints are created and processed](https://docs.cognee.ai/core-concepts/building-blocks/tasks) [Pipelines\ ---------\ \ See how DataPoints flow through processing workflows](https://docs.cognee.ai/core-concepts/building-blocks/pipelines) [Main Operations\ ---------------\ \ Understand how DataPoints are used in Add, Cognify, and Search](https://docs.cognee.ai/core-concepts/main-operations/add) Was this page helpful? YesNo [Previous](https://docs.cognee.ai/core-concepts/architecture) [TasksBuilding blocks of processing that transform data in Cognee pipelines\ \ Next](https://docs.cognee.ai/core-concepts/building-blocks/tasks) ⌘I On this page * [DataPoints: Atomic Units of Knowledge](https://docs.cognee.ai/core-concepts/building-blocks/datapoints#datapoints:-atomic-units-of-knowledge) * [What are DataPoints](https://docs.cognee.ai/core-concepts/building-blocks/datapoints#what-are-datapoints) * [Core Structure](https://docs.cognee.ai/core-concepts/building-blocks/datapoints#core-structure) * [Indexing & Embeddings](https://docs.cognee.ai/core-concepts/building-blocks/datapoints#indexing-&-embeddings) * [From DataPoints to the Graph](https://docs.cognee.ai/core-concepts/building-blocks/datapoints#from-datapoints-to-the-graph) * [Examples and details](https://docs.cognee.ai/core-concepts/building-blocks/datapoints#examples-and-details) --- # Add - Cognee Documentation [Skip to main content](https://docs.cognee.ai/core-concepts/main-operations/add#content-area) [Cognee Documentation home page![light logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20black.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=ea48b52be1df02b5909f780e6cd6856e)![dark logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20white.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=9f5bc18c4897c6e58b5cfa2b09bc079d)](https://docs.cognee.ai/) Search... ⌘K Search... Navigation Main Operations Add [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) [​](https://docs.cognee.ai/core-concepts/main-operations/add#what-is-the-add-operation) What is the add operation -------------------------------------------------------------------------------------------------------------------- The `.add` operation is how you bring content into Cognee. It takes your files, directories, or raw text, normalizes them into plain text, and records them into a dataset that Cognee can later expand into vectors and graphs with [Cognify](https://docs.cognee.ai/core-concepts/main-operations/cognify) . * **Ingestion-only**: no embeddings, no graph yet * **Flexible input**: raw text, local files, directories, or S3 URIs * **Normalized storage**: everything is turned into text and stored consistently * **Deduplicated**: Cognee uses content hashes to avoid duplicates * **Dataset-first**: everything you add goes into a dataset * Datasets are how Cognee keeps different collections organized (e.g. “research-papers”, “customer-reports”) * Each dataset has its own ID, owner, and permissions for access control * You can read more about them below [​](https://docs.cognee.ai/core-concepts/main-operations/add#where-add-fits) Where add fits ---------------------------------------------------------------------------------------------- * First step before you run [Cognify](https://docs.cognee.ai/core-concepts/main-operations/cognify) * Use it to **create a dataset** from scratch, or **append new data** over time * Ideal for both local experiments and programmatic ingestion from storage (e.g. S3) [​](https://docs.cognee.ai/core-concepts/main-operations/add#what-happens-under-the-hood) What happens under the hood ------------------------------------------------------------------------------------------------------------------------ 1. **Expand your input** * Directories are walked, S3 paths are expanded, raw text is passed through * Result: a flat list of items (files, text, handles) 2. **Ingest and register** * Files are saved into Cognee’s storage and converted to text * Cognee computes a stable content hash to prevent duplicates * Each item becomes a record in the database and is attached to your dataset * **Text extraction**: Converts various file formats into plain text * **Metadata preservation**: Keeps file information like source, creation date, and format * **Content normalization**: Ensures consistent text encoding and formatting 3. **Return a summary** * You get a pipeline run info object that tells you where everything went and which dataset is ready for the next step [​](https://docs.cognee.ai/core-concepts/main-operations/add#after-add-finishes) After add finishes ------------------------------------------------------------------------------------------------------ After `.add` completes, your data is ready for the next stage: * **Files are safely stored** in Cognee’s storage system with metadata preserved * **Database records** track each ingested item and link it to your dataset * **Dataset is prepared** for transformation with [Cognify](https://docs.cognee.ai/core-concepts/main-operations/cognify) — which will chunk, embed, and connect everything [​](https://docs.cognee.ai/core-concepts/main-operations/add#further-details) Further details ------------------------------------------------------------------------------------------------ Input sources * Mix and match: `["some text", "/path/to/file.pdf", "s3://bucket/data.csv"]` * Works with directories (recursively), S3 prefixes, and file handles * Local and cloud sources are normalized into the same format Supported formats * **Text**: `.txt, .md, .csv, .json, …` * **PDF**: `.pdf` * **Images**: common formats like `.png, .jpg, .gif, .webp, …` * **Audio**: `.mp3, .wav, .flac, …` * **Office docs**: `.docx, .pptx, .xlsx, …` * **Docling**: Cognee can also ingest the `DoclingDocument` format. Any format that [Docling](https://github.com/docling-project/docling) supports as input can be converted, then passed on to Cognee’s add. * Cognee chooses the right loader for each format under the hood Datasets * A dataset is your “knowledge base” — a grouping of related data that makes sense together * Datasets are **first-class objects in Cognee’s database** with their own ID, name, owner, and permissions * They provide **scope**: `.add` writes into a dataset, [Cognify](https://docs.cognee.ai/core-concepts/main-operations/cognify) processes per-dataset * Think of them as separate shelves in your library — e.g., a “research-papers” dataset and a “customer-reports” dataset * If you name a dataset that doesn’t exist, Cognee creates it for you; if you don’t specify, a default one is used Users and ownership * Every dataset and data item belongs to a user * If you don’t pass a user, Cognee creates/uses a default one * Ownership controls who can later read, write, or share that dataset Node sets * Optional labels to group or tag data on ingestion * Example: `node_set=["AI", "FinTech"]` * Useful later when you want to focus on subgraphs [Cognify\ -------\ \ Expand data into chunks, embeddings, and graphs](https://docs.cognee.ai/core-concepts/main-operations/cognify) [DataPoints\ ----------\ \ The units you’ll see after Cognify](https://docs.cognee.ai/core-concepts/building-blocks/datapoints) [Building Blocks\ ---------------\ \ Learn about Tasks and Pipelines behind Add](https://docs.cognee.ai/core-concepts/building-blocks/tasks) Was this page helpful? YesNo [Previous](https://docs.cognee.ai/core-concepts/building-blocks/pipelines) [CognifyTransforming ingested data into a knowledge graph with embeddings, chunks, and summaries\ \ Next](https://docs.cognee.ai/core-concepts/main-operations/cognify) ⌘I On this page * [What is the add operation](https://docs.cognee.ai/core-concepts/main-operations/add#what-is-the-add-operation) * [Where add fits](https://docs.cognee.ai/core-concepts/main-operations/add#where-add-fits) * [What happens under the hood](https://docs.cognee.ai/core-concepts/main-operations/add#what-happens-under-the-hood) * [After add finishes](https://docs.cognee.ai/core-concepts/main-operations/add#after-add-finishes) * [Further details](https://docs.cognee.ai/core-concepts/main-operations/add#further-details) --- # Installation - Cognee Documentation [Skip to main content](https://docs.cognee.ai/getting-started/installation#content-area) [Cognee Documentation home page![light logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20black.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=ea48b52be1df02b5909f780e6cd6856e)![dark logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20white.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=9f5bc18c4897c6e58b5cfa2b09bc079d)](https://docs.cognee.ai/) Search... ⌘K Search... Navigation Getting Started Installation [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) Set up your environment and install Cognee to start building AI memory. Python **3.9 – 3.12** is required to run Cognee. [​](https://docs.cognee.ai/getting-started/installation#prerequisites) Prerequisites --------------------------------------------------------------------------------------- Environment Configuration * We recommend creating a `.env` file in your project root * Cognee supports many configuration options, and a `.env` file keeps them organized API Keys & Models You have two main options for configuring LLM and embedding providers:**Option 1: OpenAI (Simplest)** * Single API key handles both LLM and embeddings * Uses gpt-4o-mini for LLM and text-embedding-3-small for embeddings by default * Works out of the box with minimal configuration **Option 2: Other Providers** * Configure both LLM and embedding providers separately * Supports Gemini, Anthropic, Ollama, and more * Requires setting both `LLM_*` and `EMBEDDING_*` variables By default, Cognee uses OpenAI for both LLMs and embeddings. If you change the LLM provider but don’t configure embeddings, it will still default to OpenAI. Virtual Environment * We recommend using [uv](https://github.com/astral-sh/uv) for virtual environment management * Run the following commands to create and activate a virtual environment: Copy uv venv && source .venv/bin/activate Optional Database * PostgreSQL database is required if you plan to use PostgreSQL as your relational database (requires `postgres` extra) [​](https://docs.cognee.ai/getting-started/installation#setup) Setup ----------------------------------------------------------------------- * OpenAI (Recommended) * Other Providers (Gemini, Anthropic, etc.) **Environment:** Add your OpenAI API key to your `.env` file: Copy LLM_API_KEY="your_openai_api_key" **Installation:** Install Cognee with all extras: Copy uv pip install cognee **What this gives you**: Cognee installed with default local databases (SQLite, LanceDB, Kuzu) — no external servers required. This single API key handles both LLM and embeddings. We use gpt-4o-mini for the LLM model and text-embedding-3-small for embeddings by default. [​](https://docs.cognee.ai/getting-started/installation#next-steps) Next Steps --------------------------------------------------------------------------------- [Run Your First Example\ ----------------------\ \ **Quickstart Tutorial**Get started with Cognee by running your first knowledge graph example.](https://docs.cognee.ai/getting-started/quickstart) [Explore Advanced Features\ -------------------------\ \ **Core Concepts**Dive deeper into Cognee’s powerful features and capabilities.](https://docs.cognee.ai/core-concepts) Was this page helpful? YesNo [Previous](https://docs.cognee.ai/getting-started/introduction) [QuickstartGet started with Cognee quickly and efficiently\ \ Next](https://docs.cognee.ai/getting-started/quickstart) ⌘I On this page * [Prerequisites](https://docs.cognee.ai/getting-started/installation#prerequisites) * [Setup](https://docs.cognee.ai/getting-started/installation#setup) * [Next Steps](https://docs.cognee.ai/getting-started/installation#next-steps) --- # Documentation Intelligence - Cognee Documentation [Skip to main content](https://docs.cognee.ai/examples/documentation-intelligence#content-area) [Cognee Documentation home page![light logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20black.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=ea48b52be1df02b5909f780e6cd6856e)![dark logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20white.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=9f5bc18c4897c6e58b5cfa2b09bc079d)](https://docs.cognee.ai/) Search... ⌘K Search... Navigation Use Cases Documentation Intelligence [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) [​](https://docs.cognee.ai/examples/documentation-intelligence#case-study:-knowledge-assistant-for-technical-documentation) Case Study: Knowledge Assistant for Technical Documentation ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ Most documentation assistants today rely on simple keyword matching or basic RAG, which treats each piece of text in isolation. We introduce a paradigm shift in how we approach documentation assistance, moving beyond simple text retrieval to understanding the intricate relationships between concepts. ### [​](https://docs.cognee.ai/examples/documentation-intelligence#scenario:-intelligent-documentation-assistant-to-built-with-qdrant) Scenario: Intelligent Documentation Assistant to Built with Qdrant Imagine a developer trying to optimize their Qdrant vector database implementation. Instead of jumping between dozens of documentation pages, picking the relevant ones and adding them manually to their coding assistant; they can ask natural language questions like: > _“How do I optimize Qdrant’s performance for high-throughput scenarios?”_ > _“What’s the relationship between indexing strategies and memory usage?”_ > _“How does distributed deployment affect query latency?”_ A knowledge graph-powered assistant doesn’t just find pages with those keywords—it understands the relationships between performance optimization, indexing strategies, memory usage, and distributed deployment, providing comprehensive answers that draw from multiple related concepts. ### [​](https://docs.cognee.ai/examples/documentation-intelligence#four-stage-solution-pipeline) Four-Stage Solution Pipeline In this example, we transform raw documentation into structured, queryable knowledge through a four-stage pipeline: #### [​](https://docs.cognee.ai/examples/documentation-intelligence#1-%F0%9F%95%B7%EF%B8%8F-intelligent-web-scraping) 1\. 🕷️ Intelligent Web Scraping * **Systematic crawling** using breadth-first search to discover all documentation pages * **Clean content extraction** using tools like Firecrawl API to get markdown content * **Rate limiting and retry handling** for robust data collection * **Comprehensive aggregation** into a single, structured document #### [​](https://docs.cognee.ai/examples/documentation-intelligence#2-%F0%9F%A7%B9-content-cleaning-&-preprocessing) 2\. 🧹 Content Cleaning & Preprocessing * **Noise removal** including cookie banners, privacy notices, and navigation elements * **Content normalization** to ensure consistent formatting * **Focus on technical content** by filtering out non-essential elements #### [​](https://docs.cognee.ai/examples/documentation-intelligence#3-%F0%9F%A7%A0-knowledge-graph-construction) 3\. 🧠 Knowledge Graph Construction Using Cognee, the cleaned documentation is transformed into a structured knowledge graph: Copy # Load content into Cognee await cognee.add([md_content], dataset_name) # Build the knowledge graph await cognee.cognify([dataset_name]) Cognee automatically: * **Extracts entities** (concepts, technologies, features) * **Identifies relationships** between entities * **Creates queryable graph structure** * **Enables semantic understanding** of the content #### [​](https://docs.cognee.ai/examples/documentation-intelligence#4-%F0%9F%94%8D-intelligent-querying) 4\. 🔍 Intelligent Querying **Graph Completion**: Leverages the knowledge graph structure for contextual answers Copy graph_completion_answer = await cognee.search( query_type=SearchType.GRAPH_COMPLETION, query_text=query_text, datasets=[dataset_name] ) ### [​](https://docs.cognee.ai/examples/documentation-intelligence#why-knowledge-graphs-matter) Why Knowledge Graphs Matter The power of this approach lies in understanding that: ✨ **Concepts are connected**: Understanding vector databases requires knowing about embeddings, similarity search, and indexing ✨ **Context matters**: The same term might mean different things in different contexts ✨ **Relationships are key**: Knowing how concepts relate is often more important than knowing what they are ✨ **Comprehensive reasoning**: Can handle complex queries that span multiple documentation sections ### [​](https://docs.cognee.ai/examples/documentation-intelligence#real-world-benefits) Real-World Benefits This approach delivers several practical advantages: * **🎯 More Accurate Answers**: By understanding relationships, the system provides more contextually relevant responses * **⚡ Faster Discovery**: Users can find information faster because the system understands what they’re really asking * **🔗 Better Connections**: The system can suggest related topics and help users discover relevant information they might not have thought to ask about * **📈 Scalable**: As documentation grows, the knowledge graph automatically incorporates new relationships ### [​](https://docs.cognee.ai/examples/documentation-intelligence#technology-stack) Technology Stack We used several cutting-edge technologies for this use demo: * **Cognee**: Core knowledge graph framework for entity extraction, relationship mapping, retrieving * **Firecrawl**: Clean web scraping that extracts markdown content * **Neo4j & Qdrant**: Backend storage for the knowledge graph * **OpenAI GPT**: As our LLM provider ### [​](https://docs.cognee.ai/examples/documentation-intelligence#getting-started) Getting Started Ready to build your own documentation assistant? You can follow [this example](https://github.com/topoteretes/cognee-community/tree/main/experimental/faq_assistant_qdrant_docs) . Here’s how it works: 1. **Install Cognee** with the necessary providers: Copy pip install cognee[neo4j,qdrant]>=0.1.40 2. **Scrape your documentation**: Copy # Customize the scraping for your docs site python scrape_docs.py 3. **Clean the content**: Copy # Remove noise and normalize content python clean_docs_qdrant.py 4. **Build the knowledge graph**: Copy # Transform content into structured knowledge python faq_assistant_with_cognee.py 5. **Start querying**: Copy # Begin asking intelligent questions python query.py ### [​](https://docs.cognee.ai/examples/documentation-intelligence#advanced-applications) Advanced Applications This approach opens up exciting possibilities: * **Multi-modal support**: Incorporating images, videos, and code examples * **Real-time updates**: Automatically updating the knowledge graph as documentation changes * **Interactive exploration**: Building UIs that let users explore the knowledge graph visually * **Cross-documentation search**: Connecting knowledge graphs from multiple projects * **Agent memory**: Integrating with coding assistants through cognee MCP server. In this example, we connected our knowledge graph generated by cognee again with cognee’s mcp server via Cursor. Thus, while building our solution with Qdrant, we didn’t have to go back and forth with documentation tabs - all the knowledge were available to us on the Cursor’s chat interface without manually adding docs pages. ### [​](https://docs.cognee.ai/examples/documentation-intelligence#next-steps) Next Steps Want to dive deeper into building intelligent documentation assistants? Check out: * [Cognee GitHub Repository](https://github.com/topoteretes/cognee) for the core framework * [Community Examples](https://github.com/topoteretes/cognee-community) for practical implementations * [Custom Tasks and Pipelines](https://docs.cognee.ai/guides/custom-tasks-pipelines) for advanced customization #### [​](https://docs.cognee.ai/examples/documentation-intelligence#join-the-conversation) Join the Conversation! Have questions about building memory enchanced assistants? Join our community to connect with other developers and get expert guidance! [Join the community](https://discord.gg/m63hxKsp4p) Was this page helpful? YesNo [Previous](https://docs.cognee.ai/examples/code-assistants) [Human Resources\ \ Next](https://docs.cognee.ai/examples/human-resources) ⌘I On this page * [Case Study: Knowledge Assistant for Technical Documentation](https://docs.cognee.ai/examples/documentation-intelligence#case-study:-knowledge-assistant-for-technical-documentation) * [Scenario: Intelligent Documentation Assistant to Built with Qdrant](https://docs.cognee.ai/examples/documentation-intelligence#scenario:-intelligent-documentation-assistant-to-built-with-qdrant) * [Four-Stage Solution Pipeline](https://docs.cognee.ai/examples/documentation-intelligence#four-stage-solution-pipeline) * [1\. 🕷️ Intelligent Web Scraping](https://docs.cognee.ai/examples/documentation-intelligence#1-%F0%9F%95%B7%EF%B8%8F-intelligent-web-scraping) * [2\. 🧹 Content Cleaning & Preprocessing](https://docs.cognee.ai/examples/documentation-intelligence#2-%F0%9F%A7%B9-content-cleaning-&-preprocessing) * [3\. 🧠 Knowledge Graph Construction](https://docs.cognee.ai/examples/documentation-intelligence#3-%F0%9F%A7%A0-knowledge-graph-construction) * [4\. 🔍 Intelligent Querying](https://docs.cognee.ai/examples/documentation-intelligence#4-%F0%9F%94%8D-intelligent-querying) * [Why Knowledge Graphs Matter](https://docs.cognee.ai/examples/documentation-intelligence#why-knowledge-graphs-matter) * [Real-World Benefits](https://docs.cognee.ai/examples/documentation-intelligence#real-world-benefits) * [Technology Stack](https://docs.cognee.ai/examples/documentation-intelligence#technology-stack) * [Getting Started](https://docs.cognee.ai/examples/documentation-intelligence#getting-started) * [Advanced Applications](https://docs.cognee.ai/examples/documentation-intelligence#advanced-applications) * [Next Steps](https://docs.cognee.ai/examples/documentation-intelligence#next-steps) * [Join the Conversation!](https://docs.cognee.ai/examples/documentation-intelligence#join-the-conversation) --- # Structured Output Backends - Cognee Documentation [Skip to main content](https://docs.cognee.ai/setup-configuration/structured-output-backends#content-area) [Cognee Documentation home page![light logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20black.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=ea48b52be1df02b5909f780e6cd6856e)![dark logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20white.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=9f5bc18c4897c6e58b5cfa2b09bc079d)](https://docs.cognee.ai/) Search... ⌘K Search... Navigation Setup Configuration Structured Output Backends [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) Structured output backends ensure reliable data extraction from LLM responses. Cognee supports two frameworks that convert LLM text into structured Pydantic models for knowledge graph extraction and other tasks. **New to configuration?**See the [Setup Configuration Overview](https://docs.cognee.ai/setup-configuration/overview) for the complete workflow:install extras → create `.env` → choose providers → handle pruning. [​](https://docs.cognee.ai/setup-configuration/structured-output-backends#supported-frameworks) Supported Frameworks ----------------------------------------------------------------------------------------------------------------------- Cognee supports two structured output approaches: * **LiteLLM + Instructor** — Provider-agnostic client with Pydantic coercion (default) * **BAML** — DSL-based framework with type registry and guardrails Both frameworks produce the same Pydantic-validated outputs, so your application code remains unchanged regardless of which backend you choose. [​](https://docs.cognee.ai/setup-configuration/structured-output-backends#how-it-works) How It Works ------------------------------------------------------------------------------------------------------- Cognee uses a unified interface that abstracts the underlying framework: Copy from cognee.infrastructure.llm.LLMGateway import LLMGateway await LLMGateway.acreate_structured_output(text, system_prompt, response_model) The `STRUCTURED_OUTPUT_FRAMEWORK` environment variable determines which backend processes your requests, but the API remains identical. [​](https://docs.cognee.ai/setup-configuration/structured-output-backends#configuration) Configuration --------------------------------------------------------------------------------------------------------- * LiteLLM + Instructor (Default) * BAML Copy STRUCTURED_OUTPUT_FRAMEWORK=instructor [​](https://docs.cognee.ai/setup-configuration/structured-output-backends#important-notes) Important Notes ------------------------------------------------------------------------------------------------------------- * **Unified Interface**: Your application code uses the same `acreate_structured_output()` call regardless of framework * **Provider Flexibility**: Both frameworks support the same LLM providers * **Output Consistency**: Both produce identical Pydantic-validated results * **Performance**: Framework choice doesn’t significantly impact performance [LLM Providers\ -------------\ \ Configure LLM providers for text generation](https://docs.cognee.ai/setup-configuration/llm-providers) [Overview\ --------\ \ Return to setup configuration overview](https://docs.cognee.ai/setup-configuration/overview) [Custom Prompts\ --------------\ \ Learn about custom prompt configuration](https://docs.cognee.ai/guides/custom-prompts) Was this page helpful? YesNo [Previous](https://docs.cognee.ai/setup-configuration/llm-providers) [Embedding ProvidersConfigure embedding providers for semantic search in Cognee\ \ Next](https://docs.cognee.ai/setup-configuration/embedding-providers) ⌘I On this page * [Supported Frameworks](https://docs.cognee.ai/setup-configuration/structured-output-backends#supported-frameworks) * [How It Works](https://docs.cognee.ai/setup-configuration/structured-output-backends#how-it-works) * [Configuration](https://docs.cognee.ai/setup-configuration/structured-output-backends#configuration) * [Important Notes](https://docs.cognee.ai/setup-configuration/structured-output-backends#important-notes) --- # Architecture - Cognee Documentation [Skip to main content](https://docs.cognee.ai/core-concepts/architecture#content-area) [Cognee Documentation home page![light logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20black.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=ea48b52be1df02b5909f780e6cd6856e)![dark logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20white.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=9f5bc18c4897c6e58b5cfa2b09bc079d)](https://docs.cognee.ai/) Search... ⌘K Search... Navigation Core Concepts Architecture [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) [​](https://docs.cognee.ai/core-concepts/architecture#cognee-architecture) Cognee Architecture ================================================================================================= [​](https://docs.cognee.ai/core-concepts/architecture#why-multiple-stores) Why multiple stores ------------------------------------------------------------------------------------------------- No single database can handle all aspects of memory. Cognee combines three complementary storage systems. Each one plays a different role, and together they make your data both **searchable** and **connected**. * **Relational store** — Tracks your documents, their chunks, and provenance (i.e. where each piece of data came from and how it’s linked to the source). * **Vector store** — Holds embeddings for semantic similarity (i.e. numerical representations that let Cognee find conceptually related text, even if the wording is different). * **Graph store** — Captures entities and relationships in a knowledge graph (i.e. nodes and edges that let Cognee understand structure and navigate connections between concepts). Cognee ships with lightweight defaults that run locally, and you can swap in production-ready backends when needed (see [Setup](https://docs.cognee.ai/core-concepts/getting-started/installation) ). [​](https://docs.cognee.ai/core-concepts/architecture#what-is-stored-where) What is stored where --------------------------------------------------------------------------------------------------- Roughly speaking: * The **relational store** handles document-level metadata and provenance. * The **vector store** contains semantic fingerprints of chunks and [DataPoints](https://docs.cognee.ai/core-concepts/building-blocks/datapoints) . * The **graph store** captures higher-level structure in the form of entities and relationships. There is some overlap: for efficiency, parts of the same information may be indexed in more than one store. [​](https://docs.cognee.ai/core-concepts/architecture#how-they-are-used) How they are used --------------------------------------------------------------------------------------------- The stores play different roles depending on the phase: * The **relational store** matters most during _cognification_, keeping track of documents, chunks, and where each piece of information comes from. * The **vector** and **graph** stores come into play during _search and retrieval_: * **Semantic searches** (vector): find conceptually related passages based on embeddings * **Structural searches** (graph): explore entities and relationships using Cypher directly * **Hybrid searches** (vector + graph): combine both perspectives to surface results that are contextually rich and structurally precise. [Main Operations\ ---------------\ \ See how Add, Cognify, and Search use the storage systems](https://docs.cognee.ai/core-concepts/main-operations/add) [Building Blocks\ ---------------\ \ Learn about DataPoints, Tasks, and Pipelines that feed into storage](https://docs.cognee.ai/core-concepts/building-blocks/datapoints) [Search\ ------\ \ Explore different query types and modes that leverage the architecture](https://docs.cognee.ai/core-concepts/main-operations/search) Was this page helpful? YesNo [Previous](https://docs.cognee.ai/core-concepts/overview) [DataPointsAtomic units of knowledge in Cognee\ \ Next](https://docs.cognee.ai/core-concepts/building-blocks/datapoints) ⌘I On this page * [Cognee Architecture](https://docs.cognee.ai/core-concepts/architecture#cognee-architecture) * [Why multiple stores](https://docs.cognee.ai/core-concepts/architecture#why-multiple-stores) * [What is stored where](https://docs.cognee.ai/core-concepts/architecture#what-is-stored-where) * [How they are used](https://docs.cognee.ai/core-concepts/architecture#how-they-are-used) --- # LLM Providers - Cognee Documentation [Skip to main content](https://docs.cognee.ai/setup-configuration/llm-providers#content-area) [Cognee Documentation home page![light logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20black.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=ea48b52be1df02b5909f780e6cd6856e)![dark logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20white.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=9f5bc18c4897c6e58b5cfa2b09bc079d)](https://docs.cognee.ai/) Search... ⌘K Search... Navigation Setup Configuration LLM Providers [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) LLM (Large Language Model) providers handle text generation, reasoning, and structured output tasks in Cognee. You can choose from cloud providers like OpenAI and Anthropic, or run models locally with Ollama. **New to configuration?**See the [Setup Configuration Overview](https://docs.cognee.ai/setup-configuration/overview) for the complete workflow:install extras → create `.env` → choose providers → handle pruning. [​](https://docs.cognee.ai/setup-configuration/llm-providers#supported-providers) Supported Providers -------------------------------------------------------------------------------------------------------- Cognee supports multiple LLM providers: * **OpenAI** — GPT models via OpenAI API (default) * **Azure OpenAI** — GPT models via Azure OpenAI Service * **Google Gemini** — Gemini models via Google AI * **Anthropic** — Claude models via Anthropic API * **Ollama** — Local models via Ollama * **Custom** — OpenAI-compatible endpoints **LLM/Embedding Configuration**: If you configure only LLM or only embeddings, the other defaults to OpenAI. Ensure you have a working OpenAI API key, or configure both LLM and embeddings to avoid unexpected defaults. [​](https://docs.cognee.ai/setup-configuration/llm-providers#configuration) Configuration -------------------------------------------------------------------------------------------- Environment Variables Set these environment variables in your `.env` file: * `LLM_PROVIDER` — The provider to use (openai, gemini, anthropic, ollama, custom) * `LLM_MODEL` — The specific model to use * `LLM_API_KEY` — Your API key for the provider * `LLM_ENDPOINT` — Custom endpoint URL (for Azure, Ollama, or custom providers) * `LLM_API_VERSION` — API version (for Azure OpenAI) * `LLM_MAX_TOKENS` — Maximum tokens per request (optional) [​](https://docs.cognee.ai/setup-configuration/llm-providers#provider-setup-guides) Provider Setup Guides ------------------------------------------------------------------------------------------------------------ OpenAI (Default) OpenAI is the default provider and works out of the box with minimal configuration. Copy LLM_PROVIDER="openai" LLM_MODEL="gpt-4o-mini" LLM_API_KEY="sk-..." # Optional overrides # LLM_ENDPOINT=https://api.openai.com/v1 # LLM_API_VERSION= # LLM_MAX_TOKENS=16384 Azure OpenAI Use Azure OpenAI Service with your own deployment. Copy LLM_PROVIDER="openai" LLM_MODEL="azure/gpt-4o-mini" LLM_ENDPOINT="https://.openai.azure.com/openai/deployments/gpt-4o-mini" LLM_API_KEY="az-..." LLM_API_VERSION="2024-12-01-preview" Google Gemini Use Google’s Gemini models for text generation. Copy LLM_PROVIDER="gemini" LLM_MODEL="gemini/gemini-2.0-flash" LLM_API_KEY="AIza..." # Optional # LLM_ENDPOINT=https://generativelanguage.googleapis.com/ # LLM_API_VERSION=v1beta Anthropic Use Anthropic’s Claude models for reasoning tasks. Copy LLM_PROVIDER="anthropic" LLM_MODEL="claude-3-5-sonnet-20241022" LLM_API_KEY="sk-ant-..." Ollama (Local) Run models locally with Ollama for privacy and cost control. Copy LLM_PROVIDER="ollama" LLM_MODEL="llama3.1:8b" LLM_ENDPOINT="http://localhost:11434/v1" LLM_API_KEY="ollama" **Installation**: Install Ollama from [ollama.ai](https://ollama.ai/) and pull your desired model: Copy ollama pull llama3.1:8b ### [​](https://docs.cognee.ai/setup-configuration/llm-providers#known-issues) Known Issues * **Requires `HUGGINGFACE_TOKENIZER`**: Ollama currently needs this env var set even when used only as LLM. Fix in progress. * **`NoDataError` with mixed providers**: Using Ollama as LLM and OpenAI as embedding provider may fail with `NoDataError`. Workaround: use the same provider for both. Custom Providers Use OpenAI-compatible endpoints like OpenRouter or other services. Copy LLM_PROVIDER="custom" LLM_MODEL="openrouter/google/gemini-2.0-flash-lite-preview-02-05:free" LLM_ENDPOINT="https://openrouter.ai/api/v1" LLM_API_KEY="or-..." # Optional fallback chain # FALLBACK_MODEL= # FALLBACK_ENDPOINT= # FALLBACK_API_KEY= [​](https://docs.cognee.ai/setup-configuration/llm-providers#advanced-options) Advanced Options -------------------------------------------------------------------------------------------------- Rate Limiting Control client-side throttling for LLM calls to manage API usage and costs.**Configuration (in .env):** Copy LLM_RATE_LIMIT_ENABLED="true" LLM_RATE_LIMIT_REQUESTS="60" LLM_RATE_LIMIT_INTERVAL="60" **How it works:** * **Client-side limiter**: Cognee paces outbound LLM calls before they reach the provider * **Moving window**: Spreads allowance across the time window for smoother throughput * **Per-process scope**: In-memory limits don’t share across multiple processes/containers * **Auto-applied**: Works with all providers (OpenAI, Gemini, Anthropic, Ollama, Custom) **Example**: `60` requests per `60` seconds ≈ 1 request/second average rate. [​](https://docs.cognee.ai/setup-configuration/llm-providers#notes) Notes ---------------------------------------------------------------------------- * If `EMBEDDING_API_KEY` is not set, Cognee falls back to `LLM_API_KEY` for embeddings * Rate limiting helps manage API usage and costs * Structured output frameworks ensure consistent data extraction from LLM responses [Embedding Providers\ -------------------\ \ Configure embedding providers for semantic search](https://docs.cognee.ai/setup-configuration/embedding-providers) [Overview\ --------\ \ Return to setup configuration overview](https://docs.cognee.ai/setup-configuration/overview) [Relational Databases\ --------------------\ \ Set up SQLite or Postgres for metadata storage](https://docs.cognee.ai/setup-configuration/relational-databases) Was this page helpful? YesNo [Previous](https://docs.cognee.ai/setup-configuration/overview) [Structured Output BackendsConfigure structured output frameworks for reliable data extraction in Cognee\ \ Next](https://docs.cognee.ai/setup-configuration/structured-output-backends) ⌘I On this page * [Supported Providers](https://docs.cognee.ai/setup-configuration/llm-providers#supported-providers) * [Configuration](https://docs.cognee.ai/setup-configuration/llm-providers#configuration) * [Provider Setup Guides](https://docs.cognee.ai/setup-configuration/llm-providers#provider-setup-guides) * [Advanced Options](https://docs.cognee.ai/setup-configuration/llm-providers#advanced-options) * [Notes](https://docs.cognee.ai/setup-configuration/llm-providers#notes) --- # Graph Stores - Cognee Documentation [Skip to main content](https://docs.cognee.ai/setup-configuration/graph-stores#content-area) [Cognee Documentation home page![light logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20black.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=ea48b52be1df02b5909f780e6cd6856e)![dark logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20white.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=9f5bc18c4897c6e58b5cfa2b09bc079d)](https://docs.cognee.ai/) Search... ⌘K Search... Navigation Setup Configuration Graph Stores [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) Graph stores capture entities and relationships in knowledge graphs. They enable Cognee to understand structure and navigate connections between concepts, providing powerful reasoning capabilities. **New to configuration?**See the [Setup Configuration Overview](https://docs.cognee.ai/setup-configuration/overview) for the complete workflow:install extras → create `.env` → choose providers → handle pruning. [​](https://docs.cognee.ai/setup-configuration/graph-stores#supported-providers) Supported Providers ------------------------------------------------------------------------------------------------------- Cognee supports multiple graph store options: * **Kuzu** — Local file-based graph database (default) * **Kuzu-remote** — Kuzu with HTTP API access * **Neo4j** — Production-ready graph database * **Neptune** — Amazon Neptune cloud graph database * **Neptune Analytics** — Amazon Neptune Analytics hybrid solution [​](https://docs.cognee.ai/setup-configuration/graph-stores#configuration) Configuration ------------------------------------------------------------------------------------------- Environment Variables Set these environment variables in your `.env` file: * `GRAPH_DATABASE_PROVIDER` — The graph store provider (kuzu, kuzu-remote, neo4j, neptune, neptune\_analytics) * `GRAPH_DATABASE_URL` — Database URL or connection string * `GRAPH_DATABASE_USERNAME` — Database username (optional) * `GRAPH_DATABASE_PASSWORD` — Database password (optional) * `GRAPH_DATABASE_NAME` — Database name (optional) [​](https://docs.cognee.ai/setup-configuration/graph-stores#setup-guides) Setup Guides ----------------------------------------------------------------------------------------- Kuzu (Default) Kuzu is file-based and requires no network setup. It’s perfect for local development and single-user scenarios. Copy GRAPH_DATABASE_PROVIDER="kuzu" # Optional: override location # SYSTEM_ROOT_DIRECTORY=/absolute/path/.cognee_system # The graph file will default to /databases/cognee_graph_kuzu **Installation**: Kuzu is included by default with Cognee. No additional installation required.**Data Location**: The graph is stored on disk. Path defaults under the Cognee system directory and is created automatically. **Concurrency Limitation**: Kuzu uses file-based locking and is not suitable for concurrent use from different agents or processes. For multi-agent scenarios, use Neo4j instead. Kuzu (Remote API) Use Kuzu with an HTTP API when you need remote access or want to run Kuzu as a service. Copy GRAPH_DATABASE_PROVIDER="kuzu-remote" GRAPH_DATABASE_URL="http://localhost:8000" GRAPH_DATABASE_USERNAME="" GRAPH_DATABASE_PASSWORD="" **Installation**: Requires a running Kuzu service exposing an HTTP API. Neo4j Neo4j is recommended for production environments and multi-user scenarios. Copy GRAPH_DATABASE_PROVIDER="neo4j" GRAPH_DATABASE_URL="bolt://localhost:7687" GRAPH_DATABASE_NAME="neo4j" GRAPH_DATABASE_USERNAME="neo4j" GRAPH_DATABASE_PASSWORD="pleaseletmein" **Installation**: Install Neo4j extras: Copy pip install "cognee[neo4j]" **Docker Setup**: Start the bundled Neo4j service with APOC + GDS plugins: Copy docker compose --profile neo4j up -d Neptune (Graph-only) Use Amazon Neptune for cloud-based graph storage. Copy GRAPH_DATABASE_PROVIDER="neptune" GRAPH_DATABASE_URL="neptune://" # AWS credentials via environment or default SDK chain **Installation**: Install Neptune extras: Copy pip install "cognee[neptune]" **Note**: AWS credentials should be configured via environment variables or AWS SDK. Neptune Analytics (Hybrid) Use Amazon Neptune Analytics as a hybrid vector + graph backend. Copy GRAPH_DATABASE_PROVIDER="neptune_analytics" GRAPH_DATABASE_URL="neptune-graph://" # AWS credentials via environment or default SDK chain **Installation**: Install Neptune extras: Copy pip install "cognee[neptune]" **Note**: This is the same as the vector store configuration. Neptune Analytics serves both purposes. [​](https://docs.cognee.ai/setup-configuration/graph-stores#advanced-options) Advanced Options ------------------------------------------------------------------------------------------------- Backend Access Control Enable per-user dataset isolation for multi-tenant scenarios. Copy ENABLE_BACKEND_ACCESS_CONTROL="true" This feature is available for Kuzu and other supported graph stores. [​](https://docs.cognee.ai/setup-configuration/graph-stores#provider-comparison) Provider Comparison ------------------------------------------------------------------------------------------------------- Graph Store Comparison | Provider | Setup | Performance | Use Case | | --- | --- | --- | --- | | Kuzu | Zero setup | Good | Local development | | Kuzu-remote | Server required | Good | Remote access | | Neo4j | Server required | Excellent | Production | | Neptune | AWS required | Excellent | Cloud solution | | Neptune Analytics | AWS required | Excellent | Hybrid cloud solution | [​](https://docs.cognee.ai/setup-configuration/graph-stores#important-considerations) Important Considerations ----------------------------------------------------------------------------------------------------------------- Data Location * **Local providers** (Kuzu): Graph files are created automatically under `SYSTEM_ROOT_DIRECTORY` * **Remote providers** (Neo4j, Neptune): Require running services or cloud setup * **Path management**: Local graphs are managed automatically, no manual path configuration needed Performance Notes * **Kuzu**: Single-file storage with good local performance * **Neo4j**: Excellent for production workloads with proper indexing * **Neptune**: Cloud-scale performance with managed infrastructure * **Hybrid solutions**: Combine graph and vector capabilities in one system [​](https://docs.cognee.ai/setup-configuration/graph-stores#notes) Notes --------------------------------------------------------------------------- * **Backend Access Control**: When enabled, Kuzu supports per-user dataset isolation * **Path Management**: Local Kuzu databases are created automatically under the system directory * **Cloud Integration**: Neptune providers require AWS credentials and proper IAM permissions [Vector Stores\ -------------\ \ Configure vector databases for embedding storage](https://docs.cognee.ai/setup-configuration/vector-stores) [Relational Databases\ --------------------\ \ Set up SQLite or Postgres for metadata storage](https://docs.cognee.ai/setup-configuration/relational-databases) [Overview\ --------\ \ Return to setup configuration overview](https://docs.cognee.ai/setup-configuration/overview) Was this page helpful? YesNo [Previous](https://docs.cognee.ai/setup-configuration/vector-stores) [Permissions SetupConfigure Cognee's permission system and access control\ \ Next](https://docs.cognee.ai/setup-configuration/permissions) ⌘I On this page * [Supported Providers](https://docs.cognee.ai/setup-configuration/graph-stores#supported-providers) * [Configuration](https://docs.cognee.ai/setup-configuration/graph-stores#configuration) * [Setup Guides](https://docs.cognee.ai/setup-configuration/graph-stores#setup-guides) * [Advanced Options](https://docs.cognee.ai/setup-configuration/graph-stores#advanced-options) * [Provider Comparison](https://docs.cognee.ai/setup-configuration/graph-stores#provider-comparison) * [Important Considerations](https://docs.cognee.ai/setup-configuration/graph-stores#important-considerations) * [Notes](https://docs.cognee.ai/setup-configuration/graph-stores#notes) --- # Relational Databases - Cognee Documentation [Skip to main content](https://docs.cognee.ai/setup-configuration/relational-databases#content-area) [Cognee Documentation home page![light logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20black.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=ea48b52be1df02b5909f780e6cd6856e)![dark logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20white.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=9f5bc18c4897c6e58b5cfa2b09bc079d)](https://docs.cognee.ai/) Search... ⌘K Search... Navigation Setup Configuration Relational Databases [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) Relational databases store metadata, document information, and system state in Cognee. They track documents, chunks, and provenance (where data came from and how it’s linked). **New to configuration?**See the [Setup Configuration Overview](https://docs.cognee.ai/setup-configuration/overview) for the complete workflow:install extras → create `.env` → choose providers → handle pruning. [​](https://docs.cognee.ai/setup-configuration/relational-databases#supported-providers) Supported Providers --------------------------------------------------------------------------------------------------------------- Cognee supports two relational database options: * **SQLite** — File-based database, works out of the box (default) * **Postgres** — Production-ready database for multi-process concurrency [​](https://docs.cognee.ai/setup-configuration/relational-databases#configuration) Configuration --------------------------------------------------------------------------------------------------- Environment Variables Set these environment variables in your `.env` file: * `DB_PROVIDER` — The database provider (sqlite, postgres) * `DB_NAME` — Database name * `DB_HOST` — Database host (Postgres only) * `DB_PORT` — Database port (Postgres only) * `DB_USERNAME` — Database username (Postgres only) * `DB_PASSWORD` — Database password (Postgres only) [​](https://docs.cognee.ai/setup-configuration/relational-databases#setup-guides) Setup Guides ------------------------------------------------------------------------------------------------- SQLite (Default) SQLite is file-based and requires no additional setup. It’s perfect for local development and single-user scenarios. Copy DB_PROVIDER="sqlite" DB_NAME="cognee_db" **Installation**: SQLite is included by default with Cognee. No additional installation required.**Data Location**: Data is stored under the Cognee system directory. You can override the root with `SYSTEM_ROOT_DIRECTORY` in your `.env` file. Postgres Postgres is recommended for production environments, multi-process concurrency, or when you need external hosting. Copy DB_PROVIDER="postgres" DB_NAME="cognee_db" DB_HOST="127.0.0.1" # use host.docker.internal when running inside Docker DB_PORT="5432" DB_USERNAME="cognee" DB_PASSWORD="cognee" **Installation**: Install the Postgres extras: Copy pip install "cognee[postgres]" # or for binary version pip install "cognee[postgres-binary]" **Docker Setup**: Use the built-in Postgres service: Copy docker compose --profile postgres up -d **Docker Networking**: When running Cognee in Docker and Postgres on your host, set: Copy DB_HOST="host.docker.internal" [​](https://docs.cognee.ai/setup-configuration/relational-databases#advanced-options) Advanced Options --------------------------------------------------------------------------------------------------------- Migration Configuration Use migration settings to extract data from a relational database and load it into the graph store. Copy MIGRATION_DB_PROVIDER="sqlite" # or postgres MIGRATION_DB_PATH="/path/to/migration/directory" MIGRATION_DB_NAME="migration_database.sqlite" # For Postgres migrations # MIGRATION_DB_HOST=127.0.0.1 # MIGRATION_DB_PORT=5432 # MIGRATION_DB_USERNAME=cognee # MIGRATION_DB_PASSWORD=cognee Backend Access Control Enable per-user dataset isolation for multi-tenant scenarios. Copy ENABLE_BACKEND_ACCESS_CONTROL="true" This feature is available for both SQLite and Postgres. [​](https://docs.cognee.ai/setup-configuration/relational-databases#troubleshooting) Troubleshooting ------------------------------------------------------------------------------------------------------- Common Issues **Postgres Connectivity**: Verify the database is listening on `DB_HOST:DB_PORT` and credentials are correct: Copy psql -h 127.0.0.1 -U cognee -d cognee_db **Docker Networking**: Use `host.docker.internal` for host-to-container access on macOS/Windows.**SQLite Concurrency**: SQLite has limited write concurrency; prefer Postgres for heavy multi-user workloads. [​](https://docs.cognee.ai/setup-configuration/relational-databases#when-to-use-each) When to Use Each --------------------------------------------------------------------------------------------------------- * **SQLite**: Local development, single-user applications, simple deployments * **Postgres**: Production environments, multi-user applications, external hosting, co-location with pgvector [Vector Stores\ -------------\ \ Configure vector databases for embedding storage](https://docs.cognee.ai/setup-configuration/vector-stores) [Graph Stores\ ------------\ \ Set up graph databases for knowledge graphs](https://docs.cognee.ai/setup-configuration/graph-stores) [Overview\ --------\ \ Return to setup configuration overview](https://docs.cognee.ai/setup-configuration/overview) Was this page helpful? YesNo [Previous](https://docs.cognee.ai/setup-configuration/embedding-providers) [Vector StoresConfigure vector databases for embedding storage and semantic search in Cognee\ \ Next](https://docs.cognee.ai/setup-configuration/vector-stores) ⌘I On this page * [Supported Providers](https://docs.cognee.ai/setup-configuration/relational-databases#supported-providers) * [Configuration](https://docs.cognee.ai/setup-configuration/relational-databases#configuration) * [Setup Guides](https://docs.cognee.ai/setup-configuration/relational-databases#setup-guides) * [Advanced Options](https://docs.cognee.ai/setup-configuration/relational-databases#advanced-options) * [Troubleshooting](https://docs.cognee.ai/setup-configuration/relational-databases#troubleshooting) * [When to Use Each](https://docs.cognee.ai/setup-configuration/relational-databases#when-to-use-each) --- # Embedding Providers - Cognee Documentation [Skip to main content](https://docs.cognee.ai/setup-configuration/embedding-providers#content-area) [Cognee Documentation home page![light logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20black.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=ea48b52be1df02b5909f780e6cd6856e)![dark logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20white.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=9f5bc18c4897c6e58b5cfa2b09bc079d)](https://docs.cognee.ai/) Search... ⌘K Search... Navigation Setup Configuration Embedding Providers [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) Embedding providers convert text into vector representations that enable semantic search. These vectors capture the meaning of text, allowing Cognee to find conceptually related content even when the wording is different. **New to configuration?**See the [Setup Configuration Overview](https://docs.cognee.ai/setup-configuration/overview) for the complete workflow:install extras → create `.env` → choose providers → handle pruning. [​](https://docs.cognee.ai/setup-configuration/embedding-providers#supported-providers) Supported Providers -------------------------------------------------------------------------------------------------------------- Cognee supports multiple embedding providers: * **OpenAI** — Text embedding models via OpenAI API (default) * **Azure OpenAI** — Text embedding models via Azure OpenAI Service * **Google Gemini** — Embedding models via Google AI * **Mistral** — Embedding models via Mistral AI * **Ollama** — Local embedding models via Ollama * **Fastembed** — CPU-friendly local embeddings * **Custom** — OpenAI-compatible embedding endpoints **LLM/Embedding Configuration**: If you configure only LLM or only embeddings, the other defaults to OpenAI. Ensure you have a working OpenAI API key, or configure both LLM and embeddings to avoid unexpected defaults. [​](https://docs.cognee.ai/setup-configuration/embedding-providers#configuration) Configuration -------------------------------------------------------------------------------------------------- Environment Variables Set these environment variables in your `.env` file: * `EMBEDDING_PROVIDER` — The provider to use (openai, gemini, mistral, ollama, fastembed, custom) * `EMBEDDING_MODEL` — The specific embedding model to use * `EMBEDDING_DIMENSIONS` — The vector dimension size (must match your vector store) * `EMBEDDING_API_KEY` — Your API key (falls back to `LLM_API_KEY` if not set) * `EMBEDDING_ENDPOINT` — Custom endpoint URL (for Azure, Ollama, or custom providers) * `EMBEDDING_API_VERSION` — API version (for Azure OpenAI) * `EMBEDDING_MAX_TOKENS` — Maximum tokens per request (optional) [​](https://docs.cognee.ai/setup-configuration/embedding-providers#provider-setup-guides) Provider Setup Guides ------------------------------------------------------------------------------------------------------------------ OpenAI (Default) OpenAI provides high-quality embeddings with good performance. Copy EMBEDDING_PROVIDER="openai" EMBEDDING_MODEL="openai/text-embedding-3-large" EMBEDDING_DIMENSIONS="3072" # Optional # EMBEDDING_API_KEY=sk-... # falls back to LLM_API_KEY if omitted # EMBEDDING_ENDPOINT=https://api.openai.com/v1 # EMBEDDING_API_VERSION= # EMBEDDING_MAX_TOKENS=8191 Azure OpenAI Embeddings Use Azure OpenAI Service for embeddings with your own deployment. Copy EMBEDDING_PROVIDER="openai" EMBEDDING_MODEL="azure/text-embedding-3-large" EMBEDDING_ENDPOINT="https://.cognitiveservices.azure.com/openai/deployments/text-embedding-3-large" EMBEDDING_API_KEY="az-..." EMBEDDING_API_VERSION="2023-05-15" EMBEDDING_DIMENSIONS="3072" Google Gemini Use Google’s embedding models for semantic search. Copy EMBEDDING_PROVIDER="gemini" EMBEDDING_MODEL="gemini/text-embedding-004" EMBEDDING_API_KEY="AIza..." EMBEDDING_DIMENSIONS="768" Mistral Use Mistral’s embedding models for high-quality vector representations. Copy EMBEDDING_PROVIDER="mistral" EMBEDDING_MODEL="mistral/mistral-embed" EMBEDDING_API_KEY="sk-mis-..." EMBEDDING_DIMENSIONS="1024" **Installation**: Install the required dependency: Copy pip install mistral-common[sentencepiece] Ollama (Local) Run embedding models locally with Ollama for privacy and cost control. Copy EMBEDDING_PROVIDER="ollama" EMBEDDING_MODEL="nomic-embed-text:latest" EMBEDDING_ENDPOINT="http://localhost:11434/api/embed" EMBEDDING_DIMENSIONS="768" HUGGINGFACE_TOKENIZER="nomic-ai/nomic-embed-text-v1.5" **Installation**: Install Ollama from [ollama.ai](https://ollama.ai/) and pull your desired embedding model: Copy ollama pull nomic-embed-text:latest Fastembed (Local) Use Fastembed for CPU-friendly local embeddings without GPU requirements. Copy EMBEDDING_PROVIDER="fastembed" EMBEDDING_MODEL="sentence-transformers/all-MiniLM-L6-v2" EMBEDDING_DIMENSIONS="384" **Installation**: Fastembed is included by default with Cognee.**Known Issues**: * As of September 2025, Fastembed requires Python < 3.13 (not compatible with Python 3.13+) Custom Providers Use OpenAI-compatible embedding endpoints from other providers. Copy EMBEDDING_PROVIDER="custom" EMBEDDING_MODEL="provider/your-embedding-model" EMBEDDING_ENDPOINT="https://your-endpoint.example.com/v1" EMBEDDING_API_KEY="provider-..." EMBEDDING_DIMENSIONS="" [​](https://docs.cognee.ai/setup-configuration/embedding-providers#advanced-options) Advanced Options -------------------------------------------------------------------------------------------------------- Rate Limiting Copy EMBEDDING_RATE_LIMIT_ENABLED="true" EMBEDDING_RATE_LIMIT_REQUESTS="10" EMBEDDING_RATE_LIMIT_INTERVAL="5" Testing and Development Copy # Mock embeddings for testing (returns zero vectors) MOCK_EMBEDDING="true" [​](https://docs.cognee.ai/setup-configuration/embedding-providers#important-notes) Important Notes ------------------------------------------------------------------------------------------------------ * **Dimension Consistency**: `EMBEDDING_DIMENSIONS` must match your vector store collection schema * **API Key Fallback**: If `EMBEDDING_API_KEY` is not set, Cognee uses `LLM_API_KEY` (except for custom providers) * **Tokenization**: For Ollama and Hugging Face models, set `HUGGINGFACE_TOKENIZER` for proper token counting * **Performance**: Local providers (Ollama, Fastembed) are slower but offer privacy and cost benefits [LLM Providers\ -------------\ \ Configure LLM providers for text generation](https://docs.cognee.ai/setup-configuration/llm-providers) [Vector Stores\ -------------\ \ Set up vector databases for embedding storage](https://docs.cognee.ai/setup-configuration/vector-stores) [Overview\ --------\ \ Return to setup configuration overview](https://docs.cognee.ai/setup-configuration/overview) Was this page helpful? YesNo [Previous](https://docs.cognee.ai/setup-configuration/structured-output-backends) [Relational DatabasesConfigure relational databases for metadata and state storage in Cognee\ \ Next](https://docs.cognee.ai/setup-configuration/relational-databases) ⌘I On this page * [Supported Providers](https://docs.cognee.ai/setup-configuration/embedding-providers#supported-providers) * [Configuration](https://docs.cognee.ai/setup-configuration/embedding-providers#configuration) * [Provider Setup Guides](https://docs.cognee.ai/setup-configuration/embedding-providers#provider-setup-guides) * [Advanced Options](https://docs.cognee.ai/setup-configuration/embedding-providers#advanced-options) * [Important Notes](https://docs.cognee.ai/setup-configuration/embedding-providers#important-notes) --- # ACL - Cognee Documentation [Skip to main content](https://docs.cognee.ai/core-concepts/permissions-system/acl#content-area) [Cognee Documentation home page![light logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20black.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=ea48b52be1df02b5909f780e6cd6856e)![dark logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20white.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=9f5bc18c4897c6e58b5cfa2b09bc079d)](https://docs.cognee.ai/) Search... ⌘K Search... Navigation Cognee Permissions System ACL [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) [​](https://docs.cognee.ai/core-concepts/permissions-system/acl#acl:-permission-storage-and-inheritance) ACL: Permission Storage and Inheritance =================================================================================================================================================== The ACL (Access Control List) system stores all permissions and handles permission checking at runtime. ACL entries are stored in the `acls` table, with each row linking a [principal](https://docs.cognee.ai/core-concepts/permissions-system/principals) to a [dataset](https://docs.cognee.ai/core-concepts/permissions-system/datasets) with a specific permission. **Runtime permission calculation** — The system doesn’t store “effective permissions” anywhere—it calculates them on demand by querying ACL entries. [​](https://docs.cognee.ai/core-concepts/permissions-system/acl#how-acl-works) How ACL Works ----------------------------------------------------------------------------------------------- When a [user](https://docs.cognee.ai/core-concepts/permissions-system/users) tries to access data, the system queries all relevant ACL entries and aggregates the permissions. The permission checking function `get_all_user_permission_datasets()` unions the [user](https://docs.cognee.ai/core-concepts/permissions-system/users) ’s direct permissions with those inherited from their [tenant](https://docs.cognee.ai/core-concepts/permissions-system/tenants) and [roles](https://docs.cognee.ai/core-concepts/permissions-system/roles) , combining all three sources: direct [user](https://docs.cognee.ai/core-concepts/permissions-system/users) permissions, [tenant](https://docs.cognee.ai/core-concepts/permissions-system/tenants) \-level permissions, and [role](https://docs.cognee.ai/core-concepts/permissions-system/roles) \-level permissions. This approach ensures permissions are always current and allows for complex permission inheritance without data duplication. [​](https://docs.cognee.ai/core-concepts/permissions-system/acl#acl-storage-schema) ACL Storage Schema --------------------------------------------------------------------------------------------------------- The ACL system uses a simple but powerful schema to store permissions: ACL Model Fields The ACL model defines what gets stored in the SQL database. The `acls` table contains: * `id`: Unique identifier (UUID primary key) * `principal_id`: References the [principal](https://docs.cognee.ai/core-concepts/permissions-system/principals) ([user](https://docs.cognee.ai/core-concepts/permissions-system/users) , [tenant](https://docs.cognee.ai/core-concepts/permissions-system/tenants) , or [role](https://docs.cognee.ai/core-concepts/permissions-system/roles) ) * `dataset_id`: References the [dataset](https://docs.cognee.ai/core-concepts/permissions-system/datasets) * `permission_id`: References the permission type * `created_at`: Timestamp when created * `updated_at`: Timestamp when last modified Permission Checking Functions * `get_all_user_permission_datasets(user, permission)`: Queries ACL entries and returns [datasets](https://docs.cognee.ai/core-concepts/permissions-system/datasets) the [user](https://docs.cognee.ai/core-concepts/permissions-system/users) can access * `give_permission_on_dataset(principal, dataset_id, permission)`: Creates or updates ACL entries [​](https://docs.cognee.ai/core-concepts/permissions-system/acl#permission-resolution-order) Permission Resolution Order --------------------------------------------------------------------------------------------------------------------------- The system evaluates permissions in a specific order: 1. **Direct [user](https://docs.cognee.ai/core-concepts/permissions-system/users) permissions** — Explicitly granted to the [user](https://docs.cognee.ai/core-concepts/permissions-system/users) 2. **[Role](https://docs.cognee.ai/core-concepts/permissions-system/roles) permissions** — Inherited through the [user](https://docs.cognee.ai/core-concepts/permissions-system/users) ’s role memberships 3. **[Tenant](https://docs.cognee.ai/core-concepts/permissions-system/tenants) permissions** — Inherited through the [user](https://docs.cognee.ai/core-concepts/permissions-system/users) ’s tenant membership This order allows for flexible permission management where more specific permissions can override broader ones. [​](https://docs.cognee.ai/core-concepts/permissions-system/acl#acl-operations) ACL Operations ------------------------------------------------------------------------------------------------- The ACL system supports several key operations: * **Grant permissions** — Add new ACL entries to grant access * **Revoke permissions** — Remove ACL entries to revoke access * **Check permissions** — Query ACL entries to determine access * **List permissions** — Get all permissions for a principal or dataset [​](https://docs.cognee.ai/core-concepts/permissions-system/acl#permission-inheritance) Permission Inheritance ----------------------------------------------------------------------------------------------------------------- The ACL system implements a three-tier inheritance model: * **User level** — Direct permissions granted to individual users * **Role level** — Permissions granted to roles, inherited by role members * **Tenant level** — Permissions granted to tenants, inherited by all tenant members Users receive the union of all permissions from these three sources, giving them the most permissive access available. [​](https://docs.cognee.ai/core-concepts/permissions-system/acl#performance-considerations) Performance Considerations ------------------------------------------------------------------------------------------------------------------------- The ACL system is designed for performance: * **Indexed queries** — Database indexes on principal\_id, dataset\_id, and permission\_id * **Efficient lookups** — Single query to get all permissions for a user * **Caching opportunities** — Permission results can be cached for frequently accessed datasets * **Batch operations** — Support for granting/revoking multiple permissions at once [​](https://docs.cognee.ai/core-concepts/permissions-system/acl#security-features) Security Features ------------------------------------------------------------------------------------------------------- The ACL system includes several security features: * **Immutable ownership** — Dataset ownership cannot be changed * **Permission validation** — All permission checks go through the ACL system * **Audit trail** — All permission changes are logged with timestamps * **Isolation** — Users can only access datasets they have permissions for [​](https://docs.cognee.ai/core-concepts/permissions-system/acl#troubleshooting) Troubleshooting --------------------------------------------------------------------------------------------------- Common ACL-related issues and solutions: * **Permission denied** — Check if user has required permission on the dataset * **Missing permissions** — Verify ACL entries exist for the principal and dataset * **Inheritance issues** — Check role and tenant memberships * **Performance problems** — Review database indexes and query patterns [Snippets\ --------\ \ See practical snippets of ACL operations](https://docs.cognee.ai/guides/permission-snippets) [Setup Configuration\ -------------------\ \ Learn how to configure ACL and multi-tenant mode](https://docs.cognee.ai/setup-configuration/permissions) Was this page helpful? YesNo [Previous](https://docs.cognee.ai/core-concepts/permissions-system/roles) [Permission SnippetsPractical code snippets and scenarios for Cognee's permission system\ \ Next](https://docs.cognee.ai/guides/permission-snippets) ⌘I On this page * [ACL: Permission Storage and Inheritance](https://docs.cognee.ai/core-concepts/permissions-system/acl#acl:-permission-storage-and-inheritance) * [How ACL Works](https://docs.cognee.ai/core-concepts/permissions-system/acl#how-acl-works) * [ACL Storage Schema](https://docs.cognee.ai/core-concepts/permissions-system/acl#acl-storage-schema) * [Permission Resolution Order](https://docs.cognee.ai/core-concepts/permissions-system/acl#permission-resolution-order) * [ACL Operations](https://docs.cognee.ai/core-concepts/permissions-system/acl#acl-operations) * [Permission Inheritance](https://docs.cognee.ai/core-concepts/permissions-system/acl#permission-inheritance) * [Performance Considerations](https://docs.cognee.ai/core-concepts/permissions-system/acl#performance-considerations) * [Security Features](https://docs.cognee.ai/core-concepts/permissions-system/acl#security-features) * [Troubleshooting](https://docs.cognee.ai/core-concepts/permissions-system/acl#troubleshooting) --- # Principals - Cognee Documentation [Skip to main content](https://docs.cognee.ai/core-concepts/permissions-system/principals#content-area) [Cognee Documentation home page![light logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20black.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=ea48b52be1df02b5909f780e6cd6856e)![dark logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20white.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=9f5bc18c4897c6e58b5cfa2b09bc079d)](https://docs.cognee.ai/) Search... ⌘K Search... Navigation Cognee Permissions System Principals [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) [​](https://docs.cognee.ai/core-concepts/permissions-system/principals#principals:-the-abstraction) Principals: The Abstraction ================================================================================================================================== A principal is any entity that can hold permissions in Cognee. This abstraction allows the permission system to work with different types of entities in a unified way, eliminating the need for separate permission systems for users, tenants, and roles. **Polymorphic design** — All principal types use the same permission mechanism, making the system flexible and consistent. [​](https://docs.cognee.ai/core-concepts/permissions-system/principals#principal-types) Principal Types ---------------------------------------------------------------------------------------------------------- There are three types of principals: * **[Users](https://docs.cognee.ai/core-concepts/permissions-system/users) ** — Individual people who interact with the system * **[Tenants](https://docs.cognee.ai/core-concepts/permissions-system/tenants) ** — Organizations or groups that contain users * **[Roles](https://docs.cognee.ai/core-concepts/permissions-system/roles) ** — Groups of users within a tenant All three types inherit from the same base Principal class, which means they can all be granted permissions on datasets using the same functions and mechanisms. [​](https://docs.cognee.ai/core-concepts/permissions-system/principals#how-principals-work-with-permissions) How Principals Work with Permissions ---------------------------------------------------------------------------------------------------------------------------------------------------- The system stores permissions by linking principals to datasets. You can grant permissions to any of the principals using built-in functions like `give_permission_on_dataset()` and `get_principal_datasets()`. When you grant a permission, you specify: * Which principal gets the permission * Which dataset the permission applies to * What type of permission (read, write, delete, share) This unified approach means you can grant permissions to: * Individual [users](https://docs.cognee.ai/core-concepts/permissions-system/users) for personal access * [Tenants](https://docs.cognee.ai/core-concepts/permissions-system/tenants) for organization-wide access * [Roles](https://docs.cognee.ai/core-concepts/permissions-system/roles) for team-based access within a tenant Principal Model Fields The base Principal model defines what gets stored in the SQL database. The `principals` table contains: * `id`: Unique identifier (UUID primary key) * `created_at`: Timestamp when created * `updated_at`: Timestamp when last modified * `type`: Discriminator field for polymorphic inheritance Each principal type (User, Tenant, Role) has its own table that references the principals table via foreign key, storing additional fields specific to that type. Permission Storage Schema The permission system links principals to datasets with permissions: * `principal_id`: References the principal ([user](https://docs.cognee.ai/core-concepts/permissions-system/users) , [tenant](https://docs.cognee.ai/core-concepts/permissions-system/tenants) , or [role](https://docs.cognee.ai/core-concepts/permissions-system/roles) ) * `dataset_id`: References the [dataset](https://docs.cognee.ai/core-concepts/permissions-system/datasets) * `permission_id`: References the permission type This many-to-many relationship allows flexible permission management across different entity types. Key Functions * `give_permission_on_dataset(principal, dataset_id, permission)`: Writes a single ACL row (or reuses an existing one) so a [user](https://docs.cognee.ai/core-concepts/permissions-system/users) , [tenant](https://docs.cognee.ai/core-concepts/permissions-system/tenants) , or [role](https://docs.cognee.ai/core-concepts/permissions-system/roles) gains read, write, delete, or share on that dataset. It’s the building block used after dataset creation or whenever access is delegated. * `get_principal_datasets(principal, permission)`: Queries those ACL entries (and the related dataset records) so you can list every dataset where that same principal holds the requested permission—handy for permission checks or UI listings. [​](https://docs.cognee.ai/core-concepts/permissions-system/principals#permission-inheritance) Permission Inheritance ------------------------------------------------------------------------------------------------------------------------ The principal system supports hierarchical permission inheritance: 1. **Direct permissions** — Explicitly granted to a specific principal 2. **[Role permissions](https://docs.cognee.ai/core-concepts/permissions-system/roles) ** — Inherited through role memberships 3. **[Tenant permissions](https://docs.cognee.ai/core-concepts/permissions-system/tenants) ** — Inherited through tenant membership When a [user](https://docs.cognee.ai/core-concepts/permissions-system/users) tries to access data, the system evaluates their effective permissions by combining all three sources. This allows for flexible access control patterns: * Grant broad permissions at the [tenant](https://docs.cognee.ai/core-concepts/permissions-system/tenants) level * Refine access with [role](https://docs.cognee.ai/core-concepts/permissions-system/roles) \-specific permissions * Override with direct [user](https://docs.cognee.ai/core-concepts/permissions-system/users) permissions when needed [​](https://docs.cognee.ai/core-concepts/permissions-system/principals#benefits-of-the-principal-system) Benefits of the Principal System -------------------------------------------------------------------------------------------------------------------------------------------- * **Unified interface** — Same functions work for all principal types * **Flexible access control** — Support for individual, team, and organization-level permissions * **Scalable management** — Easy to add new principal types or modify existing ones * **Consistent behavior** — All principals follow the same permission rules and patterns [Users\ -----\ \ Learn about individual users and authentication](https://docs.cognee.ai/core-concepts/permissions-system/users) [Tenants\ -------\ \ Understand organization-level access control](https://docs.cognee.ai/core-concepts/permissions-system/tenants) Was this page helpful? YesNo [Previous](https://docs.cognee.ai/core-concepts/permissions-system/datasets) [UsersIndividual users and authentication in Cognee's permission system\ \ Next](https://docs.cognee.ai/core-concepts/permissions-system/users) ⌘I On this page * [Principals: The Abstraction](https://docs.cognee.ai/core-concepts/permissions-system/principals#principals:-the-abstraction) * [Principal Types](https://docs.cognee.ai/core-concepts/permissions-system/principals#principal-types) * [How Principals Work with Permissions](https://docs.cognee.ai/core-concepts/permissions-system/principals#how-principals-work-with-permissions) * [Permission Inheritance](https://docs.cognee.ai/core-concepts/permissions-system/principals#permission-inheritance) * [Benefits of the Principal System](https://docs.cognee.ai/core-concepts/permissions-system/principals#benefits-of-the-principal-system) --- # Tenants - Cognee Documentation [Skip to main content](https://docs.cognee.ai/core-concepts/permissions-system/tenants#content-area) [Cognee Documentation home page![light logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20black.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=ea48b52be1df02b5909f780e6cd6856e)![dark logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20white.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=9f5bc18c4897c6e58b5cfa2b09bc079d)](https://docs.cognee.ai/) Search... ⌘K Search... Navigation Cognee Permissions System Tenants [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) [​](https://docs.cognee.ai/core-concepts/permissions-system/tenants#tenants) Tenants ======================================================================================= A tenant represents an organization or group. [Tenants](https://docs.cognee.ai/core-concepts/permissions-system/tenants) contain [users](https://docs.cognee.ai/core-concepts/permissions-system/users) and can be granted permissions on [datasets](https://docs.cognee.ai/core-concepts/permissions-system/datasets) , which apply to all members. This enables organization-wide access control and simplifies permission management for teams. **Tenant-level permissions** — When a tenant is granted a permission on a dataset, all users in that tenant automatically inherit that permission. [​](https://docs.cognee.ai/core-concepts/permissions-system/tenants#tenant-concept) Tenant Concept ----------------------------------------------------------------------------------------------------- [Tenants](https://docs.cognee.ai/core-concepts/permissions-system/tenants) are created by [users](https://docs.cognee.ai/core-concepts/permissions-system/users) who become the tenant owner. The owner can add other [users](https://docs.cognee.ai/core-concepts/permissions-system/users) to the tenant. [Users](https://docs.cognee.ai/core-concepts/permissions-system/users) can belong to at most one tenant, but [tenants](https://docs.cognee.ai/core-concepts/permissions-system/tenants) can contain multiple [users](https://docs.cognee.ai/core-concepts/permissions-system/users) . [​](https://docs.cognee.ai/core-concepts/permissions-system/tenants#tenant-level-permissions) Tenant-Level Permissions ------------------------------------------------------------------------------------------------------------------------- When a [tenant](https://docs.cognee.ai/core-concepts/permissions-system/tenants) is granted a permission on a [dataset](https://docs.cognee.ai/core-concepts/permissions-system/datasets) , all [users](https://docs.cognee.ai/core-concepts/permissions-system/users) in that tenant automatically inherit that permission. This happens through the permission checking mechanism: `get_all_user_permission_datasets()` unions the [user](https://docs.cognee.ai/core-concepts/permissions-system/users) ’s direct permissions with their [tenant](https://docs.cognee.ai/core-concepts/permissions-system/tenants) ’s permissions. [Tenants](https://docs.cognee.ai/core-concepts/permissions-system/tenants) start with zero permissions. You can leave the tenant principal empty and manage access purely through individual [user](https://docs.cognee.ai/core-concepts/permissions-system/users) permissions, or grant tenant-wide permissions for organization-wide resources. [​](https://docs.cognee.ai/core-concepts/permissions-system/tenants#permission-inheritance) Permission Inheritance --------------------------------------------------------------------------------------------------------------------- Tenant-level grants are blanket: once a [dataset](https://docs.cognee.ai/core-concepts/permissions-system/datasets) permission is assigned to the tenant principal, every [user](https://docs.cognee.ai/core-concepts/permissions-system/users) whose `tenant_id` matches inherits it. [Users](https://docs.cognee.ai/core-concepts/permissions-system/users) can also receive direct permissions that differ from the tenant defaults, giving you flexibility to customize access for specific [users](https://docs.cognee.ai/core-concepts/permissions-system/users) within the same tenant. Tenant Model Fields The Tenant model defines what gets stored in the SQL database. The `tenants` table contains: * `id`: Unique identifier (UUID primary key, references principals.id) * `name`: Human-readable name (unique) * `owner_id`: ID of the [user](https://docs.cognee.ai/core-concepts/permissions-system/users) who created the tenant Tenant Creation * `create_tenant(tenant_name, user_id)`: Creates a new tenant with the specified [user](https://docs.cognee.ai/core-concepts/permissions-system/users) as owner * `add_user_to_tenant(user_id, tenant_id, owner_id)`: Adds an existing [user](https://docs.cognee.ai/core-concepts/permissions-system/users) to a tenant (owner only) Limitations * [Users](https://docs.cognee.ai/core-concepts/permissions-system/users) without a tenant exist but are isolated * API endpoints for tenant management [​](https://docs.cognee.ai/core-concepts/permissions-system/tenants#tenant-management) Tenant Management ----------------------------------------------------------------------------------------------------------- Tenant owners can: * Add [users](https://docs.cognee.ai/core-concepts/permissions-system/users) to the tenant * Remove [users](https://docs.cognee.ai/core-concepts/permissions-system/users) from the tenant * Grant permissions to the tenant principal * Manage tenant-level access to [datasets](https://docs.cognee.ai/core-concepts/permissions-system/datasets) [​](https://docs.cognee.ai/core-concepts/permissions-system/tenants#use-cases) Use Cases ------------------------------------------------------------------------------------------- Tenants are ideal for: * **Organization-wide access** — Grant broad permissions to all team members * **Department-level isolation** — Keep different departments’ data separate * **Project-based grouping** — Organize users around specific projects or initiatives * **Scalable permission management** — Avoid granting individual permissions to many users [​](https://docs.cognee.ai/core-concepts/permissions-system/tenants#data-isolation) Data Isolation ----------------------------------------------------------------------------------------------------- Each tenant’s data is completely isolated: * **Database separation** — Each user’s data is stored in their own directory * **Permission boundaries** — [Users](https://docs.cognee.ai/core-concepts/permissions-system/users) can only access [datasets](https://docs.cognee.ai/core-concepts/permissions-system/datasets) they have permissions for * **No cross-tenant access** — Data from one tenant cannot be accessed by [users](https://docs.cognee.ai/core-concepts/permissions-system/users) from another tenant [​](https://docs.cognee.ai/core-concepts/permissions-system/tenants#best-practices) Best Practices ----------------------------------------------------------------------------------------------------- * **Start with tenant-level permissions** — Grant broad access at the tenant level * **Refine with [user](https://docs.cognee.ai/core-concepts/permissions-system/users) permissions** — Override tenant defaults for specific [users](https://docs.cognee.ai/core-concepts/permissions-system/users) when needed * **Use [roles](https://docs.cognee.ai/core-concepts/permissions-system/roles) for granular control** — Create [roles](https://docs.cognee.ai/core-concepts/permissions-system/roles) within tenants for more specific access patterns * **Regular permission audits** — Review and update permissions as team structure changes [Roles\ -----\ \ Learn about role-based permissions within tenants](https://docs.cognee.ai/core-concepts/permissions-system/roles) [ACL\ ---\ \ Understand how permissions are stored and checked](https://docs.cognee.ai/core-concepts/permissions-system/acl) Was this page helpful? YesNo [Previous](https://docs.cognee.ai/core-concepts/permissions-system/users) [RolesRole-based permissions within tenants for granular access control\ \ Next](https://docs.cognee.ai/core-concepts/permissions-system/roles) ⌘I On this page * [Tenants](https://docs.cognee.ai/core-concepts/permissions-system/tenants#tenants) * [Tenant Concept](https://docs.cognee.ai/core-concepts/permissions-system/tenants#tenant-concept) * [Tenant-Level Permissions](https://docs.cognee.ai/core-concepts/permissions-system/tenants#tenant-level-permissions) * [Permission Inheritance](https://docs.cognee.ai/core-concepts/permissions-system/tenants#permission-inheritance) * [Tenant Management](https://docs.cognee.ai/core-concepts/permissions-system/tenants#tenant-management) * [Use Cases](https://docs.cognee.ai/core-concepts/permissions-system/tenants#use-cases) * [Data Isolation](https://docs.cognee.ai/core-concepts/permissions-system/tenants#data-isolation) * [Best Practices](https://docs.cognee.ai/core-concepts/permissions-system/tenants#best-practices) --- # Overview - Cognee Documentation [Skip to main content](https://docs.cognee.ai/core-concepts/permissions-system/overview#content-area) [Cognee Documentation home page![light logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20black.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=ea48b52be1df02b5909f780e6cd6856e)![dark logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20white.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=9f5bc18c4897c6e58b5cfa2b09bc079d)](https://docs.cognee.ai/) Search... ⌘K Search... Navigation Cognee Permissions System Overview [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) [​](https://docs.cognee.ai/core-concepts/permissions-system/overview#cognee-permissions-system) Cognee Permissions System ============================================================================================================================ The Cognee permission system manages access to data through an access control architecture. This system provides data isolation and access control through dataset-scoped permissions and per-dataset storage, enabling multiple users or organizations to use the same Cognee instance while keeping their data completely separate. **Enable Backend Access Control (EBAC)** is the configuration flag that activates this multi-tenant mode, enforcing user authentication and complete data isolation. [​](https://docs.cognee.ai/core-concepts/permissions-system/overview#core-components) Core Components -------------------------------------------------------------------------------------------------------- The permission system is built around several key concepts: * **Dataset** — The basic unit of data in Cognee. All documents and their processed knowledge graphs belong to a dataset. Permissions are always defined at the dataset level. See [Datasets](https://docs.cognee.ai/core-concepts/permissions-system/datasets) for details. * **Principal** — Any entity that can hold permissions. Principals come in three forms: [Users](https://docs.cognee.ai/core-concepts/permissions-system/users) , [Tenants](https://docs.cognee.ai/core-concepts/permissions-system/tenants) , and [Roles](https://docs.cognee.ai/core-concepts/permissions-system/roles) . This unified design supports flexible access control across individuals and organizations. * **User** — An individual who creates and interacts with datasets. Users can own datasets and be granted permissions on others. Each user belongs to at most one tenant. * **Tenant** — An organization or group. Tenants contain users and can be granted permissions on datasets, which apply to all members. * **Role** — A group of users within a tenant. Roles can also be granted dataset permissions, which apply to their members. * **ACL** — The Access Control List records all permission assignments. Each entry links a principal to a dataset with a specific permission type. See [ACL](https://docs.cognee.ai/core-concepts/permissions-system/acl) for details. [​](https://docs.cognee.ai/core-concepts/permissions-system/overview#permission-types) Permission Types ---------------------------------------------------------------------------------------------------------- There are four types of permissions that can be granted on datasets: * **Read** — View documents and query the knowledge graph * **Write** — Add, modify, or remove documents and data * **Delete** — Remove the entire dataset * **Share** — Grant permissions to other principals [​](https://docs.cognee.ai/core-concepts/permissions-system/overview#how-it-works) How It Works -------------------------------------------------------------------------------------------------- When `ENABLE_BACKEND_ACCESS_CONTROL` is set to true, Cognee runs in access control mode: * **Authentication becomes mandatory** (even if `REQUIRE_AUTHENTICATION=false`) * **Data isolation is enforced** at the user + dataset level for graph and vector stores * **Database routing is automatic** — Kùzu (graph) and LanceDB (vector) are configured per request via context variables * **Supported databases**: SQLite/Postgres (relational), LanceDB (vector), Kùzu (graph) * **Custom providers are ignored** — EBAC enforces Kùzu and LanceDB regardless of user configuration See [Setup Configuration](https://docs.cognee.ai/setup-configuration/permissions) for configuration details. [​](https://docs.cognee.ai/core-concepts/permissions-system/overview#permission-resolution) Permission Resolution -------------------------------------------------------------------------------------------------------------------- When a user tries to access data, the system evaluates their effective permissions by combining: 1. **Direct user permissions** — explicitly granted to the user 2. **Role permissions** — inherited through the user’s role memberships 3. **Tenant permissions** — inherited through the user’s tenant membership The system doesn’t store “effective permissions” anywhere—it calculates them on demand by querying ACL entries. This approach ensures permissions are always current and allows for complex permission inheritance without data duplication. [​](https://docs.cognee.ai/core-concepts/permissions-system/overview#data-storage-layout) Data Storage Layout ---------------------------------------------------------------------------------------------------------------- When EBAC is enabled, Cognee automatically organizes data by user and dataset: **Filesystem layout**: Copy .cognee_system/databases// ├── .pkl # Kùzu graph database └── .lance.db/ # LanceDB vector database .data_storage// └── ... # Raw and processed files **Key points:** * Each user gets their own database directory * Each dataset gets its own database files within the user’s directory * File storage is organized by tenant (if user belongs to one) or by user ID * This structure prevents any cross-user data access at the filesystem level [Datasets\ --------\ \ Learn about datasets as the core unit of data](https://docs.cognee.ai/core-concepts/permissions-system/datasets) [Setup Configuration\ -------------------\ \ Configure multi-tenant mode and access control](https://docs.cognee.ai/setup-configuration/permissions) Was this page helpful? YesNo [Previous](https://docs.cognee.ai/core-concepts/further-concepts/ontologies) [DatasetsThe core unit of data in Cognee's permission system\ \ Next](https://docs.cognee.ai/core-concepts/permissions-system/datasets) ⌘I On this page * [Cognee Permissions System](https://docs.cognee.ai/core-concepts/permissions-system/overview#cognee-permissions-system) * [Core Components](https://docs.cognee.ai/core-concepts/permissions-system/overview#core-components) * [Permission Types](https://docs.cognee.ai/core-concepts/permissions-system/overview#permission-types) * [How It Works](https://docs.cognee.ai/core-concepts/permissions-system/overview#how-it-works) * [Permission Resolution](https://docs.cognee.ai/core-concepts/permissions-system/overview#permission-resolution) * [Data Storage Layout](https://docs.cognee.ai/core-concepts/permissions-system/overview#data-storage-layout) --- # Roles - Cognee Documentation [Skip to main content](https://docs.cognee.ai/core-concepts/permissions-system/roles#content-area) [Cognee Documentation home page![light logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20black.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=ea48b52be1df02b5909f780e6cd6856e)![dark logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20white.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=9f5bc18c4897c6e58b5cfa2b09bc079d)](https://docs.cognee.ai/) Search... ⌘K Search... Navigation Cognee Permissions System Roles [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) [​](https://docs.cognee.ai/core-concepts/permissions-system/roles#roles) Roles ================================================================================= A role is a group of [users](https://docs.cognee.ai/core-concepts/permissions-system/users) within a [tenant](https://docs.cognee.ai/core-concepts/permissions-system/tenants) . [Roles](https://docs.cognee.ai/core-concepts/permissions-system/roles) can be granted permissions on [datasets](https://docs.cognee.ai/core-concepts/permissions-system/datasets) , which apply to their members. This enables fine-grained access control within organizations and makes it easier to manage permissions for different teams. **Role-based permissions** — When a role is granted a permission on a dataset, all users assigned to that role inherit that permission. [​](https://docs.cognee.ai/core-concepts/permissions-system/roles#role-concept) Role Concept ----------------------------------------------------------------------------------------------- [Roles](https://docs.cognee.ai/core-concepts/permissions-system/roles) are created by [tenant](https://docs.cognee.ai/core-concepts/permissions-system/tenants) owners and are scoped to that specific [tenant](https://docs.cognee.ai/core-concepts/permissions-system/tenants) . The role belongs to exactly one [tenant](https://docs.cognee.ai/core-concepts/permissions-system/tenants) as soon as it’s created. Because of that foreign-key link, a role can’t be moved or shared with another [tenant](https://docs.cognee.ai/core-concepts/permissions-system/tenants) ; you would need to create a new role under the other [tenant](https://docs.cognee.ai/core-concepts/permissions-system/tenants) instead. [Users](https://docs.cognee.ai/core-concepts/permissions-system/users) can be assigned to multiple [roles](https://docs.cognee.ai/core-concepts/permissions-system/roles) within their [tenant](https://docs.cognee.ai/core-concepts/permissions-system/tenants) , and [roles](https://docs.cognee.ai/core-concepts/permissions-system/roles) can contain multiple [users](https://docs.cognee.ai/core-concepts/permissions-system/users) . This many-to-many relationship allows flexible permission management across teams. [​](https://docs.cognee.ai/core-concepts/permissions-system/roles#role-based-permissions) Role-Based Permissions ------------------------------------------------------------------------------------------------------------------- When a [role](https://docs.cognee.ai/core-concepts/permissions-system/roles) is granted a permission on a [dataset](https://docs.cognee.ai/core-concepts/permissions-system/datasets) , all [users](https://docs.cognee.ai/core-concepts/permissions-system/users) assigned to that role inherit that permission. [Users](https://docs.cognee.ai/core-concepts/permissions-system/users) receive the union of their direct permissions, [tenant](https://docs.cognee.ai/core-concepts/permissions-system/tenants) \-level permissions, and [role](https://docs.cognee.ai/core-concepts/permissions-system/roles) \-level permissions. [Roles](https://docs.cognee.ai/core-concepts/permissions-system/roles) allow you to create permission groups like “editors” or “viewers” within a [tenant](https://docs.cognee.ai/core-concepts/permissions-system/tenants) , making it easier to manage access for different teams without granting permissions to individual [users](https://docs.cognee.ai/core-concepts/permissions-system/users) . Role Model Fields The Role model defines what gets stored in the SQL database. The `roles` table contains: * `id`: Unique identifier (UUID primary key, references principals.id) * `name`: Human-readable name (unique within tenant) * `tenant_id`: ID of the tenant this role belongs to (required) Role Creation * `create_role(role_name, owner_id)`: Creates a new role (tenant owner only) * `add_user_to_role(user_id, role_id, owner_id)`: Assigns a user to a role (tenant owner only) Limitations * Roles are tenant-scoped and cannot cross tenants * API endpoints for role management [​](https://docs.cognee.ai/core-concepts/permissions-system/roles#role-management) Role Management ----------------------------------------------------------------------------------------------------- Tenant owners can: * Create roles within their tenant * Assign users to roles * Remove users from roles * Grant permissions to roles * Delete roles (when no longer needed) [​](https://docs.cognee.ai/core-concepts/permissions-system/roles#common-role-patterns) Common Role Patterns --------------------------------------------------------------------------------------------------------------- Roles are typically organized around job functions or responsibilities: * **Editors** — Can modify content and run cognify operations * **Viewers** — Can only read and search data * **Administrators** — Can manage permissions and users * **Project Managers** — Can access specific project datasets * **Reviewers** — Can read and provide feedback on content [​](https://docs.cognee.ai/core-concepts/permissions-system/roles#permission-inheritance-hierarchy) Permission Inheritance Hierarchy --------------------------------------------------------------------------------------------------------------------------------------- Users receive permissions through a three-level hierarchy: 1. **Direct permissions** — Explicitly granted to the user 2. **Role permissions** — Inherited through role memberships 3. **Tenant permissions** — Inherited through tenant membership The system calculates effective permissions by combining all three sources, giving users the most permissive access available to them. [​](https://docs.cognee.ai/core-concepts/permissions-system/roles#best-practices) Best Practices --------------------------------------------------------------------------------------------------- * **Create meaningful role names** — Use descriptive names that reflect the role’s purpose * **Keep roles focused** — Each role should have a clear, specific purpose * **Regular role reviews** — Periodically review and update role assignments * **Document role purposes** — Keep clear documentation of what each role is for * **Principle of least privilege** — Grant only the minimum permissions necessary [​](https://docs.cognee.ai/core-concepts/permissions-system/roles#role-vs-tenant-permissions) Role vs Tenant Permissions --------------------------------------------------------------------------------------------------------------------------- * **Tenant permissions** — Broad, organization-wide access * **Role permissions** — Specific, team-based access within the tenant * **Direct permissions** — Individual, user-specific access This three-tier system allows for flexible and scalable permission management. [ACL\ ---\ \ Learn how permissions are stored and checked](https://docs.cognee.ai/core-concepts/permissions-system/acl) [Snippets\ --------\ \ See practical snippets of role-based permissions](https://docs.cognee.ai/guides/permission-snippets) Was this page helpful? YesNo [Previous](https://docs.cognee.ai/core-concepts/permissions-system/tenants) [ACLAccess Control List system for permission storage and inheritance in Cognee\ \ Next](https://docs.cognee.ai/core-concepts/permissions-system/acl) ⌘I On this page * [Roles](https://docs.cognee.ai/core-concepts/permissions-system/roles#roles) * [Role Concept](https://docs.cognee.ai/core-concepts/permissions-system/roles#role-concept) * [Role-Based Permissions](https://docs.cognee.ai/core-concepts/permissions-system/roles#role-based-permissions) * [Role Management](https://docs.cognee.ai/core-concepts/permissions-system/roles#role-management) * [Common Role Patterns](https://docs.cognee.ai/core-concepts/permissions-system/roles#common-role-patterns) * [Permission Inheritance Hierarchy](https://docs.cognee.ai/core-concepts/permissions-system/roles#permission-inheritance-hierarchy) * [Best Practices](https://docs.cognee.ai/core-concepts/permissions-system/roles#best-practices) * [Role vs Tenant Permissions](https://docs.cognee.ai/core-concepts/permissions-system/roles#role-vs-tenant-permissions) --- # Users - Cognee Documentation [Skip to main content](https://docs.cognee.ai/core-concepts/permissions-system/users#content-area) [Cognee Documentation home page![light logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20black.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=ea48b52be1df02b5909f780e6cd6856e)![dark logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20white.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=9f5bc18c4897c6e58b5cfa2b09bc079d)](https://docs.cognee.ai/) Search... ⌘K Search... Navigation Cognee Permissions System Users [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) [​](https://docs.cognee.ai/core-concepts/permissions-system/users#users) Users ================================================================================= Users are the most common type of principal and the primary way people access the system. They authenticate through email and password and can own datasets, be granted permissions on others, and belong to at most one tenant. **Default user behavior** — When no user is specified, Cognee uses a default user with email “[default\_user@example.com](mailto:default_user@example.com) ” for development and testing. [​](https://docs.cognee.ai/core-concepts/permissions-system/users#user-authentication) User Authentication ------------------------------------------------------------------------------------------------------------- Users authenticate through email and password. When no user is specified, Cognee uses a default user with email “[default\_user@example.com](mailto:default_user@example.com) ” for development and testing. A user without a tenant can still use the system but operates in isolation. [​](https://docs.cognee.ai/core-concepts/permissions-system/users#user-management) User Management ----------------------------------------------------------------------------------------------------- Users can: * Own [datasets](https://docs.cognee.ai/core-concepts/permissions-system/datasets) and be granted permissions on others * Belong to at most one [tenant](https://docs.cognee.ai/core-concepts/permissions-system/tenants) * Have direct permissions on [datasets](https://docs.cognee.ai/core-concepts/permissions-system/datasets) * Inherit permissions from their [tenant](https://docs.cognee.ai/core-concepts/permissions-system/tenants) and [roles](https://docs.cognee.ai/core-concepts/permissions-system/roles) User Model Fields The User model defines what gets stored in the SQL database. The `users` table contains: * `id`: Unique identifier (UUID primary key, references principals.id) * `email`: User’s email address (unique) * `hashed_password`: Encrypted password * `tenant_id`: ID of the [tenant](https://docs.cognee.ai/core-concepts/permissions-system/tenants) the user belongs to (nullable) * `is_active`: Whether the user account is active * `is_verified`: Whether the user’s email is verified * `is_superuser`: Whether the user has superuser privileges User Creation * `create_user(email, password, tenant_id=None, is_superuser=False)`: Creates a new user with specified credentials * Default user behavior: System creates “[default\_user@example.com](mailto:default_user@example.com) ” if no user exists Environment Variables * `DEFAULT_USER_EMAIL`: Override default user email (default: “[default\_user@example.com](mailto:default_user@example.com) ”) * `DEFAULT_USER_PASSWORD`: Override default user password (default: “default\_password”) * `REQUIRE_AUTHENTICATION`: Enforce authentication on HTTP endpoints (default: “false”) * `FASTAPI_USERS_RESET_PASSWORD_TOKEN_SECRET`: Secret for password reset tokens * `FASTAPI_USERS_VERIFICATION_TOKEN_SECRET`: Secret for email verification tokens Limitations * A user can belong to at most one tenant * Users without a tenant exist but are isolated * API endpoints for user management and authentication [​](https://docs.cognee.ai/core-concepts/permissions-system/users#user-permissions) User Permissions ------------------------------------------------------------------------------------------------------- Users can receive permissions in three ways: 1. **Direct permissions** — Explicitly granted to the user 2. **[Tenant permissions](https://docs.cognee.ai/core-concepts/permissions-system/tenants) ** — Inherited through [tenant](https://docs.cognee.ai/core-concepts/permissions-system/tenants) membership 3. **[Role permissions](https://docs.cognee.ai/core-concepts/permissions-system/roles) ** — Inherited through [role](https://docs.cognee.ai/core-concepts/permissions-system/roles) memberships The system calculates effective permissions by combining all three sources, giving users the union of their direct permissions, [tenant](https://docs.cognee.ai/core-concepts/permissions-system/tenants) \-level permissions, and [role](https://docs.cognee.ai/core-concepts/permissions-system/roles) \-level permissions. [​](https://docs.cognee.ai/core-concepts/permissions-system/users#user-isolation) User Isolation --------------------------------------------------------------------------------------------------- When `ENABLE_BACKEND_ACCESS_CONTROL=true`, each user’s data is completely isolated: * **Database routing is automatic** — Kùzu (graph) and LanceDB (vector) are configured per request via context variables * **Filesystem isolation** — Each user gets their own database directory * **No cross-user access** — Users can only access [datasets](https://docs.cognee.ai/core-concepts/permissions-system/datasets) they have explicit permissions for [​](https://docs.cognee.ai/core-concepts/permissions-system/users#superuser-privileges) Superuser Privileges --------------------------------------------------------------------------------------------------------------- Users with `is_superuser=True` have additional privileges: * Can manage other [users](https://docs.cognee.ai/core-concepts/permissions-system/users) , [tenants](https://docs.cognee.ai/core-concepts/permissions-system/tenants) , and [roles](https://docs.cognee.ai/core-concepts/permissions-system/roles) * Can access all [datasets](https://docs.cognee.ai/core-concepts/permissions-system/datasets) regardless of permissions * Can perform administrative operations **Production Security** — Superuser privileges should be carefully managed in production environments. [Tenants\ -------\ \ Learn about organization-level access control](https://docs.cognee.ai/core-concepts/permissions-system/tenants) [Roles\ -----\ \ Understand role-based permissions within tenants](https://docs.cognee.ai/core-concepts/permissions-system/roles) Was this page helpful? YesNo [Previous](https://docs.cognee.ai/core-concepts/permissions-system/principals) [TenantsOrganization-level access control and permission inheritance in Cognee\ \ Next](https://docs.cognee.ai/core-concepts/permissions-system/tenants) ⌘I On this page * [Users](https://docs.cognee.ai/core-concepts/permissions-system/users#users) * [User Authentication](https://docs.cognee.ai/core-concepts/permissions-system/users#user-authentication) * [User Management](https://docs.cognee.ai/core-concepts/permissions-system/users#user-management) * [User Permissions](https://docs.cognee.ai/core-concepts/permissions-system/users#user-permissions) * [User Isolation](https://docs.cognee.ai/core-concepts/permissions-system/users#user-isolation) * [Superuser Privileges](https://docs.cognee.ai/core-concepts/permissions-system/users#superuser-privileges) --- # Qdrant - Cognee Documentation [Skip to main content](https://docs.cognee.ai/setup-configuration/community-maintained/qdrant#content-area) [Cognee Documentation home page![light logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20black.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=ea48b52be1df02b5909f780e6cd6856e)![dark logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20white.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=9f5bc18c4897c6e58b5cfa2b09bc079d)](https://docs.cognee.ai/) Search... ⌘K Search... Navigation Cognee Community Adapters Qdrant [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) Qdrant is a vector search engine that stores embeddings and performs similarity searches. It supports both cloud-hosted and self-hosted deployments. Cognee can use Qdrant as a [vector store](https://docs.cognee.ai/setup-configuration/vector-stores) backend through this [community-maintained](https://docs.cognee.ai/setup-configuration/community-maintained/overview) [adapter](https://github.com/topoteretes/cognee-community/tree/main/packages/vector/qdrant) . [​](https://docs.cognee.ai/setup-configuration/community-maintained/qdrant#installation) Installation -------------------------------------------------------------------------------------------------------- This adapter is a separate package from core Cognee. Before installing, complete the [Cognee installation](https://docs.cognee.ai/getting-started/installation) and ensure your environment is configured with [LLM and embedding providers](https://docs.cognee.ai/setup-configuration/overview) . After that, install the adapter package: Copy uv pip install cognee-community-vector-adapter-qdrant [​](https://docs.cognee.ai/setup-configuration/community-maintained/qdrant#configuration) Configuration ---------------------------------------------------------------------------------------------------------- * Docker (Local) * Qdrant Cloud Run a local Qdrant instance: Copy docker run -p 6333:6333 -p 6334:6334 \ -v "$(pwd)/qdrant_storage:/qdrant/storage:z" \ qdrant/qdrant Configure in Python: Copy from cognee_community_vector_adapter_qdrant import register from cognee import config register() config.set_vector_db_config({ "vector_db_provider": "qdrant", "vector_db_url": "http://localhost:6333", "vector_db_key": "", }) Or via environment variables: Copy VECTOR_DB_PROVIDER="qdrant" VECTOR_DB_URL="http://localhost:6333" VECTOR_DB_KEY="" [​](https://docs.cognee.ai/setup-configuration/community-maintained/qdrant#important-notes) Important Notes -------------------------------------------------------------------------------------------------------------- Adapter Registration Import and call `register()` from the adapter package before using Qdrant with Cognee. This registers the adapter with Cognee’s provider system. Embedding Dimensions Ensure `EMBEDDING_DIMENSIONS` matches your embedding model. See [Embedding Providers](https://docs.cognee.ai/setup-configuration/embedding-providers) for configuration.Changing dimensions requires recreating collections or running `prune.prune_system()`. [​](https://docs.cognee.ai/setup-configuration/community-maintained/qdrant#resources) Resources -------------------------------------------------------------------------------------------------- [Qdrant Docs\ -----------\ \ Official documentation](https://qdrant.tech/documentation/) [Adapter Source\ --------------\ \ GitHub repository](https://github.com/topoteretes/cognee-community/tree/main/packages/vector/qdrant) [Extended Example\ ----------------\ \ FAQ docs assistant example.](https://github.com/topoteretes/cognee-community/tree/main/packages/vector/qdrant/example.py) [Vector Stores\ -------------\ \ Official vector providers](https://docs.cognee.ai/setup-configuration/vector-stores) [Community Overview\ ------------------\ \ All community integrations](https://docs.cognee.ai/setup-configuration/community-maintained/overview) [Setup Overview\ --------------\ \ Configuration guide](https://docs.cognee.ai/setup-configuration/overview) Was this page helpful? YesNo [Previous](https://docs.cognee.ai/setup-configuration/community-maintained/overview) [Search BasicsStep-by-step guide to running your first Cognee search and understanding core parameters\ \ Next](https://docs.cognee.ai/guides/search-basics) ⌘I On this page * [Installation](https://docs.cognee.ai/setup-configuration/community-maintained/qdrant#installation) * [Configuration](https://docs.cognee.ai/setup-configuration/community-maintained/qdrant#configuration) * [Important Notes](https://docs.cognee.ai/setup-configuration/community-maintained/qdrant#important-notes) * [Resources](https://docs.cognee.ai/setup-configuration/community-maintained/qdrant#resources) --- # Overview - Cognee Documentation [Skip to main content](https://docs.cognee.ai/core-concepts/overview#content-area) [Cognee Documentation home page![light logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20black.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=ea48b52be1df02b5909f780e6cd6856e)![dark logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20white.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=9f5bc18c4897c6e58b5cfa2b09bc079d)](https://docs.cognee.ai/) Search... ⌘K Search... Navigation Core Concepts Overview [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) [​](https://docs.cognee.ai/core-concepts/overview#introduction) Introduction ------------------------------------------------------------------------------- Cognee is an open source tool and platform that transforms your raw data into intelligent, searchable memory. It combines vector search with graph databases to make your data both searchable by meaning and connected by relationships. **Dual storage architecture** gives you both semantic search and structural reasoning **Modular design** composes [Tasks](https://docs.cognee.ai/core-concepts/building-blocks/tasks) , [Pipelines](https://docs.cognee.ai/core-concepts/building-blocks/pipelines) , and [DataPoints](https://docs.cognee.ai/core-concepts/building-blocks/datapoints) **Main operations** handle the complete workflow from ingestion to search: add, cognify, memify, search. [​](https://docs.cognee.ai/core-concepts/overview#table-of-contents) Table of Contents ----------------------------------------------------------------------------------------- Architecture Cognee uses three complementary storage systems, each playing a different role: * **Relational store** — Tracks documents, chunks, and provenance (where data came from and how it’s linked) * **Vector store** — Holds embeddings for semantic similarity (numerical representations that find conceptually related content) * **Graph store** — Captures entities and relationships in a knowledge graph (nodes and edges that show connections between concepts) This architecture makes your data both **searchable** (via vectors) and **connected** (via graphs). Cognee ships with lightweight defaults that run locally, and you can swap in production-ready backends when needed.For detailed information about the storage architecture, see [Architecture](https://docs.cognee.ai/core-concepts/architecture) . Building Blocks Cognee’s processing system is built from three fundamental components: * **[DataPoints](https://docs.cognee.ai/core-concepts/building-blocks/datapoints) ** — Structured data units that become graph nodes, carrying both content and metadata for indexing * **[Tasks](https://docs.cognee.ai/core-concepts/building-blocks/tasks) ** — Individual processing units that transform data, from text analysis to relationship extraction * **[Pipelines](https://docs.cognee.ai/core-concepts/building-blocks/pipelines) ** — Orchestration of Tasks into coordinated workflows, like assembly lines for data transformation These building blocks work together to create a flexible system where you can: * Use built-in Tasks for common operations * Create custom Tasks for domain-specific logic by extending DataPoints * Compose Tasks into Pipelines that match your workflow Main Operations Cognee provides four main operations that users interact with: * **[Add](https://docs.cognee.ai/core-concepts/main-operations/add) ** — Ingest and prepare data for processing, handling various file formats and data sources * **[Cognify](https://docs.cognee.ai/core-concepts/main-operations/cognify) ** — Create knowledge graphs from processed data through cognitive processing and entity extraction * **[Memify](https://docs.cognee.ai/core-concepts/main-operations/memify) ** — Optional semantic enrichment of the graph for enhanced understanding _(coming soon)_ * **[Search](https://docs.cognee.ai/core-concepts/main-operations/search) ** — Query and retrieve information using semantic similarity, graph traversal, or hybrid approaches **Note:** Search works great with just the basic Add → Cognify → Search workflow. Memify is an optional enhancement that will provide additional semantic enrichment when available. Further Concepts Beyond the core workflow, Cognee offers advanced features for sophisticated knowledge management: * **[Node Sets](https://docs.cognee.ai/core-concepts/further-concepts/node-sets) ** — Tagging and organization system that helps categorize and filter your knowledge base content * **[Ontologies](https://docs.cognee.ai/core-concepts/further-concepts/ontologies) ** — External knowledge grounding through RDF/XML ontologies that connect your data to established knowledge structures These concepts extend Cognee’s capabilities for: * **Organization** — Managing growing knowledge bases with systematic tagging * **Knowledge grounding** — Connecting your data to external, validated knowledge sources * **Domain expertise** — Leveraging existing ontologies for specialized fields like medicine, finance, or research [​](https://docs.cognee.ai/core-concepts/overview#next-steps) Next steps --------------------------------------------------------------------------- A good way to learn Cognee is to start with its [architecture](https://docs.cognee.ai/core-concepts/architecture) , move on to [building blocks](https://docs.cognee.ai/core-concepts/building-blocks/datapoints) , practice the [main operations](https://docs.cognee.ai/core-concepts/main-operations/add) , and finally explore [advanced features](https://docs.cognee.ai/core-concepts/further-concepts/node-sets) . [Architecture\ ------------\ \ Understand Cognee’s three storage systems and how they work together](https://docs.cognee.ai/core-concepts/architecture) [Building Blocks\ ---------------\ \ Learn about DataPoints, Tasks, and Pipelines that power the system](https://docs.cognee.ai/core-concepts/building-blocks/datapoints) [Main Operations\ ---------------\ \ Master Add, Cognify, and Search operations for your workflows](https://docs.cognee.ai/core-concepts/main-operations/add) Was this page helpful? YesNo [Previous](https://docs.cognee.ai/getting-started/quickstart) [ArchitectureUnderstanding Cognee's storage architecture and system components\ \ Next](https://docs.cognee.ai/core-concepts/architecture) ⌘I On this page * [Introduction](https://docs.cognee.ai/core-concepts/overview#introduction) * [Table of Contents](https://docs.cognee.ai/core-concepts/overview#table-of-contents) * [Next steps](https://docs.cognee.ai/core-concepts/overview#next-steps) --- # Permissions Setup - Cognee Documentation [Skip to main content](https://docs.cognee.ai/setup-configuration/permissions#content-area) [Cognee Documentation home page![light logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20black.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=ea48b52be1df02b5909f780e6cd6856e)![dark logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20white.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=9f5bc18c4897c6e58b5cfa2b09bc079d)](https://docs.cognee.ai/) Search... ⌘K Search... Navigation Setup Configuration Permissions Setup [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) Enable Cognee’s permission system for data isolation and access control. For detailed concepts, see [Cognee Permissions System](https://docs.cognee.ai/core-concepts/permissions-system/overview) . [​](https://docs.cognee.ai/setup-configuration/permissions#enable-permission-system) Enable Permission System ---------------------------------------------------------------------------------------------------------------- Set the environment variable to enable access control: Copy ENABLE_BACKEND_ACCESS_CONTROL=true REQUIRE_AUTHENTICATION=true **Database Override**: Permission mode enforces Kùzu (graph) and LanceDB (vector). Custom providers are ignored. [​](https://docs.cognee.ai/setup-configuration/permissions#database-setup) Database Setup -------------------------------------------------------------------------------------------- Choose your relational database: * **SQLite** — Local development (auto-creates files) * **Postgres** — Production (requires manual setup) See [Relational Databases](https://docs.cognee.ai/setup-configuration/relational-databases) for detailed configuration. [​](https://docs.cognee.ai/setup-configuration/permissions#authentication) Authentication -------------------------------------------------------------------------------------------- ### [​](https://docs.cognee.ai/setup-configuration/permissions#api-server) API Server Start the server with authentication: Copy uvicorn cognee.api.client:app --host 0.0.0.0 --port 8000 **Default credentials (development only):** * Username: `default_user@example.com` * Password: `default_password` ### [​](https://docs.cognee.ai/setup-configuration/permissions#programmatic-access) Programmatic Access See [Permission Snippets](https://docs.cognee.ai/guides/permission-snippets) for complete programmatic examples. [​](https://docs.cognee.ai/setup-configuration/permissions#data-organization) Data Organization -------------------------------------------------------------------------------------------------- Data is automatically organized by user and dataset. Each user gets isolated storage: Copy .cognee_system/databases// ├── .pkl # Kùzu graph database └── .lance.db/ # LanceDB vector database [​](https://docs.cognee.ai/setup-configuration/permissions#troubleshooting) Troubleshooting ---------------------------------------------------------------------------------------------- **Permission Denied**: Verify user has required permission on the dataset. **Data Isolation**: Check per-user database files exist: Copy ls -la .cognee_system/databases// **Database Conflicts**: Custom providers are ignored in permission mode. [Permission System\ -----------------\ \ Learn about users, tenants, roles, and ACL](https://docs.cognee.ai/core-concepts/permissions-system/overview) [Usage Guide\ -----------\ \ How to use permission features](https://docs.cognee.ai/guides/permission-snippets) Was this page helpful? YesNo [Previous](https://docs.cognee.ai/setup-configuration/graph-stores) [Adapters OverviewAdapters and extensions built by the Cognee community\ \ Next](https://docs.cognee.ai/setup-configuration/community-maintained/overview) ⌘I On this page * [Enable Permission System](https://docs.cognee.ai/setup-configuration/permissions#enable-permission-system) * [Database Setup](https://docs.cognee.ai/setup-configuration/permissions#database-setup) * [Authentication](https://docs.cognee.ai/setup-configuration/permissions#authentication) * [API Server](https://docs.cognee.ai/setup-configuration/permissions#api-server) * [Programmatic Access](https://docs.cognee.ai/setup-configuration/permissions#programmatic-access) * [Data Organization](https://docs.cognee.ai/setup-configuration/permissions#data-organization) * [Troubleshooting](https://docs.cognee.ai/setup-configuration/permissions#troubleshooting) --- # Datasets - Cognee Documentation [Skip to main content](https://docs.cognee.ai/core-concepts/permissions-system/datasets#content-area) [Cognee Documentation home page![light logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20black.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=ea48b52be1df02b5909f780e6cd6856e)![dark logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20white.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=9f5bc18c4897c6e58b5cfa2b09bc079d)](https://docs.cognee.ai/) Search... ⌘K Search... Navigation Cognee Permissions System Datasets [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) [​](https://docs.cognee.ai/core-concepts/permissions-system/datasets#datasets:-the-core-unit-of-data) Datasets: The Core Unit of Data ======================================================================================================================================== A dataset is a logical container for related documents and their processed knowledge graphs. All data in Cognee belongs to a dataset. When you add documents to Cognee using `cognee.add()`, they are processed and stored within a specific dataset. **Dataset-scoped permissions** — All permissions in Cognee are defined at the dataset level, never for individual documents. [​](https://docs.cognee.ai/core-concepts/permissions-system/datasets#ownership-and-permissions) Ownership and Permissions ---------------------------------------------------------------------------------------------------------------------------- When a principal creates a dataset, they become its **owner**. A principal is any entity that can have permissions, like a [user](https://docs.cognee.ai/core-concepts/permissions-system/users) , [tenant](https://docs.cognee.ai/core-concepts/permissions-system/tenants) , or [role](https://docs.cognee.ai/core-concepts/permissions-system/roles) . Ownership cannot be changed. The owner has full control and can grant permissions to others. There are four types of permissions you can grant on a dataset: * **Read** — View documents and query the knowledge graph. * **Write** — Add, modify, or remove documents and data. * **Delete** — Remove the entire dataset. * **Share** — Grant permissions to other principals. [​](https://docs.cognee.ai/core-concepts/permissions-system/datasets#dataset-isolation:-how-access-is-enforced) Dataset Isolation: How Access Is Enforced ------------------------------------------------------------------------------------------------------------------------------------------------------------ Cognee can enforce strict data isolation between datasets, but it’s important to understand when this happens. * **Isolation is optional**: Dataset boundaries are only enforced when the `ENABLE_BACKEND_ACCESS_CONTROL` setting is `true`. * **Without isolation**: If this setting is `false`, dataset parameters are ignored during searches, and queries will run across all data in the system, regardless of permissions. * **Database support**: True isolation is currently supported when using Kùzu for the graph store, LanceDB for the vector store, and SQLite or Postgres for the relational database. Other database backends (like Neo4j or Qdrant) do not support dataset isolation. See [ACL](https://docs.cognee.ai/core-concepts/permissions-system/acl) for details on how permissions are stored and checked. For setup instructions, see [Permissions Setup](https://docs.cognee.ai/setup-configuration/permissions) . [​](https://docs.cognee.ai/core-concepts/permissions-system/datasets#using-datasets-in-operations) Using Datasets in Operations ---------------------------------------------------------------------------------------------------------------------------------- Datasets integrate with Cognee’s main operations: * **`add`**: Direct new content into a specific dataset by name or ID. If no dataset is specified, a default `main_dataset` is used. * **`cognify`**: Choose which dataset(s) to transform into AI memory stored in the graph and vector stores. * **`search`**: Scope queries to run only against datasets you have read access to. * **`memify`**: Apply optional semantic enrichment on a per-dataset basis. [​](https://docs.cognee.ai/core-concepts/permissions-system/datasets#technical-details) Technical Details ------------------------------------------------------------------------------------------------------------ Operation Permission Requirements Different operations require different permissions: * `add`/`cognify` operations → require `write` permission * `search` operations → require `read` permission * `delete` operations → require `delete` permission * Permission management → requires `share` permission Dataset Creation Methods Cognee provides two helper methods for creating datasets: * `create_dataset()`: This is a lower-level function that only inserts the dataset record. It expects the caller to manage the Access Control List (ACL) entries separately. * `create_authorized_dataset()`: This is the recommended method for most user-facing flows. It wraps `create_dataset()` and then immediately grants the creator full `read/write/delete/share` permissions. This ensures the dataset is usable as soon as it’s created, especially when `ENABLE_BACKEND_ACCESS_CONTROL` is active. Dataset Model Fields The core dataset metadata is stored in a relational (SQL) database. The `datasets` table includes: * `id`: Unique identifier (UUID primary key) * `name`: Human-readable name * `owner_id`: ID of the principal who created the dataset * `created_at`: Timestamp when created * `updated_at`: Timestamp when last modified [​](https://docs.cognee.ai/core-concepts/permissions-system/datasets#limitations) Limitations ------------------------------------------------------------------------------------------------ * Dataset ownership cannot be transferred. * When access control is enabled, the graph and vector stores are enforced as Kùzu and LanceDB. * Cross-dataset searches are not supported directly. Queries are always scoped to a single dataset. To search multiple datasets, you must run separate queries for each one you have access to. [Main Operations\ ---------------\ \ See how datasets work with Add, Cognify, and Search](https://docs.cognee.ai/core-concepts/main-operations/add) [Building Blocks\ ---------------\ \ Learn about the DataPoints that populate datasets](https://docs.cognee.ai/core-concepts/building-blocks/datapoints) Was this page helpful? YesNo [Previous](https://docs.cognee.ai/core-concepts/permissions-system/overview) [PrincipalsThe unified abstraction for entities that can hold permissions in Cognee\ \ Next](https://docs.cognee.ai/core-concepts/permissions-system/principals) ⌘I On this page * [Datasets: The Core Unit of Data](https://docs.cognee.ai/core-concepts/permissions-system/datasets#datasets:-the-core-unit-of-data) * [Ownership and Permissions](https://docs.cognee.ai/core-concepts/permissions-system/datasets#ownership-and-permissions) * [Dataset Isolation: How Access Is Enforced](https://docs.cognee.ai/core-concepts/permissions-system/datasets#dataset-isolation:-how-access-is-enforced) * [Using Datasets in Operations](https://docs.cognee.ai/core-concepts/permissions-system/datasets#using-datasets-in-operations) * [Technical Details](https://docs.cognee.ai/core-concepts/permissions-system/datasets#technical-details) * [Limitations](https://docs.cognee.ai/core-concepts/permissions-system/datasets#limitations) --- # Custom Tasks and Pipelines - Cognee Documentation [Skip to main content](https://docs.cognee.ai/guides/custom-tasks-pipelines#content-area) [Cognee Documentation home page![light logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20black.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=ea48b52be1df02b5909f780e6cd6856e)![dark logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20white.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=9f5bc18c4897c6e58b5cfa2b09bc079d)](https://docs.cognee.ai/) Search... ⌘K Search... Navigation Customizing Cognee Custom Tasks and Pipelines [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) A minimal guide to creating custom tasks and pipelines. You’ll build a two-step pipeline: the LLM extracts People directly, then you insert them into the knowledge graph. **Before you start:** * Complete [Quickstart](https://docs.cognee.ai/guides/getting-started/quickstart) to understand basic operations * Ensure you have [LLM Providers](https://docs.cognee.ai/guides/setup-configuration/llm-providers) configured * Have some text data to process [​](https://docs.cognee.ai/guides/custom-tasks-pipelines#what-custom-tasks-and-pipelines-do) What Custom Tasks and Pipelines Do ---------------------------------------------------------------------------------------------------------------------------------- * Define custom processing steps using `Task` objects * Chain multiple operations together in a pipeline * Use LLMs to extract structured data from text * Insert structured data directly into the knowledge graph * Control the entire data processing workflow [​](https://docs.cognee.ai/guides/custom-tasks-pipelines#code-in-action) Code in Action ------------------------------------------------------------------------------------------ Copy import asyncio from typing import Any, Dict, List from pydantic import BaseModel, SkipValidation import cognee from cognee.modules.engine.operations.setup import setup from cognee.infrastructure.llm.LLMGateway import LLMGateway from cognee.infrastructure.engine import DataPoint from cognee.tasks.storage import add_data_points from cognee.modules.pipelines import Task, run_pipeline class Person(DataPoint): name: str # Optional relationships (we'll let the LLM populate this) knows: List["Person"] = [] # Make names searchable in the vector store metadata: Dict[str, Any] = {"index_fields": ["name"]} class People(BaseModel): persons: List[Person] async def extract_people(text: str) -> List[Person]: system_prompt = ( "Extract people mentioned in the text. " "Return as `persons: Person[]` with each Person having `name` and optional `knows` relations. " "If the text says someone knows someone set `knows` accordingly. " "Only include facts explicitly stated." ) people = await LLMGateway.acreate_structured_output(text, system_prompt, People) return people.persons async def main(): await cognee.prune.prune_data() await cognee.prune.prune_system(metadata=True) await setup() text = "Alice knows Bob." tasks = [\ Task(extract_people), # input: text -> output: list[Person]\ Task(add_data_points) # input: list[Person] -> output: list[Person]\ ] async for _ in run_pipeline(tasks=tasks, data=text, datasets=["people_demo"]): pass if __name__ == "__main__": asyncio.run(main()) This simple example uses a two-step pipeline for demonstration. In practice, you can create complex pipelines with multiple custom tasks, data transformations, and processing steps. [​](https://docs.cognee.ai/guides/custom-tasks-pipelines#what-just-happened) What Just Happened -------------------------------------------------------------------------------------------------- ### [​](https://docs.cognee.ai/guides/custom-tasks-pipelines#step-1:-define-your-data-models) Step 1: Define Your Data Models Copy class Person(DataPoint): name: str knows: SkipValidation[Any] = None metadata: Dict[str, Any] = {"index_fields": ["name"]} class People(BaseModel): persons: List[Person] Create Pydantic models for your data. `Person` inherits from `DataPoint` for graph insertion, while `People` is a simple container for the LLM output. **Metadata is recommended** to make fields searchable in the vector database. ### [​](https://docs.cognee.ai/guides/custom-tasks-pipelines#step-2:-create-your-custom-task) Step 2: Create Your Custom Task Copy async def extract_people(text: str) -> List[Person]: system_prompt = ( "Extract people mentioned in the text. " "Return as `persons: Person[]` with each Person having `name` and optional `knows` relations. " "If the text says someone knows someone set `knows` accordingly. " "Only include facts explicitly stated." ) people = await LLMGateway.acreate_structured_output(text, system_prompt, People) return people.persons This task uses the LLM to extract structured data from text. The LLM fills `People` objects with `Person` instances, including relationships via the `knows` field. `acreate_structured_output` is backend-agnostic (BAML or LiteLLM+Instructor). Configure via `STRUCTURED_OUTPUT_FRAMEWORK` in `.env`. ### [​](https://docs.cognee.ai/guides/custom-tasks-pipelines#step-3:-build-your-pipeline) Step 3: Build Your Pipeline Copy tasks = [\ Task(extract_people), # input: text -> output: list[Person]\ Task(add_data_points) # input: list[Person] -> output: list[Person]\ ] async for _ in run_pipeline(tasks=tasks, data=text, datasets=["people_demo"]): pass Chain your tasks together in a pipeline. The first task extracts people from text, the second inserts them into the knowledge graph. `add_data_points` automatically creates nodes and edges from the `knows` relationships. Under the hood, `run_pipeline(...)` automatically initializes databases and checks LLM/embeddings configuration, so you don’t need to worry about setup. Once the pipeline completes, your Cognee memory with graph and embeddings is created and ready for interaction. You can now search your data using the standard search methods: Copy from cognee.api.v1.search import SearchType # Search the processed data results = await cognee.search( query_type=SearchType.GRAPH_COMPLETION, query_text="Who does Alice know?", datasets=["people_demo"] ) print(results) [​](https://docs.cognee.ai/guides/custom-tasks-pipelines#use-cases) Use Cases -------------------------------------------------------------------------------- This approach is particularly useful when you need to: * Extract structured data from unstructured text * Process data through multiple custom steps * Control the entire data processing workflow * Combine LLM extraction with programmatic data insertion * Build complex data processing pipelines [Custom Data Models\ ------------------\ \ Learn about custom data models](https://docs.cognee.ai/guides/custom-data-models) [Low-Level LLM\ -------------\ \ Learn about direct LLM interaction](https://docs.cognee.ai/guides/low-level-llm) [Core Concepts\ -------------\ \ Understand knowledge graph fundamentals](https://docs.cognee.ai/core-concepts/overview) Was this page helpful? YesNo [Previous](https://docs.cognee.ai/guides/custom-data-models) [Custom PromptsStep-by-step guide to using custom prompts to control graph extraction\ \ Next](https://docs.cognee.ai/guides/custom-prompts) ⌘I On this page * [What Custom Tasks and Pipelines Do](https://docs.cognee.ai/guides/custom-tasks-pipelines#what-custom-tasks-and-pipelines-do) * [Code in Action](https://docs.cognee.ai/guides/custom-tasks-pipelines#code-in-action) * [What Just Happened](https://docs.cognee.ai/guides/custom-tasks-pipelines#what-just-happened) * [Step 1: Define Your Data Models](https://docs.cognee.ai/guides/custom-tasks-pipelines#step-1:-define-your-data-models) * [Step 2: Create Your Custom Task](https://docs.cognee.ai/guides/custom-tasks-pipelines#step-2:-create-your-custom-task) * [Step 3: Build Your Pipeline](https://docs.cognee.ai/guides/custom-tasks-pipelines#step-3:-build-your-pipeline) * [Use Cases](https://docs.cognee.ai/guides/custom-tasks-pipelines#use-cases) --- # Setup Configuration - Cognee Documentation [Skip to main content](https://docs.cognee.ai/setup-configuration/overview#content-area) [Cognee Documentation home page![light logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20black.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=ea48b52be1df02b5909f780e6cd6856e)![dark logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20white.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=9f5bc18c4897c6e58b5cfa2b09bc079d)](https://docs.cognee.ai/) Search... ⌘K Search... Navigation Setup Configuration Setup Configuration [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) Configure Cognee to use your preferred LLM, embedding engine, relational database, vector store, and graph store via environment variables in a local `.env` file. This section provides beginner-friendly guides for setting up different backends, with detailed technical information available in expandable sections. [​](https://docs.cognee.ai/setup-configuration/overview#what-you-can-configure) What You Can Configure --------------------------------------------------------------------------------------------------------- Cognee uses a flexible architecture that lets you choose the best tools for your needs. We recommend starting with the defaults to get familiar with Cognee, then customizing each component as needed: * **[LLM Providers](https://docs.cognee.ai/setup-configuration/llm-providers) ** — Choose from OpenAI, Azure OpenAI, Google Gemini, Anthropic, Ollama, or custom providers for text generation and reasoning tasks * **[Structured Output Backends](https://docs.cognee.ai/setup-configuration/structured-output-backends) ** — Configure LiteLLM + Instructor or BAML for reliable data extraction from LLM responses * **[Embedding Providers](https://docs.cognee.ai/setup-configuration/embedding-providers) ** — Select from OpenAI, Azure OpenAI, Google Gemini, Mistral, Ollama, Fastembed, or custom embedding services to create vector representations for semantic search * **[Relational Databases](https://docs.cognee.ai/setup-configuration/relational-databases) ** — Use SQLite for local development or Postgres for production to store metadata, documents, and system state * **[Vector Stores](https://docs.cognee.ai/setup-configuration/vector-stores) ** — Store embeddings in LanceDB, PGVector, ChromaDB, FalkorDB, or Neptune Analytics for similarity search * **[Graph Stores](https://docs.cognee.ai/setup-configuration/graph-stores) ** — Build knowledge graphs with Kuzu, Kuzu-remote, Neo4j, Neptune, or Neptune Analytics to manage relationships and reasoning * **[Dataset Separation & Access Control](https://docs.cognee.ai/setup-configuration/permissions) ** — Configure dataset-level permissions and isolation Dataset isolation is not enabled by default; see [how to enable it](https://docs.cognee.ai/core-concepts/permissions-system/datasets#dataset-isolation) . [​](https://docs.cognee.ai/setup-configuration/overview#observability-&-telemetry) Observability & Telemetry --------------------------------------------------------------------------------------------------------------- Cognee includes built-in telemetry to help you monitor and debug your knowledge graph operations. You can control telemetry behavior with environment variables: * **`TELEMETRY_DISABLED`** (boolean, optional): Set to `true` to disable all telemetry collection (default: `false`) When telemetry is enabled, Cognee automatically collects: * Search query performance metrics * Processing pipeline execution times * Error rates and debugging information * System resource usage Telemetry data helps improve Cognee’s performance and reliability. It’s collected anonymously and doesn’t include your actual data content. [​](https://docs.cognee.ai/setup-configuration/overview#configuration-workflow) Configuration Workflow --------------------------------------------------------------------------------------------------------- 1. Install Cognee with all optional dependencies: * **Local setup**: `uv sync --all-extras` * **Library**: `pip install "cognee[all]"` 2. Create a `.env` file in your project root (if you haven’t already) — see [Installation](https://docs.cognee.ai/setup-configuration/getting-started/installation) for details 3. Choose your preferred providers and follow the configuration instructions from the guides below **Configuration Changes**: If you’ve already run Cognee with default settings and are now changing your configuration (e.g., switching from SQLite to Postgres, or changing vector stores), you should call pruning operations before the next cognification to ensure data consistency. **LLM/Embedding Configuration**: If you configure only LLM or only embeddings, the other defaults to OpenAI. Ensure you have a working OpenAI API key, or configure both LLM and embeddings to avoid unexpected defaults. [LLM Providers\ -------------\ \ Configure OpenAI, Azure, Gemini, Anthropic, Ollama, or custom LLM providers](https://docs.cognee.ai/setup-configuration/llm-providers) [Structured Output Backends\ --------------------------\ \ Configure LiteLLM + Instructor or BAML for reliable data extraction](https://docs.cognee.ai/setup-configuration/structured-output-backends) [Embedding Providers\ -------------------\ \ Set up OpenAI, Mistral, Ollama, Fastembed, or custom embedding services](https://docs.cognee.ai/setup-configuration/embedding-providers) [Relational Databases\ --------------------\ \ Choose between SQLite for local development or Postgres for production](https://docs.cognee.ai/setup-configuration/relational-databases) [Vector Stores\ -------------\ \ Configure LanceDB, PGVector, ChromaDB, FalkorDB, or Neptune Analytics](https://docs.cognee.ai/setup-configuration/vector-stores) [Graph Stores\ ------------\ \ Set up Kuzu, Neo4j, or Neptune for knowledge graph storage](https://docs.cognee.ai/setup-configuration/graph-stores) Was this page helpful? YesNo [Previous](https://docs.cognee.ai/guides/permission-snippets) [LLM ProvidersConfigure LLM providers for text generation and reasoning in Cognee\ \ Next](https://docs.cognee.ai/setup-configuration/llm-providers) ⌘I On this page * [What You Can Configure](https://docs.cognee.ai/setup-configuration/overview#what-you-can-configure) * [Observability & Telemetry](https://docs.cognee.ai/setup-configuration/overview#observability-&-telemetry) * [Configuration Workflow](https://docs.cognee.ai/setup-configuration/overview#configuration-workflow) --- # Vector Stores - Cognee Documentation [Skip to main content](https://docs.cognee.ai/setup-configuration/vector-stores#content-area) [Cognee Documentation home page![light logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20black.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=ea48b52be1df02b5909f780e6cd6856e)![dark logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20white.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=9f5bc18c4897c6e58b5cfa2b09bc079d)](https://docs.cognee.ai/) Search... ⌘K Search... Navigation Setup Configuration Vector Stores [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) Vector stores hold embeddings for semantic similarity search. They enable Cognee to find conceptually related content based on meaning rather than exact text matches. **New to configuration?**See the [Setup Configuration Overview](https://docs.cognee.ai/setup-configuration/overview) for the complete workflow:install extras → create `.env` → choose providers → handle pruning. [​](https://docs.cognee.ai/setup-configuration/vector-stores#supported-providers) Supported Providers -------------------------------------------------------------------------------------------------------- Cognee supports multiple vector store options: * **LanceDB** — File-based vector store, works out of the box (default) * **PGVector** — Postgres-backed vector storage with pgvector extension * **ChromaDB** — HTTP server-based vector database * **FalkorDB** — Hybrid graph + vector database * **Neptune Analytics** — Amazon Neptune Analytics hybrid solution [​](https://docs.cognee.ai/setup-configuration/vector-stores#configuration) Configuration -------------------------------------------------------------------------------------------- Environment Variables Set these environment variables in your `.env` file: * `VECTOR_DB_PROVIDER` — The vector store provider (lancedb, pgvector, chromadb, falkordb, neptune\_analytics) * `VECTOR_DB_URL` — Database URL or connection string * `VECTOR_DB_KEY` — Authentication key (provider-specific) * `VECTOR_DB_PORT` — Database port (for some providers) [​](https://docs.cognee.ai/setup-configuration/vector-stores#setup-guides) Setup Guides ------------------------------------------------------------------------------------------ LanceDB (Default) LanceDB is file-based and requires no additional setup. It’s perfect for local development and single-user scenarios. Copy VECTOR_DB_PROVIDER="lancedb" # Optional, can be a path or URL. Defaults to /databases/cognee.lancedb # VECTOR_DB_URL=/absolute/or/relative/path/to/cognee.lancedb **Installation**: LanceDB is included by default with Cognee. No additional installation required.**Data Location**: Vectors are stored in a local directory. Defaults under the Cognee system path if `VECTOR_DB_URL` is empty. PGVector PGVector stores vectors inside your Postgres database using the pgvector extension. Copy VECTOR_DB_PROVIDER="pgvector" # Uses the same Postgres connection as your relational DB (DB_HOST, DB_PORT, DB_NAME, DB_USERNAME, DB_PASSWORD) **Installation**: Install the Postgres extras: Copy pip install "cognee[postgres]" # or for binary version pip install "cognee[postgres-binary]" **Docker Setup**: Use the built-in Postgres with pgvector: Copy docker compose --profile postgres up -d **Note**: If using your own Postgres, ensure `CREATE EXTENSION IF NOT EXISTS vector;` is available in the target database. ChromaDB ChromaDB requires a running Chroma server and authentication token. Copy VECTOR_DB_PROVIDER="chromadb" VECTOR_DB_URL="http://localhost:3002" VECTOR_DB_KEY="" **Installation**: Install ChromaDB extras: Copy pip install "cognee[chromadb]" # or directly pip install chromadb **Docker Setup**: Start the bundled ChromaDB server: Copy docker compose --profile chromadb up -d FalkorDB FalkorDB can serve as both graph and vector store, providing a hybrid solution. Copy VECTOR_DB_PROVIDER="falkordb" VECTOR_DB_URL="localhost" VECTOR_DB_PORT="6379" **Installation**: Install FalkorDB extras: Copy pip install "cognee[falkordb]" **Docker Setup**: Start the FalkorDB service: Copy docker compose --profile falkordb up -d **Access**: Default ports are 6379 (DB) and 3001 (UI). Neptune Analytics Use Amazon Neptune Analytics as a hybrid vector + graph backend. Copy VECTOR_DB_PROVIDER="neptune_analytics" VECTOR_DB_URL="neptune-graph://" # AWS credentials via environment or default SDK chain **Installation**: Install Neptune extras: Copy pip install "cognee[neptune]" **Note**: URL must start with `neptune-graph://` and AWS credentials should be configured via environment variables or AWS SDK. [​](https://docs.cognee.ai/setup-configuration/vector-stores#important-considerations) Important Considerations ------------------------------------------------------------------------------------------------------------------ Dimension Consistency Ensure `EMBEDDING_DIMENSIONS` matches your vector store collection/table schemas: * PGVector column size * LanceDB Vector size * ChromaDB collection schema Changing dimensions requires recreating collections. Provider Comparison | Provider | Setup | Performance | Use Case | | --- | --- | --- | --- | | LanceDB | Zero setup | Good | Local development | | PGVector | Postgres required | Excellent | Production with Postgres | | ChromaDB | Server required | Good | Dedicated vector store | | FalkorDB | Server required | Good | Hybrid graph + vector | | Neptune Analytics | AWS required | Excellent | Cloud hybrid solution | [​](https://docs.cognee.ai/setup-configuration/vector-stores#community-maintained-providers) Community-Maintained Providers ------------------------------------------------------------------------------------------------------------------------------ Additional vector stores are available through community-maintained adapters: * **[Qdrant](https://docs.cognee.ai/setup-configuration/community-maintained/qdrant) ** — Vector search engine with cloud and self-hosted options * **Milvus, Pinecone, Weaviate, Redis, and more** — See [all community adapters](https://docs.cognee.ai/setup-configuration/community-maintained/overview) [​](https://docs.cognee.ai/setup-configuration/vector-stores#notes) Notes ---------------------------------------------------------------------------- * **Embedding Integration**: Vector stores use your embedding engine from the Embeddings section * **Dimension Matching**: Keep `EMBEDDING_DIMENSIONS` consistent between embedding provider and vector store * **Performance**: Local providers (LanceDB) are simpler but cloud providers offer better scalability [Embedding Providers\ -------------------\ \ Configure embedding providers for vector generation](https://docs.cognee.ai/setup-configuration/embedding-providers) [Graph Stores\ ------------\ \ Set up graph databases for knowledge graphs](https://docs.cognee.ai/setup-configuration/graph-stores) [Overview\ --------\ \ Return to setup configuration overview](https://docs.cognee.ai/setup-configuration/overview) Was this page helpful? YesNo [Previous](https://docs.cognee.ai/setup-configuration/relational-databases) [Graph StoresConfigure graph databases for knowledge graph storage and relationship reasoning in Cognee\ \ Next](https://docs.cognee.ai/setup-configuration/graph-stores) ⌘I On this page * [Supported Providers](https://docs.cognee.ai/setup-configuration/vector-stores#supported-providers) * [Configuration](https://docs.cognee.ai/setup-configuration/vector-stores#configuration) * [Setup Guides](https://docs.cognee.ai/setup-configuration/vector-stores#setup-guides) * [Important Considerations](https://docs.cognee.ai/setup-configuration/vector-stores#important-considerations) * [Community-Maintained Providers](https://docs.cognee.ai/setup-configuration/vector-stores#community-maintained-providers) * [Notes](https://docs.cognee.ai/setup-configuration/vector-stores#notes) --- # Custom Data Models - Cognee Documentation [Skip to main content](https://docs.cognee.ai/guides/custom-data-models#content-area) [Cognee Documentation home page![light logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20black.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=ea48b52be1df02b5909f780e6cd6856e)![dark logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20white.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=9f5bc18c4897c6e58b5cfa2b09bc079d)](https://docs.cognee.ai/) Search... ⌘K Search... Navigation Customizing Cognee Custom Data Models [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) A minimal guide to creating custom data models and inserting them directly into the knowledge graph using `add_data_points`. **Before you start:** * Complete [Quickstart](https://docs.cognee.ai/guides/getting-started/quickstart) to understand basic operations * Ensure you have [LLM Providers](https://docs.cognee.ai/guides/setup-configuration/llm-providers) configured * Have some structured data you want to model [​](https://docs.cognee.ai/guides/custom-data-models#what-custom-data-models-do) What Custom Data Models Do -------------------------------------------------------------------------------------------------------------- * Define your own Pydantic models that inherit from `DataPoint` * Insert structured data directly into the knowledge graph without `cognify` * Create relationships between data points programmatically * Control exactly what gets indexed and how [​](https://docs.cognee.ai/guides/custom-data-models#code-in-action) Code in Action -------------------------------------------------------------------------------------- Copy import asyncio from typing import Any from pydantic import SkipValidation import cognee from cognee.infrastructure.engine import DataPoint from cognee.infrastructure.engine.models.Edge import Edge from cognee.tasks.storage import add_data_points class Person(DataPoint): name: str # Keep it simple for forward refs / mixed values knows: SkipValidation[Any] = None # single Person or list[Person] # Recommended: specify which fields to index for search metadata: dict = {"index_fields": ["name"]} async def main(): # Start clean (optional in your app) await cognee.prune.prune_data() await cognee.prune.prune_system(metadata=True) alice = Person(name="Alice") bob = Person(name="Bob") charlie = Person(name="Charlie") # Create relationships - field name becomes edge label alice.knows = bob # You can also do lists: alice.knows = [bob, charlie] # Optional: add weights and custom relationship types bob.knows = (Edge(weight=0.9, relationship_type="friend_of"), charlie) await add_data_points([alice, bob, charlie]) asyncio.run(main()) This example shows the complete workflow with metadata for indexing and optional edge weights. In practice, you can create complex nested models with multiple relationships and sophisticated data structures. [​](https://docs.cognee.ai/guides/custom-data-models#what-just-happened) What Just Happened ---------------------------------------------------------------------------------------------- ### [​](https://docs.cognee.ai/guides/custom-data-models#step-1:-define-your-data-model) Step 1: Define Your Data Model Copy class Person(DataPoint): name: str knows: SkipValidation[Any] = None # Recommended: specify which fields to index for search metadata: dict = {"index_fields": ["name"]} Create a Pydantic model that inherits from `DataPoint`. Use `SkipValidation[Any]` for fields that will hold other DataPoints to avoid forward reference issues. **Metadata is recommended** - it tells Cognee which fields to embed and store in the vector database for search. ### [​](https://docs.cognee.ai/guides/custom-data-models#step-2:-create-data-instances) Step 2: Create Data Instances Copy alice = Person(name="Alice") bob = Person(name="Bob") charlie = Person(name="Charlie") Instantiate your models with the data you want to store. Each instance becomes a node in the knowledge graph. ### [​](https://docs.cognee.ai/guides/custom-data-models#step-3:-create-relationships) Step 3: Create Relationships Copy alice.knows = bob # Optional: add weights and custom relationship types bob.knows = (Edge(weight=0.9, relationship_type="friend_of"), charlie) Assign DataPoint instances to fields to create edges. The field name becomes the relationship label by default. **Weights are optional** - you can use `Edge` to add weights, custom relationship types, or other metadata to your relationships. ### [​](https://docs.cognee.ai/guides/custom-data-models#step-4:-insert-into-graph) Step 4: Insert into Graph Copy await add_data_points([alice, bob, charlie]) This converts your DataPoint instances into nodes and edges in the knowledge graph, automatically handling the graph structure and indexing. The `name` field gets embedded and stored in the vector database for search. [​](https://docs.cognee.ai/guides/custom-data-models#use-in-custom-tasks-and-pipelines) Use in Custom Tasks and Pipelines ---------------------------------------------------------------------------------------------------------------------------- This approach is particularly useful when creating custom tasks and pipelines where you need to: * Insert structured data programmatically * Define specific relationships between known entities * Control exactly what gets indexed and how * Integrate with external data sources or APIs You can combine this with `cognify` to extract knowledge from unstructured text, then add your own structured data on top. [Low-Level LLM\ -------------\ \ Learn about direct LLM interaction](https://docs.cognee.ai/guides/low-level-llm) [Core Concepts\ -------------\ \ Understand knowledge graph fundamentals](https://docs.cognee.ai/core-concepts/overview) [API Reference\ -------------\ \ Explore API endpoints](https://docs.cognee.ai/api-reference/introduction) Was this page helpful? YesNo [Previous](https://docs.cognee.ai/guides/permission-snippets) [Custom Tasks and PipelinesStep-by-step guide to creating custom tasks and pipelines\ \ Next](https://docs.cognee.ai/guides/custom-tasks-pipelines) ⌘I On this page * [What Custom Data Models Do](https://docs.cognee.ai/guides/custom-data-models#what-custom-data-models-do) * [Code in Action](https://docs.cognee.ai/guides/custom-data-models#code-in-action) * [What Just Happened](https://docs.cognee.ai/guides/custom-data-models#what-just-happened) * [Step 1: Define Your Data Model](https://docs.cognee.ai/guides/custom-data-models#step-1:-define-your-data-model) * [Step 2: Create Data Instances](https://docs.cognee.ai/guides/custom-data-models#step-2:-create-data-instances) * [Step 3: Create Relationships](https://docs.cognee.ai/guides/custom-data-models#step-3:-create-relationships) * [Step 4: Insert into Graph](https://docs.cognee.ai/guides/custom-data-models#step-4:-insert-into-graph) * [Use in Custom Tasks and Pipelines](https://docs.cognee.ai/guides/custom-data-models#use-in-custom-tasks-and-pipelines) --- # Custom Prompts - Cognee Documentation [Skip to main content](https://docs.cognee.ai/guides/custom-prompts#content-area) [Cognee Documentation home page![light logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20black.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=ea48b52be1df02b5909f780e6cd6856e)![dark logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20white.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=9f5bc18c4897c6e58b5cfa2b09bc079d)](https://docs.cognee.ai/) Search... ⌘K Search... Navigation Customizing Cognee Custom Prompts [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) A minimal guide to shaping graph extraction with a custom LLM prompt. You’ll pass your prompt via `custom_prompt` to `cognee.cognify()` to control entity types, relationship labels, and extraction rules. **Before you start:** * Complete [Quickstart](https://docs.cognee.ai/guides/getting-started/quickstart) to understand basic operations * Ensure you have [LLM Providers](https://docs.cognee.ai/guides/setup-configuration/llm-providers) configured * Have some text or files to process [​](https://docs.cognee.ai/guides/custom-prompts#code-in-action) Code in Action ---------------------------------------------------------------------------------- Copy import asyncio import cognee from cognee.api.v1.search import SearchType custom_prompt = """ Extract only people and cities as entities. Connect people to cities with the relationship "lives_in". Ignore all other entities. """ async def main(): await cognee.add([\ "Alice moved to Paris in 2010, while Bob has always lived in New York.",\ "Andreas was born in Venice, but later settled in Lisbon.",\ "Diana and Tom were born and raised in Helsingy. Diana currently resides in Berlin, while Tom never moved."\ ]) await cognee.cognify(custom_prompt=custom_prompt) res = await cognee.search( query_type=SearchType.GRAPH_COMPLETION, query_text="Where does Alice live?", ) print(res) if __name__ == "__main__": asyncio.run(main()) This simple example uses a few strings for demonstration. In practice, you can add multiple documents, files, or entire datasets - the custom prompt processing works the same way across all your data. [​](https://docs.cognee.ai/guides/custom-prompts#what-just-happened) What Just Happened ------------------------------------------------------------------------------------------ ### [​](https://docs.cognee.ai/guides/custom-prompts#step-1:-add-your-data) Step 1: Add Your Data Copy await cognee.add([\ "Alice moved to Paris in 2010, while Bob has always lived in New York.",\ "Andreas was born in Venice, but later settled in Lisbon.",\ "Diana and Tom were born and raised in Helsingy. Diana currently resides in Berlin, while Tom never moved."\ ]) This adds text data to Cognee using the standard `add` function. The same approach works with multiple documents, files, or entire datasets. ### [​](https://docs.cognee.ai/guides/custom-prompts#step-2:-write-a-custom-prompt) Step 2: Write a Custom Prompt Copy custom_prompt = """ Extract only people and cities as entities. Connect people to cities with the relationship "lives_in". Ignore all other entities. """ The custom prompt overrides the default system prompt used during entity/relationship extraction. It constrains node types, enforces relationship naming, and reduces noise. `custom_prompt` is ignored when `temporal_cognify=True`. ### [​](https://docs.cognee.ai/guides/custom-prompts#step-3:-cognify-with-your-custom-prompt) Step 3: Cognify with Your Custom Prompt Copy await cognee.cognify(custom_prompt=custom_prompt) This processes your data using the custom prompt to control extraction behavior. You can also scope to specific datasets by passing the `datasets` parameter. ### [​](https://docs.cognee.ai/guides/custom-prompts#step-4:-ask-questions) Step 4: Ask Questions Copy res = await cognee.search( query_type=SearchType.GRAPH_COMPLETION, query_text="Where does Alice live?", ) Use `SearchType.GRAPH_COMPLETION` to get answers that leverage your custom extraction rules. [Core Concepts\ -------------\ \ Understand knowledge graph fundamentals](https://docs.cognee.ai/core-concepts/overview) [Ontology Quickstart\ -------------------\ \ Learn about ontology integration](https://docs.cognee.ai/guides/ontology-support) [API Reference\ -------------\ \ Explore API endpoints](https://docs.cognee.ai/api-reference/introduction) Was this page helpful? YesNo [Previous](https://docs.cognee.ai/guides/custom-tasks-pipelines) [Chatbots\ \ Next](https://docs.cognee.ai/examples/chatbots) ⌘I On this page * [Code in Action](https://docs.cognee.ai/guides/custom-prompts#code-in-action) * [What Just Happened](https://docs.cognee.ai/guides/custom-prompts#what-just-happened) * [Step 1: Add Your Data](https://docs.cognee.ai/guides/custom-prompts#step-1:-add-your-data) * [Step 2: Write a Custom Prompt](https://docs.cognee.ai/guides/custom-prompts#step-2:-write-a-custom-prompt) * [Step 3: Cognify with Your Custom Prompt](https://docs.cognee.ai/guides/custom-prompts#step-3:-cognify-with-your-custom-prompt) * [Step 4: Ask Questions](https://docs.cognee.ai/guides/custom-prompts#step-4:-ask-questions) --- # Graph Visualization - Cognee Documentation [Skip to main content](https://docs.cognee.ai/guides/graph-visualization#content-area) [Cognee Documentation home page![light logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20black.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=ea48b52be1df02b5909f780e6cd6856e)![dark logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20white.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=9f5bc18c4897c6e58b5cfa2b09bc079d)](https://docs.cognee.ai/) Search... ⌘K Search... Navigation Essentials Graph Visualization [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) A minimal guide to rendering your current knowledge graph to an interactive HTML file with one call. **Before you start:** * Complete [Quickstart](https://docs.cognee.ai/guides/getting-started/quickstart) to understand basic operations * Have some data processed with `cognify` (knowledge graph exists) [​](https://docs.cognee.ai/guides/graph-visualization#what-graph-visualization-shows) What Graph Visualization Shows ----------------------------------------------------------------------------------------------------------------------- * Nodes (entities, types, chunks, summaries) with color coding * Edges with labels and weights; tooltips show extra edge properties * Interactive features: drag nodes, zoom/pan, hover edges for details [​](https://docs.cognee.ai/guides/graph-visualization#code-in-action) Code in Action --------------------------------------------------------------------------------------- Copy import asyncio import cognee from cognee.api.v1.visualize.visualize import visualize_graph async def main(): await cognee.add(["Alice knows Bob.", "NLP is a subfield of CS."]) await cognee.cognify() await visualize_graph("./graph_after_cognify.html") asyncio.run(main()) This simple example uses basic text data for demonstration. In practice, you can visualize complex knowledge graphs with thousands of nodes and relationships. [​](https://docs.cognee.ai/guides/graph-visualization#what-just-happened) What Just Happened ----------------------------------------------------------------------------------------------- ### [​](https://docs.cognee.ai/guides/graph-visualization#step-1:-create-your-knowledge-graph) Step 1: Create Your Knowledge Graph Copy await cognee.add(["Alice knows Bob.", "NLP is a subfield of CS."]) await cognee.cognify() First, create your knowledge graph using the standard add → cognify workflow. The visualization works on existing graphs. ### [​](https://docs.cognee.ai/guides/graph-visualization#step-2:-generate-visualization) Step 2: Generate Visualization Copy await visualize_graph("./graph_after_cognify.html") This creates an interactive HTML file with your knowledge graph. You can specify a custom path or use the default location. [​](https://docs.cognee.ai/guides/graph-visualization#quick-options) Quick Options ------------------------------------------------------------------------------------- ### [​](https://docs.cognee.ai/guides/graph-visualization#default-location) Default Location Copy from cognee.api.v1.visualize.visualize import visualize_graph # Writes HTML to your home directory by default await visualize_graph() ### [​](https://docs.cognee.ai/guides/graph-visualization#custom-path) Custom Path Copy from cognee.api.v1.visualize.visualize import visualize_graph # Writes to the provided file path (created/overwritten) await visualize_graph("./my_graph.html") [​](https://docs.cognee.ai/guides/graph-visualization#tips) Tips ------------------------------------------------------------------- * **Large graphs**: Rendering a very big graph can be slow. Consider building subsets (e.g., smaller datasets) before visualizing * **Edge weights**: If present, control line thickness; multiple weights are summarized and shown in tooltips * **Static HTML**: Files are static HTML; you can open them in any modern browser or share them as artifacts [Code Graph\ ----------\ \ Learn about code graph visualization](https://docs.cognee.ai/guides/code-graph) [Core Concepts\ -------------\ \ Understand knowledge graph fundamentals](https://docs.cognee.ai/core-concepts/overview) [Custom Data Models\ ------------------\ \ Learn about custom data models](https://docs.cognee.ai/guides/custom-data-models) Was this page helpful? YesNo [Previous](https://docs.cognee.ai/guides/code-graph) [Low-Level LLMStep-by-step guide to using acreate\_structured\_output for direct LLM interaction\ \ Next](https://docs.cognee.ai/guides/low-level-llm) ⌘I On this page * [What Graph Visualization Shows](https://docs.cognee.ai/guides/graph-visualization#what-graph-visualization-shows) * [Code in Action](https://docs.cognee.ai/guides/graph-visualization#code-in-action) * [What Just Happened](https://docs.cognee.ai/guides/graph-visualization#what-just-happened) * [Step 1: Create Your Knowledge Graph](https://docs.cognee.ai/guides/graph-visualization#step-1:-create-your-knowledge-graph) * [Step 2: Generate Visualization](https://docs.cognee.ai/guides/graph-visualization#step-2:-generate-visualization) * [Quick Options](https://docs.cognee.ai/guides/graph-visualization#quick-options) * [Default Location](https://docs.cognee.ai/guides/graph-visualization#default-location) * [Custom Path](https://docs.cognee.ai/guides/graph-visualization#custom-path) * [Tips](https://docs.cognee.ai/guides/graph-visualization#tips) --- # S3 Storage - Cognee Documentation [Skip to main content](https://docs.cognee.ai/guides/s3-storage#content-area) [Cognee Documentation home page![light logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20black.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=ea48b52be1df02b5909f780e6cd6856e)![dark logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20white.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=9f5bc18c4897c6e58b5cfa2b09bc079d)](https://docs.cognee.ai/) Search... ⌘K Search... Navigation Essentials S3 Storage [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) A minimal guide to using S3 (or S3-compatible, e.g., MinIO) to ingest data and/or store Cognee’s internal files. **Before you start:** * Complete [Quickstart](https://docs.cognee.ai/guides/getting-started/quickstart) to understand basic operations * Ensure you have [LLM Providers](https://docs.cognee.ai/guides/setup-configuration/llm-providers) configured * Have S3 credentials and access to an S3 bucket [​](https://docs.cognee.ai/guides/s3-storage#what-s3-storage-does) What S3 Storage Does ------------------------------------------------------------------------------------------ * **Ingest from S3**: Pass `s3://...` paths to `cognee.add()` to load data directly from S3 * **Store Cognee data on S3**: Set your data/system roots to S3 URLs to keep all files on S3 * **S3-compatible**: Works with MinIO and other S3-compatible services [​](https://docs.cognee.ai/guides/s3-storage#prerequisites) Prerequisites ---------------------------------------------------------------------------- Install with AWS extra if needed (boto3/s3fs) and add credentials to `.env`: Copy aws_access_key_id=your_access_key aws_secret_access_key=your_secret_key aws_region=us-east-1 # Optional for S3-compatible endpoints (e.g., MinIO): aws_endpoint_url=http://localhost:9000 [​](https://docs.cognee.ai/guides/s3-storage#option-a:-ingest-from-s3) Option A: Ingest from S3 -------------------------------------------------------------------------------------------------- Pass S3 URIs (files or prefixes) directly to `add()`. Directories/prefixes expand to files when credentials are set. Copy import asyncio import cognee async def main(): # Single file await cognee.add("s3://my-bucket/docs/paper.pdf") # Folder/prefix (recursively expands) await cognee.add("s3://my-bucket/datasets/reports/") # Mixed list await cognee.add([\ "s3://my-bucket/docs/paper.pdf",\ "Some inline text to ingest",\ ]) # Process the data await cognee.cognify() if __name__ == "__main__": asyncio.run(main()) This loads data directly from S3 using the `s3://` URI. Directory expansion lists S3 keys and filters out folders, while file I/O streams from S3 using `s3fs`. This simple example uses S3 paths for demonstration. In practice, you can mix S3 files with local files, use dataset scoping, and apply custom loaders - the same options work with S3 paths. [​](https://docs.cognee.ai/guides/s3-storage#option-b:-store-cognee-data-on-s3) Option B: Store Cognee Data on S3 -------------------------------------------------------------------------------------------------------------------- Keep Cognee’s generated files (text copies, system files) on S3 by pointing roots to S3 URLs. Add this to your `.env`: Copy DATA_ROOT_DIRECTORY="s3://my-bucket/cognee/data" SYSTEM_ROOT_DIRECTORY="s3://my-bucket/cognee/system" # Optional: force S3 backend detection STORAGE_BACKEND="s3" This configures Cognee to store all its internal files (processed data, system files) on S3 instead of locally. Cognee chooses S3 storage when roots start with `s3://` (or when `STORAGE_BACKEND=s3` and both roots are S3 URLs). Credentials from `.env` are required. [Core Concepts\ -------------\ \ Understand knowledge graph fundamentals](https://docs.cognee.ai/core-concepts/overview) [Setup Configuration\ -------------------\ \ Configure providers and databases](https://docs.cognee.ai/setup-configuration/overview) [API Reference\ -------------\ \ Explore API endpoints](https://docs.cognee.ai/api-reference/introduction) Was this page helpful? YesNo [Previous](https://docs.cognee.ai/guides/ontology-support) [Code GraphStep-by-step guide to building code-level graphs from repositories\ \ Next](https://docs.cognee.ai/guides/code-graph) ⌘I On this page * [What S3 Storage Does](https://docs.cognee.ai/guides/s3-storage#what-s3-storage-does) * [Prerequisites](https://docs.cognee.ai/guides/s3-storage#prerequisites) * [Option A: Ingest from S3](https://docs.cognee.ai/guides/s3-storage#option-a:-ingest-from-s3) * [Option B: Store Cognee Data on S3](https://docs.cognee.ai/guides/s3-storage#option-b:-store-cognee-data-on-s3) --- # Low-Level LLM - Cognee Documentation [Skip to main content](https://docs.cognee.ai/guides/low-level-llm#content-area) [Cognee Documentation home page![light logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20black.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=ea48b52be1df02b5909f780e6cd6856e)![dark logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20white.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=9f5bc18c4897c6e58b5cfa2b09bc079d)](https://docs.cognee.ai/) Search... ⌘K Search... Navigation Essentials Low-Level LLM [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) A minimal guide to the one function you can call directly to get Pydantic-validated structured output from an LLM. **Before you start:** * Complete [Quickstart](https://docs.cognee.ai/guides/getting-started/quickstart) to understand basic operations * Ensure you have [LLM Providers](https://docs.cognee.ai/guides/setup-configuration/llm-providers) configured * Have some text to process [​](https://docs.cognee.ai/guides/low-level-llm#what-it-is) What It Is ------------------------------------------------------------------------- * Single entrypoint: `LLMGateway.acreate_structured_output(text, system_prompt, response_model)` * Returns an instance of your Pydantic `response_model` filled by the LLM * Backend-agnostic: uses BAML or LiteLLM+Instructor under the hood based on config — your code doesn’t change This function is used by default during cognify via the extractor. The backend switch lives in `cognee/infrastructure/llm/LLMGateway.py`. [​](https://docs.cognee.ai/guides/low-level-llm#code-in-action) Code in Action --------------------------------------------------------------------------------- Copy import asyncio from pydantic import BaseModel from typing import List from cognee.infrastructure.llm.LLMGateway import LLMGateway class MiniEntity(BaseModel): name: str type: str class MiniGraph(BaseModel): nodes: List[MiniEntity] async def main(): system_prompt = ( "Extract entities as nodes with name and type. " "Use concise, literal values present in the text." ) text = "Apple develops iPhone; Audi produces the R8." result = await LLMGateway.acreate_structured_output(text, system_prompt, MiniGraph) print(result) # MiniGraph(nodes=[MiniEntity(name='Apple', type='Organization'), ...]) if __name__ == "__main__": asyncio.run(main()) This simple example uses a basic schema for demonstration. In practice, you can define complex Pydantic models with nested structures, validation rules, and custom types. [​](https://docs.cognee.ai/guides/low-level-llm#what-just-happened) What Just Happened ----------------------------------------------------------------------------------------- ### [​](https://docs.cognee.ai/guides/low-level-llm#step-1:-define-your-schema) Step 1: Define Your Schema Copy class MiniEntity(BaseModel): name: str type: str class MiniGraph(BaseModel): nodes: List[MiniEntity] Create Pydantic models that define the structure you want the LLM to return. The LLM will fill these models with data extracted from your text. ### [​](https://docs.cognee.ai/guides/low-level-llm#step-2:-write-a-system-prompt) Step 2: Write a System Prompt Copy system_prompt = ( "Extract entities as nodes with name and type. " "Use concise, literal values present in the text." ) Write a clear prompt that tells the LLM what to extract and how to structure it. Short, explicit prompts work best. ### [​](https://docs.cognee.ai/guides/low-level-llm#step-3:-call-the-llm) Step 3: Call the LLM Copy result = await LLMGateway.acreate_structured_output(text, system_prompt, MiniGraph) This calls the LLM with your text and prompt, returning a Pydantic model instance with the extracted data. A sync variant exists: `LLMGateway.create_structured_output(...)`. [​](https://docs.cognee.ai/guides/low-level-llm#custom-tasks) Custom Tasks ----------------------------------------------------------------------------- This function is often used when creating custom tasks for processing data with structured output. You’ll see it in action when we cover custom task creation in a future guide. [​](https://docs.cognee.ai/guides/low-level-llm#backend-doesn%E2%80%99t-matter) Backend Doesn’t Matter --------------------------------------------------------------------------------------------------------- The config decides the engine: * `STRUCTURED_OUTPUT_FRAMEWORK=instructor` → LiteLLM + Instructor * `STRUCTURED_OUTPUT_FRAMEWORK=baml` → BAML client/registry Both paths return the same Pydantic model instance to your code. [Structured Output\ -----------------\ \ Learn about structured output frameworks](https://docs.cognee.ai/setup-configuration/structured-output-backends) [Custom Prompts\ --------------\ \ Control extraction with custom prompts](https://docs.cognee.ai/guides/custom-prompts) [API Reference\ -------------\ \ Explore API endpoints](https://docs.cognee.ai/api-reference/introduction) Was this page helpful? YesNo [Previous](https://docs.cognee.ai/guides/graph-visualization) [Memify QuickstartStep-by-step guide to enriching existing knowledge graphs with derived facts\ \ Next](https://docs.cognee.ai/guides/memify-quickstart) ⌘I On this page * [What It Is](https://docs.cognee.ai/guides/low-level-llm#what-it-is) * [Code in Action](https://docs.cognee.ai/guides/low-level-llm#code-in-action) * [What Just Happened](https://docs.cognee.ai/guides/low-level-llm#what-just-happened) * [Step 1: Define Your Schema](https://docs.cognee.ai/guides/low-level-llm#step-1:-define-your-schema) * [Step 2: Write a System Prompt](https://docs.cognee.ai/guides/low-level-llm#step-2:-write-a-system-prompt) * [Step 3: Call the LLM](https://docs.cognee.ai/guides/low-level-llm#step-3:-call-the-llm) * [Custom Tasks](https://docs.cognee.ai/guides/low-level-llm#custom-tasks) * [Backend Doesn’t Matter](https://docs.cognee.ai/guides/low-level-llm#backend-doesn%E2%80%99t-matter) --- # Ontology Quickstart - Cognee Documentation [Skip to main content](https://docs.cognee.ai/guides/ontology-support#content-area) [Cognee Documentation home page![light logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20black.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=ea48b52be1df02b5909f780e6cd6856e)![dark logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20white.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=9f5bc18c4897c6e58b5cfa2b09bc079d)](https://docs.cognee.ai/) Search... ⌘K Search... Navigation Essentials Ontology Quickstart [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) A minimal guide to using OWL ontologies to ground Cognee’s knowledge graphs. You’ll point Cognee at an ontology file during cognify and then ask ontology-aware questions. **Before you start:** * Complete [Quickstart](https://docs.cognee.ai/guides/getting-started/quickstart) to understand basic operations * Read [Ontologies](https://docs.cognee.ai/core-concepts/further-concepts/ontologies) to understand the concepts * Ensure you have [LLM Providers](https://docs.cognee.ai/guides/setup-configuration/llm-providers) configured * Have an OWL ontology file (`.owl`) in RDF/XML format * Have some text or files relevant to the ontology’s domain [​](https://docs.cognee.ai/guides/ontology-support#what-ontology-support-does) What Ontology Support Does ------------------------------------------------------------------------------------------------------------ * Grounds entities and relations to your OWL ontology (classes, individuals, properties) * Validates types via ontology domains/ranges and class hierarchy * Improves graph completion answers for domain-specific queries [​](https://docs.cognee.ai/guides/ontology-support#step-1:-prepare-an-ontology-file) Step 1: Prepare an Ontology File ------------------------------------------------------------------------------------------------------------------------ Start from a simple OWL file. Minimal ingredients: * Classes (e.g., `TechnologyCompany`, `Car`) * Individuals (e.g., `Apple`, `Audi`) * Object properties with domain/range (e.g., `produces` with `domain=CarManufacturer`, `range=Car`) Example ontology files: * `examples/python/ontology_input_example/basic_ontology.owl` * `examples/python/ontology_input_example/enriched_medical_ontology_with_classes.owl` Use any RDF/OWL editor (Protégé) to edit .owl files. This example uses a simple ontology for demonstration. In practice, you can work with larger, more complex ontologies - the same approach works regardless of ontology size or complexity. [​](https://docs.cognee.ai/guides/ontology-support#step-2:-add-your-data) Step 2: Add Your Data -------------------------------------------------------------------------------------------------- Add either raw text or a directory. Keep it relevant to your ontology. Copy import cognee texts = [\ "Audi produces the R8 and e-tron.",\ "Apple develops iPhone and MacBook."\ ] await cognee.add(texts) # or: await cognee.add("/path/to/folder/of/files") This simple example uses a list of strings for demonstration. In practice, you can add multiple documents, files, or entire datasets - the ontology processing works the same way across all your data. [​](https://docs.cognee.ai/guides/ontology-support#step-3:-cognify-your-data-+-ontologies) Step 3: Cognify Your Data + Ontologies ------------------------------------------------------------------------------------------------------------------------------------ Create the `config` which contains the information about the ontology, to ground extracted entities/relations to the ontology. Then, simply pass the `config` to the `cognify` operation. Copy import os from cognee.modules.ontology.ontology_config import Config from cognee.modules.ontology.rdf_xml.RDFLibOntologyResolver import RDFLibOntologyResolver ontology_path = os.path.join( os.path.dirname(os.path.abspath(__file__)), "ontology_input_example/basic_ontology.owl" ) # Create full config structure manually config: Config = { "ontology_config": { "ontology_resolver": RDFLibOntologyResolver(ontology_file=ontology_path) } } await cognee.cognify(config=config) If omitted, Cognee builds a graph without ontology grounding. With an ontology, Cognee aligns nodes to classes/individuals and enforces property domain/range. [​](https://docs.cognee.ai/guides/ontology-support#step-4:-ask-ontology-aware-questions) Step 4: Ask Ontology-aware Questions -------------------------------------------------------------------------------------------------------------------------------- Use `SearchType.GRAPH_COMPLETION` to get answers that leverage ontology structure. Copy from cognee.api.v1.search import SearchType result = await cognee.search( query_type=SearchType.GRAPH_COMPLETION, query_text="What cars and their types are produced by Audi?", ) print(result) Phrase questions using ontology terms (class names, individual names, property language like “produces”, “develops”). If results feel generic, check that the ontology contains the expected classes/individuals and that your data mentions them. [​](https://docs.cognee.ai/guides/ontology-support#code-in-action) Code in Action ------------------------------------------------------------------------------------ * Small cars/tech demo: `examples/python/ontology_demo_example.py` * Medical comparison demo: `examples/python/ontology_demo_example_2.py` [Core Concepts\ -------------\ \ Understand ontology fundamentals](https://docs.cognee.ai/core-concepts/further-concepts/ontologies) [API Reference\ -------------\ \ Explore ontology API endpoints](https://docs.cognee.ai/api-reference/introduction) Was this page helpful? YesNo [Previous](https://docs.cognee.ai/guides/time-awareness) [S3 StorageStep-by-step guide to using S3 for data ingestion and storage\ \ Next](https://docs.cognee.ai/guides/s3-storage) ⌘I On this page * [What Ontology Support Does](https://docs.cognee.ai/guides/ontology-support#what-ontology-support-does) * [Step 1: Prepare an Ontology File](https://docs.cognee.ai/guides/ontology-support#step-1:-prepare-an-ontology-file) * [Step 2: Add Your Data](https://docs.cognee.ai/guides/ontology-support#step-2:-add-your-data) * [Step 3: Cognify Your Data + Ontologies](https://docs.cognee.ai/guides/ontology-support#step-3:-cognify-your-data-+-ontologies) * [Step 4: Ask Ontology-aware Questions](https://docs.cognee.ai/guides/ontology-support#step-4:-ask-ontology-aware-questions) * [Code in Action](https://docs.cognee.ai/guides/ontology-support#code-in-action) --- # Code Graph - Cognee Documentation [Skip to main content](https://docs.cognee.ai/guides/code-graph#content-area) [Cognee Documentation home page![light logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20black.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=ea48b52be1df02b5909f780e6cd6856e)![dark logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20white.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=9f5bc18c4897c6e58b5cfa2b09bc079d)](https://docs.cognee.ai/) Search... ⌘K Search... Navigation Essentials Code Graph [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) A minimal guide to building a code-level graph from a repository and searching it. The pipeline parses your repo, extracts code entities and dependencies, and optionally processes non-code docs alongside. **Before you start:** * Complete [Quickstart](https://docs.cognee.ai/guides/getting-started/quickstart) to understand basic operations * Ensure you have [LLM Providers](https://docs.cognee.ai/guides/setup-configuration/llm-providers) configured * Have a local repository path (absolute or relative) [​](https://docs.cognee.ai/guides/code-graph#what-code-graph-does) What Code Graph Does ------------------------------------------------------------------------------------------ * Scans a repo for supported languages and builds code nodes/edges (files, symbols, imports, call/dependency links) * Optional: includes non-code files (markdown, docs) as a standard knowledge graph * Enables `SearchType.CODE` for code-aware queries [​](https://docs.cognee.ai/guides/code-graph#code-in-action) Code in Action ------------------------------------------------------------------------------ Copy import asyncio import cognee from cognee import SearchType from cognee.api.v1.cognify.code_graph_pipeline import run_code_graph_pipeline async def main(): repo_path = "/path/to/your/repo" # folder root # Build the code graph (code only) async for _ in run_code_graph_pipeline(repo_path, include_docs=False): pass # Ask a code question results = await cognee.search(query_type=SearchType.CODE, query_text="Where is Foo used?") print(results) asyncio.run(main()) This simple example uses a basic repository for demonstration. In practice, you can process large codebases with multiple languages and complex dependency structures. [​](https://docs.cognee.ai/guides/code-graph#what-just-happened) What Just Happened -------------------------------------------------------------------------------------- ### [​](https://docs.cognee.ai/guides/code-graph#step-1:-build-the-code-graph) Step 1: Build the Code Graph Copy async for _ in run_code_graph_pipeline(repo_path, include_docs=False): pass This scans your repository for supported languages and builds code nodes/edges. The pipeline handles file parsing, symbol extraction, and dependency analysis automatically. ### [​](https://docs.cognee.ai/guides/code-graph#step-2:-search-your-code) Step 2: Search Your Code Copy results = await cognee.search(query_type=SearchType.CODE, query_text="Where is Foo used?") Use `SearchType.CODE` to ask code-aware questions about your repository. This searches through the extracted code structure, not just text content. [​](https://docs.cognee.ai/guides/code-graph#include-documentation-optional) Include Documentation (Optional) ---------------------------------------------------------------------------------------------------------------- Also process non-code files from the repo (slower, uses LLM for text): Copy async for _ in run_code_graph_pipeline(repo_path, include_docs=True): pass This processes markdown files, documentation, and other text files alongside your code, creating a comprehensive knowledge graph. [​](https://docs.cognee.ai/guides/code-graph#advanced-options) Advanced Options ---------------------------------------------------------------------------------- Copy async for _ in run_code_graph_pipeline( repo_path, include_docs=False, excluded_paths=["**/node_modules/**", "**/dist/**"], supported_languages=["python", "typescript"], ): pass * **`excluded_paths`**: List of paths (globs) to skip, e.g., tests, build folders * **`supported_languages`**: Narrow to certain languages to speed up processing [​](https://docs.cognee.ai/guides/code-graph#visualize-your-graph-optional) Visualize Your Graph (Optional) -------------------------------------------------------------------------------------------------------------- Copy from cognee.api.v1.visualize.visualize import visualize_graph await visualize_graph("./graph_code.html") Generate an HTML visualization of your code graph to explore the structure and relationships. [​](https://docs.cognee.ai/guides/code-graph#what-happens-under-the-hood) What Happens Under the Hood -------------------------------------------------------------------------------------------------------- `run_code_graph_pipeline(...)` automatically handles: * Repository scanning and file parsing * Code entity extraction (functions, classes, imports, calls) * Dependency analysis and relationship mapping * Database initialization and setup * Optional documentation processing with LLM Once complete, your code graph is ready for search and analysis. [Custom Tasks\ ------------\ \ Learn about custom tasks and pipelines](https://docs.cognee.ai/guides/custom-tasks-pipelines) [Core Concepts\ -------------\ \ Understand knowledge graph fundamentals](https://docs.cognee.ai/core-concepts/overview) [API Reference\ -------------\ \ Explore API endpoints](https://docs.cognee.ai/api-reference/introduction) Was this page helpful? YesNo [Previous](https://docs.cognee.ai/guides/s3-storage) [Graph VisualizationStep-by-step guide to rendering interactive knowledge graphs\ \ Next](https://docs.cognee.ai/guides/graph-visualization) ⌘I On this page * [What Code Graph Does](https://docs.cognee.ai/guides/code-graph#what-code-graph-does) * [Code in Action](https://docs.cognee.ai/guides/code-graph#code-in-action) * [What Just Happened](https://docs.cognee.ai/guides/code-graph#what-just-happened) * [Step 1: Build the Code Graph](https://docs.cognee.ai/guides/code-graph#step-1:-build-the-code-graph) * [Step 2: Search Your Code](https://docs.cognee.ai/guides/code-graph#step-2:-search-your-code) * [Include Documentation (Optional)](https://docs.cognee.ai/guides/code-graph#include-documentation-optional) * [Advanced Options](https://docs.cognee.ai/guides/code-graph#advanced-options) * [Visualize Your Graph (Optional)](https://docs.cognee.ai/guides/code-graph#visualize-your-graph-optional) * [What Happens Under the Hood](https://docs.cognee.ai/guides/code-graph#what-happens-under-the-hood) --- # Distributed Execution - Cognee Documentation [Skip to main content](https://docs.cognee.ai/guides/distributed-execution#content-area) [Cognee Documentation home page![light logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20black.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=ea48b52be1df02b5909f780e6cd6856e)![dark logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20white.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=9f5bc18c4897c6e58b5cfa2b09bc079d)](https://docs.cognee.ai/) Search... ⌘K Search... Navigation Essentials Distributed Execution [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) A minimal guide to running Cognee pipelines across [Modal](https://modal.com/docs) containers with a one-line toggle. Good fit for large batches or slow tasks. **Before you start:** * Complete [Quickstart](https://docs.cognee.ai/guides/getting-started/quickstart) to understand basic operations * Ensure you have [LLM Providers](https://docs.cognee.ai/guides/setup-configuration/llm-providers) configured * Have a Modal account and tokens configured locally (`modal setup`) * Create a Modal Secret named `distributed_cognee` with your environment variables [​](https://docs.cognee.ai/guides/distributed-execution#what-distributed-execution-does) What Distributed Execution Does --------------------------------------------------------------------------------------------------------------------------- * Distributes per-item task execution to Modal functions * Keeps your code unchanged; you can keep using `add` → `cognify` → `search` or custom pipelines * Scales processing across multiple containers for large datasets [​](https://docs.cognee.ai/guides/distributed-execution#what-is-modal) What is Modal? ---------------------------------------------------------------------------------------- [Modal](https://modal.com/docs) is a serverless cloud platform that provides compute-intensive applications without thinking about infrastructure. It’s perfect for running generative AI models, large-scale batch workflows, and job queues at scale. When you enable distributed execution, Cognee automatically uses Modal to run your processing tasks across multiple containers, making it much faster for large datasets. [​](https://docs.cognee.ai/guides/distributed-execution#prerequisites) Prerequisites --------------------------------------------------------------------------------------- Install extras with Modal support and configure your environment: Copy # Install with distributed support pip install cognee[distributed] # Configure Modal (creates account if needed) modal setup # Create Modal Secret with your environment variables modal secret create distributed_cognee Add your environment variables to the Modal Secret (e.g., `LLM_API_KEY`, DB configs, S3 creds if used). [​](https://docs.cognee.ai/guides/distributed-execution#code-in-action) Code in Action ----------------------------------------------------------------------------------------- Copy import asyncio import cognee from cognee import SearchType async def main(): # COGNEE_DISTRIBUTED=true is picked up implicitly # 1) Add data (text, files, or S3 URIs) await cognee.add([\ "Alice knows Bob. Bob works at ACME.",\ "NLP is a subfield of computer science.",\ ], dataset_name="dist_demo") # 2) Build the knowledge graph (runs distributed) await cognee.cognify(datasets=["dist_demo"]) # 3) Query answers = await cognee.search( query_type=SearchType.GRAPH_COMPLETION, query_text="Who does Alice know?", top_k=5, ) print(answers) asyncio.run(main()) This simple example uses basic text data for demonstration. In practice, you can process large datasets, files, or S3 URIs - the distributed execution scales automatically across Modal containers. [​](https://docs.cognee.ai/guides/distributed-execution#what-just-happened) What Just Happened ------------------------------------------------------------------------------------------------- ### [​](https://docs.cognee.ai/guides/distributed-execution#step-1:-enable-distribution) Step 1: Enable Distribution Copy export COGNEE_DISTRIBUTED=true python your_script.py Set the environment variable and run your code as usual. Internally, pipelines switch from `run_tasks` to `run_tasks_distributed` (Modal) via this toggle. ### [​](https://docs.cognee.ai/guides/distributed-execution#step-2:-add-your-data) Step 2: Add Your Data Copy await cognee.add([\ "Alice knows Bob. Bob works at ACME.",\ "NLP is a subfield of computer science.",\ ], dataset_name="dist_demo") Add your data using the standard `add` function. The same approach works with files, S3 URIs, or large datasets. ### [​](https://docs.cognee.ai/guides/distributed-execution#step-3:-process-distributed) Step 3: Process Distributed Copy await cognee.cognify(datasets=["dist_demo"]) The `cognify` operation automatically runs distributed across Modal containers when `COGNEE_DISTRIBUTED=true` is set. ### [​](https://docs.cognee.ai/guides/distributed-execution#step-4:-search-your-data) Step 4: Search Your Data Copy answers = await cognee.search( query_type=SearchType.GRAPH_COMPLETION, query_text="Who does Alice know?", top_k=5, ) Search your processed data using the standard search methods. The results are the same whether processed locally or distributed. [​](https://docs.cognee.ai/guides/distributed-execution#what-happens-under-the-hood) What Happens Under the Hood ------------------------------------------------------------------------------------------------------------------- When `COGNEE_DISTRIBUTED=true`: * Tasks are distributed to Modal functions automatically * Each task runs in its own container * Results are collected and merged back * Database schemas are created on first run * Costs are tracked in your Modal workspace Start small and confirm costs in your Modal workspace. For non-pipeline first calls that write to DBs, call `await setup()` once. [Deploy REST API\ ---------------\ \ Learn about API deployment](https://docs.cognee.ai/guides/deploy-rest-api-server) [Custom Tasks\ ------------\ \ Learn about custom tasks and pipelines](https://docs.cognee.ai/guides/custom-tasks-pipelines) [Core Concepts\ -------------\ \ Understand knowledge graph fundamentals](https://docs.cognee.ai/core-concepts/overview) Was this page helpful? YesNo [Previous](https://docs.cognee.ai/guides/memify-quickstart) [Feedback SystemStep-by-step guide to using feedback to improve Cognee's knowledge graphs\ \ Next](https://docs.cognee.ai/guides/feedback-system) ⌘I On this page * [What Distributed Execution Does](https://docs.cognee.ai/guides/distributed-execution#what-distributed-execution-does) * [What is Modal?](https://docs.cognee.ai/guides/distributed-execution#what-is-modal) * [Prerequisites](https://docs.cognee.ai/guides/distributed-execution#prerequisites) * [Code in Action](https://docs.cognee.ai/guides/distributed-execution#code-in-action) * [What Just Happened](https://docs.cognee.ai/guides/distributed-execution#what-just-happened) * [Step 1: Enable Distribution](https://docs.cognee.ai/guides/distributed-execution#step-1:-enable-distribution) * [Step 2: Add Your Data](https://docs.cognee.ai/guides/distributed-execution#step-2:-add-your-data) * [Step 3: Process Distributed](https://docs.cognee.ai/guides/distributed-execution#step-3:-process-distributed) * [Step 4: Search Your Data](https://docs.cognee.ai/guides/distributed-execution#step-4:-search-your-data) * [What Happens Under the Hood](https://docs.cognee.ai/guides/distributed-execution#what-happens-under-the-hood) --- # Memify Quickstart - Cognee Documentation [Skip to main content](https://docs.cognee.ai/guides/memify-quickstart#content-area) [Cognee Documentation home page![light logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20black.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=ea48b52be1df02b5909f780e6cd6856e)![dark logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20white.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=9f5bc18c4897c6e58b5cfa2b09bc079d)](https://docs.cognee.ai/) Search... ⌘K Search... Navigation Essentials Memify Quickstart [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) A minimal guide to running a small enrichment pass over your existing knowledge graph to add useful derived facts (e.g., coding rules) without re-ingesting data. **Before you start:** * Complete [Quickstart](https://docs.cognee.ai/guides/getting-started/quickstart) to understand basic operations * Ensure you have [LLM Providers](https://docs.cognee.ai/guides/setup-configuration/llm-providers) configured * Have an existing knowledge graph (add → cognify completed) [​](https://docs.cognee.ai/guides/memify-quickstart#what-memify-does) What Memify Does ----------------------------------------------------------------------------------------- * Pulls a subgraph (or whole graph) into a mini-pipeline * Applies enrichment tasks to create new nodes/edges from existing context * Defaults: extracts relevant chunks and adds coding rule associations [​](https://docs.cognee.ai/guides/memify-quickstart#code-in-action) Code in Action ------------------------------------------------------------------------------------- Copy import asyncio import cognee from cognee import SearchType async def main(): # 1) Add two short chats and build a graph await cognee.add([\ "We follow PEP8. Add type hints and docstrings.",\ "Releases should not be on Friday. Susan must review PRs.",\ ], dataset_name="rules_demo") await cognee.cognify(datasets=["rules_demo"]) # builds graph # 2) Enrich the graph (uses default memify tasks) await cognee.memify(dataset="rules_demo") # 3) Query the new coding rules rules = await cognee.search( query_type=SearchType.CODING_RULES, query_text="List coding rules", node_name=["coding_agent_rules"], ) print("Rules:", rules) asyncio.run(main()) This simple example uses basic text data for demonstration. In practice, you can enrich large knowledge graphs with complex derived facts and associations. [​](https://docs.cognee.ai/guides/memify-quickstart#what-just-happened) What Just Happened --------------------------------------------------------------------------------------------- ### [​](https://docs.cognee.ai/guides/memify-quickstart#step-1:-build-your-knowledge-graph) Step 1: Build Your Knowledge Graph Copy await cognee.add([\ "We follow PEP8. Add type hints and docstrings.",\ "Releases should not be on Friday. Susan must review PRs.",\ ], dataset_name="rules_demo") await cognee.cognify(datasets=["rules_demo"]) First, create your knowledge graph using the standard add → cognify workflow. Memify works on existing graphs, so you need this foundation first. ### [​](https://docs.cognee.ai/guides/memify-quickstart#step-2:-enrich-with-memify) Step 2: Enrich with Memify Copy await cognee.memify(dataset="rules_demo") This runs the default memify tasks on your existing graph. No data parameter means it processes the existing graph, optionally filtering with `node_name` and `node_type`. ### [​](https://docs.cognee.ai/guides/memify-quickstart#step-3:-query-enriched-data) Step 3: Query Enriched Data Copy rules = await cognee.search( query_type=SearchType.CODING_RULES, query_text="List coding rules", node_name=["coding_agent_rules"], ) Search for the newly created derived facts using specialized search types like `SearchType.CODING_RULES`. [​](https://docs.cognee.ai/guides/memify-quickstart#customizing-tasks-optional) Customizing Tasks (Optional) --------------------------------------------------------------------------------------------------------------- Copy from cognee.modules.pipelines.tasks.task import Task from cognee.tasks.memify.extract_subgraph_chunks import extract_subgraph_chunks from cognee.tasks.codingagents.coding_rule_associations import add_rule_associations await cognee.memify( extraction_tasks=[Task(extract_subgraph_chunks)], enrichment_tasks=[Task(add_rule_associations, rules_nodeset_name="coding_agent_rules")], dataset="rules_demo", ) You can customize the memify pipeline by specifying your own extraction and enrichment tasks. [​](https://docs.cognee.ai/guides/memify-quickstart#what-happens-under-the-hood) What Happens Under the Hood --------------------------------------------------------------------------------------------------------------- The default memify tasks are equivalent to: * **Extraction**: `Task(extract_subgraph_chunks)` - pulls relevant chunks from your graph * **Enrichment**: `Task(add_rule_associations, rules_nodeset_name="coding_agent_rules")` - creates new associations and rules This creates derived knowledge without re-processing your original data. [Custom Data Models\ ------------------\ \ Learn about custom data models](https://docs.cognee.ai/guides/custom-data-models) [Custom Tasks\ ------------\ \ Learn about custom tasks and pipelines](https://docs.cognee.ai/guides/custom-tasks-pipelines) [Core Concepts\ -------------\ \ Understand knowledge graph fundamentals](https://docs.cognee.ai/core-concepts/overview) Was this page helpful? YesNo [Previous](https://docs.cognee.ai/guides/low-level-llm) [Distributed ExecutionStep-by-step guide to running Cognee pipelines across Modal containers\ \ Next](https://docs.cognee.ai/guides/distributed-execution) ⌘I On this page * [What Memify Does](https://docs.cognee.ai/guides/memify-quickstart#what-memify-does) * [Code in Action](https://docs.cognee.ai/guides/memify-quickstart#code-in-action) * [What Just Happened](https://docs.cognee.ai/guides/memify-quickstart#what-just-happened) * [Step 1: Build Your Knowledge Graph](https://docs.cognee.ai/guides/memify-quickstart#step-1:-build-your-knowledge-graph) * [Step 2: Enrich with Memify](https://docs.cognee.ai/guides/memify-quickstart#step-2:-enrich-with-memify) * [Step 3: Query Enriched Data](https://docs.cognee.ai/guides/memify-quickstart#step-3:-query-enriched-data) * [Customizing Tasks (Optional)](https://docs.cognee.ai/guides/memify-quickstart#customizing-tasks-optional) * [What Happens Under the Hood](https://docs.cognee.ai/guides/memify-quickstart#what-happens-under-the-hood) --- # Temporal Cognify - Cognee Documentation [Skip to main content](https://docs.cognee.ai/guides/time-awareness#content-area) [Cognee Documentation home page![light logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20black.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=ea48b52be1df02b5909f780e6cd6856e)![dark logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20white.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=9f5bc18c4897c6e58b5cfa2b09bc079d)](https://docs.cognee.ai/) Search... ⌘K Search... Navigation Essentials Temporal Cognify [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) A minimal guide to Cognee’s temporal mode. If you already know the regular add → cognify → search flow, this adds one switch at cognify time and one search type for time-aware questions. **Before you start:** * Complete [Quickstart](https://docs.cognee.ai/guides/getting-started/quickstart) to understand basic operations * Ensure you have [LLM Providers](https://docs.cognee.ai/guides/setup-configuration/llm-providers) configured * Have data that contains dates/times (years or full dates) [​](https://docs.cognee.ai/guides/time-awareness#what-temporal-mode-does) What Temporal Mode Does ---------------------------------------------------------------------------------------------------- * Builds events and timestamps from your text during cognify * Lets you ask time-based questions like “before 1980”, “after 2010”, or “between 2000 and 2006” * Uses `SearchType.TEMPORAL` to retrieve the most relevant events and answer with temporal context [​](https://docs.cognee.ai/guides/time-awareness#step-1:-add-data) Step 1: Add Data -------------------------------------------------------------------------------------- Add data with temporal information using the standard `add` function. Copy import cognee text = """ In 1998 the project launched. In 2001 version 1.0 shipped. In 2004 the team merged with another group. In 2010 support for v1 ended. """ await cognee.add(text, dataset_name="timeline_demo") This simple example uses one string that gets treated as a single document. In practice, you can add multiple documents, files, or entire datasets - the temporal processing works the same way across all your data. [​](https://docs.cognee.ai/guides/time-awareness#step-2:-cognify-with-temporal-mode) Step 2: Cognify with Temporal Mode -------------------------------------------------------------------------------------------------------------------------- Set `temporal_cognify=True` to extract events/timestamps instead of the default entity-graph pipeline. Copy await cognee.cognify(datasets=["timeline_demo"], temporal_cognify=True) Only datasets you pass (or all by default) are processed. Temporal mode runs an event/timestamp pipeline and stores temporal nodes in the graph. This example uses a single dataset for simplicity. In practice, you can process multiple datasets simultaneously by passing a list of dataset names, or omit the `datasets` parameter to process all available datasets. [​](https://docs.cognee.ai/guides/time-awareness#step-3:-ask-time-aware-questions) Step 3: Ask Time-aware Questions ---------------------------------------------------------------------------------------------------------------------- Use `SearchType.TEMPORAL` and phrase your query with time hints. Copy from cognee.api.v1.search import SearchType # Before / after queries await cognee.search( query_type=SearchType.TEMPORAL, query_text="What happened before 2000?", top_k=10 ) await cognee.search( query_type=SearchType.TEMPORAL, query_text="What happened after 2010?", top_k=10 ) # Between queries await cognee.search( query_type=SearchType.TEMPORAL, query_text="Events between 2001 and 2004", top_k=10 ) # Scoped descriptions await cognee.search( query_type=SearchType.TEMPORAL, query_text="Key project milestones between 1998 and 2010", top_k=10 ) * If the query has clear dates, the retriever filters events by time and ranks them * If no dates are detected, it falls back to event/entity graph retrieval and still answers * Increase `top_k` to inspect more candidate events [​](https://docs.cognee.ai/guides/time-awareness#optional:-limit-to-specific-datasets) Optional: Limit to Specific Datasets ------------------------------------------------------------------------------------------------------------------------------ Copy await cognee.search( query_type=SearchType.TEMPORAL, query_text="What happened after 2004?", datasets=["timeline_demo"], top_k=10, ) [​](https://docs.cognee.ai/guides/time-awareness#using-the-http-api) Using the HTTP API ------------------------------------------------------------------------------------------ If your server is running, you can run temporal search via the API by setting `search_type` to `"TEMPORAL"`: Copy curl -X POST "http://localhost:8000/api/v1/search" \ -H "Content-Type: application/json" \ ${TOKEN:+-H "Authorization: Bearer $TOKEN"} \ -d '{ "search_type": "TEMPORAL", "query": "What happened between 2001 and 2004?", "top_k": 10 }' For now, enabling temporal processing at cognify time is easiest in Python with `temporal_cognify=True`. [​](https://docs.cognee.ai/guides/time-awareness#code-in-action) Code in Action ---------------------------------------------------------------------------------- Check `examples/python/temporal_example.py` for a complete script that: * Adds two biographies (with dates) * Runs `cognee.cognify(temporal_cognify=True)` * Queries with `SearchType.TEMPORAL` for time-aware answers [Core Concepts\ -------------\ \ Understand knowledge graph fundamentals](https://docs.cognee.ai/core-concepts/overview) [API Reference\ -------------\ \ Explore temporal API endpoints](https://docs.cognee.ai/api-reference/introduction) Was this page helpful? YesNo [Previous](https://docs.cognee.ai/guides/deploy-rest-api-server) [Ontology QuickstartStep-by-step guide to using OWL ontologies to ground Cognee knowledge graphs\ \ Next](https://docs.cognee.ai/guides/ontology-support) ⌘I On this page * [What Temporal Mode Does](https://docs.cognee.ai/guides/time-awareness#what-temporal-mode-does) * [Step 1: Add Data](https://docs.cognee.ai/guides/time-awareness#step-1:-add-data) * [Step 2: Cognify with Temporal Mode](https://docs.cognee.ai/guides/time-awareness#step-2:-cognify-with-temporal-mode) * [Step 3: Ask Time-aware Questions](https://docs.cognee.ai/guides/time-awareness#step-3:-ask-time-aware-questions) * [Optional: Limit to Specific Datasets](https://docs.cognee.ai/guides/time-awareness#optional:-limit-to-specific-datasets) * [Using the HTTP API](https://docs.cognee.ai/guides/time-awareness#using-the-http-api) * [Code in Action](https://docs.cognee.ai/guides/time-awareness#code-in-action) --- # Deploy REST API Server - Cognee Documentation [Skip to main content](https://docs.cognee.ai/guides/deploy-rest-api-server#content-area) [Cognee Documentation home page![light logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20black.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=ea48b52be1df02b5909f780e6cd6856e)![dark logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20white.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=9f5bc18c4897c6e58b5cfa2b09bc079d)](https://docs.cognee.ai/) Search... ⌘K Search... Navigation Essentials Deploy REST API Server [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) Deploy Cognee as a REST API server to expose its functionality via HTTP endpoints. [​](https://docs.cognee.ai/guides/deploy-rest-api-server#setup) Setup ------------------------------------------------------------------------ Copy # Clone repository git clone https://github.com/topoteretes/cognee.git cd cognee # Configure environment cp .env.template .env Edit `.env` with your preferred configuration. See [Setup Configuration](https://docs.cognee.ai/guides/setup-configuration/overview) guides for all available options. [​](https://docs.cognee.ai/guides/deploy-rest-api-server#deployment-methods) Deployment Methods -------------------------------------------------------------------------------------------------- * Docker * Python (Local) ### [​](https://docs.cognee.ai/guides/deploy-rest-api-server#start-server) Start Server Copy # Start API server docker compose up --build cognee # Check status docker compose ps [​](https://docs.cognee.ai/guides/deploy-rest-api-server#access-api) Access API ---------------------------------------------------------------------------------- * **API:** [http://localhost:8000](http://localhost:8000/) * **Documentation:** [http://localhost:8000/docs](http://localhost:8000/docs) [​](https://docs.cognee.ai/guides/deploy-rest-api-server#authentication) Authentication ------------------------------------------------------------------------------------------ If `REQUIRE_AUTHENTICATION=true` in your `.env` file: 1. **Register:** `POST /api/v1/auth/register` 2. **Login:** `POST /api/v1/auth/login` 3. **Use token:** Include `Authorization: Bearer ` header or use cookies [​](https://docs.cognee.ai/guides/deploy-rest-api-server#api-examples) API Examples -------------------------------------------------------------------------------------- Authentication **Register a user:** Copy curl -X POST "http://localhost:8000/api/v1/auth/register" \ -H "Content-Type: application/json" \ -d '{"email": "user1@example.com", "password": "strong_password"}' **Login and get token:** Copy TOKEN="$(curl -s -X POST http://localhost:8000/api/v1/auth/login \ -H 'Content-Type: application/x-www-form-urlencoded' \ -d 'username=user1@example.com&password=strong_password' | jq -r .access_token)" Dataset Management **Create a dataset:** Copy curl -X POST http://localhost:8000/api/v1/datasets \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $TOKEN" \ -d '{"name": "project_docs"}' **List datasets:** Copy curl -H "Authorization: Bearer $TOKEN" http://localhost:8000/api/v1/datasets Data Operations **Add data (upload file):** Copy curl -X POST http://localhost:8000/api/v1/add \ -H "Authorization: Bearer $TOKEN" \ -F "data=@/absolute/path/to/file.pdf" \ -F "datasetName=project_docs" **Build knowledge graph:** Copy curl -X POST http://localhost:8000/api/v1/cognify \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $TOKEN" \ -d '{"datasets": ["project_docs"]}' **Search data:** Copy curl -X POST http://localhost:8000/api/v1/search \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $TOKEN" \ -d '{"query": "What are the main topics?", "datasets": ["project_docs"], "top_k": 10}' Multi-tenant Operations **Create tenant:** Copy curl -X POST "http://localhost:8000/api/v1/permissions/tenants?tenant_name=acme" \ -H "Authorization: Bearer $TOKEN" **Add user to tenant:** Copy curl -X POST "http://localhost:8000/api/v1/permissions/users//tenants?tenant_id=" \ -H "Authorization: Bearer $TOKEN" **Create role:** Copy curl -X POST "http://localhost:8000/api/v1/permissions/roles?role_name=editor" \ -H "Authorization: Bearer $TOKEN" **Assign user to role:** Copy curl -X POST "http://localhost:8000/api/v1/permissions/users//roles?role_id=" \ -H "Authorization: Bearer $TOKEN" **Grant dataset permissions:** Copy curl -X POST "http://localhost:8000/api/v1/permissions/datasets/?permission_name=read&dataset_ids=&dataset_ids=" \ -H "Authorization: Bearer $TOKEN" [API Reference\ -------------\ \ Explore all API endpoints](https://docs.cognee.ai/api-reference/introduction) [Setup Configuration\ -------------------\ \ Configure providers and databases](https://docs.cognee.ai/setup-configuration/overview) [MCP Integration\ ---------------\ \ Set up AI assistant integration](https://docs.cognee.ai/cognee-mcp/mcp-overview) Was this page helpful? YesNo [Previous](https://docs.cognee.ai/guides/search-basics) [Temporal CognifyStep-by-step guide to using temporal mode for time-aware queries\ \ Next](https://docs.cognee.ai/guides/time-awareness) ⌘I On this page * [Setup](https://docs.cognee.ai/guides/deploy-rest-api-server#setup) * [Deployment Methods](https://docs.cognee.ai/guides/deploy-rest-api-server#deployment-methods) * [Access API](https://docs.cognee.ai/guides/deploy-rest-api-server#access-api) * [Authentication](https://docs.cognee.ai/guides/deploy-rest-api-server#authentication) * [API Examples](https://docs.cognee.ai/guides/deploy-rest-api-server#api-examples) --- # Cognee Walkthrough - Cognee Documentation [Skip to main content](https://docs.cognee.ai/examples/getting-started-with-cognee#content-area) [Cognee Documentation home page![light logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20black.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=ea48b52be1df02b5909f780e6cd6856e)![dark logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20white.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=9f5bc18c4897c6e58b5cfa2b09bc079d)](https://docs.cognee.ai/) Search... ⌘K Search... Navigation Tutorials Cognee Walkthrough [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) Cognee gives you the tools to **build smarter AI agents** with context-aware memory. Use it to create a **queryable knowledge graph** powered by embeddings from your data. When retrieving data, your agent can reach up to **92.5% accuracy**. [​](https://docs.cognee.ai/examples/getting-started-with-cognee#what-you%E2%80%99ll-learn) What You’ll Learn --------------------------------------------------------------------------------------------------------------- In this tutorial, you’ll: * **Organize memory** with [nodesets](https://docs.cognee.ai/core-concepts/further-concepts/node-sets) and apply filters during retrieval * **Define your data model** using [ontology support](https://docs.cognee.ai/guides/ontology-support) * **Enhance memory** with contextual enrichment layers * **Visualize your graph** with [graph visualization](https://docs.cognee.ai/guides/graph-visualization) to explore stored knowledge * **Search smarter** by combining vector similarity with graph traversal * **Refine results** through interactive search and [feedback](https://docs.cognee.ai/guides/feedback-system) [​](https://docs.cognee.ai/examples/getting-started-with-cognee#example-use-case) Example Use Case ----------------------------------------------------------------------------------------------------- In this example, you will use a **Cognee-powered [Coding Assistant](https://docs.cognee.ai/examples/code-assistants) ** to get context-aware coding help. You can open [this example on a Google Colab Notebook](https://colab.research.google.com/drive/12Vi9zID-M3fpKpKiaqDBvkk98ElkRPWy?usp=sharing) and run the steps shown below to build your cognee memory interactively. [​](https://docs.cognee.ai/examples/getting-started-with-cognee#prerequisites) Prerequisites ----------------------------------------------------------------------------------------------- * OpenAI API key (or another supported LLM provider) > Cognee uses OpenAI’s GPT-5 model as default. Note that the OpenAI free tier does not satisfy the rate limit requirements. Please refer to our [LLM providers documentation](https://docs.cognee.ai/setup-configuration/llm-providers) > to use another provider. [​](https://docs.cognee.ai/examples/getting-started-with-cognee#setup) Setup ------------------------------------------------------------------------------- First, let’s set up the environment and import necessary modules.Utility Functions Setup Create a utility class to handle file downloads and visualization helpers: Copy class NotebookUtils: """Utility class for cognee demo - helper methods to keep the main notebook clean and focused.""" def __init__(self): """Initialize the NotebookUtils with default configurations.""" self.artifacts_dir = None self.assets_config = self._initialize_assets_config() def _initialize_assets_config(self) -> Dict[str, Tuple[str, str]]: """Initialize configuration mapping for remote assets to download from cognee repository.""" return { "human_agent_conversations": ( "/content/copilot_conversations.json", "https://raw.githubusercontent.com/topoteretes/cognee/main/notebooks/data/copilot_conversations.json", ), "python_zen_principles": ( "/content/zen_principles.md", "https://raw.githubusercontent.com/topoteretes/cognee/main/notebooks/data/zen_principles.md", ), "ontology": ( "/content/basic_ontology.owl", "https://raw.githubusercontent.com/topoteretes/cognee/main/examples/python/ontology_input_example/basic_ontology.owl", ), } def download_remote_file_if_not_exists(self, local_path: str, remote_url: str) -> str: """Download remote file if it doesn't exist locally to avoid unnecessary re-downloads.""" file_path = Path(local_path) if not file_path.exists(): file_path.parent.mkdir(parents=True, exist_ok=True) urllib.request.urlretrieve(remote_url, file_path) print(f"Downloaded: {file_path.name}") else: print(f"File already exists: {file_path.name}") return str(file_path) def load_json_file_content(self, file_path: str) -> Dict[str, Any]: """Load and parse JSON file content into a Python dictionary.""" with open(file_path, "r", encoding="utf-8") as file: return json.load(file) def load_text_file_content(self, file_path: str) -> str: """Load and return raw text content from a text file.""" with open(file_path, "r", encoding="utf-8") as file: return file.read() def preview_json_structure(self, json_data: Dict[str, Any], max_keys: int = 3) -> None: """Display formatted preview of JSON data structure and sample content.""" print("JSON Structure Preview:") pprint.pp(list(json_data.keys())[:max_keys]) if "conversations" in json_data and json_data["conversations"]: print("Sample conversation:") pprint.pp(json_data["conversations"][0]) def preview_text_content(self, text_content: str, max_chars: int = 200) -> None: """Display formatted preview of text content to show its format.""" print("Text Content Preview:") print(text_content[:max_chars]) if len(text_content) > max_chars: print(f"... (truncated, total length: {len(text_content)} characters)") def create_notebook_artifacts_directory(self, dir_name: str = "artifacts") -> Path: """Create and return artifacts directory for storing notebook outputs like graph visualizations.""" notebook_dir = Path.cwd() self.artifacts_dir = notebook_dir / dir_name self.artifacts_dir.mkdir(exist_ok=True) print(f"Artifacts directory created/verified at: {self.artifacts_dir}") return self.artifacts_dir def download_remote_assets(self) -> Dict[str, str]: """Download all remote assets from cognee repository and return their local file paths.""" downloaded_assets = {} print("Downloading remote assets...") print("-" * 40) for asset_name, (local_path, remote_url) in self.assets_config.items(): downloaded_assets[asset_name] = self.download_remote_file_if_not_exists( local_path, remote_url ) print("-" * 40) print(f"Successfully processed {len(downloaded_assets)} assets") return downloaded_assets def preview_downloaded_assets(self, asset_paths: Dict[str, str]) -> None: """Display comprehensive preview of all downloaded assets.""" print("=== ASSET PREVIEWS ===\n") # Preview JSON files for asset_name, file_path in asset_paths.items(): if file_path.endswith('.json'): print(f"--- {asset_name.upper()} ---") json_data = self.load_json_file_content(file_path) self.preview_json_structure(json_data) print() # Preview text files for asset_name, file_path in asset_paths.items(): if file_path.endswith(('.md', '.txt')): print(f"--- {asset_name.upper()} ---") text_content = self.load_text_file_content(file_path) self.preview_text_content(text_content) print() # Preview OWL files for asset_name, file_path in asset_paths.items(): if file_path.endswith('.owl'): print(f"--- {asset_name.upper()} ---") print(f"OWL ontology file: {Path(file_path).name}") text_content = self.load_text_file_content(file_path) self.preview_text_content(text_content, max_chars=300) print() # Initialize the utility class utils = NotebookUtils() Install Cognee using pip: Copy !pip install cognee==0.3.4 # Create artifacts directory for storing visualization outputs artifacts_path = utils.create_notebook_artifacts_directory() import cognee [​](https://docs.cognee.ai/examples/getting-started-with-cognee#create-sample-data-to-ingest-into-memory) Create Sample Data to Ingest into Memory ----------------------------------------------------------------------------------------------------------------------------------------------------- In this example, we’ll use a **Python developer** scenario. The data sources we’ll ingest into Cognee include: * A short introduction about the developer (`developer_intro`) * A conversation between the developer and a coding agent (`human_agent_conversations`) * The Zen of Python principles (`python_zen_principles`) * A basic ontology file with structured data about common technologies (`ontology`) ### [​](https://docs.cognee.ai/examples/getting-started-with-cognee#prepare-the-sample-data) Prepare the Sample Data Copy # Define the developer introduction to simulate personal context developer_intro = ( "Hi, I'm an AI/Backend engineer. " "I build FastAPI services with Pydantic, heavy asyncio/aiohttp pipelines, " "and production testing via pytest-asyncio. " "I've shipped low-latency APIs on AWS, Azure, and GoogleCloud." ) # Download additional datasets from the Cognee repository asset_paths = utils.download_remote_assets() human_agent_conversations = asset_paths["human_agent_conversations"] python_zen_principles = asset_paths["python_zen_principles"] ontology_path = asset_paths["ontology"] The `download_remote_assets()` function: * Handles multiple file types (JSON, Markdown, ontology) * Creates the required folders automatically * Prevents redundant downloads [​](https://docs.cognee.ai/examples/getting-started-with-cognee#review-the-structure-and-content-of-downloaded-data) Review the Structure and Content of Downloaded Data --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Next, let’s inspect the data we just downloaded. Use `preview_downloaded_assets()` to quickly summarize and preview each file’s structure and contents before Cognee processes them. Copy # Preview each file's structure and contents utils.preview_downloaded_assets(asset_paths) [​](https://docs.cognee.ai/examples/getting-started-with-cognee#reset-memory-and-add-structured-data) Reset Memory and Add Structured Data --------------------------------------------------------------------------------------------------------------------------------------------- Start by resetting Cognee’s memory using `prune()` to ensure a clean, reproducible run. Then, use [`add()`](https://docs.cognee.ai/core-concepts/main-operations/add) to load your data into dedicated node sets for organized memory management. Copy await cognee.prune.prune_data() await cognee.prune.prune_system(metadata=True) await cognee.add(developer_intro, node_set=["developer_data"]) await cognee.add(human_agent_conversations, node_set=["developer_data"]) await cognee.add(python_zen_principles, node_set=["principles_data"]) [​](https://docs.cognee.ai/examples/getting-started-with-cognee#configure-the-ontology-and-build-a-knowledge-graph) Configure the Ontology and Build a Knowledge Graph ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Set the ontology file path, then run [`cognify()`](https://docs.cognee.ai/core-concepts/main-operations/cognify) to transform all data into a **knowledge graph** backed by embeddings. Cognee automatically loads the ontology configuration from the `ONTOLOGY_FILE_PATH` environment variable. Copy # Configure ontology file path for structured data processing os.environ["ONTOLOGY_FILE_PATH"] = ontology_path # Transform all data into a knowledge graph backed by embeddings await cognee.cognify() [​](https://docs.cognee.ai/examples/getting-started-with-cognee#visualize-and-inspect-the-graph-before-and-after-enrichment) Visualize and Inspect the Graph Before and After Enrichment ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Generate HTML visualizations of your knowledge graph to see how Cognee processed the data. First, visualize the initial graph structure. Then, use [`memify()`](https://docs.cognee.ai/core-concepts/main-operations/memify) to enhance the knowledge graph adding deeper semantic connections and improves relationships between concepts. Finally, generate a second visualization to compare the enriched graph. Copy # Generate initial graph visualization showing nodesets and ontology structure initial_graph_visualization_path = str(artifacts_path / "graph_visualization_nodesets_and_ontology.html") await cognee.visualize_graph(initial_graph_visualization_path) # Enhance the knowledge graph with memory consolidation for improved connections await cognee.memify() # Generate second graph visualization after memory enhancement enhanced_graph_visualization_path = str(artifacts_path / "graph_visualization_after_memify.html") await cognee.visualize_graph(enhanced_graph_visualization_path) The generated HTML files can be opened in your browser to explore and inspect the graph structure. [​](https://docs.cognee.ai/examples/getting-started-with-cognee#query-cognee-memory-with-natural-language) Query Cognee Memory with Natural Language ------------------------------------------------------------------------------------------------------------------------------------------------------- Run cross-document [searches](https://docs.cognee.ai/core-concepts/main-operations/search) to connect information across multiple data sources. Then, perform filtered searches within specific node sets to focus on targeted context. Copy # Cross-document knowledge retrieval from multiple data sources results = await cognee.search( query_text="How does my AsyncWebScraper implementation align with Python's design principles?", query_type=cognee.SearchType.GRAPH_COMPLETION, ) print("Python Pattern Analysis:", results) # Filtered search using NodeSet to query only specific subsets of memory from cognee.modules.engine.models.node_set import NodeSet results = await cognee.search( query_text="How should variables be named?", query_type=cognee.SearchType.GRAPH_COMPLETION, node_type=NodeSet, node_name=["principles_data"], ) print("Filtered search result:", results) [​](https://docs.cognee.ai/examples/getting-started-with-cognee#provide-interactive-feedback-for-continuous-learning) Provide Interactive Feedback for Continuous Learning ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Run a search with `save_interaction=True` to capture user feedback. Then, use the `FEEDBACK` query type to refine future retrievals and improve Cognee’s performance over time. Copy # Interactive search with feedback mechanism for continuous improvement answer = await cognee.search( query_type=cognee.SearchType.GRAPH_COMPLETION, query_text="What is the most zen thing about Python?", save_interaction=True, ) print("Initial answer:", answer) # Provide feedback on the previous search result # The last_k parameter specifies which previous answer to give feedback about feedback = await cognee.search( query_type=cognee.SearchType.FEEDBACK, query_text="Last result was useful, I like code that complies with best practices.", last_k=1, ) [​](https://docs.cognee.ai/examples/getting-started-with-cognee#visualize-the-graph-after-feedback) Visualize the Graph After Feedback ----------------------------------------------------------------------------------------------------------------------------------------- Generate a final visualization to see how the feedback mechanism improved the knowledge graph. Copy feedback_enhanced_graph_visualization_path = str( artifacts_path / "graph_visualization_after_feedback.html" ) await cognee.visualize_graph(feedback_enhanced_graph_visualization_path) This view highlights the enhanced connections and learning captured from user feedback. [​](https://docs.cognee.ai/examples/getting-started-with-cognee#next-steps) Next Steps ----------------------------------------------------------------------------------------- [Join the Community\ ------------------\ \ **Cognee Discord**Join over 1,000 builders to ask questions and share insights.](https://discord.gg/cqF6RhDYWz) [Explore Examples\ ----------------\ \ **GitHub Repository**Star our repo ⭐ and try additional examples to deepen your knowledge.](https://github.com/topoteretes/cognee) Was this page helpful? YesNo [Previous](https://docs.cognee.ai/examples/human-resources) [Cognee CLI OverviewCommand line interface for Cognee AI memory operations\ \ Next](https://docs.cognee.ai/cognee-cli/overview) ⌘I On this page * [What You’ll Learn](https://docs.cognee.ai/examples/getting-started-with-cognee#what-you%E2%80%99ll-learn) * [Example Use Case](https://docs.cognee.ai/examples/getting-started-with-cognee#example-use-case) * [Prerequisites](https://docs.cognee.ai/examples/getting-started-with-cognee#prerequisites) * [Setup](https://docs.cognee.ai/examples/getting-started-with-cognee#setup) * [Create Sample Data to Ingest into Memory](https://docs.cognee.ai/examples/getting-started-with-cognee#create-sample-data-to-ingest-into-memory) * [Prepare the Sample Data](https://docs.cognee.ai/examples/getting-started-with-cognee#prepare-the-sample-data) * [Review the Structure and Content of Downloaded Data](https://docs.cognee.ai/examples/getting-started-with-cognee#review-the-structure-and-content-of-downloaded-data) * [Reset Memory and Add Structured Data](https://docs.cognee.ai/examples/getting-started-with-cognee#reset-memory-and-add-structured-data) * [Configure the Ontology and Build a Knowledge Graph](https://docs.cognee.ai/examples/getting-started-with-cognee#configure-the-ontology-and-build-a-knowledge-graph) * [Visualize and Inspect the Graph Before and After Enrichment](https://docs.cognee.ai/examples/getting-started-with-cognee#visualize-and-inspect-the-graph-before-and-after-enrichment) * [Query Cognee Memory with Natural Language](https://docs.cognee.ai/examples/getting-started-with-cognee#query-cognee-memory-with-natural-language) * [Provide Interactive Feedback for Continuous Learning](https://docs.cognee.ai/examples/getting-started-with-cognee#provide-interactive-feedback-for-continuous-learning) * [Visualize the Graph After Feedback](https://docs.cognee.ai/examples/getting-started-with-cognee#visualize-the-graph-after-feedback) * [Next Steps](https://docs.cognee.ai/examples/getting-started-with-cognee#next-steps) --- # Search Basics - Cognee Documentation [Skip to main content](https://docs.cognee.ai/guides/search-basics#content-area) [Cognee Documentation home page![light logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20black.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=ea48b52be1df02b5909f780e6cd6856e)![dark logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20white.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=9f5bc18c4897c6e58b5cfa2b09bc079d)](https://docs.cognee.ai/) Search... ⌘K Search... Navigation Essentials Search Basics [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) A minimal guide to using `cognee.search()` to ask questions against your processed datasets. This guide shows the basic call and what each parameter does so you know which knob to turn. **Before you start:** * Complete [Quickstart](https://docs.cognee.ai/getting-started/quickstart) to understand basic operations * Ensure you have [LLM Providers](https://docs.cognee.ai/setup-configuration/llm-providers) configured for LLM-backed search types * Run `cognee.cognify(...)` to build the graph before searching * Keep at least one dataset with `read` permission for the user running the search [​](https://docs.cognee.ai/guides/search-basics#code-in-action) Code in Action --------------------------------------------------------------------------------- Copy import asyncio import cognee async def main(): # Make sure you've already run cognee.cognify(...) so the graph has content answers = await cognee.search( query_text="What are the main themes in my data?" ) for answer in answers: print(answer) asyncio.run(main()) `SearchType.GRAPH_COMPLETION` is the default, so you get an LLM-backed answer plus supporting context as soon as you have data in your graph. [​](https://docs.cognee.ai/guides/search-basics#what-just-happened) What Just Happened ----------------------------------------------------------------------------------------- The search call uses the default `SearchType.GRAPH_COMPLETION` mode to provide LLM-backed answers with supporting context from your knowledge graph. The results are returned as a list that you can iterate through and process as needed. [​](https://docs.cognee.ai/guides/search-basics#parameters-reference) Parameters Reference --------------------------------------------------------------------------------------------- Most examples below assume you are inside an async function. Import helpers when you need them: Copy from cognee import SearchType from cognee.modules.engine.models.node_set import NodeSet Core Parameters * **`query_text`** (str, required): The question or phrase you want answered. Copy answers = await cognee.search(query_text="Who owns the rollout plan?") * **`query_type`** (SearchType, optional, default: `SearchType.GRAPH_COMPLETION`): Switch search modes without changing your code flow. See [Search Types](https://docs.cognee.ai/core-concepts/main-operations/search) for the complete list. Copy await cognee.search( query_text="List coding guidelines", query_type=SearchType.CODING_RULES, ) * **`top_k`** (int, optional, default: 10): Cap how many ranked results you want back. Copy await cognee.search(query_text="Summaries please", top_k=3) Prompt & Generation Parameters * **`system_prompt_path`** (str, optional, default: `"answer_simple_question.txt"`): Point to a prompt file packaged with your project. Copy await cognee.search( query_text="Explain the roadmap in bullet points", system_prompt_path="prompts/bullets.txt", ) * **`system_prompt`** (Optional\[str\]): Inline override for experiments or dynamically generated prompts. Copy await cognee.search( query_text="Give me a confident answer", system_prompt="Answer succinctly and state confidence at the end.", ) * **`only_context`** (bool, optional, default: False): Skip LLM generation and just fetch supporting context chunks. Copy context = await cognee.search( query_text="What did we promise the client?", only_context=True, ) * **`use_combined_context`** (bool, optional, default: False): Collapse results into a single combined response when you query multiple datasets. Copy combined = await cognee.search( query_text="Quarterly financial highlights", datasets=["finance_q1", "finance_q2"], use_combined_context=True, ) `use_combined_context` should only be set when `ENABLE_BACKEND_ACCESS_CONTROL` is turned on. When access control is disabled, this parameter has no meaningful effect on dataset scoping. Node Sets & Filtering Parameters These options filter the graph down to the node sets you care about. In most workflows you set **both**: keep `node_type=NodeSet` and pass one or more set names in `node_name`—the same labels you used when calling `cognee.add(..., node_set=[...])`. * **`node_type`** (Optional\[Type\], optional, default: `NodeSet`): Controls which graph model to search. Leave this as `NodeSet` unless you’ve built a custom node model. * **`node_name`** (Optional\[List\[str\]\]): Names of the node sets to include. Cognee treats each string as a logical bucket of memories. Copy await cognee.search( query_text="What discounts did TechSupply offer?", node_type=NodeSet, node_name=["vendor_conversations"], ) Copy await cognee.search( query_text="Summarize procurement rules", node_type=NodeSet, node_name=["procurement_policies", "purchase_history"], ) Interaction & History Parameters * **`save_interaction`** (bool, optional, default: False): Persist the Q&A as a graph interaction for auditing or later review. Copy await cognee.search( query_text="Draft the release note", save_interaction=True, ) * **`last_k`** (Optional\[int\], optional, default: 1): When using `SearchType.FEEDBACK`, choose how many recent interactions to update with your feedback. Copy await cognee.search( query_text="Please improve the last answer", query_type=SearchType.FEEDBACK, last_k=3, ) Datasets & Users * **`datasets`** (Optional\[Union\[list\[str\], str\]\]): Limit search to dataset names you already know. Copy await cognee.search( query_text="Key risks", datasets=["risk_register", "exec_summary"], ) * **`dataset_ids`** (Optional\[Union\[list\[UUID\], UUID\]\]): Same as `datasets`, but with explicit UUIDs when names collide. Copy from uuid import UUID await cognee.search( query_text="Customer feedback", dataset_ids=[UUID("aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee")], ) * **`user`** (Optional\[User\]): Provide a user object when running multi-tenant flows or background jobs. Copy from cognee.modules.users.methods import get_user user = await get_user(user_id) await cognee.search(query_text="Team OKRs", user=user) **When** `ENABLE_BACKEND_ACCESS_CONTROL=true`: * **Result shape**: Searches run only on datasets the user can access and return either: * **Per dataset**: list of `{dataset_name, dataset_id, search_result}` * **Combined**: single `CombinedSearchResult` with merged snippets (`use_combined_context=True`) * If no `user` is given, `get_default_user()` is used (created if missing); errors only if this user lacks dataset permissions. * If `datasets` is not set, all datasets readable by the user are searched; errors if none are accessible or if requested datasets are forbidden. `PermissionDeniedError` will be raised unless you search with the same user that added the data or grant access to the default user. **When** `ENABLE_BACKEND_ACCESS_CONTROL=false` * Dataset filters (`datasets`, `dataset_ids`) are ignored — everything is searched. * Results normally come back as a plain list (`["answer1", "answer2"]`). * Setting `use_combined_context=True` here just wraps the same results in a `CombinedSearchResult` without changing them. [Custom Prompts\ --------------\ \ Learn about custom prompts for tailored answers](https://docs.cognee.ai/guides/custom-prompts) [Permission Snippets\ -------------------\ \ Multi-tenant deployment patterns](https://docs.cognee.ai/guides/permission-snippets) [API Reference\ -------------\ \ Explore all search types and parameters](https://docs.cognee.ai/api-reference/introduction) Was this page helpful? YesNo [Previous](https://docs.cognee.ai/setup-configuration/community-maintained/qdrant) [Deploy REST API ServerDeploy Cognee as a REST API server using Docker or Python\ \ Next](https://docs.cognee.ai/guides/deploy-rest-api-server) ⌘I On this page * [Code in Action](https://docs.cognee.ai/guides/search-basics#code-in-action) * [What Just Happened](https://docs.cognee.ai/guides/search-basics#what-just-happened) * [Parameters Reference](https://docs.cognee.ai/guides/search-basics#parameters-reference) --- # Feedback System - Cognee Documentation [Skip to main content](https://docs.cognee.ai/guides/feedback-system#content-area) [Cognee Documentation home page![light logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20black.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=ea48b52be1df02b5909f780e6cd6856e)![dark logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20white.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=9f5bc18c4897c6e58b5cfa2b09bc079d)](https://docs.cognee.ai/) Search... ⌘K Search... Navigation Essentials Feedback System [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) This guide shows you how to use Cognee’s feedback system to improve search results and knowledge graph quality. **Before you start:** * Complete [Quickstart](https://docs.cognee.ai/guides/getting-started/quickstart) to understand basic operations * Read [Search](https://docs.cognee.ai/guides/core-concepts/main-operations/search) to understand search types * Ensure you have [LLM Providers](https://docs.cognee.ai/guides/setup-configuration/llm-providers) configured for feedback processing [​](https://docs.cognee.ai/guides/feedback-system#example:-basic-feedback-loop) Example: Basic Feedback Loop --------------------------------------------------------------------------------------------------------------- This example shows how to provide feedback to improve future search results. ### [​](https://docs.cognee.ai/guides/feedback-system#step-1:-perform-search-with-interaction-saving) Step 1: Perform Search with Interaction Saving Copy import cognee from cognee import SearchType # Search with interaction saving enabled results = await cognee.search( query_text="What are the main themes in my data?", query_type=SearchType.GRAPH_COMPLETION, save_interaction=True # Required for feedback ) print("Search results:", results) ### [​](https://docs.cognee.ai/guides/feedback-system#step-2:-provide-positive-feedback) Step 2: Provide Positive Feedback Copy # Provide positive feedback await cognee.search( query_text="Excellent analysis, very comprehensive and accurate!", query_type=SearchType.FEEDBACK, last_k=1 # Apply to last interaction ) print("✅ Positive feedback applied") ### [​](https://docs.cognee.ai/guides/feedback-system#step-3:-provide-negative-feedback) Step 3: Provide Negative Feedback Copy # Provide constructive negative feedback await cognee.search( query_text="This answer missed the key technical details I needed", query_type=SearchType.FEEDBACK, last_k=1 ) print("✅ Negative feedback applied") **Result:** Feedback scores are applied to knowledge graph relationships to improve future results. [​](https://docs.cognee.ai/guides/feedback-system#example:-batch-feedback-collection) Example: Batch Feedback Collection --------------------------------------------------------------------------------------------------------------------------- This example shows how to collect feedback on multiple recent interactions. ### [​](https://docs.cognee.ai/guides/feedback-system#step-1:-perform-multiple-searches) Step 1: Perform Multiple Searches Copy # Perform several searches queries = [\ "What are the technical requirements?",\ "Summarize the project timeline",\ "Explain the architecture decisions"\ ] for query in queries: results = await cognee.search( query_text=query, query_type=SearchType.GRAPH_COMPLETION, save_interaction=True ) print(f"Results for '{query}': {results}") ### [​](https://docs.cognee.ai/guides/feedback-system#step-2:-provide-batch-feedback) Step 2: Provide Batch Feedback Copy # Provide feedback on multiple recent interactions await cognee.search( query_text="The last few searches have been much more accurate and helpful", query_type=SearchType.FEEDBACK, last_k=3 # Apply to last 3 interactions ) print("✅ Batch feedback applied to recent interactions") **Result:** Multiple interactions are improved based on your feedback. [​](https://docs.cognee.ai/guides/feedback-system#example:-application-integration) Example: Application Integration ----------------------------------------------------------------------------------------------------------------------- This example shows how to integrate feedback collection in your application. ### [​](https://docs.cognee.ai/guides/feedback-system#step-1:-create-search-function-with-feedback) Step 1: Create Search Function with Feedback Copy async def search_with_feedback(query: str, user_feedback: str = None): # Perform search results = await cognee.search( query_text=query, query_type=SearchType.GRAPH_COMPLETION, save_interaction=True ) # If user provides feedback, apply it if user_feedback: await cognee.search( query_text=user_feedback, query_type=SearchType.FEEDBACK, last_k=1 ) print("✅ Feedback collected and applied") return results ### [​](https://docs.cognee.ai/guides/feedback-system#step-2:-use-in-your-application) Step 2: Use in Your Application Copy # Search with immediate feedback results = await search_with_feedback( "What are the security considerations?", "Great answer, very detailed and practical" ) # Search without feedback results = await search_with_feedback("What is the deployment process?") **Result:** Integrated feedback collection in your application workflow. [​](https://docs.cognee.ai/guides/feedback-system#common-issues) Common Issues --------------------------------------------------------------------------------- **Feedback not working:** * Ensure `save_interaction=True` in your search calls * Check that you have recent interactions to apply feedback to * Verify you’re using `SearchType.FEEDBACK` for feedback calls **No improvement in results:** * Provide more specific feedback text * Give feedback soon after receiving results * Use positive feedback to reinforce good results **Performance concerns:** * Feedback requires LLM processing for sentiment analysis * Consider batching multiple feedback calls * Monitor LLM API quotas and rate limits **Integration challenges:** * Start with simple feedback collection * Gradually add more sophisticated feedback patterns * Test feedback effectiveness over time [Core Concepts\ -------------\ \ Understand knowledge graph fundamentals](https://docs.cognee.ai/core-concepts/overview) [API Reference\ -------------\ \ Explore feedback API endpoints](https://docs.cognee.ai/api-reference/introduction) Was this page helpful? YesNo [Previous](https://docs.cognee.ai/guides/distributed-execution) [Permission SnippetsPractical code snippets and scenarios for Cognee's permission system\ \ Next](https://docs.cognee.ai/guides/permission-snippets) ⌘I On this page * [Example: Basic Feedback Loop](https://docs.cognee.ai/guides/feedback-system#example:-basic-feedback-loop) * [Step 1: Perform Search with Interaction Saving](https://docs.cognee.ai/guides/feedback-system#step-1:-perform-search-with-interaction-saving) * [Step 2: Provide Positive Feedback](https://docs.cognee.ai/guides/feedback-system#step-2:-provide-positive-feedback) * [Step 3: Provide Negative Feedback](https://docs.cognee.ai/guides/feedback-system#step-3:-provide-negative-feedback) * [Example: Batch Feedback Collection](https://docs.cognee.ai/guides/feedback-system#example:-batch-feedback-collection) * [Step 1: Perform Multiple Searches](https://docs.cognee.ai/guides/feedback-system#step-1:-perform-multiple-searches) * [Step 2: Provide Batch Feedback](https://docs.cognee.ai/guides/feedback-system#step-2:-provide-batch-feedback) * [Example: Application Integration](https://docs.cognee.ai/guides/feedback-system#example:-application-integration) * [Step 1: Create Search Function with Feedback](https://docs.cognee.ai/guides/feedback-system#step-1:-create-search-function-with-feedback) * [Step 2: Use in Your Application](https://docs.cognee.ai/guides/feedback-system#step-2:-use-in-your-application) * [Common Issues](https://docs.cognee.ai/guides/feedback-system#common-issues) --- # Permission Snippets - Cognee Documentation [Skip to main content](https://docs.cognee.ai/guides/permission-snippets#content-area) [Cognee Documentation home page![light logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20black.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=ea48b52be1df02b5909f780e6cd6856e)![dark logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20white.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=9f5bc18c4897c6e58b5cfa2b09bc079d)](https://docs.cognee.ai/) Search... ⌘K Search... Navigation Cognee Permissions System Permission Snippets [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) This guide provides practical code snippets demonstrating the permission system in action. These snippets show how to create users, tenants, roles, and datasets, and how to manage permissions effectively. **Complete snippets** — All code snippets are complete and runnable, showing the full workflow from setup to permission management. Creating a User [Users](https://docs.cognee.ai/core-concepts/permissions-system/users) are the foundation of the permission system. Here’s how to create a new [user](https://docs.cognee.ai/core-concepts/permissions-system/users) : Copy from cognee.modules.users.methods import create_user user = await create_user( email="alice@company.com", password="password123", is_superuser=True ) Creating a Tenant [Tenants](https://docs.cognee.ai/core-concepts/permissions-system/tenants) group [users](https://docs.cognee.ai/core-concepts/permissions-system/users) together and can receive permissions. Create a [tenant](https://docs.cognee.ai/core-concepts/permissions-system/tenants) with an owner: Copy from cognee.modules.users.tenants.methods import create_tenant # Assuming user is already created await create_tenant("acme_corp", user.id) Adding Users to a Tenant Add existing [users](https://docs.cognee.ai/core-concepts/permissions-system/users) to a [tenant](https://docs.cognee.ai/core-concepts/permissions-system/tenants) . Only the [tenant](https://docs.cognee.ai/core-concepts/permissions-system/tenants) owner can add [users](https://docs.cognee.ai/core-concepts/permissions-system/users) : Copy from cognee.modules.users.tenants.methods import add_user_to_tenant # Assuming user2, tenant_id, and owner_id are already defined await add_user_to_tenant(user2.id, tenant_id, owner_id) Creating a Role [Roles](https://docs.cognee.ai/core-concepts/permissions-system/roles) provide permission groups within a [tenant](https://docs.cognee.ai/core-concepts/permissions-system/tenants) . Create a [role](https://docs.cognee.ai/core-concepts/permissions-system/roles) for the [tenant](https://docs.cognee.ai/core-concepts/permissions-system/tenants) : Copy from cognee.modules.users.roles.methods import create_role # Assuming owner_id is the tenant owner await create_role("editor", owner_id) Creating a Dataset Datasets are the core data containers. Create a dataset with automatic permissions for the creator: Copy from cognee.modules.data.methods import create_authorized_dataset # Assuming user is already created dataset = await create_authorized_dataset("project_docs", user) Granting Read Permission Grant specific permissions to principals. Give read access to a user: Copy from cognee.modules.users.permissions.methods import give_permission_on_dataset # Assuming user2 and dataset are already created await give_permission_on_dataset(user2, dataset.id, "read") Granting Multiple Permissions Grant different permission types to the same principal. Give comprehensive access: Copy from cognee.modules.users.permissions.methods import give_permission_on_dataset # Assuming user2 and dataset are already created await give_permission_on_dataset(user2, dataset.id, "read") await give_permission_on_dataset(user2, dataset.id, "write") await give_permission_on_dataset(user2, dataset.id, "delete") Checking User Permissions Query what datasets a user can access. Check permissions by type: Copy from cognee.modules.users.permissions.methods import get_all_user_permission_datasets # Assuming user is already created # Get all datasets user can read readable_datasets = await get_all_user_permission_datasets(user, "read") # Get all datasets user can write writable_datasets = await get_all_user_permission_datasets(user, "write") Complete Permission Setup Set up a complete permission scenario from scratch. This example shows the full workflow: Copy from cognee.modules.users.methods import create_user, get_user from cognee.modules.users.tenants.methods import create_tenant, add_user_to_tenant from cognee.modules.data.methods import create_authorized_dataset from cognee.modules.users.permissions.methods import give_permission_on_dataset # 1. Create users user1 = await create_user("alice@company.com", "password123", is_superuser=True) user2 = await create_user("bob@company.com", "password456") # 2. Create tenant and add users await create_tenant("acme_corp", user1.id) # Refresh user1 to get tenant_id user1 = await get_user(user1.id) await add_user_to_tenant(user2.id, user1.tenant_id, user1.id) # 3. Create dataset dataset = await create_authorized_dataset("confidential_docs", user1) # 4. Grant different permissions await give_permission_on_dataset(user2, dataset.id, "read") # Read-only access Permission Inheritance Example Demonstrate how permissions flow through the hierarchy. Show tenant and role inheritance: Copy from cognee.modules.users.permissions.methods import give_permission_on_dataset # Assuming tenant, role, and dataset are already created # Grant permission to tenant (all users inherit) await give_permission_on_dataset(tenant, dataset.id, "read") # Grant permission to role (role members inherit) await give_permission_on_dataset(role, dataset.id, "write") # User gets both: read (from tenant) + write (from role) Multi-tenant Organization Setup Create organization with multiple teams: Copy # Create organization with multiple teams # 1. Create tenant tenant = await create_tenant("tech_company", admin_user.id) # 2. Create roles for different teams dev_role = await create_role("developers", admin_user.id) qa_role = await create_role("qa_team", admin_user.id) pm_role = await create_role("product_managers", admin_user.id) # 3. Create datasets for different projects frontend_dataset = await create_authorized_dataset("frontend_docs", admin_user) backend_dataset = await create_authorized_dataset("backend_docs", admin_user) qa_dataset = await create_authorized_dataset("qa_docs", admin_user) # 4. Grant role-based permissions await give_permission_on_dataset(dev_role, frontend_dataset.id, "write") await give_permission_on_dataset(dev_role, backend_dataset.id, "write") await give_permission_on_dataset(qa_role, qa_dataset.id, "write") await give_permission_on_dataset(pm_role, frontend_dataset.id, "read") await give_permission_on_dataset(pm_role, backend_dataset.id, "read") Temporary Access Management Grant temporary access to external contractor: Copy # Grant temporary access to external contractor contractor = await create_user("contractor@external.com", "temp_password") # Grant read access to specific dataset await give_permission_on_dataset(contractor, project_dataset.id, "read") # Later, revoke access by removing the permission # (This would require a revoke_permission function) Cross-team Collaboration Allow teams to collaborate on shared datasets: Copy # Allow teams to collaborate on shared datasets shared_dataset = await create_authorized_dataset("shared_research", admin_user) # Grant different levels of access to different teams await give_permission_on_dataset(dev_role, shared_dataset.id, "read") await give_permission_on_dataset(research_role, shared_dataset.id, "write") await give_permission_on_dataset(management_role, shared_dataset.id, "read") Best Practices Follow these best practices for permission management: * **Start simple** — Begin with basic user and dataset creation * **Use roles for teams** — Create roles for different job functions * **Grant tenant permissions** — Use tenant-level permissions for organization-wide access * **Regular audits** — Periodically review and update permissions * **Document access patterns** — Keep clear records of who has access to what * **Test permission changes** — Verify permissions work as expected after changes [Setup Configuration\ -------------------\ \ Learn how to configure the permission system](https://docs.cognee.ai/setup-configuration/permissions) [API Reference\ -------------\ \ Explore permission system API endpoints](https://docs.cognee.ai/api-reference/introduction) Was this page helpful? YesNo [Previous](https://docs.cognee.ai/core-concepts/permissions-system/acl) [Setup ConfigurationConfigure Cognee to use your preferred LLM, embedding engine, and storage backends\ \ Next](https://docs.cognee.ai/setup-configuration/overview) ⌘I --- # Page Not Found [Skip to main content](https://docs.cognee.ai/core-concepts/knowledge-graphs#content-area) [Cognee Documentation home page![light logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20black.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=ea48b52be1df02b5909f780e6cd6856e)![dark logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20white.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=9f5bc18c4897c6e58b5cfa2b09bc079d)](https://docs.cognee.ai/) Search... ⌘K Search... Navigation Page Not Found [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) 404 Page Not Found ============== We couldn't find the page. Maybe you were looking for one of these pages below? [Documentation Intelligence](https://docs.cognee.ai/examples/documentation-intelligence#why-knowledge-graphs-matter) [API Reference](https://docs.cognee.ai/api-reference/introduction#core-api-endpoints) [Graph Stores](https://docs.cognee.ai/setup-configuration/graph-stores#graph-stores) ⌘I --- # Page Not Found [Skip to main content](https://docs.cognee.ai/core-concepts/getting-started/installation#content-area) [Cognee Documentation home page![light logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20black.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=ea48b52be1df02b5909f780e6cd6856e)![dark logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20white.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=9f5bc18c4897c6e58b5cfa2b09bc079d)](https://docs.cognee.ai/) Search... ⌘K Search... Navigation Page Not Found [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) 404 Page Not Found ============== We couldn't find the page. Maybe you were looking for one of these pages below? [Tasks](https://docs.cognee.ai/core-concepts/building-blocks/tasks#core-concepts) [Introduction](https://docs.cognee.ai/getting-started/introduction#ready-to-get-started) [Overview](https://docs.cognee.ai/core-concepts/permissions-system/overview#core-components) ⌘I --- # Client Integrations - Cognee Documentation [Skip to main content](https://docs.cognee.ai/cognee-mcp/integrations#content-area) [Cognee Documentation home page![light logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20black.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=ea48b52be1df02b5909f780e6cd6856e)![dark logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20white.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=9f5bc18c4897c6e58b5cfa2b09bc079d)](https://docs.cognee.ai/) Search... ⌘K Search... Navigation Client Integrations [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) Cognee MCP works with AI development tools that support the Model Context Protocol. These clients connect to your Cognee MCP server and provide access to memory management, code intelligence, and data operations through their interfaces. The client configuration is the same whether your MCP server runs in standalone mode or connects to a centralized Cognee backend. The server architecture is transparent to clients. [​](https://docs.cognee.ai/cognee-mcp/integrations#available-clients) Available Clients ------------------------------------------------------------------------------------------ [Cursor\ ------\ \ AI-powered code editor with native MCP support](https://docs.cognee.ai/cognee-mcp/integrations/cursor) [Claude Code\ -----------\ \ Command-line AI assistant from Anthropic](https://docs.cognee.ai/cognee-mcp/integrations/claude-code) [Cline\ -----\ \ VS Code extension for AI-assisted development](https://docs.cognee.ai/cognee-mcp/integrations/cline) [Continue\ --------\ \ Open-source AI coding assistant for VS Code and JetBrains](https://docs.cognee.ai/cognee-mcp/integrations/continue) [Roo Code\ --------\ \ VS Code extension for AI-powered development](https://docs.cognee.ai/cognee-mcp/integrations/roo-code) [​](https://docs.cognee.ai/cognee-mcp/integrations#configuration-options) Configuration Options -------------------------------------------------------------------------------------------------- Each integration requires a configuration file that tells the client how to connect to your Cognee MCP server. You have two options: ### [​](https://docs.cognee.ai/cognee-mcp/integrations#docker-http-transport) Docker (HTTP Transport) Use this if you started Cognee MCP with Docker using the quickstart guide. The client connects to the server over HTTP. Copy { "mcpServers": { "cognee": { "url": "http://localhost:8000/mcp" } } } ### [​](https://docs.cognee.ai/cognee-mcp/integrations#local-stdio-transport) Local (stdio Transport) Use this if you cloned the Cognee repository and run the server from source. The client starts the server as a subprocess and communicates through standard input/output. Copy { "mcpServers": { "cognee": { "command": "uv", "args": [\ "--directory",\ "/absolute/path/to/cognee-mcp",\ "run",\ "cognee-mcp"\ ], "env": { "LLM_API_KEY": "your-api-key" } } } } The configuration file location and exact format varies by client. See the specific integration guide for your tool. [​](https://docs.cognee.ai/cognee-mcp/integrations#next-steps) Next Steps ---------------------------------------------------------------------------- Choose your client from the cards above to see detailed setup instructions for that specific tool. Was this page helpful? YesNo ⌘I On this page * [Available Clients](https://docs.cognee.ai/cognee-mcp/integrations#available-clients) * [Configuration Options](https://docs.cognee.ai/cognee-mcp/integrations#configuration-options) * [Docker (HTTP Transport)](https://docs.cognee.ai/cognee-mcp/integrations#docker-http-transport) * [Local (stdio Transport)](https://docs.cognee.ai/cognee-mcp/integrations#local-stdio-transport) * [Next Steps](https://docs.cognee.ai/cognee-mcp/integrations#next-steps) --- # Cognee Cloud - Cognee Documentation [Skip to main content](https://docs.cognee.ai/how-to-guides/cognee-cloud/index#content-area) [Cognee Documentation home page![light logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20black.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=ea48b52be1df02b5909f780e6cd6856e)![dark logo](https://mintcdn.com/cognee/of3mX7JsgcxLIPDF/images/Cognee%20logo%20white.svg?fit=max&auto=format&n=of3mX7JsgcxLIPDF&q=85&s=9f5bc18c4897c6e58b5cfa2b09bc079d)](https://docs.cognee.ai/) Search... ⌘K Search... Navigation Cognee Cloud [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) [Documentation](https://docs.cognee.ai/getting-started/introduction) [Cognee Cloud](https://docs.cognee.ai/cognee-cloud/overview) [Deploy](https://docs.cognee.ai/how-to-guides/cognee-sdk/deployment) [Integrations](https://docs.cognee.ai/integrations) [MCP](https://docs.cognee.ai/cognee-mcp/mcp-overview) [HTTP API](https://docs.cognee.ai/api-reference/introduction) [Python API](https://docs.cognee.ai/python-api) Cognee Cloud provides scalable, managed infrastructure for deploying and running Cognee’s knowledge graph platform in production environments. Cognee Cloud is the cloud-hosted version of Cognee, offering enterprise-grade infrastructure without the operational overhead. [​](https://docs.cognee.ai/how-to-guides/cognee-cloud/index#key-features) Key Features ----------------------------------------------------------------------------------------- Managed Infrastructure ---------------------- Fully hosted, auto-scaling Kuzu, LanceDB & PostgreSQL backends Always-on Pipelines ------------------- Cognify pipelines without servers to maintain Secure by Default ----------------- Role-based access controls (RBAC) and audit logging Simple API Keys --------------- One-click API key generation for instant access [​](https://docs.cognee.ai/how-to-guides/cognee-cloud/index#getting-started) Getting Started ----------------------------------------------------------------------------------------------- 1 Access the Console Navigate to [https://platform.cognee.ai/](https://platform.cognee.ai/) to see the login screen. **Prerequisites**: A Google or GitHub account and a valid credit/debit card. 2 Choose Authentication Select **Google** or **GitHub** to authenticate. OAuth keeps your credentials secure—no separate password required. 3 Subscribe & Payment On first sign-in, you’ll be prompted to subscribe and add a payment method. Enter your card details and click **Save**. **New to Cognee?** Try it locally first with the [Quickstart](https://docs.cognee.ai/getting-started/quickstart) to explore features and understand how knowledge graphs work before committing to the cloud platform. 4 Create API Key Click **Create API Key** to automatically generate your first API key. Copy and store your API key securely. You’ll need it for all API requests. [​](https://docs.cognee.ai/how-to-guides/cognee-cloud/index#api-integration) API Integration ----------------------------------------------------------------------------------------------- Once you have your API key, you can start using Cognee Cloud through our comprehensive API. ### [​](https://docs.cognee.ai/how-to-guides/cognee-cloud/index#interactive-api-explorer) Interactive API Explorer [Swagger Documentation\ ---------------------\ \ Explore and test all API endpoints interactively with your API key](https://cognee--cognee-saas-backend-serve.modal.run/docs) ### [​](https://docs.cognee.ai/how-to-guides/cognee-cloud/index#core-api-endpoints) Core API Endpoints Data Management * **`/api/add`**: Ingest text data into your knowledge graph * **`/api/delete`**: Remove specific data items from datasets * **`/api/list_datasets`**: View all available datasets Knowledge Processing * **`/api/cognify`**: Transform raw data into structured knowledge graphs * **`/api/cognify_status`**: Check the status of cognify operations Search & Retrieval * **`/api/search`**: Query your knowledge graph with natural language * **`/api/get_insights`**: Get structured insights and relationships [View Complete API Reference\ ---------------------------\ \ Explore all available endpoints with interactive examples](https://docs.cognee.ai/api-reference) All API endpoints require your API key in the `X-Api-Key` header for authentication. [​](https://docs.cognee.ai/how-to-guides/cognee-cloud/index#typical-workflow) Typical Workflow ------------------------------------------------------------------------------------------------- 1 Ingest Data Use the `/api/add` endpoint to ingest raw text into your dataset. 2 Build Knowledge Graph Run the `/api/cognify` pipeline to transform your data into a structured knowledge graph. 3 Query & Search Use `/api/search` to ask questions and retrieve relevant information from your knowledge graph. 4 Manage Data Optionally use `/api/delete` to remove outdated items or visualize your graph structure. [​](https://docs.cognee.ai/how-to-guides/cognee-cloud/index#authentication) Authentication --------------------------------------------------------------------------------------------- * API Key * Content Types Include your API key in the request header: Copy X-Api-Key: YOUR-API-KEY [​](https://docs.cognee.ai/how-to-guides/cognee-cloud/index#next-steps) Next Steps ------------------------------------------------------------------------------------- [API Reference\ -------------\ \ Explore detailed API documentation and examples](https://docs.cognee.ai/api-reference) User Management --------------- Invite teammates and manage roles in Settings → Users Cognee Cloud makes it effortless to deploy production-grade knowledge graphs without worrying about infrastructure, scaling, or security. Was this page helpful? YesNo ⌘I On this page * [Key Features](https://docs.cognee.ai/how-to-guides/cognee-cloud/index#key-features) * [Getting Started](https://docs.cognee.ai/how-to-guides/cognee-cloud/index#getting-started) * [API Integration](https://docs.cognee.ai/how-to-guides/cognee-cloud/index#api-integration) * [Interactive API Explorer](https://docs.cognee.ai/how-to-guides/cognee-cloud/index#interactive-api-explorer) * [Core API Endpoints](https://docs.cognee.ai/how-to-guides/cognee-cloud/index#core-api-endpoints) * [Typical Workflow](https://docs.cognee.ai/how-to-guides/cognee-cloud/index#typical-workflow) * [Authentication](https://docs.cognee.ai/how-to-guides/cognee-cloud/index#authentication) * [Next Steps](https://docs.cognee.ai/how-to-guides/cognee-cloud/index#next-steps) ---