### Install MemoRAG via Pip

Source: https://github.com/qhjqhj00/memorag/blob/main/README.md

Installs the MemoRAG library directly from the Python Package Index (PyPI). This is the simplest way to get started with the stable release.

```bash
pip install memorag
```

--------------------------------

### Install MemoRAG from Source

Source: https://github.com/qhjqhj00/memorag/blob/main/README.md

Installs MemoRAG by cloning the repository and installing it in editable mode. This is useful for development or using the latest unreleased features.

```shell
# clone this repo first
cd MemoRAG
pip install -e .
```

--------------------------------

### Install MemoRAG Dependencies

Source: https://github.com/qhjqhj00/memorag/blob/main/README.md

Installs the necessary Python and GPU-accelerated libraries for MemoRAG. Requires PyTorch and FAISS GPU. Ensure your CUDA environment is compatible.

```bash
pip install torch==2.3.1
conda install -c pytorch -c nvidia faiss-gpu=1.8.0
```

--------------------------------

### MemoRAG Lite Mode Example

Source: https://github.com/qhjqhj00/memorag/blob/main/README.md

Demonstrates how to use MemoRAG's Lite mode for memory-augmented RAG processing with millions of tokens using minimal code. This example is found in a specific notebook within the repository.

```Python
from memorag import MemoRAG

# Initialize MemoRAG with a Lite mode configuration
# This setup allows processing millions of tokens efficiently
memorag_lite = MemoRAG(mode="lite", ...)

# Load your large dataset or documents
data = "..."

# Process the data and perform RAG operations
response = memorag_lite.process(data, query="...")
print(response)
```

--------------------------------

### Load Memory with MemoRAG

Source: https://github.com/qhjqhj00/memorag/blob/main/examples/example.ipynb

Loads memory from a specified directory using the MemoRAG pipeline, printing statistics. Includes timing for the loading operation.

```python
start = time.time()
test_txt = open("harry_potter.txt").read()
pipe.load("cache/harry_potter_qwen/", print_stats=True)
print(f"Loading from cache takes {round(time.time()-start,2)} for the full book.")

```

--------------------------------

### Initialize MemoRAG Pipeline

Source: https://github.com/qhjqhj00/memorag/blob/main/examples/example.ipynb

Initializes the MemoRAG pipeline with specified memory and retriever model names/paths, cache directory, and Hugging Face access token. The cache directory and access token are optional.

```python
from memorag import MemoRAG

pipe = MemoRAG(
    mem_model_name_or_path="TommyChien/memorag-qwen2-7b-inst",
    ret_model_name_or_path="BAAI/bge-m3",
    cache_dir="path_to_model_cache",  # to specify local model cache directory (optional)
    access_token="hugging_face_access_token"  # to specify local model cache directory (optional)
)

```

--------------------------------

### Initialize MemoRAG Pipeline

Source: https://github.com/qhjqhj00/memorag/blob/main/examples/example.ipynb

Initializes the MemoRAG pipeline with specified models for memory, retrieval, and generation. It allows configuration of cache directories and Hugging Face access tokens for model authentication.

```python
from memorag import MemoRAG

pipe = MemoRAG(
    mem_model_name_or_path="TommyChien/memorag-mistral-7b-inst",
    ret_model_name_or_path="BAAI/bge-m3",
    gen_model_name_or_path="mistralai/Mistral-7B-Instruct-v0.2",
    cache_dir="path_to_model_cache",  # to specify local model cache directory (optional)
    access_token="hugging_face_access_token"  # to specify local model cache directory (optional)
)
```

--------------------------------

### Memorize and Save with MemoRAG

Source: https://github.com/qhjqhj00/memorag/blob/main/examples/example.ipynb

Memorizes text content using the MemoRAG pipeline and saves it to a specified directory, printing statistics. Includes timing for the prefilling operation.

```python
import time
start = time.time()
test_txt = open("harry_potter.txt").read()
pipe.memorize(test_txt, save_dir="cache/harry_potter_qwen/", print_stats=True)
print(f"Prefilling takes {round(time.time()-start,2)} second for the full book.")

```

--------------------------------

### Run MemoRAG Evaluation

Source: https://github.com/qhjqhj00/memorag/blob/main/README.md

This script navigates to the examples directory and executes the evaluation script for MemoRAG using the longbench benchmark. It is used to assess the performance of the MemoRAG system.

```bash
cd examples
bash longbench/eval.sh
```

--------------------------------

### Answer Query with Memory

Source: https://github.com/qhjqhj00/memorag/blob/main/examples/example.ipynb

Uses the memorized data to answer a given query. The response from the memory model is printed.

```python
query = "How are the mutual relationships between the main characters? "

res = memo_model.answer(query)
print("Using memory to answer the query:\n", res)

```

--------------------------------

### Query Memorized Chinese Content

Source: https://github.com/qhjqhj00/memorag/blob/main/examples/memorag_lite.ipynb

Shows how to query the MemoRAGLite system using a Chinese question. This example verifies the retrieval and response generation for non-English queries.

```python
query = "故事的结局是什么？"
print(pipe(query))
```

--------------------------------

### MemoRAG Quick Start on Google Colab

Source: https://github.com/qhjqhj00/memorag/blob/main/README.md

Provides instructions and context for running the complete MemoRAG pipeline on Google Colab. It highlights the ability to process significant amounts of text (e.g., ~68K tokens) on limited hardware like a single T4 GPU.

```APIDOC
MemoRAG Quick Start Guide:

Objective: Run the full MemoRAG pipeline (Memory Model + Retriever + Generation Model) on Google Colab.

Environment: Single T4 GPU with 15GiB memory.

Capabilities: Process ~68K tokens (half of the example book) and perform all MemoRAG functions.

Steps:
1. Open the provided Google Colab notebook: https://colab.research.google.com/drive/1fPMXKyi4AwWSBkC7Xr5vBdpPpx9gDeFX?usp=sharing
2. Follow the instructions within the notebook to install dependencies, load models, and process data.
3. Interact with MemoRAG by providing queries to retrieve information from the large dataset.

Example Interaction (Conceptual):
# Load data from a file or URL
document_text = "..."

# Initialize MemoRAG (details abstracted in Colab notebook)
# memorag_instance = MemoRAG(...)

# Perform a query
query = "What is the main advantage of MemoRAG over standard RAG?"
# result = memorag_instance.query(query)
# print(result)

Notes:
- The Colab environment provides free access to GPU resources.
- The example demonstrates MemoRAG's capability to handle substantial context sizes even on modest hardware.
```

--------------------------------

### Reset and Load Memory

Source: https://github.com/qhjqhj00/memorag/blob/main/examples/example.ipynb

Resets the current memory state (deleting existing memory) and then loads memory from a specified binary file path. Includes timing to measure the loading duration.

```python
memo_model.reset()  # delete memory
start = time.time()
memo_model.load("cache/harry_potter_qwen/memory.bin")
print(f"Loading from cache takes {round(time.time()-start,2)} for the full book.")

```

--------------------------------

### Rewrite Query

Source: https://github.com/qhjqhj00/memorag/blob/main/examples/example.ipynb

Rewrites the input query into more specific surrogate queries using the memory model. The rewritten queries are formatted as a numbered list.

```python
res = memo_model.rewrite(query)
res = [f"{i+1}: {line}" for i,line in enumerate(res.split("\n")[:-1]) if line]
res = "\n".join(res)
print("Using memory to rewrite the input query into more specifc surrogate queries:\n", res)

```

--------------------------------

### MemoRAG Lite Mode Usage

Source: https://github.com/qhjqhj00/memorag/blob/main/README.md

Demonstrates the simplified 'Lite Mode' of MemoRAG for quick setup and experimentation. It allows memorizing context and performing queries with minimal code. Supports English or Chinese contexts, with potential performance degradation for other languages.

```python
from memorag import MemoRAGLite

pipe = MemoRAGLite()
context = open("examples/harry_potter.txt").read()
pipe.memorize(context, save_dir="harry_potter", print_stats=True)

query = "What's the book's main theme?"
print(pipe(query))
```

--------------------------------

### Memorize Chinese Context with MemoRAGLite

Source: https://github.com/qhjqhj00/memorag/blob/main/examples/memorag_lite.ipynb

Provides an example of memorizing content from a Chinese text file (`fortress_besieged.txt`). This showcases MemoRAGLite's capability to handle non-English content and form memory accordingly.

```python
context = open("fortress_besieged.txt").read()
pipe.memorize(context, save_dir="fortress_besieged", print_stats=True)
```

--------------------------------

### Initialize Memory Model

Source: https://github.com/qhjqhj00/memorag/blob/main/examples/example.ipynb

Initializes the Memory model with a specified model name, cache directory, and beacon ratio. The cache directory is optional for specifying a local model cache location.

```python
from memorag import Memory

memo_model = Memory(
    "TommyChien/memorag-qwen2-7b-inst",
    cache_dir="path_to_model_cache",  # to specify local model cache directory (optional)
    beacon_ratio=4)

```

--------------------------------

### Perform Question Answering (QA)

Source: https://github.com/qhjqhj00/memorag/blob/main/examples/example.ipynb

Executes a question-answering task using the MemoRAG pipeline. It compares the performance of using only memory versus the MemoRAG approach, highlighting how MemoRAG's memory clues improve retriever accuracy.

```python
query = "how many times does the chamber be opened in Harry Potter?"
res = pipe(context=test_txt, query=query, task_type="qa", max_new_tokens=256)
print(f"Using memory to produce the answer: \n{res} \n\n")
res = pipe(context=test_txt, query=query, task_type="memorag", max_new_tokens=256)
print(f"Using MemoRAG to produce the answer: \n{res}")
```

--------------------------------

### Recall Text Clues

Source: https://github.com/qhjqhj00/memorag/blob/main/examples/example.ipynb

Recalls text clues from memory based on a query. The recalled text is processed to format it as a numbered list of relevant lines.

```python
query = "How are the mutual relationships between the main characters? "

res = memo_model.recall(query)
res = [line for line in res.split("\n")[:-1] if line]
res = [f"{i+1}: {line}" for i,line in enumerate(res)]
res = "\n".join(res)
print("Using memory to recall text clues to support the evidence retrieval:\n", res)

```

--------------------------------

### Retrieve Passages with MemoRAG

Source: https://github.com/qhjqhj00/memorag/blob/main/examples/example.ipynb

Retrieves passages based on the recalled clues using the MemoRAG pipeline. The first three retrieved passages are printed, separated by '======'.

```python
retrieved_passages = pipe._retrieve(clues)
print("======\n".join(retrieved_passages[:3]))

```

--------------------------------

### Load MemoRAG Cache

Source: https://github.com/qhjqhj00/memorag/blob/main/examples/example.ipynb

Loads preprocessed data (memory, embeddings, chunks) from a specified cache directory. This significantly speeds up subsequent operations by avoiding reprocessing and re-encoding of the context.

```python
import time
start = time.time()
test_txt = open("harry_potter.txt").read()
pipe.load("cache/harry_potter_mistral/", print_stats=True)
print(f"Loading from cache takes {round(time.time()-start,2)} for the full book.")
```

--------------------------------

### Memorize and Save Memory

Source: https://github.com/qhjqhj00/memorag/blob/main/examples/example.ipynb

Memorizes text content from a file and saves the resulting memory to a specified binary file path. Includes timing to measure the prefilling duration.

```python
import time
start = time.time()
context = open("harry_potter.txt").read()
memo_model.memorize(context)
memo_model.save("cache/harry_potter_qwen/memory.bin")
print(f"Prefilling takes {round(time.time()-start,2)} second for the full book.")

```

--------------------------------

### Summarize Text with MemoRAG

Source: https://github.com/qhjqhj00/memorag/blob/main/examples/example.ipynb

Performs a summarization task on the provided text using the MemoRAG pipeline. This demonstrates the library's capability to condense large amounts of text into concise summaries.

```python
res = pipe(context=test_txt, task_type="summarize", max_new_tokens=512)
print(f"Using MemoRAG to summarize the full book:\n {res}")
```

--------------------------------

### Recall Clues with MemoRAG

Source: https://github.com/qhjqhj00/memorag/blob/main/examples/example.ipynb

Recalls text clues using the MemoRAG pipeline's memory model. The recalled clues are filtered to include only those with more than 3 words and then printed.

```python
query = "How are the mutual relationships between the main characters? "

clues = pipe.mem_model.recall(query).split("\n")
clues = [q for q in clues if len(q.split()) > 3]
print(clues)

```

--------------------------------

### Initialize MemoRAG with Custom API Generator

Source: https://github.com/qhjqhj00/memorag/blob/main/examples/example.ipynb

Initializes MemoRAG with a custom agent that uses external APIs (like Azure OpenAI or DeepSeek) as the generation model. This allows leveraging powerful LLMs via API calls for generation tasks.

```python
from memorag import Agent, MemoRAG
api_dict = {
    "endpoint": "",
    "api_version": "2024-02-15-preview",
    "api_key": ""
}
model = "gpt-35-turbo-16k"
source = "azure"

# Example for DeepSeek models:
# model = ""
# source = "deepseek"
# api_dict = {
#     "base_url": "",
#     "api_key": ""
# }

# Example for OpenAI models:
# model = ""
# source = "openai"
# api_dict = {
#     "api_key": ""
# }


agent = Agent(model, source, api_dict)
print(agent.generate("hi!")) #  test API

pipe = MemoRAG(
    mem_model_name_or_path="TommyChien/memorag-qwen2-7b-inst",
    ret_model_name_or_path="BAAI/bge-m3",
    cache_dir="path_to_model_cache",  # to specify local model cache directory (optional)
    customized_gen_model=agent,
)
pipe.load("cache/harry_potter_qwen/", print_stats=True)
```

--------------------------------

### Perform MemoRAG Task with API Generator

Source: https://github.com/qhjqhj00/memorag/blob/main/examples/example.ipynb

Executes a MemoRAG task (e.g., question answering) using a pipeline configured with a custom API-based generator. This demonstrates how to integrate external LLMs for enhanced response generation.

```python
query = "How are the mutual relationships between the main characters? "
test_txt = open("harry_potter.txt").read()

res = pipe(context=test_txt, query=query, task_type="memorag", max_new_tokens=256)
print(f"Using MemoRAG with GPT-3.5 to produce the answer: \n{res}")
```

--------------------------------

### Python Project Dependencies

Source: https://github.com/qhjqhj00/memorag/blob/main/requirements.txt

This snippet lists the core Python packages required for the project. It includes machine learning libraries like transformers and deepspeed, data handling tools, and natural language processing utilities. Ensure these packages are installed in your Python environment for proper project functionality.

```python
transformers>=4.43.1
deepspeed>=0.14.0
minference==0.1.5
triton==2.3.1
accelerate
datasets
rouge
fuzzywuzzy
jieba
python-Levenshtein
seaborn
tiktoken
openai
semantic_text_splitter
langdetect
```

--------------------------------

### Memorize Text and Save Cache

Source: https://github.com/qhjqhj00/memorag/blob/main/examples/example.ipynb

Memorizes text content from a file, processes it, and saves the results to disk in a specified directory. This includes the memory cache (memory.bin), dense embeddings (index.bin), and text chunks (chunks.json) for faster future operations.

```python
import time
start = time.time()
test_txt = open("harry_potter.txt").read()
pipe.memorize(test_txt, save_dir="cache/harry_potter_mistral/", print_stats=True)
print(f"Prefilling takes {round(time.time()-start,2)} second for the full book.")
```

--------------------------------

### Initialize MemoRAGLite

Source: https://github.com/qhjqhj00/memorag/blob/main/examples/memorag_lite.ipynb

Demonstrates the basic initialization of the MemoRAGLite class. It shows how to create an instance and lists the default arguments available for customization, such as model paths and retrieval settings.

```python
from memorag import MemoRAGLite
pipe = MemoRAGLite()

## All args of MemoRAGLite are:

# gen_model_name_or_path: str="Qwen/Qwen2.5-1.5B-Instruct",
# ret_model_name_or_path: str="BAAI/bge-m3",
# customized_gen_model=None,
# ret_hit: int = 3,
# retrieval_chunk_size: int = 512,
# cache_dir: Optional[str] = None,
# access_token: Optional[str] = None,
# load_in_4bit: bool = False,
# enable_flash_attn: bool = True
```

--------------------------------

### MemoRAG Basic Usage with Model Configuration

Source: https://github.com/qhjqhj00/memorag/blob/main/README.md

Shows how to initialize and use the full MemoRAG pipeline with specific HuggingFace models for memory, retrieval, and generation. It covers context memorization, saving/loading cache, and querying. The context handling capacity depends on the chosen memory model and parameters like `beacon_ratio`.

```python
from memorag import MemoRAG

# Initialize MemoRAG pipeline
pipe = MemoRAG(
    mem_model_name_or_path="TommyChien/memorag-qwen2-7b-inst",
    ret_model_name_or_path="BAAI/bge-m3", 
    gen_model_name_or_path="mistralai/Mistral-7B-Instruct-v0.2", # Optional: if not specify, use memery model as the generator
    cache_dir="path_to_model_cache",  # Optional: specify local model cache directory
    access_token="hugging_face_access_token",  # Optional: Hugging Face access token
    beacon_ratio=4
)

context = open("examples/harry_potter.txt").read()
query = "How many times is the Chamber of Secrets opened in the book?"

# Memorize the context and save to cache
pipe.memorize(context, save_dir="cache/harry_potter/", print_stats=True)

# Generate response using the memorized context
res = pipe(context=context, query=query, task_type="memorag", max_new_tokens=256)
print(f"MemoRAG generated answer: \n{res}")
```

--------------------------------

### Memorize English Context with MemoRAGLite

Source: https://github.com/qhjqhj00/memorag/blob/main/examples/memorag_lite.ipynb

Shows how to read content from an English text file and use the `memorize` method to form memory. It also includes the option to print statistics during the process.

```python
context = open("harry_potter.txt").read()
pipe.memorize(context, save_dir="harry_potter", print_stats=True)
```

--------------------------------

### Query Memorized English Content

Source: https://github.com/qhjqhj00/memorag/blob/main/examples/memorag_lite.ipynb

Demonstrates how to query the MemoRAGLite system with a natural language question after memory has been loaded. The output of the query is printed to the console.

```python
query = "What's the book's main theme?"
print(pipe(query))
```

--------------------------------

### Load Pre-cached Memory in MemoRAGLite

Source: https://github.com/qhjqhj00/memorag/blob/main/examples/memorag_lite.ipynb

Illustrates how to load an existing, pre-cached memory from a specified directory. This allows for quick access to previously processed data without re-memorization.

```python
## You can also load a pre-cached memory from a directory
pipe.load("harry_potter")
```

--------------------------------

### Initialize MemoRAG with Long LLMs

Source: https://github.com/qhjqhj00/memorag/blob/main/README.md

Demonstrates initializing the MemoRAG pipeline with long-context LLMs for use as memory models. It specifies memory and retrieval model names, with optional parameters for cache directory and Hugging Face access tokens.

```python
from memorag import MemoRAG
model = MemoRAG(
    mem_model_name_or_path="shenzhi-wang/Llama3.1-8B-Chinese-Chat",    # For Chinese
    # mem_model_name_or_path="meta-llama/Meta-Llama-3.1-8B-Instruct",  # For English
    ret_model_name_or_path="BAAI/bge-m3",
    # cache_dir="path_to_model_cache",  # to specify local model cache directory (optional)
    # access_token="hugging_face_access_token"  # to specify local model cache directory (optional)
    )
```

--------------------------------

### Mentorship System Discussion and Rules

Source: https://github.com/qhjqhj00/memorag/blob/main/examples/fortress_besieged.txt

Details discussions and decisions made during a meeting about the university's mentorship system. It covers rules regarding student-teacher dining, student conduct, and faculty responsibilities, reflecting administrative procedures and debates.

```APIDOC
Mentorship System Implementation:

Discussion Points:
- Student-teacher dining rules
- Faculty responsibilities and student supervision
- Academic integrity and student conduct

Decisions & Rules:
1.  **Student-Teacher Dining**: 
    - Minimum requirement: Each mentor must dine with students at least twice a week.
    - Scheduling: Dates to be arranged by the disciplinary office.
    - Dining Hall Etiquette:
        - Mentors should not leave the dining hall before students.
        - Students must wait for mentors to be served first.
        - No talking during meals ('silent meals').
    - Exceptions: Saturday dinner and Sunday meals are excluded from the minimum requirement.
    - Seating Arrangement: Discussion on how to assign mentors to tables (e.g., 1 mentor per 6 students, or 2 mentors per 4 students).
    - Financial Considerations: Debates on whether the school should cover additional meal costs due to reduced student numbers per table.

2.  **Student Conduct & Faculty Guidance**: 
    - Handling student misconduct: Disciplinary actions range from warnings to expulsion.
    - Faculty role in guidance: Emphasis on 'mentor's cultivation' and 'ignorance is not a crime' for minor offenses.
    - Faculty meetings: Discussions on curriculum, student welfare, and administrative policies.

3.  **Academic Performance & Evaluation**: 
    - Grading philosophy: 'Giving charcoal in snow' (providing help when needed) is encouraged, while 'adding flowers to brocade' (giving excessive praise) is discouraged.
    - Score value: 'One cent cannot buy anything, let alone one point' - emphasizing the value of scores.
    - Student petitions: Students can petition for changes in instructors based on perceived qualifications.

4.  **Faculty Conduct & University Policy**: 
    - Smoking policy: Attempts to regulate smoking in faculty areas and shared facilities.
    - Faculty dining expenses: Discussions on whether the university covers meal costs for faculty.
    - Faculty solidarity: Encouragement for colleagues to cooperate and support each other.

Related Concepts:
- Departmental politics and rivalries (e.g., Foreign Languages vs. Chinese Literature departments).
- Influence of external factors (e.g., Ministry of Education directives, other universities' practices).
- Personal relationships and their impact on academic decisions.
```

--------------------------------

### Faculty Appointment and Course Assignment

Source: https://github.com/qhjqhj00/memorag/blob/main/examples/fortress_besieged.txt

Describes the process of assigning a temporary replacement for a vacant teaching position, involving faculty recommendations, discussions, and political considerations. It highlights how personal connections and departmental interests influence appointments.

```APIDOC
Course Assignment Process:

Situation: Sun Xiaojie's English class needs a substitute teacher.

Key Personnel & Actions:
1.  **Liu Dongfang (Head of Foreign Languages Dept.)**: 
    - Initially volunteers to teach the class himself due to concerns about Mrs. Han taking over.
    - Acknowledges Zhao Xinmei's superior English skills.
    - Seeks Zhao Xinmei's assistance in finding a replacement.

2.  **Zhao Xinmei**: 
    - Recommended by Liu Dongfang to teach Sun Xiaojie's class.
    - Hesitant to refuse directly due to Sun Xiaojie's connection.
    - Recommends Fang Hongjian as a suitable candidate.
    - Assures Gao Songnian of Fang Hongjian's English proficiency.

3.  **Gao Songnian (University Official)**: 
    - Consults with Zhao Xinmei regarding the replacement.
    - Approves Zhao Xinmei's recommendation of Fang Hongjian.

4.  **Fang Hongjian**: 
    - Accepts the teaching assignment after persuasion regarding its benefits and potential risks.
    - Begins teaching English to a lower-level group.

Related Events:
- Han Xueyu's intervention regarding his wife's potential teaching position.
- Fang Hongjian's subsequent challenges with grading and student feedback.
```

--------------------------------

### MemoRAG with Qwen2 and Mistral Memory Models

Source: https://github.com/qhjqhj00/memorag/blob/main/README.md

Illustrates the integration of Qwen2-7B-Inst and Mistral-7B-Inst as memory models within the MemoRAG framework. This provides flexibility in choosing the underlying LLM for memory operations.

```Python
from memorag import MemoRAG

# Initialize MemoRAG using Qwen2-7B-Inst as the memory model
memorag_qwen2 = MemoRAG(memory_model="TommyChien/memorag-qwen2-7b-inst", ...)

# Initialize MemoRAG using Mistral-7B-Inst as the memory model
# memorag_mistral = MemoRAG(memory_model="TommyChien/memorag-mistral-7b-inst", ...)

# Example usage with a query
response = memorag_qwen2.retrieve("Find information about efficient caching.")
print(response)
```

--------------------------------

### University Meeting Procedures and Oratory Styles

Source: https://github.com/qhjqhj00/memorag/blob/main/examples/fortress_besieged.txt

Describes the atmosphere and proceedings of a university meeting discussing the mentorship system. It highlights the typical patterns of academic discourse, including platitudes, personal anecdotes, and the dynamics of group consensus or dissent.

```APIDOC
University Meeting Dynamics:

Meeting Topic: Discussion on the mentorship system.

Meeting Participants:
- Ministry Inspector (部视学)
- Gao Songnian (Chairman/Official)
- Li Meiting (Disciplinary Officer)
- Department Heads (e.g., Foreign Languages, Mathematics, Economics)
- Professors and Lecturers

Meeting Proceedings:
1.  **Opening Remarks**: Ministry Inspector delivers a speech heavily referencing personal experiences in Britain ('兄弟在英国的时候').
2.  **Academic Discourse**: Gao Songnian reiterates concepts like 'cells and organisms' and 'sacrificing personal convenience for group life'.
3.  **Proposal Presentation**: Li Meiting reads out ministry guidelines and proposed internal regulations.
4.  **Debate and Opposition**: 
    - Common reasons for opposition: Personal disagreements with the proposer, opposition to those who agree, or association with those who oppose.
    - Specific issue: Rule requiring mentors to dine with students.
    - Strong protests from faculty with families.
    - Arguments against the rule: Financial burden, disruption to household routines, dietary restrictions (e.g., stomach ailments).
    - Faculty demand for clarification on mentor allocation and table arrangements.
5.  **Resolution Modification**: Original draft is significantly amended.
6.  **Rituals and Symbolism**: 
    - Discussion on adopting pre/post-meal blessings (like in Oxford/Cambridge).
    - Attempts to find suitable Chinese phrases for blessings.
    - Proposal: Moment of silence before meals to reflect on national hardship and duty.
    - Decision: Adopted as a formal procedure.
7.  **Enforcement of Rules**: 
    - Li Meiting establishes strict rules for dining hall conduct to ensure discipline and respect for mentors.
    - Rules include: Mentors served first, students wait for mentors, no talking during meals.

8.  **Faculty Debate Style**: 
    - Characterized by lengthy speeches, repetition of ideas, and reliance on authority or personal experience.
    - Tendency to agree or disagree based on social dynamics rather than pure logic.
```

--------------------------------

### MemoRAG Load Cached Data

Source: https://github.com/qhjqhj00/memorag/blob/main/README.md

Demonstrates how to load previously memorized context data from disk. This significantly speeds up subsequent operations by avoiding re-encoding, chunking, and indexing, making repeated use of the same context highly efficient.

```python
pipe.load("cache/harry_potter/", print_stats=True)
```

--------------------------------

### Memory-Augmented Retrieval with MemoRAG

Source: https://github.com/qhjqhj00/memorag/blob/main/README.md

Demonstrates using MemoRAG for memory-augmented retrieval, enhancing evidence retrieval with recalled clues. It covers initializing MemoRAG, memorizing text, and saving the context for retrieval operations.

```python
from memorag import MemoRAG

# Initialize MemoRAG pipeline
pipe = MemoRAG(
    mem_model_name_or_path="TommyChien/memorag-qwen2-7b-inst",
    ret_model_name_or_path="BAAI/bge-m3",
    cache_dir="path_to_model_cache",  # Optional: specify local model cache directory
    access_token="hugging_face_access_token"  # Optional: Hugging Face access token
)

# Load and memorize the context
test_txt = open("harry_potter.txt").read()
pipe.memorize(test_txt, save_dir="cache/harry_potter/", print_stats=True)
```

--------------------------------

### MemoRAG with Meta-Llama-3.1 and Llama3.1 Memory Models

Source: https://github.com/qhjqhj00/memorag/blob/main/README.md

Shows how to integrate Meta-Llama-3.1-8B-Instruct and Llama3.1-8B-Chinese-Chat as memory models within the MemoRAG framework. This allows leveraging these specific LLMs for the memory component.

```Python
from memorag import MemoRAG

# Initialize MemoRAG using Meta-Llama-3.1-8B-Instruct as the memory model
memorag_llama = MemoRAG(memory_model="Meta-Llama-3.1-8B-Instruct", ...)

# Or initialize using Llama3.1-8B-Chinese-Chat for Chinese language support
# memorag_llama_chinese = MemoRAG(memory_model="Llama3.1-8B-Chinese-Chat", ...)

# Example usage with a query
response = memorag_llama.query("What are the key features of MemoRAG?")
print(response)
```

--------------------------------

### Perform Summarization Task with MemoRAG

Source: https://github.com/qhjqhj00/memorag/blob/main/README.md

Shows how to use the MemoRAG pipeline to perform a summarization task on provided context. It specifies the task type and maximum new tokens for the generated summary.

```python
res = pipe(context=context, task_type="summarize", max_new_tokens=512)
print(f"MemoRAG summary of the full book:\n {res}")
```

--------------------------------

### Use APIs as Generators with MemoRAG

Source: https://github.com/qhjqhj00/memorag/blob/main/README.md

Illustrates integrating external APIs, such as Azure OpenAI or Deepseek, as custom generators within the MemoRAG pipeline. It covers API configuration, initialization of an Agent, and using the agent for generation or as a customized generator for MemoRAG.

```python
from memorag import Agent, MemoRAG

# API configuration for Azure
api_dict_azure = {
    "endpoint": "",
    "api_version": "2024-02-15-preview",
    "api_key": ""
}
model_azure = "gpt-35-turbo-16k"
source_azure = "azure"

# Initialize Agent with Azure API
agent_azure = Agent(model_azure, source_azure, api_dict_azure)
print(agent_azure.generate("hi!"))  # Test the API

# Initialize MemoRAG pipeline with a customized generator model (Azure)
pipe_azure = MemoRAG(
    mem_model_name_or_path="TommyChien/memorag-qwen2-7b-inst",
    ret_model_name_or_path="BAAI/bge-m3",
    cache_dir="path_to_model_cache",  # Optional: specify local model cache directory
    customized_gen_model=agent_azure,
)

# Load previously cached context
pipe_azure.load("cache/harry_potter_qwen/", print_stats=True)

# Use the loaded context for question answering
query = "How are the mutual relationships between the main characters?"
context = open("harry_potter.txt").read()

res_azure = pipe_azure(context=context, query=query, task_type="memorag", max_new_tokens=256)
print(f"MemoRAG with GPT-3.5 generated answer: \n{res_azure}")

# --- Configuration for Deepseek models ---
# model_deepseek = ""
# source_deepseek = "deepseek"
# api_dict_deepseek = {
#     "base_url": "",
#     "api_key": ""
# }
# agent_deepseek = Agent(model_deepseek, source_deepseek, api_dict_deepseek)

# --- Configuration for OpenAI models ---
# model_openai = ""
# source_openai = "openai"
# api_dict_openai = {
#     "api_key": ""
# }
# agent_openai = Agent(model_openai, source_openai, api_dict_openai)

```

--------------------------------

### Character Descriptions and Quirks

Source: https://github.com/qhjqhj00/memorag/blob/main/examples/fortress_besieged.txt

Provides brief descriptions of key characters, focusing on their physical appearance, habits, or defining traits, as observed within the narrative context.

```APIDOC
Character Profiles:

1.  **Wang Chuhou**: 
    - Physical Trait: Distinctive mustache, described as a single stroke rather than two distinct sides.
    - Historical Context: Grew a mustache twenty years prior, associating it with the status of officials at the time.
    - Inspiration: Modeled his mustache after a provincial governor's 'diamond-shaped' mustache, aiming for a smaller, 'red diamond-pointed' version to avoid perceived presumption.

2.  **Gao Songnian**: 
    - Role: University official, involved in administrative decisions and faculty consultations.
    - Communication Style: Uses platitudes and references to abstract concepts ('cells and organisms').
    - Interaction: Engages in discussions with faculty, makes decisions on appointments, and approves proposals.

3.  **Li Meiting**: 
    - Role: Disciplinary Officer (训导长).
    - Personality: Meticulous, tries to enforce rules strictly, seeks to set a good example.
    - Actions: Intervenes in student discipline, proposes new rules, attempts to regulate faculty behavior (e.g., smoking).
    - Communication Style: Relies on ministry directives, can be flustered when faced with strong opposition.

4.  **Liu Dongfang**: 
    - Role: Head of the Foreign Languages Department.
    - Personality: Concerned with departmental reputation, acknowledges academic merit in others (e.g., Zhao Xinmei), can be politically astute.
    - Actions: Involved in faculty appointments, defends his staff, navigates departmental politics.

5.  **Zhao Xinmei**: 
    - Role: Faculty member, known for English proficiency.
    - Personality: Observant, influential, prefers indirect action.
    - Actions: Offers private support, makes recommendations, engages in discussions about faculty appointments.

6.  **Fang Hongjian**: 
    - Role: Instructor teaching English.
    - Situation: Faces challenges with student performance, grading, and a student petition against him.
    - Personality: Initially insecure about his position, later gains confidence, can be sensitive to criticism.
    - Interactions: Receives advice from Liu Dongfang and Zhao Xinmei, becomes a target of political maneuvering.
```

--------------------------------

### Use Memory Model Independently

Source: https://github.com/qhjqhj00/memorag/blob/main/README.md

Shows how to use the `Memory` class from MemoRAG independently for storing, recalling, and interacting with context. It covers initialization, memorizing text, saving, querying for answers, recalling clues, and rewriting queries.

```python
from memorag import Memory

# Initialize the Memory model
memo_model = Memory(
    "TommyChien/memorag-qwen2-7b-inst",
    cache_dir="path_to_model_cache",  # Optional: specify local model cache directory
    beacon_ratio=4  # Adjust beacon ratio for handling longer contexts
)

# Load and memorize the context
context = open("harry_potter.txt").read()
memo_model.memorize(context)

# Save the memorized context to disk
memo_model.save("cache/harry_potter/memory.bin")

# Query the model for answers
query = "How are the mutual relationships between the main characters?"

res_answer = memo_model.answer(query)
print("Using memory to answer the query:\n", res_answer)

# Recall text clues for evidence retrieval
res_recall = memo_model.recall(query)
print("Using memory to recall text clues to support evidence retrieval:\n", res_recall)

# Rewrite the query into more specific surrogate queries
res_rewrite = memo_model.rewrite(query)
print("Using memory to rewrite the input query into more specific surrogate queries:\n", res_rewrite)
```

--------------------------------

### Student Petition Against Instructor

Source: https://github.com/qhjqhj00/memorag/blob/main/examples/fortress_besieged.txt

Details a formal petition submitted by students against their English instructor, Fang Hongjian. The petition lists specific criticisms regarding his qualifications and grading practices, leading to an administrative review.

```APIDOC
Student Petition:

Subject: Petition for replacement of instructor due to academic inadequacy.

Petitioner: Students of English Group D.

Instructor in question: Fang Hongjian.

Allegations:
- Lack of qualification to teach English.
- Errors in grading and marking (e.g., penmanship errors, oversight).
- Inconsistent grading standards (e.g., grading good papers strictly, bad papers leniently).

Evidence cited:
- List of specific grading mistakes and oversights.
- Examples of students using foreign names that reflect poor understanding or cultural appropriation (e.g., 'Florrie', 'Bacon', 'Byron', 'Chamberlain', 'Zeppelin').

Administrative Action:
- Petition submitted to the Principal's office.
- Principal forwards the petition to Liu Dongfang for review and response.
- Liu Dongfang intends to defend Fang Hongjian and refute the claims.

Suspected Instigators:
- The three students who were auditing Fang Hongjian's class.
- Han Xueyu is suspected of orchestrating the petition.
```

--------------------------------

### Python Memory Recall and Passage Retrieval

Source: https://github.com/qhjqhj00/memorag/blob/main/README.md

Demonstrates querying a memory model for character relationship clues. Filters clues and retrieves relevant passages using a `pipe` object. Includes `mem_model.recall` and `_retrieve` methods.

```python
# Define the query
query = "How are the mutual relationships between the main characters?"

# Recall clues from memory
clues = pipe.mem_model.recall(query).split("\n")
clues = [q for q in clues if len(q.split()) > 3]  # Filter out short or irrelevant clues
print("Clues generated from memory:\n", clues)

# Retrieve relevant passages based on the recalled clues
retrieved_passages = pipe._retrieve(clues)
print("======\n".join(retrieved_passages[:3]))
```

--------------------------------

### Handling of Student Misconduct

Source: https://github.com/qhjqhj00/memorag/blob/main/examples/fortress_besieged.txt

Details the process and debate surrounding the disciplinary action for a Chinese literature student accused of disrespect. It involves differing opinions from department heads and the intervention of a disciplinary officer.

```APIDOC
Student Disciplinary Action:

Case: A Chinese literature student accused of disrespect.

Stakeholders & Positions:
- Liu Dongfang (Head of Foreign Languages Dept.): Advocates for expulsion.
- Wang Chuhou (Head of Chinese Literature Dept.): Opposes expulsion.
- Zhao Xinmei: Supports Liu Dongfang's stance privately, offers indirect assistance.
- Li Meiting (Disciplinary Officer): Proposes a lenient approach.

Resolution:
- Li Meiting intervenes, citing the student's lack of proper guidance ('mentor's cultivation') and ignorance.
- Action taken: Student receives a formal demerit ('记过一次').
- Follow-up: Li Meiting provides private 'close guidance' to the student, fostering gratitude.

Underlying Factors:
- Departmental politics and personal relationships influencing decisions.
```

--------------------------------

### Initialize MemoRAG

Source: https://github.com/qhjqhj00/memorag/blob/main/examples/longllm_as_memory.ipynb

Instantiates the MemoRAG model with specified language models for memory and retrieval. It supports custom cache directories and Hugging Face access tokens for model loading.

```python
from memorag import MemoRAG
model = MemoRAG(
    mem_model_name_or_path="shenzhi-wang/Llama3.1-8B-Chinese-Chat", 
    ret_model_name_or_path="BAAI/bge-m3",
    cache_dir="path_to_model_cache",  # to specify local model cache directory (optional)
    access_token="hugging_face_access_token"  # to specify local model cache directory (optional)
    )
```

```python
from memorag import MemoRAG
model = MemoRAG(
    mem_model_name_or_path="meta-llama/Meta-Llama-3.1-8B-Instruct", 
    ret_model_name_or_path="BAAI/bge-m3",
    cache_dir="path_to_model_cache",  # to specify local model cache directory (optional)
    access_token="hugging_face_access_token"  # to specify local model cache directory (optional)
    )
```

--------------------------------

### Academic Gossip and Rumor Mill

Source: https://github.com/qhjqhj00/memorag/blob/main/examples/fortress_besieged.txt

Illustrates how rumors and gossip spread within the university, influencing perceptions and creating conflict. It shows how information, often distorted, is passed between faculty and students, impacting reputations and relationships.

```APIDOC
Rumor Dissemination and Impact:

Scenario 1: Fang Hongjian's teaching performance.
- Rumor: Fang Hongjian is criticized by Liu Dongfang in front of students.
- Source: Allegedly spread by a colleague with a grievance against Liu Dongfang.
- Impact: Fang Hongjian becomes aware of potential trouble and seeks to clarify with Liu Dongfang.

Scenario 2: Han Xueyu's alleged actions.
- Rumor: Han Xueyu is trying to undermine Fang Hongjian, possibly to secure a position for his wife.
- Evidence: Han Xueyu's wife's potential teaching role, Han Xueyu's attempts to influence appointments.
- Impact: Fang Hongjian suspects Han Xueyu of orchestrating the student petition against him.

Scenario 3: Student dining and faculty behavior.
- Observation: Students overhear conversations in the restroom about food poisoning at the Han residence.
- Interpretation: Fang Hongjian suspects this is related to Han Xueyu's machinations against him.

General Observation:
- Gossip often involves misinterpretations, personal biases, and departmental rivalries.
- Information is frequently 'passed on' rather than verified.
- The university environment is portrayed as one where reputations can be easily damaged by unsubstantiated claims.
```

--------------------------------

### Load and Memorize Context

Source: https://github.com/qhjqhj00/memorag/blob/main/examples/longllm_as_memory.ipynb

Reads text content from a file and memorizes it using the MemoRAG model. The context can be truncated if it exceeds the LLM's context length. The `print_stats` argument shows memory usage details.

```python
context = open("fortress_besieged.txt").read()
print(f"The book 'Fortress Besieged' (围城) has {len(context)} characters.")
## The LLM supports 128K context length, so we truncate the book to around 128K
## Here the context KV caches are not compressed, so the cache file is big
model.memorize(context[:100000], "besieged_cache", print_stats=True)
```

```python
context = open("harry_potter.txt").read()
model.memorize(context, "harry_potter", print_stats=True)
```

--------------------------------

### Query with MemoRAG (QA Mode)

Source: https://github.com/qhjqhj00/memorag/blob/main/examples/longllm_as_memory.ipynb

Performs a question-answering task using the provided context and a query. The model generates an answer based on the context, with a specified maximum number of new tokens.

```python
query = "主人公是个什么样的人？"
res = model(context, query, "qa", max_new_tokens=512)
print("Using Memory to generate the answer:\n", res)
```

```python
query = "How are the mutual relationships of the main roles?"
res = model(context, query, "qa", max_new_tokens=512)
print("Using Memory to generate the answer:\n", res)
```