> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fased.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Session Management Deep Dive

# Session Management & Compaction (Deep Dive)

This document explains how Fased manages sessions end-to-end:

* **Session routing** (how inbound messages map to a `sessionKey`)
* **Session store** (`sessions.json`) and what it tracks
* **Transcript persistence** (`*.jsonl`) and its structure
* **Transcript hygiene** (provider-specific fixups before runs)
* **Context limits** (context window vs tracked tokens)
* **Compaction** (manual + auto-compaction) and where to hook pre-compaction work
* **Silent housekeeping** (e.g. memory writes that shouldn’t produce user-visible output)

If you want a higher-level overview first, start with:

* [/concepts/session](/concepts/session)
* [/concepts/compaction](/concepts/compaction)
* [/concepts/session-pruning](/concepts/session-pruning)
* [/reference/transcript-hygiene](/reference/transcript-hygiene)

***

## Source of truth: the Gateway

Fased is designed around a single **Gateway process** that owns session state.

* UIs (macOS app, web Control UI, TUI) should query the Gateway for session lists and token counts.
* In remote mode, session files are on the remote host; “checking your local Mac files” won’t reflect what the Gateway is using.

***

## Two persistence layers

Fased persists sessions in two layers:

1. **Session store (`sessions.json`)**
   * Key/value map: `sessionKey -> SessionEntry`
   * Small, mutable, safe to edit (or delete entries)
   * Tracks session metadata (current session id, last activity, toggles, token counters, etc.)

2. **Transcript (`<sessionId>.jsonl`)**
   * Append-only transcript with tree structure (entries have `id` + `parentId`)
   * Stores the actual conversation + tool calls + compaction summaries
   * Used to rebuild the model context for future turns

***

## On-disk locations

Per agent, on the Gateway host:

* Store: `~/.fased/agents/<agentId>/sessions/sessions.json`
* Transcripts: `~/.fased/agents/<agentId>/sessions/<sessionId>.jsonl`
  * Telegram topic sessions: `.../<sessionId>-topic-<threadId>.jsonl`

Fased resolves these via `src/config/sessions.ts`.

***

## Store maintenance and disk controls

Session persistence has automatic maintenance controls (`session.maintenance`) for `sessions.json` and transcript artifacts:

* `mode`: `warn` (default) or `enforce`
* `pruneAfter`: stale-entry age cutoff (default `30d`)
* `maxEntries`: cap entries in `sessions.json` (default `500`)
* `rotateBytes`: rotate `sessions.json` when oversized (default `10mb`)
* `resetArchiveRetention`: retention for `*.reset.<timestamp>` transcript
  archives. Defaults to the same value as `pruneAfter`; `false` disables
  cleanup.
* `maxDiskBytes`: optional sessions-directory budget
* `highWaterBytes`: optional target after cleanup (default `80%` of `maxDiskBytes`)

Enforcement order for disk budget cleanup (`mode: "enforce"`):

1. Remove oldest archived or orphan transcript artifacts first.
2. If still above the target, evict oldest session entries and their transcript files.
3. Keep going until usage is at or below `highWaterBytes`.

In `mode: "warn"`, Fased reports potential evictions but does not mutate the store/files.

Run maintenance on demand:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
fased sessions cleanup --dry-run
fased sessions cleanup --enforce
```

***

## Task/cron sessions and run logs

Scheduled task runs and legacy cron runs can create isolated session entries and
transcripts. They have dedicated retention controls:

* `cron.sessionRetention` (default `24h`) prunes old isolated task/cron run sessions from the session store (`false` disables).
* `cron.runLog.maxBytes` + `cron.runLog.keepLines` prune
  `~/.fased/cron/runs/<jobId>.jsonl` files. Defaults are `2_000_000` bytes
  and `2000` lines.

***

## Session keys (`sessionKey`)

A `sessionKey` identifies *which conversation bucket* you’re in (routing + isolation).

Common patterns:

* Main/direct chat (per agent): `agent:<agentId>:<mainKey>` (default `main`)
* Group: `agent:<agentId>:<channel>:group:<id>`
* Room/channel (Discord/Slack): `agent:<agentId>:<channel>:channel:<id>` or `...:room:<id>`
* Task/cron: `cron:<job.id>`
* Webhook: `hook:<uuid>` (unless overridden)

The canonical rules are documented at [/concepts/session](/concepts/session).

***

## Session ids (`sessionId`)

Each `sessionKey` points at a current `sessionId` (the transcript file that continues the conversation).

Rules of thumb:

* **Reset** (`/new`, `/reset`) creates a new `sessionId` for that `sessionKey`.
* **Daily reset** defaults to 4:00 AM local time on the gateway host. It
  creates a new `sessionId` on the next message after the reset boundary.
* **Idle expiry** uses `session.reset.idleMinutes` or legacy
  `session.idleMinutes`. It creates a new `sessionId` when a message arrives
  after the idle window. When daily + idle are both configured, whichever
  expires first wins.
* **Thread parent fork guard** uses `session.parentForkMaxTokens` with default
  `100000`. It skips parent transcript forking when the parent session is
  already too large, so the new thread starts fresh. Set `0` to disable.

Implementation detail: the decision happens in `initSessionState()` in `src/auto-reply/reply/session.ts`.

***

## Session store schema (`sessions.json`)

The store’s value type is `SessionEntry` in `src/config/sessions.ts`.

Key fields (not exhaustive):

* `sessionId`: current transcript id (filename is derived from this unless `sessionFile` is set)
* `updatedAt`: last activity timestamp
* `sessionFile`: optional explicit transcript path override
* `chatType`: `direct | group | room` (helps UIs and send policy)
* `provider`, `subject`, `room`, `space`, `displayName`: metadata for group/channel labeling
* Toggles:
  * `thinkingLevel`, `verboseLevel`, `reasoningLevel`, `elevatedLevel`
  * `sendPolicy` (per-session override)
* Model selection:
  * `providerOverride`, `modelOverride`, `authProfileOverride`
* Token counters (best-effort / provider-dependent):
  * `inputTokens`, `outputTokens`, `totalTokens`, `contextTokens`
* `compactionCount`: how often auto-compaction completed for this session key
* `memoryFlushAt`: timestamp for the last pre-compaction memory flush
* `memoryFlushCompactionCount`: compaction count when the last flush ran

The store is safe to edit, but the Gateway is the authority: it may rewrite or rehydrate entries as sessions run.

***

## Transcript structure (`*.jsonl`)

Transcripts are managed by `@mariozechner/pi-coding-agent`’s `SessionManager`.

The file is JSONL:

* First line: session header (`type: "session"`, includes `id`, `cwd`, `timestamp`, optional `parentSession`)
* Then: session entries with `id` + `parentId` (tree)

Notable entry types:

* `message`: user/assistant/toolResult messages
* `custom_message`: extension-injected messages that *do* enter model context (can be hidden from UI)
* `custom`: extension state that does *not* enter model context
* `compaction`: persisted compaction summary with `firstKeptEntryId` and `tokensBefore`
* `branch_summary`: persisted summary when navigating a tree branch

Fased intentionally does **not** “fix up” transcripts; the Gateway uses `SessionManager` to read/write them.

***

## Context windows vs tracked tokens

Two different concepts matter:

1. **Model context window**: hard cap per model (tokens visible to the model)
2. **Session store counters**: rolling stats written into `sessions.json`.
   These power chat status, Agent > Sessions, and fallback usage display.

If you’re tuning limits:

* The context window comes from the model catalog (and can be overridden via config).
* `contextTokens` in the store is a runtime estimate/reporting value; don’t treat it as an exact limit.

For more, see [/token-use](/reference/token-use).

***

## Compaction: what it is

Compaction summarizes older conversation into a persisted `compaction` entry in the transcript and keeps recent messages intact.

After compaction, future turns see:

* The compaction summary
* Messages after `firstKeptEntryId`

Compaction is **persistent** (unlike session pruning). See [/concepts/session-pruning](/concepts/session-pruning).

***

## When auto-compaction happens (Pi runtime)

In the embedded Pi agent, auto-compaction triggers in two cases:

1. **Overflow recovery**: the model returns a context overflow error → compact → retry.
2. **Threshold maintenance**: after a successful turn, when:

`contextTokens > contextWindow - reserveTokens`

Where:

* `contextWindow` is the model’s context window
* `reserveTokens` is headroom reserved for prompts + the next model output

These are Pi runtime semantics (Fased consumes the events, but Pi decides when to compact).

***

## Compaction settings (`reserveTokens`, `keepRecentTokens`)

Pi’s compaction settings live in Pi settings:

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  compaction: {
    enabled: true,
    reserveTokens: 16384,
    keepRecentTokens: 20000,
  },
}
```

Fased also enforces a safety floor for embedded runs:

* If `compaction.reserveTokens < reserveTokensFloor`, Fased bumps it.
* Default floor is `20000` tokens.
* Set `agents.defaults.compaction.reserveTokensFloor: 0` to disable the floor.
* If it’s already higher, Fased leaves it alone.

Why: leave enough headroom for multi-turn “housekeeping” (like memory writes) before compaction becomes unavoidable.

Implementation: `ensurePiCompactionReserveTokens()` in `src/agents/pi-settings.ts`
(called from `src/agents/pi-embedded-runner.ts`).

***

## User-visible surfaces

You can observe compaction and session state via:

* Chat `/status` (current session)
* Agent > Sessions (session list, last activity, transcript metadata, and protected delete actions)
* Usage page (token usage history; session counters are only a fallback when no better usage record exists)
* `fased status` (CLI)
* `fased sessions` / `sessions --json`
* Verbose mode: `🧹 Auto-compaction complete` + compaction count

***

## Silent housekeeping (`NO_REPLY`)

Fased supports “silent” turns for background tasks where the user should not see intermediate output.

Convention:

* The assistant starts its output with `NO_REPLY` to indicate “do not deliver a reply to the user”.
* Fased strips/suppresses this in the delivery layer.

As of `2026.1.10`, Fased also suppresses **draft/typing streaming** when a
partial chunk begins with `NO_REPLY`. This keeps silent operations from showing
partial output mid-turn.

***

## Pre-compaction “memory flush” (implemented)

Goal: before auto-compaction happens, run a silent agentic turn that writes durable
state to disk (e.g. `memory/YYYY-MM-DD.md` in the agent workspace) so compaction can’t
erase critical context.

Fased uses the **pre-threshold flush** approach:

1. Monitor session context usage.
2. When it crosses a “soft threshold” (below Pi’s compaction threshold), run a silent
   “write memory now” directive to the agent.
3. Use `NO_REPLY` so the user sees nothing.

Config (`agents.defaults.compaction.memoryFlush`):

* `enabled` (default: `true`)
* `softThresholdTokens` (default: `4000`)
* `prompt` (user message for the flush turn)
* `systemPrompt` (extra system prompt appended for the flush turn)

Notes:

* The default prompt/system prompt include a `NO_REPLY` hint to suppress delivery.
* The flush runs once per compaction cycle (tracked in `sessions.json`).
* The flush runs only for embedded Pi sessions (CLI backends skip it).
* The flush is skipped when the session workspace is read-only (`workspaceAccess: "ro"` or `"none"`).
* See [Memory](/concepts/memory) for the workspace file layout and write patterns.

Pi also exposes a `session_before_compact` hook in the extension API, but Fased’s
flush logic lives on the Gateway side today.

***

## Troubleshooting checklist

* Session key wrong? Start with [/concepts/session](/concepts/session) and
  confirm the `sessionKey` in chat `/status` or Agent > Sessions.
* Store vs transcript mismatch? Confirm the Gateway host and the store path from `fased status`.
* Compaction spam? Check:
  * model context window (too small)
  * compaction settings (`reserveTokens` too high for the model window can cause earlier compaction)
  * tool-result bloat: enable/tune session pruning
* Silent turns leaking? Confirm the reply starts with `NO_REPLY` exactly, and
  confirm the build includes the streaming suppression fix.