perf: preserve conversation prefixes across agent turns

artemis/config/agent.py

@@ -425,7 +425,7 @@ class MemoryRuntimeConfig(BaseModel):
 
 
 class MemoryTranscriptConfig(BaseModel):
-    """Scrub-edge options for the message transcript (agent.memory.transcript)."""
+    """Phased context compaction for the shared Flash/Pro transcript."""
 
     enabled: bool = Field(
         default=True,
@@ -443,7 +443,7 @@ class MemoryTranscriptConfig(BaseModel):
         default=3,
         ge=1,
         description=(
-            "Depth K of the screenshot scrub edge from the start gate up: the"
+            "At a compaction boundary, depth K of the screenshot scrub edge: the"
             " K-th most recent screenshot (the live one counts as depth 1) is"
             " replaced by its visual summary."
         ),
@@ -452,11 +452,9 @@ class MemoryTranscriptConfig(BaseModel):
         default=6,
         ge=1,
         description=(
-            "Screenshot scrub depth while the operator's measured context is"
-            " below budget*start_ratio (nothing is being replaced yet, so"
-            " more raw screenshots stay in view). Must be >= image_scrub_depth;"
-            " set equal to it to disable the occupancy-driven depth. A change"
-            " of depth never rewrites an already-scrubbed message."
+            "Screenshot depth for an explicit low-occupancy compaction. Normal"
+            " turns retain previously sent images unchanged. Must be >="
+            " image_scrub_depth."
         ),
     )
     pending_grace_steps: int = Field(
@@ -472,13 +470,10 @@ class MemoryTranscriptConfig(BaseModel):
         default=1,
         ge=1,
         description=(
-            "Text edge of the scrub: once a message is deeper than this many"
-            " image-bearing observations (1 = as soon as a newer observation"
-            " exists) its UI element list, plan recitation and per-turn"
-            " ephemeral blocks are removed. Kept shallow on purpose: only the"
-            " live observation carries an indexed element list, so a stale"
-            " [n] index can never be picked up as a target. Screenshots follow"
-            " image_scrub_depth / image_scrub_depth_relaxed."
+            "At phase compaction, remove old UI lists, plan recitations and"
+            " ephemeral notices beyond this observation depth. Between phases"
+            " old content stays immutable; only the latest observation may"
+            " supply current action targets."
         ),
     )
     context_budget_tokens: int = Field(
@@ -496,12 +491,9 @@ class MemoryTranscriptConfig(BaseModel):
         ge=0.0,
         lt=1.0,
         description=(
-            "Start gate: below budget*start_ratio of the operator's measured"
-            " prompt size, closed segments only prepare their capsule in the"
-            " background — the original turns stay in the transcript. Ready"
-            " chunks replace their turns once the measured context reaches"
-            " this ratio (the hard threshold overrides it). 0 restores"
-            " swap-as-soon-as-ready."
+            "Preparation gate: at budget*start_ratio begin background chunk"
+            " summaries without replacing the live prefix. Zero enables early"
+            " preparation, not immediate replacement. Swaps wait for soft_ratio."
         ),
     )
     soft_ratio: float = Field(
@@ -509,9 +501,9 @@ class MemoryTranscriptConfig(BaseModel):
         gt=0.0,
         lt=1.0,
         description=(
-            "Soft threshold: when the operator's last measured prompt size"
-            " reaches budget*soft_ratio, the oldest open segment is"
-            " chunk-compressed (L2)."
+            "At budget*soft_ratio, replace prepared summaries as one batch and"
+            " scrub old observations, starting a new stable context phase."
+            " Pending summaries retain original turns until ready or hard pressure."
         ),
     )
     hard_ratio: float = Field(
@@ -519,7 +511,7 @@ class MemoryTranscriptConfig(BaseModel):
         gt=0.0,
         le=1.0,
         description=(
-            "Hard threshold: when the operator's last measured prompt size"
+            "Hard threshold: when the projected current prompt size"
             " reaches budget*hard_ratio, ready chunks swap as L2 blocks first;"
             " only if that would not bring the estimated context back under the"
             " line does everything closed force-swap (pending chunks included)"