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

# Knowledge graphs (GraphRAG)

> Extract an entity-relationship graph from a knowledge base and retrieve over it with multi-hop traversal.

A knowledge base can build a **knowledge graph** on top of its documents: named
entities and the typed relationships between them, extracted at ingest. Agents
then retrieve over it with **GraphRAG** - vector search to find relevant
passages, plus multi-hop traversal of the graph to pull in connected facts. That
answers relational questions ("how is X connected to Y?", "what did X acquire and
who runs it?") that plain similarity search misses.

This builds on ordinary [knowledge bases](/docs/concepts/knowledge); enable it
per base.

## How it works

1. Create a knowledge base with **Build a knowledge graph** turned on, and pick
   an **extraction model** (see below).
2. Add documents. Each is split with **hierarchical chunking**: small child
   chunks are embedded for precise retrieval, and grouped under larger parent
   blocks that give the model richer context.
3. A background **graph-worker** runs the extraction model over each parent
   block and writes the entities, typed relationships, and provenance back to
   the chunk each fact came from.
4. **Retrieval** matches child chunks by vector, links them to their graph
   entities, traverses the typed-edge graph up to two hops, and returns the
   parent passages plus the related facts.

Embeddings still come from the [self-hosted embedder](/docs/concepts/knowledge)
(`bge-small-en-v1.5`); only the entity/relationship extraction uses a chat
model.

## The extraction model

Extraction runs on **your own model**, resolved through the
[model gateway](/docs/concepts/models): the extraction model is a fully-qualified
name like `openrouter/openai/gpt-4o-mini`, whose provider prefix must match a
provider you have connected. Its cost lands on your provider connection.

<Warning>
  The extraction model is **required** when the graph is enabled. If a base has no
  extraction model, its documents ingest and embed normally but their graph shows
  `error`. A cheap, JSON-reliable model such as `openrouter/openai/gpt-4o-mini` is
  a good default.
</Warning>

## The graph inspector

The knowledge base page shows a **graph tab** once extraction finishes. It lays
the entities out with a force-directed layout so connected entities cluster,
colors them by type, and lets you filter to the neighborhood of a named entity.
Each document also shows a `graph:` status (`pending` → `ready`, or `error`)
alongside its ingest status.

## From an agent

Add a tool with the built-in key `graph_search` and reference it from an agent
node. At run time the agent calls `graph_search(query)`, which returns relevant
passages **plus** the entities and typed relationships connected to them:

```
Passages:
- Acme Corporation was founded by Jane Doe in 2010. In 2020 Acme acquired ...

Related facts (knowledge graph):
- Acme Corporation FOUNDED_BY Jane Doe
- Acme Corporation ACQUIRED Beta Analytics
- Beta Analytics LED_BY John Smith
```

Use `graph_search` instead of (or alongside) `knowledge_search` when questions
are about how things relate, not just what a passage says.

## API

* `POST /v1/knowledge` with `"graph_enabled": true` and `"graph_model": "<fqn>"` -
  create a graph-enabled base
* `GET /v1/knowledge/{kb}/graph` - the extracted graph (`stats`, `nodes`,
  `edges`); optional `entity` filter and `limit`
* `GET /v1/knowledge/{kb}/documents` - each document's `graph_status`

See the [API overview](/docs/api-reference/overview).

## Notes

* **Multi-tenant and private.** The graph is stored in the same Postgres as
  everything else, scoped by row-level security to your workspace.
* **Re-ingesting** a document rebuilds its part of the graph; it does not leave
  stale entities or edges behind.
* **Extraction quality** depends on the document. Prose rich in named things and
  explicit relationships (bios, org policies, contracts, reports) yields dense
  graphs; free-form narrative yields sparser ones. Every extracted fact is
  grounded in the source text - the extractor is instructed never to invent
  relationships.