# How Symbolic Memory and Context Offloading with Mermaid Canvas Work in TencentDB-Agent

> Discover how TencentDB-Agent-Memory uses symbolic IDs and Mermaid Canvas for efficient context offloading. See agent states visualized compactly without LLM bloat.

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

---

**TencentDB-Agent-Memory uses deterministic symbolic IDs to reference offloaded execution traces, generating compact Mermaid Canvas visualizations that depict agent state without bloating the LLM context window.**

The TencentCloud/TencentDB-Agent-Memory repository implements a tiered memory architecture designed to overcome the token limitations of large language models. By separating raw execution data from active prompts through **symbolic memory** and **context offloading**, the system produces interactive **Mermaid Canvas** diagrams that maintain full provenance while keeping conversations lightweight.

## What Is Symbolic Memory?

**Symbolic memory** assigns a deterministic identifier to every piece of data that leaves the active context. When the agent persists a tool call, LLM response, or intermediate artifact, [`src/offload/storage.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/src/offload/storage.ts) generates a short symbolic ID (e.g., `n‑1`, `n‑2`) and stores the payload in the off‑load database.

These **symbolic IDs** are defined in [`src/offload/types.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/src/offload/types.ts) and serve as lightweight pointers. Because the ID is detached from the concrete payload, the system can reference the same logical node across many generations without embedding the full data in the prompt. This design allows the LLM to reason about complex execution graphs using only compact identifiers.

## The Context Offloading Mechanism

When a conversation exceeds the LLM token limit, the agent triggers **context offloading**. The system serializes excess context—including tool call logs and previous Mermaid diagrams—into a **checkpoint file** and writes it to the off‑load store via [`src/offload/storage.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/src/offload/storage.ts).

The active prompt retains only a summary of the checkpoint plus a list of symbolic IDs. When the LLM needs specific details, it requests them on‑demand using the symbolic reference. This approach dramatically reduces the token footprint while preserving complete traceability of the execution history.

## Generating the Mermaid Canvas

The **L2 Mermaid Generation Pipeline** in [`src/offload/pipelines/l2-mermaid.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/src/offload/pipelines/l2-mermaid.ts) converts the symbolic memory store into a visual flowchart. The pipeline executes three distinct stages:

1. **Extract** – Retrieves the latest off‑load entries using [`src/offload/local-llm/parsers/l2-parser.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/src/offload/local-llm/parsers/l2-parser.ts).
2. **Map** – Resolves each entry to a Mermaid node using the symbolic IDs defined in [`src/offload/types.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/src/offload/types.ts).
3. **Render** – Outputs a complete Mermaid flowchart wrapped in a fenced code block (`` ```mermaid ``) that is returned to the LLM as part of the response payload.

The prompt template in `src/offload/local-llm/prompts/l2-prompt.ts` instructs the LLM on how to interpret and modify these diagrams.

## The LLM Interaction Loop

The interaction between the agent and the Mermaid Canvas follows a structured JSON protocol. The LLM receives the current diagram fragment alongside a **JSON instruction** specifying where to insert new nodes or update existing ones.

The LLM responds with a JSON object containing `node_mapping`, `start_line`, and an optional `replace_blocks` field. The `src/offload/local-llm/parsers/json-utils.ts` module extracts and validates this JSON, while `src/offload/local-llm/parsers/l2-parser.ts` orchestrates the parsing flow and persists any new entries back to the symbolic memory store.

## Incremental Visualization Without History Replay

Because symbolic IDs remain constant across checkpoints, the Mermaid Canvas can **incrementally evolve** without resending the entire execution history. New tasks appear as fresh nodes, completed tasks transition from `todo` to `doing` to `done`, and critical paths are highlighted dynamically.

This incremental approach yields a **compact, high‑level visual map** that reflects the current cognitive state of the agent while the full provenance remains safely off‑loaded.

## Code Examples

```typescript
// 1️⃣ Add an off‑load entry and obtain its symbolic ID
import { storeEntry } from '@/MemoryCore/src/offload/storage';
const entry = { tool: 'sql‑exec', payload: 'SELECT …' };
const symId = await storeEntry(entry);   // e.g. "n‑3"

```

```typescript
// 2️⃣ Generate a Mermaid diagram from the current symbolic memory
import { generateMermaid } from '@/MemoryCore/src/offload/pipelines/l2-mermaid';
const mermaid = await generateMermaid(); // returns a string like:
// ```mermaid
// flowchart TD
//   n‑1[Tool: sql‑exec] --> n‑2[LLM: interpret]
//   n‑3[Tool: sql‑exec] --> n‑4[LLM: summarize]
// ```

```

```typescript
// 3️⃣ Update the diagram from LLM output (JSON + Mermaid block)
import { applyLlmUpdate } from '@/MemoryCore/src/offload/local-llm/parsers/l2-parser';
const llmResponse = `{
  "node_mapping": {"n‑5":"Tool: cache‑write"},
  "start_line": 3,
  "replace_blocks": [{"content":"n‑5[Tool: cache‑write]"}]
}
\`\`\`mermaid
flowchart TD
  n‑1 --> n‑2
  n‑3 --> n‑4
  n‑5
\`\`\``;
await applyLlmUpdate(llmResponse);

```

## Summary

- **Symbolic memory** uses deterministic IDs (e.g., `n‑1`) to reference offloaded data in [`src/offload/types.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/src/offload/types.ts), keeping prompts compact.
- **Context offloading** moves execution traces to checkpoint files via [`src/offload/storage.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/src/offload/storage.ts) when token limits are reached.
- The **L2 pipeline** in [`src/offload/pipelines/l2-mermaid.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/src/offload/pipelines/l2-mermaid.ts) renders symbolic memory as Mermaid flowcharts through Extract, Map, and Render stages.
- **Incremental updates** are handled by [`src/offload/local-llm/parsers/l2-parser.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/src/offload/local-llm/parsers/l2-parser.ts) and [`json-utils.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/json-utils.ts), allowing the canvas to evolve without resending history.

## Frequently Asked Questions

### What is a symbolic ID in TencentDB-Agent-Memory?

A **symbolic ID** is a short, deterministic string generated by [`src/offload/storage.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/src/offload/storage.ts) when an entry is first persisted. Stored in [`src/offload/types.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/src/offload/types.ts), these IDs act as lightweight pointers that allow the LLM to reference complex data without including the full payload in the active context.

### How does context offloading reduce token usage?

When conversations exceed token limits, the system serializes excess data into checkpoint files using [`src/offload/storage.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/src/offload/storage.ts). Only symbolic IDs and a brief summary remain in the prompt, enabling the LLM to request specific details on‑demand rather than processing the entire execution history in every request.

### How does the Mermaid Canvas update incrementally?

The canvas updates incrementally because symbolic IDs remain constant across checkpoints. The LLM receives the current diagram and outputs JSON instructions (parsed by [`src/offload/local-llm/parsers/l2-parser.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/src/offload/local-llm/parsers/l2-parser.ts)) that add or modify specific nodes. This avoids the need to regenerate or resend the complete execution trace for every visualization update.

### Which files handle the storage and generation of symbolic memory?

[`src/offload/storage.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/src/offload/storage.ts) manages persistence and checkpointing, [`src/offload/types.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/src/offload/types.ts) defines the symbolic ID structures, and [`src/offload/pipelines/l2-mermaid.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/src/offload/pipelines/l2-mermaid.ts) handles the generation of Mermaid diagrams. Parsing logic resides in [`src/offload/local-llm/parsers/l2-parser.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/src/offload/local-llm/parsers/l2-parser.ts) and [`src/offload/local-llm/parsers/json-utils.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/src/offload/local-llm/parsers/json-utils.ts).