ReMem - REMem

Overview

The ReMem class is the primary interface for the ReMem framework. It orchestrates knowledge graph construction, embedding storage, information extraction, and retrieval-augmented question answering.

Constructor

ReMem(
    global_config: Optional[BaseConfig] = None,
    working_dir: Optional[str] = None,
    llm: Optional[BaseLLM] = None,
    extract_llm: Optional[BaseLLM] = None,
    qa_llm: Optional[BaseLLM] = None
)

global_config

BaseConfig

default:"None"

Global configuration settings for the instance. If not provided, creates a new BaseConfig with default values.

working_dir

str

default:"None"

Directory where work-specific files will be stored. If not provided, constructs a default directory: {save_dir}/ReMem_{timestamp}

llm

BaseLLM

default:"None"

Language model for general processing. If not provided, initializes based on global_config.llm_infer_mode and global_config.llm_name.

extract_llm

BaseLLM

default:"None"

Language model specifically for information extraction. Defaults to the main llm if not provided.

qa_llm

BaseLLM

default:"None"

Language model specifically for question answering. Defaults to the main llm if not provided.

Example

from remem.remem import ReMem
from remem.utils.config_utils import BaseConfig

# Initialize with default configuration
remem = ReMem()

# Initialize with custom configuration
config = BaseConfig(
    llm_name="gpt-4o-mini",
    embedding_model_name="nvidia/NV-Embed-v2",
    retrieval_top_k=10
)
remem = ReMem(global_config=config)

Core Methods

index

Indexes documents by extracting information and building the knowledge graph.

index(docs: List[str]) -> None

docs

List[str]

required

List of document strings to be indexed.

The indexing process:

Chunks documents using the text preprocessor
Performs information extraction (OpenIE, episodic, or temporal)
Constructs the knowledge graph with entities, facts, and passages
Stores embeddings for retrieval

Example

docs = [
    "Paris is the capital of France. It is known for the Eiffel Tower.",
    "London is the capital of the United Kingdom."
]

remem.index(docs)

retrieve

Performs retrieval using the ReMem framework with fact-based and graph-enhanced search.

retrieve(
    queries: List[str],
    num_to_retrieve: Optional[int] = None
) -> List[QuerySolution]

queries

List[str]

required

List of query strings for which documents are to be retrieved.

num_to_retrieve

int

default:"None"

Maximum number of documents to retrieve for each query. Defaults to global_config.retrieval_top_k if not specified.

return

List[QuerySolution]

List of QuerySolution objects, each containing:

question: The original query
docs: Retrieved document texts
doc_scores: Relevance scores for each document
graph_seeds: Top-k facts used for graph search
doc_metadata: Metadata for retrieved documents

Long queries with no relevant facts after reranking will fall back to dense passage retrieval (DPR) results.

Example

queries = [
    "What is the capital of France?",
    "Where is the Eiffel Tower located?"
]

results = remem.retrieve(queries, num_to_retrieve=5)

for result in results:
    print(f"Query: {result.question}")
    print(f"Top document: {result.docs[0]}")
    print(f"Score: {result.doc_scores[0]}")

rag_for_qa

Performs retrieval-augmented generation for question answering.

rag_for_qa(
    queries: Union[List[str], List[QuerySolution]],
    gold_docs: Optional[List[List[str]]] = None,
    gold_answers: Optional[List[List[str]]] = None,
    metrics: Tuple[str, ...] = ("qa_em", "qa_f1", "retrieval_recall"),
    question_metadata: Optional[List[Dict]] = None,
    to_save: bool = True,
    **kwargs
) -> Tuple[List[QuerySolution], List[str], List[Dict], Dict, Dict]

queries

Union[List[str], List[QuerySolution]]

required

List of query strings or pre-processed QuerySolution objects. If strings, retrieval will be performed automatically.

gold_docs

List[List[str]]

default:"None"

List of lists containing gold-standard documents for each query. Required for retrieval evaluation.

gold_answers

List[List[str]]

default:"None"

List of lists containing gold-standard answers for each query. Required for QA evaluation.

metrics

Tuple[str, ...]

default:"(\"qa_em\", \"qa_f1\", \"retrieval_recall\")"

Evaluation metrics to compute. Available options:

Retrieval: "retrieval_recall", "retrieval_recall_all", "retrieval_ndcg_any", "retrieval_recall_locomo"
QA: "qa_em", "qa_f1", "qa_bleu1", "qa_bleu4", "qa_longmemeval", "qa_mem0_llm_judge", "qa_evalsuit_llm_judge"

question_metadata

List[Dict]

default:"None"

Optional metadata for each question (e.g., question type, ID).

to_save

bool

default:"True"

Whether to save results to disk.

return

Tuple

Returns a tuple containing:

List[QuerySolution]: Query solutions with answers
List[str]: Raw LLM response messages
List[Dict]: Metadata dictionaries
Dict: Overall retrieval evaluation results (if enabled)
Dict: Overall QA evaluation results (if enabled)

Example

queries = ["What is the capital of France?"]
gold_answers = [["Paris"]]

query_solutions, responses, metadata, retrieval_eval, qa_eval = remem.rag_for_qa(
    queries=queries,
    gold_answers=gold_answers,
    metrics=("qa_em", "qa_f1")
)

print(f"Answer: {query_solutions[0].answer}")
print(f"QA Exact Match: {qa_eval['qa_em']}")
print(f"QA F1 Score: {qa_eval['qa_f1']}")

qa

Executes question-answering inference using retrieved documents.

qa(queries: List[QuerySolution]) -> Tuple[List[QuerySolution], List[str], List[Dict]]

queries

List[QuerySolution]

required

List of QuerySolution objects containing queries and retrieved documents.

return

Tuple

Returns a tuple containing:

List[QuerySolution]: Updated QuerySolution objects with predicted answers
List[str]: Raw response messages from the LLM
List[Dict]: Metadata dictionaries

Example

# First retrieve documents
retrieval_results = remem.retrieve(["What is the capital of France?"])

# Then perform QA
qa_results, responses, metadata = remem.qa(retrieval_results)

print(f"Answer: {qa_results[0].answer}")
print(f"Rationale: {qa_results[0].qa_rationale}")

Graph Methods

initialize_graph

Initializes a graph from a saved file or creates a new one.

initialize_graph() -> ig.Graph

return

ig.Graph

A loaded or newly initialized igraph Graph object.

Example

graph = remem.initialize_graph()
print(f"Graph has {graph.vcount()} nodes and {graph.ecount()} edges")

save_igraph

Saves the current graph to disk.

save_igraph() -> None

Example

remem.save_igraph()

get_graph_info

Returns information about the current graph structure.

get_graph_info() -> Dict

return

Dict

Dictionary containing graph statistics and metadata.

Example

info = remem.get_graph_info()
print(info)

Embedding & Storage Methods

prepare_retrieval_objects

Prepares in-memory objects for fast retrieval operations.

prepare_retrieval_objects() -> None

This method is automatically called before the first retrieval if not manually invoked. It loads:

All embedding vectors into memory
Graph node mappings and indices
Passage, entity, and fact keys

Example

# Manually prepare for retrieval
remem.prepare_retrieval_objects()
print(f"Ready to retrieve: {remem.ready_to_retrieve}")

dense_passage_retrieval

Performs dense passage retrieval using embedding similarity.

dense_passage_retrieval(
    query: str,
    candidate_docs: List[str] = None,
    norm: bool = True
) -> Tuple[np.ndarray, np.ndarray]

query

str

required

The input query string.

candidate_docs

List[str]

default:"None"

Optional candidate documents to search. If None, uses indexed documents.

norm

bool

default:"True"

Whether to normalize similarity scores.

return

Tuple[np.ndarray, np.ndarray]

Returns a tuple containing:

Sorted document indices (by relevance)
Corresponding normalized similarity scores

Example

query = "What is the capital of France?"
doc_ids, scores = remem.dense_passage_retrieval(query)

print(f"Top document index: {doc_ids[0]}")
print(f"Top document score: {scores[0]}")

Properties

embedding_model

Access the embedding model instance.

@property
embedding_model -> BaseEmbeddingModel

Example

embed_model = remem.embedding_model
print(f"Embedding model: {embed_model.embedding_model_name}")

chunk_embedding_store

Access the embedding store for document chunks.

@property
chunk_embedding_store -> EmbeddingStore

Example

store = remem.chunk_embedding_store
print(f"Total chunks: {len(store.embeddings)}")

phrase_embedding_store

Access the embedding store for entities/phrases.

@property
phrase_embedding_store -> EmbeddingStore

triple_embedding_store

Access the embedding store for facts/triples.

@property
triple_embedding_store -> EmbeddingStore

Evaluation Methods

evaluate_qa

Evaluates question answering results against gold answers.

evaluate_qa(
    gold_answers: List[List[str]],
    qa_evaluators: List,
    query_solutions: List[QuerySolution],
    question_metadata: Optional[List[Dict]] = None
) -> Dict

gold_answers

List[List[str]]

required

Gold-standard answers for evaluation.

qa_evaluators

List

required

List of QA evaluator instances.

query_solutions

List[QuerySolution]

required

Query solutions with predicted answers.

question_metadata

List[Dict]

default:"None"

Optional metadata (type, ID) for each question.

return

Dict

Dictionary with overall QA evaluation metrics.

evaluate_retrieval

Evaluates retrieval results against gold documents.

evaluate_retrieval(
    gold_docs: List[List[str]],
    query_solutions: List[QuerySolution],
    retrieval_evaluators: List
) -> Dict

gold_docs

List[List[str]]

required

Gold-standard documents for evaluation.

query_solutions

List[QuerySolution]

required

Query solutions with retrieved documents.

retrieval_evaluators

List

required

List of retrieval evaluator instances.

return

Dict

Dictionary with retrieval metrics (recall at various k values).

Advanced Methods

run_ppr

Runs Personalized PageRank on the knowledge graph.

run_ppr(
    reset_prob: np.ndarray,
    damping: float = 0.5
) -> Tuple[np.ndarray, np.ndarray]

reset_prob

np.ndarray

required

Reset probability distribution for each node in the graph.

damping

float

default:"0.5"

Damping factor for PageRank computation.

return

Tuple[np.ndarray, np.ndarray]

Returns:

Sorted document node IDs by PageRank score
Corresponding PageRank scores

query_to_triple_scores

Computes similarity scores between a query and all indexed facts.

query_to_triple_scores(query: str) -> np.ndarray

query

str

required

The input query text.

return

np.ndarray

Normalized array of similarity scores between query and facts.

Example

scores = remem.query_to_triple_scores("What is the capital of France?")
top_fact_idx = scores.argmax()
print(f"Top fact score: {scores[top_fact_idx]}")

Complete Example

from remem.remem import ReMem
from remem.utils.config_utils import BaseConfig

# Configure ReMem
config = BaseConfig(
    llm_name="gpt-4o-mini",
    embedding_model_name="nvidia/NV-Embed-v2",
    retrieval_top_k=10,
    qa_top_k=5
)

# Initialize
remem = ReMem(global_config=config)

# Index documents
docs = [
    "Paris is the capital of France. The Eiffel Tower is located in Paris.",
    "London is the capital of the United Kingdom.",
    "Berlin is the capital of Germany."
]
remem.index(docs)

# Retrieve and answer questions
queries = ["What is the capital of France?"]
gold_answers = [["Paris"]]

results, responses, metadata, retrieval_metrics, qa_metrics = remem.rag_for_qa(
    queries=queries,
    gold_answers=gold_answers,
    metrics=("qa_em", "qa_f1", "retrieval_recall")
)

print(f"Answer: {results[0].answer}")
print(f"Retrieved docs: {len(results[0].docs)}")
print(f"QA F1 Score: {qa_metrics['qa_f1']}")
print(f"Retrieval Recall@5: {retrieval_metrics.get('retrieval_recall@5', 'N/A')}")

Core API

Information Extraction

RAG Strategies

Embeddings

LLM Backends

Evaluation

​Overview

​Constructor

​Example

​Core Methods

​index

​Example

​retrieve

​Example

​rag_for_qa

​Example

​qa

​Example

​Graph Methods

​initialize_graph

​Example

​save_igraph

​Example

​get_graph_info

​Example

​Embedding & Storage Methods

​prepare_retrieval_objects

​Example

​dense_passage_retrieval

​Example

​Properties

​embedding_model

​Example

​chunk_embedding_store

​Example

​phrase_embedding_store

​triple_embedding_store

​Evaluation Methods

​evaluate_qa

​evaluate_retrieval

​Advanced Methods

​run_ppr

​query_to_triple_scores

​Example

​Complete Example

Build docs developers (and LLMs) love

Overview

Constructor

Example

Core Methods

index

Example

retrieve

Example

rag_for_qa

Example

qa

Example

Graph Methods

initialize_graph

Example

save_igraph

Example

get_graph_info

Example

Embedding & Storage Methods

prepare_retrieval_objects

Example

dense_passage_retrieval

Example

Properties

embedding_model

Example

chunk_embedding_store

Example

phrase_embedding_store

triple_embedding_store

Evaluation Methods

evaluate_qa

evaluate_retrieval

Advanced Methods

run_ppr

query_to_triple_scores

Example

Complete Example