QUICKSTART

This guide will help you get started with Cognee quickly and efficiently.

Purpose	Where to go	Example
Ingest unstructured data	This tutorial is the right place	PDFs, docs, csvs
Ingest structured & semi-structured data	Navigate to Migrate Relational DB to Cognee	Relational Databases
Apply memory or NLP algorithms	Navigate to Custom Pipelines	Summaries, Associations, Predictions, World Models, Classifications
Use MCP	Navigate to Cognee Docker MCP	You are lazy, and just need something that works

💡 How Cognee Works (2-minute explanation)

Cognee transforms your data into an intelligent knowledge graph using three key concepts:

🔧 Tasks: Individual processing steps (like “extract text chunks” or “find entities”)

Each task does one specific job well
Tasks are chained together to process your data step by step

🔄 Pipelines: Sequences of tasks that transform raw data → structured knowledge

cognee.add() runs the data ingestion pipeline
cognee.cognify() runs the knowledge graph creation pipeline

🗄️ Dual Storage: Graph database (relationships) + Vector database (semantic similarity)

Graph: Stores explicit relationships (“Machine Learning is a subset of AI”)
Vector: Stores semantic embeddings for similarity search
Together: Enable both precise relationship queries and fuzzy semantic search

When you call cognee.add() and cognee.cognify(), you’re running pipelines of tasks that create a knowledge graph you can search both by relationships and similarity.

Follow these step-by-step instructions to set up your environment, install Cognee, and run your first knowledge graph operations. Cognee is highly customizable, check our .env template

1. Preparation

Cognee runs on Python versions 3.9 to 3.12, make sure you have a suitable setup.

Before running Cognee you have to specify up your environment. This is easiest done editing the .env file in the directory you are working in.

Cognee relies on third-party LLM providers and you have a great choice of them you can use in your workflow.

The simple way

Just provide your OpenAI API key if you already have one. This will help you both with LLM and embeddings.


echo 'LLM_API_KEY="your_api_key"' > .env

The free way

If you don’t have an OpenAI API key and you would like to try Cognee with free services, register for an OpenRouter account and get a free API key. OpenRouter does not host embedding providers, so you have to fall back to a local way to do that. Your .env should look something like this then:


LLM_API_KEY="your_api_key"
LLM_PROVIDER="custom"
LLM_MODEL="openrouter/google/gemini-2.0-flash-thinking-exp-1219:free"
LLM_ENDPOINT="https://openrouter.ai/api/v1"
EMBEDDING_PROVIDER="fastembed"
EMBEDDING_MODEL="sentence-transformers/all-MiniLM-L6-v2"
EMBEDDING_DIMENSIONS=384
EMBEDDING_MAX_TOKENS=256

2. Install cognee

In this example we will use Poetry to install Cognee. You can install it with poetry or uv, we support using uv.


$ uv venv
$ source .venv/bin/activate
$ uv pip install cognee
# $ uv pip install "cognee[fastembed]" ## if you are going the free way

Cognee stores data in a relational database, in a vector database and in a graph database. We provide you with a variety of possibilities for each store, so you can choose the right one for your purposes and install it as cognee’s optinonal dependencies like we did above for fastembed. To see more check out our infrastructure page.

For this simple example we will use our default set of SQLite, LanceDB and NetworkX that doesn’t require extra servers or registration at third parties.

3. Basic usage

This minimal example shows how to add content, process it, and perform a search:


import cognee
import asyncio
 
async def main():
    
    # Add sample content
    text = "Natural language processing (NLP) is a subfield of computer science."
    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="Tell me about NLP"
    )
    
    for result in results:
        print(result)
 
if __name__ == '__main__':
    asyncio.run(main())

4. Further resources

If you want to try cognee in an interactive notebook environment check out our Cognee GraphRAG Simple Example Colab
Explore our How-to Guides for advanced users

Join the Conversation!

Have questions? Join our community now to connect with professionals, share insights, and get your questions answered!