A "write-once" packfile storage with optimal layout and binary format.
Running Matrix servers on spinning, mechanical drives—made less painful.
- Disk offsets probed in average-case
O(1)time via open-addressed linear probing. - Binary serialization format repacked periodically in topological order, making nominal C2S and federation DB reads purely sequential.
- Stores edge and inverted edge indexes, facilitating near pure sequential segments.
- Records are never rewritten in place. Removing a key appends a versioned removal marker (one-way format addition: older builds refuse to open a store that holds one); space returns at repack.
The storage engine is format-agnostic. Its application-specific mapping policy
is declared by a versioned JSON collection template: record identity, collection
key, payload-retention policy, relationships, and validation behaviour. The Matrix
reference policy is templates/matrix-event-v1.json;
see templates/README.md for the generic format and why
Matrix uses event_id as its logical identity.
The CLI's read-only metadata inspector reports physical storage and durability state without acquiring writer locks:
mtxdb meta [overview|db|wal|checkpoint|delta|sidecars|packs|locks|raw]
The default target is overview. Use --limit and --offset for pagination,
--decode for supported payload decoding, and --json for structured output.
Corrupt headers, truncated tails, stale checkpoints, orphaned delta epochs, and
lock-marker anomalies are reported as diagnostics while inspection continues
where possible.
The process-safety policy for read-only tools and the multi-reader feature is
documented in
docs/docs/2026-09-30-process-safety-and-reader-builds.md.