memvid

The Problem

AI agents that rely on Retrieval‑Augmented Generation usually need a full‑stack RAG pipeline: vector DB, storage, indexing, and orchestration. Deploying, scaling, and securing that stack adds latency and operational burden, especially for edge or serverless workloads that need a lightweight, persistent memory.

What This Does

memvid replaces the external pipeline with a single‑file, append‑only memory layer. All embeddings, metadata, and a compact search index live inside a “Smart Frame” container (src/memvid/frame.rs). The core library (src/lib.rs) exposes a Rust API that agents can call to ask, store, and search without any external services.

Key modules:

• src/memvid/ask.rs, src/memvid/doctor.rs, src/memvid/lifecycle.rs – implement the public agent‑facing commands and lifecycle management.
• src/memvid/mutation.rs – handles immutable writes, commit, and discard logic.
• src/memvid/search/*.rs – thin wrappers around the embedded Tantivy index for fast vector and keyword search.
• src/clip.rs – loads the optional CLIP model for on‑the‑fly embedding generation (used by examples such as examples/openai_embedding.rs).

The repository ships a Docker build (docker/core/Dockerfile) for containerised use and a Makefile that invokes cargo build --release.

How It Is Wired

Execution starts at examples/basic_usage.rs (fn main). The binary builds the library (src/lib.rs) and calls the high‑level run_serial_test helper, which eventually invokes the execute function in src/graph_search.rs:203. execute walks a 110‑function sub‑graph and reaches the core memory ops:

1. ask → is_empty (18 calls) – validates that a query frame exists.
2. store_table_impl → insert (18 calls) – writes new frames via src/memvid/mutation.rs.
3. register_builtin_schemas → register / builtin (18 calls) – sets up the Tantivy schema used by src/memvid/search/tantivy.rs.

The most‑used internal primitives are is_empty (228 call sites), Err (135), and file‑system helpers like open_read_only (43). The filesystem boundary is crossed in three short paths:

• execute → drop → commit → commit_with_options → with_staging_lock → EmbeddedWal::open (writes to the memory file).
• main → create → OpenOptions::new().read(true).write(true) (opens or creates the .memvid file).
• run (src/memvid/doctor.rs) → try_open → OpenOptions::new().read(true).write(true) (used by the doctor utility for consistency checks).

Responsibility mapping (top‑ranked files by call traffic):

No circular import cycles were detected; the internal call graph is a shallow DAG, making isolated changes relatively safe. The three oversized files (ask.rs, doctor.rs, lifecycle.rs) each exceed 1 300 lines, so refactoring them into smaller, responsibility‑focused modules would reduce blast radius.

How To Use It

# Clone the repo
git clone https://github.com/moses-y/memvid
cd memvid

# Build the library (release mode)
make build          # runs `cargo build --release`

# Run the reference example
cargo run --example basic_usage

The Makefile defines a build target that calls Cargo; no additional environment variables are required. For containerised deployment:

docker build -f docker/core/Dockerfile -t memvid:latest .
docker run --rm -v $(pwd)/data:/data memvid:latest \
    /app/examples/basic_usage

The library can also be consumed as a crate (memvid-core) in other Rust projects by adding memvid-core = "0.1" to Cargo.toml.

Real‑World Use

A chatbot running on a serverless function can keep a per‑user memory file in /tmp. On each request it:

let mem = Memvid::open("/tmp/user123.memvid")?;
let answer = mem.ask("What did we discuss about project X?")?;

The call resolves to ask → is_empty → search → is_empty, performs a fast vector lookup inside the file, and returns the most recent relevant frame—all without external network I/O.

Code Health & Issues

• High – Pin third‑party GitHub Actions to a commit SHA (.github/workflows/*).
• Medium – Declare least‑privilege GITHUB_TOKEN permissions (.github/workflows/ci.yml).
• Medium – Enable Dependabot (.github/dependabot.yml).
• Medium – Pin Docker base images by digest (docker/cli/Dockerfile).
• Medium – Add a dependency‑vulnerability scan step in CI.
• Medium – Move the 4.9 MiB dictionary file (data/frequency_bigramdictionary_en_243_342.txt) to Git LFS or external storage.
• Medium – Set persist-credentials: false on the checkout action.
• Low – Define timeout-minutes on CI jobs.

No critical findings were reported. Tests (tests/) and CI are present, and the repository includes a license and lockfile.

The Bottom Line

memvid delivers a self‑contained, high‑performance memory store that eliminates external vector‑DB dependencies. The codebase is functional but suffers from deep nesting, duplicated blocks, and a few very large source files, which increase maintenance cost. Teams comfortable with Rust and needing an embedded, serverless memory layer will find it ready to adopt; others should allocate effort for refactoring and tightening CI security before production use.