rig-memvid

Memvid-backed persistent memory and vector store for Rig agents.

memvid-core is a crash-safe, deterministic, single-file (.mv2) AI memory format. This crate exposes that format to Rig in two ways:

1. MemvidStore — a VectorStoreIndex you can register with an agent for RAG.
2. MemvidPersistHook — a PromptHook that automatically appends every user prompt and assistant response into a memvid file as the agent runs.

The two compose: persist with the hook, recall with the store. They share an Arc<Mutex<Memvid>> so writes are immediately searchable.

Features

Vector search (vec)

Enabling vec pulls in ort = =2.0.0-rc.10, which conflicts with rig-fastembed's =2.0.0-rc.9. Workspaces that depend on rig-fastembed must stay on the default lex-only configuration until those pins converge upstream. Workspaces that don't can opt in:

[dependencies]
rig-memvid = { version = "0.1", features = ["lex", "vec"] }

Attach a local embedder on the builder; reads and writes through [MemvidStore] are then routed through memvid's HNSW index instead of BM25:

let store = MemvidStore::builder()
    .path("./agent_memory.mv2")
    .with_default_embedder()? // BGE-small, 384-dim
    .open_or_create()?;

The ONNX model and tokenizer are loaded from $XDG_CACHE_HOME/memvid/text-models/ (or the platform equivalent). They must already be on disk; memvid does not auto-download. Fetch them with:

mkdir -p ~/Library/Caches/memvid/text-models   # macOS
curl -L https://huggingface.co/BAAI/bge-small-en-v1.5/resolve/main/onnx/model.onnx \
  -o ~/Library/Caches/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 ~/Library/Caches/memvid/text-models/bge-small-en-v1.5_tokenizer.json

When an embedder is attached:

• MemvidStore::put_text embeds the payload and stores it via put_with_embedding_and_options.
• MemvidStore::top_n / top_n_ids embed the query and run vec_search_with_embedding.
• MemvidFilter::scope is honoured; uri, as_of_frame, and as_of_ts return MemvidError::UnsupportedFilter (memvid's vector path doesn't support those). Drop down to MemvidStore::search(SearchRequest) for full filter control.

Compatibility

This crate is community-maintained and not affiliated with the rig project.

WASM

memvid-core depends on tantivy, mmap, and (optionally) onnxruntime. This crate is not WASM-compatible and will not build for wasm32-* targets.

Quickstart

use rig::providers::openai;
use rig_memvid::{MemvidStore, MemvidPersistHook, MemoryConfig, WritePolicy};

# async fn run() -> anyhow::Result<()> {
let store = MemvidStore::builder()
    .path("./agent_memory.mv2")
    .open_or_create()?;

let openai = openai::Client::from_env();

let hook = MemvidPersistHook::new(
    store.clone(),
    MemoryConfig {
        policy: WritePolicy::Raw,
        commit_each_turn: true,
        default_tags: vec!["chat".into()],
    },
);

let agent = openai
    .agent(openai::GPT_4O)
    .preamble("You are a helpful assistant with persistent memory.")
    .dynamic_context(4, store)
    .build();

let response = agent
    .prompt("What did we discuss yesterday?")
    .with_hook(hook)
    .await?;

println!("{response}");
# Ok(()) }

Filter

MemvidFilter implements SearchFilter and accepts these keys via eq(...):

• uri (String) — restrict to frames whose URI matches the given prefix
• scope (String) — restrict to a logical scope
• as_of_frame (u64) — point-in-time view by frame id
• as_of_ts (i64) — point-in-time view by unix-millis timestamp

gt/lt/or are not supported by memvid's query model and will produce a MemvidError::UnsupportedFilter at query time.

License

MIT