# Context
URL: /docs/framework/context
Source: /app/src/content/docs/framework/context.mdx

import { DocImage } from '@/components/DocImage';

<DocImage title="Context" />

import { Step, Steps } from 'fumadocs-ui/components/steps';

**Smart context management for long conversations with automatic compression**

## Overview

Auto context compression in Astreus provides intelligent conversation management by automatically handling long conversation histories. The system compresses older messages while preserving important information, ensuring agents can maintain coherent long conversations without exceeding model token limits.

## Basic Usage

Enable auto context compression to get automatic conversation management:

```typescript
import { Agent } from '@astreus-ai/astreus';

// Create an agent with auto context compression enabled
const agent = await Agent.create({
  name: 'ContextAwareAgent',
  model: 'gpt-4o',
  autoContextCompression: true  // Enable smart context management
});

// Long conversations are automatically managed
for (let i = 1; i <= 50; i++) {
  const response = await agent.ask(`Tell me fact #${i} about TypeScript`);
  console.log(`Fact ${i}:`, response);
}

// Agent can still reference early conversation through compressed context
const summary = await agent.ask('What was the first fact you told me?');
console.log(summary); // System retrieves from compressed context
```

## Example with Tasks

Auto context compression works with both direct conversations and tasks:

```typescript
const agent = await Agent.create({
  name: 'ResearchAgent',
  model: 'gpt-4o',
  autoContextCompression: true,
  memory: true // Often used together with memory
});

// Create multiple related tasks
const task1 = await agent.createTask({
  prompt: "Research the latest trends in AI development"
});

const result1 = await agent.executeTask(task1.id);

const task2 = await agent.createTask({
  prompt: "Based on the research, what are the key opportunities?"
});

const result2 = await agent.executeTask(task2.id);
// Task can reference previous context even if it was compressed
```

Auto context compression ensures agents can handle conversations and tasks of any length while maintaining coherence and staying within token limits.

## Configuration Options

You can customize the auto context compression behavior with these parameters:

```typescript
const agent = await Agent.create({
  name: 'CustomContextAgent',
  model: 'gpt-4o',
  autoContextCompression: true,
  
  // Context compression configuration
  maxContextLength: 4000,           // Trigger compression at 4000 tokens
  preserveLastN: 5,                 // Keep last 5 messages uncompressed
  compressionRatio: 0.4,            // Target 40% size reduction
  compressionStrategy: 'hybrid',    // Use hybrid compression strategy
  
  memory: true,
});
```

### Configuration Parameters

| Parameter                | Type      | Default    | Description                                    |
| ------------------------ | --------- | ---------- | ---------------------------------------------- |
| `autoContextCompression` | `boolean` | `false`    | Enable automatic context compression           |
| `maxContextLength`       | `number`  | `8000`     | Token limit before compression triggers        |
| `preserveLastN`          | `number`  | `3`        | Number of recent messages to keep uncompressed |
| `compressionRatio`       | `number`  | `0.3`      | Target compression ratio (0.1 = 90% reduction) |
| `compressionStrategy`    | `string`  | `'hybrid'` | Compression algorithm to use                   |

### Compression Mathematics

The compression ratio determines how much the context is reduced:

$\text{Compression Ratio} = \frac{\text{compressed tokens}}{\text{original tokens}}$

For example, with a ratio of 0.3:

* Original: 1000 tokens
* Compressed: 300 tokens
* **Reduction: 70%**

The token reduction percentage is calculated as:
$\text{Reduction \%} = (1 - \text{ratio}) \times 100\%$

With `compressionRatio = 0.3`:
$\text{Reduction} = (1 - 0.3) \times 100\% = 70\%$

### Compression Strategies

Choose the compression strategy that best fits your use case:

#### `'summarize'` - Text Summarization

* **Best for**: General conversations, Q\&A, discussions
* **How it works**: Creates concise summaries of message groups
* **Pros**: Maintains context flow, good for most use cases
* **Cons**: May lose specific details

```typescript
const agent = await Agent.create({
  name: 'SummarizingAgent',
  autoContextCompression: true,
  compressionStrategy: 'summarize',
  preserveLastN: 4
});
```

#### `'selective'` - Important Message Selection

* **Best for**: Task-oriented conversations, technical discussions
* **How it works**: Uses AI to identify and preserve important messages
* **Pros**: Keeps crucial information intact
* **Cons**: May be more resource intensive

```typescript
const agent = await Agent.create({
  name: 'SelectiveAgent',
  autoContextCompression: true,
  compressionStrategy: 'selective',
  preserveLastN: 3
});
```

#### `'hybrid'` - Combined Approach (Recommended)

* **Best for**: Most applications, balanced approach
* **How it works**: Combines summarization and selective preservation
* **Pros**: Balanced between context preservation and efficiency
* **Cons**: None significant

```typescript
const agent = await Agent.create({
  name: 'HybridAgent',
  autoContextCompression: true,
  compressionStrategy: 'hybrid', // Default and recommended
});
```

## Advanced Usage

### Custom Compression Settings by Use Case

#### High-Frequency Conversations

For chatbots or interactive agents with many short messages:

```typescript
const chatbot = await Agent.create({
  name: 'Chatbot',
  autoContextCompression: true,
  maxContextLength: 2000,     // Compress more frequently
  preserveLastN: 8,           // Keep more recent messages
  compressionRatio: 0.5,      // More aggressive compression
  compressionStrategy: 'summarize'
});
```

#### Long-Form Content Creation

For agents working with detailed content:

```typescript
const writer = await Agent.create({
  name: 'ContentWriter',
  autoContextCompression: true,
  maxContextLength: 12000,    // Allow longer context
  preserveLastN: 3,           // Keep recent context tight
  compressionRatio: 0.2,      // Gentle compression
  compressionStrategy: 'selective'
});
```

#### Technical Documentation

For agents handling complex technical discussions:

```typescript
const techAgent = await Agent.create({
  name: 'TechnicalAssistant',
  autoContextCompression: true,
  maxContextLength: 6000,
  preserveLastN: 5,           
  compressionRatio: 0.3,      
  compressionStrategy: 'hybrid' // Best for mixed content
});
```

## How Context Compression Works

### Compression Process

<Steps>
  <Step>
    **Token Monitoring**: Agent continuously monitors total token count in conversation
  </Step>

  <Step>
    **Trigger Point**: When tokens exceed `maxContextLength`, compression is triggered
  </Step>

  <Step>
    **Message Preservation**: Recent `preserveLastN` messages are kept uncompressed
  </Step>

  <Step>
    **Content Analysis**: Older messages are analyzed based on chosen strategy
  </Step>

  <Step>
    **Compression**: Messages are compressed into summaries or selections
  </Step>

  <Step>
    **Context Update**: Compressed context replaces original messages
  </Step>
</Steps>

### What Gets Preserved

* **System prompts**: Always preserved
* **Recent messages**: Last N messages based on `preserveLastN`
* **Important context**: Key information identified by the compression strategy
* **Compressed summaries**: Condensed versions of older conversations

### Example Compression Flow

```typescript
// Before compression (1200 tokens)
[
  { role: 'user', content: 'Tell me about TypeScript' },
  { role: 'assistant', content: 'TypeScript is...' },
  { role: 'user', content: 'What about interfaces?' },
  { role: 'assistant', content: 'Interfaces in TypeScript...' },
  { role: 'user', content: 'Show me an example' },
  { role: 'assistant', content: 'Here\'s an example...' },
]

// After compression (400 tokens)
[
  { role: 'system', content: '[Compressed] User asked about TypeScript basics, interfaces, and examples. Assistant provided comprehensive explanations...' },
  { role: 'user', content: 'Show me an example' },
  { role: 'assistant', content: 'Here\'s an example...' },
]
```

## Monitoring and Debugging

### Context Window Information

Get details about the current context state:

```typescript
const contextWindow = agent.getContextWindow();

console.log({
  messageCount: contextWindow.messages.length,
  totalTokens: contextWindow.totalTokens,
  maxTokens: contextWindow.maxTokens,
  utilization: `${contextWindow.utilizationPercentage.toFixed(1)}%`
});

// Check if compression occurred
const hasCompression = contextWindow.messages.some(
  msg => msg.metadata?.type === 'summary'
);
console.log('Context compressed:', hasCompression);
```

### Context Analysis

Analyze context for optimization opportunities:

```typescript
const analysis = agent.analyzeContext();

console.log({
  compressionNeeded: analysis.compressionNeeded,
  averageTokensPerMessage: analysis.averageTokensPerMessage,
  suggestedCompressionRatio: analysis.suggestedCompressionRatio
});
```