Super Agent Stack
DocsHome

Message Transforms

Automatically compress long conversations to fit within model context limits using intelligent middle-out compression.

What are Message Transforms?

Message transforms automatically process your conversation history to fit within model context windows. The most common transform is "middle-out" compression, which preserves the beginning and end of conversations while removing middle content.

❌ Without Transforms

Long conversations exceed context limits and fail

✅ With Middle-Out

Conversations are intelligently compressed to fit

How Middle-Out Compression Works

Middle-out compression preserves the most important parts of a conversation:

KeptSystem message and initial context
KeptFirst few user/assistant exchanges
RemovedMiddle portion of conversation
KeptRecent messages and current query

This approach works well because the beginning establishes context and the end contains the most relevant recent information.

Basic Usage

message-transforms.ts
import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: 'https://www.superagentstack.com/api/v1',
  apiKey: process.env.OPENROUTER_KEY,
  defaultHeaders: { 'superAgentKey': process.env.SUPER_AGENT_KEY },
});

// Long conversation that might exceed context limits
const longConversation = [
  { role: 'system', content: 'You are a helpful assistant.' },
  { role: 'user', content: 'Let me tell you about my project...' },
  { role: 'assistant', content: 'I would love to hear about it!' },
  // ... many more messages ...
  { role: 'user', content: 'Based on everything we discussed, what should I do next?' }
];

const response = await client.chat.completions.create({
  model: 'openai/gpt-4o',
  messages: longConversation,
  // @ts-expect-error - OpenRouter extension
  transforms: ['middle-out']  // Enable automatic compression
});

console.log(response.choices[0].message.content);

Disabling Automatic Transforms

Some models with smaller context windows (8k or less) have automatic compression enabled by default. You can disable this if you want to manage context yourself.

disable-transforms.ts
const response = await client.chat.completions.create({
  model: 'openai/gpt-4o-mini',
  messages: shortConversation,
  // @ts-expect-error - OpenRouter extension
  transforms: []  // Empty array disables automatic transforms
});

// If the conversation exceeds context limits, you'll get an error
// instead of automatic compression

Context Limit Errors

When transforms are disabled and your conversation exceeds the model's context limit, you'll receive an error. Consider enabling middle-out compression or manually truncating your messages.

When to Use Message Transforms

ScenarioRecommendation
Long chat sessions✅ Enable middle-out
Document analysis with history✅ Enable middle-out
Short, single-turn queries❌ Not needed
Every message is critical❌ Disable and manage manually
Using models with large context⚠️ Optional, but good for safety

Combining with Super Agent Stack Memory

Message transforms work alongside Super Agent Stack's memory system. The memory system handles long-term context, while transforms handle immediate conversation compression.

transforms-with-memory.ts
const response = await client.chat.completions.create({
  model: 'openai/gpt-4o',
  messages: [
    { role: 'user', content: 'Continue our discussion from yesterday' }
  ],
  // @ts-expect-error - OpenRouter/Super Agent Stack extensions
  transforms: ['middle-out'],  // Compress if needed
  sessionId: 'user-123',       // Load conversation history from memory
  useRAG: true                 // Also search uploaded documents
});

// The AI will:
// 1. Load previous conversation from memory (sessionId)
// 2. Search relevant documents (useRAG)
// 3. Compress if total context exceeds limits (transforms)
// 4. Generate response with full context

curl Example

bash
curl -X POST https://www.superagentstack.com/api/v1/chat/completions \
  -H "Authorization: Bearer $OPENROUTER_KEY" \
  -H "superAgentKey: $SUPER_AGENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "Long conversation message 1..."},
      {"role": "assistant", "content": "Response 1..."},
      {"role": "user", "content": "What did we discuss?"}
    ],
    "transforms": ["middle-out"]
  }'

Best Practices

Use for Long Sessions

Enable middle-out compression for any application with extended conversations to prevent unexpected context limit errors.

Important Information at Edges

Place critical information at the beginning (system message) or end (recent messages) of your conversation, as middle content may be compressed.

Combine with Memory

Use Super Agent Stack's memory system for long-term context and transforms for immediate conversation management.

Next Steps