# qhjqhj00/memorag architecture

> Architecture diagram of the GitHub repository qhjqhj00/memorag, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-01-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/qhjqhj00/memorag
- Repository: https://github.com/qhjqhj00/memorag

## Overview

##### Main Components Identification

a) Memory Model
- Handles global context understanding
- Processes up to 1M tokens
- Provides memory-based knowledge discovery
- Includes caching mechanism for optimization

b) Retrieval System
- Integrates with memory model for enhanced retrieval
- Uses embedding models (e.g., BGE-M3)
- Manages document chunking and indexing
- Implements FAISS for efficient similarity search

c) Generation Model
- Supports multiple LLM options (local models or APIs)
- Integrates with memory and retrieval components
- Handles final response generation

##### Key Relationships and Data Flow

a) Primary Pipeline Flow:
**Input Context → Memory Model → Retrieval System → Generation Model → Final Output**

b) Memory Processing Flow:
**Raw Input → Chunking → Indexing → KV Cache Storage → Memory Model**

##### Architectural Patterns
Key architectural features:

- Cache Management System
- KV cache storage
- Chunked passages storage
- FAISS index storage

- Model Integration Layer
- How different models can be plugged in
- API integration points

##### Technical Implementation Details
Important technical elements:

- File Storage System
- Cache directory structure
- Model weights storage
- Index storage

- Model Configuration
- Memory model settings
- Retrieval model configuration
- Generator model options

**┌─ Input Layer ─────────────────────────┐**
- Context Documents / User Queries       │
- ┬─────────────────────┘
- ↓
**┌─ Memory Layer ──────────────────────────────────┐**
- Global Memory Model                           │
- Context Processing                            │
- Caching System                                │
- ┬──────────────────────────────┘
- ↓
**┌─ Retrieval Layer ────────────────────────────┐**
- Document Chunking                          │
- Embedding Generation                       │
- FAISS Index                               │
- ┬────────────────────────────┘
- ↓
**┌─ Generation Layer ───────────────────────────┐**
- LLM Integration                           │
- API Support                               │
- Response Generation                       │
- ┬────────────────────────────┘
- ↓
**┌─ Output Layer ──────────────────────────┐**
- Generated Responses                     │
- ┘

##### Additional Elements
- Version information and supported model types
- Configuration options and parameters
- Performance optimization points

##### Implementation Notes
- Input/output formats at each stage
- Cache hit/miss paths

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph Legend
        L1[Component]
        L2[(Storage)]
        L3([Process])
        L4{Decision}
        style L1 fill:#a8d1f0
        style L2 fill:#d1d1d1
        style L3 fill:#90EE90
        style L4 fill:#FFB6C1
    end

    subgraph Input
        IC[Input Context]
        Q[Query]
    end

    subgraph "Memory Layer"
        MM["Memory Model"]:::memory
        click MM "https://github.com/qhjqhj00/MemoRAG/blob/main/memorag/memorag.py"
        ML["Lite Mode"]:::memory
        click ML "https://github.com/qhjqhj00/MemoRAG/blob/main/memorag/memorag_lite.py"
        CP([Context Processing])
        CG([Clue Generation])
    end

    subgraph "Retrieval Layer"
        RS["Retrieval System"]:::retrieval
        click RS "https://github.com/qhjqhj00/MemoRAG/blob/main/memorag/retrieval.py"
        DC([Document Chunking])
        ER([Enhanced Retrieval])
    end

    subgraph "Generation Layer"
        GN["Generation Model"]:::generation
        click GN "https://github.com/qhjqhj00/MemoRAG/blob/main/memorag/agent.py"
        PM["Prompt Manager"]:::generation
        click PM "https://github.com/qhjqhj00/MemoRAG/blob/main/memorag/prompt.py"
    end

    subgraph "Storage Layer"
        KV[(KV Cache)]:::storage
        FI[(Faiss Index)]:::storage
        PC[(Passage Cache)]:::storage
    end

    subgraph "Evaluation"
        EV["Evaluation System"]:::eval
        click EV "https://github.com/qhjqhj00/MemoRAG/blob/main/examples/longbench/eval.py"
        EU["Evaluation Utils"]:::eval
        click EU "https://github.com/qhjqhj00/MemoRAG/blob/main/examples/longbench/utils.py"
    end

    IC --> DC
    DC --> CP
    CP --> MM
    MM --> KV
    MM --> FI
    MM --> PC

    Q --> CG
    CG --> MM
    MM --> RS
    RS --> ER
    ER --> GN
    PM --> GN
    GN --> FR[Final Response]

    KV -.-> RS
    FI -.-> RS
    PC -.-> RS

    classDef memory fill:#a8d1f0
    classDef retrieval fill:#90EE90
    classDef generation fill:#FFB6C1
    classDef storage fill:#d1d1d1
    classDef eval fill:#FFE4B5

    click ME "https://github.com/qhjqhj00/MemoRAG/blob/main/examples/longllm_as_memory.ipynb"
    click LE "https://github.com/qhjqhj00/MemoRAG/blob/main/examples/memorag_lite.ipynb"
```
