# Sessions, context, and cache
[Feature docs index](README.md) · [Repository README](../../README.md)
## Purpose
Understand persisted JSONL sessions, full structured history replay, manual and opt-in automatic compaction, context budget behavior, and local cache records.
## Details
Sessions are JSONL files under `~/.magi-code/sessions`. They record user prompts, assistant responses, diagnostics, tool calls/results, context/cache events, rewind events, and subagent summaries where applicable. Slash-command errors are recorded as diagnostics when a session is active. `/changes` reads per-session checkpoint ledgers under `~/.magi-code/checkpoints` and reports only sanitized file-tool snapshot metadata. `/rewind` appends a sanitized local rewind event with target turn, relative paths, statuses, and counts; file bytes, diffs, blob hashes, secret-looking paths, and denied paths are omitted. Existing sessions without checkpoint dirs show empty `/changes` and need no migration. `/prune-sessions [days]` is opt-in destructive cleanup for this directory: no argument means older than 30 days, one positive integer sets a custom threshold, and invalid forms delete nothing. Pruning a session also removes that session checkpoint ledger plus blobs no remaining ledger references.
Default context budget:
| Setting | Default |
| --- | ---: |
| `context.enabled` | `true` |
| `context.max_tokens` | `128000` |
| `context.reserve_tokens` | `16384` |
| `context.keep_recent_tokens` | `20000` (legacy; not used for active provider replay) |
Active session continuity replays full provider-visible JSONL history as ordered structured conversation records before the current user prompt until a valid `/compact` checkpoint exists. Prior user turns, assistant text, provider response items, tool calls, and tool results remain distinct; local telemetry such as hook diagnostics, hook lifecycle records, session titles, and context-cache events is excluded.
Local-only event types include `hook_diagnostic`, `hook_lifecycle`, `context_cache`, `session_title`, and `diagnostic`. `hook_lifecycle` records preserve sanitized hook start/success/failure history for local audit and Mission Control replay without rerunning hooks. They are excluded from provider replay, recent context helpers, context-budget accounting, and cache-key material. No session history is silently summarized, recent-sliced, or truncated for provider requests.
OpenAI Responses diagnostics retain bounded metadata per HTTP attempt: requested model, optional provider-reported `response.model`, optional `x-request-id`, attempt sequence, and outcome. Metadata is local-only, excluded from provider replay, recent-context text, and cache-key material. `response.model` is provider-reported observability data, not proof or cryptographic attestation of routing correctness; values may be absent or differ across retries.
`/compact [custom instructions]` creates an explicit replay checkpoint for an active persisted session. The command sends the current provider-visible replay state to the selected compaction model with `prompts/compact.md`, no tool execution, and no tool definitions. On success, the current active JSONL is copied byte-for-byte into an immutable `.history/<session-id>/` archive under the sessions root, then the top-level active file is atomically replaced with one checkpoint plus any events appended after the bounded snapshot. The active file is the only provider replay source; archives preserve local audit history but are never sent to providers or used for normal listing/title reads. Raw earlier JSONL events remain durable. Future provider requests include exactly the latest valid summary boundary plus provider-visible events after that checkpoint. Repeated compaction rotates each active generation. Sessions disabled with `--no-session` or missing an active session fail locally before provider dispatch.
`/prune-sessions [days]` deletes only regular top-level `*.jsonl` session files under configured session root. Activity age comes from latest valid event timestamp when available, with file mtime as fallback for empty or malformed legacy files. Files newer than or equal to cutoff stay; files strictly older than cutoff are removed unless active session. Directories, nested files, symlinks, wrong extensions, invalid session ids, cache files, auth/settings files, and non-session `~/.magi-code` data are ignored. Archives are immutable during session lifetime and removed only after validated primary deletion succeeds under session lock. Results report deleted count, skipped active-session count when applicable, and failed deletion count with bounded categories such as `permission_denied` or `not_found`; raw paths, JSONL content, and OS error chains are never shown. Deleted session files cannot be resumed through `magi-code`.
Session storage trust boundary: configured session root must be a non-symlink, owner-private directory on Unix (`0700` or stricter). Top-level primary JSONL and metadata sidecar files must be owner-private regular files (`0600` or stricter), use names derived from validated session IDs, and reject symlinks, directories, replacements, unsafe owners, or unsafe permissions. Opens use no-follow protection on Unix and bind opened objects to expected paths. Windows reports permission repair as unsupported. Existing unsafe objects are rejected rather than followed. For recognized broad legacy layouts, run `magi-code sessions repair-permissions`; it resolves `MC_HOME`, prompts by default, supports `--yes` and `--dry-run`, never recurses or follows links, and fails closed on unknown or unsafe entries. Unsafe layouts require manual inspection.
Compaction uses the active provider/model by default. To override, set both non-blank `compaction.provider` and `compaction.model` in `settings.json`; partial or blank override fails without writing a checkpoint. Use `/new` when you want a clean session instead of a summarized continuation boundary.
Automatic compaction is disabled when `compaction.auto` is missing or `compaction.auto.enabled` is false. Enable it with exactly one trigger:
```json
{
"compaction": {
"auto": {
"enabled": true,
"threshold_percent": 80
}
}
}
```
`threshold_percent` accepts `1` through `100`; `threshold_tokens` accepts any value greater than `0`. Use one, never both. Enabling without either trigger is invalid, and both triggers are invalid. Percentage mode triggers when projected next-request tokens divided by active model maximum reaches configured percentage. Token mode triggers when projection reaches fixed count. This trigger is independent of `context.max_tokens - context.reserve_tokens`, though automatic scheduling still requires context budgeting enabled.
Automatic scheduling runs only for normal persisted primary sessions after clean successful turns: provider output complete, tools settled, required session writes done, and cancellation clear. It does not run for `--no-session`, subagents, title/vision/tool-internal provider jobs, compaction requests, or cancelled, failed, incomplete, partial, or unsafe-tool-progress turns.
At eligible boundary, magi-code projects next provider request with pending steering when available, otherwise literal lowercase `continue`. Below configured trigger, turn ends normally. At or above trigger, runtime reuses `/compact` provider/model selection, prompt, summary validation, immutable archive rotation, and active-primary checkpoint. It verifies compacted request falls below same configured trigger before continuing.
After successful automatic compaction, pending Mission Control steering replaces fallback and is submitted in existing collapsed order. Without steering, runtime durably appends and submits literal `continue`; persisted `user_input` payload has `origin: "automatic_compaction"`, while CLI and Mission Control render it as `you [automatic]: continue`. Manual `/compact` never adds this continuation solely because auto mode is enabled.
Failure stops automatic continuation. Before checkpoint commit, old primary remains authoritative. After checkpoint commit but before continuation append, new checkpoint primary remains authoritative. No provider request is sent without durable continuation input; pending steering is acknowledged only after its append succeeds. Diagnostics are bounded and sanitized. Recovery remains explicit: retry normal input, run `/compact`, fix compaction provider/auth/settings, or start `/new`.
Context budget resolution starts from the global/default `context` settings, then uses cached model-catalog context-window metadata when available, then applies `context.model_overrides["provider/model"]` when the active provider/model key matches exactly. Explicit overrides win over cached catalog metadata and affect normal runs, context usage display, and `/compact` request-fit checks. They are local budget settings only; setting a larger limit than the provider really supports can still produce a provider-side rejection.
Token counting is local. The agent loop uses `tiktoken-rs` with embedded `o200k_base` and `cl100k_base` tokenizer tables, selects by model family, and projects token budget without a provider round-trip.
If full assembled request exceeds `context.max_tokens - context.reserve_tokens` while `context.enabled` is `true`, the run fails locally before provider dispatch with estimated size, threshold, and remediation. Default-off automatic compaction cannot rescue input already submitted outside an eligible clean boundary; current remediation remains run `/compact`, choose a larger compaction model, or start `/new`.
`context.keep_recent_tokens` remains accepted for settings compatibility and bounded non-provider helper reads, but it no longer selects active provider-visible session history.
Reusable context diagnostics may be cached under `~/.magi-code/cache`. Cache keys are SHA-256 hex digests over provider, model, stable system prompt, ordered structured conversation input, and file fingerprints when present. These are local diagnostics only; provider-side cache hits are opportunistic and not promised.
OpenAI Codex and custom-provider model catalogs are cached under `~/.magi-code/cache/model-catalog/<provider>.json`. Catalog cache entries contain sanitized model identifiers and display metadata only, never API keys, OAuth tokens, bearer headers, account ids, or raw provider responses. Context budgets use only explicit context/input metadata; output-token limits remain separate output metadata and are never used as context-window fallback.
---
[Back to feature docs](README.md) · [Back to repository README](../../README.md)