> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentium.in/llms.txt
> Use this file to discover all available pages before exploring further.

# Sessions & History

> The conversation transcript — what was said in the current chat, remembered across runs.

# Sessions & History

## In plain terms

A **session** is the running transcript of one conversation. It's how the agent remembers what was said two messages ago — and two days ago, if it's the same session.

> **The analogy:** it's the chat thread itself. Close the app and reopen it; the conversation is still there because the session was saved.

This is the **foundation of memory** — it's on automatically the moment you add a `storage` backend. Everything else (facts, summaries, entities) builds on top of it.

## When to use it

Always. Any agent that has a back-and-forth conversation needs sessions. You enable it implicitly just by setting `storage`:

```typescript theme={null}
const agent = new Agent({
  name: "assistant",
  model: openai("gpt-4o"),
  memory: { storage: new SqliteStorage("app.db") },   // sessions now ON
});

// Pass the SAME sessionId to continue a conversation
await agent.run("My name is Alex", { sessionId: "s1", userId: "u1" });
await agent.run("What's my name?", { sessionId: "s1", userId: "u1" });
// → "Your name is Alex."
```

## When you don't need it

* **One-shot, stateless calls** (a classify-this-text endpoint that never has a follow-up). You can still pass `storage`; it just won't matter.
* For *cross-session* memory ("remember me next week, in a new conversation"), sessions alone aren't enough — turn on [User Facts](/memory/user-facts), which persist across all of a user's sessions.

## Configuration

| Property      | Type     | Default     | What it controls                                                                            |
| ------------- | -------- | ----------- | ------------------------------------------------------------------------------------------- |
| `maxMessages` | `number` | `50`        | How many messages are kept in the active thread. Oldest are trimmed first                   |
| `maxTokens`   | `number` | `undefined` | Trim by token count instead of message count — keeps history within a context-window budget |

```typescript theme={null}
// Keep the last 30 messages (≈15 turns)
memory: { storage, maxMessages: 30 }

// Or trim by tokens to fit a context window
memory: { storage, maxTokens: 8000 }
```

**What happens when the limit is hit:** the oldest messages are removed from the active thread. If [Summaries](/memory/summaries) is enabled (the default), those removed messages are first compressed into a recap so their content isn't lost — only the verbatim text is dropped.

**`maxMessages` vs `maxTokens`:** use `maxMessages` for simplicity (predictable, easy to reason about). Use `maxTokens` when message lengths vary wildly and you want to protect against context-window overflow regardless of how chatty the messages are.

## Sessions vs other stores

| You want to remember…                                    | Use                              |
| -------------------------------------------------------- | -------------------------------- |
| What was said in *this* conversation                     | **Sessions** (this page)         |
| A short recap of *older* parts of this conversation      | [Summaries](/memory/summaries)   |
| Facts about the *person*, across all their conversations | [User Facts](/memory/user-facts) |

## Cross-references

* [Memory Overview](/memory/overview) — how all the stores fit together
* [Summaries](/memory/summaries) — what happens to overflow messages
* [Incremental Sessions](/memory/incremental-sessions) — append-only session storage for high write throughput
* [Storage Backends](/storage/overview) — where sessions are persisted