@reaatech/agent-handoff-compression

Status: Pre-1.0 — APIs may change in minor versions. Pin to a specific version in production.

Context compression strategies for reducing conversation history before agent handoff. Includes three built-in compressors with configurable token budgets and a pluggable interface for custom implementations.

Installation

npm install @reaatech/agent-handoff-compression
# or
pnpm add @reaatech/agent-handoff-compression

Feature Overview

• Three built-in strategies — hybrid, summary, and sliding-window compressors
• Hybrid compression — sliding window + extractive summary + key fact extraction + entity detection + intent identification
• Extractive summarization — sentence scoring by position weight, length penalty, and keyword bonus
• Sliding window — most recent N messages within token budget, newest-first iteration
• Fast token estimation — heuristic CJK/ASCII counter, no external tokenizer required
• Pluggable — inject a custom TokenCounter (e.g. tiktoken) for your LLM's exact tokenizer
• Composable — each compressor implements ContextCompressor from @reaatech/agent-handoff

Quick Start

import {
  HybridCompressor,
  SummaryCompressor,
  SlidingWindowCompressor,
  SimpleTokenCounter,
} from '@reaatech/agent-handoff-compression';

const compressor = new HybridCompressor(new SimpleTokenCounter());

const result = await compressor.compress(messages, {
  maxTokens: 2000,
  preserveRecentMessages: 3,
});

console.log(result.summary);
console.log(`Compression ratio: ${result.compressionRatio}`);
console.log(`Key facts: ${result.keyFacts.length}`);
console.log(`Intents detected: ${result.intents.length}`);

Exports

Compressors

| Export | Strategy | Best For | |---|---|---| | HybridCompressor | Sliding window + summary + key facts + entities + intents | General purpose (default) | | SummaryCompressor | Extractive summarization with sentence scoring | Long conversations needing a condensed overview | | SlidingWindowCompressor | Most recent N messages within token budget | Chat-style agents where recency matters most |

Base Classes & Interfaces

| Export | Description | |---|---| | BaseCompressor | Abstract class with tokenCounter and estimateTokens() | | SimpleTokenCounter | Fast heuristic: CJK chars ≈ 0.67 tokens, ASCII ≈ 0.25 tokens | | TokenCounter | Interface: estimate(text: string): number | | CompressionStrategy | Interface: name, compress(messages, options?) |

Compression Output (CompressedContext)

| Field | Type | Description | |---|---|---| | summary | string | Condensed conversation narrative | | keyFacts | KeyFact[] | Extracted facts with importance scores and source message IDs | | intents | Intent[] | Detected user intents with confidence scores | | entities | Entity[] | Extracted emails, phones, names, organizations | | openItems | OpenItem[] | Pending questions and action items with priority | | originalTokenCount | number | Token count of uncompressed input | | compressedTokenCount | number | Token count of compressed output | | compressionRatio | number | compressed / original (lower = better compression) |

Custom Compressors

Implement the ContextCompressor interface from @reaatech/agent-handoff:

import type { Message, CompressionOptions, CompressedContext } from '@reaatech/agent-handoff';

class LastNCompressor implements ContextCompressor {
  async compress(messages: Message[], options?: CompressionOptions): Promise<CompressedContext> {
    const limit = options?.preserveRecentMessages ?? 10;
    const recent = messages.slice(-limit);

    return {
      summary: recent.map((m) => `${m.role}: ${m.content}`).join('\n'),
      keyFacts: [],
      entities: [],
      intents: [],
      openItems: [],
      compressionMethod: 'last_n',
      originalTokenCount: messages.length,
      compressedTokenCount: recent.length,
      compressionRatio: recent.length / Math.max(1, messages.length),
    };
  }

  estimateTokens(text: string): number {
    return Math.ceil(text.length / 4);
  }
}

Related Packages

• @reaatech/agent-handoff — Core types, errors, utilities
• @reaatech/agent-handoff-routing — Agent routing engine
• @reaatech/agent-handoff-protocol — Full orchestration layer

License

MIT