From 34fe1677757649be9fcbb93495c98944acab6c23 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sun, 19 Jul 2026 22:34:03 +0800
Subject: [PATCH] docs(goal): describe round cache behavior

---
 packages/goal/goal-session/README.md | 12 ++++++++++--
 1 file changed, 10 insertions(+), 2 deletions(-)

diff --git a/packages/goal/goal-session/README.md b/packages/goal/goal-session/README.md
index 0a73cfb75d..e0e74f749f 100644
--- a/packages/goal/goal-session/README.md
+++ b/packages/goal/goal-session/README.md
@@ -49,9 +49,17 @@ Cancellation is observe-before-act: the concrete loop emits `agent/cancel-reques
 
 ### Goal-round prompt
 
-**What the model sees**: Each admitted round is one retained user-role `<goal_round>` block naming the full objective and positive round number. Earlier human messages, goal-state snapshots, assistant output, and tool records remain in the same session history.
+#### What the model sees
 
-**Token effect**: One fixed instruction block plus the objective is added per admitted round. Later requests resend retained rounds until compaction shadows them; no fresh agent or copied conversation prefix is created.
+Each admitted round is one retained user-role `<goal_round>` block naming the full objective and positive round number. Earlier human messages, goal-state snapshots, assistant output, and tool records remain in the same session history.
+
+#### Token effect
+
+One fixed instruction block plus the objective is added per admitted round. Later requests resend retained rounds until compaction shadows them; no fresh agent or copied conversation prefix is created.
+
+#### KV Cache effect
+
+Append-only within an epoch: each admitted round extends the existing conversation after its reusable prefix. Compaction may replace the derived-history suffix and move the reusable boundary.
 
 ## Known Limitations and Deferred Work