3.5 State Prefixes, Sessions, Artifacts & Memory Bank

The Rosku Bank Memory Meltdown: Lost Preferences & Bloated State

Rosku Bank’s Wealth & Loan Assistant has three major memory bugs in production:

1. When a customer starts a new chat session the next day, the agent forgets their preferred language (user:language) and forgets that they mentioned saving for a house three weeks ago!
2. Temporary calculation variables from Turn 1 leak into Turn 5 because developers didn’t scope them to a single invocation (temp:).
3. Developers encode a customer’s 15-MB PDF tax return as a Base64 string and save it directly inside session.state, causing the database and LLM context to grind to a halt!

1. Key Concept Definitions: The 3 Storage Pillars & 4 State Scopes

In the Agent Development Kit (ADK) on the Gemini Enterprise Agent Platform, information management is divided across five core primitives:

1. Turn & Session State (temp: vs. unprefixed)

temp:key is an ephemeral scratchpad wiped automatically when the current single turn finishes. Unprefixed key persists across turns within the current session_id only.

2. Cross-Session State (user: & app:)

user:key persists across all sessions belonging to a specific user_id. app:key is shared globally across all users and sessions of the application (requires persistent SessionService).

3. Tracked State Mutation (state_delta)

Always mutate state via output_key, tool_context.state, or callback_context.state so ADK records an EventActions(state_delta=…) event—never mutate detached session objects!

4. Memory Bank (MemoryService)

Ingests completed sessions (add_session_to_memory) and uses an LLM to extract, deduplicate, and semantically index long-term unstructured facts recalled via PreloadMemoryTool or LoadMemoryTool.

5. ArtifactService (GcsArtifactService)

Stores large binary Part payloads (PDFs, images, audio, CSVs) outside session.state in Cloud Storage with automatic revision numbering (v0, v1, v2…) and optional user: scoping.

---

2. Interactive Explorer: 4 State Prefixes, Memory Bank & ArtifactService

Switch between the 3 Storage & Memory Modes below and click the 4 stages to inspect how ADK scopes variables, extracts long-term memories, and handles binary files:

1. The 4 State Prefixes2. Memory Bank (Long-Term)3. ArtifactService (Binary Files)

← PrevStage 1 / 4Next →

SCOPE 1: TEMP: PREFIX

1. Ephemeral Single-Invocation Scratchpad (temp:key)

Persistence & Visibility

Shared between sub-agents during the current single turn, then wiped automatically when the turn completes.

Rosku Bank Example & Architecture Rule

Use temp:raw_calc to pass intermediate math between two sub-agents without polluting permanent session history!

---

3. Visual Parameter Matrix: The 4 session.state Scope Prefixes

Review how each state key prefix controls visibility and persistence across turns, sessions, and users:

State Key Prefix	Example Key	Scope & Lifespan	Shared Across Sessions?	Ideal Rosku Bank Use Case
temp:	temp:raw_dti_calc	Single Invocation (Turn) Only. Wiped automatically as soon as the current turn ends.	No (Not even saved to the next turn in the same session!)	Passing temporary scratchpad data from Sub-Agent 1 to Sub-Agent 2 inside a single turn.
No Prefix	mortgage_step	Current Session Only. Persists across turns inside one session_id.	No (Isolated to the current conversation thread)	Tracking multi-turn form progress or shopping cart items during a single chat session.
user:	user:account_tier	User-Wide. Tied to user_id across the persistent SessionService.	YES (Visible in all current and future sessions for that user!)	Storing known structured user settings (preferred language, account tier, UI theme).
app:	app:prime_rate	Application-Wide. Tied to app_name globally.	YES (Visible to all users and all sessions of the application!)	Global configuration values, feature flags, or daily bank-wide base interest rates.

---

4. Real-World Deep Dive: Storage Pillar Sorting & State Mutation Mechanics

Architect Question	How It Works Under the Hood in Production
“When should Rosku Bank store data in session.state (user:key) vs. Memory Bank vs. ArtifactService?”	Structured Flags vs. Unstructured Facts vs. Binary Files: 1. session.state (user:tier): Known, structured key-value variables injected into prompts via {user:tier}. 2. Memory Bank (MemoryService): Unstructured life events and evolving preferences mentioned casually in past conversations, extracted by an LLM and searched semantically (PreloadMemoryTool / LoadMemoryTool). 3. ArtifactService (GcsArtifactService): Large binary files (15-MB PDFs, PNG charts, audio) stored as versioned Part blobs (v0, v1...) in Cloud Storage!
“Why do state changes get lost if a developer calls session = session_service.get_session() and mutates session.state['k'] = 'v' directly outside the runner?”	State Changes Must Be Recorded as EventActions(state_delta=...)! ADK persists state updates by appending Event objects containing actions.state_delta to the session log. Always mutate state through output_key, tool_context.state['k'] = 'v', callback_context.state['k'] = 'v', or EventActions(state_delta={'k': 'v'}) so the Runner tracks and commits the delta!
“How can an uploaded PDF artifact be shared across all future chat sessions for the same customer instead of just the current session?”	Prefix the Artifact Filename with user:! Just like user: state keys, calling tool_context.save_artifact(filename='user:w2_tax_form.pdf', artifact=part) scopes the binary file in GcsArtifactService to the user_id across all sessions!

Golden Rule for Module 3.5

1. Single-turn scratchpad = temp: | One session = No prefix | All sessions for 1 user = user: | All users globally = app:.
2. Unstructured cross-session semantic recall = Memory Bank.
3. Large binary files (PDFs, images, CSVs) with versioning = ArtifactService (GcsArtifactService)!

Official Google Cloud Documentation & Further Reading

Explore the official Agent Development Kit (ADK) documentation for session state prefixes, Memory Bank integration, and artifact management:

ADK Session State & Scope Prefixes (temp, user, app) →ADK MemoryService & Vertex AI Memory Bank →ADK ArtifactService & GcsArtifactService Guide →