coderClaw

Session Management & Compaction (Deep Dive)

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

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

Source of truth: the Gateway

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

Two persistence layers

CoderClaw 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:

CoderClaw resolves these via src/config/sessions.ts.

Session keys (sessionKey)

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

Common patterns:

The canonical rules are documented at /concepts/session.

Session ids (sessionId)

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

Rules of thumb:

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):

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:

Notable entry types:

CoderClaw 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 (used for /status and dashboards)

If you’re tuning limits:

For more, see /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:

Compaction is persistent (unlike session pruning). See /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:

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

Compaction settings (reserveTokens, keepRecentTokens)

Pi’s compaction settings live in Pi settings:

{
  compaction: {
    enabled: true,
    reserveTokens: 16384,
    keepRecentTokens: 20000,
  },
}

CoderClaw also enforces a safety floor for embedded runs:

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:

Silent housekeeping (NO_REPLY)

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

Convention:

As of 2026.1.10, CoderClaw also suppresses draft/typing streaming when a partial chunk begins with NO_REPLY, so silent operations don’t leak 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.

CoderClaw 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):

Notes:

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

Troubleshooting checklist

This site is open source. Improve this page.