HippoRAG 2: a knowledge-graph memory layer for LLM retrieval
[NeurIPS'24] HippoRAG is a novel RAG framework inspired by human long-term memory that enables LLMs to continuously integrate knowledge across external documents. RAG + Knowledge Graphs + Personalized PageRank.
At a glance
- What is it?
- HippoRAG 2 from OSU-NLP-Group builds a persisted graph over your documents and retrieves with Personalized PageRank instead of embedding similarity alone. It is an MIT-licensed Python package, and its main cost is offline indexing plus a strict index identity system that rejects stale state.
- Who is it for?
- Adopt HippoRAG 2 if your queries require joining facts that live in separate documents and you can afford an offline OpenIE pass over the corpus. Do not adopt it for single-document lookup, for latency-critical paths where the graph build dominates, or if you cannot re-index from source when the embedding or extraction model changes, because indexes without a matching index_manifest.json are rejected rather than migrated.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 12 days ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The retrieval gap HippoRAG 2 targets
Standard RAG retrieves passages by embedding similarity. That works when the answer sits in one chunk, and it degrades when the answer requires joining facts that never co-occur in a single passage. The README frames this as associativity (multi-hop retrieval) and sense-making (integrating large and complex contexts), and the project positions itself as a memory framework for LLMs rather than a retrieval pipeline. The intended user is someone building question answering over a document collection where questions span entities: the README's own minimal example indexes the sentence "George Rankin is a politician." and asks "What is George Rankin's occupation?", which is a single-hop illustration of a pattern the papers extend to MuSiQue, 2Wiki, HotpotQA and LV-Eval. If your queries are answered by one paragraph, the graph machinery buys you nothing. The project is explicit that it aims to improve associativity and sense-making "without sacrificing their performance on simpler tasks", which is a claim about the evaluation suite, not a guarantee about your corpus.
OpenIE graph, persisted vectors, and Personalized PageRank at query time
The mechanism visible in the repository is a three-part pipeline. Offline, HippoRAG runs OpenIE over the documents to extract entities and relations, builds a knowledge graph from them, and persists vectors alongside the OpenIE state. At query time it retrieves over that graph using Personalized PageRank, which spreads activation from query-relevant nodes across connected entities rather than scoring each chunk independently. The README describes the online process as cost and latency efficient, with the heavier resource use pushed into offline indexing, and claims significantly fewer resources for offline indexing than other graph-based solutions such as GraphRAG, RAPTOR and LightRAG. That split is the design bet: pay once at index time, keep per-query work bounded. The paper links are arXiv 2405.14831 (NeurIPS '24, HippoRAG 1) and arXiv 2502.14802 (ICML '25, HippoRAG 2), so the methodology figure and the evaluation claims live there rather than in the README. Note that the current main branch is HippoRAG 2 while the v1.0.0 release corresponds to HippoRAG 1, which is kept on a separate legacy branch.
Installing and running the minimal index and query loop
The README gives a Conda path and a uv path. With Conda: conda create -n hipporag python=3.10, conda activate hipporag, pip install hipporag. For a project-local environment: uv venv --python 3.10 .venv, source .venv/bin/activate, uv pip install -e . Optional local-model support is installed only when needed, for example uv pip install -e '.[vllm]' or uv pip install -e '.[gritlm]'. Environment variables are scoped to the models you actually use: CUDA_VISIBLE_DEVICES, HF_HOME, and OPENAI_API_KEY. The minimal OpenAI workflow constructs HippoRAG with save_dir, llm_model_name and embedding_model_name, calls hipporag.index(docs=docs), then hipporag.rag_qa(queries=queries). For a self-hosted OpenAI-compatible server you additionally pass llm_base_url, embedding_provider and embedding_base_url, as in the README's localhost:8000 and localhost:8001 example. Bedrock has two routes: standard Bedrock Runtime models go through LiteLLM with the model ID prefixed bedrock/, as in examples/demo_bedrock.py, while OpenAI models on Bedrock Mantle use llm_model_name='bedrock-mantle/openai.gpt-5.5' with an explicit llm_base_url and AWS_BEARER_TOKEN_BEDROCK set. Mantle endpoint and model availability are region-specific, and HippoRAG raises an error if the Bedrock API key is missing.
Index identity is a hard gate, not a migration path
The most consequential operational detail is in the upgrading section. Version 2.0.0a5 binds persisted vectors and OpenIE state to the endpoint, deployment, model, normalization and component identity that produced them. An index without an index_manifest.json, or one whose identity no longer matches the active configuration, is rejected rather than mixed silently. The README states plainly that re-indexing into a fresh save_dir is the path, and that copying or fabricating only the manifest is not a safe migration. If you inject a custom embedding model, extraction LLM or text preprocessor, you are expected to set index_identity to a stable version string so configuration changes cannot reuse incompatible state. This is a deliberate fail-closed design and it is the right call for correctness, but it changes the cost model: swapping an embedding model is not a config edit, it is a full rebuild of the graph and vectors. Teams that expect to hot-swap models behind a stable store will find this restrictive. The same fail-closed instinct appears in the OpenAI-compatible endpoint handling, where HippoRAG refuses to cache a response whose token cost cannot be accounted for; endpoints must return standard usage data.
Where the SDK compatibility surface costs you time
HippoRAG supports openai>=3.3.1,<4. Compatible 3.x client updates are accepted, but a new major version requires an explicit compatibility review. The README suggests reproducing the minimum supported SDK baseline with uv pip install -r requirements.txt -c constraints/openai-tested.txt, and checking SDK compatibility in separate clean environments against both that baseline and the newest allowed release via uv pip install -r requirements.txt --upgrade-package openai followed by PYTHONPATH=src python -m unittest tests.test_openai_sdk_compat. That is a real maintenance tax: two environments, a constraint file, and a named test module to keep green. It is also unusually honest documentation for a research-derived package, and it tells you the maintainers treat the OpenAI client boundary as a compatibility risk rather than an implementation detail. If your stack pins an older openai 2.x client, this package is not for you without a client upgrade.
How it differs from chunk-level graph RAG systems
The README contrasts HippoRAG 2 with GraphRAG, RAPTOR and LightRAG on offline indexing resources, which is the axis where the project claims an advantage. The structural difference is where the graph is anchored. HippoRAG extracts entities and relations with OpenIE and retrieves by Personalized PageRank over that entity graph, so retrieval is a spreading-activation step over linked entities. Chunk-hierarchy approaches such as RAPTOR build a tree of summaries and retrieve by descending it, which keeps the unit of retrieval close to text and avoids a separate extraction pass. GraphRAG-style pipelines build community summaries over an entity graph, which produces corpus-level thematic answers but makes per-query cost and index rebuild cost heavier. If your questions are thematic ("what are the main themes in this corpus"), a community-summary approach maps more directly onto the question shape than entity-level PageRank. If your questions are entity-linking questions across documents, HippoRAG's retrieval unit is closer to the question. The README does not give a head-to-head cost table, so treat the resource comparison as a claim to reproduce on your own corpus rather than a settled number.
Licence, maintenance and what to check before committing
The repository is MIT licensed, which permits commercial use and modification with the usual attribution and warranty disclaimer; that is a summary of the identifier, not legal advice, and you should read the LICENSE file for the binding text. Maintenance signals in the supplied material: the last push is dated 2026-09-03, the repository is not archived, and the only listed release is v1.0.0 from 2025-02-27, which corresponds to HippoRAG 1. HippoRAG 2 is the main branch and is described in the README as version 2.0.0a5, an alpha, so you are tracking a moving branch rather than a tagged stable release. Plan for that: pin a commit, and expect the index identity rules to force re-indexing on upgrade. Before adopting, verify three things on your own data. First, that your embedding and extraction endpoints return standard usage data, because HippoRAG fails closed otherwise. Second, that a full re-index of your corpus fits your budget, since index_identity changes invalidate the store. Third, that your questions actually need multi-hop association; run the same queries against plain embedding retrieval and compare, because the graph only pays off when the answer spans documents.
Editorial conclusion
Adopt HippoRAG 2 if your queries require joining facts that live in separate documents and you can afford an offline OpenIE pass over the corpus. Do not adopt it for single-document lookup, for latency-critical paths where the graph build dominates, or if you cannot re-index from source when the embedding or extraction model changes, because indexes without a matching index_manifest.json are rejected rather than migrated. Verify first that your OpenAI-compatible chat and embedding endpoints return standard usage data, since HippoRAG fails closed rather than caching a response whose token cost cannot be accounted for.
Community notes