pi-smart-compaction

Native-lifecycle compaction for Pi 0.83+: choose a dedicated local summary model and optionally reuse OpenAI Responses compaction artifacts.

How it works

Pi remains the sole owner of compaction timing. The extension does not add threshold checks, compact between tool calls, create shadow checkpoints, or start synthetic continuations. Pi's existing compaction.enabled, reserveTokens, and keepRecentTokens settings decide when automatic compaction runs, and /compact continues to use Pi's native lifecycle.

When Pi starts a compaction:

1. If compaction.json selects a different model or reasoning effort, the extension asks that target to generate Pi's portable summary.
2. If that attempt fails, the extension returns control to Pi, which runs its built-in compaction once with the current session model.
3. If no override is configured, or the configured target exactly matches Pi's built-in target, Pi handles the local summary directly.

For models using the openai + openai-responses or openai-codex + openai-codex-responses pairing, the extension also starts Responses compaction v2 from the same native branch snapshot. A successful artifact is attached to the completed Pi compaction and preferred for compatible provider requests. The normal Pi summary remains canonical and is used when the latest compaction has no compatible artifact. Focused /compact <instructions> requests stay local-only because the remote protocol cannot preserve Pi's custom summary focus.

| Working provider | Portable summary | Optional request replay | |---|---|---| | openai + openai-responses, or openai-codex + openai-codex-responses | Configured target, then Pi built-in | Responses compaction v2 artifact | | Other providers | Configured target, then Pi built-in | None |

Install

From npm:

pi install npm:@kky42/pi-smart-compaction

Or from GitHub:

pi install git:github.com/kky42/pi-smart-compaction

Configure

Create ~/.pi/agent/compaction.json:

{
  "model": "deepseek/deepseek-v4-flash",
  "reasoningEffort": "high"
}

Both fields are optional:

• model uses a provider/model selector.
• reasoningEffort accepts off, minimal, low, medium, high, xhigh, or max and is clamped to the selected model.
• Omitted fields inherit the current session target.
• Missing or empty configuration leaves local compaction entirely to Pi.

Remote attempts start alongside local compaction. After Pi finishes the formal local compaction, an unfinished remote attempt gets at most a 2-minute completion grace period. If the grace period expires, or Pi cancels the compaction, the extension aborts remote authentication and transport, discards any artifact, and continues with the local summary.

"Local" means a portable Pi summary, not necessarily an on-device model. The selected compaction model receives the context being summarized. Eligible OpenAI or Codex sessions also send that context to their current Responses endpoint to create the optional remote artifact. Eligibility uses only provider and API type; custom baseUrl values are not filtered.

Fallback behavior

• Configured local success: Pi commits that CompactionResult.
• Configured local failure: Pi runs its built-in compaction once.
• Remote failure: local compaction continues normally and no artifact is attached.
• Remote replay failure: the current request fails normally; the extension does not classify the error, retry it, or disable the artifact. A later compatible request reuses the artifact.
• Cancellation: the extension cancels instead of starting another fallback request.

Existing sessions containing old pi-smart-compaction-shadow entries remain readable. Those entries are no longer generated or used as context.

Live validation

The unit and smoke suite runs without provider access:

npm test

Run the deterministic Pi RPC lifecycle integration with a local transport:

npm run test:integration

Run the opt-in real-provider RPC matrix with existing Pi credentials:

PI_SMART_COMPACTION_LIVE=1 npm run test:live