Skip to main content
Version: 2.0

Reminders

LLMs have a well-documented recency bias: the most recent tokens in the prompt dominate their attention. In a short session, that's fine — the system instructions are not far away. In a long session, it means an instruction written at turn 1 is effectively invisible by turn 40.

Reminders are short pieces of text the platform automatically appends to user inputs or tool outputs on every turn, so the things you care about stay near the end of the prompt where the model is still paying attention. They are how you counteract drift on long sessions without rewriting the system prompt on every message.

Where reminders live​

Reminders are attached to an agent step, not to the agent as a whole, so they only fire while the agent is in that step. They're triggered by hooks — named event types. Two are supported: input_message (the user sent a message) and tool_output (a tool returned a result). A single reminder can subscribe to both.

Two kinds of reminders​

There are two reminder types.

Templated reminder​

A Velocity-templated string re-injected on every matching hook event. Use this for general context, rules, and anything that depends on agent or session metadata.

TEMPLATED REMINDER ON A STEP

Code example with json syntax.
1

The template can reference ${session.metadata.*}, ${agent.metadata.*}, and ${currentDate}, but cannot depend on per-turn state. If you need truly per-turn data, put it in the tool output or the instruction itself.

TEMPLATED REMINDER ON A RETRIEVAL TOOL'S OUTPUT

Code example with json syntax.
1

When a reminder needs to stay silent under some condition, emit an empty string from the Velocity template rather than trying to suppress the hook:

#if($session.metadata.tier == "enterprise")Reminder: enterprise SLA applies — respond within 2 business hours.#end

Glossary expansion reminder​

A specialized reminder that looks up terms from a glossary in user input and appends their expansions as a hint block. Use this for internal acronyms, codenames, and team names the LLM would not recognize.

GLOSSARY EXPANSION REMINDER

Code example with json syntax.
1

Glossary reminders always fire on input_message; there are no configurable hooks. See Glossaries for the matching rules and how the hint block is formatted.

How the LLM sees a reminder​

input_message hooks​

Use this hook when the constraint is about how the agent should interpret or respond to user input — tone, guardrails keyed to who is speaking, per-user context expansion. The reminder text is appended to the user's content, so from the model's point of view it looks like the user said it:

how do I deploy?

Reminder: the user is on the enterprise tier. Never quote a discount unless the tier is 'enterprise'.

The Reminder: prefix is part of the author's template — the platform doesn't prepend anything. Write the template however reads best.

tool_output hooks​

Use this hook when the constraint is about how to handle results coming back from a tool — citation requirements on retrieval, redaction rules on PII-bearing fetches, "don't invent fields not present in this payload." The reminder rides along with the tool output so the model sees it immediately after the result, exactly where it's deciding what to do with that data.

If multiple reminders fire on the same tool output, their texts are joined and delivered together.

The original user message and tool output stay unchanged in the session event log — the reminder is only layered on for the LLM.

Reminders vs instructions​

  • Instructions are the system prompt. They're compiled once at the start of a step, and the LLM reads them as the framing for the entire conversation. Best for persona, rules, output format, and static guidance.
  • Reminders fire on every matching event. They land near the end of the prompt, where the model's attention is strongest. Best for constraints the model tends to forget over time, per-message context expansion, and recency-sensitive guardrails.

Use instructions for things that need to be true from turn 1. Use reminders for things that need to remain true at turn 50.

When to reach for a reminder​

Typical uses:

  • Guardrails that matter per turn. "Do not share any document with confidentiality=internal without a managerial approval note."
  • Dynamic user context. "The user is in the EU. Respond in the language indicated by session.metadata.language."
  • Output format that drifts. "Every response must end with a one-line next-action summary."
  • Glossary expansion — see Glossaries.

Reminders cost tokens on every turn they fire, so keep each one short and specific. A 30-token reminder is doing useful work; a 300-token one is an instruction in disguise and probably belongs in the system prompt.

Trade-offs​

  • Compiled at session start. Templated reminders bind to session.metadata once, so mid-session metadata changes won't be reflected. If you need truly live values, put them in the tool output instead.
  • Every matching turn pays tokens. A reminder that fires on every user message adds its tokens to every user message. That's the whole point — but it means long reminders are expensive, and a reminder that's really an instruction belongs in the system prompt.
  • Scoped to a single step. Reminders don't cross step transitions. Either repeat the reminder on each step where it applies, or lean into the scoping and let different steps carry different reminders.
  • Fire-or-don't at the hook level. A reminder cannot conditionally skip a hook; use the Velocity template to emit an empty string when it shouldn't apply.