Designing a Repeated-Wake Digest Strategy
Learning Headroom
From Layout to Strategy: Designing the Digest
Recall from 2.3 — Stable-Prefix and Live-Zone Layout:
- Byte-stable prefix first (instructions, rules, tool contracts)
- Volatile wake digest next
- Run-specific context (tool output, loop state) last
That answered: **where** does volatile content live?
Today's question: **what exactly belongs in that digest, and how should each field be encoded?**
**Every wake carries four layers**
- 1. Stable instructions, project rules, tool contracts
- 2. Current task + instruction-bearing fields
- 3. Volatile per-wake memory digest
- 4. Recent loop state, tool output, child-agent context
Layer 1 stays byte-identical. Layers 2–4 are what a digest schema must organize.
Where this leads → 7.2 End-to-End Headroom Tuning Playbook uses this schema as one lever in the full tuning workflow.
The Digest Schema: Five Design Decisions
**Digest schema design**
For every field in the wake digest, decide: (1) Partition — stable prefix or live tail? (2) Encoding — verbatim, compact summary, or dropped? (3) Backing — does a summary need a retrievable full version, i.e. CCR? (4) Lifetime — how long must the stored/backing version live, i.e. TTL?
```mermaid
flowchart LR
F["Field in the digest"] --> P{"Stable or live-tail?"}
P -->|Stable| PRE["Goes in prefix"]
P -->|Live| ENC{"How much exact wording needed?"}
ENC -->|All of it, instruction-bearing| VERB["Verbatim"]
ENC -->|Gist is enough| SUM["Compact summary"]
SUM --> BACK{"Might need the original later?"}
BACK -->|Yes| CCR["CCR-backed detail"]
BACK -->|No| DONE["Summary only"]
CCR --> TTL["Set store lifetime"]
```
Builds on ← 5.2 Instruction-Bearing Content Routing: the verbatim-vs-summary branch is that same routing question, applied to digest fields.
Builds on ← 5.4 CCR Lifetime and Retrieval Failure Handling: the TTL step reuses that lifetime logic — pick too short and retrieval fails later.
Field-by-Field Routing Table
**Field-by-field routing**
- Current task — Verbatim — instruction-bearing, drives next action
- Hard constraints — Verbatim — safety/acceptance boundary, no paraphrase risk
- Definitions of done — Verbatim — wording must survive every wake intact
- Irreversible decisions — Verbatim summary + CCR-backed detail — summary stays short, exact record stays recoverable
- Open threads — Compact summary + CCR-backed detail — thread can shrink, source stays recoverable if reopened
- Learnings — Compact summary — informs next wake without needing exact prose
- File/search/tool outputs — CCR-backed compression — large backing detail, rarely re-read in full
- Prose notes — Compact summary, CCR-backed if bulky — keeps digest readable, doesn't lose source
- Bulk JSON-ish arrays — SmartCrusher/ContentRouter + CCR-backed detail — first thing to explode in size
Why verbatim for task/constraints/DoD? Paraphrasing an instruction risks silently changing its meaning — a rewritten "must" can drift into "should."
Why summary+CCR for threads/decisions? You need the digest small every wake, but you can't afford to lose the one wake where the exact reasoning mattered.
Worked Example: Building a Digest for a Coding Agent
**Digest for a multi-day refactor agent**
Scenario: a coding agent wakes every 10 minutes to keep working on a multi-day refactor task. At this wake it holds six raw fields:
1. Task: "Migrate auth module to new session API; must not break existing tests."
2. Constraint: "Never delete files outside /src/auth."
3. Decision made 3 wakes ago: "Chose to keep the old token format for backward compat" (200-word rationale).
4. Open thread: "Investigating why 2 tests flake on CI" (400-word debug log so far).
5. Learning: "The mock server ignores query params, so param-based tests always pass."
6. Last tool output: full 3,000-line test run log.
Routing each field through the schema:
| # | Field | Partition | Encoding | Backing | TTL |
|---|---|---|---|---|---|
| 1 | Task | Live tail | Verbatim (28 words) | none | session-length |
| 2 | Constraint | Live tail | Verbatim (9 words) | none | session-length |
| 3 | Decision | Live tail | Verbatim summary (12 words) | CCR-backed 200-word rationale | until task closes |
| 4 | Open thread | Live tail | Compact summary (15 words) | CCR-backed 400-word log | short, refreshed each wake |
| 5 | Learning | Live tail | Compact summary (18 words) | none | session-length |
| 6 | Tool output | Live tail (tail-of-tail) | Dropped from digest text | CCR-backed full log | short, superseded next run |
Result: every row keeps the digest small every wake, and nothing that mattered was thrown away — it's either kept verbatim or parked behind CCR.
Picking the TTL: Why Lifetime Must Match the Field's Job
**TTL alignment** — the store lifetime for a CCR-backed field should match how long the *summary* might need to reach back to it.
Ask two questions:
1. How long could a future wake plausibly need this backing detail?
2. What happens if retrieval fails after expiry? (Recall 5.4: expired backing detail becomes unretrievable, and the caller must handle that gracefully, not crash.)
```mermaid
flowchart TD
A["CCR-backed field"] --> Q1{"Could a future wake need the full detail?"}
Q1 -->|Only this wake, superseded next run| SHORT["Short TTL: e.g. tool output logs"]
Q1 -->|Until the task/decision closes| MED["Medium TTL: e.g. irreversible decisions"]
Q1 -->|Rarely, but high cost if lost| LONG["Long TTL: e.g. compliance-relevant records"]
SHORT --> R["Expired? Retrieval-failure path handles it gracefully"]
MED --> R
LONG --> R
```
Common mismatch: setting every CCR field to one global TTL. A tool-output log kept for a week wastes store space; an irreversible-decision rationale expiring in an hour breaks the summary the moment someone asks "why did we do that?"
Edge Cases and What Can Go Wrong
Misroute risk 1 — summarizing an instruction-bearing field. Paraphrasing "must not break existing tests" into a summary can silently drop the "must." Test: if rewording could change what the agent does next, it belongs in verbatim, not summary.
Misroute risk 2 — summary with no backing. An irreversible decision summarized with no CCR backing loses the rationale forever. If it's ever questioned later, there's nothing to retrieve. Test: could losing the original ever matter? If yes, back it.
Misroute risk 3 — TTL shorter than the summary's reach. An open-thread summary that says "see investigation log" is useless once that log has expired. The retrieval-failure path from 5.4 kicks in, but that's a fallback, not a design goal.
Misroute risk 4 — everything dumped into the live tail unpartitioned. If stable rules and the volatile digest aren't separated (2.3), every wake invalidates the cache prefix — headroom savings vanish even if the digest itself is well designed.
**Checklist for a passing schema**
- Stable vs. live-tail partition assigned to every field
- Verbatim reserved for instruction-bearing fields only
- Summaries used where gist suffices
- CCR backing attached wherever the original could matter later
- TTL matches each field's actual useful lifespan
بازگشت به دوره