Skip to main content
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: On-demand commands:
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: Fsync policies: Compaction: Over time the AOF grows as it accumulates the full history of writes, including overwritten keys. Compact it to the minimal set of commands needed to reproduce the current live keyspace:
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

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

Store the snapshot and AOF on separate volumes if possible. A disk failure will then affect only one persistence mechanism, not both.