Tutorial: Expiring chat sessions with LangGraph

Audience

Developers building LangGraph agents who need session checkpoints to expire automatically without a cleanup job.

Duration

This tutorial should take between 15 and 25 minutes.

Objectives

By the end of this tutorial, you will be able to:

• Configure AerospikeSaver, the LangGraph checkpoint backend that stores graph checkpoints in Aerospike, with a per-checkpoint time to live (TTL).
• Run a LangGraph chat agent that persists checkpoints to Aerospike.
• Resume a thread from stored checkpoints while the TTL is still active.
• Verify that Aerospike reclaims expired checkpoint records automatically.

Imagine a customer support chatbot that keeps user messages in history so it can maintain the context of the conversation. If those messages are stored in a separate table, your application has to fetch and sort them on every request, manage the schema, and build a cleanup job to remove records from abandoned sessions. LangGraph is a framework for building stateful large language model (LLM) applications by representing workflows as graphs and saving checkpoints for potential new branches from any point. With LangGraph and Aerospike, there is no separate messages table. LangGraph stores the full conversation history as a checkpoint in Aerospike after every turn. Your application calls graph.invoke() with a thread_id and LangGraph loads the latest checkpoint automatically. The agent continues where the user left off.

When using this kind of implementation, checkpoint records accumulate in Aerospike for every session, including abandoned ones. A relational database needs a scheduled job to delete stale rows. Aerospike applies a time to live (TTL) on each checkpoint record at write time and reclaims it automatically.

In this tutorial, you run the expiring chat sessions cookbook from the langgraph-aerospike repository. The demo uses a simple model to take the place of an LLM acting as the chatbot, so you don’t need an API key. You configure chat records to persist in Aerospike with a short TTL, start a chat thread, resume it, wait for expiry, and confirm the prior history is gone.

Checkpoint TTL on Aerospike

AerospikeSaver is the checkpoint backend that connects LangGraph to Aerospike. It stores each checkpoint as a record in Aerospike and stamps every write with a TTL. When the TTL elapses, Aerospike deletes the record automatically.

The configure step sets the TTL duration and controls whether reading a checkpoint resets the expiry clock. The demo uses a one-minute TTL for quick verification. Production apps typically use much longer durations, such as a day or a week.

Session lifecycle to verify

The cookbook demo (demo.py) runs five phases. This tutorial groups them into two run-demo pages:

1. Configure, start, and resume (Phases 1–3): stamp a one-minute TTL, persist the first user/assistant pair, then send a second user message on the same thread_id (four messages total).
2. Expire and prove (Phases 4–5): wait past the TTL, confirm the session is gone from Aerospike, then invoke again for a fresh two-message session.

The message count is the proof: four after resume, two after expiry.

Checklist

• I understand why checkpoint TTL matters for production chat agents.