# What Are Mermaid Symbols and How They Reduce Token Usage in TencentDB Agent Memory

> Discover Mermaid symbols in TencentDB Agent Memory. Learn how these compact identifiers replace text, slash token usage, and optimize LLM prompts for efficiency.

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

---

**Mermaid symbols are compact node identifiers (e.g., `001-N1["Load config"]`) that replace verbose natural-language descriptions of workflow steps, compressing LLM prompts and significantly reducing token consumption.**

TencentDB Agent Memory leverages **Mermaid diagrams** to persist and communicate the state of complex database tasks. By encoding each step as a concise symbol rather than a full sentence, the system minimizes the token footprint of prompts sent to large language models (LLMs) while preserving structural clarity.

## What Are Mermaid Symbols?

In the context of the TencentDB-Agent-Memory repository, **Mermaid symbols** refer to the succinct node definitions within a Mermaid flowchart. Each symbol follows the pattern `XXX-NY["Label"]`, where:

- `XXX` represents a hexadecimal task identifier.
- `N` denotes a node type.
- `Y` is the sequential node number.
- `["Label"]` contains a brief, bracketed description of the action.

For example, `001-N1["Load config"]` is a single symbol that encapsulates the action of loading a configuration file. These symbols function as a **symbolic language**, allowing the system to represent entire workflow steps without embedding lengthy explanatory text in the prompt.

## How Mermaid Symbols Reduce Token Usage

LLM APIs charge per token, and verbose textual descriptions of multi-step workflows quickly exhaust context windows and budgets. Mermaid symbols mitigate this by compressing information:

- **Token efficiency**: A symbol like `001-N1["Validate schema"]` consumes approximately 5 tokens, whereas the equivalent natural language sentence—"Please read the schema file and validate it against the expected format"—might consume 15–20 tokens.
- **Implicit relationships**: Mermaid edges (e.g., `001-N1 --> 002-N2`) convey sequence and dependency without transitional phrases like "and then" or "after which," further reducing token count.
- **Deterministic structure**: The diagram format provides a rigid, predictable schema that the LLM can parse efficiently, reducing the need for disambiguating context.

## Implementation in TencentDB Agent Memory

The repository implements symbol-based compression in the `MemoryCore/src/offload/` directory, where Mermaid diagrams are injected, parsed, and tokenized.

### Generating Diagrams with [`mmd-injector.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/mmd-injector.ts)

The [`MemoryCore/src/offload/mmd-injector.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/offload/mmd-injector.ts) file constructs the Mermaid diagram by assembling node symbols and connecting edges. It wraps the output in Markdown code fences to ensure proper extraction by downstream parsers.

```typescript
// MemoryCore/src/offload/mmd-injector.ts
const mermaidHeader = "```mermaid\n";
const mermaidFooter = "```";

const nodes = [
  `001-N1["Load config"]`,
  `002-N2["Validate schema"]`,
  `003-N3["Fetch credentials"]`,
];

const edges = [
  "001-N1 --> 002-N2",
  "002-N2 --> 003-N3",
];

const mmdContent = `${mermaidHeader}${nodes.join("\n")}\n${edges.join("\n")}\n${mermaidFooter}`;

```

This generated string is inserted into the LLM prompt, allowing the model to understand the entire workflow topology with minimal token expenditure.

### Extracting Node Summaries with [`llm-input-l3.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/llm-input-l3.ts)

The [`MemoryCore/src/offload/hooks/llm-input-l3.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/offload/hooks/llm-input-l3.ts) module extracts the human-readable labels from the symbols to build a concise L3-level prompt. It uses regular expressions to parse the bracketed content without processing the full diagram text.

```typescript
// MemoryCore/src/offload/hooks/llm-input-l3.ts
function extractNodeSummaries(mmd: string): string[] {
  // Captures the label inside the brackets of each node definition
  const re = /[0-9A-Fa-f]{3}-N\d+\["([^"]+)"\]/g;
  const summaries: string[] = [];
  let match;

  while ((match = re.exec(mmd)) !== null) {
    summaries.push(match[1]); // e.g., "Load config"
  }

  return summaries;
}

// Build a compact prompt from the extracted labels
const summaries = extractNodeSummaries(mmdContent);
const concisePrompt = `Current task steps: ${summaries.join(", ")}.`;

```

By sending only the short labels (`summaries`) rather than the full Mermaid source or lengthy descriptions, the system achieves significant token savings.

### Verifying Token Counts with [`l3-token-counter.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/l3-token-counter.ts)

The [`MemoryCore/src/offload/l3-token-counter.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/offload/l3-token-counter.ts) utility validates the compression by counting tokens in the final prompt. It ensures the symbolic representation stays within the model's context limits.

```typescript
// MemoryCore/src/offload/l3-token-counter.ts
import { encode } from "gpt-tokenizer";

export function tokenCount(text: string): number {
  return encode(text).length;
}

// Example verification
const tokens = tokenCount(concisePrompt); // ≈ 12 tokens vs. 40+ for verbose text

```

Supporting utilities in [`MemoryCore/src/offload/l3-token-helpers.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/offload/l3-token-helpers.ts) provide additional formatting and caching logic to optimize token usage further. Parsing utilities in [`MemoryCore/src/offload/parsers/json-utils.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/offload/parsers/json-utils.ts) handle the extraction of raw Mermaid content from JSON payloads when the diagram is stored in structured memory.

## Summary

- **Mermaid symbols** are structured node identifiers (e.g., `001-N1["Label"]`) that encode workflow steps in a compact, machine-readable format.
- These symbols replace verbose natural-language descriptions, reducing per-step token counts from 15–20 tokens to approximately 5 tokens.
- The [`mmd-injector.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/mmd-injector.ts) file generates diagrams, [`llm-input-l3.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/llm-input-l3.ts) extracts concise summaries, and [`l3-token-counter.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/l3-token-counter.ts) verifies token limits.
- Symbolic representation preserves workflow structure via Mermaid edges while eliminating transitional phrases and redundant context.
- This approach lowers API costs, reduces latency, and prevents context window overflow during complex database operations.

## Frequently Asked Questions

### What is the exact format of a Mermaid symbol in TencentDB Agent Memory?

A Mermaid symbol follows the pattern `XXX-NY["Label"]`, where `XXX` is a three-character hexadecimal identifier, `N` indicates a node, `Y` is the node index, and `["Label"]` contains a short description. For example, `0A3-N2["Connect to DB"]` identifies the second node in task `0A3` with the action "Connect to DB".

### How much token reduction can Mermaid symbols achieve?

Mermaid symbols typically reduce token counts by 60–80% for workflow descriptions. A single symbol such as `001-N1["Load config"]` uses roughly 5 tokens, whereas an equivalent natural language instruction might require 15–20 tokens. For workflows with dozens of steps, this compression prevents context window overflow and significantly reduces API costs.

### Which source files handle Mermaid symbol processing?

The primary files are [`MemoryCore/src/offload/mmd-injector.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/offload/mmd-injector.ts) (generates the diagram), [`MemoryCore/src/offload/hooks/llm-input-l3.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/offload/hooks/llm-input-l3.ts) (parses symbols and extracts labels), and [`MemoryCore/src/offload/l3-token-counter.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/offload/l3-token-counter.ts) (verifies token limits). Supporting logic resides in [`MemoryCore/src/offload/l3-token-helpers.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/offload/l3-token-helpers.ts) and [`MemoryCore/src/offload/parsers/json-utils.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/offload/parsers/json-utils.ts).

### Can Mermaid symbols represent complex conditional workflows?

Yes. Symbols can represent decision nodes (e.g., `001-N3{"Is valid?"}`) and branching edges (e.g., `001-N3 -->|Yes| 001-N4`). The symbolic format supports all standard Mermaid flowchart syntax, allowing nested conditions and parallel paths while maintaining the compact token profile that makes the technique efficient for LLM prompting.