# What Is Context Offloading and Symbolization in TencentDB Agent Memory?

> Discover context offloading and symbolization in TencentDB Agent Memory. Understand how these features overcome LLM token limits and improve code comprehension.

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

---

**Context offloading and symbolization are dual mechanisms in TencentDB Agent Memory that solve the dual problems of LLM token limits and code comprehension by externalizing conversation state to tiered storage and building queryable call-graphs of repository symbols.**

TencentDB Agent Memory is an open-source framework that enables AI agents to handle long-running, multi-turn tasks without exhausting model context windows. By combining *context offloading*—a tiered persistence strategy for conversation data—with *symbolization*—a semantic code analysis engine—the system allows agents to perform deep codebase exploration and extended reasoning sessions. These capabilities are implemented across the `MemoryCore` and `MemoryKnowledge` modules of the TencentCloud repository.

## Understanding Context Offloading

Context offloading partitions a conversation’s mental state into four logical layers (L0–L3). When token consumption approaches the LLM’s limit, the system serializes intermediate artifacts—such as tool results and generated diagrams—to external storage, compressing the active window while preserving full provenance.

### The Four-Layer Offloading Architecture

The offloading pipeline progresses through distinct transformation stages defined in [`MemoryCore/src/offload/types.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/offload/types.ts).

**L1 Extraction** captures raw tool-call pairs and filters them into concise summaries. The `ToolPair` and `OffloadEntry` interfaces (lines 12–30) model these batched results, which are appended to `offload.jsonl` files under `offload/{session_id}/`.

**L2 Mermaid Generation** feeds L1 summaries into an LLM prompt that produces Mermaid diagram (MMD) fragments. The `MmdNode` interface stores these visual representations, while `MmdMetadata` (lines 59–74) tracks their session-specific locations in `offload/{session_id}/mmds/`.

**L3 Compression** activates when token usage exceeds configurable ratios such as `aggressiveCompressRatio` or `emergencyCompressRatio`. The system prunes older messages, replacing them with the most "replaceable" offloaded entries to maintain a compact token window for the live LLM interaction.

### REST API Endpoints for Offload Management

The offload orchestration layer exposes three V2 REST endpoints via [`MemoryCore/src/offload_server/router.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/offload_server/router.ts) (lines 24–77):

- `POST /v2/offload/ingest` – Receives batched tool-call data. The Python SDK implements this as `client.offload_ingest(session_id, tool_name, result)`.
- `POST /v2/offload/compact` – Triggers a compression run that deletes or replaces messages, accessible via `client.offload_compact(session_id)`.
- `POST /v2/offload/query-mmd` – Retrieves generated Mermaid diagrams through `client.offload_query_mmd(session_id)`.

### Configuration and Threshold Tuning

Developers tune offloading behavior through the `PluginConfig` interface in [`MemoryCore/src/offload/types.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/offload/types.ts) (lines 33–84). Key thresholds include:

- `mildOffloadRatio` – Initial trigger for L1 serialization.
- `l2NullThreshold` – Conditions for Mermaid generation failure handling.
- `aggressiveCompressRatio` – Emergency compression trigger.

This configuration ensures that the agent can conduct extended code reviews or project planning sessions without hitting model token limits, while retaining the ability to reconstruct full context from `offload.jsonl` logs.

## Understanding Symbolization

Symbolization provides agents with semantic code intelligence by constructing a `CodeGraph` that maps every function, class, variable, and file to its call relationships. This enables precise, impact-aware queries that go beyond simple text search.

### CodeGraph Construction and Storage

The `CodeGraph` is built during repository cloning (`git clone`) and indexed by the symbolization engine. Metadata is persisted in a SQLite database (`knowledge.db`), allowing fast traversal of dependency chains without reloading source files.

### Querying Symbols via REST API

The symbol server exposes HTTP routes under `/v3/tools/`, defined in [`MemoryKnowledge/src/routes/code-graph.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryKnowledge/src/routes/code-graph.ts) (lines 70–88). The OpenAPI specification ([`MemoryKnowledge/openapi.yaml`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryKnowledge/openapi.yaml), lines 572–616) formalizes these endpoints:

- `GET /v3/tools/callers?symbol={id}` – Returns all functions invoking the specified symbol.
- `GET /v3/tools/callees?symbol={id}` – Returns all functions called by the specified symbol.
- `GET /v3/tools/impact?symbol={id}` – Analyzes the full dependency chain to determine blast radius before refactoring.
- `GET /v3/tools/symbol?symbol={id}` – Retrieves detailed node metadata.

### SDK Implementation Patterns

The Python SDK wraps these endpoints into intuitive methods. To analyze a codebase, developers execute queries such as:

```python
from tencentdb_agent_memory import MemoryClient

client = MemoryClient(...)

# Locate symbols matching a name fragment

matches = client.search_symbols("UserService")

# Inspect call hierarchy

callers = client.get_callers(matches[0].id)

# Assess refactoring risk

impact = client.analyze_impact(matches[0].id)

```

These methods enable automated workflows such as answering "who calls `UserService.getUser`?" or determining which files require updates when renaming `AuthToken`.

## Summary

- **Context offloading** implements a four-layer (L0–L3) storage strategy that moves tool results and generated diagrams to `offload.jsonl` and MMD files when token limits approach.
- The offload server provides REST endpoints (`/v2/offload/ingest`, `/compact`, `/query-mmd`) and configurable thresholds (`aggressiveCompressRatio`, `mildOffloadRatio`) to manage the compression lifecycle.
- **Symbolization** constructs a persistent `CodeGraph` in SQLite (`knowledge.db`), exposing call relationships via `/v3/tools/` endpoints for impact analysis and dependency queries.
- Both systems are accessible through Python and TypeScript SDKs, enabling agents to perform long-running tasks with full code intelligence.

## Frequently Asked Questions

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

Offloading triggers when the active conversation token count exceeds configurable ratios defined in `PluginConfig`, specifically `mildOffloadRatio` for initial L1 serialization and `aggressiveCompressRatio` for emergency L3 compression. The system evaluates token usage continuously and automatically serializes `ToolPair` data to `offload.jsonl` files before pruning the active message window.

### How does symbolization differ from simple text search?

Symbolization builds a structured `CodeGraph` that understands semantic relationships—such as caller-callee dependencies and inheritance chains—rather than matching string patterns. According to the `MemoryKnowledge` implementation, this allows agents to query "who calls this function?" via `/v3/tools/callers` or calculate refactoring impact via `/v3/tools/impact`, providing precise codebase navigation that text search cannot replicate.

### What storage formats are used for offloaded context?

Offloaded data uses two primary formats: JSONL files (`offload.jsonl`) for structured tool-call summaries adhering to the `OffloadEntry` schema, and Markdown files containing Mermaid diagrams (MMD) for visual conversation flow. These reside in session-specific directories (`offload/{session_id}/` and `offload/{session_id}/mmds/`) as implemented in the storage layer.

### Can developers customize token compression behavior?

Yes. Developers customize behavior through the `PluginConfig` interface in [`MemoryCore/src/offload/types.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/offload/types.ts), adjusting parameters such as `l2NullThreshold` for diagram generation failure handling and `emergencyCompressRatio` for critical memory conservation. These settings allow fine-grained control over when the system transitions between L1 extraction, L2 Mermaid generation, and L3 compression stages.