memvid-rs 0.1.5

High-performance video memory encoding library with semantic search (Rust bindings)

memvid-rs (Python Bindings)

Memvid-rs combines the performance of Rust with the ease of use of Python. It encodes text data into QR codes and then into video frames, with semantic search capabilities powered by FAISS and SentenceTransformers.

This project exposes the core logic written in Rust (MemvidEncoder, MemvidDecoder) as a Python module via PyO3, with a high-level Python wrapper for semantic search.

Attribution: This project is a port reimplemented in Rust based on the ideas and design of Olow304/memvid. We deeply appreciate the innovative approach of the original project.

🚀 Key Features

• High Performance: Leverages Rust's parallel processing and efficient memory management for fast text-to-video conversion.
• Semantic Search: FAISS vector index with SentenceTransformer embeddings for <100ms search across millions of chunks.
• Incremental Append: Add new data to existing archives without rebuilding from scratch. Only new chunks need embedding generation.
• Pythonic: Easy to install via pip and use naturally as a Python object.
• Strong Compression: Significantly reduces storage space via Text -> QR -> Video (H.264/H.265) conversion.

📦 Installation

From PyPI (Recommended)

# Basic installation (Rust encoder/decoder only)
pip install memvid-rs

# Full installation with semantic search
pip install memvid-rs[full]

From Source (Development)

Requires Rust and Python development environments.

# 1. Install Rust & FFmpeg
brew install rust ffmpeg

# 2. Create and activate virtual environment
python3 -m venv .venv
source .venv/bin/activate

# 3. Install Maturin and dependencies
pip install maturin sentence-transformers faiss-cpu

# 4. Build and install
maturin develop --release

💻 Usage

Basic Usage (Rust Encoder Only)

import memvid_rs

# Initialize Encoder
encoder = memvid_rs.MemvidEncoder()

# Add Text (chunk_size=200, overlap=20)
text_data = "Memvid-rs is fast and efficient. " * 100
encoder.add_text(text_data, chunk_size=200, overlap=20)

# Build Video
encoder.build("output.mp4", "index.json")
print("Video created: output.mp4")

Full Usage with Semantic Search

from memvid_rs import MemvidEncoder, MemvidRetriever

# === ENCODING ===
encoder = MemvidEncoder()

# Add text chunks
texts = [
    "Python is a high-level programming language.",
    "Machine learning uses algorithms to learn from data.",
    "Rust is focused on safety and performance.",
]
for text in texts:
    encoder.add_text(text, chunk_size=512)

# Build video + FAISS index
encoder.build_video("memory.mp4", "index")
# Creates: memory.mp4, index.faiss, index.json

# === RETRIEVAL ===
retriever = MemvidRetriever("memory.mp4", "index")

# Semantic search
results = retriever.search("programming language", top_k=3)
for text, score, metadata in results:
    print(f"[{score:.3f}] {text}")

# Search with context
results = retriever.search_with_context(
    "artificial intelligence",
    top_k=2,
    context_before=1,
    context_after=1
)

Incremental Append (New in v2.0)

Add new data to existing archives without rebuilding everything from scratch. Only new chunks need embedding generation, making updates much faster.

from memvid_rs import MemvidEncoder

# === METHOD 1: append_to_archive (Recommended) ===
# Add new content to existing archive
encoder = MemvidEncoder()
encoder.add_text("New content for 2025 sustainability report...")
encoder.add_pdf("new_report_2025.pdf")

# Append to existing archive (only generates embeddings for new chunks)
stats = encoder.append_to_archive("memory.mp4", "index")
print(f"Added {stats['new_chunks']} chunks (total: {stats['total_chunks']})")
# Output: Added 150 chunks (total: 1150)

# === METHOD 2: load_archive + build_video ===
# Load existing archive, modify, and rebuild
encoder = MemvidEncoder.load_archive("memory.mp4", "index")
print(f"Loaded {len(encoder.chunks)} existing chunks")

# Add new content
encoder.add_text("Additional content...")

# Rebuild (video is regenerated, but FAISS index is incrementally updated)
encoder.build_video("memory.mp4", "index")

Use Cases:

• Annual Report Updates: Add new yearly sustainability reports to existing knowledge base
• Continuous Learning: Incrementally grow your memory archive over time
• Efficient Updates: Only new chunks need embedding generation (saves ~90% time)

# Example: Annual ESG report archiving
encoder = MemvidEncoder()

# Year 1: Initial build
encoder.add_pdf("esg_report_2024.pdf")
encoder.build_video("esg_archive.mp4", "esg_index")

# Year 2: Incremental append (much faster!)
encoder = MemvidEncoder()
encoder.add_pdf("esg_report_2025.pdf")
stats = encoder.append_to_archive("esg_archive.mp4", "esg_index")
# Only generates embeddings for 2025 report, reuses 2024 embeddings

🔧 API Reference

memvid_rs.MemvidEncoder

High-level encoder with semantic search support.

from memvid_rs import MemvidEncoder

encoder = MemvidEncoder(
    model_name="intfloat/multilingual-e5-large-instruct",  # Default (MIT, MTEB Rank 2)
    index_type="Flat"               # FAISS index type: "Flat" or "IVF"
)

# Adding content
encoder.add_text(text, chunk_size=512, overlap=50)
encoder.add_chunks(["chunk1", "chunk2"])  # Pre-chunked text
encoder.add_pdf("document.pdf")           # Requires PyPDF2

# Building
encoder.build_video("output.mp4", "index")

# Incremental append (v2.0+)
stats = encoder.append_to_archive("existing.mp4", "existing_index")

# Load existing archive
encoder = MemvidEncoder.load_archive("existing.mp4", "existing_index")

# Statistics
stats = encoder.get_stats()

memvid_rs.MemvidRetriever

Semantic search and retrieval from QR videos.

from memvid_rs import MemvidRetriever

retriever = MemvidRetriever(
    video_path="memory.mp4",
    index_path="index",
    cache_size=100  # Frame cache size
)

# Search methods
results = retriever.search(query, top_k=5)
results = retriever.search_with_context(query, top_k=5, context_before=1, context_after=1)
text = retriever.get_chunk(chunk_id)
all_text = retriever.get_all_text()
stats = retriever.get_stats()

memvid_rs._RustEncoder / memvid_rs.MemvidDecoder (Low-level Rust API)

from memvid_rs import _RustEncoder, MemvidDecoder

# Low-level Rust Encoder (no embeddings)
encoder = _RustEncoder()
encoder.add_text(text, chunk_size, overlap)
encoder.build(video_path, index_path)
chunks = encoder.get_chunks()

# Rust Decoder
decoder = MemvidDecoder(video_path, index_path)
text = decoder.get_chunk_text(chunk_id)
texts = decoder.get_chunks_text([0, 1, 2])
all_chunks = decoder.get_all_chunks()
info = decoder.get_video_info()

⚠️ Requirements

• System: macOS (Tested), Linux, Windows
• Runtime: ffmpeg (Required for video encoding)
  • macOS: brew install ffmpeg
  • Windows: winget install Gyan.FFmpeg (Restart terminal after install) or download from gyan.dev
• Python: >= 3.8
• Optional: sentence-transformers, faiss-cpu for semantic search

📄 License

MIT License