Skip to main content
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; 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 (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: 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.
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.

​
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:
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.

​
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.