Tutorial: Infinite chat history with ADK
For the complete documentation index see: llms.txt
All documentation pages available in markdown.
Objectives
By the end of this tutorial, you will be able to:
- Keep ADK conversations growing to thousands of turns without hitting per-record size limits or losing context.
- Add history indefinitely using the same
append_eventandget_sessionAPIs while Aerospike opens segment records automatically when a segment fills. - Load only the recent turns your model needs for context through
num_recent_events, with read time driven by how many turns you request rather than total history size. - Load the complete conversation in order for audit, export, or debugging.
Think about a long-running research agent that gathers and analyzes sources over many days. Each user message and model reply adds another turn to the conversation. After thousands of turns, the full transcript is too large to store in a single chunk. Writes start failing, the agent loses context, or you truncate history to stay under a size cap.
Even if your application compacts context for model calls, you may still need the full conversation history available in your UI, for example so a user can scroll back through earlier turns on every login. That is what this tutorial covers.
Google Agent Development Kit (ADK) is Google’s framework for building these agent applications. ADK tracks each conversation in a session: a durable record of events plus session state (metadata the agent updates across turns). Your code calls append_event to add each turn and get_session to read back session history.
By default, ADK expects a session service to persist that data. The adk-aerospike package provides AerospikeSessionService, which stores ADK sessions in Aerospike Database. Instead of packing the entire history into one record, the service writes events into segment records that grow until Aerospike signals the record is full, then opens the next segment automatically. Your application keeps using the same ADK APIs (create_session, append_event, get_session) with no segment logic required.
In this tutorial, you append 20,000 turns in a synthetic conversation and verify three read modes: load everything, load only the most recent turns, and load turns after a timestamp.
Key terms
| Term | Meaning |
|---|---|
| Session | One conversation thread for a given app, user, and session ID. Holds events and its merged state. |
| Event | A single turn in the conversation (for example, a user message or assistant reply). |
| Segment | A storage record that holds a portion of the session’s event history. Additional segments are created as history grows. |
append_event | ADK API call that adds an event (and optional state changes) to a session. |
get_session | ADK API call that reads a session’s events and its merged state. Optional filters limit how much history is returned. |
AerospikeSessionService | The adk-aerospike backend that maps ADK sessions to Aerospike records. |
Read modes to verify
The demo exercises three ways to read the same session after 20,000 appends:
| Read mode | What it returns |
|---|---|
Full get_session | Complete conversation history in order. |
num_recent_events=N | Only the last N events, without loading the full history. |
after_timestamp=T | Events from a cutoff time forward (the last ~10 turns in the demo). |
In production, agents typically call get_session with num_recent_events set to the context window size (for example, the last 20 turns) so each model request stays fast even when total history is large. Full get_session reads load the entire transcript for the chat UI, export, or debugging.
On the next page, you learn how sessions and segments map to Aerospike records before you run the demo.