How xmudeeplit/memgraphrag works
1. Repository purpose
- MemGraphRAG is an offline/CLI-driven GraphRAG system that builds a persistent “memory” from a text corpus and then uses that memory to answer questions with graph-aware retrieval.
2. Top-level execution paths
- code/index.py is the indexing entrypoint: it ingests a corpus, extracts structured knowledge, builds memory artifacts, and writes graph/embedding stores.
- code/retrieval_dataset_test.py is the evaluation/QA entrypoint: it loads the saved artifacts, retrieves evidence for questions, generates answers, and records metrics and traces.
3. Primary pipeline boundary
- The architecture is split into two phases:
- Indexing/construction: corpus → extracted facts/schemas → persistent memory and graph.
- Retrieval/QA: question → candidate evidence from memory/graph → reranking and reasoning → answer + evaluation output.
- The saved save-dir is the boundary between these phases.
4. Three-layer memory model
- code/src/Memory.py and code/src/MemGraphRAG.py organize the core representation into three linked layers:
- Passage layer: original text chunks.
- Fact layer: extracted relation triples.
- Schema layer: abstract ontology triples generalized from facts.
- The design keeps bidirectional links among these layers so retrieval can move between raw text, concrete facts, and abstract patterns.
5. Knowledge extraction subsystem
- code/src/information_extraction/ contains OpenIE implementations for:
- Online extraction through an OpenAI-compatible LLM.
- Offline extraction through local vLLM-based generation.
- This subsystem turns corpus passages into structured triples and associated evidence, using prompts from code/src/prompts/.
6. Prompt and schema management
- code/src/prompts/ contains task-specific templates for triple extraction, linking, NER, query formulation, and retrieval QA.
- prompt_template_manager.py centralizes template selection, which matters because the same pipeline can be run with different model backends and prompt styles.
7. Graph construction and conflict handling
- code/src/MemGraphRAG.py is the orchestrator for building the memory graph from extracted information.
- The README indicates the pipeline performs ontology induction, low-frequency schema filtering, and conflict-aware resolution of hard contradictory evidence before final graph creation.
- The resulting graph is persisted as JSON/GraphML artifacts under the output directory.
8. Embedding and vector storage
- code/src/embedding_model/ abstracts multiple embedding backends such as BGE, Contriever, GritLM, and NVEmbedV2.
- code/src/embedding_store.py persists embeddings for chunks, entities, and facts so retrieval can reuse them without recomputation.
- Embedding model identity is part of the saved artifact path, so indexing and retrieval must use compatible model settings.
9. Retrieval engine
- code/src/rerank.py and retrieval logic inside the main pipeline combine embedding similarity with graph-based expansion.
- The README describes a graph-enhanced retrieval strategy using similarity scoring plus Personalized PageRank, with optional fact reranking and threshold filtering.
- This means retrieval is not purely vector search; it is a hybrid of dense retrieval and graph traversal over the constructed memory graph.
10. LLM and backend abstraction
- code/src/llm/ provides a backend interface for:
- OpenAI-compatible APIs
- local vLLM-based models
- These backends are used both for extraction and for answer generation, so the repository treats the LLM as a replaceable service boundary.
11. Evaluation and experiment harness
- code/src/evaluation/ includes retrieval and QA evaluators, with separate modules for scoring retrieval quality and answer quality.
- code/src/evaluation/README.md suggests this layer is meant to standardize benchmarking rather than drive core indexing behavior.
- retrieval_dataset_test.py produces structured outputs containing answers, retrieved documents, metadata, latency, and token usage for batch experiments.
12. Data and artifact layout
- dataset/ contains example corpora and QA sets for HotpotQA, Musique, 2WikiMultiHopQA, and a medical dataset.
- Output artifacts typically include:
- OpenIE results
- initial memory with schema
- final memory JSON
- memory graph files
- embedding directories for chunks/entities/facts
- These artifacts are the durable state of the system and are what make reruns and evaluation reproducible.
13. Utilities and runtime support
- code/src/utils/ handles configuration, logging, embedding helpers, evaluation helpers, QA helpers, and general typing/misc support.
- _bootstrap_sys_path.py indicates the CLI scripts are designed to run from the repo root while still importing the local src package cleanly.
14. External dependencies that shape the architecture
- The system assumes an OpenAI-compatible LLM endpoint for online operation and a local Hugging Face embedding model for dense retrieval.
- Optional offline extraction depends on local inference tooling such as vllm or llama-factory.
- These external model services are architectural dependencies, not just implementation details, because they define how extraction, retrieval, and generation are executed.
Main entry points: Memory.py Memory model · retrieval_dataset_test.py Retrieval CLI · rerank.py Reranker · MemGraphRAG.py MemGraphRAG
Components 18
Pipeline
Indexing and retrieval phases separated by the saved memory artifacts.
- Index CLI · Builds memory artifacts from a corpus.
code/index.py - Retrieval CLI · Runs batch QA over saved artifacts and records outputs.
code/retrieval_dataset_test.py - Save dir · Persistent output boundary between indexing and retrieval.
Core memory
Three-layer memory representation and graph orchestration.
- MemGraphRAG · Coordinates graph construction, retrieval, and answer assembly.
code/src/MemGraphRAG.py - Memory model · Passage, fact, and schema layers with links among them.
code/src/Memory.py - Passages · Original corpus chunks used as evidence.
- Facts · Extracted relation triples grounded in passages.
- Schemas · Generalized schema-level knowledge induced from facts.
Model backends
LLM, extraction, and embedding backends.
- Online IE · OpenAI-compatible triple extraction.
code/src/information_extraction/openie_openai.py - Offline IE · Local vLLM-based triple extraction.
code/src/information_extraction/openie_vllm_offline.py - Prompt manager · Selects task prompts for extraction, linking, NER, and QA.
code/src/prompts/prompt_template_manager.py - LLM API · OpenAI-compatible generation backend.
code/src/llm/openai_gpt.py - Local LLM · Local vLLM generation backend.
code/src/llm/vllm_offline.py - Embedding backends · BGE, Contriever, GritLM, and NVEmbedV2 adapters.
code/src/embedding_model - Embedding store · Stores chunk, entity, and fact embeddings for reuse.
code/src/embedding_store.py
Operations
Reranking, evaluation, and shared utilities.
- Reranker · Combines similarity, graph expansion, and filtering.
code/src/rerank.py - Evaluators · Retrieval and QA scoring modules.
code/src/evaluation - Utils · Configuration, logging, embedding, QA, and typing helpers.
code/src/utils
Connections 23
- Index CLI → MemGraphRAG: builds · Indexing entrypoint drives graph construction.
- Retrieval CLI → MemGraphRAG: loads · Retrieval entrypoint loads the saved memory graph.
- Index CLI → Save dir: writes · Produces durable artifacts under the output directory.
- Retrieval CLI → Save dir: reads · Consumes persisted artifacts for QA and evaluation.
- MemGraphRAG → Memory model: organizes · Core orchestration organizes the memory layers.
- Memory model → Passages: contains · Passage layer stores original chunks.
- Memory model → Facts: contains · Fact layer stores extracted triples.
- Memory model → Schemas: contains · Schema layer stores generalized ontology triples.
- Passages → Online IE: extracts · Online extraction turns passages into triples.
- Passages → Offline IE: extracts · Offline extraction turns passages into triples.
- Online IE → Prompt manager: uses · Extraction uses task-specific prompts.
- Offline IE → Prompt manager: uses · Extraction uses task-specific prompts.
- Online IE → LLM API: calls · Online extraction depends on API LLMs.
- Offline IE → Local LLM: calls · Offline extraction depends on local LLMs.
- Facts → Schemas: induces · Facts are generalized into schema knowledge.
- MemGraphRAG → Embedding store: persists · Stores embeddings for later retrieval.
- Embedding store → Embedding backends: computed by · Vectors are produced by selectable embedding models.
- Retrieval CLI → Reranker: queries · QA retrieval uses hybrid reranking and expansion.
- Reranker → Embedding store: scores · Uses dense similarity from persisted embeddings.
- Reranker → Memory model: expands · Traverses graph-linked memory for evidence.
- Reranker → Evaluators: feeds · Retrieval outputs are evaluated in batch runs.
- Retrieval CLI → Utils: supports · Shared helpers support configuration, logging, and QA formatting.
- Index CLI → Utils: supports · Shared helpers support configuration and logging.