Cachepoint

Cachepoint is a pi extension that automatically creates a compact session checkpoint shortly before the model provider's prompt cache is expected to expire.

Unlike pi's normal standalone compaction request, Cachepoint asks the current model to summarize the current native conversation. The request extends the same prompt prefix with a final summary instruction, allowing the provider to reuse that prefix from its prompt cache.

I built this extension to optimize the use of prompt caches and to feel less stressed to continue my sessions within the cache time. If you sometimes want to continue with the full original context you can always just jump back to it via the pi builtin /tree command.

Cachepoint supports pi's built-in openai (API key), openai-codex (ChatGPT Plus/Pro), anthropic (API key or Claude Pro/Max), and kimi-coding (API key or Kimi Code subscription) providers.

How it works

1. Watches successful supported-provider requests, including Codex WebSocket responses.
2. Arms an inactivity timer using the provider's effective cache-retention policy.
3. At the deadline, checks that pi is idle and the context exceeds the minimum size.
4. Runs a shadow summary request with the same model, system prompt, conversation, tools, session ID, effective request headers, transport family, and cache-retention setting.
5. Supplies the response through session_before_compact, so pi persists it as a normal compaction checkpoint and retains the configured recent tail.

The footer countdown appears only during the final minute before an automatic Cachepoint and only when the context has reached the configured minimum-token threshold. While visible, it updates once per second.

The summary instruction and response are not appended as ordinary conversation messages.

Install

pi install npm:pi-cachepoint

Commands

• /cachepoint-status — show provider support, context size, retention policy, and timer state.

Configuration flags

--cachepoint-min-tokens <tokens>       default: 50000
--cachepoint-max-summary-tokens <tokens> default: 8192
--cachepoint-debug

For the direct openai provider, pi maps PI_CACHE_RETENTION=long to OpenAI's supported 24-hour retention policy. Cachepoint reads the same setting:

PI_CACHE_RETENTION=long pi --no-extensions -e ./pi-cachepoint

The openai-codex transport supports a prompt cache key but does not expose the direct API's 24-hour retention parameter, so Cachepoint always uses the short in-memory schedule for Codex.

For anthropic, short retention uses Anthropic's five-minute cache and PI_CACHE_RETENTION=long uses the one-hour cache. The Anthropic long-TTL schedule is configured separately from OpenAI's 24-hour schedule.

kimi-coding performs automatic prefix caching but does not expose a caller-controlled retention setting. Its cache has been observed to remain warm for at least five minutes, so Cachepoint always uses the conservative short schedule for Kimi, regardless of PI_CACHE_RETENTION.

Safety behavior

Cachepoint:

• cancels a pending schedule as soon as the user submits a new prompt, then waits for that prompt's successful provider response before scheduling again;
• runs only while pi is idle and has no queued messages;
• clears pending state when session-tree navigation changes the active branch;
• skips automatic compaction once the assumed cache TTL has elapsed;
• uses the current model and thinking level;
• disables tool calls using the provider's native tool_choice shape while preserving tool definitions for cache-prefix stability;
• refuses tool-call, empty, errored, interrupted, or truncated summary responses;
• cancels rather than falling back to an uncached normal compaction if its custom summary fails;
• skips automatic compaction when context headroom is insufficient;
• reports a warning when the provider reports zero cache-read tokens.

Current limitations

Prompt-cache reuse requires an exact provider prefix. Cachepoint reconstructs the current native request from pi's public extension APIs and preserves the last serialized provider tool list, but a hit cannot be guaranteed. In particular, cache reuse may be reduced by:

• provider-side eviction before the documented retention window;
• laptop sleep or pi exiting before the timer fires;
• other extensions that modify context or provider payloads after Cachepoint's handlers;
• model, system-prompt, or active-tool changes;
• provider behavior changes;
• prompts below the provider/model's cache eligibility threshold.

OpenAI's in-memory cache generally lasts 5–10 minutes of inactivity rather than exposing an exact expiry timestamp. Anthropic documents a five-minute short TTL and a one-hour extended TTL. Cachepoint conservatively assumes five minutes for short retention and triggers one minute early. The same short schedule is used for OpenAI Codex and Kimi Coding because their transports do not expose a caller-controlled expiry signal.

The summary request can itself create a new cache entry that is unlikely to be reused after compaction. The expected saving comes from reading the large existing prefix at the cached-input rate and making subsequent resumed contexts much smaller.