Maintenance & Repair

Commands for maintaining the health and integrity of your memory files.

Verify

Check file integrity without modification.

Basic Usage

memvid verify knowledge.mv2

Options

Option	Description
`--deep`	Run thorough verification
`--json`	Output 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

Option	Description
`--plan-only`	Preview repairs without applying
`--rebuild-time-index`	Rebuild the time index
`--rebuild-lex-index`	Rebuild the lexical index
`--rebuild-vec-index`	Rebuild the vector index
`--vacuum`	Compact and reclaim deleted space
`--json`	Output 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

Level	Description
`INFO`	Informational, no action needed
`WARN`	Potential issue, repair recommended
`ERROR`	Problem 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

Variable	Description	Default
`MEMVID_MODELS_DIR`	Model cache directory	`~/.memvid/models`
`MEMVID_CACHE_DIR`	General cache directory	`~/.cache/memvid`
`MEMVID_OFFLINE`	Skip model downloads	`false`
`MEMVID_PARALLEL_SEGMENTS`	Control parallel ingestion	Auto

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

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

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

After System Updates

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

Next Steps

Create & Ingest

Add more content to your memories

Search & Ask

Query your memories

​Verify

​Basic Usage

​Options

​Examples

​Exit Codes

​Doctor

​Basic Usage

​Options

​Examples

​Severity Levels

​Verify Single File

​Basic Usage

​Example

​Common Maintenance Tasks

​After Crashes

​Reclaiming Space

​Rebuilding Indices

​Cleaning Up Old Files

​Environment Variables

​Setting Environment Variables

​Debug Commands

​Version

​Debug Segment

​Verbose Output

​Troubleshooting

​Time Index Corruption

​Lexical Index Issues

​Vector Index Issues

​Capacity Issues

​Lock Issues

​Best Practices

​Regular Maintenance

​Before Sharing Files

​After System Updates

​Next Steps

Create & Ingest

Search & Ask

Verify

Basic Usage

Options

Examples

Exit Codes

Doctor

Basic Usage

Options

Examples

Severity Levels

Verify Single File

Basic Usage

Example

Common Maintenance Tasks

After Crashes

Reclaiming Space

Rebuilding Indices

Cleaning Up Old Files

Environment Variables

Setting Environment Variables

Debug Commands

Version

Debug Segment

Verbose Output

Troubleshooting

Time Index Corruption

Lexical Index Issues

Vector Index Issues

Capacity Issues

Lock Issues

Best Practices

Regular Maintenance

Before Sharing Files

After System Updates

Next Steps