# `ExAthena.Sessions.Store`
[🔗](https://github.com/udin-io/ex_athena/blob/v0.7.1/lib/ex_athena/sessions/store.ex#L1)

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)
    }

# `event`

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

# `session_id`

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

# `append`

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

# `list`

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

# `read`

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

# `tail`

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

# `new_event`

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

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

---

*Consult [api-reference.md](api-reference.md) for complete listing*