# How the Mermaid Canvas Represents Task State in TencentDB Agent Memory

> Explore how the Mermaid Canvas visualizes task state in TencentDB Agent Memory. See how it maps tool calls to color-coded nodes for real-time progress tracking.

- Repository: [Tencent Cloud/TencentDB-Agent-Memory](https://github.com/TencentCloud/TencentDB-Agent-Memory)
- Tags: internals
- Published: 2026-08-24

---

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

```typescript
// 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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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.

```typescript
// 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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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.

```typescript
// 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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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)

```html
<!-- 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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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.