# Progressive Session Maintenance
Progressive Session Maintenance (PSM) writes background summaries of saved session events. It is disabled by default and separate from the [Summary pane](session-summarizer.md).
## Settings
Open `/settings` → **PSM**. The tab contains **Progressive Session Maintenance** and **Progressive Event Summaries** controls. Save with `Ctrl-S` and restart to apply settings. An in-flight summary uses its captured settings.
```json
{
"sessions": {
"psm": {
"enabled": true,
"event_threshold": 20,
"provider": "local-provider",
"model": "summary-model",
"reasoning": "low"
}
}
}
```
| `enabled` | Default `false`. Enables observation after turn preparation. |
| `event_threshold` | Default `20`; accepts 1 through 1000 tracked events. Turn completion also triggers maintenance. |
| `provider`, `model` | Set both or omit both. Omitted values use the active conversation provider and model. |
| `reasoning` | Omit or select `default` to inherit conversation reasoning. Explicit levels depend on provider/model support. |
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:
```json
{"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:
```bash
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:
- At most 128 archive-directory entries, 512 MiB scanned, and one million source records per pass.
- At most 64 MiB of pending source text in memory.
- At most 1000 records and 8 MiB per provider request, with no source-record truncation.
- At most 1 MiB of provider output, 2000 characters per summary, and a 120-second cancellation deadline.
- At most 64 MiB per sidecar.
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.