# olow304/memvid architecture

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

- Interactive diagram: https://gitdiagram.com/olow304/memvid
- Repository: https://github.com/olow304/memvid

## Overview

##### Project type and purpose
- Memvid is an open-source Python library and CLI tool for “Video-as-Database” AI memory.
- Its purpose: encode large text corpora (chunks, PDFs, docs) into a compressed MP4 video plus a JSON index, then provide lightning-fast semantic search and chat over that video “database.”

##### File structure
- Top-level package: `memvid/` (core modules: `encoder.py`, `retriever.py`, `chat.py`, `interactive.py`, `llm_client.py`, etc.).
- Supporting directories:
- `docker/` – Dockerfile, scripts, resource monitor for containerized encoding.
- `examples/` – sample scripts demonstrating API use cases (file chat, memory building, codec comparison).
- `tests/` – unit tests for core modules.
- Config and orchestration:
- `setup.py`, `requirements.txt` – package metadata and dependencies.
- `Makefile`, `pytest.ini` – build/test automation.
- Resource/workflow scripts:
- `docker_manager.py` – programmatic Docker orchestration.
- `resource_monitor.py`, `ffmpeg_executor.py` – video encoding helpers.

##### README for additional insights
- Core workflow:
a. Ingest text (chunks, PDFs) → b. Compute embeddings → c. Encode embeddings into video frames → d. Output `memory.mp4` + `memory_index.json`.
- Retrieval: load video+index → semantic search via FAISS-like index → chat interfaces (CLI or web UI).
- Pluggable components: embedding models, LLM providers (OpenAI, Anthropic, local), video codecs (H.264, H.265), distributed processing flags.
- Docker support for heavy workloads and troubleshooting notes.

##### Essential details to capture
- Ingest stage (text & PDF → chunking).
- Embedding & indexing flow.
- Video encoding step (include Docker/ffmpeg).
- Outputs (video + index).
- Retrieval & search path (Retriever → Chat → LLM).
- Extensibility hooks for new embedding or codec.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Ingestion Stage
    subgraph "Input Ingestion"
        PDFParser["PDF Parser"]:::external
        Chunker["Chunker"]:::core
    end

    %% Embedding & Indexing Stage
    subgraph "Embedding & Indexing"
        Embedding["Embedding Model"]:::core
        IndexBuilder["Index Builder"]:::core
    end

    %% Video Encoding Stage
    subgraph "Video Encoder"
        FrameGenerator["Frame Generator"]:::core
        FFmpegExec["FFmpeg Executor"]:::external
        DockerManager["Docker Manager"]:::util
        ResourceMonitor["Resource Monitor"]:::util
    end

    %% Storage Artifacts
    subgraph "Storage"
        MP4["memory.mp4"]:::storage
        JSONIndex["memory_index.json"]:::storage
    end

    %% Retrieval & Chat Stage
    subgraph "Retrieval & Chat"
        Retriever["Retriever"]:::core
        ChatAPI["Chat API"]:::core
        InteractiveUI["Interactive UI"]:::core
        LLMClient["LLM Client"]:::core
        ExternalLLM["External LLM API"]:::external
    end

    %% Examples & Tests
    subgraph "Developer Resources"
        Examples["Examples"]:::util
        Tests["Tests"]:::util
    end

    %% Config & Utilities
    subgraph "Configuration & Utilities"
        Config["Global Config"]:::util
        Utils["Utility Functions"]:::util
    end

    %% Build & CI
    subgraph "Build & CI"
        Setup["setup.py"]:::util
        Requirements["requirements.txt"]:::util
        RequirementsComp["docker/requirements-compute.txt"]:::util
        MakefileNode["Makefile"]:::util
        Pytest["pytest.ini"]:::util
    end

    %% Docker Support Files
    subgraph "Docker Support"
        Dockerfile["Dockerfile"]:::util
        StartDocker["start_docker_container.sh"]:::util
        Troubleshoot["WSL_TROUBLESHOOTING.md"]:::util
    end

    %% Data Flow
    PDFParser -->|ingest| Chunker
    Chunker -->|chunks| Embedding
    Embedding -->|embeddings| IndexBuilder
    IndexBuilder -->|index| FrameGenerator
    FrameGenerator -->|frames| FFmpegExec
    DockerManager --> FFmpegExec
    DockerManager --> ResourceMonitor
    FFmpegExec -->|video| MP4
    FrameGenerator -->|metadata| JSONIndex

    MP4 --> Retriever
    JSONIndex --> Retriever
    Retriever -->|results| ChatAPI
    ChatAPI --> InteractiveUI
    InteractiveUI --> LLMClient
    LLMClient --> ExternalLLM

    Examples -.-> Chunker
    Tests -.-> Chunker
    Config --> Chunker
    Utils --> Chunker

    %% Click Events
    click Chunker "https://github.com/olow304/memvid/blob/main/memvid/encoder.py"
    click Embedding "https://github.com/olow304/memvid/blob/main/memvid/index.py"
    click IndexBuilder "https://github.com/olow304/memvid/blob/main/memvid/index.py"
    click DockerManager "https://github.com/olow304/memvid/blob/main/memvid/docker_manager.py"
    click FFmpegExec "https://github.com/olow304/memvid/blob/main/docker/scripts/ffmpeg_executor.py"
    click ResourceMonitor "https://github.com/olow304/memvid/blob/main/docker/resource_monitor.py"
    click Retriever "https://github.com/olow304/memvid/blob/main/memvid/retriever.py"
    click ChatAPI "https://github.com/olow304/memvid/blob/main/memvid/chat.py"
    click InteractiveUI "https://github.com/olow304/memvid/blob/main/memvid/interactive.py"
    click LLMClient "https://github.com/olow304/memvid/blob/main/memvid/llm_client.py"
    click Config "https://github.com/olow304/memvid/blob/main/memvid/config.py"
    click Utils "https://github.com/olow304/memvid/blob/main/memvid/utils.py"
    click Examples "https://github.com/olow304/memvid/tree/main/examples/"
    click Tests "https://github.com/olow304/memvid/tree/main/tests/"
    click Dockerfile "https://github.com/olow304/memvid/tree/main/docker/Dockerfile"
    click StartDocker "https://github.com/olow304/memvid/blob/main/docker/start_docker_container.sh"
    click Troubleshoot "https://github.com/olow304/memvid/blob/main/docker/WSL_TROUBLESHOOTING.md"
    click Setup "https://github.com/olow304/memvid/blob/main/setup.py"
    click Requirements "https://github.com/olow304/memvid/blob/main/requirements.txt"
    click RequirementsComp "https://github.com/olow304/memvid/blob/main/docker/requirements-compute.txt"
    click MakefileNode "https://github.com/olow304/memvid/tree/main/Makefile"
    click Pytest "https://github.com/olow304/memvid/blob/main/pytest.ini"

    %% Styles
    classDef core fill:#D0E8FF,stroke:#0366d6,stroke-width:1px
    classDef storage fill:#E6FFEC,stroke:#28a745,stroke-width:1px
    classDef external fill:#FFF4E5,stroke:#d15704,stroke-width:1px
    classDef util fill:#F2F2F2,stroke:#6a737d,stroke-width:1px
```
