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

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, 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 (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.

Python SDK (v2 Client)

The Python client in sdk/memory-core/python/tencentdb_agent_memory/v2/client.py exposes offload_ingest(), offload_compact(), and offload_query_mmd() methods between lines 414-520.

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 type these operations as offloadIngest, offloadCompact, and offloadQueryMmd.

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

• sdk/memory-core/typescript/src/types.ts – Defines TypeScript interfaces for Offload API request and response shapes.

• MemoryCore/src/offload_server/router.ts – HTTP router that dispatches /v2/offload/* routes to the appropriate processing handlers.

• 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, 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.

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