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 pipelinecognee.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!