cognee-quickstart

name	cognee-quickstart
description	Help users start or troubleshoot a Cognee project by choosing the right installation path, creating a clean Python environment, configuring LLM and embedding providers, installing optional extras, running the first remember/recall smoke test, and resolving dependency setup errors.

Cognee Quickstart

Use this skill when the user is starting with Cognee, setting up dependencies, running Cognee from source, configuring providers, using local models, or reporting install/import/API key errors.

First move

Classify the setup path before installing anything:

• Fastest package setup: User wants to try Cognee in a new app or notebook.
• Provider-specific setup: User wants OpenAI, Gemini, Anthropic, Ollama, Fastembed, or another backend.
• Source setup: User cloned topoteretes/cognee to inspect examples, change code, or contribute.
• Existing broken setup: User already has errors, stale environments, or dependency conflicts.

If the path is unclear, ask one short question. Otherwise make the conservative default: package install in a fresh virtual environment using OpenAI defaults.

Environment rules

• Work from the project root, where the user's .env should live.
• Require Python 3.10 through 3.14. Check python --version or python3 --version.
• Prefer uv for environment and package work. Use python -m venv and pip only when uv is unavailable.
• Do not install packages globally unless the user explicitly asks.
• Do not mix package managers in the same environment.
• Treat .env values as secrets. Never print real API keys back to the user.

Fastest package setup

Use this path for most first-time users with an OpenAI API key:

uv venv
source .venv/bin/activate
uv pip install cognee

Create .env in the project root:

LLM_API_KEY="your_openai_api_key"

Verify import before running a full example:

python -c "import cognee; print('cognee import ok')"

Then run the smoke test:

import asyncio
import cognee

async def main():
    await cognee.forget(everything=True)
    await cognee.remember("Cognee turns documents into AI memory.")
    results = await cognee.recall(query_text="What does Cognee do?")
    for result in results:
        print(result.text)

if __name__ == "__main__":
    asyncio.run(main())

Provider setup

The most common configuration mistake is setting only an LLM provider or only an embedding provider. If the user is not using OpenAI defaults, configure both sides explicitly.

Gemini example

LLM_PROVIDER="gemini"
LLM_MODEL="gemini/gemini-flash-latest"
LLM_API_KEY="your_gemini_api_key"

EMBEDDING_PROVIDER="gemini"
EMBEDDING_MODEL="gemini/gemini-embedding-001"
EMBEDDING_API_KEY="your_gemini_api_key"

Anthropic LLM example

Anthropic is an LLM provider, not an embedding provider. Pair it with an embedding provider such as OpenAI, Gemini, or Fastembed.

uv pip install "cognee[anthropic]"

LLM_PROVIDER="anthropic"
LLM_MODEL="anthropic/<your_claude_model>"
LLM_API_KEY="your_anthropic_api_key"

EMBEDDING_PROVIDER="openai"
EMBEDDING_MODEL="openai/text-embedding-3-small"
EMBEDDING_API_KEY="your_openai_api_key"

Local no-API-key example

Use Ollama for the LLM and Fastembed for CPU-friendly embeddings:

ollama pull llama3.1:8b

LLM_PROVIDER="ollama"
LLM_MODEL="llama3.1:8b"
LLM_ENDPOINT="http://localhost:11434/v1"
LLM_API_KEY="ollama"

EMBEDDING_PROVIDER="fastembed"
EMBEDDING_MODEL="sentence-transformers/all-MiniLM-L6-v2"
EMBEDDING_DIMENSIONS="384"

If the user changes embedding providers or dimensions after a previous run, advise a local reset before re-running:

import asyncio
import cognee

async def main():
    await cognee.prune.prune_system(metadata=True)

asyncio.run(main())

Source setup

Use this path when the user cloned the Cognee repository:

git clone https://github.com/topoteretes/cognee.git
cd cognee
uv venv
source .venv/bin/activate
uv pip install -e ".[dev]"

If the development extra fails because the package metadata changed, fall back to:

uv pip install -e .

Create .env from .env.template if it exists, then set at least LLM_API_KEY for the default OpenAI path. Run the same import check and smoke test before changing examples or source code.

Dependency triage

When setup fails, do not reinstall blindly. Read the first meaningful error and match it:

Error clue	Likely fix
No module named cognee	Activate the virtual environment and install cognee in that environment.
Python 3.9, SyntaxError, or resolver rejects Python	Switch to Python 3.10 through 3.14 and recreate the virtual environment.
anthropic	Install cognee[anthropic].
psycopg2, asyncpg, or pgvector	Install cognee[postgres] or cognee[postgres-binary].
neo4j	Install cognee[neo4j].
playwright, tavily, or beautifulsoup4	Install cognee[scraping].
unstructured	Install cognee[docs].
docling	Install cognee[docling].
fastembed	Install cognee[fastembed] or cognee[codegraph].
tree_sitter	Install cognee[codegraph].
modal	Install cognee[distributed].
redis	Install cognee[redis].
baml	Install cognee[baml].
API key, auth, or provider fallback errors	Confirm .env is in the project root and both LLM and embedding settings are configured for non-default providers.
Embedding dimension mismatch or stale vector collections	Reset local metadata with await cognee.prune.prune_system(metadata=True) or use a new SYSTEM_ROOT_DIRECTORY.
LLM connection preflight times out on a local/small model	Add COGNEE_SKIP_CONNECTION_TEST=true to .env, then test with a small input.

Windows adjustments

Use PowerShell activation instead of source:

uv venv
.venv\Scripts\Activate.ps1

If activation is blocked:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Use forward slashes or doubled backslashes in .env path values.

Finish criteria

Before saying the setup is done, confirm:

• The intended Python interpreter is active.
• import cognee succeeds.
• .env is in the project root.
• LLM and embedding configuration are both explicit unless the user is using OpenAI defaults.
• The smoke test stores text and recalls an answer.
• Any installed extras match the feature the user is actually trying to use.