Agent Skills

Install Cognee’s maintained agent skills so Claude Code, Codex, and other assistants know the SDK.

The Cognee repository ships a maintained set of agent skills — short, task-scoped instruction files an assistant loads on demand when your request matches one. Give them to Claude Code, Codex, or another skill-aware assistant so it works from Cognee’s actual API surface instead of guessing.

Available skills

Each skill lives at .agents/skills/<name>/SKILL.md in the Cognee repository.

Skill	Use it for
cognee-install	Installing Cognee and running a first remember → recall flow with the Python SDK: fresh setup, virtual env, extras selection, a minimal working example.
cognee-ingestion	Putting data into memory with remember() — inputs (text, files, folders, URLs, repos, databases), datasets and node sets, loaders, ontologies, the graph extractor, chunking, dry-run cost estimates, temporal graphs.
cognee-recall	Querying memory with recall() (or search()) — picking a search type, auto-routing, scoping to datasets/node sets/sessions, getting context or citations, debugging empty results.
cognee-forget	Removing data with forget() — finding the dataset and document that hold the content, and choosing between one document, a whole dataset, or only the graph/vector memory.
cognee-improve-sessions	Session memory and improve() — storing conversation turns, agent traces and feedback with session_id, bridging sessions into the permanent graph, reading an ImproveResult, tuning IMPROVE_* settings.
cognee-custom-graph-models	Shaping the knowledge graph with graph_model= — DataPoint node classes, identity and index fields, typed Edge fields and FromIdentity references, debugging duplicated nodes or missing edges.
cognee-custom-pipelines	Writing custom tasks and chaining them with run_custom_pipeline or run_pipeline, storing custom DataPoints, enriching the existing graph with memify, debugging how data flows between tasks.
cognee-permissions	Users, tenants, roles, and multi-tenancy — sharing datasets, acting as a specific user, authenticating over HTTP, debugging PermissionDeniedError or missing datasets.
cognee-migrations	Database migrations — when they run automatically, checking or repairing state with cognee-cli upgrade/downgrade/stamp/current, authoring a new revision, moving data between systems.
cognee-performance	Cognee being slow, expensive, or rate-limited — ingestion and read-latency tuning, per-stage models, cost estimates, background work, scaling a deployment.
cognee-integrations	Connecting Cognee to external services — LLM and embedding providers, alternate databases, S3 storage, the MCP server for IDE integration.
cognee-cli	Driving Cognee from the terminal with cognee-cli — memory commands, datasets, config, migrations.
cognee-server	Running the API server (and optional UI) locally — starting it, checking health, connecting clients, choosing an auth posture.
cognee-docker	Running Cognee with Docker or docker compose, including the full stack with UI, MCP, Postgres, and Neo4j.
cognee-community	Anything that ships outside core — community database adapters, data-source connectors, custom tasks and retrievers — or contributing a package back.

Install the skills

.agents/skills/ is the canonical location: it is the only copy of the files, and Codex (plus other tooling that reads the tool-neutral .agents/ path) picks it up directly. Claude Code reads .claude/skills, which the repository commits as a symlink to ../.agents/skills, so both point at the same files.

To use the skills in your own project, clone Cognee and copy the ones you want:

git clone https://github.com/topoteretes/cognee.git
mkdir -p .agents/skills
cp -r cognee/.agents/skills/cognee-ingestion .agents/skills/
cp -r cognee/.agents/skills/cognee-recall .agents/skills/

Then point Claude Code at the same folder. This assumes .claude/skills does not exist yet — if it does, ln silently creates .claude/skills/skills instead, so copy the skills into .claude/skills/ directly:

mkdir -p .claude
ln -s ../.agents/skills .claude/skills

On a Windows clone of the Cognee repository itself, no manual step is needed when you open it in Claude Code with Git Bash available: a SessionStart hook replaces the checked-out placeholder with a directory junction automatically.

Fallback: a single inline quickstart skill

If you would rather not clone the repository, the self-contained setup skill below still works — create the folder and copy the block below into .claude/skills/cognee-quickstart/SKILL.md:

mkdir -p .claude/skills/cognee-quickstart

It covers the same ground as cognee-install (Python version, virtual environments, provider configuration, optional extras, and the first remember / recall smoke test) in one block. cognee-install supersedes it and is the version that gets maintained, so prefer it when you have the repository available.

---
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"
LLM_API_KEY="ollama"

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

`LLM_ENDPOINT` is the bare host — no `/v1` suffix; on the default structured output backend LiteLLM appends Ollama's native `/api/generate` path itself, and a trailing `/v1` fails with a 404.

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` | Reinstall `cognee` — `fastembed` is a core dependency, and both `cognee[fastembed]` and `cognee[codegraph]` are now empty compatibility aliases that install nothing. |
| `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

There is no `source` on Windows. Pick the activation script that matches the shell the user is in — PowerShell uses `Activate.ps1`, Command Prompt uses `activate.bat`:

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

```cmd
uv venv
.venv\Scripts\activate.bat
```

If PowerShell activation is blocked by an execution policy:

```powershell
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
```

If `uv` is not on `PATH` after `pip install uv`, call it through Python: `python -m uv pip install cognee`.

After installing, confirm the active interpreter resolves Cognee from the venv:

```powershell
python -c "import cognee; print(cognee.__file__)"
```

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.