Install
npm (Recommended)
Cargo
From Source
npm install -g memvid-cli
cargo install --path memvid/crates/memvid-cli --force --features parallel_segments,temporal_track
Global Flags
| Flag | Description |
|---|
-v, --verbose | Debug output (repeat to increase) |
--embedding-model MODEL | Embedding model (bge-small, bge-base, nomic, gte-large, openai, openai-large) |
--parallel-segments | Enable parallel segment building |
--json | Output as JSON (available on most commands) |
Core Workflows
# Create a memory file
memvid create data.mv2 --tier free --size 1GB
# Ingest documents with embeddings
memvid put data.mv2 --input docs/whitepaper.pdf --title "Whitepaper" --label docs --embedding --vector-compression
# Search
memvid find data.mv2 --query "hybrid search" --top-k 5 --json
# Ask with citations
memvid ask data.mv2 --question "What changed last release?" --top-k 6 --mode hybrid --json
# Timeline and replay
memvid timeline data.mv2 --limit 20 --as-of-frame 150
# Inspect a frame
memvid view data.mv2 --frame-id 10 --page 1
# Stats and maintenance
memvid stats data.mv2
memvid verify data.mv2 --deep
memvid doctor data.mv2 --vacuum --rebuild-lex-index --rebuild-vec-index
API Reference
File Operations
| Command | Purpose | Key Flags |
|---|
create | Create new .mv2 file | --tier, --size, --no-lex, --no-vector |
open | Inspect metadata | --json |
stats | Show file statistics | --json |
Data Operations
| Command | Purpose | Key Flags |
|---|
put | Append from file or stdin | --input, --uri, --title, --embedding, --vector-compression |
put-many | Batch ingest | --input batch.json, --compression-level |
api-fetch | Fetch from HTTP + ingest | --config, --mode, --dry-run |
update | Replace payload/metadata | --frame-id, --uri, --input, --title |
delete | Remove a frame | --frame-id, --uri, --yes |
Search Operations
| Command | Purpose | Key Flags |
|---|
find | Lexical/hybrid search | --query, --mode, --top-k, --scope |
vec-search | Search with vector input | --vector, --embedding |
ask | Retrieval + synthesis | --question, --mode, --top-k, --sources |
Timeline & View
| Command | Purpose | Key Flags |
|---|
timeline | Chronological list | --limit, --since, --until, --reverse |
when | Temporal phrase resolution | --on, --tz, --anchor, --window |
view | Render a frame | --frame-id, --uri, --page, --play |
Memory Cards & Enrichment
| Command | Purpose | Key Flags |
|---|
enrich | Extract memory cards | --engine, --incremental, --json |
memories | View memory cards | --entity, --slot, --json |
state | Get entity state (O(1)) | --json |
facts | Audit extracted facts | --entity, --json |
export | Export facts | --format, --entity |
Tables
| Command | Purpose | Key Flags |
|---|
tables import | Import tables from PDF | --input, --embed-rows |
tables list | List all tables | --json |
tables export | Export table data | --table-id, --format |
Maintenance
| Command | Purpose | Key Flags |
|---|
verify | Check file integrity | --deep |
doctor | Repair and optimize | --vacuum, --rebuild-lex-index, --rebuild-vec-index |
who | Check file lock | --json |
nudge | Release stale lock | |
Tickets & Capacity
| Command | Purpose | Key Flags |
|---|
tickets sync | Sync from dashboard | --memory-id, --api-key |
tickets apply | Apply ticket manually | --ticket |
tickets list | List current tickets | --json |
plan show | Show current plan | --json |
Sessions
| Command | Purpose | Key Flags |
|---|
session start | Start recording | --name |
session end | End recording | |
session list | List sessions | --json |
session replay | Replay session | --adaptive, --top-k |
Embeddings are off by default in the CLI to save space. Add --embedding (and optionally --vector-compression) when you want vectors.
Environment Variables
| Variable | Purpose | Default |
|---|
MEMVID_API_KEY | Dashboard API key for ticket sync | n/a |
MEMVID_API_URL | Control plane base URL | production URL |
MEMVID_CACHE_DIR | Ticket cache directory | ~/.cache/memvid |
MEMVID_MODELS_DIR | Model cache directory | ~/.memvid/models |
MEMVID_OFFLINE | Skip model downloads | 0 |
MEMVID_EMBEDDING_MODEL | Default embedding model | bge-small |
MEMVID_LLM_CONTEXT_BUDGET | Max chars to send to LLMs | unset |
MEMVID_PARALLEL_SEGMENTS | Force parallel builder | unset |
OPENAI_API_KEY | OpenAI API key | n/a |
ANTHROPIC_API_KEY | Anthropic API key | n/a |
GEMINI_API_KEY | Google Gemini API key | n/a |
Error Codes
| Code | Name | Description |
|---|
| MV001 | CapacityExceeded | Storage limit reached |
| MV002 | TicketInvalid | Invalid ticket signature |
| MV004 | LexIndexDisabled | Lexical search not enabled |
| MV007 | FileLocked | File locked by another process |
| MV010 | FrameNotFound | Requested frame doesn’t exist |
| MV011 | VecIndexDisabled | Vector search not enabled |
| MV014 | VecDimensionMismatch | Wrong embedding dimension |
| MV015 | EmbeddingFailed | Embedding generation failed |
Tips
- Use
--json on any command for structured output
- Replay filters:
--as-of-frame and --as-of-ts are available on find, ask, and timeline
- Locks: mutation commands accept
--lock-timeout and --force for stale writers
doctor and verify are safe read-only when run with --plan-only or --deep
