DSH plugin sessions: store and query in DeepSeek Harness

A logical session in DeepSeek Harness is a header plus an ordered event log, where each event carries seq, type and a timestamp; queries use provider-agnostic filters, full-text search, session lineage and bounded reads, and live data takes priority over persisted data (source). A session is both the source of the next round's context and the record you review afterwards; because it plays both roles at once, its data model is an event log rather than one long transcript. This piece covers how that model is organised, queried and read by plugins; where to look and search is in where sessions are kept, and how sessions join the chain in how one turn runs.

Why sessions are an event log

Making a session an ordered event log rather than one assembled transcript is what makes ordering, retrieval, incremental reads and later processing all possible (source). Put the two designs side by side:

1. Order needs explicit marking: with only a blob of text, sequence can only be guessed from position; an event log gives each event a monotonic number, so order is definite.
2. Retrieval needs structure: filtering by type, taking a range, searching by keyword all require events to be individually addressable; a plain transcript cannot do this.
3. Incremental reads need boundaries: new events keep appending, and only numbered events allow "take only what came after last time".
4. Later processing needs a stable shape: a plugin that wants to work on session data needs a stable, backend-agnostic read interface, or every backend would need its own code.

So the event log is not a storage detail but the core abstraction of the session mechanism; all the query powers below build on it.

What a DeepSeek Harness session consists of

A logical session in DeepSeek Harness is a header plus an ordered event log, with seq giving a definite order (source). Three points:

1. The header is the basic information: SessionHeader records the session's identity and metadata, forming the logical session together with the log; it answers "which session is this".
2. The log is ordered: each event carries a monotonically increasing seq; order is not guessed from timestamps, which may be equal or out of order.
3. Logical session and storage are decoupled: queries work on logical sessions, and whichever backend holds them does not change the vocabulary you use — the value of the abstraction.

What an event holds: seq, type and time

Every DeepSeek Harness session event carries a monotonically increasing seq, an event type and a timestamp, and the three together support ordering, filtering and replay (source). Their uses:

1. seq handles order: it fixes an event's position in the session and is the coordinate for bounded reads — taking events whose seq falls in a range means taking one segment of the session.
2. type handles classification: it marks what kind of event this is, so "only look at one kind" becomes a single filter rather than reading everything first.
3. Time handles the moment: it gives the actual time an event happened, used for human-facing ordering and display, but not as the basis of order.
4. Together they allow replay: sort by seq, filter by type, present by time, and you can rebuild what happened in the session and in which order.

The vocabulary for querying sessions

In DeepSeek Harness, sessions are queried with provider-agnostic filters, full-text search, session lineage and bounded event reads (source). Taken one by one:

1. Provider-agnostic filters: items combine with AND, values within a single list with OR, and ranges are inclusive. "Provider-agnostic" means the vocabulary is not tied to a specific search or storage backend, so changing backend does not change how you query.
2. Full-text search: scans extracted semantic text without binding to a specific search provider, so "find that piece of content" does not depend on an external service.
3. Session lineage: tracks relations between sessions, such as derivation or association, so "where did this session come from, what did it produce" is answerable.
4. Bounded event reads: take a range of events by seq instead of pulling everything; events keep appending, and boundaries let you take only what you need.
5. Atomic observation: reads are given as a consistent snapshot, useful for restore pre-checks and validation — you see one coherent cross-section, not a set still changing mid-read.

What live-first means

When live data exists, DeepSeek Harness session queries prefer it; the logical session corpus is organised as live-first with persisted data as the fallback (source). Three implications:

1. A running session can still be queried: a session need not be written to disk to be observable, so "how far has this round got" is visible.
2. Freshness beats completeness: preferring live data means a query gets the latest state, not the previous persisted snapshot.
3. Persistence handles durability: live data runs in memory while persisted data covers fallback and long-term storage; the query layer handles the priority for you.

How a plugin uses it: ctx.sessionQuery

A DSH plugin reaches session data through ctx.sessionQuery, the abstract session query engine entry that handles exact reads, source priority, relation tracking and semantic extraction (source). Two points:

1. Plugins do not touch underlying files: where sessions live, in what format, and how live and persisted data are merged all belong to the service layer; plugins use the query vocabulary and therefore do not break when the backend changes.
2. The entry is a service, not a format: to build something on session data — statistics, retrieval, summarisation — the entry is ctx.sessionQuery; ready-made implementations can be found under Settings → Plugin Market, which is DSH Plugin Hub.

Notes on session persistence

Hold on to "logical session", "event log" and "live-first" and this area is clear.

1. Logical session comes before storage form: the query vocabulary does not change with the backend, so do not depend on a specific file layout.
2. Order is seq, not time: time only marks the moment, ordering always follows the sequence number.
3. Prefer bounded reads over pulling everything: it is more efficient and matches how events keep appending.
4. Filter vocabulary composes: items with AND, values with OR, ranges inclusive — combined, they express precise filtering intent.
5. A running session may still be queryable: thanks to live-first.
6. Plugins go through ctx.sessionQuery: they do not touch underlying files or re-implement source priority.
7. For the how-to, see where sessions are kept; how sessions join the chain is in how one turn runs.

Source: DeepSeek Harness docs - session query, docs - core subsystems.