pi-compaction

High-performance unified context projection and compaction for Pi.

Responsibilities

incrementally index completed tool calls;
replace large tool results with deterministic bounded evidence stubs;
refine large stubs with non-blocking semantic summaries;
expose one effective context projection to normal provider requests and Codex native compaction;
cancel Pi's raw threshold compaction until the effective lower-bound reaches the configured threshold;
retain original tool evidence through context_tree_query;
publish read-only effective metrics for the footer and context observer.

Context Mode remains responsible for preventing large external data from entering the session. RTK remains responsible for ordinary tool-output cleanup.

Configuration

Set piCompaction in the Pi agent settings.json:

{
  "piCompaction": {
    "enabled": true,
    "softRatio": 0.72,
    "hardRatio": 0.9,
    "targetRatio": 0.55,
    "deterministic": {
      "enabled": true,
      "maxStubTokens": 256
    },
    "semantic": {
      "enabled": true,
      "model": "default",
      "thinking": "low",
      "concurrency": 1,
      "minInputChars": 4000,
      "maxInputChars": 24000,
      "maxRetries": 2
    },
    "native": {
      "enabled": true
    }
  }
}

The extension never writes settings. Invalid or missing fields are normalized in memory.

Session format

The only custom entry type is pi-compaction, version 1. Segment summary entries contain hashes, summaries, and source references; they never duplicate complete raw tool output. Native checkpoints use Pi compaction-entry details with the same kind/version.

This implementation intentionally does not read legacy context-prune-* or openai-codex-native-compaction entries. Start a new session after switching to this extension.

Interfaces

context_tree_query: recover original bounded tool evidence by source key or tool call ID.
/compaction-status: show raw/effective tokens, reclaimed tokens, confidence, segments, and pending semantic jobs.

Performance model

The first session hydration scans the branch once. Appended turns use delta projection and immutable cached snapshots. The context hook performs no model call and no session write. Semantic summaries run in a bounded background worker and become visible only at later safe event boundaries.

2.3 KiB Raw Blame History