Sessions and memory

Durable sessions

Each workspace can hold multiple UUID-based sessions under .q/sessions/. Studio registers root sessions with their workspace locations and presents roots from different repositories in one list. Add a repository, then choose an existing root session or create a new one. Deleting an inactive root removes its complete delegated child tree but preserves durable Workspace Memory archive records.

One process owns a selected session. Another q process may open a different session in the same workspace, but session locks do not serialize edits to the repository itself.

Transcript and context

q persists the visible transcript separately from the compacted request context sent to models. When context metadata is available, q can shorten model context while leaving the complete user-visible transcript intact.

The primary session record is:

Session v2 stores messages in a common format for Chat Completions and Responses. Existing v1 Chat Completions sessions are converted on load and saved in the new format on the next write. The record also keeps Responses replay state when applicable. Retired loop_mode values are accepted from older files and omitted on the next save.

Delegated recovery

Each delegated child call has a bookmark in delegations.json and its own session under delegates/<invocation-id>/. Children may have their own nested delegation tree. After a restart, q restores the deepest child first and returns its stored result to the parent call before continuing the parent turn.

Studio projects these records as a navigable tree. Selecting a child opens its transcript. A completed child can be deleted; q removes that child and every descendant while retaining the completed tool exchange in the parent transcript. Active, blocked, and unknown children cannot be deleted through this action.

If q stopped while a general tool call had no recorded result, recovery reports that call as unknown to its agent and does not run it again automatically. An interrupted external ACP child also returns unknown; q cannot resume the remote agent’s internal turn.

Workspace Memory

Workspace Memory stores durable messages, tool activity, failures, lifecycle events, and search indexes. It supports retrieval without making one chat projection carry every historical event.

Large tool results are stored as immutable Loom artifacts. The prompt receives a bounded receipt and may inspect only the relevant slice later.

Learning

After successful turns, Thinker can extract reusable propositions: established workflows, durable project facts, reusable resolutions, and evidence-backed findings likely to affect future work.

Librarian decides whether a proposition should be created, merged, or discarded in the global Library. /learn off stops collection and queue processing; it does not delete already queued data.

Run-specific build, test, formatting, and audit snapshots stay in task history instead of becoming durable project facts.