Memory in Nexus agents

Memory is how your Nexus bot retains context about the customer across turns - and across switches between your single agents (the LLM-driven specialists). This page covers what memory is, what it isn't, and the difference between an agent's local Memory and the bot-wide Global memory.

Memory ≠ Variables

If you only need to pass a value into an attached tool or workflow, you don't need memory. The tool will pick the value up directly from its input mapping at execution time.

Use memory only when you want to intentionally retain context about the customer / end-user so a later turn (or a different agent) can read it.

Tool input mapping  →  for data flow between a turn and a tool call
Memory              →  for context you want to remember across turns

Memory vs Global memory

Your Nexus bot declares memory in two places, both backed by the same runtime store:

• Configuration → Memory (under Agents in the Configuration nav) - variables that are shared across every agent in the bot. The page calls them "memory variables accessible to all agents across conversations". These same variables appear on every specialised agent's profile as the Global memory row.
• Each specialised agent's Memory row (in its Lifecycle section) - variables that are local to that one agent.

So on a single agent's profile you see two memory rows side by side: Memory (this agent's local vars) and Global memory (the bot-wide vars defined on the Configuration → Memory page).

Both surfaces use the same entry fields:

Field	Required	Notes
Variable name	✅	Letters, digits, underscores. Must start with a letter or underscore.
Data type	✅	string, number, boolean, object, array.
Default value	-	Seeded into memory when the conversation starts.
Description	✅	What the variable means and when to use it. Helps the model decide whether to write to it.

Use Memory for context only this agent's flow needs to track (bike_model_picked, preferred_test_ride_slot). Use Global memory for context every agent should be able to read and write (customer_id, account_tier, preferred_language).

Variable names in Memory are validated against Global memory to prevent duplicates within the same agent's view.

How memory actually behaves at runtime

This is the part most people get wrong. At runtime, an agent's Memory and the bot's Global memory flow into the same memory store - a key-value pool scoped to (botId, userId), with a TTL that resets on every user message. The default is 60 minutes of inactivity; always-on chat channels get a longer window - 24 hours on Yellow Messenger, for example - so a normal gap between messages doesn't wipe context. The Memory / Global memory split is a declaration convention that documents intent and scopes the UI; it is not a runtime isolation boundary.

In practice:

• Memory survives agent handoffs. If the billing agent writes last_invoice_id, the support agent can read it on the next turn.
• Memory survives short breaks. As long as the customer's next message arrives before the channel's TTL elapses (60 minutes by default, longer on always-on channels), prior memory is still there.
• Memory is per customer, per bot. Two different customers talking to the same bot have independent memory.

caution

Pick variable names with this in mind. Because every agent in the conversation can see every other agent's writes, name collisions across agents will silently overwrite each other. Prefix or namespace agent-local variables (billing_last_invoice_id) when there's any chance of overlap.

Allowed variables (per-agent read scope)

By default an agent can read the whole memory pool plus the caller's user properties. Allowed variables lets you narrow that down: pick an explicit list of variables and user properties, and the agent may read only those.

You'll find it on AI Agent → Configuration → Profile settings, in the Allowed variables section (available when the bot uses unified memory). It's a chip picker over your Global memory variables and user properties, with its own Save. The helper text reads "This agent can only read the variables and user properties you add here." Add * to allow all user properties.

• Leave it empty and nothing is restricted — the agent reads memory and user properties as before. The allowlist only takes effect once you add at least one entry.
• Allowed variables scopes reads only. It doesn't change what the agent can write.

Scope the super agent's routing and fallback

Set Allowed variables on the super agent (the router) to control what the routing decision and the fallback / root-responder reply are allowed to read. With an allowlist set, the router's Context Expert prompt and the no-active-sub-agent fallback reply see only those variables — not the entire user profile and every global. Use it to keep routing focused and to keep PII out of prompts that don't need it.

Sharing parent memory with sub-agents (opt-in)

For tightly-coupled parent / sub-agent pairs you can opt in to projecting a parent agent's agent-scoped Memory into its sub-agents' prompt context - without using Global memory and without inlining values into Trigger instructions.

How it works:

• Set exposeMemoryToSubAgents: true on the parent agent's compiled config.
• When a sub-agent runs, the parent's Memory keys appear in the sub-agent's <ongoing-context> under a parentAgent section, with each key rewritten as parent.<originalKey>.
• The projection is read-only: the sub-agent sees the values but cannot write to the parent's scope through this surface. The existing merge-on-pop behaviour (where a child's local vars merge back into the parent on completion) is unchanged.

The parent. prefix prevents collisions - a child's own customer_id and the parent's parent.customer_id are distinct keys the LLM can address separately.

When to use it

• A sub-agent needs to read state the parent already collected (verified identity, order context) without that state leaking to peer specialised agents via Global memory.
• The parent / sub-agent pair is a tightly-scoped delegation and you don't want to namespace-pollute by writing to Global.

When not to

• The value is needed by multiple root agents - that's what Global memory is for.
• You want the sub-agent to be able to write back to a shared key - there's no write path through this surface; use Global memory or rely on the merge-on-pop behaviour.

Today this is a runtime-only flag. The agent profile editor doesn't expose a toggle yet - the runtime accepts exposeMemoryToSubAgents as soon as the platform sends it, but you'll need platform-side configuration or a future builder UX to enable it. A builder UI for this is a planned follow-up.

Best practices

• Declare what you depend on. If an agent reads customer_tier, declare it - even if another agent writes it. Declarations are the only documentation the next person editing your bot has.
• Reference declared memory in prompts; don't improvise variables. Before writing an Agent instructions prompt, map the Global memory (Configuration → Memory) the agent will read and write, and reference those names. A single agent's prompt should point at declared memory rather than inventing an ad-hoc variable mid-prompt that nothing seeds or persists. (Flow-local variables inside a multi agent are different - those are scoped to the flow and don't need to live in Global memory.)
• Name variables for what they store. user_details, delivery_full_address, name_on_order tell the next editor - and the model - what's inside. data1, temp, data_temp2 tell them nothing and make collisions harder to spot.
• Use workflow-returned values as-is. When a tool or workflow returns a value, store and reuse it verbatim - don't ask the model to reformat or "correct" it, or you get silent corruption.

  Bad: prompt the model to re-title-case the city a lookup returned. Good: store result.normalized_city (the value the workflow already normalised) and treat it as canonical.

• Default values matter. Without a default, the variable is undefined until something writes to it, and downstream tools may get an empty payload.
• Don't use memory as a scratchpad. Memory's TTL resets on activity but isn't indefinite (60 minutes by default, longer on always-on channels). If a value only matters within a single turn, pass it through tool input mapping instead.
• Don't put secrets in memory. Memory is conversation-scoped, not session-encrypted. Tokens and credentials belong in tool configuration, not in memory.