The Problem

Retrieval‑augmented generation (RAG) systems struggle with consistency when facts are scattered across many passages. Maintaining coherent, conflict‑aware knowledge without re‑processing the entire corpus for each query is costly and error‑prone, especially for multi‑hop QA where entities must be linked across documents.

What This Does

MemGraphRAG implements a three‑layer memory (schema → fact → passage) that persists across runs.

  • Schema layer – abstract type triples are generated in code/src/Memory.py and stored in the Memory object.
  • Fact layer – concrete relation triples are extracted by the OpenIE modules (code/src/information_extraction/openie_openai.py or openie_vllm_offline.py) and fed into code/src/MemGraphRAG.py.
  • Passage layer – raw text chunks from the dataset/ folder are indexed with embeddings (code/src/embedding_model/*.py) and linked to facts.

The core orchestration lives in code/src/MemGraphRAG.py, which builds the graph, resolves conflicts, and runs retrieval‑augmented generation via the LLM adapters (code/src/llm/openai_gpt.py or vllm_offline.py).

How It Is Wired

Entry point – code/index.py (invoked by code/run_index.sh). It parses CLI arguments, instantiates MemGraphRAG, and calls MemGraphRAG.run().

Control flow

  1. index.py → MemGraphRAG.__init__ (creates a Memory instance, loads config from code/src/utils/config_utils.py).
  2. MemGraphRAG.run() Calls EmbeddingModel (selected in code/src/embedding_model/__init__.py) to embed passages (embed_utils.py). Triggers fact extraction via information_extraction/openie_* modules. Populates Memory with schemas (Memory.add_schema) and facts (Memory.add_fact). Builds the graph (rerank.py for PPR‑based retrieval) and invokes the LLM (llm/openai_gpt.py or llm/vllm_offline.py).
  3. Results are written by utils/qa_utils.py to JSON logs used by the evaluation scripts (code/src/evaluation/*.py).

External touch points

  • File system – reads raw corpora from dataset/; writes retrieval logs under code/.
  • Network – optional OpenAI calls (llm/openai_gpt.py) and HuggingFace model downloads in the embedding modules.
  • Compute – heavy lifting is in embedding_model/* (uses torch/sentence-transformers) and the OpenIE pipelines.

The graph construction (Memory + rerank.py) is the widest‑impact component; errors there affect both retrieval quality and downstream generation.

How To Use It

# 1. Clone the exact repository
git clone https://github.com/moses-y/MemGraphRAG.git
cd MemGraphRAG

# 2. Create a Python 3.10+ environment and install deps
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# 3. (Optional) Install OpenAI key if you plan to use the online LLM
export OPENAI_API_KEY=sk-...

# 4. Index a dataset (example with HotpotQA)
bash code/run_index.sh dataset/hotpotqa/hotpotqa.json

# 5. Run a retrieval‑augmented QA batch
bash code/run_retrieval_test.sh

Configuration – No separate config file is required; code/src/utils/config_utils.py reads environment variables (OPENAI_API_KEY, EMBEDDING_MODEL_NAME) and defaults. Adjust the embedding model name in requirements.txt or by setting EMBEDDING_MODEL_NAME before step 4.

Real‑World Use

A legal‑tech platform can preload public statutes (as passages) with run_index.sh. When a user asks a multi‑step legal question, the system retrieves the supporting passages, resolves contradictory citations via the conflict‑aware graph, and generates a concise answer—all without re‑embedding the corpus.

from code.src.MemGraphRAG import MemGraphRAG
rag = MemGraphRAG(dataset_path="dataset/legal/codes.json")
answer = rag.answer("What are the penalties for breach of contract under Article 5?")
print(answer)

Code Health & Issues

  • Medium – CI missing – No .github/, Jenkinsfile, or other CI configuration; automated testing is not enforced.
  • Low – No lockfile – Dependencies are listed only in requirements.txt; reproducibility depends on PyPI snapshots.
  • Low – Limited test coverage – Only two test files (retrieval_dataset_test.py, retrieval_dataset_test.py duplicates) exist, covering a small portion of the pipeline.
  • Low – Mixed Python versions – Compiled byte‑code (__pycache__) shows artifacts for Python 3.10‑3.13, suggesting the code has been run under multiple interpreters but the README pins only 3.10+.

No obvious security secrets are committed; the license (MIT) is present.

The Bottom Line

MemGraphRAG provides a concrete implementation of a memory‑driven GraphRAG system with clear modular boundaries (embedding, extraction, memory, LLM). It is usable out‑of‑the‑box for research prototypes but lacks production‑grade CI, lockfile reproducibility, and extensive test coverage. Engineers looking to extend GraphRAG with custom schemas or offline LLMs will find the codebase approachable, while teams needing robust CI/CD should add a pipeline and lockfile before deployment.