Timeline, View & Stats

Commands for inspecting and navigating your memory files.

Timeline

Browse documents chronologically using the time index.

Basic Usage

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

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

{
  "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

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

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

{
  "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

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

# 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

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

# 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

memvid stats knowledge.mv2

Options

Option	Description
`--json`	Output as JSON

Examples

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

{
  "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.

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:

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:

memvid nudge knowledge.mv2

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

Real-World Examples

Daily Review

# 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

# 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

# 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

​Timeline

​Basic Usage

​Options

​Time-Travel Options

​Examples

​View

​Basic Usage

​Selection Options

​Output Options

​Pagination (Text Content)

​Media Playback

​Examples

​Update

​Basic Usage

​Selection

​Updatable Fields

​Examples

​Delete

​Basic Usage

​Options

​Examples

​Stats

​Basic Usage

​Options

​Examples

​Open

​Options

​Lock Inspection

​Who

​Nudge

​Real-World Examples

​Daily Review

​Archiving Old Content

​Media Library

​Next Steps

Maintenance

Search & Ask

Timeline

Basic Usage

Options

Time-Travel Options

Examples

View

Basic Usage

Selection Options

Output Options

Pagination (Text Content)

Media Playback

Examples

Update

Basic Usage

Selection

Updatable Fields

Examples

Delete

Basic Usage

Options

Examples

Stats

Basic Usage

Options

Examples

Open

Options

Lock Inspection

Who

Nudge

Real-World Examples

Daily Review

Archiving Old Content

Media Library

Next Steps