diff --git a/README.md b/README.md
index f1b00ce..98687df 100644
--- a/README.md
+++ b/README.md
@@ -109,6 +109,22 @@ Get a free key from your [NCBI account](https://www.ncbi.nlm.nih.gov/account/) 
 
 ---
 
+## Local state
+
+Pinakes stores its content-addressed snapshots and reproducibility manifests under your OS cache
+directory by default — `~/Library/Caches/pinakes` on macOS, `$XDG_CACHE_HOME/pinakes` (else
+`~/.cache/pinakes`) on Linux. It is created on first use; back it up or clear it like any cache.
+Relocate it with `PINAKES_STATE_ROOT`:
+
+```sh
+export PINAKES_STATE_ROOT=/path/to/pinakes-state   # where the local snapshot store lives
+```
+
+Everything stays local: a pinned query and its `pinakes verify` re-run read this directory with
+**no network access**.
+
+---
+
 ## Why Pinakes
 
 Three guarantees, none of which a raw API call or a typical MCP wrapper gives you: