looprig
doc
LR-WWW-001
rev
B
date
2026-07-15
sheet
1 of 1
Skip to documentation
Documentation navigation

Documentation navigation

Documentation / guides

Overview

Count complete model context and replace an older transcript prefix with a validated summary.

developer

Compaction measures the complete model request and, at a safe Loop boundary, replaces an older transcript prefix with one validated user-message summary. The attempt carries a context basis, model identity, and request fingerprint so the summary cannot be committed against a different conversation.

How it works

Harness resolves context limits after reserved output and safety margin, counts the complete request with the configured context counter, and records a ContextMeasurement. CompactionPolicy decides whether automatic pressure is eligible. A registered blocking current-Loop Hustle receives the exact loop.CompactionInput; Harness validates its identity and summary shape before durably replacing the prefix.

%%{init: {"theme":"dark"}}%%
flowchart LR
    M[complete request measurement] --> P{policy and pressure}
    P -->|manual or automatic at boundary| S[CompactionStarted]
    S --> H[registered blocking compaction Hustle]
    H --> V[identity, XML, bytes, tokens, post-count]
    V -->|valid| C[CompactionCommitted]
    V -->|invalid or unavailable| R[CompactionRejected]
    C --> W[waiter resolved replies]
    R --> X[waiter rejected replies]

Proof: context measurement and tracking and live compaction tests.

Configure compaction

assistant, err := loop.Define(
	loop.WithName("assistant"),
	loop.WithInference(client, selectedModel),
	loop.WithContextCounter(counter),
	loop.WithInferenceCapability(capability),
	loop.WithCompaction(loop.CompactionPolicy{
		Automatic:        true,
		CounterPolicy:    loop.CounterPolicyRequireExact,
		CompactAt:        8_000,
		RearmBelow:       6_000,
		ReservedOutput:   4_096,
		MaxSummaryTokens: 2_048,
		CountTimeout:     3 * time.Second,
		Hustle:           hustle.Name("context.compact"),
	}),
)

The context counter, inference capability, and policy are validated as one compatible configuration. Harness supplies no hidden timeout or threshold defaults. The named Hustle must be registered on the Rig and be blocking with ModelSourceCurrentLoop.

Proof: Loop compaction definition, policy validation, and Rig validation.

Run manual compaction

attemptID, err := live.Compact(ctx)
if err != nil {
	return fmt.Errorf("request compaction: %w", err)
}
fmt.Printf("compaction requested: %s\n", attemptID)

CompactToLoop targets a particular Loop ID. Completion is asynchronous with respect to the request, so observe CompactionStarted, CompactionCommitted, or CompactionRejected, along with CompactWaiterResolved or CompactWaiterRejected when waiting for a command outcome. The API accepts no caller-supplied summary.

Proof: Session compaction methods and compaction event tests.

Safety properties

Compaction never treats arbitrary model text as a replacement transcript. The output must be one nonempty UserMessage text block, match input basis/model/ fingerprint, satisfy the exact summary grammar, stay within byte and token limits, and leave the complete post-replacement request below the context limit. Automatic compaction re-arms only after context falls below RearmBelow.

Proof: compaction replacement and finalization tests.

Source and proof

← back to documentation