# Context Offload Modes in TencentDB Agent Memory: A Technical Guide to ingest, compact, and query-mmd

> Explore TencentDB Agent Memory's three context offload modes ingest, compact, and query-mmd. Learn how to persist data, compress history, and visualize task flows.

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

---

**TencentDB Agent Memory provides three distinct Context Offload modes—`offload_ingest`, `offload_compact`, and `offload_query_mmd`—that enable agents to persist raw tool outputs, compress message history, and visualize task flows via Mermaid diagrams.**

The TencentCloud/TencentDB-Agent-Memory repository implements a sophisticated **Memory Hub** that allows AI agents to offload intermediate context data for efficient reuse. Understanding these **Context Offload modes** is essential for building stateful agent applications that persist expensive tool results and retrieve compressed context across sessions without re-executing original operations.

## What Are Context Offload Modes?

Context Offload modes are specialized API operations exposed by the Memory Hub that handle different stages of context lifecycle management. According to the source code in [`MemoryCore/src/offload_server/router.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/offload_server/router.ts), the system routes three primary HTTP endpoints—`POST /v2/offload/ingest`, `POST /v2/offload/compact`, and `POST /v2/offload/query-mmd`—each triggering specific server-side processing pipelines.

These modes operate across a layered architecture (L1, L1.5, L2, and L15) that progressively transforms raw tool outputs into structured, retrievable facts and compact message representations suitable for cross-session agent reuse.

## The Three Context Offload Operations

### offload_ingest: Persisting Raw Tool Results

The `offload_ingest` mode accepts raw results from tool calls—such as code searches, web searches, or LLM-generated snippets—and initiates the asynchronous **L1 processing pipeline**. As implemented 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) (lines 414-520), this method stores the result and triggers fact extraction (atoms) for later retrieval.

When you call the `POST /v2/offload/ingest` endpoint, the server renames files and creates deterministic references that enable subsequent agents to recall exact context without re-running the original tool.

### offload_compact: Server-Side Context Compression

The `offload_compact` mode performs aggressive deduplication and merging of message lists through the **L2** or **L15** processing layers. This operation removes duplicated or unnecessary message parts and merges related entries to produce a compact representation suitable for quick re-injection into new Agent sessions.

The API endpoint `POST /v2/offload/compact` accepts a compression level parameter (`level=1` for light compression, `level=2` for aggressive) that determines whether the system invokes L2 or L15-level merging algorithms.

### offload_query_mmd: Visualizing Task Flows

The `offload_query_mmd` mode returns a **Mermaid Diagram (MMD)** flowchart representing the task graph generated during off-load processing. This visual artifact, accessible via `POST /v2/offload/query-mmd`, provides deterministic, human-readable descriptions of workflow execution patterns.

Agents and developers use this mode for debugging complex multi-step operations or for obtaining high-level views of task dependencies that emerged during the L2/L15 processing stages.

## SDK Implementation Examples

The TencentDB Agent Memory SDKs implement these three modes as first-class methods in both Python and TypeScript. Both clients interact with the same underlying HTTP endpoints defined in [`MemoryCore/src/offload_server/types.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/offload_server/types.ts).

### Python SDK (v2 Client)

The Python client 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) exposes `offload_ingest()`, `offload_compact()`, and `offload_query_mmd()` methods between lines 414-520.

```python
from tencentdb_agent_memory.v2 import client

c = client.Client(base_url="http://localhost:8125")

# 1️⃣ Ingest a tool result into the L1 pipeline

ingest_resp = c.offload_ingest(
    session_id="sess-123",
    tool="search",
    result={"content": "search results..."},
    id_fields={"doc_id": "12345"},
)

# 2️⃣ Compact message history using L2/L15 compression

compact_resp = c.offload_compact(
    session_id="sess-123",
    messages=[
        {"role": "assistant", "content": "first response"},
        {"role": "assistant", "content": "second response"},
    ],
    level=2,  # 1 = light, 2 = aggressive (L15)

)

# 3️⃣ Retrieve the MMD flowchart visualization

mmd_resp = c.offload_query_mmd(session_id="sess-123")
print(mmd_resp["mmd"])  # Mermaid diagram string

```

### TypeScript SDK (memory-core)

The TypeScript definitions in [`sdk/memory-core/typescript/src/types.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/sdk/memory-core/typescript/src/types.ts) type these operations as `offloadIngest`, `offloadCompact`, and `offloadQueryMmd`.

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

const client = new MemoryClient({ baseUrl: "http://localhost:8125" });

// 1️⃣ Ingest tool output to Memory Hub
await client.offloadIngest({
  sessionId: "sess-123",
  tool: "search",
  result: { content: "search results..." },
  idFields: { docId: "12345" },
});

// 2️⃣ Compact context with server-side compression
await client.offloadCompact({
  sessionId: "sess-123",
  messages: [{ role: "assistant", content: "previous response" }],
  level: 2,
});

// 3️⃣ Query the Mermaid diagram for session visualization
const { mmd } = await client.offloadQueryMmd({ sessionId: "sess-123" });
console.log(mmd);

```

## Key Source Files

The Context Offload subsystem spans multiple modules across the TencentDB-Agent-Memory repository:

- **[`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)** – Implements the Python client methods `offload_ingest`, `offload_compact`, and `offload_query_mmd` (lines 414-520).

- **[`sdk/memory-core/typescript/src/types.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/sdk/memory-core/typescript/src/types.ts)** – Defines TypeScript interfaces for Offload API request and response shapes.

- **[`MemoryCore/src/offload_server/router.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/offload_server/router.ts)** – HTTP router that dispatches `/v2/offload/*` routes to the appropriate processing handlers.

- **[`MemoryCore/src/offload_server/types.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/offload_server/types.ts)** – Core data structures and type definitions used by the Offload subsystem for L1, L2, and L15 pipeline stages.

## Summary

TencentDB Agent Memory implements three distinct **Context Offload modes** that enable efficient context management across agent sessions:

- **`offload_ingest`** stores raw tool outputs and triggers the L1 pipeline for fact extraction and deterministic reference creation.
- **`offload_compact`** performs server-side compression across L2 or L15 layers to deduplicate and merge message histories.
- **`offload_query_mmd`** retrieves Mermaid diagram visualizations of the task graphs generated during processing.

These operations exposed through `POST /v2/offload/ingest`, `POST /v2/offload/compact`, and `POST /v2/offload/query-mmd` endpoints allow agents to implement persist-and-reuse patterns without re-executing expensive tool calls.

## Frequently Asked Questions

### What is the difference between L2 and L15 compression in the compact mode?

The `offload_compact` mode supports two compression levels that map to different pipeline stages. Level 1 triggers **L2** processing, which performs light deduplication and merging of related entries. Level 2 invokes **L15** processing, which applies aggressive compression algorithms to remove all unnecessary context and produce minimal representations for session re-injection.

### Can I use Context Offload modes with the v3 API endpoints?

Yes. According to the router implementation in [`MemoryCore/src/offload_server/router.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/offload_server/router.ts), the system supports both `/v2/offload/` and `/v3/offload/` paths for all three modes: `ingest`, `compact`, and `query-mmd`. The SDKs abstract these version differences, but the underlying functionality remains consistent across versions.

### How does the L1 pipeline process data ingested via offload_ingest?

When you call `offload_ingest`, the L1 pipeline immediately extracts atomic facts from the raw tool result and creates deterministic file references. This asynchronous process prepares the context for storage and enables later retrieval by subsequent agents without requiring the original tool to re-execute, effectively implementing a caching layer for tool outputs.

### What format does the offload_query_mmd endpoint return?

The `offload_query_mmd` endpoint returns a JSON response containing a `mmd` field with a string value representing valid **Mermaid diagram** syntax. This flowchart visualization displays the task graph generated during the L2 or L15 processing stages, showing dependencies and execution flows as implemented in the Memory Hub processing pipeline.