diff --git a/.openclaw-sync/source.json b/.openclaw-sync/source.json
index 1e035618b..a7d37889e 100644
--- a/.openclaw-sync/source.json
+++ b/.openclaw-sync/source.json
@@ -1,5 +1,5 @@
 {
   "repository": "openclaw/openclaw",
-  "sha": "8adbee3a686aa9bb0907b126fc2b1c0343f44f71",
-  "syncedAt": "2026-05-02T06:31:43.144Z"
+  "sha": "4d9c658f4058576e3356d0ee9d95525563f49ec0",
+  "syncedAt": "2026-05-02T06:37:10.708Z"
 }
diff --git a/docs/reference/session-management-compaction.md b/docs/reference/session-management-compaction.md
index f6f871239..2e8312066 100644
--- a/docs/reference/session-management-compaction.md
+++ b/docs/reference/session-management-compaction.md
@@ -54,6 +54,12 @@ OpenClaw persists sessions in two layers:
      transcript exceeds the checkpoint size cap, avoiding a second giant
      `.checkpoint.*.jsonl` copy.
 
+Gateway history readers should avoid materializing the whole transcript unless
+the surface explicitly needs arbitrary historical access. First-page history,
+embedded chat history, restart recovery, and token/usage checks use bounded tail
+reads. Full transcript scans go through the async transcript index, which is
+cached by file path plus `mtimeMs`/`size` and shared across concurrent readers.
+
 ---
 
 ## On-disk locations