From 4d965414b6074a28f18e5ba1871211d490999d3d Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sun, 19 Jul 2026 22:24:09 +0800
Subject: [PATCH] docs(goal): describe cache effect

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

diff --git a/packages/goal/goal/README.md b/packages/goal/goal/README.md
index 57f366c844..b59536ee1f 100644
--- a/packages/goal/goal/README.md
+++ b/packages/goal/goal/README.md
@@ -33,9 +33,17 @@ Policy plugins call the service verbs and react to the scoped `goal/changed` eve
 
 ### Goal-state mutation
 
-**What the model sees**: Each mutation is one raw user-role context block. A snapshot is rendered as `<goal_state>{"goal":...,"roundsStarted":...,"createdAt":...,"updatedAt":...}</goal_state>`; a clear renders the tombstone id/revision and `clearedAt`. There is no hidden state summary outside the log.
+#### What the model sees
 
-**Token effect**: Every retained mutation adds one full snapshot to derived history until compaction shadows it. Full snapshots make each record independently inspectable but repeat the objective and lifecycle fields.
+Each mutation is one raw user-role context block. A snapshot is rendered as `<goal_state>{"goal":...,"roundsStarted":...,"createdAt":...,"updatedAt":...}</goal_state>`; a clear renders the tombstone id/revision and `clearedAt`. There is no hidden state summary outside the log.
+
+#### Token effect
+
+Every retained mutation adds one full snapshot to derived history until compaction shadows it. Full snapshots make each record independently inspectable but repeat the objective and lifecycle fields.
+
+#### KV Cache effect
+
+Append-only within an epoch: each mutation follows the reusable request prefix and preceding history. Compaction may replace the derived-history suffix and move the reusable boundary.
 
 ## Known Limitations and Deferred Work