> ## 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.

# Timeline, View & Stats

> Inspect your memories with timeline, view, and stats commands

Commands for inspecting and navigating your memory files.

***

## Timeline

Browse documents chronologically using the time index.

### Basic Usage

```bash theme={null}
memvid timeline knowledge.mv2
```

### Options

| Option               | Description                                | Default         |
| -------------------- | ------------------------------------------ | --------------- |
| `--limit`            | Maximum entries to return                  | 50              |
| `--since`            | Start timestamp (Unix)                     | None            |
| `--until`            | End timestamp (Unix)                       | None            |
| `--on <PHRASE>`      | Temporal phrase filter (e.g., "last week") | None            |
| `--tz <ZONE>`        | Timezone for temporal phrases              | America/Chicago |
| `--anchor <RFC3339>` | Anchor date for resolution                 | Now             |
| `--reverse`          | Reverse chronological order                | false           |
| `--json`             | Output as JSON                             | false           |

### Time-Travel Options

| Option                 | Description                   |
| ---------------------- | ----------------------------- |
| `--as-of-frame ID`     | View timeline as of frame ID  |
| `--as-of-ts TIMESTAMP` | View timeline as of timestamp |

### Examples

```bash theme={null}
# Get recent entries
memvid timeline knowledge.mv2 --limit 20

# Reverse order (oldest first)
memvid timeline knowledge.mv2 --reverse

# Filter by time range
memvid timeline knowledge.mv2 --since 1704067200 --until 1706745600

# Frames from last week
memvid timeline knowledge.mv2 --on "last week"

# Frames from specific timezone
memvid timeline knowledge.mv2 --on "yesterday" --tz "America/New_York"

# JSON output for scripting
memvid timeline knowledge.mv2 --json

# Time-travel view
memvid timeline knowledge.mv2 --as-of-frame 50
```

**Output:**

```
Timeline (5 entries):

[1] 2024-11-15 10:30:00 - API Documentation
    mv2://docs/api.md

[2] 2024-11-14 15:45:00 - Meeting Notes
    mv2://notes/meeting-2024-11-14.md

[3] 2024-11-14 09:00:00 - Project Roadmap
    mv2://planning/roadmap.md
```

**JSON Output:**

```json theme={null}
{
  "entries": [
    {
      "frame_id": 1,
      "timestamp": 1731667800,
      "preview": "API Documentation for v2...",
      "uri": "mv2://docs/api.md"
    },
    {
      "frame_id": 2,
      "timestamp": 1731600300,
      "preview": "Meeting Notes from standup...",
      "uri": "mv2://notes/meeting-2024-11-14.md"
    }
  ]
}
```

***

## View

Inspect individual documents and their metadata.

### Basic Usage

```bash theme={null}
memvid view knowledge.mv2 --frame-id 124
```

### Selection Options

| Option          | Description          |
| --------------- | -------------------- |
| `--frame-id ID` | Document ID to view  |
| `--uri URI`     | Document URI to view |

### Output Options

| Option      | Description                        |
| ----------- | ---------------------------------- |
| `--json`    | Output as JSON                     |
| `--binary`  | Raw binary output                  |
| `--preview` | Preview mode (for media)           |
| `--play`    | Play/stream mode (for audio/video) |

### Pagination (Text Content)

| Option        | Description         | Default |
| ------------- | ------------------- | ------- |
| `--page N`    | Page number         | 1       |
| `--page-size` | Characters per page | Auto    |

### Media Playback

| Option                     | Description                  |
| -------------------------- | ---------------------------- |
| `--preview-start HH:MM:SS` | Video preview start time     |
| `--preview-end HH:MM:SS`   | Video preview end time       |
| `--start-seconds`          | Playback start (with --play) |
| `--end-seconds`            | Playback end (with --play)   |

### Examples

```bash theme={null}
# View by frame ID
memvid view knowledge.mv2 --frame-id 124

# View by URI
memvid view knowledge.mv2 --uri "mv2://docs/api.md"

# JSON output with full metadata
memvid view knowledge.mv2 --frame-id 124 --json

# Preview an image
memvid view knowledge.mv2 --uri "mv2://images/diagram.png" --preview

# Play audio/video
memvid view knowledge.mv2 --frame-id 12 --play

# Play specific segment
memvid view knowledge.mv2 --frame-id 12 --play --start-seconds 30 --end-seconds 60

# Paginate long text
memvid view knowledge.mv2 --frame-id 5 --page 2 --page-size 2000

# Raw binary output
memvid view knowledge.mv2 --frame-id 10 --binary > output.pdf
```

**Output:**

```
Frame: 124
Title: API Documentation
URI: mv2://docs/api.md
Track: documentation
Kind: markdown
Timestamp: 2024-11-15T10:30:00Z
Tags: version=2.0, category=reference
Labels: api, public

Content:
The API provides endpoints for authentication, user management,
and data retrieval. All endpoints require authentication via...
```

**JSON Output:**

```json theme={null}
{
  "frame_id": 124,
  "title": "API Documentation",
  "uri": "mv2://docs/api.md",
  "track": "documentation",
  "kind": "markdown",
  "timestamp": 1731667800,
  "tags": {
    "version": "2.0",
    "category": "reference"
  },
  "labels": ["api", "public"],
  "checksum": "a3b2c1d4e5f6...",
  "payload_length": 15234,
  "content": "The API provides endpoints for..."
}
```

***

## Update

Modify frame metadata (not content).

### Basic Usage

```bash theme={null}
memvid update knowledge.mv2 --frame-id 124 --title "New Title"
```

### Selection

| Option          | Description         |
| --------------- | ------------------- |
| `--frame-id ID` | Frame ID to update  |
| `--uri URI`     | Frame URI to update |

### Updatable Fields

| Option                 | Description                           |
| ---------------------- | ------------------------------------- |
| `--set-uri URI`        | Change the URI                        |
| `--title TITLE`        | Update title                          |
| `--timestamp TS`       | Update timestamp                      |
| `--track TRACK`        | Update track                          |
| `--kind KIND`          | Update kind                           |
| `--tag KEY=VALUE`      | Add/update tags                       |
| `--label LABEL`        | Add labels                            |
| `--metadata JSON`      | Add metadata                          |
| `--input PATH`         | Replace payload                       |
| `--vector-compression` | Recompute embeddings with compression |

### Examples

```bash theme={null}
# Update title
memvid update knowledge.mv2 --frame-id 124 --title "Updated API Docs"

# Add tags
memvid update knowledge.mv2 --uri "mv2://docs/api.md" \
  --tag "reviewed=true" \
  --tag "version=2.1"

# Move to different track
memvid update knowledge.mv2 --frame-id 124 --track "archived"

# Replace content and recompute embeddings
memvid update knowledge.mv2 --frame-id 124 \
  --input ./new-content.md \
  --vector-compression
```

***

## Delete

Remove frames from the memory.

### Basic Usage

```bash theme={null}
memvid delete knowledge.mv2 --frame-id 42
```

### Options

| Option          | Description              |
| --------------- | ------------------------ |
| `--frame-id ID` | Frame ID to delete       |
| `--uri URI`     | Frame URI to delete      |
| `--yes`         | Skip confirmation prompt |
| `--json`        | JSON output              |

### Examples

```bash theme={null}
# Delete with confirmation
memvid delete knowledge.mv2 --frame-id 42

# Delete without confirmation
memvid delete knowledge.mv2 --uri "mv2://old/doc.md" --yes

# Reclaim space after deletions
memvid doctor knowledge.mv2 --vacuum
```

***

## Stats

Get statistics about your memory file.

### Basic Usage

```bash theme={null}
memvid stats knowledge.mv2
```

### Options

| Option   | Description    |
| -------- | -------------- |
| `--json` | Output as JSON |

### Examples

```bash theme={null}
# Human-readable output
memvid stats knowledge.mv2

# JSON for scripting
memvid stats knowledge.mv2 --json
```

**Output:**

```
Memory: knowledge.mv2

Documents:         150
Active Frames:     148
Size:              52.4 MB
Capacity:          1.0 GB
Utilization:       5.2%

Indices:
  Lexical:         Yes
  Vector:          Yes
  Time:            Yes

Storage Breakdown:
  Payloads:        48.2 MB
  Lex Index:       2.1 MB
  Vec Index:       1.8 MB
  Time Index:      0.3 MB

Compression:
  Ratio:           78%
  Saved:           14.2 MB
```

**JSON Output:**

```json theme={null}
{
  "frame_count": 150,
  "active_frame_count": 148,
  "size_bytes": 54945587,
  "capacity_bytes": 1073741824,
  "storage_utilisation_percent": 5.2,
  "has_lex_index": true,
  "has_vec_index": true,
  "has_time_index": true,
  "payload_bytes": 50545664,
  "lex_index_bytes": 2202009,
  "vec_index_bytes": 1887436,
  "time_index_bytes": 310478,
  "compression_ratio_percent": 78,
  "saved_bytes": 14876543
}
```

***

## Open

Inspect memory file metadata and manifests.

```bash theme={null}
memvid open knowledge.mv2
```

### Options

| Option   | Description    |
| -------- | -------------- |
| `--json` | Output as JSON |

Shows detailed information about the file structure, including frame count, index status, and internal metadata.

***

## Lock Inspection

### Who

Check who holds the write lock:

```bash theme={null}
memvid who knowledge.mv2
```

**Output:**

```
Lock held by:
  PID: 12345
  Acquired: 2024-11-15T10:30:00Z
  Heartbeat: Active
```

### Nudge

Request the active writer to release when safe:

```bash theme={null}
memvid nudge knowledge.mv2
```

This sends a signal to the writer process to checkpoint and release the lock.

***

## Real-World Examples

### Daily Review

```bash theme={null}
# See what was added today
memvid timeline notes.mv2 --since $(date -d "today 00:00" +%s) --limit 50

# View specific entry details
memvid view notes.mv2 --frame-id 42 --json
```

### Archiving Old Content

```bash theme={null}
# Find old entries
memvid timeline archive.mv2 --until $(date -d "6 months ago" +%s)

# Update their track
for id in 1 2 3 4 5; do
  memvid update archive.mv2 --frame-id $id --track "archived"
done
```

### Media Library

```bash theme={null}
# Browse media timeline
memvid timeline media.mv2 --limit 20

# Preview an image
memvid view media.mv2 --uri "mv2://photos/vacation.jpg" --preview

# Play a video clip
memvid view media.mv2 --frame-id 15 --play --start-seconds 10 --end-seconds 30
```

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Maintenance" icon="wrench" href="/cli/maintenance-and-tickets">
    Repair files and verify integrity
  </Card>

  <Card title="Search & Ask" icon="magnifying-glass" href="/cli/search-and-ask">
    Query your memories
  </Card>
</CardGroup>