Skip to main content
Commands for inspecting and navigating your memory files.

​
Timeline

Browse documents chronologically using the time index.

​
Basic Usage

memvid timeline knowledge.mv2

​
Options

OptionDescriptionDefault
--limitMaximum entries to return50
--sinceStart timestamp (Unix)None
--untilEnd timestamp (Unix)None
--on <PHRASE>Temporal phrase filter (e.g., “last week”)None
--tz <ZONE>Timezone for temporal phrasesAmerica/Chicago
--anchor <RFC3339>Anchor date for resolutionNow
--reverseReverse chronological orderfalse
--jsonOutput as JSONfalse

​
Time-Travel Options

OptionDescription
--as-of-frame IDView timeline as of frame ID
--as-of-ts TIMESTAMPView 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

OptionDescription
--frame-id IDDocument ID to view
--uri URIDocument URI to view

​
Output Options

OptionDescription
--jsonOutput as JSON
--binaryRaw binary output
--previewPreview mode (for media)
--playPlay/stream mode (for audio/video)

​
Pagination (Text Content)

OptionDescriptionDefault
--page NPage number1
--page-sizeCharacters per pageAuto

​
Media Playback

OptionDescription
--preview-start HH:MM:SSVideo preview start time
--preview-end HH:MM:SSVideo preview end time
--start-secondsPlayback start (with —play)
--end-secondsPlayback 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

OptionDescription
--frame-id IDFrame ID to update
--uri URIFrame URI to update

​
Updatable Fields

OptionDescription
--set-uri URIChange the URI
--title TITLEUpdate title
--timestamp TSUpdate timestamp
--track TRACKUpdate track
--kind KINDUpdate kind
--tag KEY=VALUEAdd/update tags
--label LABELAdd labels
--metadata JSONAdd metadata
--input PATHReplace payload
--vector-compressionRecompute 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

OptionDescription
--frame-id IDFrame ID to delete
--uri URIFrame URI to delete
--yesSkip confirmation prompt
--jsonJSON 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

OptionDescription
--jsonOutput 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

OptionDescription
--jsonOutput 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

​
Next Steps

Maintenance

Repair files and verify integrity

Search & Ask

Query your memories