DSH plugin recall records: kind, form, version, references
In DSH plugin, a session reference record is not a block of text but a set of structured facts: kind says what it is, form says where the material came from, version says how to parse it, and references says which sessions were read and how far. All four together make recall possible.
DeepSeek Harness: Three enum values at the top
Read the values before reading the array. (source) A record usually starts like this:
{
"kind": "session-reference",
"form": "recall",
"version": 1,
"references": []
}
The three values answer different questions: what this record is, what shape the material takes, and what structural version it uses.
People who treat them as metadata decoration tend to collapse all three into one concept when writing downstream parsers.
DeepSeek Harness: kind vs form
kind types the record; form describes the material's origin. (source) Comparison:
| Field | Value | Question answered |
|---|---|---|
kind | session-reference | Is this a cross-session reference? |
form | recall | Was the material extracted from another session's log? |
kind decides which schema downstream parsing uses; form labels the semantics of the content.
An analogy: kind is the file type, form is the source of the content. Both are necessary and neither substitutes for the other.
DeepSeek Harness: Whose version is it
The record's own structure, not the source session's format. (source) This is the easiest confusion:
| Field | Location | Meaning |
|---|---|---|
version: 1 | Record top level | Structure version of this source record |
capturedFormatVersion | Inside each reference | Format version of the referenced session |
The first decides how to parse the record; the second decides how to read the source session.
Conflate them and upgrades produce "the record parses, but the content is read wrong".
DeepSeek Harness: Eleven fields in references, five groups
One entry per referenced session, fields in five groups. (source) Comparison:
| Group | Fields |
|---|---|
| Identity | sessionId, label |
| Coordinates | capturedFormatVersion, capturedThroughSeq |
| Source state | compacted |
| Snapshot facts | originalMessages, retainedMessages, omittedMessages, omittedBytes, truncated |
| Order | inputIndex |
The groups answer: which session, how far it was read, whether the source was compacted, how much this preparation lost, and where it sat in the input.
Many fields, but each group serves one decision; you do not need all of them at once.
DeepSeek Harness: Using the record for recall
Start from coordinates, then the gap, then replay in order. (source) Three steps:
- Use
capturedThroughSeqto locate a position in the source generation; - Use
compactedand the message counts to attribute the gap to the source or to this preparation; - Use
inputIndexto restore the original order of references.
Step 1 goes wrong when the coordinate is read as the current session's seq. The official description places it in the source session's original generation.
Step 2 decides whether you can explain a missing span. Step 3 affects only display order, not what was read.
DeepSeek Harness: Verifying the structure
Four assertions cover enums, versions, and the array. Steps:
- Reference once, read the record, and confirm
kind,form, andversion; - Confirm every reference has
sessionIdandinputIndex; - Confirm
versionandcapturedFormatVersiondid not overwrite each other; - Reference two sessions and confirm
inputIndexis 0 and 1 in selection order.
Step 3 is the regression focus: when the record structure evolves, merging the two version fields is the easiest mistake.
Step 4 checks ordering; do not stop at the array length.
With the record structure clear, the next topic is source compaction. Read DSH plugin referencing a compacted session; for reading coordinates, read DSH plugin capturedThroughSeq; for the wider picture, read how DSH plugin implements session references.
Sources: DeepSeek Harness reference - Session references, session-reference/src/types.ts
FAQ
In DSH plugin, kind says the record is a cross-session reference, form says material came from another session's log, and version describes the record's own structure. Each value answers a different question about the record.
No, DSH plugin's record version differs from capturedFormatVersion. version: 1 at the top describes the persisted source structure; capturedFormatVersion inside each reference describes the source session's format. Mixing them produces records that parse but read the wrong content.
A DSH plugin reference entry has eleven fields in five groups: identity, coordinates, source state, snapshot facts, and input order. Each group answers one question and does not need all fields at once.
DSH plugin recall starts from capturedThroughSeq to locate the source generation position, then uses compacted and the message counts to attribute the gap, then restores order with inputIndex. The coordinate must be read with the source session identity.
Related Terms
- kind
- kind identifies the record type; for cross-session references it is session-reference.— DeepSeek Harness reference - Session references
- form
- form identifies where material came from; recall means it was extracted from another session's log.— DeepSeek Harness reference - Session references
- references
- references is the array of per-session entries describing identity, coordinates, source state, snapshot facts, and order.— session-reference/src/types.ts
- inputIndex
- inputIndex records the original position of each reference in the input order.— session-reference/src/types.ts
Sources
- DeepSeek Harness reference - Session references· deepseek-ai
- session-reference/src/types.ts· deepseek-ai