Skip to main content
Version: 0.0.6

Architecture

Agentic GraphRAG has two connected flows: ingestion builds a graph from source documents, and agents use that graph to find evidence, answer questions, and record their work. The graph keeps links between facts and their source text, so an answer can use both structure and passages. Tasks and decisions live in the same graph and point back to the passages they rely on.

Why it exists​

A vector search finds passages that resemble a question, but it does not connect facts across passages. A graph adds those links while retaining the source text needed to support an answer.

Agentic GraphRAG stores the facts as a graph and keeps the source text next to them. A question can use both: the passage that states a fact, and the entities that connect passages.

The components separate source parsing, graph construction, search, and memory. You can replace embedding components through their interfaces. The Graph storage page explains how Neo4j stores the graph and its indexes.

How it works​

Graph.add calls ingestion, which writes the graph store. The built-in agent and the MCP server call evidence, which reads the graph store, and memory, which reads and writes it. A document change makes ingestion flag decisions in memory. You pass in the embedder, the schema, and the LLM.Graph.add calls ingestion, which writes the graph store. The built-in agent and the MCP server call evidence, which reads the graph store, and memory, which reads and writes it. A document change makes ingestion flag decisions in memory. You pass in the embedder, the schema, and the LLM.

Graph.add runs ingestion, which writes the graph store. The agent and the MCP server read it through evidence and read and write it through memory. The Agent loop page shows the steps in detail.

Ingestion loads each source as a document, chunks its text, extracts and resolves entity mentions, then stores the graph and embeddings. The Ingestion pipeline page explains how these stages handle updates and failures.

At query time, one task-scoped agent discovers and fetches evidence from the graph, then writes an answer that cites only the evidence it fetched. It records its messages, tool results, and decisions as task memory in the same graph. The Agent loop page explains when the agent searches again and where its limits apply.

You call Graph.add for the first flow and build_agent for the second. An MCP client reaches the same graph through agrag-mcp. All of them use the same graph store and embedder.

Example​

A note says that Ada Lovelace worked with Charles Babbage in London on the Analytical Engine. The loader makes one document. The chunker makes one chunk. The extractor finds entities such as two people, one place and one product. The store writes the document, the chunk and the entities, and links the chunk to each entity. A later question about Babbage finds the chunk through the Babbage entity, and the answer cites that chunk.

Design choices

Where are the embeddings kept? In Neo4j, next to the graph. The Graph storage page explains why. The graph keeps structure and provenance, and the native vector index finds similar text fast.

Why must you pass in the components? Graph.open takes the store, the embedder, the extractor and the schema as arguments. The library has no global configuration for them. Two graphs in one process can use different stores. A test can pass a fake.

Why is the schema required? Extraction, validation and storage all use the schema. Without one, each stage guesses what an entity is. DEFAULT_SCHEMA gives a starting point.

Why are the public APIs async? Ingestion and search wait on models and databases. Async calls let the library run those waits together.