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

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

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 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.
2. Map – Resolves each entry to a Mermaid node using the symbolic IDs defined in 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

// 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"

// 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]
// ```

// 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, keeping prompts compact.
• Context offloading moves execution traces to checkpoint files via src/offload/storage.ts when token limits are reached.
• The L2 pipeline in 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 and 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 when an entry is first persisted. Stored in 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. 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) 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 manages persistence and checkpointing, src/offload/types.ts defines the symbolic ID structures, and src/offload/pipelines/l2-mermaid.ts handles the generation of Mermaid diagrams. Parsing logic resides in src/offload/local-llm/parsers/l2-parser.ts and src/offload/local-llm/parsers/json-utils.ts.

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