DeepSeek Harness · 4 of 6
Context, session, and persistence
DeepSeek keeps an append-only record and derives the model surface from it. Compaction changes the derived surface through new events; it does not rewrite the historical log in place.
§1
The session log is the source of truth
A Session is an append-only sequence of typed SessionEvents. Model messages are derived from that log rather than stored as an independent transcript. Replay applies the same derivation rules to the same events. Source · session model
Only three message-producing event types join the ordered model surface: user message, assistant message, and tool result. Turn boundaries, stream chunks, usage, hook records, and compaction bookkeeping can remain durable without becoming model messages.
§2
Append-only log, replaceable surface
| Layer | Contains | Mutation rule | Consumer |
|---|---|---|---|
| Event log | Every durable lifecycle fact with contiguous sequence IDs. | Append only. | Persistence, replay, audit, UI fidelity. |
| Session surface | Ordered message-producing event nodes. | New nodes append or replace a prior surface range by reference. | deriveMessages(), token meter, compaction. |
| Model history | Provider-independent messages projected from current surface nodes. | Re-derived/cached from surface; empty assistant content and raw chunks are skipped. | Next request builder. |
| Human transcript | Append-origin interaction record. | May show history shadowed from the current model surface. | UI and inspection. |
A surface replacement shadows selected model-visible nodes while their original events remain in the log. deriveMessages() projects and freezes messages from the current surface. Source · surface operations
§3
Token metering observes the routed request
The token-meter capability owns estimation and replay of request size; compaction is an optional sibling capability rather than part of the loop spine. Pressure policy runs before request derivation, while confirmed provider overflow can trigger a more forceful recovery path after the failed step closes. Source · compaction seam
This separation lets a deployment swap the estimator or summarizer without changing the default agent loop, and lets a headless profile omit compaction entirely.
§4
Compaction is a logged replacement transaction
Summary compaction appends log-only compaction/start, compaction/summary, and compaction/end events. The summary enters model history through a separate user-message event whose surface operation replaces the selected range. The start/end bracket makes an interrupted operation detectable rather than rewriting earlier events. Source · compaction events
The result records the summary, shadowed range, exact shadowed sequence IDs, and estimated token count. Range selection preserves tool-call/result pairing, because a summary that keeps a call but drops its result would create a malformed model history.
§5
Prune and spill solve different pressure
Before summary selection, an optional model-free pruner can replace large tool-result surface entries and then remeasure. Separately, spill policy can persist an oversized plain-text result in full and replace its inline content with a head/tail preview, opaque locator, and backend-provided retrieval guidance. Source · pruning Source · spill seam
Pruning changes the model-visible representation without calling another model. Spill preserves exact text off-context. Summary compaction uses an LLM to derive a smaller replacement. The source log and artifact store make those losses and indirections traceable.
§6
Persistence is authoritative; projection caches are accelerators
The persistence seam makes the append-only event log durable. The pinned tree includes a per-session logical JSONL backend and a SQLite backend with one row per event. Headers carry storage metadata such as format version, working directory, lineage, and seed boundary outside the conversation event vocabulary. Source · durability seam Source · backends
Projection units fold session events into domain-specific JSON views for clients. An optional persisted projection cache checkpoints those views and can fold only the tail on cold reads. Cache failure falls back to authoritative log/persistence work; it does not become a second source of truth.