diff --git a/docs/cli.md b/docs/cli.md
index 033faa5a..416c4d4f 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -173,6 +173,8 @@ Reduce disk usage by optimizing and pruning old table versions across all tables
 haiku-rag vacuum
 ```
 
+**Automatic Cleanup:** Vacuum runs automatically in the background after document operations. By default, it removes versions older than 60 seconds (`VACUUM_RETENTION_SECONDS`), preserving recent versions for concurrent connections. Manual vacuum can be useful for cleanup after bulk operations or to free disk space immediately.
+
 ### Rebuild Database
 
 Rebuild the database by deleting all chunks & embeddings and re-indexing all documents. This is useful
diff --git a/docs/configuration.md b/docs/configuration.md
index 9094052a..631899ae 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -232,6 +232,12 @@ CHUNK_SIZE=256
 # When expanded chunks overlap or are adjacent, they are automatically merged
 # into single chunks with continuous content to eliminate duplication
 CONTEXT_CHUNK_RADIUS=0
+
+# Vacuum retention threshold (seconds) for automatic cleanup
+# When documents are added/updated, old table versions older than this are removed
+# Default: 60 seconds (safe for concurrent connections)
+# Set to 0 for aggressive cleanup (removes all old versions immediately)
+VACUUM_RETENTION_SECONDS=60
 ```
 
 #### Markdown Preprocessor