🗜️ Context Compression Showcase

Demonstrates Autonomous Context Compression in OrkaJS - letting agents decide when to compress their conversation history instead of relying on fixed token thresholds.

Features

• Autonomous Compression: Agent decides when to compress context at clean task boundaries
• Real-time Visualization: See compression events, token savings, and summaries live
• Multi-turn Conversations: Test with long conversations that would normally exceed context limits
• Metrics Dashboard: Track messages compressed, tokens saved, and compression history

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                         Frontend (Next.js)                       │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────────┐  │
│  │   Chat UI   │  │  Metrics    │  │   Compression History   │  │
│  │             │  │  Dashboard  │  │   Timeline              │  │
│  └──────┬──────┘  └──────┬──────┘  └───────────┬─────────────┘  │
│         │                │                      │                │
│         └────────────────┴──────────────────────┘                │
│                          │                                       │
└──────────────────────────┼───────────────────────────────────────┘
                           │ HTTP/WebSocket
┌──────────────────────────┼───────────────────────────────────────┐
│                          ▼                                       │
│                    Backend (Express)                             │
│  ┌─────────────────────────────────────────────────────────────┐ │
│  │                    ReActAgent                                │ │
│  │  ┌─────────────┐  ┌─────────────────────────────────────┐   │ │
│  │  │   Tools     │  │         SummaryMemory               │   │ │
│  │  │  - search   │  │  ┌─────────────────────────────┐    │   │ │
│  │  │  - calc     │  │  │   compress() method         │    │   │ │
│  │  │  - compact  │◄─┼──│   (autonomous compression)  │    │   │ │
│  │  └─────────────┘  │  └─────────────────────────────┘    │   │ │
│  │                   └─────────────────────────────────────┘   │ │
│  └─────────────────────────────────────────────────────────────┘ │
│                          │                                       │
│                          ▼                                       │
│                    OpenAI API                                    │
└──────────────────────────────────────────────────────────────────┘

Quick Start

1. Install Dependencies

# Backend
cd backend && npm install

# Frontend
cd ../frontend && npm install

2. Configure Environment

# Backend
cp backend/.env.example backend/.env
# Add your OPENAI_API_KEY

3. Run the Application

# Terminal 1: Backend
cd backend && npm run dev

# Terminal 2: Frontend
cd frontend && npm run dev

Open http://localhost:3010 to see the demo.

OrkaJS Code Highlights

import { ReActAgent, createCompactConversationTool } from '@orka-js/agent';
import { SummaryMemory } from '@orka-js/memory-store';
import { OpenAIAdapter } from '@orka-js/openai';

const llm = new OpenAIAdapter({ apiKey: process.env.OPENAI_API_KEY });
const memory = new SummaryMemory({ llm, maxMessages: 100 });

// Create the autonomous compression tool
const compactTool = createCompactConversationTool({
  compress: async () => {
    const result = await memory.compress();
    return {
      success: result.success,
      reason: result.reason,
      summary: result.summary,
      messagesCompressed: result.messagesCompressed,
      tokensSaved: result.tokensSaved,
      compressedAt: result.compressedAt,
    };
  },
});

// Agent can now autonomously decide when to compress
const agent = new ReActAgent({
  llm,
  goal: 'Help users with complex tasks while managing context efficiently',
  tools: [compactTool, searchTool, calculatorTool],
  systemPrompt: `You are a helpful assistant with access to a compact_conversation tool.
Use it proactively when:
- The conversation becomes lengthy
- You're transitioning to a new task
- You notice repetitive context`,
});

API Endpoints

Method	Endpoint	Description
POST	/api/chat	Send a message and get agent response
GET	/api/metrics	Get compression metrics and history
POST	/api/compress	Manually trigger compression
DELETE	/api/clear	Clear conversation history

Environment Variables

Variable	Description	Required
OPENAI_API_KEY	OpenAI API key	Yes
PORT	Backend port (default: 4010)	No

License

MIT - Part of the OrkaJS Showcase collection.