What Is Context Offloading and Symbolization in TencentDB Agent Memory?

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.

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 (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 (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 (lines 70–88). The OpenAPI specification (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:

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

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