# Installation

## Requirements

- **Python** 3.11–3.13. On Python 3.10, pip installs 0.2.0 instead, without an error, and
  these pages do not describe it. On 3.14 pip finds no version to install.
- A running **AgensGraph** instance, **2.17 or later** (an older server is refused at connect)
- The **pgvector** extension available to the database cognee will use (for the vector store)

Installing `cognee-agensgraph` also pulls in the cognee core (`cognee >= 0.2.1, < 0.3`),
the AgensGraph driver [agensgraph-python](https://github.com/skaiworldwide-oss/agensgraph-python)
(`>= 2.0.0`), and `psycopg[binary] >= 3.3.4`. Both adapters talk to the server through the
driver. cognee 0.3 changed the graph interface, so this release stays on cognee 0.2.

## Install

`cognee-agensgraph` is published to PyPI:

```bash
pip install cognee-agensgraph
```

or, through the `agensgraph-ai` umbrella package, which installs the same thing:

```bash
pip install "agensgraph-ai[cognee]"
```

Importing the package once anywhere in your program registers the AgensGraph adapters with
cognee:

```python
import cognee_agensgraph   # registers AgensgraphAdapter + AgensgraphVectorAdapter
```

## Upgrading from 0.2.0

> **A graph written by 0.2.0 is not readable by 0.3.x.** 0.2.0 kept every node on one
> label, `"__Node__"`, with the class in a `labels` property. From 0.3.0 each DataPoint class
> is stored on a label of its own, in lower case, under a common `__node__` label.

Drop the old graph in SQL, in the database cognee uses:

```sql
DROP GRAPH cognee CASCADE;
```

Then upgrade the package:

```bash
pip install -U cognee-agensgraph
```

Then clear what cognee recorded and build again from your data:
`await cognee.prune.prune_data()` and `await cognee.prune.prune_system(metadata=True)`, then
`add` and `cognify` your data again. Running `cognify` alone on a dataset cognee already
processed does nothing, so the graph stays empty. Drop the graph first:
`cognee.prune.prune_system()` on its own is not enough, because it deletes only nodes under the
new `__node__` label, and 0.2.0's nodes are on `"__Node__"`. `prune_system` also clears the
vector collections, and `cognify` writes them again.

Cypher written for 0.2.0 needs the same change. Once the old graph is dropped,
`MATCH (n:"__Node__")` finds nothing. Match the class label instead, for example
`MATCH (n:Entity)`, or `MATCH (n:__Node__)` for every node (see [Usage](usage.md)).

## Set up the pgvector extension

cognee's vector store uses [pgvector](https://github.com/pgvector/pgvector). AgensGraph does
not bundle it, so build it once against your AgensGraph install:

```bash
git clone https://github.com/pgvector/pgvector.git
export PG_CONFIG=/path/to/agens/bin/pg_config
cd pgvector && make && make install
```

On first use the vector adapter runs `CREATE EXTENSION IF NOT EXISTS vector` in the
database it connects to. That needs a role allowed to create the extension, normally a
superuser. If the application role is not one, enable it once yourself:

```sql
-- in the AgensGraph database cognee will use:
CREATE EXTENSION IF NOT EXISTS vector;
```

## Configure the models

cognee uses an LLM to build the graph and an embedding model to create vectors. Configure
them with cognee's standard settings. For OpenAI, set these **before** you import cognee:

```bash
export LLM_API_KEY="sk-..."
export LLM_PROVIDER="openai"
export LLM_MODEL="gpt-4o-mini"
export EMBEDDING_PROVIDER="openai"
export EMBEDDING_MODEL="openai/text-embedding-3-small"
export EMBEDDING_DIMENSIONS="1536"
export EMBEDDING_API_KEY="sk-..."
```

The embedding dimension must match the model you choose (`text-embedding-3-small` is
1536-d), and it must be 2000 or less. The vector store indexes every collection with HNSW,
and pgvector's HNSW index takes at most 2000 dimensions. cognee's default
`text-embedding-3-large` (3072-d) fails when the first collection is created, so set
`EMBEDDING_MODEL` and `EMBEDDING_DIMENSIONS` as above. The dimension is fixed when a
collection's table is first created. To change embedding models later, drop the affected
collection tables, or reset the memory (see [Usage](usage.md)).

With the package installed, pgvector available, and the models configured, head to
[Usage](usage.md) to point cognee at AgensGraph and build your first memory.