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

# Custom Knowledge Graphs

> Build and query runtime knowledge graphs using the Graph Query Tool and Cypher — for agent-driven graph population and retrieval.

Airia supports two approaches to knowledge graphs. This page covers **Custom Knowledge Graphs** — runtime graphs that agents populate and query dynamically using Cypher.

> 💡 **Which approach should I use?**
>
> * **[Knowledge Graph Extraction](/context-engineering/knowledge-graph-extraction)** — Automatic, ingestion-time entity extraction from your documents. Entities and relationships are built during data processing. Best for RAG use cases where you want structured knowledge extracted from your data sources automatically.
>
> * **Custom Knowledge Graphs** (this page) — Runtime graphs that agents populate and query via the Graph Query Tool and Cypher. Best for use cases where agents capture information from conversations, external APIs, or structured workflows and store it in a graph for later retrieval.
>
> You can use both approaches in the same project.

## Create a Knowledge Graph

1. Navigate to the **Knowledge Graphs** tab in your project
2. Click the **New Graph** button
3. Configure the graph settings:
   * **Scope** — "Current Project" or "All Projects"
   * **Access** — Optionally restrict to your user account

## Populate the Graph

To write data into your graph, create a **Graph Query Tool**:

1. Go to the **Tools** section
2. Select the **"Query Graph DB"** tool template
3. Link the tool to your Knowledge Graph

The same Graph Query DB tool serves for both **writing and reading** operations — it uses a shared Cypher endpoint for both capturing and querying information.

### Writing Data via an Agent

Instruct your agent to capture structured information into the graph. For example, in your agent's system prompt:

```
When the user mentions a new customer, create a node in the knowledge graph
with the customer name, industry, and contact information.
When they mention a relationship between entities, create an edge connecting them.
```

The agent uses the Graph Query Tool to execute Cypher `CREATE` and `MERGE` statements that populate the graph.

## Query the Graph

Attach the same Graph Query Tool to any agent that needs to read from the graph. The agent can formulate Cypher queries to:

* Find specific entities: `MATCH (n:Customer {name: 'Acme'}) RETURN n`
* Traverse relationships: `MATCH (c:Customer)-[:PURCHASED]->(p:Product) RETURN c, p`
* Aggregate data: `MATCH (n) RETURN labels(n), count(n)`

## Inspect the Graph

To view the data in your graph:

1. Navigate to **Knowledge Graphs** in your project
2. Click **See Graph Info** on your graph
3. Examine nodes and relationships

## Best Practices

* **Use descriptive node labels** — `Customer`, `Product`, `Regulation` are better than `Node1`, `Entity`
* **Include properties on nodes** — Store relevant attributes so agents can query by specific fields
* **Use consistent naming** — If multiple agents write to the same graph, agree on a schema
* **Test Cypher queries manually** before deploying in production agents