Memory And Budgets

Memory and budgets both use runtime storage, but they solve different problems:

• Memory preserves facts and events.
• Budgets track usage and enforce limits.

Facts And Events

Data	Behavior
Facts	Mutable key-value records used for preferences, profiles, summaries, plans, and other remembered information.
Events	Append-only session activity used for history, tracing, and Studio views.

Facts have a kind that helps identify records such as a normal fact, profile, summary, plan, or usage record. Internal summary and plan records are kept out of the general Memory Facts context and are supplied through their dedicated context behavior. Usage counters currently remain visible with the other fact keys. Summaries and plans follow the Memory node’s selected scope; budget counters use session scope for Session budgets and user scope for the other budget periods.

Normal fact keys that do not start with __ are automatically supplied to the model on each reasoning call. This also applies when the Agent node uses Context None.

Events can contain user input, model output, tool requests, tool results, warnings, and errors. Treat them as sensitive operational data.

Memory Scope

Scope	Fact behavior
Session	Facts belong to one sessionId.
User	Facts can follow a userId across sessions.

Event history remains session-based. Selecting User scope does not merge separate session event timelines.

Treat a stable userId as required for User scope. Do not use User-scoped memory for anonymous requests or requests where identity can change. If no reliable user identity is available, use Session scope.

Changing the Memory node between Session and User scope does not migrate existing records. Previously stored facts can become unavailable under the new lookup scope.

Summarized context and planning also store internal facts. In the current runtime, choosing User scope means those internal summaries and active plans can be shared across the user’s sessions. Prefer Session scope when conversations or concurrent agent runs must remain isolated.

Agent Memory Actions

The model can request memory reads and writes when the corresponding actions are available. Both operations continue the loop with another agent reasoning step, so they count toward Max Iterations and can cause additional model usage.

The model already receives normal scoped facts automatically. memory.read is primarily useful when it needs to refresh selected values after a write.

Writing an existing key replaces its value and kind within the current agent and session/user scope. Writing null leaves the fact present with an empty value; it does not delete the record. The current model-facing actions do not include fact deletion.

Memory writes should store stable, useful information rather than every detail from a conversation. Never store credentials or authentication secrets as facts because normal facts are sent to the model provider.

Budget Types

Type	What is measured
Tokens	Token usage reported for model calls.
Spend	Cost reported by the configured provider.

Spend limits depend on the provider returning usable cost data. A provider that does not report cost cannot support accurate spend enforcement.

Budget Periods

Period	Scope and reset
Session	Current session only.
Daily	User usage for the current UTC day.
Weekly	User usage from Monday in UTC.
Monthly	User usage from the first day of the UTC month.
Lifetime	All recorded usage for the user.

Non-session periods require a stable userId to aggregate usage correctly.

Threshold And Limit

The warning threshold is a percentage of the hard limit. Budget state is checked before each agent reasoning step:

• If previously recorded usage has reached the threshold, each subsequent reasoning step can emit agent.warning.
• If previously recorded usage has reached the hard limit, the next reasoning step emits agent.error instead of making another reasoner call.

Set a positive hard limit. An empty or zero value is interpreted as 0 and blocks the first reasoning step when the Budget is selected.

Usage is recorded after each model call. A call that crosses the limit has already happened, and a terminal response from that call can still be returned. Thinker also makes its reasoning and extraction calls within one reasoning step, without a budget check between them.

Treat this budget as a runtime guard for subsequent work, not as a strict provider-side spending cap. Provider-side limits are still advisable when an exact maximum is required.

See Memory node and Budget node for configuration fields.