Context Management

Overview

Effective context management is crucial for AI agent performance. Maestro provides tools to manage context size, transfer context between agents, and groom context for optimal efficiency.

Context Management Settings

Configure context behavior in Settings > Context Management:

interface ContextManagementSettings {
  // Auto-grooming settings
  autoGroomingEnabled: boolean;
  autoGroomingThreshold: number;  // Token count threshold
  
  // Context transfer settings
  enableContextTransfer: boolean;
  transferFormat: 'full' | 'summary';
  
  // Session storage settings
  maxStoredSessions: number;
  sessionRetentionDays: number;
}

Session Storage

Maestro automatically stores session messages for each agent type, enabling context persistence and transfer.

Supported Agents

Each agent has its own session storage implementation:

Claude Code - Stores session in .claude_code/sessions/
OpenCode - Stores session data in agent-specific format
Codex - Maintains OpenAI conversation history
Factory Droid - Custom session storage

Session Data Structure

Message Format
Session Result

interface SessionMessage {
  role: 'user' | 'assistant' | 'system';
  content: string;
  timestamp: number;
  metadata?: {
    tokens?: number;
    model?: string;
    tool_use?: any[];
  };
}

interface SessionMessagesResult {
  messages: SessionMessage[];
  total: number;
  sessionId: string;
  agentId: string;
}

Context Grooming

Context grooming spawns a temporary agent process to summarize conversation history. This reduces token usage while preserving key information.

How It Works

Detect Large Context

Maestro monitors context size and alerts when approaching token limits.

Spawn Grooming Session

A batch-mode agent process is created with read-only access to analyze the context.

Generate Summary

The agent generates a concise summary of the conversation, preserving:

Key decisions and conclusions
Important code changes
Unresolved issues
Action items

Replace Context

The original context is replaced with the summary, freeing up tokens for new conversation.

Grooming API

// Single-call grooming (recommended)
const result = await window.maestro.context.groomContext(
  projectRoot: string,
  agentType: string,
  prompt: string,
  options?: {
    sshRemoteConfig?: SshRemoteConfig;
    customPath?: string;
    customArgs?: string;
    customEnvVars?: Record<string, string>;
  }
);

// Returns: string (groomed summary)

Grooming Configuration

Timeout Settings

Default Timeouts:

Overall timeout: 5 minutes
Idle timeout: 5 seconds (with min 100 char response)
Connection timeout: 10 seconds

Grooming operations automatically cancel if they exceed these limits.

SSH Remote Support

Context grooming fully supports SSH remote execution:

const result = await window.maestro.context.groomContext(
  '/path/to/project',
  'claude-code',
  'Summarize this conversation focusing on key decisions',
  {
    sshRemoteConfig: {
      enabled: true,
      remoteId: 'my-server',
      workingDirOverride: '/remote/path'
    }
  }
);

Batch Mode Processing

Grooming uses batch mode (non-interactive) agent execution:

No PTY allocation
Direct stdin/stdout communication
Uses --print --output-format stream-json for Claude Code
Collects response until process exits or idle timeout

Context Transfer

Transfer context from one agent to another to continue work with a different AI model.

Transfer Workflow

Select Source Session

In the source agent, choose the session/tab to transfer.

Initiate Transfer

Use the context menu or keyboard shortcut to start the transfer.

Choose Destination

Select the target agent and optionally groom the context before transfer.

Verify Transfer

The context appears in the destination agent with a summary header.

Retrieving Stored Sessions

// Get session context from storage
const session = await window.maestro.context.getStoredSession(
  agentId: string,
  projectRoot: string,
  sessionId: string
);

if (session) {
  console.log(`Retrieved ${session.messages.length} messages`);
  console.log(`Total: ${session.total}`);
}

Context Optimization Tips

Follow these best practices to maintain optimal context size:

1. Use Read-Only Mode for Analysis

Enable read-only mode (Cmd+R) when asking the agent to review or analyze:

# Good: Read-only analysis
"Review this codebase architecture" (in read-only mode)

# Avoid: Analysis in edit mode
"Review this codebase architecture" (in edit mode)

2. Leverage Session History

Use the /history command to create checkpoints:

/history

This generates a summary and adds it to the History tab, allowing you to start fresh while preserving the context.

3. Start New Tabs for New Topics

Don’t cram unrelated tasks into a single conversation:

New Tab (Cmd+T) for each distinct task
Star Important Tabs (Cmd+Shift+S) to keep them accessible
Close Completed Tabs (Cmd+W) to reduce clutter

4. Groom Before Major Changes

Before starting a large refactoring or feature:

Groom the current context to summarize decisions
Start a new tab for the new work
Reference the summary if needed

Advanced Context Patterns

Group Chat Context

Group Chat manages context across multiple agents simultaneously, with automatic context grooming between rounds.

When using Group Chat:

Each agent receives context from previous agents
Context is automatically groomed after each round
Summary preserves key insights from all agents

Auto Run Context

Auto Run documents maintain their own context:

Phase context is isolated to each phase
Task context builds on phase context
Document-level context available to all phases

Monitoring Context Usage

Watch for these signs that context needs grooming:

Agent responses becoming slower
“Context limit” warnings in output
Degraded response quality
Agent forgetting earlier conversation details

Context Cancellation

Cancel ongoing grooming operations:

// Cancel all active grooming sessions
await window.maestro.context.cancelGrooming();

Useful when:

Grooming takes too long
You need to modify the grooming prompt
You want to transfer context without grooming

Next Steps

Explore Slash Commands for context-aware automation
Learn about SSH Remote Execution for remote context grooming
Review Configuration for context management settings

Usage Guides

Advanced

Context Management

Overview