LLM Quickstart Skill

mkdir -p .claude/skills/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:

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

Create `.env` in the project root:

```dotenv
LLM_API_KEY="your_openai_api_key"
```

Verify import before running a full example:

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

Then run the smoke test:

```python
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

```dotenv
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.

```bash
uv pip install "cognee[anthropic]"
```

```dotenv
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:

```bash
ollama pull llama3.1:8b
```

```dotenv
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:

```python
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:

```bash
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:

```bash
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`:

```powershell
uv venv
.venv\Scripts\Activate.ps1
```

If activation is blocked:

```powershell
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.