By default, Cache-Pot is a pure in-memory store — the entire keyspace lives in RAM and is gone if the process exits. Persistence is opt-in, and Cache-Pot offers two complementary mechanisms you can enable independently or together: periodic snapshots that checkpoint the full keyspace to disk, and an append-only file (AOF) that logs every write command so you can replay it on startup. Enabling both gives you the strongest durability guarantees.
Snapshots
A snapshot is a complete, point-in-time copy of the keyspace written to a single file. Cache-Pot serialises all keys and values, writes the bytes to a temporary file, and then atomically renames that file into place — so you never see a half-written snapshot.
Snapshots run automatically on a configurable interval and once more during graceful shutdown (on SIGINT or SIGTERM). On the next startup, Cache-Pot loads the snapshot file before accepting connections.
Configuration flags:
| Flag | Default | Description |
|---|
--snapshot-path | cache-pot.snapshot | Path to the snapshot file. Set to an empty string to disable snapshots entirely. |
--snapshot-interval | 60s | How often to write a periodic snapshot. |
SAVE # Write a snapshot synchronously — blocks until done
BGSAVE # Write a snapshot (same behaviour in this release)
Set --snapshot-path "" to run Cache-Pot as a purely ephemeral cache with no disk activity.
Append-Only File (AOF)
The AOF records every write command as a RESP-encoded array, appended to a log file. On startup, Cache-Pot replays the log through the normal command-dispatch table to reconstruct the keyspace — no special restore logic needed.
Two important details make AOF replay safe and idempotent:
- Relative TTLs are normalised. Commands like
EXPIRE key 60 or SET key val EX 300 are logged as absolute PEXPIREAT deadlines, so replay produces the same expiry regardless of when it happens.
SCACHE.SET is logged as its resulting VSET. Replaying a semantic-cache write never re-calls the embeddings API; the already-computed vector is logged directly.
If the process crashes mid-write, the truncated tail of the AOF is detected automatically and trimmed away on next startup.
Configuration flags:
| Flag | Default | Description |
|---|
--aof-path | (not set) | Path to the AOF file. AOF is disabled when not set. |
--aof-fsync | everysec | Fsync policy: always, everysec, or no. |
| Policy | Durability | Performance |
|---|
always | At most one command lost on crash | Slowest |
everysec | At most ~1 second of writes lost | Balanced (recommended) |
no | OS decides when to flush | Fastest, least durable |
BGREWRITEAOF # Compact the AOF to the minimal live-keyspace command set
A compaction also runs automatically on graceful shutdown when --aof-path is set.
AOF vs. snapshot priority
When both mechanisms are enabled and the AOF file is non-empty, Cache-Pot treats the AOF as the authoritative dataset at startup and ignores the snapshot. The snapshot is still useful as a fast-load fallback if you ever disable the AOF.
Choosing a persistence mode
| Mode | Durability | Startup time | Use when |
|---|
| None | None — all data lost on exit | Instant | Ephemeral cache, dev/test only |
| Snapshot only | Up to one snapshot interval of data loss (default 60 s) | Fast | Low-write workloads where some loss is acceptable |
| AOF only | ~1 s data loss with everysec fsync | Slower on large datasets | High-durability needs without snapshot overhead |
| Both | Best — AOF takes priority; snapshot provides fast fallback | AOF replayed at startup | Production deployments |
AOF replay can be slow on very large datasets because every logged command is re-executed through the dispatch table. If fast restarts matter, keep snapshots enabled so you can fall back to them by removing the AOF file.
Example: enabling both mechanisms
cache-pot serve \
--snapshot-path /var/lib/cache-pot/snapshot \
--snapshot-interval 30s \
--aof-path /var/lib/cache-pot/appendonly.aof \
--aof-fsync everysec
Store the snapshot and AOF on separate volumes if possible. A disk failure will then affect only one persistence mechanism, not both.
