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

Context Offload thresholds and compression ratios in TencentDB Agent Memory are configured through the OffloadConfig interface defined in 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 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, 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 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 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, 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) 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 or the TypeScript skill client

Practical Configuration Examples

YAML Configuration File

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

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

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 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.
• L2 triggers (l2NullThreshold, l2TimeoutSeconds) determine Mermaid diagram generation timing, evaluated in 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. 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.

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 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 to skip L3 compaction when the token ratio is already low. This prevents unnecessary compression overhead in stateless client implementations.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}