Use one session for related work, with a current objective and identifiable source material. This guide targets Sonny 0.12.7. It builds on Sessions and continuation and the explanation of context and compaction .
Establish the task and its sources
Choose a reviewed Recipe, provider and workspace. Keep the original source documents available under the intended access rules. For a pilot comparison, record source labels, both denominators, the reporting dates and the questions that remain unresolved. The supplied-research workflow provides a small example with public inputs.
State the current objective plainly:
Compare Notes A and B. Cite each note, preserve both denominators, and identify
missing evidence. Keep interpretation separate from the recorded results.
Put a reusable decision in an appropriate durable record when it should outlive the session. For example, use the supported Memory workflow to store a reviewed project rule. That does not mean its full body will be automatically included in every later request.
When the task changes, state the replacement objective and the assumptions that no longer apply. Use the supported goal controls for the session’s standing objective. A remembered earlier instruction is weaker than a clear current task.
Check important details before compaction
Ask Sonny to identify the current sources, calculations, constraints and unresolved questions. Compare those statements with the documents yourself. Save any required approved output through the documented export/file workflow before relying on it as a recovery source. A screenshot or a message visible in the UI is not proof that its content enters the next model request.
Separate an essential requirement from an incidental detail. If an exact number, identifier or date matters to completion, name it as an explicit constraint and keep its original source. Do not expect incidental prose to survive a summary verbatim.
Request compaction deliberately
Automatic compaction can occur as the working context grows. You can also enter the session command:
/compact
The installed simple REPL was exercised with this command. The TUI exposes the
same directive through its own engine adapter; the runtime receipt below is
the REPL journey, not a separate TUI certification. This is a command inside
the session, not sonny compact in a shell.
A small session may report no-op (below budget). A configured pipeline may
report a reduction, or an error may leave uncompacted history. Do not repeatedly
request compaction to force a particular percentage. It can make additional
model calls and does not certify a complete or correct summary.
Measured example
A controlled provider returned long synthetic comparison notes. One early reply contained the optional colour label saffron. The fixture deliberately used state/continuation responses that omitted that incidental detail.
| Point in the same installed REPL session | Observed result |
|---|---|
| Before compaction | The outgoing model request contained the optional label |
Automatic state/continuation work and /compact | The production pipeline called both extraction and summarization; the manual command reported about a 39% estimated reduction |
| Follow-up asking for the label | The checkpoint-bearing request no longer contained the label; the controlled response reported the missing detail |
| Follow-up supplying the saved excerpt | The new request contained the excerpt and the controlled response returned the label |
This tests actual context assembly and loss/recovery through the installed binary. The fixture’s summaries are deliberately lossy and its usage counters are synthetic. It does not measure real model accuracy, provider billing, or guarantee a particular compression ratio. The missing detail was restored by supplying evidence, not by treating a summary as a lossless archive.
Recover a missing detail from its source
First check which source was available, permitted and selected. Ask a focused question about the missing fact and its source label. If the answer lacks evidence, open the original document yourself or use an approved read-only tool to retrieve the relevant passage. Check its version and surrounding context.
Then supply a short, attributed excerpt rather than repeating the whole conversation. The synthetic recovery request used:
Saved first reply excerpt: The optional colour label is saffron.
Use this excerpt for the label; keep the pilot results and unresolved owner
separate from that incidental detail.
For real work, prefer the original document over an assistant’s earlier claim. If the only available record is an old generated answer, label it as such and verify it before promoting it to a fact. Ask for a revised answer that cites the recovered passage, then check the exact detail yourself.
If a supported resource-recovery operation can no longer retrieve an old tool result, re-read the permitted original source. Do not assume a temporary cache is durable or broaden access to bypass a missing resource. For an integration problem, follow MCP connection troubleshooting separately.
Continue or start a new task
Continue the same session while its objective, workspace and access scope still fit. Start a new session when they change substantially; carry forward a small, reviewed task brief and source references. Starting new work, clearing a view, compacting history and deleting stored data are different operations.
The TUI can persist compacted history and checkpoints for resume. Keep required original documents and exports separately: reopening a saved session does not promise every pre-compaction byte is available. Headless cross-process replay has the documented authority/persistence limits . Use the backup runbook before replacing a store.
Use offline packing only for its diagnostic purpose
sonny context pack takes a flat JSON transcript and constructs an offline
packet. It does not compact the active conversation, retrieve a saved session
by ID, call a provider or modify its telemetry store. Download the
synthetic transcript
used for the packing
checks, or choose your own reviewed flat JSON transcript:
curl --fail --location 'https://sonny.sh/examples/context/transcript.json' -o context-transcript.json
sonny context pack --transcript ./context-transcript.json --budget 400 --format json
sonny context pack --transcript ./context-transcript.json --budget 400 --format json --strict
The first user message becomes the packet’s objective; this mapping is not a
replay of the runtime’s full instruction/trust model. The budget reserves one
tenth for output unless --output-reserve is supplied. --budget overrides
--window; the latter defaults to 8,000 when neither is supplied.
Read dropped_messages and dropped_bytes. The executed offline example
dropped eight messages and 11,360 bytes while loss_categories was empty.
Strict mode returned nonzero for that drop. A null continuation means no
marker evaluation was requested; --markers can request that diagnostic.
An empty loss list or a survival score is not proof that all useful meaning
survived. An objective/constraint block that cannot fit, malformed JSON and an
unsupported output format also fail rather than establish a usable packet.
For operator telemetry, use the context diagnostics reference and inspect its store/filter limits. Its PASS status is not a substitute for checking the task’s original facts and required outcome.