> ## 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

> Session management for multi-turn conversations. Message history, state, overflow handling, and storage drivers.

# Sessions

Sessions in Agentium track **conversation history** and **arbitrary state** per conversation. The `SessionManager` stores raw messages and replays them as context to the LLM on each run.

***

## How It Works

Every time you call `agent.run()` or `agent.stream()` with a `sessionId`, the agent:

1. Loads the session's message history from storage
2. Includes the history as conversation context to the LLM
3. After the run, appends the new user/assistant exchange to the session

If you use the same `sessionId` across multiple calls, the agent maintains a continuous conversation.

```typescript theme={null}
const agent = new Agent({
  name: "assistant",
  model: openai("gpt-4o"),
  storage: new InMemoryStorage(),
});

await agent.run("My name is Bob.", { sessionId: "conv-1" });
const result = await agent.run("What's my name?", { sessionId: "conv-1" });
// Agent knows "Bob" from the first message
```

If `sessionId` is omitted, a new UUID is generated per run — each call is a fresh conversation.

***

## Session Object

| Property    | Type                      | Description                       |
| ----------- | ------------------------- | --------------------------------- |
| `sessionId` | `string`                  | Unique identifier for the session |
| `userId`    | `string?`                 | Optional user identifier          |
| `messages`  | `ChatMessage[]`           | Conversation history              |
| `state`     | `Record<string, unknown>` | Arbitrary key-value state         |
| `createdAt` | `Date`                    | When the session was created      |
| `updatedAt` | `Date`                    | When the session was last updated |

***

## History Overflow

When `numHistoryRuns` is set on the agent, the session automatically trims older messages to stay within the limit. This prevents the context window from growing unboundedly.

```typescript theme={null}
const agent = new Agent({
  name: "assistant",
  model: openai("gpt-4o"),
  storage,
  numHistoryRuns: 25,  // keep last 25 exchanges (50 messages)
});
```

When messages overflow, if a [Memory](/agents/memory) instance is configured, the trimmed messages are sent to Memory for LLM-powered summarization. This way, old conversation context is preserved as summaries rather than lost.

***

## Token-Based Trimming

For tighter control, set `maxContextTokens` to automatically trim history based on estimated token count:

```typescript theme={null}
const agent = new Agent({
  name: "assistant",
  model: openai("gpt-4o"),
  storage,
  maxContextTokens: 4000,
});
```

The agent estimates tokens for the system prompt, current input, and history. History is trimmed from oldest first until everything fits within the budget.

***

## Session State

Sessions support arbitrary `state` for persisting data across turns. Access it via `RunContext.sessionState` in hooks or tools:

```typescript theme={null}
const agent = new Agent({
  name: "assistant",
  model: openai("gpt-4o"),
  storage: new InMemoryStorage(),
  hooks: {
    beforeRun: async (ctx) => {
      const count = ctx.getState<number>("runCount") ?? 0;
      ctx.setState("runCount", count + 1);
    },
  },
});
```

State is automatically persisted via `updateState` after each run.

***

## SessionManager API

`SessionManager` is used internally by agents but can also be used standalone:

```typescript theme={null}
import { SessionManager, InMemoryStorage } from "@agentium/core";

const sm = new SessionManager(new InMemoryStorage(), {
  maxMessages: 50,  // optional: auto-trim when exceeded
});

const session = await sm.getOrCreate("conv-1", "user-42");
const { overflow } = await sm.appendMessages("conv-1", [
  { role: "user", content: "Hello" },
  { role: "assistant", content: "Hi there!" },
]);
// overflow contains trimmed messages (empty if under maxMessages)

const history = await sm.getHistory("conv-1", 20); // last 20 messages
await sm.updateState("conv-1", { topic: "greetings" });
await sm.deleteSession("conv-1");
```

***

## Storage Drivers

<CardGroup cols={2}>
  <Card title="InMemoryStorage" icon="memory">
    Default. Sessions live in process memory. Lost on restart. Good for development.
  </Card>

  <Card title="MongoDBStorage" icon="database">
    Persistent sessions in MongoDB. Use for production.
  </Card>

  <Card title="SqliteStorage" icon="hard-drive">
    Persistent sessions in SQLite. Good for single-node deployments.
  </Card>

  <Card title="PostgresStorage" icon="server">
    Persistent sessions in PostgreSQL. Use for scalable deployments.
  </Card>
</CardGroup>

```typescript theme={null}
import { Agent, MongoDBStorage, openai } from "@agentium/core";

const storage = new MongoDBStorage(
  "mongodb://localhost:27017",
  "myapp",
  "sessions"
);
await storage.initialize();

const agent = new Agent({
  name: "assistant",
  model: openai("gpt-4o"),
  storage,
});
```

***

## Session vs Memory vs User Memory

| Layer           | Stores               | Keyed by    | Purpose                                         |
| --------------- | -------------------- | ----------- | ----------------------------------------------- |
| **Session**     | Raw messages + state | `sessionId` | Immediate conversation history, replayed to LLM |
| **Memory**      | LLM summaries        | `sessionId` | Long-term context from overflowed messages      |
| **User Memory** | Personal facts       | `userId`    | Cross-session personalization                   |

Session is always active. Memory kicks in when history overflows. User Memory persists facts about a person across all their sessions. See [Memory](/agents/memory) and [User Memory](/agents/user-memory) for details.