ApeRAG: Five Index Types, One Retrieval Stack, and a Helm Chart

The problem ApeRAG picks: retrieval that outgrows a single vector index

A single embedding index answers similarity questions well and relational questions badly. Ask who reports to whom across three documents and a vector search returns passages that mention both names, not the edge between them. ApeRAG's answer is to run five index types over the same corpus, listed in the README as Vector, Full-text, Graph, Summary and Vision, and to let a retrieval layer choose among them. The target user is a team that has already decided a plain vector store is not enough and is willing to operate the storage to fix that. The README's own framing is building a knowledge graph and context engineering, then deploying agents that search across it. That is a narrower audience than the generic RAG platform label suggests. If your documents are flat, short and independent, the graph index is cost without return.

What the retrieval stack actually contains

The graph side is not built from scratch. The README states ApeRAG uses a deeply modified LightRAG implementation with entity normalization, described as entity merging, to produce cleaner knowledge graphs. Entity merging is the mechanism worth understanding before you trust the output: when two surface forms resolve to the same node, the graph gets smaller and traversal gets cheaper, but an over-eager merge fuses entities that should stay separate, and nothing in the supplied material describes the merge threshold or how to inspect or reverse a merge. The five index types are not five copies of the same data. Vector and full-text indexes are conventional. The graph index stores entities and relations. Summary indexing implies a per-document or per-chunk summarization pass, and vision indexing implies image and chart content is embedded or described separately. Each of those is an additional write path that runs when a document is ingested, so ingestion latency scales with the number of enabled indexes, not just document size. The README does not give ingestion throughput figures, and I have not run it, so treat the cost as unquantified until you measure it on your own corpus.

Agents and the MCP endpoint: how an outside assistant reaches your collections

ApeRAG exposes a Model Context Protocol server, which is the part most teams will evaluate first because it is the cheapest to try. The README gives the client configuration directly: an mcpServers entry named aperag-mcp pointing at http://localhost:8000/mcp/, with an Authorization header carrying a bearer token. Authentication resolves in a stated priority order: the HTTP Authorization header first, then the APERAG_API_KEY environment variable as a fallback. The README also warns to substitute your deployed origin when the service is not local, which matters because the default URL is localhost and will silently fail from a remote client. The MCP server exposes three capability groups per the README: collection browsing, hybrid search across vector, full-text and graph methods, and natural language querying over documents. Separately, the platform ships built-in agents that the README says identify relevant collections on their own, search, and add web search. The gap is that collection auto-selection is a routing decision made by a model, and the supplied material gives no accuracy figure for it. If your collections have overlapping vocabulary, test routing before you rely on it.

Getting it running: Compose first, Helm when you mean it

The documented minimum is 2 CPU cores, 4 GiB RAM, Docker and Docker Compose. The quick start is four commands: clone the repository, change into it, copy envs/env.template to .env, then run docker-compose up -d --pull always. The web interface lands on port 3000 at /web/ and the API documentation on port 8000 at /docs. Enhanced parsing is a separate Compose profile rather than a default, which is the right call given it pulls in another service. The README shows two ways to enable it: setting DOCRAY_HOST to the aperag-docray service on port 8639 and running docker compose --profile docray up -d, or the GPU variant against aperag-docray-gpu. The Makefile shortcuts are make compose-up WITH_DOCRAY=1 and make compose-up WITH_DOCRAY=1 WITH_GPU=1, and the README marks the GPU path as recommended. For Kubernetes, the prerequisites are a cluster at v1.20 or later, kubectl, and Helm v3 or later, and the README states ApeRAG requires PostgreSQL, Redis, Qdrant and Elasticsearch, with a choice between deploying those yourself and using the provided path. Note that the README text supplied here cuts off mid-sentence at that choice, so the exact second option is not confirmable from this material.

Four stateful services is the real deployment cost

The dependency list is the constraint that decides most adoption questions. PostgreSQL, Redis, Qdrant and Elasticsearch are all named as required, and the Kubernetes section points at Helm charts plus KubeBlocks integration for deploying production-grade versions of them. That is four systems with their own backup, upgrade and capacity stories, plus the ApeRAG services on top. Redis implies Celery task processing, which the README confirms when it describes async task processing with Celery in the developer-facing feature list. Elasticsearch is the heaviest of the four to operate. A team that already runs these is adding an application. A team that does not is taking on a search cluster to answer questions about its own documents, and should price that honestly before starting. The 4 GiB minimum in the quick start is a floor for trying the stack, not a sizing figure for a corpus, and the README offers no guidance on what corpus size maps to what footprint. That omission is the single biggest planning gap in the documentation.

Where ApeRAG is the wrong tool

Two cases stand out. The first is a small, static corpus. If a few hundred pages answer your questions, the graph and summary indexes add ingestion passes and storage for retrieval quality you may not be able to measure. A plain vector store with a reranker is a shorter path. The second is a team without platform capacity. Four stateful services, a Celery worker tier, a FastAPI backend and a React frontend is an application you operate, not a library you import. There is also the release cadence to weigh: the recent releases are v0.7.0-alpha.34, alpha.33 and alpha.32, published two days apart in March 2026, and the alpha label is the project's own. Rapid alpha iteration means interfaces can move between tags. Pin a specific tag and read the diff before upgrading rather than tracking main. Finally, the entity normalization behaviour is a genuine unknown: the README presents it as an improvement, and it may well be, but merging is lossy by definition and no inspection or rollback path is documented in the material supplied.

The alternative that changes the trade, and the one that does not

The obvious comparison is LightRAG itself, since ApeRAG states it is a deeply modified LightRAG implementation. The difference in approach is scope. LightRAG is a graph-based retrieval library you embed in your own application, and you supply the storage. ApeRAG is the application: it adds the vector, full-text, summary and vision indexes alongside the graph index, wraps them in a FastAPI backend and React frontend, adds Celery task processing, an MCP server, audit logging and model management, and ships a Helm chart. If graph retrieval is the only thing you need, adopting the library and choosing your own two or three services is less to run. If you need the multi-index hybrid plus an MCP endpoint plus a management UI, assembling that from a library is weeks of work that ApeRAG has already done. The honest framing is that ApeRAG trades operational surface for integration work you would otherwise do yourself, and that trade only pays if the integration work is real for you.

Licence, maintenance and what to verify before you commit

ApeRAG is Apache-2.0, which permits commercial use and modification and includes a patent grant. The practical implication is that you can fork and ship it, but you inherit the obligation to carry the licence and notice files, and if you modify the LightRAG-derived portions you are tracking upstream changes across a fork of a fork. That is a maintenance cost, not a legal problem, and it is the kind of thing worth a conversation with counsel rather than a decision made from a README. On upgrade cost, the alpha versioning means you should read release notes between tags and expect schema or config changes; the repository keeps a development guide and a separate document on building the Docker image, which is where configuration drift will show up first. Before adopting, verify three things on your own data: whether entity merging separates the entities you care about, whether your document formats need the docray profile at all or parse acceptably without it, and what the four backing services cost you per month at your corpus size. The Compose file at the repository root answers the second question in an afternoon.

Editorial conclusion

Adopt ApeRAG if you already run PostgreSQL, Redis, Qdrant and Elasticsearch and want graph retrieval plus an MCP endpoint without writing the retrieval layer yourself. Do not adopt it if you want a single-binary local tool or cannot operate four stateful services, and note that the current release line is v0.7.0-alpha, so pin a tag rather than tracking main. Before committing, verify two things against your own corpus: whether entity normalization collapses entities you need kept apart, and whether the docray parsing profile is required for your document formats. Start with the Compose file at the repository root, not the Helm chart.

Official sources

1. apecloud/ApeRAG on GitHub
2. Issues
3. License: Apache-2.0
4. README
5. Releases