Skip to content

Mustache template syntax

Node content can include Mustache template variables. When an agent reads a node, Hadron compiles the content by resolving variables from the memory's data. This applies to any node type — most often system nodes (prompts, conversation stages) and info nodes (knowledge content templated per user).

Variable syntax

Welcome, {{name}}! You live in {{location}}.

Variables use double braces. Names follow JavaScript identifier rules (letters, numbers, underscores, dots for nested access). Whitespace inside the braces is ignored in node content. That does not hold for a boot prompt: see Platform variables in a boot prompt.

To access a nested field:

Welcome, {{user.name}}! Your team is {{user.team.name}}.

To pull data from a different node by URN, use a colon-separated path:

Theme: {{settings.theme}}

settings here is a node URN segment under the same memory. The compiler treats anything before the first dot as a node URN; everything after the dot is field access on that node's data.

Resolution order

When the compiler encounters {{name}}, it tries these sources in order and returns the first match:

  1. The node's own data field. If the node carries data: { name: "Alex" }, that wins.
  2. The memory's default data node at the memory root. By convention each memory has a data node (created on first write); any field on that node is available as a bare {{field}}.
  3. Cross-node lookup for dotted references like {{settings.theme}}. The compiler reads the node at URN settings and pulls theme from its data.

Stage prompts in chatbot agents follow the same rules, compiled against the memory the chat lives in. The facts a chatbot has extracted are fields on that memory's data node, each saved under the last segment of its extraction field (memory.name is saved as name), so a prompt reads them as bare {{name}}. A dotted {{memory.name}} is a cross-node lookup for a node at loc memory, which usually doesn't exist, so it renders empty. See Building a chatbot agent.

Defaults and missing variables

If a variable is missing in every source, the compiler:

  • Drops the variable silently — {{missing}} becomes the empty string. No error, no undefined text leaking through to the LLM.
  • Logs a debug-level warning so you can spot template typos in the server logs without it affecting the agent's response.

To provide a default at the call site, use a fallback section:

Welcome, {{#name}}{{name}}{{/name}}{{^name}}friend{{/name}}!

{{#name}}…{{/name}} renders only if name is set; {{^name}}…{{/name}} renders only if it isn't. This is the standard Mustache "section" / "inverted section" pattern.

Raw substitution — no escaping, no triple braces

Variables are substituted verbatim: the value is inserted as-is, with no HTML escaping. {{note}} with note = "A & B <tag>" renders A & B <tag> unchanged — which is what you want for Markdown and prompt content, where escaping would mangle the text.

Because substitution is already raw, there is no separate "unescaped" form, and the Mustache triple-brace {{{var}}} is not supported. The engine reads it as a literal {, then the tag {{var}}, then a literal } — so {{{role}}} with role = "Backend Engineer" renders {Backend Engineer}, stray braces and all. Always use double braces {{var}}.

Partials

Includes use the {{> }} syntax. The path resolves to a node URN inside the same memory:

{{> prompts:partials:metadata-spec}}

Hadron reads the referenced node, compiles it (recursively), and inlines the result. Use partials for prompt fragments shared across stages (metadata specs, safety language, tone guidelines) so a one-line edit updates everywhere. A partial is an include: see Include syntax and settings for the full grammar, settings and which reads resolve it.

Worked example

A stage prompt:

You are advising {{name}} ({{business_type}}, {{team_size}}).

Their goal: {{top_goal}}.
Their challenge: {{biggest_challenge}}.

{{> prompts:partials:metadata-spec}}

With the user's memory's data node containing:

{
  "name": "Alex Chen",
  "business_type": "specialty coffee shop",
  "team_size": "3 (1 owner + 2 part-time)",
  "top_goal": "break even consistently",
  "biggest_challenge": "winter foot traffic drop"
}

…and prompts:partials:metadata-spec containing the standard "respond via the respond tool" instructions, the compiled prompt sent to the LLM has the user's profile inlined and the metadata spec appended.

Reading raw vs. compiled

Tools and APIs that read nodes return compiled content by default. To see the raw template (e.g. while debugging a prompt), pass raw: true:

  • MCP: hadron_get_node with raw: true
  • Portal: the node detail page has a "Raw" toggle on the content panel
  • GraphQL: node(rel: "...", raw: true)

Platform variables in a boot prompt

A worker's boot prompt is a template that is filled when the worker binds, never when the prompt is compiled. It uses a closed set of platform variables, and only these:

Variable Filled with
{{worker.name}} the worker's name
{{worker.role}} the worker's role
{{agent.name}} the Agent's name
{{worker.reportsTo.name}} the name of the worker it reports to
{{worker.signature}} the signature line the worker uses outside the team
{{worker.trailer}} the commit trailer, as team worker get prints it
{{worker.url}} the worker's portal link
{{session.llmModel}} the model of the bound session

The names worker.*, agent.* and session.* are reserved for this set.

Three behaviours of this set, as built today. They describe the binder that fills a boot prompt, not every {{…}} in Hadron, and the specification does not state them yet:

  • The token is exact. {{ worker.name }} with spaces, tabs or newlines inside the braces is left as written.
  • An unknown name stays as written. {{worker.nickname}} is not in the set, so it prints literally. The older {{name}} and {{role}} are no longer filled either.
  • Substitution is single-pass. If a value itself looks like a token, it is not expanded again.

The platform does not check that a boot prompt binds the name. Read the composed prompt in a team worker cast --dry-run before you cast. For the whole setup, see Set up an AI team.