Handler for connecting to a Neo4j database, enabling multi-user mode on a Neo4j database instance hosted on their cloud, Neo4j Aura.
Make sure that ENABLE_BACKEND_ACCESS_CONTROL in your .env file is NOT set to False.
Multi-user mode is enabled by default, therefore ENABLE_BACKEND_ACCESS_CONTROL=True by default.
The Neo4j adapter is one of Cognee’s core graph adapters, along with Kuzu. Multi-user mode, however,
is only enabled via the Neo4j Aura Cloud with this handler. You can read more about Aura in the official
Neo4j Aura docs.
By default, Cognee stores graph data locally using Kuzu (a file-based database). When you switch to Neo4j,
your data moves to a Neo4j server — which can be local (self-hosted) or cloud-based (Neo4j Aura).
Self-hosted Neo4j — You run Neo4j yourself (locally or on a server). Data stays on that server.
Neo4j Aura — Neo4j’s fully managed cloud service. Data is stored in Neo4j’s cloud infrastructure; nothing is saved locally on your machine. This is useful for teams, production deployments, or when you need managed backups.
This is the simplest approach. All datasets share the same Aura instance.For the general Neo4j provider setup and more context on using a single shared Aura database,
see Graph Stores.
The Neo4jAuraDevDatasetDatabaseHandler goes further: it automatically creates a dedicated
Neo4j Aura instance for each Cognee dataset via the Neo4j Aura API, and deletes it when the
dataset is removed. This enables strong per-dataset isolation for multi-user deployments.This handler requires Neo4j Aura API OAuth credentials, not a regular database password.
OAuth client secret from the Neo4j Aura API console
NEO4J_TENANT_ID
Yes
Your Neo4j Aura tenant (organization) ID
NEO4J_ENCRYPTION_KEY
Recommended
Key used to encrypt database passwords at rest
GRAPH_DATASET_DATABASE_HANDLER
Yes
Selects the neo4j_aura_dev dataset database handler
NEO4J_ENCRYPTION_KEY defaults to "test_key" if not set. Always set a strong random key in production to protect the Aura instance credentials stored in Cognee’s relational database.
Calls the Neo4j Aura API to provision a new database instance (1 GB, Neo4j 5, GCP)
Polls until the instance is ready (up to ~5 minutes)
Encrypts the instance password and stores the connection details in Cognee’s relational database
Returns connection info so subsequent operations use that dataset’s dedicated graph
When a dataset is deleted, Cognee calls the Aura API to tear down the corresponding instance.
Each dataset gets its own Aura instance. For applications with many datasets, this results in
multiple Aura instances running in parallel. Check your Aura plan limits accordingly.
Graph Stores
Details About Cognee’s Graph Stores (including Neo4j Aura Option 1)
