Skip to main content
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.
Neo4j Community edition serves exactly one database per running server — CREATE DATABASE (used by the plain neo4j handler) is an Enterprise-only feature. The neo4j_community handler gets around this by running one Neo4j Community Docker container per dataset, mirroring the neo4j_aura_dev handler’s one-instance-per-dataset model with Docker in place of the Aura REST API. Use it when you want per-dataset graph isolation on the free Neo4j edition, on a host you control.

​
Requirements

This handler requires a reachable Docker daemon on the host running Cognee. Before provisioning a dataset, Cognee checks that the docker binary is on PATH and that docker info responds; if either check fails, dataset creation raises a RuntimeError explaining what is missing. Install the Neo4j dependencies, since this handler uses the Neo4j graph database provider:

​
Environment Variables

NEO4J_ENCRYPTION_KEY defaults to "test_key" if not set. Always set a strong random key in production to protect the per-dataset container passwords stored in Cognee’s relational database.
Every running container is a full Neo4j server and consumes CPU and RAM. Tune NEO4J_COMMUNITY_MAX_CONTAINERS to the concurrency your host can actually sustain — it defaults to DATABASE_MAX_LRU_CACHE_SIZE so the container pool tracks the graph-engine cache capacity.

​
How It Works

When a dataset is created, Cognee:
  1. Verifies Docker is available.
  2. Picks a free localhost port and runs a neo4j:5-community container named cognee-neo4j-<dataset_id> with a named data volume cognee-neo4j-data-<dataset_id>, where <dataset_id> is the dataset’s UUID without dashes. The bolt port is published on 127.0.0.1 only, and stays fixed for the container’s lifetime.
  3. Generates a random per-dataset password, encrypts it with Fernet, and stores it together with the container name, volume name, and host port in the DatasetDatabase row.
  4. Waits until a Neo4j server answers a bolt protocol handshake on the published port (a plain TCP connect is not a readiness signal — docker-proxy accepts connections before Neo4j listens).
Containers are labelled ai.cognee.neo4j_community=true and ai.cognee.dataset_id=<dataset_id>, so Cognee only ever inspects, stops, or removes containers it created itself. Auto-start. Before every operation on a dataset, Cognee decrypts the credentials and starts the container if it is stopped. Graph data lives on the named volume, so it survives container stops and Cognee restarts. Auto-stop. Container lifetime follows the graph-engine LRU cache: once a dataset’s engine is evicted and no caller holds it, the dataset is idle and its container is stopped. The next operation on that dataset starts it again. Container ceiling. Before a container starts, Cognee counts the running containers it manages (including ones that survived a restart, found via a docker ps label filter) and stops least-recently-used ones until there is room under NEO4J_COMMUNITY_MAX_CONTAINERS.
Deleting a dataset is irreversible. delete_dataset removes both the dataset’s container and its named Docker volume, so all graph data for that dataset is destroyed. Back up the volume first if you need to keep it.
If a container is removed outside of Cognee, the next operation on that dataset fails with an error telling you to delete and re-create the dataset so a fresh container can be provisioned. Container startup problems are visible through docker logs cognee-neo4j-<dataset_id>.

Graph Stores

Details About Cognee’s Graph Stores

Multi-User Overview

More Details About Multi-User Mode