How the Mermaid Canvas Represents Task State in TencentDB Agent Memory

The Mermaid Canvas converts the internal off-load log of running tasks into a visual flowchart, mapping each tool call to color-coded nodes that display real-time progress.

In the TencentCloud/TencentDB-Agent-Memory repository, the Mermaid Canvas serves as the visualization layer for the agent's memory system. It transforms abstract task execution data into concrete Mermaid flowcharts (specifically flowchart TD diagrams) that indicate which steps are pending, active, or completed. This system bridges the gap between LLM tool calls and human-readable task progress through a structured pipeline of off-load entries, LLM-powered diagram generation, and status-driven styling.

Core Architecture of the Mermaid Canvas

The canvas operates on a pipeline that persists tool calls as structured entries, triggers generation when thresholds are met, and renders the final diagram with embedded status indicators.

Off-load Entries as the Data Foundation

Every LLM-generated tool call is stored as an OffloadEntry in the off-load log. These entries contain the critical fields required for canvas placement.

// src/offload/types.ts
export interface OffloadEntry {
  tool_call_id: string;
  node_id: string | null;   // null → not yet placed on the canvas
  status?: "done" | "doing" | "todo";
  // …other fields…
}

Initially, when a tool call is recorded, the node_id field is null, indicating the entry has not yet been assigned a position in the Mermaid diagram. The tool_call_id serves as the unique identifier, while the optional status field tracks the lifecycle state.

The L2 Generation Pipeline

The checkL2Trigger function in src/offload/pipelines/l2-mermaid.ts monitors the off-load log for entries requiring canvas placement. When the count of entries with null node_id values exceeds a configurable threshold, or when a timeout elapses, the pipeline triggers the L2 generation process.

// src/offload/pipelines/l2-mermaid.ts
export async function checkL2Trigger(
  stateManager: OffloadStateManager,
  pluginConfig: Partial<PluginConfig> | undefined,
  logger: PluginLogger,
) {
  // …scan off‑load log, count null entries, respect timeout…
  if (eligibleNullCount >= nullThreshold) {
    return { shouldTrigger: true, reason: "...", entriesByMmd };
  }
}

This function groups entries by their target Mermaid file (targetMmd) and returns a trigger decision along with the filtered entries.

Node Identification and Back-filling

Mapping off-load entries to diagram nodes requires consistent identifier generation and fallback mechanisms when the LLM omits explicit IDs.

Node ID Extraction Patterns

Node IDs follow a strict pattern of XXX-NYYY (for example, 001-N12). The helper extractMmdNodeIdsFromText scans existing Mermaid diagrams to extract all current node identifiers, preventing collisions. When the LLM fails to provide an explicit node ID for a tool call, the pickMmdDerivedFallbackNodeId function generates a sensible fallback based on existing IDs in the diagram.

These utilities reside in src/offload/pipelines/l2-mermaid.ts (lines 39-66 for extraction, 68-92 for fallback logic).

The Backfill Process

After the LLM returns a mapping of tool_call_id to node_id, the backfillNodeIds function updates the off-load entries. This ensures every "wait" entry receives a concrete node identifier, either from the LLM's JSON payload or from the fallback derivation.

// src/offload/pipelines/l2-mermaid.ts
export async function backfillNodeIds(
  ctx: StorageContext,
  nodeMapping: Record<string, string>,
  waitIds: Set<string>,
  logger: PluginLogger,
) {
  const mapping = normalizeNodeMapping(nodeMapping);
  // …apply mapping, fall back to derived IDs, rewrite the log…
}

This back-filling step is critical because it guarantees that every off-load entry can be placed on the canvas before the final diagram is rendered.

LLM Integration and Prompting

The Mermaid Canvas relies on the LLM to generate both the diagram syntax and the node mapping structure, guided by a specialized prompt.

The L2 Prompt Structure

Located in src/offload/local-llm/prompts/l2-prompt.ts, the L2 prompt instructs the model to create or update a Mermaid flowchart wrapped in a fenced code block. The prompt specifically requires:

• Output of a valid Mermaid flowchart TD diagram
• Annotation of each node with a status (done, doing, or todo)
• Return of a JSON payload mapping each tool_call_id to its corresponding node_id
• Avoidance of visual clutter in the layout

The prompt also provides the current diagram state (if it exists) alongside the list of pending tool calls, allowing the LLM to incrementally update the canvas rather than regenerating it entirely.

Parsing the Response

The LLM response contains both the Mermaid block and the JSON mapping. Helper functions in src/offload/local-llm/parsers/json-utils.ts, such as extractMermaidFromFence, parse the fenced code block from the text response. This separation allows the system to extract the visual diagram for rendering while using the JSON mapping to update the internal off-load entries via the backfill process.

Rendering and State Visualization

The final canvas renders as a standard Mermaid flowchart, with visual state encoded directly in the node styling.

Status-Based Color Coding

The LLM embeds style definitions within the Mermaid syntax to indicate task progress. The front-end (consuming the mmd_content field) renders these colors to provide immediate visual feedback:

• Done: fill:#8F8 (green)
• Doing: fill:#FF8 (yellow/amber)
• Todo: fill:#DDD (gray)

<!-- Front-end rendering example -->
<div class="mermaid">
flowchart TD
  001-N1[Task A] --> 001-N2[Task B]
  style 001-N1 fill:#8F8   <!-- done -->
  style 001-N2 fill:#FF8   <!-- doing -->
</div>

Whenever the off-load log changes—whether through new tool calls, updated node IDs, or status transitions—the L2 pipeline re-runs. This produces a fresh Mermaid diagram that reflects the current task state, ensuring the canvas remains synchronized with the agent's execution progress.

Summary

• The Mermaid Canvas transforms off-load entries into visual flowcharts using the L2 pipeline in src/offload/pipelines/l2-mermaid.ts.
• OffloadEntry objects store tool_call_id, node_id, and status, with node_id initially null until backfilled.
• The L2 trigger (checkL2Trigger) monitors null entry thresholds to determine when to generate new diagrams.
• Node ID management follows the XXX-NYYY pattern, with fallback generation via pickMmdDerivedFallbackNodeId when the LLM omits identifiers.
• The L2 prompt instructs the LLM to produce Mermaid flowchart TD syntax with embedded status styles and a JSON mapping for backfillNodeIds.
• Visual state is encoded through inline styles (fill:#8F8 for done, fill:#FF8 for doing, fill:#DDD for todo), rendered by the front-end Mermaid library.

Frequently Asked Questions

What is the Mermaid Canvas in TencentDB Agent Memory?

The Mermaid Canvas is the visualization subsystem that converts the internal off-load log of agent tasks into a Mermaid flowchart diagram. It maps each tool call to a node in a flowchart TD diagram, color-coding nodes by status (done, doing, todo) to provide a real-time view of task execution progress.

How does the L2 trigger determine when to update the canvas?

The checkL2Trigger function in src/offload/pipelines/l2-mermaid.ts scans the off-load log and counts entries where node_id is null. When this count exceeds a configurable threshold or when a specified timeout elapses, the trigger fires, initiating the LLM pipeline to generate or update the Mermaid diagram with the new entries.

What happens when the LLM doesn't provide a node ID?

When the LLM response lacks explicit node identifiers, the system invokes pickMmdDerivedFallbackNodeId to generate IDs following the XXX-NYYY pattern (e.g., 001-N12). The backfillNodeIds function then applies these fallbacks to the off-load entries, ensuring every tool call receives a valid node identifier for canvas placement.

How are task statuses visualized in the Mermaid diagram?

Task statuses are visualized through inline style definitions within the Mermaid syntax. The LLM annotates each node with style attributes: green (fill:#8F8) for completed tasks, yellow (fill:#FF8) for active tasks, and gray (fill:#DDD) for pending tasks. The front-end renders these styles to create a color-coded progress indicator.

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