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 (>= 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:

pip install cognee-agensgraph

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

pip install "agensgraph-ai[cognee]"

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

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:

DROP GRAPH cognee CASCADE;

Then upgrade the package:

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).

Set up the pgvector extension#

cognee’s vector store uses pgvector. AgensGraph does not bundle it, so build it once against your AgensGraph install:

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:

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

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).

With the package installed, pgvector available, and the models configured, head to Usage to point cognee at AgensGraph and build your first memory.