useAIChatCompression

⚠️ Internal API: useAIChatCompression is not part of the public entry point. It exists so ChatContainer/ChatPopout can coordinate compression state. Depend on it only if you are mirroring the internals for a custom container and can absorb breaking changes.

The hook normalises a CompressionConfig, keeps the compression store in sync, and exposes the controller that manages pinned messages, artifacts, and token usage.

Signature

function useAIChatCompression(
  options?: { compression?: CompressionConfig }
): {
  config: NormalizedCompressionConfig;
  controller: CompressionController;
  buildPayload: (
    messages: UIMessage[],
    options?: CompressionRunOptions
  ) => Promise<BuildCompressionPayloadResult>;
};

The compression object matches the configuration used by ChatContainer.

What you get back

• config – Normalised settings with defaults applied.
• controller – Live state (usage, pinnedMessages, artifacts, snapshot) plus mutators such as pinMessage, clearArtifacts, and runCompression.
• buildPayload(messages, options?) – Helper that assembles the payload sent to your compression endpoint. It merges pinned messages and artifacts before optionally POSTing via the configured fetcher.

Tip: Prefer controller.runCompression unless you need to inspect the payload yourself.

Manual compression button

function ManualCompressionControl() {
  const chat = useAIChat({ compression: { enabled: true, maxTokenBudget: 16_000 } });
  const { controller } = useAIChatCompression();
 
  const handleClick = async () => {
    if (!controller.config.enabled) return;
    await controller.runCompression?.({ force: true });
  };
 
  return (
    <button type="button" onClick={handleClick} disabled={chat.messages.length === 0}>
      Compress history
    </button>
  );
}

CompressionConfig cheatsheet

• enabled – master toggle.
• api – endpoint consumed by createCompressionHandler.
• maxTokenBudget / compressionThreshold – drive the overBudget and shouldCompress flags.
• pinnedMessageLimit – cap per-thread pins.
• model, onCompression, onError, fetcher – customise backend behaviour.

Pair this hook with the server template to keep transcripts within budget while giving users artifact review and pin management.