Skip to main content
memvid-core provides APIs for file locking and integrity verification that host applications can use directly.

​
File Locking

Memvid uses OS-level file locks to manage concurrent access: 
use memvid_core::{Memvid, OpenReadOptions};

// Writers get exclusive lock
let mut mv = Memvid::open("notes.mv2")?;

// Readers share the lock
let mv_read = Memvid::open_read_only("notes.mv2")?;

// Optional: allow repair if the file needs recovery (may take an exclusive lock)
let mv_repair = Memvid::open_read_only_with_options(
    "notes.mv2",
    OpenReadOptions { allow_repair: true },
)?;

​
Lock Behavior

  • Writers take an exclusive FileLock
  • Readers share a read lock (multiple concurrent readers allowed)
  • Locks are released when the Memvid handle is dropped

​
Checking Lock Status

CLI commands for inspecting locks: 
# Check who holds the lock
memvid who notes.mv2

# Request the writer to release
memvid nudge notes.mv2

​
Verification

Verify file integrity with the core API: 
use memvid_core::{Memvid, VerificationStatus};

// Basic verification
let report = Memvid::verify("notes.mv2", false)?;

// Deep verification (more thorough)
let report = Memvid::verify("notes.mv2", true)?;

// Check results
if report.overall_status == VerificationStatus::Passed {
    println!("File is valid");
} else {
    for check in &report.checks {
        println!("{}: {:?}", check.name, check.status);
    }
}

​
Verification Checks

The verification report includes:
CheckDescription
TimeIndexReadTime index readable (or skipped if disabled)
TimeIndexEntryCountTrack entry count matches manifest
TimeIndexSortOrderDeep mode: timestamps sorted
LexIndexDecodeLexical index readable (or skipped if disabled)
VecIndexDecodeVector index readable (or skipped if disabled)
WalPendingRecordsNo uncommitted WAL records
FrameCountConsistencyStats match TOC frame count

​
Doctor (Repair)

Repair corrupted or damaged files: 
use memvid_core::{Memvid, DoctorOptions};

// Rebuild time index
Memvid::doctor("notes.mv2", DoctorOptions {
    rebuild_time_index: true,
    ..Default::default()
})?;

// Rebuild lexical index
Memvid::doctor("notes.mv2", DoctorOptions {
    rebuild_lex_index: true,
    ..Default::default()
})?;

// Rebuild vector index
Memvid::doctor("notes.mv2", DoctorOptions {
    rebuild_vec_index: true,
    ..Default::default()
})?;

// Vacuum deleted frames
Memvid::doctor("notes.mv2", DoctorOptions {
    vacuum: true,
    ..Default::default()
})?;

// Full repair
Memvid::doctor("notes.mv2", DoctorOptions {
    rebuild_time_index: true,
    rebuild_lex_index: true,
    rebuild_vec_index: true,
    vacuum: true,
    ..Default::default()
})?;

​
Doctor Report

The doctor command returns a report with:
  • Findings: Issues detected (INFO, WARN, ERROR severity)
  • Planned Actions: Repairs that will be performed
  • Status: Result of each repair action

​
Single-File Verification

Memvid enforces the “single-file guarantee” at open/create time. If it detects sidecars (e.g. notes.mv2-wal), it fails with MemvidError::AuxiliaryFileDetected. 
use memvid_core::{Memvid, MemvidError};

match Memvid::open("notes.mv2") {
    Ok(_mv) => println!("opened successfully"),
    Err(MemvidError::AuxiliaryFileDetected { path }) => {
        eprintln!("auxiliary file detected: {}", path.display());
    }
    Err(err) => eprintln!("open failed: {err}"),
}
For an explicit directory scan, use the CLI command memvid verify-single-file <file>.

​
CLI Commands

The CLI exposes these APIs: 
# Verify integrity
memvid verify notes.mv2 --deep

# Repair issues
memvid doctor notes.mv2 --rebuild-time-index --rebuild-lex-index

# Check single-file compliance
memvid verify-single-file notes.mv2

# Inspect locks
memvid who notes.mv2
memvid nudge notes.mv2

​
Error Handling

The core API exposes structured errors via MemvidError: 
use memvid_core::{Memvid, MemvidError};

match Memvid::open("notes.mv2") {
    Ok(mv) => { /* success */ }
    Err(MemvidError::Locked(locked)) => {
        let pid = locked.owner.as_ref().and_then(|owner| owner.pid);
        println!("File locked (pid={pid:?}): {}", locked.message);
    }
    Err(e) => { /* other error */ }
}

​
Best Practices

​
Concurrent Access

  1. Use read-only mode for queries to allow concurrent readers
  2. Keep write sessions short to minimize lock contention
  3. Handle LockedError gracefully with retry logic

​
Integrity Maintenance

  1. Verify periodically (weekly or after large ingestions)
  2. Run doctor after crashes or power failures
  3. Vacuum after bulk deletions to reclaim space

​
Recovery Workflow

# 1. Verify the file
memvid verify notes.mv2 --deep

# 2. If issues found, preview repairs
memvid doctor notes.mv2 --plan-only

# 3. Apply repairs
memvid doctor notes.mv2 --rebuild-time-index --rebuild-lex-index

# 4. Verify again
memvid verify notes.mv2 --deep