CLI Reference - Memvid

Install

Auto Installer (Recommended)
npm
Cargo
From Source

The installer automatically checks for and installs required dependencies (git, node, npm), then installs Memvid globally.macOS / Linux:

curl -fsSL https://raw.githubusercontent.com/memvid/preflight-installer/main/install.sh | bash

Windows (PowerShell):

irm https://raw.githubusercontent.com/memvid/preflight-installer/main/install.ps1 | iex

The installer only installs missing tools and asks for confirmation before proceeding. View source on GitHub

npm install -g memvid-cli

cargo install memvid-cli

cargo install --path memvid/crates/memvid-cli --force --features parallel_segments,temporal_track

Verify installation:

memvid --version

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

See Error Reference for complete documentation.

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

Five-Minute Quickstart

Fast start for CLI, Python, and Node.js

CLI Commands

Detailed command documentation

​Install

​Global Flags

​Core Workflows

​API Reference

​File Operations

​Data Operations

​Search Operations

​Timeline & View

​Memory Cards & Enrichment

​Tables

​Maintenance

​Tickets & Capacity

​Sessions

​Environment Variables

​Error Codes

​Tips

Five-Minute Quickstart

CLI Commands

Install

Global Flags

Core Workflows

API Reference

File Operations

Data Operations

Search Operations

Timeline & View

Memory Cards & Enrichment

Tables

Maintenance

Tickets & Capacity

Sessions

Environment Variables

Error Codes

Tips