These docs track the main branch and may describe unreleased features. The stable documentation lives at docs.docker.com.

Session Context Tool

Reference a previous session as context, without manual export/import.

Overview

The session_context toolset lets an agent discover earlier sessions and pull one in as context for the current session. It removes the manual workaround of exporting a conversation to HTML and re-attaching it with an @ mention.

The tool surface is two read-only tools:

Tool	Description
`list_sessions`	List previous sessions (most recent first) with id, title, creation time and message count.
`read_session`	Return the transcript of a previous session, by id or by a relative reference like `-1`.

The session the agent is currently running in is never listed by list_sessions and cannot be read by read_session (a circular reference returns an error).

Configuration

toolsets:
  - type: session_context

No configuration options. Both tools are read-only and operate against the same session store the runtime already uses for persistence.

Restrict the toolset to a subset of tools the standard way:

# An agent that may browse but never pull a full transcript into context.
toolsets:
  - type: session_context
    tools:
      - list_sessions

Selecting a session

read_session accepts either form:

A concrete id returned by list_sessions, e.g. read_session("a1b2c3...").
A relative reference: -1 is the most recent session, -2 the second most recent, and so on. Relative references resolve against the same ordering list_sessions uses (most recent first), excluding sub-sessions.

Transcript size

A long session could overflow the current context window, so read_session caps the rendered transcript. When a transcript is larger than the budget, the oldest messages are dropped (the most recent are usually the most useful for continuing work) and a note records how many were omitted:

[12 earlier message(s) omitted to fit the context budget; showing the most recent 8]

Notes

list_sessions defaults to 20 sessions and is capped at 100; pass limit to request fewer.
read_session returns an error when the session is not found, when the reference cannot be resolved, or when it points at the current session.
Both tools are read-only: they never modify, branch, or delete sessions.

Example

See examples/session_context.yaml for a complete working example.

← Previous Model Picker Next → LSP