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¶
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:
To pull data from a different node by URN, use a colon-separated path:
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:
- The node's own
datafield. If the node carriesdata: { name: "Alex" }, that wins. - The memory's default data node at the memory root. By convention
each memory has a
datanode (created on first write); any field on that node is available as a bare{{field}}. - Cross-node lookup for dotted references like
{{settings.theme}}. The compiler reads the node at URNsettingsand pullsthemefrom itsdata.
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, noundefinedtext 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:
{{#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:
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_nodewithraw: 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.
Related¶
- Building an agent — where templates first appear in the setup flow.
- Building a chatbot agent — uses templates and partials throughout.
- Node types —
systemnodes (prompts, partials) are the most common template carriers.