> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cognee.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Graph Stores

> Configure graph databases for knowledge graph storage and relationship reasoning in Cognee

Graph stores capture entities and relationships in knowledge graphs. They enable Cognee to understand structure and navigate connections between concepts, providing powerful reasoning capabilities.

<Info>
  **New to configuration?**

  See the [Setup Configuration Overview](./overview) for the complete workflow:

  install extras → create `.env` → choose providers → handle pruning.
</Info>

## Supported Providers

Cognee supports multiple graph store options:

* **Kuzu** — Local file-based graph database (default)
* **Kuzu-remote** — Kuzu with HTTP API access
* **Neo4j** — Production-ready graph database (self-hosted or Docker)
* **Neo4j Aura** — Neo4j's fully managed cloud service
* **Neptune** — Amazon Neptune cloud graph database
* **Neptune Analytics** — Amazon Neptune Analytics hybrid solution
* **Memgraph** — In-memory graph database (community adapter)

<Info>
  **Local vs. cloud storage**: By default Cognee stores its graph in a local Kuzu file. To persist data in the cloud, switch to a remote provider such as Neo4j Aura, Neptune, or a self-hosted Neo4j instance on a remote server.
</Info>

## Configuration

<Accordion title="Environment Variables">
  Set these environment variables in your `.env` file:

  * `GRAPH_DATABASE_PROVIDER` — The graph store provider (kuzu, kuzu-remote, neo4j, neptune, neptune\_analytics)
  * `GRAPH_DATABASE_URL` — Database URL or connection string
  * `GRAPH_DATABASE_USERNAME` — Database username (optional)
  * `GRAPH_DATABASE_PASSWORD` — Database password (optional)
  * `GRAPH_DATABASE_NAME` — Database name (optional)
</Accordion>

## Setup Guides

<AccordionGroup>
  <Accordion title="Kuzu (Default)">
    Kuzu is file-based and requires no network setup. It's perfect for local development and single-user scenarios.

    ```dotenv theme={null}
    GRAPH_DATABASE_PROVIDER="kuzu"
    # Optional: override location
    # SYSTEM_ROOT_DIRECTORY=/absolute/path/.cognee_system
    # The graph file will default to <SYSTEM_ROOT_DIRECTORY>/databases/cognee_graph_kuzu
    ```

    **Installation**: Kuzu is included by default with Cognee. No additional installation required.

    **Data Location**: The graph is stored on disk. Path defaults under the Cognee system directory and is created automatically.

    <Warning>
      **Concurrency Limitation**: Kuzu uses file-based locking and is not suitable for concurrent use from different agents or processes. For multi-agent scenarios, use Neo4j instead.
    </Warning>
  </Accordion>

  <Accordion title="Kuzu (Remote API)">
    Use Kuzu with an HTTP API when you need remote access or want to run Kuzu as a service.

    ```dotenv theme={null}
    GRAPH_DATABASE_PROVIDER="kuzu-remote"
    GRAPH_DATABASE_URL="http://localhost:8000"
    GRAPH_DATABASE_USERNAME="<optional>"
    GRAPH_DATABASE_PASSWORD="<optional>"
    ```

    **Installation**: Requires a running Kuzu service exposing an HTTP API.
  </Accordion>

  <Accordion title="Neo4j (Self-Hosted)">
    Neo4j is recommended for production environments where you need a powerful, dedicated graph database. Data is stored on the Neo4j server (local or remote), not on the Cognee host machine.

    ```dotenv theme={null}
    GRAPH_DATABASE_PROVIDER="neo4j"
    GRAPH_DATABASE_URL="bolt://localhost:7687"
    GRAPH_DATABASE_NAME="neo4j"
    GRAPH_DATABASE_USERNAME="neo4j"
    GRAPH_DATABASE_PASSWORD="pleaseletmein"
    ```

    **Installation**: Install Neo4j extras:

    ```bash theme={null}
    pip install "cognee[neo4j]"
    ```

    **Docker Setup**: Start the bundled Neo4j service with APOC + GDS plugins:

    ```bash theme={null}
    docker compose --profile neo4j up -d
    ```
  </Accordion>

  <Accordion title="Neo4j Aura (Cloud)">
    [Neo4j Aura](https://neo4j.com/docs/aura/) is Neo4j's fully managed cloud service. Graph data is stored in Neo4j's cloud infrastructure — nothing is stored locally on your machine.

    There are two ways to use Neo4j Aura with Cognee:

    **Option 1 — Connect to an existing Aura instance**

    Create a free or paid Aura instance at [console.neo4j.io](https://console.neo4j.io), then point Cognee at it using the `neo4j+s://` connection URI provided in your Aura console:

    ```dotenv theme={null}
    GRAPH_DATABASE_PROVIDER="neo4j"
    GRAPH_DATABASE_URL="neo4j+s://<your-instance-id>.databases.neo4j.io"
    GRAPH_DATABASE_NAME="neo4j"
    GRAPH_DATABASE_USERNAME="neo4j"
    GRAPH_DATABASE_PASSWORD="<your-aura-password>"
    ```

    **Option 2 — Auto-provisioned Aura instances per dataset (multi-user mode)**

    Cognee's `Neo4jAuraDevDatasetDatabaseHandler` can automatically create and delete a dedicated Neo4j Aura instance for each Cognee dataset. This requires Neo4j Aura API credentials (OAuth):

    ```dotenv theme={null}
    GRAPH_DATABASE_PROVIDER="neo4j"
    GRAPH_DATASET_DATABASE_HANDLER="neo4j_aura_dev"
    NEO4J_CLIENT_ID=<your_oauth_client_id>
    NEO4J_CLIENT_SECRET=<your_oauth_client_secret>
    NEO4J_TENANT_ID=<your_aura_tenant_id>
    NEO4J_ENCRYPTION_KEY=<key_for_encrypting_stored_credentials>
    ```

    See the [Neo4j Aura Dataset Database Handler](/core-concepts/multi-user-mode/dataset-database-handlers/existing-dataset-database-handlers/neo4j-aura-dev) page for full details on Option 2.

    **Installation**: Install Neo4j extras:

    ```bash theme={null}
    pip install "cognee[neo4j]"
    ```
  </Accordion>

  <Accordion title="Neptune (Graph-only)">
    Use Amazon Neptune for cloud-based graph storage.

    ```dotenv theme={null}
    GRAPH_DATABASE_PROVIDER="neptune"
    GRAPH_DATABASE_URL="neptune://<GRAPH_ID>"
    # AWS credentials via environment or default SDK chain
    ```

    **Installation**: Install Neptune extras:

    ```bash theme={null}
    pip install "cognee[neptune]"
    ```

    **Note**: AWS credentials should be configured via environment variables or AWS SDK.
  </Accordion>

  <Accordion title="Neptune Analytics (Hybrid)">
    Use Amazon Neptune Analytics as a hybrid vector + graph backend.

    ```dotenv theme={null}
    GRAPH_DATABASE_PROVIDER="neptune_analytics"
    GRAPH_DATABASE_URL="neptune-graph://<GRAPH_ID>"
    # AWS credentials via environment or default SDK chain
    ```

    **Installation**: Install Neptune extras:

    ```bash theme={null}
    pip install "cognee[neptune]"
    ```

    **Note**: This is the same as the vector store configuration. Neptune Analytics serves both purposes.
  </Accordion>
</AccordionGroup>

## Advanced Options

<Accordion title="Backend Access Control">
  Enable per-user dataset isolation for multi-tenant scenarios.

  ```dotenv theme={null}
  ENABLE_BACKEND_ACCESS_CONTROL="true"
  ```

  This feature is available for Kuzu and other supported graph stores.
</Accordion>

## Provider Comparison

<Accordion title="Graph Store Comparison">
  | Provider            | Data Location | Setup                 | Performance | Use Case              |
  | ------------------- | ------------- | --------------------- | ----------- | --------------------- |
  | Kuzu                | Local disk    | Zero setup            | Good        | Local development     |
  | Kuzu-remote         | Remote server | Server required       | Good        | Remote access         |
  | Neo4j (self-hosted) | Neo4j server  | Server required       | Excellent   | Production            |
  | Neo4j Aura          | Neo4j cloud   | Aura account required | Excellent   | Managed cloud         |
  | Neptune             | AWS cloud     | AWS required          | Excellent   | Cloud solution        |
  | Neptune Analytics   | AWS cloud     | AWS required          | Excellent   | Hybrid cloud solution |
</Accordion>

## Important Considerations

<Accordion title="Data Location">
  * **Local providers** (Kuzu): Graph files are created automatically under `SYSTEM_ROOT_DIRECTORY`
  * **Remote providers** (Neo4j, Neptune): Require running services or cloud setup
  * **Path management**: Local graphs are managed automatically, no manual path configuration needed
</Accordion>

<Accordion title="Performance Notes">
  * **Kuzu**: Single-file storage with good local performance
  * **Neo4j**: Excellent for production workloads with proper indexing
  * **Neptune**: Cloud-scale performance with managed infrastructure
  * **Hybrid solutions**: Combine graph and vector capabilities in one system
</Accordion>

## Community-Maintained Providers

Additional graph stores are available through community-maintained adapters:

* **[Memgraph](/setup-configuration/community-maintained/memgraph)** — In-memory graph database (Bolt protocol)

## Notes

<AccordionGroup>
  <Accordion title="Backend Access Control">
    When backend access control is enabled, Cognee can isolate graph data per dataset for supported providers such as Kuzu. This is mainly relevant for multi-user deployments where different users or workloads should not share the same graph state by default.
  </Accordion>

  <Accordion title="Path Management">
    For local Kuzu setups, Cognee creates and manages the graph database automatically under the system directory. In most cases you do not need to manually create graph files or point Cognee at a specific path unless you are customizing `SYSTEM_ROOT_DIRECTORY`.
  </Accordion>

  <Accordion title="Cloud Integration">
    Neptune-based setups rely on AWS credentials, network access, and the appropriate IAM permissions to connect successfully. Before using Neptune or Neptune Analytics, make sure your environment can authenticate through the standard AWS SDK credential chain.
  </Accordion>

  <Accordion title="Neo4j Type Labels">
    **APOC is required for Neo4j type labels.** Cognee uses `apoc.create.addLabels` to apply type-specific labels to every node. Without it, Cognee can still store nodes, but Neo4j will only show the generic `__Node__` label, making entity types harder to inspect directly.

    The bundled Docker Compose Neo4j profile already includes APOC. For self-hosted Neo4j instances, install the [APOC plugin](https://neo4j.com/docs/apoc/current/installation/) before connecting Cognee.
  </Accordion>

  <Accordion title="Troubleshooting: 'No nodes found'">
    The warning `No nodes found in the database` means the graph DB at the current path is empty. Common causes:

    <AccordionGroup>
      <Accordion title="Path mismatch between runs">
        For Kuzu, the graph is stored on disk at:

        ```text theme={null}
        {SYSTEM_ROOT_DIRECTORY}/databases/cognee_graph_kuzu
        ```

        `SYSTEM_ROOT_DIRECTORY` defaults to a `.cognee_system` folder inside the installed Cognee package directory (typically inside your virtual environment). If this path resolves differently across sessions — for example, after reinstalling packages or using a different virtual environment — each session sees an empty graph.

        Pin it to an explicit absolute path in your `.env`:

        ```dotenv theme={null}
        SYSTEM_ROOT_DIRECTORY=/home/user/my-project/.cognee_system
        ```

        Raw ingested files (added via `add()`) are stored separately under `DATA_ROOT_DIRECTORY`, which defaults to `.data_storage` in the same package directory. Set both if you want fully portable storage:

        ```dotenv theme={null}
        SYSTEM_ROOT_DIRECTORY=/home/user/my-project/.cognee_system
        DATA_ROOT_DIRECTORY=/home/user/my-project/.data_storage
        ```
      </Accordion>

      <Accordion title="Data not yet processed in this session">
        The graph persists on disk between runs — you do not need to re-run `add()` + `cognify()` every time. Calling `search()` or [`visualize_graph()`](/guides/graph-visualization) in a new session will find existing data, as long as `SYSTEM_ROOT_DIRECTORY` points to the same location as the original ingestion run.
      </Accordion>

      <Accordion title="Graph was pruned">
        `cognee.prune.prune_system()` deletes all graph and system data. Re-run `add()` and `cognify()` to rebuild it.
      </Accordion>
    </AccordionGroup>
  </Accordion>
</AccordionGroup>

<Columns cols={3}>
  <Card title="Vector Stores" icon="database" href="/setup-configuration/vector-stores">
    Configure vector databases for embedding storage
  </Card>

  <Card title="Relational Databases" icon="database" href="/setup-configuration/relational-databases">
    Set up SQLite or Postgres for metadata storage
  </Card>

  <Card title="Overview" icon="settings" href="/setup-configuration/overview">
    Return to setup configuration overview
  </Card>
</Columns>