HippoRAG 2: graph-based RAG that keeps LLM memory associative

What HippoRAG 2 is for, and who should care

HippoRAG 2 is a memory framework for LLMs that, in the README's phrasing, recognizes and uses connections in new knowledge. The problem it targets is specific: a vector index retrieves passages that look like the question, but questions that require joining facts across several documents (multi-hop retrieval) tend to fail because the connecting passage never mentions the query terms. The project's own framing splits this into associativity and sense-making, and the README claims improvements on both without sacrificing performance on simpler tasks. The audience is therefore teams already running RAG who have hit that ceiling, not people looking for a first retrieval stack. The repository is Python, MIT licensed, and the current version in pyproject.toml is 2.0.0a5, which is an alpha tag even though the last push was on 2026-09-03. The only tagged release listed is v1.0.0 from 2025-02-27, and the README points HippoRAG 1 users at the legacy branch. If you are evaluating this for production, you are evaluating an alpha-versioned package, and the README's own upgrade section is written for people who are already running it.

The retrieval mechanism: OpenIE graph plus Personalized PageRank

The architecture visible in the repository is a pipeline rather than a single model. Indexing extracts open information (OpenIE) from your documents and builds a knowledge graph, which is why networkx and python_igraph are pinned dependencies. Embeddings are stored alongside it, and the optional extras (milvus, qdrant, chroma, transformers-embedding, gritlm, vllm) determine which vector store and which local model backend you use. At query time, retrieval runs Personalized PageRank over that graph, which is what carries relevance from a matched node to its neighbors instead of stopping at the top-k nearest chunks. The README describes the online path as cost and latency efficient, with the heavier resource use pushed into offline indexing, and it contrasts that with GraphRAG, RAPTOR and LightRAG, which it says consume significantly more resources during offline indexing. That trade-off is the core design decision: you pay once at index time to get a graph, and you get multi-hop reach at query time without an extra LLM call per hop. The README does not document how graph size scales with corpus size, so the indexing cost for a large corpus is something you have to measure yourself.

Installing HippoRAG and running a first query

The README asks for Python 3.10 and suggests Conda or uv. The published package is installed with pip, and the same README recommends a project-local .venv for development.

conda create -n hipporag python=3.10
conda activate hipporag
pip install hipporag

Before running anything with OpenAI models, export the key. The README notes that only the environment variables required by the models you use need to be set, and lists CUDA_VISIBLE_DEVICES and HF_HOME alongside it.

export OPENAI_API_KEY=<your openai api key>

The minimal workflow from the README constructs a HippoRAG object with a save directory, an LLM name and an embedding model name, indexes a list of documents, then calls rag_qa with a list of queries.

from hipporag import HippoRAG

docs = ["George Rankin is a politician."]
queries = ["What is George Rankin's occupation?"]
with HippoRAG(save_dir="outputs", llm_model_name="gpt-4o-mini", embedding_model_name="text-embedding-3-small") as hipporag:
    hipporag.index(docs=docs)
    results = hipporag.rag_qa(queries=queries)

The complete runnable version is examples/demo_openai.py, and the examples directory also holds demo_azure.py, demo_bedrock.py, demo_bedrock_mantle.py, demo_local.py and demo_orcarouter.py, so the provider you use likely has a matching script. If you want a local environment instead of the published package, the README gives the uv route: uv venv --python 3.10 .venv, then uv pip install -e ., with extras such as uv pip install -e '.[vllm]' added only when needed.

The index_manifest.json boundary and what breaks on upgrade

The most consequential limitation is not retrieval quality, it is migration. Version 2.0.0a5 binds persisted vectors and OpenIE state to the endpoint, deployment, model, normalization and component identity that produced them. Indexes without an index_manifest.json, or whose identity no longer matches the active configuration, are rejected instead of being mixed. The README is explicit that you must re-index into a fresh save_dir, and that copying or fabricating only the manifest is not a safe migration. In practice this means an upgrade is a full re-index, with the offline cost that implies, and there is no documented rollback path for an index that fails the identity check. The second constraint is the same mechanism seen from the other side: if you inject a custom embedding model, extraction LLM or text preprocessor, you are told to set index_identity to a stable version string. If you leave it unstable, a configuration change invalidates your index. A third boundary is provider behaviour. OpenAI-compatible chat and embedding endpoints must return standard usage data, and the README states HippoRAG fails closed rather than caching a response whose token cost cannot be accounted for. That is a sensible default, but it means a proxy that strips usage fields will break indexing rather than degrade quietly.

HippoRAG 2 versus GraphRAG and LightRAG

Both HippoRAG 2 and GraphRAG build a graph over a corpus, so the comparison is not graph versus no graph. The README's stated difference is resource use during offline indexing: HippoRAG 2 is described as using significantly fewer resources than GraphRAG, RAPTOR and LightRAG, while remaining cost and latency efficient in online processes. The retrieval step is where the approaches diverge most clearly. HippoRAG 2 runs Personalized PageRank over the graph, a cheap traversal that reuses the graph structure rather than asking a model to reason over it at query time. Graph-style pipelines that summarize communities or generate intermediate answers spend model calls per query, which is where their online cost comes from. LightRAG sits in the same graph-based family and appears in the same README sentence about offline resource use, so if your concern is index-time spend, the project positions itself as the lighter option among the three. What the README does not provide is a head-to-head cost table, and the evaluation figures it cites are its own experiments across NaturalQuestions, PopQA, NarrativeQA, MuSiQue, 2Wiki, HotpotQA and LV-Eval, not an independent comparison. Treat the resource claim as the project's position, and measure your own corpus.

Models, endpoints and the OpenAI SDK constraint

HippoRAG supports openai>=3.3.1,<4. The README's wording is that compatible 3.x client updates are accepted while a new major version requires an explicit compatibility review. That is a real pin, and it will collide with any other package in your environment that requires openai 4.x. The repository ships constraints/openai-tested.txt so you can reproduce the minimum supported SDK baseline without changing the library's declared dependency range, and it provides tests.test_openai_sdk_compat to check the newest allowed release in a clean environment. For self-hosted models, you pass llm_base_url and embedding_base_url pointing at OpenAI-compatible servers, with embedding_provider set to openai; the README notes that for loopback endpoints that do not require authentication, HippoRAG supplies a client-local placeholder without changing the process-wide OPENAI_API_KEY. Bedrock is covered twice: standard Bedrock Runtime models go through the LiteLLM route with the model ID prefixed by bedrock/, while OpenAI models such as GPT-5.5 use Amazon Bedrock Mantle and its Responses API, with the endpoint and model availability described as region-specific. The Mantle path requires an explicit endpoint and raises an error if the Bedrock API key is missing, and an existing AWS profile can be used instead by constructing a BaseConfig with bedrock_mantle_auth='aws_credentials'.

Licence and the cost of staying current

HippoRAG is MIT licensed, which permits commercial use and modification provided the copyright notice and permission notice are retained. The dependencies are the part worth reading closely, because they carry their own terms and their own upgrade pressure: torch 2.5.1, transformers 4.45.2, litellm 1.73.1, networkx 3.4.2, python_igraph 0.11.8, pydantic 2.10.4 and tiktoken 0.7.0 are all pinned to exact versions in pyproject.toml and requirements.txt. Exact pins make installs reproducible and make conflicts visible early, but they also mean a security fix in one of those libraries requires a coordinated bump rather than a range update. The optional extras are the same story: vllm is pinned to 0.6.6.post1 and gritlm to 1.0.2, so local-model users inherit those constraints. The upgrade cost is dominated by re-indexing rather than by the package itself. Because index identity is bound to the producing configuration, changing an embedding model or an extraction LLM means rebuilding the graph and the vectors, and the README's answer is a fresh save_dir. Nothing in the README describes an incremental re-index or a partial migration, so plan index rebuilds as full rebuilds. This is a description of the project's terms, not legal advice; check the licences of the models and stores you plug in.

Editorial conclusion

Adopt HippoRAG 2 if your retrieval quality is limited by questions that require joining facts spread across several documents, and you can afford an offline indexing pass plus a graph store. Do not adopt it if a single vector index already answers your queries, or if you need to keep and upgrade an index built before version 2.0.0a5: the README states that indexes without an index_manifest.json, or whose identity no longer matches the active configuration, are rejected rather than mixed silently. Verify first that your embedding model, extraction LLM and text preprocessor can be pinned to a stable index_identity string, because that value is what prevents configuration changes from reusing incompatible state.

Frequently asked questions

Official sources

1. License: MIT
2. OSU-NLP-Group/HippoRAG on GitHub
3. Project website
4. README
5. Releases