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:

Loads the session’s message history from storage
Includes the history as conversation context to the LLM
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.

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.

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

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:

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:

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

InMemoryStorage

Default. Sessions live in process memory. Lost on restart. Good for development.

MongoDBStorage

Persistent sessions in MongoDB. Use for production.

SqliteStorage

Persistent sessions in SQLite. Good for single-node deployments.

PostgresStorage

Persistent sessions in PostgreSQL. Use for scalable deployments.

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 and User Memory for details.

​Sessions

​How It Works

​Session Object

​History Overflow

​Token-Based Trimming

​Session State

​SessionManager API

​Storage Drivers