Overview

Short-term memory stores messages, tool interactions, and state so later turns can restore context. Sessions are identified by app_name, user_id, and session_id; continuing a session requires the same storage backend and all three identifiers The agent configuration supplies system instructions. Compaction, filtering, and agent settings also determine which history reaches the model. Persisting a session does not mean sending its entire history unchanged on every turn

Short-term memory builds on Google ADK’s Session mechanism. For background, see Google ADK Session.

Single entry point: ShortTermMemory

Whatever backend you use, you interact with one class — veadk.memory.short_term_memory.ShortTermMemory. It selects the storage mode based on backend (or db_url) and exposes a uniform session-management surface.

from veadk.memory.short_term_memory import ShortTermMemory

# Select the implementation via backend
stm = ShortTermMemory(backend="sqlite", local_database_path="./stm.db")

Parameters

Parameter	Type	Default	Description
`backend`	`"local" \| "sqlite" \| "mysql" \| "postgresql" \| "database"`	`"local"`	Selects the backend. `database` is deprecated and equivalent to `sqlite`.
`db_url`	`str`	`""`	A database connection string (e.g. `sqlite+aiosqlite:///./test.db`). Once set, `backend` is ignored, and `db_url` is used with `db_kwargs`.
`backend_configs`	`dict`	`{}`	Backend-specific settings, such as overriding database connection configuration through `mysql_config` or `postgresql_config`.
`db_kwargs`	`dict`	`{}`	Additional database connection or connection-pool settings.
`local_database_path`	`str`	`/tmp/veadk_local_database.db`	Local DB file path, used only by `sqlite`.
`after_load_memory_callback`	`Callable \| None`	`None`	Synchronous read callback; receives `Session` or `None` plus the query arguments. Use `def callback(session, args, *kwargs)`
`after_create_session_callback`	`Callable \| None`	`None`	Synchronous or asynchronous callback invoked after a new session is created; receives the new `Session` and is not invoked when an existing session is reused.

If a username or password in the connection string contains special characters such as @ or :, URL-encode it with urllib.parse.quote_plus first (e.g. p@ssword → p%40ssword), otherwise parsing fails.

Backend behavior

All backends provide the same session-management operations. They differ in persistence location and connection method:

local keeps sessions in the current process only;
sqlite writes sessions to a local file;
mysql and postgresql write sessions to an external database for multi-instance sharing.

Choosing a backend

Backend	Persistent	External service	Use case	Docs
`local`	No (memory only)	None	Local debugging, ephemeral sessions	In-memory
`sqlite`	Yes (local file)	None	Single-node persistence	SQLite
`mysql`	Yes	MySQL	Distributed persistence	MySQL
`postgresql`	Yes	PostgreSQL	Distributed persistence	PostgreSQL

Working with the Runner

Short-term memory is usually passed to the Runner, which then creates or restores sessions automatically. Complete model configuration, then reuse the app, user, and session identifiers to continue the context

import asyncio

from veadk import Agent, Runner
from veadk.memory.short_term_memory import ShortTermMemory

stm = ShortTermMemory(backend="sqlite", local_database_path="./stm.db")
agent = Agent(name="memory_agent", instruction="Remember what the user tells you.")
runner = Runner(agent=agent, short_term_memory=stm, app_name="memory_demo", user_id="user_42")

async def main():
    sid = "user-42-chat"
    try:
        print(await runner.run(messages="My name is Ming and my favorite color is blue.", session_id=sid))
        print(await runner.run(messages="What's my name? What's my favorite color?", session_id=sid))
    finally:
        await stm.session_service.close()

asyncio.run(main())

If you pass neither short_term_memory nor session_service to the Runner, it falls back to creating a local (in-memory) short-term memory automatically.

Session management interface

You rarely create or manage a Session directly; instead you use session_service to manage the full lifecycle:

Start a session create_session(): create a new Session when the user starts interacting.
Resume a session get_session(): retrieve a Session by session_id to continue.
Save progress append_event(): append a new interaction (Event) to the history.
List sessions list_sessions(): query active sessions for a user and app.
Clean up delete_session(): delete a Session and its associated data.

A session-creation callback lets you provision resources, record an audit event, or synchronize an external system after a session is first created. Register after_create_session_callback:

from veadk.memory.short_term_memory import ShortTermMemory

async def after_create_session(session):
    print(f"Created session: {session.id}")

stm = ShortTermMemory(
    after_create_session_callback=after_create_session,
)

The callback runs only when a new session is actually created; it is not invoked when an existing session is reused. The callback may be a synchronous function or an asynchronous function (async def). If it raises an exception, the exception is propagated to the caller and agent execution does not continue.

For every backend, ShortTermMemory.create_session() first checks for and reuses an existing session with the same app_name, user_id, and session_id to avoid duplicates. The callback only runs on first creation.

Context compaction

As a conversation grows, the history keeps expanding, increasing what the model must process and slowing responses. Context compaction summarizes the history with a sliding window: when the history exceeds a threshold, older events are compacted automatically.

Configure compaction

Pass the App configuration below to a Google ADK Runner or app loader that supports it to compact history at the configured invocation interval. Creating an App alone does not run compaction.

from google.adk.apps.app import App, EventsCompactionConfig

from veadk import Agent

root_agent = Agent(
    name="my_agent",
    instruction="You are a helpful assistant who answers politely.",
)

app = App(
    name="my_agent",
    root_agent=root_agent,
    events_compaction_config=EventsCompactionConfig(
        compaction_interval=3,  # compact every 3 new calls
        overlap_size=1,         # overlap with 1 invocation from the previous window
    ),
)

Custom compactor

Use LlmEventSummarizer to set the model and prompt template for compaction. Provide the model’s API key and base via environment variables (read from os.environ, never hard-code):

import os

from google.adk.apps.app import App, EventsCompactionConfig
from google.adk.apps.llm_event_summarizer import LlmEventSummarizer
from google.adk.models.lite_llm import LiteLlm

from veadk import Agent

root_agent = Agent(
    name="my_agent",
    instruction="You are a helpful assistant who answers politely.",
)

summarization_llm = LiteLlm(
    model="volcengine/doubao-seed-2-1-pro-260628",
    api_key=os.environ["MODEL_AGENT_API_KEY"],
    api_base=os.environ.get(
        "MODEL_AGENT_API_BASE", "https://ark.cn-beijing.volces.com/api/v3/"
    ),
)

my_compactor = LlmEventSummarizer(
    llm=summarization_llm,
    prompt_template="""Summarize this conversation:
{conversation_history}

1. Keep key entities, data points, and timeline;
2. Highlight the core problems discussed and their solutions;
3. Stay logically coherent and context-relevant;
4. Remove repetition and redundant details.""",
)

app = App(
    name="my_agent",
    root_agent=root_agent,
    events_compaction_config=EventsCompactionConfig(
        compactor=my_compactor,
        compaction_interval=5,
        overlap_size=1,
    ),
)

A custom template must contain {conversation_history}; otherwise the summary request contains no history to summarize. The app above is application configuration and must be passed to a Google ADK Runner or app loader that supports App. Constructing it alone does not run conversations or compaction. Compaction makes additional model requests, and summaries may omit detail, so they are not backups of the original conversation after_load_memory_callback must be synchronous, may receive None for a missing session, and should accept query keyword arguments. after_create_session_callback runs only for sessions created through ShortTermMemory.create_session(); direct session_service.create_session() calls bypass it. A failed callback does not automatically remove the session that was already created

Get started

Core components

Observability

Extensions

Frontend

Security

Deployment

Overview

Single entry point: ShortTermMemory

Parameters

Backend behavior

Choosing a backend

Working with the Runner

Session management interface

Context compaction

Configure compaction

Custom compactor

​Single entry point: ShortTermMemory

​Parameters

​Backend behavior

​Choosing a backend

​Working with the Runner

​Session management interface

​Context compaction

​Configure compaction

​Custom compactor

Single entry point: ShortTermMemory

Parameters

Backend behavior

Choosing a backend

Working with the Runner

Session management interface

Context compaction

Configure compaction

Custom compactor