# How to Configure Context Offload Thresholds and Compression Ratios in TencentDB Agent Memory

> Configure Context Offload thresholds and compression ratios in TencentDB Agent Memory using the OffloadConfig interface. Control L1 flush triggers, L2 timeouts, and L3 compression via YAML, env vars, or SDK.

- Repository: [Tencent Cloud/TencentDB-Agent-Memory](https://github.com/TencentCloud/TencentDB-Agent-Memory)
- Tags: how-to-guide
- Published: 2026-08-22

---

**Context Offload thresholds and compression ratios in TencentDB Agent Memory are configured through the `OffloadConfig` interface defined in [`MemoryCore/src/config.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/config.ts), allowing precise control over L1 flush triggers, L2 processing timeouts, and L3 compression aggressiveness via YAML files, environment variables, or SDK runtime overrides.**

The TencentCloud/TencentDB-Agent-Memory repository implements a three-tier Context Offload subsystem that batches tool interactions and compresses historical context to maintain LLM token limits. All threshold values and compression ratios governing this pipeline are declared in the core configuration interface and parsed at runtime by the `parseConfig` function.

## Configuration Architecture and Core Files

The `OffloadConfig` interface in [`MemoryCore/src/config.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/config.ts) serves as the central schema for Context Offload behavior. This interface defines default values for all threshold parameters, which `parseConfig` validates and applies during agent initialization. The actual evaluation logic resides in [`MemoryCore/src/offload/index.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/offload/index.ts), where the system compares current state against these thresholds to trigger L1, L2, or L3 operations.

## L1 Flush Thresholds

The **`forceTriggerThreshold`** parameter determines when pending tool-call pairs are flushed to the LLM for extraction.

- **Default**: `4` pending entries
- **Behavior**: When the queue reaches this count, [`MemoryCore/src/offload_server/offload-task-executor.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/offload_server/offload-task-executor.ts) immediately triggers an L1 batch regardless of other conditions
- **Tuning**: Increase to reduce API call frequency and associated costs; decrease for faster extraction cycles and lower latency

## L2 Processing Triggers

Two parameters control the L2 stage, which generates Mermaid diagram (MMD) representations from processed tool pairs:

**`l2NullThreshold`**
Specifies the maximum number of entries with `node_id=null` that can accumulate before forcing an MMD processing round. Default is `4`.

**`l2TimeoutSeconds`**
Sets the maximum interval between forced L2 runs. Default is `300` seconds (5 minutes). If the null threshold is not reached within this window, processing triggers automatically to prevent stale data.

These thresholds are evaluated in [`MemoryCore/src/offload/index.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/offload/index.ts) following each L1 completion.

## L3 Compression Ratio Parameters

The L3 compression stage applies graduated strategies based on current token utilization ratios:

**`mildOffloadRatio`** (default `0.5`)
When the token-to-window ratio falls below this value, the system applies mild compression, replacing verbose tool results with concise summaries while preserving the original message structure.

**`aggressiveCompressRatio`** (default `0.85`)
Ratios exceeding this threshold trigger aggressive compression, which may delete or heavily summarize older messages to reclaim significant token space.

**`compactionRatio`** (client mode only, default `0.5`)
In stateless client configurations defined in [`sdk/memory-core/typescript/src/v3/skill-client.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/sdk/memory-core/typescript/src/v3/skill-client.ts), this value provides a shortcut to skip L3 entirely when the current ratio is already below the threshold, avoiding unnecessary CPU cycles.

## Retention and Resource Limits

Additional configuration fields manage auxiliary storage resources:

- **`offloadRetentionDays`**: Days to retain offloaded sessions, references, and MMDs before automatic cleanup (default `0`, disabled)
- **`logMaxSizeMb`**: Maximum size in megabytes for offload debug logs before truncation (default `50`)

## Configuration Deployment Methods

The system supports three configuration channels, parsed in descending order of precedence by `parseConfig`:

1. **Configuration files**: JSON or YAML files (e.g., [`memory-config.yaml`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/memory-config.yaml)) loaded at startup
2. **Environment variables**: Mapped to the `OffloadConfig` schema for containerized deployments
3. **SDK runtime overrides**: Programmatic configuration passed through constructors in [`sdk/memory-core/python/tencentdb_agent_memory/v2/client.py`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/sdk/memory-core/python/tencentdb_agent_memory/v2/client.py) or the TypeScript skill client

## Practical Configuration Examples

### YAML Configuration File

```yaml
offload:
  enabled: true
  mode: "local"
  model: "openai/gpt-4o"
  forceTriggerThreshold: 6
  l2NullThreshold: 5
  l2TimeoutSeconds: 180
  mildOffloadRatio: 0.45
  aggressiveCompressRatio: 0.80
  compactionRatio: 0.55
  offloadRetentionDays: 7
  logMaxSizeMb: 100

```

### Python SDK Runtime Override

```python
from tencentdb_agent_memory.v2 import Client

client = Client(
    api_key="YOUR_API_KEY",
    base_url="https://api.tencentsvc.com/v2",
    offload_config={
        "forceTriggerThreshold": 3,
        "l2NullThreshold": 2,
        "mildOffloadRatio": 0.6,
        "aggressiveCompressRatio": 0.9,
    },
)

```

### TypeScript Configuration Inspection

```typescript
import { MemoryCore } from "@tencentdb/agent-memory";

const core = new MemoryCore();
const cfg = core.getConfig();
console.log("Current L1 trigger:", cfg.offload.forceTriggerThreshold);
console.log("Mild compression ratio:", cfg.offload.mildOffloadRatio);

```

## Summary

- **`OffloadConfig` in [`MemoryCore/src/config.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/config.ts)** defines the complete schema for Context Offload thresholds and compression ratios.
- **L1 thresholds** (`forceTriggerThreshold`) control tool-pair flush frequency, implemented in [`MemoryCore/src/offload_server/offload-task-executor.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/offload_server/offload-task-executor.ts).
- **L2 triggers** (`l2NullThreshold`, `l2TimeoutSeconds`) determine Mermaid diagram generation timing, evaluated in [`MemoryCore/src/offload/index.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/offload/index.ts).
- **L3 ratios** (`mildOffloadRatio`, `aggressiveCompressRatio`) govern compression aggressiveness as token limits approach.
- **Configuration** supports YAML files, environment variables, and SDK overrides via `parseConfig` and client constructors in both Python and TypeScript SDKs.
- **Retention policies** and log limits are controlled by `offloadRetentionDays` and `logMaxSizeMb` respectively.

## Frequently Asked Questions

### Where are the default Context Offload threshold values defined?

Default values are declared in the `OffloadConfig` interface within [`MemoryCore/src/config.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/config.ts). The `parseConfig` function initializes these defaults when the agent starts, reading from configuration files or environment variables to override them.

### How does the `forceTriggerThreshold` affect L1 processing performance?

Increasing `forceTriggerThreshold` batches more tool-call pairs before flushing to the LLM, reducing API costs but potentially delaying extraction. Lower values provide faster feedback cycles at the expense of more frequent LLM calls, as implemented in [`MemoryCore/src/offload_server/offload-task-executor.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/offload_server/offload-task-executor.ts).

### What is the difference between mild and aggressive compression ratios?

`mildOffloadRatio` (default `0.5`) triggers conservative summarization that preserves message structure while reducing token count, whereas `aggressiveCompressRatio` (default `0.85`) permits deletion or heavy summarization of older context. The system evaluates these thresholds in [`MemoryCore/src/offload/index.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/offload/index.ts) to select the appropriate L3 strategy.

### Can I disable automatic L3 compression in client mode?

Yes. Set `compactionRatio` to `0.0` or configure the client mode settings in [`sdk/memory-core/typescript/src/v3/skill-client.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/sdk/memory-core/typescript/src/v3/skill-client.ts) to skip L3 compaction when the token ratio is already low. This prevents unnecessary compression overhead in stateless client implementations.