awslabs/graphrag-toolkit: two Python packages for graph-backed retrieval, and the storage decisions they force

The gap lexical-graph fills between chunked embeddings and multi-hop questions

Plain vector RAG splits a document into chunks, embeds each chunk, and retrieves the nearest ones at question time. That works when the answer sits inside a single chunk. It degrades when the answer requires joining facts that live in different chunks, or when the question is about a relationship rather than a passage. The lexical-graph package addresses this by automating construction of what the README calls a hierarchical lexical graph from unstructured data, then composing question-answering strategies that query that graph. The hierarchy is the point: the arXiv article linked from the README, Hierarchical Lexical Graph for Enhanced Multi-Hop Retrieval, describes the design of that model, so the structure is documented rather than implied. The audience is engineers building GenAI applications who have already concluded that chunk retrieval alone is not enough and who are willing to run a graph database next to their vector store. It is not a drop-in replacement for a vector index, and nothing in the material suggests it is intended to be one.

What the lexical graph actually contains and how a question reaches it

The graph model page in the published docs is the reference for the node and edge structure, and the README points there directly rather than restating it. What the repository layout makes clear is the division of labour: the lexical-graph directory holds the construction pipeline and the retrieval strategies, and the byokg-rag directory holds a separate system. The data flow implied by the README is extraction from unstructured text into graph nodes and edges, storage in a graph database, and then query-time traversal combined with vector search. The topics listed for the repository name the stores involved: amazon-neptune, amazon-opensearch-serverless, graph-database, postgresql. So the intended deployment pairs a graph store with a vector store and queries both. The README's own framing of the companion video is that vector search and graph search work differently and can be used together to improve accuracy, which is a more modest claim than replacing one with the other. Treat the graph as an additional retrieval path, not a substitute.

byokg-rag assumes you already have a graph, which changes the entire onboarding path

BYOKG-RAG is described in the README as an approach to Knowledge Graph Question Answering that combines LLMs with structured knowledge graphs, and the name states the constraint: bring your own knowledge graph. There is no extraction pipeline to run here, because the graph is an input rather than an output. That makes it a different kind of adoption decision from lexical-graph. If your organisation already maintains a curated graph, byokg-rag is the package that operates over it. If you do not, byokg-rag has nothing to query and lexical-graph is the entry point instead. The two packages sit at opposite ends of the same problem, and the release history treats them as separate artefacts: graphrag-lexical-graph and graphrag-byokg are versioned and published independently, both reaching v3.19.1 on the same day. Installing one does not install the other's assumptions. Check which package matches your starting position before reading further into the docs, because the tutorials diverge immediately.

Installation, the workshop notebook, and what the docs leave to you

Both packages are published to PyPI under the names shown in the README badges, graphrag-lexical-graph and graphrag-byokg, so installation is a pip install of the package you need. The README does not print a full command, and I am not going to invent one. The docs site at awslabs.github.io/graphrag-toolkit is described as the starting point, and the repository ships a self-guided workshop under examples/lexical-graph/workshop as a set of Jupyter notebooks. That workshop is the fastest way to see the configuration surface, because the README does not enumerate config keys, connection strings, or environment variables. The topics list tells you which backends are in scope, and the docs are where the per-backend setup lives. Expect to supply credentials and endpoints for a graph store and a vector store before anything runs. The absence of a quickstart command in the README is a real friction point for evaluation: you cannot judge the API from the repository front page alone.

The store coupling is the main limitation, and it is structural

Every topic on the repository points at a managed AWS service or at PostgreSQL: amazon-neptune, amazon-opensearch-serverless, postgresql. That is a narrower footprint than a general-purpose GraphRAG library, and it is the constraint most likely to rule the toolkit out. If your organisation runs a different graph database, the material gives no indication that a backend abstraction exists to swap in. The second limitation is operational: you are now responsible for two data systems rather than one. Ingestion has to keep the graph and the vector index consistent, and the toolkit's construction pipeline is the thing that writes both. When extraction produces a poor graph, retrieval quality drops in ways that are harder to debug than a bad embedding, because the failure is in the structure rather than in a similarity score. A third point, stated plainly: the README does not describe evaluation tooling, and the RAG Explorer sample is an external repository for comparing GraphRAG and vector RAG responses. If you need to prove the graph path beats chunk retrieval on your corpus, that comparison is work you do yourself.

How it differs from LlamaIndex's property graph index

LlamaIndex is listed among the repository topics and its property graph index is the closest well-known alternative. The difference is where the abstraction sits. LlamaIndex defines an extraction and query interface and lets you attach a graph store from a wider set, with the schema emerging from what the extractor produces. The lexical graph here is a specified model with a published design article, and the toolkit's value is that the construction pipeline and the retrieval strategies are built around that one model rather than around a generic graph. You trade backend portability for a structure that was designed for multi-hop retrieval. That trade is defensible when you are already on Neptune or PostgreSQL and want the graph shape decided for you. It is the wrong trade when your graph store is fixed by an existing platform team and is not on the supported list. The other listed integration, mcp, matters for a different reason: it means the toolkit can be exposed to agent frameworks through the Model Context Protocol rather than only through direct Python calls.

Licence, versioning, and what an upgrade actually costs

The project is Apache-2.0, which permits commercial use, modification, and redistribution provided you keep the licence and notices intact. That is a permissive licence and it removes the source-availability question that copyleft alternatives raise. It does not remove the operational question. The release history shows the two packages versioned in lockstep at v3.19.1 with dev builds such as graphrag-lexical-graph/v3.19.1.dev1 published days before the stable tag. If you pin to a dev build you are tracking a moving target. Because the graph model is the contract, an upgrade that changes extraction output can leave existing graph data in an older shape, and the material does not describe a migration path for stored graphs. Budget for re-ingestion when the graph model changes, not just for a dependency bump. This is not legal advice; read the LICENSE file and your own counsel's guidance on attribution if you redistribute.

Editorial conclusion

Adopt it if you already run Amazon Neptune, Neptune Analytics, or PostgreSQL with pgvector and want the graph model and retrieval strategies handled for you rather than assembled from scratch. Do not adopt it if you need a store-agnostic retrieval layer or you cannot commit to maintaining a graph schema alongside your vector index. Before writing code, read the graph-model page in the docs and confirm which store backends your installed version supports, because the two packages version independently and the release history shows dev builds interleaved with stable ones.

Official sources

1. awslabs/graphrag-toolkit on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases