> ## Documentation Index
> Fetch the complete documentation index at: https://docs.memvid.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Embedded WAL

> Durability guarantees and sizing rules

Memvid 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

1. Serialize the new TOC (after applying pending time entries)
2. Write the TOC into the WAL region and fsync
3. Append the TOC to the end of the file and fsync
4. Update and fsync the header/footer
5. 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: `&lt; 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.