> ## Documentation Index
> Fetch the complete documentation index at: https://cache-pot.thatdevguy.in/llms.txt
> Use this file to discover all available pages before exploring further.

# Persistence in Cache-Pot: snapshots and append-only file

> Cache-Pot offers two durability modes: periodic snapshots and an append-only file (AOF). Enable either or both to keep your data safe across restarts.

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.                                          |

**On-demand commands:**

```bash theme={null}
SAVE      # Write a snapshot synchronously — blocks until done
BGSAVE    # Write a snapshot (same behaviour in this release)
```

<Note>
  Set `--snapshot-path ""` to run Cache-Pot as a purely ephemeral cache with no disk activity.
</Note>

***

## 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`.        |

**Fsync policies:**

| 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 |

**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:

```bash theme={null}
BGREWRITEAOF   # Compact the AOF to the minimal live-keyspace command set
```

<Note>
  A compaction also runs automatically on graceful shutdown when `--aof-path` is set.
</Note>

### 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                            |

<Warning>
  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.
</Warning>

***

## Example: enabling both mechanisms

```bash theme={null}
cache-pot serve \
  --snapshot-path /var/lib/cache-pot/snapshot \
  --snapshot-interval 30s \
  --aof-path /var/lib/cache-pot/appendonly.aof \
  --aof-fsync everysec
```

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