Browse documentation

Technical documentation / Reference

Progressive Session Maintenance

Progressive Session Maintenance (PSM) writes background summaries of saved session events. It requires the shared beta flag, is disabled by default, and is separate from the Summary pane.

Settings

Open /settings → Beta features. With Enable beta features off, this page shows an overview. Enable it, then open Background session summaries (PSM) below the toggle, or search for PSM. Enable Maintain background summaries, then configure the event threshold and optional model/reasoning. Save with Ctrl-S and restart. An in-flight summary uses its captured settings.

{
  "beta": true,
  "sessions": {
    "psm": {
      "enabled": true,
      "event_threshold": 20,
      "provider": "local-provider",
      "model": "summary-model",
      "reasoning": "low"
    }
  }
}
SettingBehavior
enabledDefault false. Enables observation after turn preparation.
event_thresholdDefault 20; accepts 1 through 1000 tracked events. Turn completion also triggers maintenance.
provider, modelSet both or omit both. Omitted values use the active conversation provider and model.
reasoningOmit or select default to inherit conversation reasoning. Explicit levels depend on provider/model support.

With beta unset or false, PSM controls are hidden from task navigation, Search, and Browse. Saved PSM configuration is retained but cannot start background work, even if sessions.psm.enabled remains true. Existing summary and status files remain exportable and are still removed during session pruning.

PSM observes persisted primary, side, and local-agent turns. Separate subagent sessions and nested Code Mode event types are not independently summarized. --no-session produces no PSM output.

Inputs and output

Tracked events are user_input, assistant_output, tool_call, and tool_result. Each request contains full original JSONL records, not replay projections or truncated tool outputs. Compaction archives remain eligible; repeated event IDs are read once. Legacy records without event IDs are skipped.

Only user input, assistant output, and tool calls produce summary entries. Tool results supply evidence for the corresponding call, never standalone entries. Each tool-call entry links to its result's event ID through response_id. A call without a result waits until a later trigger or turn completion. User/assistant text of at most 240 characters is preserved, subject to sensitive-text redaction.

Summaries append to <session-id>.psm.ndjson beside the original session. Each line commits one batch:

{"schema_version":1,"source_event_ids":["a1","a2"],"entries":[{"event_id":"a1","type":"tool_call","summary":"Read the requested file.","response_id":"a2"}]}

source_event_ids includes tool results and records which inputs have been processed. entries preserves source order. PSM does not modify session JSONL, replay, compaction, context caches, or the Summary pane. Session exports include readable PSM files; session pruning removes them.

Diagnose progress

Each maintenance pass updates <session-id>.psm.status.json beside the summary file. This is an atomically replaced diagnostic snapshot, not another event log. It does not change conversation revisions or provider context.

For example, inspect an active session with:

cat ~/.magi-code/sessions/SESSION_ID.psm.status.json

The snapshot includes process ID, trigger event ID, provider/model/reasoning, timestamps, pending and current-batch record counts, input bytes, and saved-batch counts. Counts reset each pass. last_success_at and last_error survive retries and restarts; a completed pass can retain an earlier error for diagnosis.

Stages distinguish waiting for a file lock, reading summaries/history, preparing a provider, requesting or receiving a summary, validating output, writing summaries, waiting for a tool result, completion, and failure. last_error contains its timestamp, failed stage, and a redacted message capped at 2000 characters. Provider timeouts explicitly report the 120-second deadline.

updated_at and elapsed_ms change on stage transitions and completed batches, not on a timer. A stale requesting_summary snapshot can mean a slow request, a stopped process, or a failed diagnostic write; it is not proof of a live worker. Check process_id separately. The file first appears when a worker starts, not when PSM is enabled.

Status files are owner-private, limited to 16 KiB, included in exports, and removed during session pruning. They do not copy source records or generated summaries, but error messages can contain provider-supplied text; redaction is not a guarantee that content is safe to share. Diagnostic writes are best effort: storage errors can leave a missing or stale status file without blocking the conversation or summary generation.

Cost and failures

PSM makes additional provider calls using the selected provider's credentials and quota. Full tracked records can contain source code, paths, prompts, and tool data. Stored-record and summary redaction does not guarantee that content is safe to send to another provider. The observer has no tools and does not request Fast service tiers.

One worker per session processes a coalesced pending trigger. Provider, validation, and storage errors do not interrupt conversation turns or append diagnostics to their history. Failed batches remain unacknowledged and retry on a later threshold or turn-completion trigger. Restarting does not immediately run maintenance; the next prepared turn triggers recovery. Exiting can interrupt background work, leaving it for a later trigger. A partial final sidecar line is discarded before retry.

Bounds prevent full-record processing from using unlimited resources:

Oversized records or call/result spans, malformed complete sidecar lines, and exhausted limits prevent further progress until their cause is resolved. They do not advance the processed-event cursor.

Edit this page on GitHub ↗