# Context Merging

> Send only new messages and let White Circle handle the history

Context merging allows you to send only the **new messages** rather than the entire history every time. White Circle automatically combines your new messages with previously submitted content.

This reduces payload size, simplifies your code, and ensures consistent moderation across the full context.

## How It Works

1. **First Request**

   Send the initial messages with an `external_session_id`:

   ```json
   {
     "deployment_id": "your-deployment-id",
     "external_session_id": "conversation-123",
     "messages": [
       { "role": "user", "content": "Hello, I need help with my account" },
       { "role": "assistant", "content": "Hi! I'd be happy to help. What's the issue?" }
     ]
   }
   ```

   White Circle stores these messages associated with `conversation-123`.

2. **Subsequent Requests**

   For new messages, send only the new content with `include_context: true`:

   ```json
   {
     "deployment_id": "your-deployment-id",
     "external_session_id": "conversation-123",
     "include_context": true,
     "messages": [
       { "role": "user", "content": "I forgot my password" },
       { "role": "assistant", "content": "I can help you reset it. What's your email?" }
     ]
   }
   ```

   White Circle automatically prepends the previous messages before analyzing.

3. **White Circle Sees the Full Context**

   When analyzing the second request, White Circle evaluates this combined content:

   ```json
   [
     { "role": "user", "content": "Hello, I need help with my account" },
     { "role": "assistant", "content": "Hi! I'd be happy to help. What's the issue?" },
     { "role": "user", "content": "I forgot my password" },
     { "role": "assistant", "content": "I can help you reset it. What's your email?" }
   ]
   ```

   > [!NOTE]
   > Only the **last message** in the combined array is checked for policy violations and metrics. The previous messages provide context for the evaluation but are not themselves checked.

## Requirements

> [!WARNING]
> Context merging requires an `external_session_id`. Without it, White Circle cannot identify which previous messages to merge.

| Parameter | Required | Description |
|-----------|----------|-------------|
| `external_session_id` | ✓ | Your tracking ID for the session |
| `include_context` | | Set to `true` to enable merging. Defaults to `true` when `external_session_id` is provided |

### Default Behavior

| Scenario | `include_context` default |
|----------|---------------------------|
| `external_session_id` provided | `true` — context is merged automatically |
| No `external_session_id` | Not applicable — each request is independent |

## When to Use Context Merging

### Real-time moderation

As new content is generated, send each new exchange with `include_context: true`. White Circle maintains the full context for accurate policy evaluation.

This is especially important for detecting:

- Multi-turn jailbreak attempts where users gradually push boundaries
- Context-dependent violations that only make sense with history
- Patterns of behavior across the session

### Reducing payload size

For long sessions, sending the full history every time can be expensive and slow. With context merging:

- You send only new messages
- Requests are smaller and faster
- White Circle handles the history

## Disabling Context Merging

If you want to check messages in isolation (without previous context), explicitly set `include_context: false`:

```json
{
  "deployment_id": "your-deployment-id",
  "external_session_id": "conversation-123",
  "include_context": false,
  "messages": [
    { "role": "user", "content": "Check this message alone" }
  ]
}
```

> [!TIP]
> If you always want independent checks (no merging), explicitly set `include_context: false`.

## Comparison: With and Without Context Merging

### With Context Merging

**Request 1:**

```json
{
  "deployment_id": "your-deployment-id",
  "external_session_id": "session-123",
  "messages": [
    { "role": "user", "content": "Hi there" },
    { "role": "assistant", "content": "Hello!" }
  ]
}
```

**Request 2:**

```json
{
  "deployment_id": "your-deployment-id",
  "external_session_id": "session-123",
  "include_context": true,
  "messages": [
    { "role": "user", "content": "Tell me more" },
    { "role": "assistant", "content": "Sure, here's more info..." }
  ]
}
```

✅ White Circle analyzes all 4 messages together

### Without Context Merging

**Request 1:**

```json
{
  "deployment_id": "your-deployment-id",
  "messages": [
    { "role": "user", "content": "Hi there" },
    { "role": "assistant", "content": "Hello!" }
  ]
}
```

**Request 2:**

```json
{
  "deployment_id": "your-deployment-id",
  "messages": [
    { "role": "user", "content": "Hi there" },
    { "role": "assistant", "content": "Hello!" },
    { "role": "user", "content": "Tell me more" },
    { "role": "assistant", "content": "Sure, here's more info..." }
  ]
}
```

❌ You must send the full content every time
