Memvid Portable Agent Memory

What does this agent do, and when should you use it?

Memvid is a Rust-based memory system that packages content, embeddings, search structures, and metadata into one .mv2 file. It stores memory as append-only Smart Frames containing immutable content, timestamps, checksums, and basic metadata, with an embedded WAL for crash recovery. Optional features cover Tantivy BM25 search, HNSW vector search, local ONNX text embeddings, CLIP image retrieval, Whisper transcription, PDF extraction, temporal parsing, and encrypted capsules. Developers can integrate it through a Rust crate, Node.js SDK, Python SDK, or CLI; its core is model-agnostic and can operate fully offline. It is a practical fit for teams seeking a local, portable alternative to server-hosted vector databases and multi-component RAG infrastructure, provided they can manage the feature flags, model files, and compute required by their chosen retrieval modes.

An application creates a .mv2 file with Memvid::create, writes content and metadata such as titles, URIs, and tags through put_bytes_with_options, and persists the update with commit. The file stores compressed frames, an embedded WAL, a table of contents, and optional lexical, vector, and chronological indexes; existing frames remain immutable while new memory is appended. A client submits a SearchRequest to mem.search and receives hits containing titles, text, and snippets. The lex feature supplies Tantivy BM25 search, while vec adds HNSW search with local ONNX text embeddings and api_embed can call OpenAI's embedding API. The clip, whisper, and pdf_extract features add image retrieval, audio transcription, and PDF text extraction respectively. Its timeline model also supports querying earlier memory states and rewinding, replaying, or branching memory.

1. Developers building long-running assistants that must retain user facts and conversation context across sessions while keeping memory portable.
2. Teams deploying searchable knowledge bases on edge devices or isolated systems where a remote database is unavailable.
3. Engineering groups indexing source code and technical documents for lexical or semantic codebase exploration.
4. Customer-support, sales, or workflow-automation teams that need to accumulate operational context and retrieve relevant history quickly.
5. Medical, legal, or financial workflow designers who need immutable records and historical-state inspection for auditable memory behavior.
6. Applications ingesting PDFs, images, or audio that can provision the corresponding extraction, CLIP, or Whisper features and models.

How do you install or deploy this agent?

The Rust core requires Rust 1.85.0 or newer. Add the base crate to Cargo.toml:

[dependencies]
memvid-core = "2.0"

Enable full-text search, vector retrieval, and temporal parsing when required:

[dependencies]
memvid-core = { version = "2.0", features = ["lex", "vec", "temporal_track"] }

To build the repository itself:

git clone https://github.com/memvid/memvid.git
cd memvid
cargo build --release

Other documented distribution options are:

npm install -g memvid-cli
npm install @memvid/sdk
pip install memvid-sdk
cargo add memvid-core

Before using the default local BGE-small model with vec, download its ONNX model and tokenizer:

mkdir -p ~/.cache/memvid/text-models
curl -L 'https://huggingface.co/BAAI/bge-small-en-v1.5/resolve/main/onnx/model.onnx' \
  -o ~/.cache/memvid/text-models/bge-small-en-v1.5.onnx
curl -L 'https://huggingface.co/BAAI/bge-small-en-v1.5/resolve/main/tokenizer.json' \
  -o ~/.cache/memvid/text-models/bge-small-en-v1.5_tokenizer.json

Credentials are needed only for the optional OpenAI embedding path:

export OPENAI_API_KEY="sk-..."

How do you use this agent?

This Rust example creates a memory file, writes and commits one metadata-bearing document, then searches it:

use memvid_core::{Memvid, PutOptions, SearchRequest};

fn main() -> memvid_core::Result<()> {
    let mut mem = Memvid::create("knowledge.mv2")?;

    let opts = PutOptions::builder()
        .title("Meeting Notes")
        .uri("mv2://meetings/2024-01-15")
        .tag("project", "alpha")
        .build();
    mem.put_bytes_with_options(b"Q4 planning discussion...", opts)?;
    mem.commit()?;

    let response = mem.search(SearchRequest {
        query: "planning".into(),
        top_k: 10,
        snippet_chars: 200,
        ..Default::default()
    })?;

    for hit in response.hits {
        println!("{}: {}", hit.title.unwrap_or_default(), hit.text);
    }

    Ok(())
}

When using local embeddings, bind the index to its model to prevent accidental model mixing:

mem.set_vec_model("bge-small-en-v1.5")?;

The repository's documented examples can be launched directly:

cargo run --example basic_usage
cargo run --example pdf_ingestion
cargo run --example clip_visual_search --features clip
cargo run --example test_whisper --features whisper -- /path/to/audio.mp3

Run the test suite with:

cargo test

What are this agent's strengths and limitations?

How does this agent compare with similar options?

Key facts side by side with the most closely related agents.

How does FollowAgents rate this agent?

Recent releases

Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.

1. v2.0.140 2026-05-27
   Release notes excerpt

   Bug fixes #230 — WAL checksum mismatch after region growth Sustained put + commit workloads that grew the embedded WAL could corrupt it, surfacing as Embedded WAL is corrupted at offset N: wal record checksum mismatch (and, in some reports, runaway sparse-file growth past EOF). grow_wal_region / ensure_wal_capacity shifted the data region right by delta and updated data_end/footer_offset, but left cached_payload_end stale. rebuild_indexes then seeked to that pre-growth offset — now inside the grown WAL region — and overwrote live WAL record payloads. `cached_payloa …

   View on GitHub ↗
2. v2.0.139 2026-03-13
   Release notes excerpt

   v2.0.139 Release Date: March 13, 2026 Overview This release completes the fix for MV005 (Time index track is invalid: frame id out of range) by extending graceful stale frame_id handling to all search paths — find(), ask(), Tantivy, lex fallback, vec search, and temporal metadata lookups. --- 🐛 Bug Fixes MV005 crash in find() and ask() search paths — Issue #196 (continued) - v2.0.138 fixed the timeline.rs path only; stale frame_ids in Tantivy evaluation, snippet assembly, lex fallback, and temporal metadata lookups still caused hard crashes …

   View on GitHub ↗
3. v2.0.138 2026-03-03
   Release notes excerpt

   v2.0.138 Release Date: March 3, 2026 Overview This release fixes two SDK issues: lex_enabled/vec_enabled state not persisting after re-opening .mv2 files, and ask() crashing with "frame id out of range" on files with inconsistent time indexes. --- 🐛 Bug Fixes lex_enabled/vec_enabled reset to None on re-open — Issue #194 - Added lex_enabled and vec_enabled fields to the core Stats struct so SDKs can read runtime search engine state …

   View on GitHub ↗

FAQ