Skip to main content

Agent Context Management

Efficiently manage context windows for your Agents. Budget tokens, prioritize content, and optimize long conversations.

ContextManager - Core Usage

import { ContextManager, createContextManager } from 'praisonai';

// Create a context manager with token budget
const context = createContextManager({
  maxTokens: 4000,
  tokenRatio: 4  // ~4 chars per token
});

// Add context items with priorities
context.add({
  content: 'User prefers concise answers',
  priority: 0.9,  // High priority (0-1)
  type: 'system'
});

context.add({
  content: 'Previous conversation about TypeScript...',
  priority: 0.7,
  type: 'history'
});

context.add({
  content: 'Technical documentation reference...',
  priority: 0.5,
  type: 'retrieval'
});

// Build context string for LLM (respects budget)
const contextString = context.build();
console.log(`Context: ${context.getTokenCount()} tokens`);

Use with Agent

import { Agent, createContextManager } from 'praisonai';

const contextManager = createContextManager({ maxTokens: 4000 });

// Add system context
contextManager.add({
  content: 'You are a helpful coding assistant.',
  priority: 1.0,
  type: 'system'
});

const agent = new Agent({
  name: 'Code Helper',
  instructions: contextManager.build()
});

await agent.chat('Help me with TypeScript');

Context Budgeter

Budget tokens across multiple context sources:
import { ContextBudgeter, createContextBudgeter } from 'praisonai';

const budgeter = createContextBudgeter({
  totalBudget: 8000,
  responseReserve: 2000,  // Reserve for response
  strategy: 'priority'   // priority | proportional | fixed
});

// Allocate budget for different sources
const systemAlloc = budgeter.allocate('system', 500, 10);  // High priority
const historyAlloc = budgeter.allocate('history', 2000, 5);
const ragAlloc = budgeter.allocate('rag', 3000, 3);

// Use tokens from allocations
budgeter.use(systemAlloc.id, 300);
budgeter.use(historyAlloc.id, 1500);

// Check remaining
console.log('Available:', budgeter.getAvailable());
console.log('Stats:', budgeter.getStats());

Context Optimizer

Optimize context when it exceeds budget:
import { ContextOptimizer, createContextOptimizer } from 'praisonai';

const optimizer = createContextOptimizer({
  targetTokens: 4000,
  strategies: ['truncate-low-priority', 'deduplicate', 'compress'],
  tokenRatio: 4
});

// Items to optimize
const items = [
  { id: '1', content: 'Important system prompt', priority: 1.0, timestamp: Date.now() },
  { id: '2', content: 'Older conversation...', priority: 0.3, timestamp: Date.now() - 100000 },
  { id: '3', content: 'Duplicate info...', priority: 0.5, timestamp: Date.now() - 50000 },
];

const result = await optimizer.optimize(items);

console.log('Optimization Result:');
console.log(`  Strategy: ${result.strategy}`);
console.log(`  Tokens saved: ${result.tokensSaved}`);
console.log(`  Items kept: ${result.optimized.length}`);
console.log(`  Items removed: ${result.removed.length}`);

Optimization Strategies

StrategyDescription
truncate-oldRemove oldest items first
truncate-low-priorityRemove lowest priority items
deduplicateRemove similar content
compressShorten all content
summarizeSummarize into single item

Complete Example

import { 
  Agent, 
  ContextManager, 
  ContextBudgeter, 
  ContextOptimizer 
} from 'praisonai';

async function createOptimizedAgent() {
  const budgeter = new ContextBudgeter({ totalBudget: 8000 });
  const context = new ContextManager({ maxTokens: 6000 });
  const optimizer = new ContextOptimizer({ targetTokens: 5000 });
  
  // Add context items
  context.add({ content: 'System instructions...', priority: 1.0, type: 'system' });
  context.add({ content: 'User history...', priority: 0.6, type: 'history' });
  context.add({ content: 'Retrieved docs...', priority: 0.4, type: 'rag' });
  
  // Optimize if needed
  if (context.getTokenCount() > 5000) {
    const optimized = await optimizer.optimize(context.getItems());
    context.clear();
    optimized.optimized.forEach(item => context.add(item));
  }
  
  const agent = new Agent({
    name: 'Optimized Agent',
    instructions: context.build()
  });
  
  return agent;
}
  • Memory - Agent memory systems
  • Sessions - Conversation persistence
  • RAG - Retrieval augmented generation