Skip to main contentMemvid embeds its write-ahead log inside the .mv2 file. The Security & Performance Architecture spec defines the sizing tiers:
| File size | WAL region |
|---|
| <100 MB | 1 MB |
| <1 GB | 4 MB |
| <10 GB | 16 MB |
| ≥10 GB | 64 MB |
Commit protocol
- Serialize the new TOC (after applying pending time entries)
- Write the TOC into the WAL region and fsync
- Append the TOC to the end of the file and fsync
- Update and fsync the header/footer
- Truncate/zero the WAL region
EmbeddedWal (defined in memvid-core/src/io/wal.rs) tracks stats such as bytes written and number of checkpoints. Every clean shutdown, seal(), WAL reaching 75 % capacity, or every 1 000 transactions triggers a checkpoint.
Recovery flow
Memvid::open() reads the header, replays WAL entries if present, and validates the TOC checksum before exposing the file. Recovery time targets from the performance spec: < 250 ms even when replaying WAL + TOC.
Developer tip - Use memvid doctor --vacuum (if exposed) or memvid verify --deep to confirm the WAL pointer reset; the Golden Test Pack ensures no phantom WAL bytes survive crashes.
