Skip to main content
Commands for maintaining the health and integrity of your memory files.

​
Verify

Check file integrity without modification.

​
Basic Usage

memvid verify knowledge.mv2

​
Options

OptionDescription
--deepRun thorough verification
--jsonOutput as JSON

​
Examples

# Quick verification
memvid verify knowledge.mv2

# Deep verification (slower, more thorough)
memvid verify knowledge.mv2 --deep

# JSON output for automation
memvid verify knowledge.mv2 --deep --json
Output: 
Verifying: knowledge.mv2

Checks:
  [PASS] HeaderChecksum
  [PASS] TocIntegrity
  [PASS] WalConsistency
  [PASS] TimeIndexSortOrder
  [PASS] LexIndexDecode
  [PASS] VecIndexDecode
  [PASS] FrameCountConsistency

Overall: PASSED
JSON Output: 
{
  "file_path": "knowledge.mv2",
  "checks": [
    { "name": "HeaderChecksum", "status": "passed" },
    { "name": "TocIntegrity", "status": "passed" },
    { "name": "WalConsistency", "status": "passed" },
    { "name": "TimeIndexSortOrder", "status": "passed" },
    { "name": "LexIndexDecode", "status": "passed" },
    { "name": "VecIndexDecode", "status": "passed" },
    { "name": "FrameCountConsistency", "status": "passed" }
  ],
  "overall_status": "passed"
}

​
Exit Codes

  • 0 - All checks passed
  • Non-zero - One or more checks failed

​
Doctor

Diagnose and repair issues with memory files.

​
Basic Usage

memvid doctor knowledge.mv2

​
Options

OptionDescription
--plan-onlyPreview repairs without applying
--rebuild-time-indexRebuild the time index
--rebuild-lex-indexRebuild the lexical index
--rebuild-vec-indexRebuild the vector index
--vacuumCompact and reclaim deleted space
--jsonOutput as JSON

​
Examples

# Preview what would be fixed
memvid doctor knowledge.mv2 --plan-only

# Rebuild corrupted time index
memvid doctor knowledge.mv2 --rebuild-time-index

# Rebuild lexical index
memvid doctor knowledge.mv2 --rebuild-lex-index

# Rebuild vector index
memvid doctor knowledge.mv2 --rebuild-vec-index

# Compact deleted frames and reclaim space
memvid doctor knowledge.mv2 --vacuum

# Fix multiple issues at once
memvid doctor knowledge.mv2 --rebuild-time-index --rebuild-lex-index

# Full repair and optimization
memvid doctor knowledge.mv2 \
  --rebuild-time-index \
  --rebuild-lex-index \
  --rebuild-vec-index \
  --vacuum
Output: 
Doctor Report: knowledge.mv2

Findings:
  [WARN] Time index has 3 out-of-order entries
  [INFO] 12 deleted frames can be vacuumed

Planned Actions:
  1. Rebuild time index
  2. Vacuum deleted frames

Executing repairs...
  [DONE] Time index rebuilt (148 entries)
  [DONE] Vacuumed 12 frames, reclaimed 2.3 MB

Complete.

​
Severity Levels

LevelDescription
INFOInformational, no action needed
WARNPotential issue, repair recommended
ERRORProblem found, repair required

​
Verify Single File

Ensure no auxiliary files exist alongside your memory file.

​
Basic Usage

memvid verify-single-file knowledge.mv2
This checks that the directory contains only the .mv2 file with no leftover sidecars:
  • No .wal files
  • No .shm files
  • No .lock files
  • No -wal files
  • No hidden siblings

​
Example

$ memvid verify-single-file knowledge.mv2
Single-file check: PASSED
No auxiliary files found.
If sidecars are found: 
$ memvid verify-single-file knowledge.mv2
Single-file check: FAILED
Found auxiliary files:
  - knowledge.mv2-wal
  - knowledge.mv2.lock

Remove these files and re-verify.

​
Common Maintenance Tasks

​
After Crashes

If your application crashed while writing: 
# Verify integrity
memvid verify knowledge.mv2 --deep

# If issues found, run doctor
memvid doctor knowledge.mv2 --plan-only

# Apply repairs if needed
memvid doctor knowledge.mv2 --rebuild-time-index

​
Reclaiming Space

After deleting many frames: 
# Check current stats
memvid stats knowledge.mv2

# Vacuum to reclaim space
memvid doctor knowledge.mv2 --vacuum

# Verify results
memvid stats knowledge.mv2

​
Rebuilding Indices

If search isn’t working correctly: 
# Check index status
memvid stats knowledge.mv2 --json | grep has_lex_index

# Rebuild lexical index
memvid doctor knowledge.mv2 --rebuild-lex-index

# Rebuild vector index
memvid doctor knowledge.mv2 --rebuild-vec-index

# Verify search works
memvid find knowledge.mv2 --query "test"

​
Cleaning Up Old Files

Remove leftover files from older versions: 
# Check for sidecars
ls -la knowledge.mv2*

# Remove any found
rm -f knowledge.mv2-wal knowledge.mv2-shm knowledge.mv2.lock

# Verify clean state
memvid verify-single-file knowledge.mv2

​
Environment Variables

VariableDescriptionDefault
MEMVID_MODELS_DIRModel cache directory~/.memvid/models
MEMVID_CACHE_DIRGeneral cache directory~/.cache/memvid
MEMVID_OFFLINESkip model downloadsfalse
MEMVID_PARALLEL_SEGMENTSControl parallel ingestionAuto

​
Setting Environment Variables

# Set model directory
export MEMVID_MODELS_DIR=~/.memvid/models

# Enable offline mode
export MEMVID_OFFLINE=1

# Enable parallel ingestion
export MEMVID_PARALLEL_SEGMENTS=1

​
Debug Commands

​
Version

Check CLI version: 
memvid version

​
Debug Segment

Inspect internal vector segment data (advanced): 
# View segment metadata
memvid debug-segment knowledge.mv2 --segment-id 1

# Include hex dump
memvid debug-segment knowledge.mv2 --segment-id 1 --hex-dump --max-bytes 512

​
Verbose Output

Enable debug logging: 
# Increase verbosity
memvid -v verify knowledge.mv2       # WARN level
memvid -vv verify knowledge.mv2      # INFO level
memvid -vvv verify knowledge.mv2     # DEBUG level
memvid -vvvv verify knowledge.mv2    # TRACE level

​
Troubleshooting

​
Time Index Corruption

Symptom: 
TimeIndexSortOrder: Failed
Solution: 
memvid doctor knowledge.mv2 --rebuild-time-index
memvid verify knowledge.mv2 --deep

​
Lexical Index Issues

Symptom:
  • Search returns no results
  • has_lex_index: false in stats
Solution: 
memvid doctor knowledge.mv2 --rebuild-lex-index

​
Vector Index Issues

Symptom:
  • Semantic search not working
  • has_vec_index: false in stats
Solution: 
memvid doctor knowledge.mv2 --rebuild-vec-index

​
Capacity Issues

Symptom: 
Error: CapacityExceeded
Solutions: 
# Check current usage
memvid stats knowledge.mv2

# Delete unused frames
memvid delete knowledge.mv2 --frame-id 42 --yes

# Vacuum to reclaim space
memvid doctor knowledge.mv2 --vacuum

​
Lock Issues

Symptom: 
Error: File is locked by another process
Solutions: 
# Check who holds the lock
memvid who knowledge.mv2

# Request release
memvid nudge knowledge.mv2

# Find process (macOS/Linux)
lsof knowledge.mv2

​
Best Practices

​
Regular Maintenance

  1. Verify periodically: Run memvid verify --deep weekly or after major ingestion
  2. Vacuum after deletions: Run --vacuum after deleting significant content
  3. Monitor capacity: Check memvid stats before large ingestions

​
Before Sharing Files

  1. Verify integrity: memvid verify knowledge.mv2 --deep
  2. Check single-file: memvid verify-single-file knowledge.mv2
  3. Review stats: memvid stats knowledge.mv2

​
After System Updates

  1. Verify existing files still work
  2. Rebuild indices if search behaves differently
  3. Check for any deprecated features

​
Next Steps

Create & Ingest

Add more content to your memories

Search & Ask

Query your memories