AIR

Context storage architecture

This page describes the storage layer underneath Session. If you only need to use sessions, see core/sessions.md instead. If you need to understand token budget trimming, see features/context-optimization.md.

ContextStore interface

air.context.base.ContextStore is an abstract base class with six async methods, all keyed by a session_id string:

python
async def add_message(self, session_id, role, content, provider=None, model=None) -> None
async def get_messages(self, session_id) -> list[Message]
async def get_history(self, session_id) -> list[dict]
async def clear_session(self, session_id) -> None
async def delete_session(self, session_id) -> None
async def list_sessions(self) -> list[str]

get_messages returns AIR Message objects (role plus content only), used to rebuild the ChatRequest sent to a provider. get_history returns plain dicts with the full stored record (role, content, provider, model, created_at), used for Session.history().

Built in implementations

  • air.context.memory.InMemoryContextStore: a plain dict of lists, no persistence, no file created. This is what AIR() uses by default when persist is not passed.
  • air.context.sqlite.SQLiteContextStore: backed by the standard library sqlite3 module, one connection per instance, guarded by an asyncio.Lock. Used automatically when you pass persist="path/to/file.db" to AIR(...). Exposes an additional close() method (not part of the ContextStore interface) that AIR.close() calls if present.

Both implementations store only what Session gives them: session id, role, content, provider name, model, and a timestamp. Neither implementation stores API keys or provider objects; see core/sessions.md.

Session as the only built in consumer

air.context.session.Session is the only place in AIR that reads and writes through a ContextStore in the current source. AIR.session(session_id) is the supported way to obtain a Session; there is no documented use case for constructing ContextStore implementations directly unless you are implementing your own backend.

Writing your own backend

Implement the six methods above and pass an instance somewhere AIR expects a context store. There is no public constructor argument on AIR for supplying a custom ContextStore directly in the current version; AIR.__init__ always constructs either InMemoryContextStore or SQLiteContextStore depending on persist. If you need a different backend, use air.session(...)'s returned Session for routing/optimization behavior and manage your own storage separately, or subclass/patch AIR._context_store directly (an internal attribute, not a stable public API).