ExAthena.Sessions.Store behaviour (ExAthena v0.4.0)

Copy Markdown View Source

Behaviour for append-only session event storage.

Sessions emit one event per loop transition (user message, assistant message, tool call, tool result, compaction, iteration, session start/end). A Store module decides where those events live: an in-memory ETS table, a JSONL file, an external service, etc.

The default store is ExAthena.Sessions.Stores.InMemory — fast, ephemeral, perfect for tests and short-lived runs. The ExAthena.Sessions.Stores.Jsonl store buffers events in ETS and flushes to disk every 250ms, giving you portable + replay-friendly storage at near-zero hot-path cost.

Event shape

Each event is a map:

%{
  ts: iso8601_string(),
  event: atom(),     # :session_start | :user_message | …
  data: map(),       # event-specific payload
  uuid: binary()     # stable per-event id (for chain patching + rewind)
}

Summary

Types

event()
session_id()

Callbacks

append(session_id, event)
list()
read(session_id)
tail(session_id, n)

Functions

new_event(event, data)

Build a new event with a generated uuid + ISO 8601 timestamp.

Types

event()

@type event() :: %{ts: String.t(), event: atom(), data: map(), uuid: String.t()}

session_id()

@type session_id() :: String.t()

Callbacks

append(session_id, event)

@callback append(session_id(), event()) :: :ok

list()

@callback list() :: [session_id()]

read(session_id)

@callback read(session_id()) :: {:ok, [event()]} | {:error, term()}

tail(session_id, n)

@callback tail(session_id(), n :: pos_integer()) :: {:ok, [event()]} | {:error, term()}

Functions

new_event(event, data)

@spec new_event(atom(), map()) :: event()

Build a new event with a generated uuid + ISO 8601 timestamp.