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

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

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

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

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

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

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

// 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 provide additional formatting and caching logic to optimize token usage further. Parsing utilities in 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 file generates diagrams, llm-input-l3.ts extracts concise summaries, and 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 (generates the diagram), MemoryCore/src/offload/hooks/llm-input-l3.ts (parses symbols and extracts labels), and MemoryCore/src/offload/l3-token-counter.ts (verifies token limits). Supporting logic resides in MemoryCore/src/offload/l3-token-helpers.ts and 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.

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