# How TencentDB Agent Memory Handles Context Offloading for Long-Horizon Tasks

> Discover how TencentDB Agent Memory manages context offloading for long-horizon tasks. Learn about its three-stage pipeline, task executors, and efficient data compression for seamless real-time interactions.

- Repository: [Tencent Cloud/TencentDB-Agent-Memory](https://github.com/TencentCloud/TencentDB-Agent-Memory)
- Tags: deep-dive
- Published: 2026-08-21

---

**TencentDB Agent Memory manages context offloading for long-horizon tasks through a three-stage pipeline that separates raw tool outputs from active LLM contexts, using specialized task executors with lock-free and distributed locking strategies to compress historical data without blocking real-time interactions.**

Long-running AI agent conversations risk exhausting LLM token limits when every historical tool call remains in the active context window. The TencentCloud/TencentDB-Agent-Memory repository solves this by implementing an **offload subsystem** that archives raw interactions, periodically compacts them into condensed summaries, and reinjects only relevant context back into the conversation flow.

## The Three-Stage Offload Pipeline

The offload architecture in [`MemoryCore/src/offload_server/router.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/offload_server/router.ts) orchestrates three distinct operations that move data from raw ingestion to compressed reuse.

### Ingestion: Capturing Raw Tool Outputs (`offload_ingest`)

When tool calls generate results, the SDK's `offload_ingest()` method transmits raw messages to the offload server via `POST /v2/offload/ingest`. The router persists these under `offload/<sessionId>/` for asynchronous processing:

```typescript
// MemoryCore/src/offload_server/router.ts
if (pathname === "/v2/offload/ingest") {
  // store incoming messages under offload/<sessionId>/…
}

```

This ingestion stage captures the complete unfiltered interaction history, ensuring no contextual data is lost before compaction occurs.

### Compaction: Compressing Historical Context (`offload_compact`)

The **pipeline worker** ([`MemoryCore/src/services/pipeline-worker.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/services/pipeline-worker.ts)) drives the compaction stage through background task consumption. When the SDK calls `offload_compact()` (mapped to `POST /v2/offload/compact`), the worker pulls tasks from a Redis-backed queue and executes three critical steps:

1. **Lock acquisition** – Tasks typed as `offload-l2` acquire per-MMD distributed locks; `offload-l1` tasks proceed lock-free
2. **Context summarization** – Executors (`executeOffloadL1`, `executeOffloadL2`) read raw files from `offload/<sessionId>/`, invoke LLM summarization, and write compacted results to `offload/<sessionId>/compact`
3. **Acknowledgment** – Successful tasks are ACKed to the queue; failures trigger exponential back-off retry logic

The lock-free path for `offload-l1` minimizes latency for small sessions:

```typescript
// MemoryCore/src/services/pipeline-worker.ts
if (lockKey === null) {               // lock-free
  await this.executeTask(task, undefined);
  await this.backend.ackTask(msgId);
}

```

### Visualization: Querying Mermaid Diagrams (`offload_query_mmd`)

For debugging long-horizon workflows, the `offload_query_mmd()` SDK method (endpoint `POST /v2/offload/query-mmd`) generates Mermaid diagrams from stored metadata. The implementation in [`MemoryCore/src/offload_server/prompts/l2-prompt.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/offload_server/prompts/l2-prompt.ts) assembles visual representations of the offloaded task flow, enabling developers to trace how context evolved across multiple compaction cycles.

## Task Classification and Concurrency Control

The pipeline worker distinguishes three offload task types, each optimized for different concurrency and consistency requirements:

| Task Type | Locking Strategy | Typical Use Case |
|-----------|------------------|------------------|
| **offload-l1** | Lock-free (no distributed lock) | Fast compaction of small sessions with minimal coordination overhead |
| **offload-l2** | Per-MMD distributed lock | Full compaction requiring heavy LLM calls, allowing concurrent processing of different sessions |
| **offload-l15** | Worker-level lock-free | Specialized telemetry and monitoring pipelines |

The task classification logic appears in [`pipeline-worker.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/pipeline-worker.ts) (lines 301-361), where the worker branches to appropriate executors based on the `task.type` field. This multi-tier approach ensures that lightweight compactions never wait for heavy summarization jobs while preventing race conditions during critical context mutations.

## Resilience Patterns in the Pipeline Worker

The compaction system implements several reliability mechanisms to guarantee **at-least-once delivery** without blocking the real-time LLM interaction loop:

- **Conflict handling** – When `offload-l2` lock acquisition fails, the worker either skips the task or retries with exponential back-off (lines 48-62)
- **Timeout re-enqueuing** – If lock acquisition exceeds TTL, the task re-enqueues with a new message ID (lines 84-102), preventing permanent loss of compaction jobs
- **Dead-letter queue** – Tasks exceeding `maxRetries` migrate to a dead-letter queue for manual inspection, ensuring failed compactions don't infinitely retry

These patterns ensure that context offloading for long-horizon tasks remains reliable even under Redis connection instability or LLM rate limiting.

## Implementing Context Offloading in Your Application

The following TypeScript example demonstrates the complete lifecycle using the TencentDB Agent Memory SDK:

```typescript
import { MemoryClient } from "tencentdb-agent-memory";

// 1️⃣ Ingest raw tool output
await client.offload_ingest({
  sessionId: "session-123",
  instanceId: "agent-main",
  messages: [{ role: "assistant", content: "…tool result…" }],
});

// 2️⃣ Trigger compaction (often scheduled automatically)
const compacted = await client.offload_compact({
  sessionId: "session-123",
  instanceId: "agent-main",
});

// Inject compacted context into subsequent prompts
await llm.chat({
  messages: [
    ...compacted.context,           // ← compacted historical context
    { role: "user", content: "Continue the conversation…" },
  ],
});

// 3️⃣ Retrieve diagnostic visualization
const mmd = await client.offload_query_mmd({
  sessionId: "session-123",
});
console.log(mmd.diagram);   // Mermaid diagram of offloaded workflow

```

## Summary

- **TencentDB Agent Memory** implements context offloading through separate **Ingest**, **Compact**, and **Query** stages managed by [`MemoryCore/src/offload_server/router.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/offload_server/router.ts)
- The **pipeline worker** ([`MemoryCore/src/services/pipeline-worker.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/services/pipeline-worker.ts)) processes compaction tasks with three concurrency levels: lock-free (`offload-l1`), distributed-locked (`offload-l2`), and specialized (`offload-l15`)
- Raw tool outputs persist under `offload/<sessionId>/` while compacted summaries reduce token usage for long-horizon conversations
- Resilience patterns include exponential back-off, lock timeout re-enqueuing, and dead-letter queues to prevent context loss
- Developer observability is supported through Mermaid diagram generation via [`MemoryCore/src/offload_server/prompts/l2-prompt.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/offload_server/prompts/l2-prompt.ts)

## Frequently Asked Questions

### What is context offloading in TencentDB Agent Memory?

Context offloading is an architectural pattern that separates active LLM conversation windows from historical tool interaction data. According to the TencentCloud/TencentDB-Agent-Memory source code, the system captures raw tool outputs via `offload_ingest()`, periodically compresses them into token-efficient summaries via `offload_compact()`, and reinjects only relevant compacted context back into the LLM prompt. This prevents token budget exhaustion during long-horizon tasks while preserving access to historical reasoning chains.

### How does the pipeline worker handle concurrent compaction tasks?

The pipeline worker in [`MemoryCore/src/services/pipeline-worker.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/services/pipeline-worker.ts) implements tiered concurrency control through task typing. `offload-l1` tasks execute without distributed locks for maximum throughput on small sessions, while `offload-l2` tasks acquire per-MMD locks to prevent race conditions during heavy LLM summarization. Failed lock acquisitions trigger either immediate skipping or exponential back-off retry, ensuring that concurrent sessions don't corrupt each other's compacted context.

### What distinguishes offload-l1 from offload-l2 task types?

**offload-l1** tasks use a lock-free execution path optimized for fast, lightweight compaction of small context windows, minimizing latency by avoiding distributed lock overhead. **offload-l2** tasks require exclusive per-MMD locks before execution, making them suitable for comprehensive compaction involving heavy LLM calls or large historical datasets. The worker selects executors (`executeOffloadL1` versus `executeOffloadL2`) based on the task type field, with locking logic concentrated in lines 48-102 of [`pipeline-worker.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/pipeline-worker.ts).

### How does the system prevent data loss during context compaction?

The offload subsystem implements multiple reliability layers: Redis-backed task queues ensure durability of compaction jobs; exponential back-off retry logic handles transient failures; and lock timeout mechanisms re-enqueue tasks with new IDs if acquisition fails beyond TTL (lines 84-102). After exceeding `maxRetries`, tasks migrate to a dead-letter queue rather than dropping, enabling manual recovery of failed long-horizon context operations.