> ## Documentation Index
> Fetch the complete documentation index at: https://docs.helicone.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Context Editing

> Automatically manage conversation context by clearing old tool uses and thinking blocks for long-running AI agent sessions

Context editing enables automatic management of conversation context by intelligently clearing old tool uses and thinking blocks. This can greatly reduce costs in long-running sessions with minimal tradeoffs in context performance.

<Info>
  Context editing is currently supported for **Anthropic models only**. The configuration is ignored when routing to other providers.
</Info>

## Why Context Editing

<CardGroup cols={3}>
  <Card title="Prevent Context Overflow" icon="memory">
    Automatically clear old tool results before hitting context limits
  </Card>

  <Card title="Reduce Token Costs" icon="dollar-sign">
    Keep only relevant context, reducing input tokens on subsequent calls
  </Card>

  <Card title="Enable Long Sessions" icon="clock">
    Run AI agents for longer periods without manual context management
  </Card>
</CardGroup>

***

## Quick Start

Enable context editing with a simple configuration. The AI Gateway handles the translation to Anthropic's native format.

<CodeGroup>
  ```typescript TypeScript theme={null}
  import OpenAI from "openai";
  import { HeliconeChatCreateParams } from "@helicone/helpers";

  const client = new OpenAI({
    apiKey: process.env.HELICONE_API_KEY,
    baseURL: "https://ai-gateway.helicone.ai/v1",
  });

  const response = await client.chat.completions.create({
    model: "claude-sonnet-4-20250514",
    messages: [
      { role: "system", content: "You are a helpful coding assistant." },
      { role: "user", content: "Help me debug this application..." }
      // ... many tool calls and responses
    ],
    tools: [/* your tools */],
    context_editing: {
      enabled: true
    }
  } as HeliconeChatCreateParams);
  ```

  ```python Python theme={null}
  import os
  from openai import OpenAI

  client = OpenAI(
      api_key=os.environ.get("HELICONE_API_KEY"),
      base_url="https://ai-gateway.helicone.ai/v1",
  )

  response = client.chat.completions.create(
      model="claude-sonnet-4-20250514",
      messages=[
          {"role": "system", "content": "You are a helpful coding assistant."},
          {"role": "user", "content": "Help me debug this application..."}
          # ... many tool calls and responses
      ],
      tools=[# your tools],
      context_editing={
          "enabled": True
      }
  )
  ```

  ```bash theme={null}
  curl https://ai-gateway.helicone.ai/v1/chat/completions \
    -H "Authorization: Bearer $HELICONE_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "claude-sonnet-4-20250514",
      "messages": [
        {"role": "system", "content": "You are a helpful coding assistant."},
        {"role": "user", "content": "Help me debug this application..."}
      ],
      "tools": [],
      "context_editing": {
        "enabled": true
      }
    }'
  ```
</CodeGroup>

***

## Configuration Options

The `context_editing` object supports two strategies for managing context:

### Clear Tool Uses

Automatically clear old tool use results when context grows too large:

```typescript theme={null}
context_editing: {
  enabled: true,
  clear_tool_uses: {
    // Trigger clearing when input tokens exceed this threshold
    trigger: 100000,

    // Keep the most recent N tool uses
    keep: 5,

    // Ensure at least this many tokens are cleared
    clear_at_least: 20000,

    // Never clear results from these tools
    exclude_tools: ["get_user_preferences", "read_config"],

    // Clear tool inputs (arguments) but keep outputs
    clear_tool_inputs: true
  }
}
```

| Parameter           | Type      | Description                             |
| ------------------- | --------- | --------------------------------------- |
| `trigger`           | number    | Token threshold to trigger clearing     |
| `keep`              | number    | Number of recent tool uses to preserve  |
| `clear_at_least`    | number    | Minimum tokens to clear when triggered  |
| `exclude_tools`     | string\[] | Tool names that should never be cleared |
| `clear_tool_inputs` | boolean   | Clear tool inputs while keeping outputs |

### Clear Thinking

Manage thinking/reasoning blocks in multi-turn conversations:

```typescript theme={null}
context_editing: {
  enabled: true,
  clear_thinking: {
    // Keep the N most recent thinking turns, or "all" to keep everything
    keep: 3
  }
}
```

| Parameter | Type            | Description                                |
| --------- | --------------- | ------------------------------------------ |
| `keep`    | number \| "all" | Number of thinking turns to keep, or "all" |

***

## Complete Example

Here's a full configuration for a long-running coding agent:

<CodeGroup>
  ```typescript TypeScript theme={null}
  import OpenAI from "openai";
  import { HeliconeChatCreateParams } from "@helicone/helpers";

  const client = new OpenAI({
    apiKey: process.env.HELICONE_API_KEY,
    baseURL: "https://ai-gateway.helicone.ai/v1",
  });

  const response = await client.chat.completions.create({
    model: "claude-sonnet-4-20250514",
    messages: conversationHistory,
    tools: [
      {
        type: "function",
        function: {
          name: "read_file",
          description: "Read a file from the filesystem",
          parameters: {
            type: "object",
            properties: {
              path: { type: "string", description: "File path to read" }
            },
            required: ["path"]
          }
        }
      },
      {
        type: "function",
        function: {
          name: "write_file",
          description: "Write content to a file",
          parameters: {
            type: "object",
            properties: {
              path: { type: "string" },
              content: { type: "string" }
            },
            required: ["path", "content"]
          }
        }
      },
      {
        type: "function",
        function: {
          name: "run_command",
          description: "Execute a shell command",
          parameters: {
            type: "object",
            properties: {
              command: { type: "string" }
            },
            required: ["command"]
          }
        }
      }
    ],
    reasoning_effort: "medium",
    context_editing: {
      enabled: true,
      clear_tool_uses: {
        trigger: 150000,        // Trigger at 150k tokens
        keep: 10,               // Keep last 10 tool uses
        clear_at_least: 50000,  // Clear at least 50k tokens
        exclude_tools: ["read_file"],  // Always keep file reads
        clear_tool_inputs: true  // Clear large file contents from inputs
      },
      clear_thinking: {
        keep: 5  // Keep last 5 thinking blocks
      }
    },
    max_completion_tokens: 16000
  } as HeliconeChatCreateParams);
  ```

  ```python Python theme={null}
  response = client.chat.completions.create(
      model="claude-sonnet-4-20250514",
      messages=conversation_history,
      tools=[
          {
              "type": "function",
              "function": {
                  "name": "read_file",
                  "description": "Read a file from the filesystem",
                  "parameters": {
                      "type": "object",
                      "properties": {
                          "path": {"type": "string", "description": "File path to read"}
                      },
                      "required": ["path"]
                  }
              }
          },
          {
              "type": "function",
              "function": {
                  "name": "write_file",
                  "description": "Write content to a file",
                  "parameters": {
                      "type": "object",
                      "properties": {
                          "path": {"type": "string"},
                          "content": {"type": "string"}
                      },
                      "required": ["path", "content"]
                  }
              }
          }
      ],
      reasoning_effort="medium",
      context_editing={
          "enabled": True,
          "clear_tool_uses": {
              "trigger": 150000,
              "keep": 10,
              "clear_at_least": 50000,
              "exclude_tools": ["read_file"],
              "clear_tool_inputs": True
          },
          "clear_thinking": {
              "keep": 5
          }
      },
      max_completion_tokens=16000
  )
  ```

  ```bash theme={null}
  curl https://ai-gateway.helicone.ai/v1/chat/completions \
    -H "Authorization: Bearer $HELICONE_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "claude-sonnet-4-20250514",
      "messages": [...],
      "tools": [...],
      "reasoning_effort": "medium",
      "context_editing": {
        "enabled": true,
        "clear_tool_uses": {
          "trigger": 150000,
          "keep": 10,
          "clear_at_least": 50000,
          "exclude_tools": ["read_file"],
          "clear_tool_inputs": true
        },
        "clear_thinking": {
          "keep": 5
        }
      },
      "max_completion_tokens": 16000
    }'
  ```
</CodeGroup>

***

## Responses API Support

Context editing works with both the Chat Completions API and the [Responses API](/gateway/concepts/responses-api):

```typescript theme={null}
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.HELICONE_API_KEY,
  baseURL: "https://ai-gateway.helicone.ai/v1",
});

const response = await client.responses.create({
  model: "claude-sonnet-4-20250514",
  input: conversationInput,
  tools: [/* your tools */],
  context_editing: {
    enabled: true,
    clear_tool_uses: {
      trigger: 100000,
      keep: 5
    }
  }
});
```

***

## Default Behavior

When `context_editing.enabled` is `true` but no specific strategies are provided, the AI Gateway uses sensible defaults:

```typescript theme={null}
// Minimal configuration
context_editing: {
  enabled: true
}

// Equivalent to
context_editing: {
  enabled: true,
  clear_tool_uses: {}  // Uses Anthropic defaults
}
```

***

## Related Features

* [Reasoning](/gateway/concepts/reasoning) - Extended thinking that benefits from context editing
* [Prompt Caching](/gateway/concepts/prompt-caching) - Cache static context for cost savings
* [Sessions](/features/sessions) - Track and analyze long-running agent sessions

<Card title="Learn More" href="https://docs.anthropic.com/en/docs/build-with-claude/context-editing">
  Anthropic Context Editing Documentation
</Card>