Agent Context Management

Purpose

This skill enables agents to understand their own capabilities, manage context efficiently, and format responses appropriately for their specific platform (Claude, GPT-4, etc.).

Key capabilities:

• Auto-detect what type of agent is running
• Understand agent-specific capabilities and limitations
• Calculate token budgets and context usage
• Format responses optimally for each agent type
• Manage multi-turn conversation context

When to Use

Use this skill when you need to:

• Detect what agent/model is running the code
• Check agent capabilities (tool use, vision, code execution, etc.)
• Calculate remaining token budget
• Format responses for specific agents
• Optimize context usage in long conversations
• Handle agent-specific features or limitations

Available Hooks

sqlite.context.detect

Auto-detect the current agent type and version.

Parameters:

• hints (object, optional): Detection hints
  • userAgent (string): User agent string
  • environment (object): Environment variables
  • capabilities (array): Known capabilities

Returns:

• type (string): Agent type (e.g., 'claude-code', 'gpt-4', 'gpt-3.5-turbo')
• version (string): Agent version
• capabilities (array): Detected capabilities
• confidence (number): Detection confidence (0-1)

Example:

const agent = await fixiplug.dispatch('sqlite.context.detect');

console.log(agent.type);  // 'claude-code'
console.log(agent.version);  // '3.5-sonnet-20241022'
console.log(agent.capabilities);
// [
//   'tool-use',
//   'vision',
//   'code-execution',
//   'file-editing',
//   'artifacts',
//   'extended-thinking'
// ]
console.log(agent.confidence);  // 0.98

// Agent-specific logic
if (agent.type.startsWith('claude')) {
  console.log('Using Claude-specific formatting');
} else if (agent.type.startsWith('gpt')) {
  console.log('Using GPT-specific formatting');
}

sqlite.context.capabilities

Get detailed capabilities for a specific agent type.

Parameters:

• agentType (string, required): Agent type (e.g., 'claude-3-5-sonnet', 'gpt-4')
• includeDetails (boolean, optional): Include detailed capability info (default: false)

Returns:

• agentType (string): Agent type
• maxTokens (number): Maximum context tokens
• maxOutputTokens (number): Maximum output tokens
• toolUseSupport (boolean): Supports tool/function calling
• visionSupport (boolean): Supports image inputs
• streamingSupport (boolean): Supports streaming responses
• capabilities (array): List of capabilities
• limitations (array): Known limitations
• recommendedPractices (array): Best practices for this agent

Example:

const caps = await fixiplug.dispatch('sqlite.context.capabilities', {
  agentType: 'claude-3-5-sonnet',
  includeDetails: true
});

console.log(`Max tokens: ${caps.maxTokens}`);  // 200000
console.log(`Tool use: ${caps.toolUseSupport}`);  // true
console.log(`Vision: ${caps.visionSupport}`);  // true

console.log('Capabilities:', caps.capabilities);
// [
//   { name: 'tool-use', description: 'Can use tools/functions', enabled: true },
//   { name: 'vision', description: 'Can analyze images', enabled: true },
//   { name: 'extended-thinking', description: 'Has extended thinking mode', enabled: true },
//   ...
// ]

console.log('Limitations:', caps.limitations);
// [
//   'Cannot execute code directly in some environments',
//   'Image input size limited to 5MB',
//   'Max 5 images per request'
// ]

console.log('Best practices:', caps.recommendedPractices);
// [
//   'Use structured outputs for complex data',
//   'Break large tasks into smaller tool calls',
//   'Provide clear, detailed prompts for best results'
// ]

sqlite.context.token_budget

Calculate remaining token budget for current conversation.

Parameters:

• agentType (string, optional): Agent type (auto-detected if omitted)
• conversation (array, required): Conversation history
  • Each item: { role: 'user' | 'assistant', content: string }
• systemPrompt (string, optional): System prompt
• includeBreakdown (boolean, optional): Include detailed breakdown (default: false)

Returns:

• totalTokens (number): Total tokens used so far
• maxTokens (number): Maximum tokens allowed
• remainingTokens (number): Tokens remaining
• percentageUsed (number): Percentage of budget used
• recommendation (string): Recommendation for next steps
• breakdown (object, optional): Detailed token breakdown

Example:

const budget = await fixiplug.dispatch('sqlite.context.token_budget', {
  agentType: 'claude-3-5-sonnet',
  conversation: [
    { role: 'user', content: 'What is 2+2?' },
    { role: 'assistant', content: '2+2 equals 4.' },
    { role: 'user', content: 'Explain why.' },
    { role: 'assistant', content: 'Addition is combining quantities...' }
  ],
  systemPrompt: 'You are a helpful math tutor.',
  includeBreakdown: true
});

console.log(`Used: ${budget.totalTokens} / ${budget.maxTokens}`);
// Used: 1250 / 200000

console.log(`Remaining: ${budget.remainingTokens} tokens`);
// Remaining: 198750 tokens

console.log(`Budget used: ${budget.percentageUsed}%`);
// Budget used: 0.6%

console.log('Recommendation:', budget.recommendation);
// 'Plenty of context remaining, no optimization needed'

console.log('Breakdown:', budget.breakdown);
// {
//   systemPrompt: 42,
//   userMessages: 580,
//   assistantMessages: 628,
//   overhead: 0,
//   total: 1250
// }

// Make decisions based on budget
if (budget.percentageUsed > 80) {
  console.log('Context nearly full, consider summarizing');
} else if (budget.percentageUsed > 50) {
  console.log('Context half-used, monitor usage');
} else {
  console.log('Plenty of context available');
}

sqlite.context.format_response

Format a response optimally for the current agent.

Parameters:

• content (any, required): Content to format
• responseType (string, required): Type of response ('text', 'code', 'data', 'error')
• agentType (string, optional): Target agent type (auto-detected if omitted)
• options (object, optional): Formatting options

Returns:

• formatted (string): Formatted content
• metadata (object): Format metadata

Example:

// Format code response
const formatted = await fixiplug.dispatch('sqlite.context.format_response', {
  content: {
    language: 'python',
    code: 'def hello():\n    print("Hello, world!")'
  },
  responseType: 'code',
  options: {
    includeComments: true,
    syntaxHighlight: true
  }
});

console.log(formatted.formatted);
// For Claude: Uses markdown code blocks with syntax highlighting
// For GPT: Uses appropriate formatting for GPT UI

// Format data response
const dataFormatted = await fixiplug.dispatch('sqlite.context.format_response', {
  content: {
    results: [
      { name: 'Alice', score: 95 },
      { name: 'Bob', score: 87 }
    ]
  },
  responseType: 'data',
  options: {
    format: 'table'  // or 'json', 'list'
  }
});

console.log(dataFormatted.formatted);
// Formatted as markdown table for Claude, or appropriate format for other agents

Best Practices

1. Always Detect Before Optimizing

// Good: Detect first
const agent = await fixiplug.dispatch('sqlite.context.detect');
if (agent.capabilities.includes('vision')) {
  // Use vision features
}

// Bad: Assume capabilities
// Just try to use vision without checking

2. Monitor Token Budget

// In long conversations
async function checkBudget(conversation) {
  const budget = await fixiplug.dispatch('sqlite.context.token_budget', {
    conversation
  });

  if (budget.percentageUsed > 80) {
    // Summarize or truncate history
    return summarizeConversation(conversation);
  }

  return conversation;
}

3. Format Appropriately

// Detect agent and format accordingly
const agent = await fixiplug.dispatch('sqlite.context.detect');

const response = await fixiplug.dispatch('sqlite.context.format_response', {
  content: data,
  responseType: 'data',
  agentType: agent.type
});

return response.formatted;

4. Cache Detection Results

// Cache detection result (doesn't change during session)
let cachedAgent = null;

async function getAgent() {
  if (!cachedAgent) {
    cachedAgent = await fixiplug.dispatch('sqlite.context.detect');
  }
  return cachedAgent;
}

Common Use Cases

Use Case 1: Agent-Specific Features

const agent = await fixiplug.dispatch('sqlite.context.detect');

if (agent.type.startsWith('claude-code')) {
  // Use file editing features
  console.log('Can use file editing tools');
} else if (agent.type.startsWith('gpt-4')) {
  // Use GPT-4 specific features
  console.log('Can use advanced reasoning');
}

Use Case 2: Context Management

async function manageConversation(conversation) {
  const budget = await fixiplug.dispatch('sqlite.context.token_budget', {
    conversation,
    includeBreakdown: true
  });

  console.log(`Context usage: ${budget.percentageUsed.toFixed(1)}%`);

  if (budget.percentageUsed > 75) {
    console.log('Approaching context limit, summarizing...');
    // Summarize older messages
    const summary = createSummary(conversation.slice(0, -10));
    return [
      { role: 'system', content: `Previous context: ${summary}` },
      ...conversation.slice(-10)
    ];
  }

  return conversation;
}

Use Case 3: Capability Checks

const caps = await fixiplug.dispatch('sqlite.context.capabilities', {
  agentType: 'claude-3-5-sonnet'
});

// Check if vision is supported
if (caps.visionSupport) {
  console.log('Can process images');
  // Include image analysis features
}

// Check tool use
if (caps.toolUseSupport) {
  console.log('Can use tools');
  // Enable tool-based workflows
}

console.log(`Max context: ${caps.maxTokens} tokens`);

Use Case 4: Response Formatting

// Data to return
const results = {
  users: [
    { id: 1, name: 'Alice', score: 95 },
    { id: 2, name: 'Bob', score: 87 }
  ]
};

// Format for current agent
const formatted = await fixiplug.dispatch('sqlite.context.format_response', {
  content: results,
  responseType: 'data',
  options: { format: 'table' }
});

console.log(formatted.formatted);
// Automatically formatted as markdown table, JSON, or other format
// depending on what works best for the current agent

Agent Types Reference

Claude Family

• claude-code: Claude Code CLI agent
• claude-3-5-sonnet: Claude 3.5 Sonnet
• claude-3-opus: Claude 3 Opus
• claude-3-haiku: Claude 3 Haiku

Common Capabilities:

• Tool use ✓
• Vision (3.5+ models) ✓
• Extended thinking ✓
• Streaming ✓

GPT Family

• gpt-4: GPT-4 base model
• gpt-4-turbo: GPT-4 Turbo
• gpt-3.5-turbo: GPT-3.5 Turbo

Common Capabilities:

• Function calling ✓
• Vision (GPT-4 Vision) ✓
• Streaming ✓

Performance Characteristics

• Agent Detection: ~50-100ms (cache this!)
• Capabilities Lookup: ~10-20ms
• Token Budget Calc: ~100-200ms (depends on conversation size)
• Response Formatting: ~50-150ms

Error Handling

Possible errors:

• DetectionError: Could not detect agent type
• UnsupportedAgentError: Agent type not recognized
• ValidationError: Invalid parameters

Example:

try {
  const agent = await fixiplug.dispatch('sqlite.context.detect');
} catch (error) {
  if (error.name === 'DetectionError') {
    console.warn('Could not detect agent, using defaults');
    // Fall back to generic agent handling
  } else {
    console.error('Unexpected error:', error.message);
  }
}

Advanced Features

Multi-Agent Coordination

When multiple agents are working together:

const agents = await Promise.all([
  fixiplug.dispatch('sqlite.context.detect', { hints: { id: 'agent-1' } }),
  fixiplug.dispatch('sqlite.context.detect', { hints: { id: 'agent-2' } })
]);

// Coordinate based on capabilities
const primaryAgent = agents.find(a => a.capabilities.includes('code-execution'));
const supportAgent = agents.find(a => !a.capabilities.includes('code-execution'));

Dynamic Capability Adjustment

const agent = await fixiplug.dispatch('sqlite.context.detect');

// Adjust workflow based on capabilities
if (agent.capabilities.includes('vision')) {
  workflow.addStep('image-analysis');
}

if (agent.capabilities.includes('tool-use')) {
  workflow.addStep('tool-execution');
}

Context-Aware Caching

const budget = await fixiplug.dispatch('sqlite.context.token_budget', {
  conversation
});

// Adjust caching strategy based on budget
if (budget.percentageUsed < 20) {
  cacheStrategy = 'aggressive';  // Cache more
} else if (budget.percentageUsed < 60) {
  cacheStrategy = 'balanced';
} else {
  cacheStrategy = 'minimal';  // Cache less, free up context
}

Prerequisites

• SQLite Extensions Framework installed
• Environment variable: SQLITE_FRAMEWORK_PATH

Related Skills

• sqlite-pattern-learner: Learn from database patterns
• sqlite-extension-generator: Generate optimized code
• sqlite-agent-amplification: Dynamic tool creation

Version

1.0.0 - Initial release