> ## Documentation Index
> Fetch the complete documentation index at: https://docs.memvid.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Advanced CLI Commands

> Advanced commands for enrichment, models, Logic-Mesh traversal, and auditing

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

```bash theme={null}
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

```bash theme={null}
# 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

```json theme={null}
{
  "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

```bash theme={null}
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

```bash theme={null}
# 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

```json theme={null}
{
  "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

```bash theme={null}
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

```bash theme={null}
# 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

```json theme={null}
{
  "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

```bash theme={null}
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

```bash theme={null}
# 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

```bash theme={null}
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

```bash theme={null}
# 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:**

```json theme={null}
[
  {
    "subject": "Alice",
    "predicate": "employer",
    "object": "Anthropic",
    "confidence": 0.95,
    "source_frame_id": 145
  }
]
```

**CSV:**

```csv theme={null}
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

```bash theme={null}
memvid schema <SUBCOMMAND> <FILE> [OPTIONS]
```

### Subcommands

#### schema infer

Infer schema from existing facts.

```bash theme={null}
memvid schema infer project.mv2

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

#### schema list

List known schemas.

```bash theme={null}
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

```bash theme={null}
# 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

```bash theme={null}
# 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

```bash theme={null}
# 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.

<Note>
  Logic-Mesh must be enabled during ingestion with `memvid put --logic-mesh` to use follow commands.
</Note>

### Subcommands

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

### Traverse Relationships

```bash theme={null}
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

```bash theme={null}
# 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

```bash theme={null}
# 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

```bash theme={null}
# 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

```bash theme={null}
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

```bash theme={null}
# 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:**

```markdown theme={null}
# 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:**

```json theme={null}
{
  "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

```bash theme={null}
# 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

```bash theme={null}
memvid session end knowledge.mv2
```

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

### List Sessions

```bash theme={null}
# 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.

```bash theme={null}
# 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

```bash theme={null}
# 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:

1. **Start a session** before ingesting data
2. **Ingest documents** with different terminology
3. **Run queries** that show the failure
4. **End the session**
5. **Replay with adaptive retrieval** to see if results improve

```bash theme={null}
# 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

```bash theme={null}
# 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

```bash theme={null}
# 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

```bash theme={null}
# 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

<CardGroup cols={2}>
  <Card title="Entity Extraction" icon="diagram-project" href="/concepts/entity-extraction">
    Learn about Logic-Mesh and entity extraction
  </Card>

  <Card title="Visual Embeddings" icon="image" href="/concepts/visual-embeddings">
    Enable visual search with CLIP
  </Card>

  <Card title="Local Models" icon="microchip" href="/concepts/local-models">
    Configure local model inference
  </Card>

  <Card title="Python SDK" icon="python" href="/python-sdk/overview">
    Use these features programmatically
  </Card>
</CardGroup>