Advanced CLI Commands

Advanced CLI commands for power users including memory enrichment, model management, entity graph traversal, and document auditing.

Enrichment

The enrich command extracts structured memory cards (Subject-Predicate-Object triplets) from frames using various extraction engines.

Text: "Alice works at Anthropic as a Senior Engineer"

Extracted Facts:
  Alice → employer → Anthropic
  Alice → role → Senior Engineer

Synopsis

memvid enrich <FILE> [OPTIONS]

Options

Option	Description	Default
`--engine <ENGINE>`	Extraction engine	`rules`
`--incremental`	Only process unenriched frames	`true`
`--force`	Re-enrich all frames	Disabled
`--json`	Output results as JSON	Disabled
`--verbose`	Show extracted memory cards	Disabled

Available Engines

Engine	Description	Speed	Accuracy	Requires
`rules`	Pattern-based extraction	Fast	Good	Nothing (offline)
`candle`	Local LLM (Phi-3.5)	Medium	Better	Downloaded model
`openai`	OpenAI GPT-4o-mini	Slow	Best	API key
`claude`	Anthropic Claude	Slow	Best	API key
`gemini`	Google Gemini	Slow	Best	API key
`mistral`	Mistral AI	Slow	Better	API key
`groq`	Groq (fast inference)	Fast	Better	API key

Examples

# Fast, offline enrichment using rules
memvid enrich project.mv2 --engine rules

# See what was extracted
memvid enrich project.mv2 --engine rules --verbose

# Using OpenAI (most accurate)
OPENAI_API_KEY=sk-xxx memvid enrich project.mv2 --engine openai

# Using local LLM (no API needed)
memvid enrich project.mv2 --engine candle

# Using Claude
ANTHROPIC_API_KEY=sk-ant-xxx memvid enrich project.mv2 --engine claude

# Re-process everything
memvid enrich project.mv2 --engine rules --force

Response

Enrichment complete for project.mv2

Engine: rules v1.2.0
Frames processed: 45
Cards extracted: 127
  - Entities: 23
  - Facts: 89
  - Events: 15

New cards: 127
Total cards: 127
Total entities: 23

JSON Output

{
  "engine": "rules",
  "version": "1.2.0",
  "frames_processed": 45,
  "cards_extracted": 127,
  "total_cards": 127,
  "total_entities": 23,
  "new_cards": 127,
  "cards_by_kind": {
    "fact": 89,
    "event": 15,
    "entity": 23
  }
}

Memories

The memories command displays extracted memory cards from enriched frames.

Synopsis

memvid memories <FILE> [OPTIONS]

Options

Option	Description	Default
`--entity <NAME>`	Filter by entity name	All
`--kind <KIND>`	Filter by card kind	All
`--limit <N>`	Max results	50
`--offset <N>`	Pagination offset	0
`--sort <FIELD>`	Sort by field	None
`--as-of-frame <ID>`	Time-travel view	Current
`--json`	Output as JSON	Disabled

Examples

# View all memory cards
memvid memories project.mv2

# Filter by entity
memvid memories project.mv2 --entity "Alice"

# Filter by kind
memvid memories project.mv2 --kind fact

# Paginate
memvid memories project.mv2 --limit 20 --offset 40

# JSON output
memvid memories project.mv2 --json

Response

Memory Cards in project.mv2 (showing 50 of 127)

Entity: Alice
  employer: Anthropic (fact, frame #123)
  role: Senior Engineer (fact, frame #123)
  location: San Francisco (fact, frame #145)
  joined: 2023-06 (event, frame #123)

Entity: Bob
  employer: OpenAI (fact, frame #156)
  role: Research Scientist (fact, frame #156)

Entity: Project Alpha
  status: active (fact, frame #189)
  budget: $500,000 (fact, frame #201)
  lead: Alice (fact, frame #189)

JSON Output

{
  "count": 127,
  "cards": [
    {
      "id": "card_001",
      "entity": "Alice",
      "slot": "employer",
      "value": "Anthropic",
      "kind": "fact",
      "polarity": "positive",
      "confidence": 0.95,
      "source_frame_id": 123,
      "source_uri": "file:///meeting.txt",
      "engine": "rules",
      "engine_version": "1.2.0"
    }
  ]
}

State

Query current entity state with O(1) lookup. This is the fastest way to get an entity’s current attributes.

Synopsis

memvid state <FILE> <ENTITY> [OPTIONS]

Arguments

Argument	Description
`FILE`	Path to the .mv2 file
`ENTITY`	Entity name to query

Options

Option	Description
`--predicate <PRED>`	Filter by predicate
`--as-of-frame <ID>`	Time-travel view
`--json`	JSON output

Examples

# Get Alice's current state
memvid state project.mv2 "Alice"

# Get specific predicate
memvid state project.mv2 "Alice" --predicate employer

# Time-travel: Alice's state at frame 100
memvid state project.mv2 "Alice" --as-of-frame 100

Response

Entity: Alice

Current State:
  employer: Anthropic
    Kind: fact | Source: frame #145 | Engine: rules

  role: Senior Engineer
    Kind: fact | Source: frame #145 | Engine: rules

  location: San Francisco
    Kind: fact | Source: frame #156 | Engine: openai

  joined: 2023-06
    Kind: event | Source: frame #145 | Engine: rules

Last updated: frame #156 (2024-01-20)

JSON Output

{
  "entity": "Alice",
  "found": true,
  "slots": {
    "employer": {
      "value": "Anthropic",
      "kind": "fact",
      "polarity": "positive",
      "source_frame_id": 145,
      "document_date": "2024-01-15",
      "engine": "rules"
    },
    "role": {
      "value": "Senior Engineer",
      "kind": "fact",
      "source_frame_id": 145,
      "engine": "rules"
    }
  }
}

Facts

Audit fact changes with provenance and filtering.

Synopsis

memvid facts <FILE> [OPTIONS]

Options

Option	Description
`--entity <NAME>`	Filter by entity
`--predicate <PRED>`	Filter by predicate
`--object <OBJ>`	Filter by object value
`--added`	Show only additions
`--removed`	Show only deletions
`--limit <N>`	Max results (default: 50)
`--json`	JSON output

Examples

# View all fact changes
memvid facts project.mv2

# Changes for Alice
memvid facts project.mv2 --entity "Alice"

# Only employer changes
memvid facts project.mv2 --predicate employer

# Only additions
memvid facts project.mv2 --added

Response

Fact Audit for project.mv2

[+] Alice → employer → Anthropic
    Frame: #145 | Date: 2024-01-15 | Engine: rules

[+] Alice → role → Senior Engineer
    Frame: #145 | Date: 2024-01-15 | Engine: rules

[-] Bob → employer → Google
    Frame: #156 | Date: 2024-01-18 | Engine: rules

[+] Bob → employer → OpenAI
    Frame: #156 | Date: 2024-01-18 | Engine: rules

Export

Export facts to various formats.

Synopsis

memvid export <FILE> -o <PATH> [OPTIONS]

Options

Option	Description	Default
`-o <PATH>`, `--out <PATH>`	Output file path	Required
`--format <FORMAT>`	Format: `ntriples`, `json`, `csv`	`ntriples`
`--entity <NAME>`	Filter by entity	All
`--predicate <PRED>`	Filter by predicate	All

Examples

# Export as N-Triples (RDF)
memvid export project.mv2 -o facts.nt --format ntriples

# Export as JSON
memvid export project.mv2 -o facts.json --format json

# Export as CSV
memvid export project.mv2 -o facts.csv --format csv

# Export only Alice's facts
memvid export project.mv2 -o alice.json --format json --entity "Alice"

Output Formats

N-Triples (RDF):

<Alice> <employer> "Anthropic" .
<Alice> <role> "Senior Engineer" .
<Bob> <employer> "OpenAI" .

JSON:

[
  {
    "subject": "Alice",
    "predicate": "employer",
    "object": "Anthropic",
    "confidence": 0.95,
    "source_frame_id": 145
  }
]

CSV:

subject,predicate,object,confidence,source_frame_id
Alice,employer,Anthropic,0.95,145
Alice,role,Senior Engineer,0.92,145
Bob,employer,OpenAI,0.88,156

Schema

Infer and manage predicate schemas.

Synopsis

memvid schema <SUBCOMMAND> <FILE> [OPTIONS]

Subcommands

schema infer

Infer schema from existing facts.

memvid schema infer project.mv2

# Filter by entity type
memvid schema infer project.mv2 --entity-type person

schema list

List known schemas.

memvid schema list project.mv2

# Filter by predicate
memvid schema list project.mv2 --predicate employer

Response

Inferred Schema for project.mv2

Entity Type: person
  employer: string (organization)
  role: string (job_title)
  location: string (city)
  joined: date

Entity Type: project
  status: enum (active, completed, cancelled)
  budget: currency
  lead: reference (person)
  deadline: date

Models

The models command manages local models for enrichment, embeddings, and visual search.

Subcommands

Subcommand	Description
`install`	Install a model
`list`	List available and installed models
`remove`	Remove an installed model
`verify`	Verify model integrity

Install Models

# Install LLM model for enrichment
memvid models install phi-3.5-mini

# Install CLIP model for visual search
memvid models install --clip mobileclip-s2

# Install NER model for Logic-Mesh entity extraction
memvid models install --ner distilbert-ner

# Force re-download
memvid models install phi-3.5-mini --force

Available Models

Category	Model	Description
LLM	`phi-3.5-mini`	Phi-3.5 Mini for enrichment
LLM	`phi-3.5-mini-q8`	Quantized version (smaller)
CLIP	`mobileclip-s2`	MobileCLIP for visual search
CLIP	`mobileclip-s2-fp16`	FP16 precision version
CLIP	`siglip-base`	SigLIP base model
NER	`distilbert-ner`	DistilBERT NER for entity extraction

List Models

# List all models
memvid models list

# JSON output
memvid models list --json

# Filter by model type
memvid models list --model-type embedding
memvid models list --model-type clip
memvid models list --model-type ner

Model Types

Type	Description
`embedding`	Text embedding models for semantic search
`reranker`	Result reranking models
`llm`	Local LLM models for inference
`clip`	CLIP models for visual search
`ner`	NER models for entity extraction
`external`	External API-based models

Remove and Verify Models

# Remove a model
memvid models remove phi-3.5-mini

# Skip confirmation
memvid models remove phi-3.5-mini --yes

# Verify model integrity
memvid models verify phi-3.5-mini

# Verify all installed models
memvid models verify

Follow (Logic-Mesh Traversal)

The follow command traverses the entity-relationship graph built from extracted entities.

Logic-Mesh must be enabled during ingestion with memvid put --logic-mesh to use follow commands.

Subcommands

Subcommand	Description
`traverse`	Follow relationships from an entity
`entities`	List all entities in the mesh
`stats`	Show Logic-Mesh statistics

Traverse Relationships

memvid follow traverse knowledge.mv2 --start "Microsoft"

Traverse Options

Option	Description	Default
`--start`, `-s`	Starting entity (partial match)	Required
`--link`, `-l`	Relationship type to follow	`related`
`--hops`	Maximum traversal depth	`2`
`--direction`	Direction (`outgoing`, `incoming`, `both`)	`both`
`--json`	Output as JSON	`false`

Traverse Examples

# Find entities related to Microsoft
memvid follow traverse knowledge.mv2 --start "Microsoft"

# Follow specific relationship type
memvid follow traverse knowledge.mv2 --start "Satya Nadella" --link "manager"

# Deeper traversal
memvid follow traverse knowledge.mv2 --start "Seattle" --hops 3

# JSON output
memvid follow traverse knowledge.mv2 --start "Microsoft" --json

List Entities

# List all entities
memvid follow entities knowledge.mv2

# Filter by entity type
memvid follow entities knowledge.mv2 --kind person
memvid follow entities knowledge.mv2 --kind organization

# Search entities by name
memvid follow entities knowledge.mv2 --query "tech"

# Limit results
memvid follow entities knowledge.mv2 --limit 100

# JSON output
memvid follow entities knowledge.mv2 --json

Entity Types

Type	Description
`person`	Individuals
`organization`	Companies, institutions
`project`	Projects, products
`location`	Places, addresses

Mesh Statistics

# View Logic-Mesh statistics
memvid follow stats knowledge.mv2

# JSON output
memvid follow stats knowledge.mv2 --json

Stats Output

Logic-Mesh Statistics
=====================
  Nodes (entities):  156
  Edges (relations): 423

  Entity Kinds:
    person: 45
    organization: 32
    project: 28
    location: 51

  Relationship Types:
    related: 180
    member: 95
    manager: 48
    author: 100

  Storage offset:    1234567
  Storage size:      45678 bytes

Audit

The audit command generates sourced reports on specific topics from your knowledge base.

Basic Usage

memvid audit knowledge.mv2 "What are the key findings about customer satisfaction?"

Options

Option	Description	Default
`--out`, `-o`	Output file path	stdout
`--format`	Output format (`text`, `markdown`, `json`)	`text`
`--top-k`	Number of sources to retrieve	`10`
`--snippet-chars`	Maximum characters per snippet	`500`
`--mode`	Retrieval mode (`lex`, `sem`, `hybrid`)	`hybrid`
`--scope`	Filter by URI prefix	None
`--start`	Start date filter	None
`--end`	End date filter	None
`--use-model`	Model for answer synthesis	None

Examples

# Basic audit to stdout
memvid audit knowledge.mv2 "Revenue trends in Q4"

# Save as markdown report
memvid audit knowledge.mv2 "Security vulnerabilities" --format markdown --out report.md

# JSON output for automation
memvid audit knowledge.mv2 "Customer feedback" --format json --out audit.json

# More comprehensive retrieval
memvid audit knowledge.mv2 "Product roadmap" --top-k 20 --snippet-chars 1000

# Filter by date range
memvid audit knowledge.mv2 "Sales performance" --start "2024-01-01" --end "2024-12-31"

# Filter by URI scope
memvid audit knowledge.mv2 "Engineering decisions" --scope "mv2://docs/engineering/"

# Use model for answer synthesis
memvid audit knowledge.mv2 "Summarize customer issues" --use-model "ollama:qwen2.5:1.5b"
memvid audit knowledge.mv2 "Key takeaways" --use-model "openai:gpt-4o-mini"
memvid audit knowledge.mv2 "Key takeaways" --use-model "nvidia:meta/llama3-8b-instruct"

Output Formats

Text (default):

AUDIT REPORT: Revenue trends in Q4
==================================

Source 1: Q4 Financial Report (mv2://reports/q4-2024.pdf)
---------------------------------------------------------
Revenue increased 15% year-over-year, driven by enterprise sales...

Source 2: Board Meeting Notes (mv2://notes/board-dec.md)
--------------------------------------------------------
CFO presented Q4 projections showing strong growth in APAC region...

Markdown:

# Audit Report: Revenue trends in Q4

## Source 1: Q4 Financial Report
**URI:** mv2://reports/q4-2024.pdf

Revenue increased 15% year-over-year, driven by enterprise sales...

## Source 2: Board Meeting Notes
**URI:** mv2://notes/board-dec.md

CFO presented Q4 projections showing strong growth in APAC region...

JSON:

{
  "question": "Revenue trends in Q4",
  "sources": [
    {
      "title": "Q4 Financial Report",
      "uri": "mv2://reports/q4-2024.pdf",
      "snippet": "Revenue increased 15% year-over-year...",
      "score": 0.95
    }
  ],
  "answer": "Based on the sources, Q4 revenue increased 15%..."
}

Session Recording (Time-Travel Replay)

The session command enables recording and replaying agent sessions for debugging RAG failures and testing different search strategies.

Subcommands

Subcommand	Description
`start`	Start a recording session
`end`	End the current recording session
`list`	List all recorded sessions
`replay`	Replay a session with different parameters
`delete`	Delete a recorded session

Start Session

# Start a named recording session
memvid session start knowledge.mv2 "Debug Session"

# Start an unnamed session
memvid session start knowledge.mv2

All subsequent operations (put, find, ask) will be recorded until the session is ended.

End Session

memvid session end knowledge.mv2

Returns a summary with action count, checkpoints, and duration.

List Sessions

# List all recorded sessions
memvid session list knowledge.mv2

# JSON output
memvid session list knowledge.mv2 --json

Replay Session

The key feature: replay a recorded session with different parameters to understand how results change.

# Replay with default parameters
memvid session replay knowledge.mv2 <session-id>

# Replay with adaptive retrieval enabled
memvid session replay knowledge.mv2 <session-id> --adaptive

# Replay with different top-k
memvid session replay knowledge.mv2 <session-id> --top-k 20

# Replay with different strategy
memvid session replay knowledge.mv2 <session-id> --adaptive --strategy elbow

Replay Options

Option	Description	Default
`--adaptive`	Enable adaptive retrieval	`false`
`--top-k`	Override top-k for searches	Original value
`--strategy`	Adaptive strategy (`elbow`, `cliff`, `relative`, `combined`)	`combined`
`--verbose`	Show detailed replay output	`false`
`--json`	Output results as JSON	`false`

Delete Session

# Delete a session
memvid session delete knowledge.mv2 <session-id>

# Skip confirmation
memvid session delete knowledge.mv2 <session-id> --yes

Use Case: Debugging RAG Failures

When a query fails to find relevant results:

Start a session before ingesting data
Ingest documents with different terminology
Run queries that show the failure
End the session
Replay with adaptive retrieval to see if results improve

# Start recording
memvid session start knowledge.mv2 "Terminology Mismatch Debug"

# Ingest documents
memvid put knowledge.mv2 --text "Databricks acquired Tabular"

# Query with mismatched terminology (fails with top-k)
memvid find knowledge.mv2 "Databricks purchases"

# End recording
memvid session end knowledge.mv2

# Replay with adaptive retrieval
memvid session replay knowledge.mv2 <session-id> --adaptive --verbose

The replay shows how adaptive retrieval discovers documents that top-k filtering missed.

Best Practices

Enrichment Strategy

# Start with fast, offline rules
memvid enrich project.mv2 --engine rules

# Upgrade to LLM for better accuracy on important data
memvid enrich project.mv2 --engine openai --force

# Use incremental for ongoing updates
memvid enrich project.mv2 --engine rules  # Only new frames

Combining Search Modes

# Use state for entity queries (instant)
memvid state project.mv2 "Alice"

# Use find for exploratory search
memvid find project.mv2 --query "who works at AI companies" --graph

# Use ask for complex questions
memvid ask project.mv2 --question "What projects is Alice leading?" --memories

Compliance and Audit

# Export all facts for compliance review
memvid export project.mv2 -o compliance.json --format json

# Audit specific entity
memvid facts project.mv2 --entity "Alice" > alice-audit.txt

# Time-travel for historical state
memvid state project.mv2 "Alice" --as-of-frame 100

Environment Variables

Variable	Description
`MEMVID_MODELS_DIR`	Model storage directory (default: `~/.memvid/models`)
`MEMVID_OFFLINE=1`	Skip model downloads (use cached models only)
`OPENAI_API_KEY`	Required for OpenAI enrichment and models
`ANTHROPIC_API_KEY`	Required for Claude models
`GEMINI_API_KEY`	Required for Gemini models (legacy: `GOOGLE_API_KEY`)
`MISTRAL_API_KEY`	Required for Mistral models
`GROQ_API_KEY`	Required for Groq inference

Next Steps

Entity Extraction

Learn about Logic-Mesh and entity extraction

Visual Embeddings

Enable visual search with CLIP

Local Models

Configure local model inference

Python SDK

Use these features programmatically

​Enrichment

​Synopsis

​Options

​Available Engines

​Examples

​Response

​JSON Output

​Memories

​Synopsis

​Options

​Examples

​Response

​JSON Output

​State

​Synopsis

​Arguments

​Options

​Examples

​Response

​JSON Output

​Facts

​Synopsis

​Options

​Examples

​Response

​Export

​Synopsis

​Options

​Examples

​Output Formats

​Schema

​Synopsis

​Subcommands

​schema infer

​schema list

​Response

​Models

​Subcommands

​Install Models

​Available Models

​List Models

​Model Types

​Remove and Verify Models

​Follow (Logic-Mesh Traversal)

​Subcommands

​Traverse Relationships

​Traverse Options

​Traverse Examples

​List Entities

​Entity Types

​Mesh Statistics

​Stats Output

​Audit

​Basic Usage

​Options

​Examples

​Output Formats

​Session Recording (Time-Travel Replay)

​Subcommands

​Start Session

​End Session

​List Sessions

​Replay Session

​Replay Options

​Delete Session

​Use Case: Debugging RAG Failures

​Best Practices

​Enrichment Strategy

​Combining Search Modes

​Compliance and Audit

​Environment Variables

​Next Steps

Entity Extraction

Visual Embeddings

Local Models

Python SDK

Enrichment

Synopsis

Options

Available Engines

Examples

Response

JSON Output

Memories

Synopsis

Options

Examples

Response

JSON Output

State

Synopsis

Arguments

Options

Examples

Response

JSON Output

Facts

Synopsis

Options

Examples

Response

Export

Synopsis

Options

Examples

Output Formats

Schema

Synopsis

Subcommands

schema infer

schema list

Response

Models

Subcommands

Install Models

Available Models

List Models

Model Types

Remove and Verify Models

Follow (Logic-Mesh Traversal)

Subcommands

Traverse Relationships

Traverse Options

Traverse Examples

List Entities

Entity Types

Mesh Statistics

Stats Output

Audit

Basic Usage

Options

Examples

Output Formats

Session Recording (Time-Travel Replay)

Subcommands

Start Session

End Session

List Sessions

Replay Session

Replay Options

Delete Session

Use Case: Debugging RAG Failures

Best Practices

Enrichment Strategy

Combining Search Modes

Compliance and Audit

Environment Variables

Next Steps