What it does
The engine periodically writes a checkpoint of its in-memory state: a full base file plus small delta files that hold just what changed. On start-up it loads the checkpoint chain and replays the log above it. A damaged checkpoint is never trusted; the engine falls back to the log.
How it works
A base checkpoint is a full snapshot written with a temporary file and an atomic rename. Between bases the engine writes delta checkpoints, each holding the entities that changed or were deleted since the previous checkpoint, so the cost of a delta follows the amount of change rather than the size of the data. When the delta count crosses a threshold of eight, the chain is folded into a fresh base. The default cadence is one checkpoint every 10,000 writes and can be changed with KYNETRA_CHECKPOINT_EVERY.
On start-up the engine loads the base, checks the CRC of every delta, and follows the chain by explicit links: each delta records the sequence number of the checkpoint it was computed against. A delta whose predecessor is missing or damaged is not applied, even if its own checksum is valid, because applying it would silently skip whatever the missing one held. Anything the chain does not cover is still in the log, which checkpointing never removes, so the engine replays it. Tests corrupt a delta file and a base checkpoint and check that the engine falls back to log replay without data loss.
A checkpoint that claims to be ahead of the log is rejected and deleted at open. The search and vector index snapshots follow the same rule as checkpoints: they are never stamped above the flushed log position, and tests check that the index watermark never exceeds the data watermark.
Operators can read checkpoint posture and force a checkpoint. GET /admin/checkpoint reports the profile, the checkpoint sequence, the next log sequence, the durable next sequence and how many records a restart would replay. POST /admin/checkpoint writes one immediately and returns its sequence. Both need an administrator, and the force is refused while the engine is recovery-uncertain.
Measured: one million entities resident in 7,514 MB of RSS — about 7,874 bytes per entity — loading in 40.6 s and booting from checkpoint in 14.2 s. This is local scope, one host (Apple M5, 32 GB RAM). It is stage A of a memory-ceiling suite on one host with 32 GB of RAM; the artifact also extrapolates a ceiling for a smaller host, and that extrapolation is arithmetic, not a measurement, so it is not published here.
Where you reach it
- HTTP
GET /admin/checkpoint (posture), POST /admin/checkpoint (force one) - Config
KYNETRA_CHECKPOINT_EVERY (writes between checkpoints, 10000 by default)
Limits
- Checkpoints do not shorten or remove the log. Log files stay on disk.
- The server holds entity values in memory. Capacity on one host is bounded by RAM, and restart time includes loading that state.
- The columnar checkpoint format and the disk-resident entity profile exist in the engine library but are not selectable in the server.
Evidence
- ArtifactMemory-ceiling stage A artifact (local scope, one host)
- On this siteReliability
- TestsCovered in the engine repository by 14 checkpoint tests (delta chains, compaction, corrupt delta and corrupt base fallbacks, WAL tail across restarts), 7 incremental-index tests, and 7 restore-and-checkpoint consistency tests
Test coverage is listed as present in the engine repository at this edition. This page does not report test results.
Every figure on this site is local-scope: one host, one operator, no third-party reproduction. Artifacts are linked next to each number, and gates that were missed are published beside the gates that were met.
KynetraDB is in private preview
Request a preview to try this against your own workload.