Sessions, Memory & Skills

LLMs are inherently stateless: all their reasoning happens inside the context window of a single API call. Nothing that came before exists for the model — unless someone puts it there. Context Engineering is the process of dynamically assembling and managing the information inside the context window to enable stateful, intelligent agents.

It is the natural evolution of Prompt Engineering: instead of polishing a static instruction, the context engineer orchestrates the entire payload — selecting, summarizing and strategically injecting different types of information on every turn, with maximum relevance and minimum noise. External systems (RAG, session stores, memory managers) manage the context; the framework orchestrates it all.

Everything the model "sees" in a turn fits into three categories. Assembly is dynamic: memories aren't static, few-shot examples must be relevant to the task (not hardcoded), and RAG responds to the immediate query.

The conversation history grows without stopping. Bigger windows survive long transcripts, but: cost and latency rise with every token, and context rot appears — the model's attention to critical information decreases as the context grows. The solution is to mutate the history dynamically: summarization, selective pruning, compaction.

A session encapsulates the dialogue history and working memory of one continuous conversation: a self-contained record bound to a specific user. A user can have multiple sessions — separate, disconnected logs.

The agent appends events and mutates the state according to business logic. The structure echoes the list of Content objects in the Gemini API — each Content has a role (user/model) and parts (text, images, tool calls): one turn = one Event.

# o histórico é uma lista de Content: role + partsresponse = client.models.generate_content( model="gemini-2.5-flash", contents=[{"role": "user",  "parts": [{"text": "Quero ir a Paris em novembro"}]},{"role": "model", "parts": [{"text": "Direto ou com escala?"}]},{"role": "user",  "parts": [{"text": "Direto, por favor"}]}, ], )

The framework is a universal translator between your code and the LLM: it keeps the history and state, builds the requests, parses and stores the responses. For Gemini, the request is List[Content] — each Content with a role and parts. The framework maps your internal object (e.g. an ADK Event) to role/parts before the call. This abstraction decouples the agent's logic from the specific LLM — and prevents vendor lock-in.

session = Session( id="s_771", events=[event_1, event_2, event_3],  # histórico cronológicostate={"cart_items": [...]},          # working memory separada)

class AgentState(TypedDict): messages: Annotated[list, add_messages]  # históricocart: dict                                 # dados de trabalho# o grafo pode reescrever o state a cada passo (ex.: compactar)

There is a critical trade-off: the same abstraction that decouples the agent from the LLM isolates it from agents of other frameworks. The isolation hardens at the persistence layer — the database schema gets coupled to the framework's internal objects, and the record becomes non-portable. A LangGraph agent cannot natively interpret the Session/Event objects of an ADK agent: seamless handoff, impossible.

In a simple architecture, the session is an immutable log. As it scales, token usage explodes — and four limitations bite latency-sensitive applications:

The three compaction strategies

# limita o contexto enviado ao LLM, sem modificar o log persistidoplugin = ContextFilterPlugin(num_invocations_to_keep=10)# ou: compactação agendada de eventosconfig = EventsCompactionConfig(compaction_interval=5, overlap_size=1)

Trigger mechanisms

Sessions and memory live in symbiosis: sessions are the primary source for generating memories, and memories are the key strategy for managing the size of sessions. Each one feeds the other, in a continuous cycle.

A memory is a snapshot of extracted, meaningful information from a conversation or source: a condensed representation that preserves the important context, persisted across sessions for a continuous, personalized experience.

Four capabilities a memory system enables

The five layers collaborating on every turn

Memory retrieval is often compared to RAG, but the architectural principles are different: RAG deals with static external data; Memory, with dynamic, user-specific context. They are complementary — and a truly intelligent agent needs both.

Memories are classified by how they are stored and captured — and they work together for a rich, contextual understanding. Golden rule: memories are descriptive, not predictive.

Anatomy of a memory

A 'memory' is an atomic piece of context that is returned by the memory manager and used by the agent as context. While the exact schema can vary, a single memory generally consists of two components: content and metadata.

Declarative × Procedural (cognitive science)

Organization patterns

Storage architectures

Creation mechanisms

Scope: who the memory describes

Multimodal memory: source × content

from google.genai import types client = vertexai.Client(project=..., location=...) response = client.agent_engines.memories.generate( name=agent_engine_name, direct_contents_source={"events": [{"content": types.Content( role="user", parts=[ types.Part.from_text("This is context about the multimodal input."), types.Part.from_bytes(data=CONTENT_AS_BYTES, mime_type=MIME_TYPE), types.Part.from_uri(file_uri="file/path/to/content", mime_type=MIME_TYPE) ] )}]}, scope={"user_id": user_id})

Generation autonomously transforms raw conversational data into structured, meaningful insights — an LLM-directed ETL pipeline (Extract, Transform, Load). That's what distinguishes memory managers from RAG engines and traditional databases: instead of the dev specifying database operations manually, the LLM decides when to add, update or merge memories — abstracting the complexity of managing content, chaining calls and running background services.

memories.generate( scope={"user_id": "u_8123"}, direct_contents_source=session_events,   # matéria-prima rawconfig={"wait_for_completion": False},   # assíncrono, em background)

The fundamental question of extraction is: "what information in this conversation is meaningful enough to become a memory?" It's not simple summarization — it's intelligent, targeted filtering: separating signal (facts, preferences, goals) from noise (pleasantries, filler).

"Meaningful" is not universal — it's defined by the agent's purpose. A customer-support agent extracts order numbers and technical issues; a wellness coach extracts long-term goals and emotional states. Customizing that definition is the key to an effective agent.

How the LLM knows what to extract

Most managers work out-of-the-box with common topics (preferences, key facts, goals) — and many allow custom topics. The paper's example: a conversation about a coffee shop generates two feedback memories — "the drip coffee was lukewarm" and "the music was too loud".

config = MemoryGenerationConfig( memory_topics=[ ManagedTopicEnum.USER_PERSONAL_INFO,          # tópico built-inCustomMemoryTopic( name="business_feedback", description="feedback about the coffee shop", ), ], generate_memories_examples=[...],                  # few-shot: conversa → fatos)

Consolidation integrates new information into a coherent, accurate, evolving knowledge base. It's the most sophisticated stage: without it, memory becomes a noisy, contradictory, unreliable log. This LLM-managed "self-curation" is what elevates the memory manager beyond a simple database.

The four problems it addresses

The three-step process

"Garbage in, garbage out" is even more critical for LLMs: here it's "garbage in, confident garbage out". For trustworthy decisions and effective consolidation, the agent must critically evaluate the quality of its own memories — and reliability derives from provenance: the detailed record of origin and history.

Lineage during management

Trust evolves — and pruning is active

Trust is not static: it grows with corroboration (multiple consistent reliable sources) and decays with age and conflict. Memory pruning (active forgetting) identifies and discards memories that are no longer useful — by time-based decay (a meeting from 2 years ago is worth less than last week's), low confidence (a weak inference never corroborated) or irrelevance (old trivial details in the face of current goals). Reactive consolidation + proactive pruning = a curated knowledge base, not an ever-growing log of everything.

Memory managers automate extraction and consolidation after generation is triggered — but who decides when to attempt generation is the agent. It's a critical architectural choice: balancing data freshness against computational cost and latency.

Trigger strategies

Memory-as-a-tool: the agent decides

In the most sophisticated approach, generation is exposed as a tool (e.g. create_memory) whose definition describes which types of information are meaningful. The agent analyzes the conversation and calls the tool autonomously when it identifies something worth persisting — shifting the responsibility of identifying the "meaningful" from the memory manager to the agent/dev.

def generate_memories(tool_context):# opção 1: histórico completo da sessionmemory_service.add_session_to_memory(tool_context.session)# opção 2: só o último turno, assíncronomemories.generate(..., config={"wait_for_completion": False}) runner = Runner(agent=agent, memory_service=VertexAiMemoryBankService())

# aqui o AGENTE extrai (extract_memories) e envia ao Memory Bank# apenas para CONSOLIDAR com as memórias existentesmemories = extract_memories(direct_memories_source={"fact": query}) memory_bank.store(memories)  # consolidação delegada ao serviço

Background, always

The retrieval strategy depends on the organization: a structured user profile is a simple lookup (the whole profile or one attribute); a collection is a complex search problem — finding the most pertinent information in a large, loosely structured pool.

Effective retrieval is crucial: irrelevant memories confuse the model and degrade the response; perfect context produces a remarkably intelligent interaction. The central challenge is balancing utility against a strict latency budget.

The three scoring dimensions

Precision techniques (and their cost)

Timing: when to fetch

# Option 1: PreloadMemoryTool embutida — busca por similaridade em todo turnoagent = LlmAgent( ..., tools=[adk.tools.preload_memory_tool.PreloadMemoryTool()] )# Option 2: callback customizado — mais controle sobre como as memórias são buscadasdef retrieve_memories_callback(callback_context, llm_request): user_id = callback_context._invocation_context.user_id app_name = callback_context._invocation_context.app_name response = client.agent_engines.memories.retrieve( name="projects/.../locations/.../reasoningEngines/...", scope={"user_id": user_id, "app_name": app_name}) memories = [f"* {memory.memory.fact}" for memory in list(response)]if not memories:return  # nenhuma memória para acrescentar às System Instructions# anexa as memórias formatadas às System Instructionsllm_request.config.system_instruction += "\nHere is information that you have about the user:\n"llm_request.config.system_instruction += "\n".join(memories) agent = LlmAgent( ..., before_model_callback=retrieve_memories_callback, )

# Option 1: LoadMemoryTool embutida — o agente decide quando buscaragent = LlmAgent( ..., tools=[adk.tools.load_memory_tool.LoadMemoryTool()], )# Option 2: tool customizada — descreva que tipos de informação podem estar disponíveisdef load_memory(query: str, tool_context: ToolContext):"""Retrieves memories for the user. The following types of information may be stored for the user: * User preferences, like the user's favorite foods. ..."""# busca memórias por similaridaderesponse = tool_context.search_memory(query)return response.memories agent = LlmAgent( ..., tools=[load_memory], )

Positioning influences the LLM's reasoning, operational costs and response quality. In practice, a hybrid strategy works best: system prompt for stable/global memories (the user profile, always present); dialogue injection or memory-as-a-tool for transient/episodic memories (relevant only to the immediate context).

Memories in the System Instructions

Appending memories to the system prompt with a preamble gives them high authority and separates the context from the dialogue — ideal for stable, global information. Typically via a template (e.g. Jinja) with a <MEMORIES> block iterating over retrieved_memory.memory.fact.

from jinja2 import Template template = Template("""{{ system_instructions }}<MEMORIES> Here is some information about the user:{% for retrieved_memory in data %}* {{ retrieved_memory.memory.fact }}{% endfor %}</MEMORIES> """) prompt = template.render( system_instructions=system_instructions, data=retrieved_memories )

Memories in the Conversation History

Injecting directly into the dialogue — before the full history or right before the user's last query. Risks: noise (more tokens, confusion if irrelevant) and dialogue injection (the model treats the memory as something actually said in the conversation). Mind the perspective: if you use role "user" with user-level memories, write in first person. Special case: retrieval via tool calls — memories arrive as tool output.

def load_memory(query: str, tool_context):"""Search the user's long-term memories."""response = tool_context.search_memory(query)return response.memories  # entra no contexto como tool output

And what about procedural memories?

The paper focused on declarative — a reflection of today's commercial market, whose platforms are architected to extract/store/retrieve the "what". But storing the "how" is not an information-retrieval problem — it's a reasoning-augmentation problem, with its own lifecycle:

Memory evaluation is a multi-layered process: verifying the agent remembers the right things (quality), finds memories when needed (retrieval), and that using them actually helps achieve goals (task success). In academia, reproducible benchmarks; in industry, direct impact on the production agent.

From prototype to production, the focus shifts to enterprise-grade concerns: scalability, resilience and security. Rule number one: decouple memory processing from the main logic — the UX can never be blocked by expensive generation.

Concurrency, failures and global scale

Privacy & security risks

Memories derive from — and include — user data. Think of a secure corporate archive managed by a professional archivist: it preserves valuable knowledge while protecting the company.

The journey from a conversational turn to persistent intelligence is governed by Context Engineering — dynamically assembling history, memories and external knowledge into the context window. It depends on the interplay of two distinct, interconnected systems: