Compaction
Sliding window, budget tracking, summarization, and key facts extraction.
import {
createSlidingWindow,
createBudgetManager,
extractKeyFacts,
summarizeMessages,
} from "@use-crux/core/compaction";For usage patterns and when to use each primitive, see the Compaction guide.
createSlidingWindow(config)
Rolling window that keeps recent messages and summarizes older ones.
| Field | Type | Description |
|---|---|---|
windowSize | number | Max messages to keep verbatim |
generate | GenerateTextFn | Text generation function |
model | unknown | Model for summarization |
summaryBudget | number? | Max tokens for summary |
storage | Storage? | Persistent records and media assets |
Returns: SlidingWindow
| Method | Description |
|---|---|
.push(message) | Add a message (triggers compression if window overflows) |
.getMessages() | Get current messages (summary + recent window) |
.getStats() | { totalMessages, windowedMessages, summaryTokens, evictions } |
createBudgetManager(config)
Token budget tracker. Reports pressure level but does not compact.
| Field | Type | Description |
|---|---|---|
limit | number | Total token budget |
warningThreshold | number? | Fraction for warning level (default: 0.7) |
criticalThreshold | number? | Fraction for critical level (default: 0.9) |
Returns: BudgetManager
| Method | Description |
|---|---|
.report(category, tokens) | Report token usage in a category |
.check() | Get current budget state (see below) |
.check() returns:
| Property | Type | Description |
|---|---|---|
used | number | Total tokens used |
available | number | Tokens remaining |
pressure | number | Usage fraction (0--1) |
level | 'normal' | 'warning' | 'critical' | Pressure level |
breakdown | Record<string, number> | Tokens per category |
extractKeyFacts(config)
Structured extraction from messages using a Zod schema.
| Field | Type | Description |
|---|---|---|
messages | Message[] | Messages to extract from |
generate | GenerateObjectFn | Structured generation function |
model | unknown | Model to use |
schema | ZodType | Output schema |
Returns: Promise<T>: typed object matching schema.
summarizeMessages(config)
Summarize messages into compact text.
| Field | Type | Description |
|---|---|---|
messages | Message[] | Messages to summarize |
generate | GenerateTextFn | Text generation function |
model | unknown | Model to use |
maxTokens | number? | Max summary tokens (default: 500) |
focus | string[]? | Aspects to prioritize (e.g. ['decisions', 'action-items']) |
Returns: Promise<CompactionResult> with summary, tokensBefore,
tokensAfter, ratio, and the exact outer compaction.run pair in _meta.
Direct summarizeMessages() owns its summary span.
compactConversation() applies the same observed result contract to a
stateless evicted-message batch, including both zero-work paths. Generated work
may call summarizeMessages() as a child, but the returned envelope points at
the outer conversation compaction span. @use-crux/convex re-exports this Core
implementation under the same name. See
Operation Result Correlation.
Types
import type {
GenerateTextFn,
GenerateObjectFn,
CompactionResult,
SlidingWindow,
SlidingWindowConfig,
SlidingWindowStats,
BudgetManager,
BudgetConfig,
BudgetState,
} from "@use-crux/core/compaction";
type GenerateTextFn = (opts: {
model: unknown;
system?: string;
prompt: string;
}) => Promise<{ text: string }>;
type GenerateObjectFn = <T>(opts: {
model: unknown;
system?: string;
prompt: string;
schema: ZodType<T>;
}) => Promise<{ object: T }>;createGenerateObjectFnFromGenerate(generate, options?)
Create a GenerateObjectFn backed by a full adapter generate() function. The bridge builds a synthetic structured prompt from { system, prompt, schema }, calls the supplied adapter generate with { model, input: {} }, and returns result.object.
Use this when a compaction, scoring, retrieval, or Eval API needs the GenerateObjectFn shape and the call should still run through adapter runtime behavior such as prompt hooks, validation retry, safety, memory, or instrumentation.
import { createGenerateObjectFnFromGenerate } from "@use-crux/core/compaction";
import { generate } from "@use-crux/ai";
const generateObject = createGenerateObjectFnFromGenerate(generate, {
promptId: "scoring.judge",
});Related
- Guide: Compaction
- Cookbook: Chat with memory