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. History survives a process restart only when the configured storage persists it. A fallback or explicit in-memory store loses it when the process ends. Agents keep fallback session history without explicit memory configuration. Adding memory.storage selects its storage backend and enables the configured unified-memory features.

When to use it

Use sessions for a continuing conversation; use a fresh owned session for independent work. Choose a storage driver explicitly when its lifetime matters. This host function receives a configured model and host-owned storage:

import { Agent, type ModelProvider, type StorageDriver } from "@agentium/core";

export async function demonstrateSession(model: ModelProvider, storage: StorageDriver) {
  const agent = new Agent({
    name: "assistant", model, register: false,
    memory: { storage, summaries: false },
  });
  try {
    await agent.run("My name is Alex", { sessionId: "demo", userId: "alice" });
    return await agent.run("What is my name?", { sessionId: "demo", userId: "alice" });
  } finally {
    await agent.close({ closeStorage: false });
  }
}

The second result should refer to Alex. The host closes its storage after all users of that driver have drained. Use an owned session ID and verified identity in a real service; see the Agent memory example for installation and a live run.

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, which persist across all of a user’s sessions.

Configuration

Property	Type	Default	What it controls
`maxMessages`	`number`	`50`	Soft limit for retained history; trimming preserves whole turns
`maxTokens`	`number`	`undefined`	Additional token budget for history sent to the model; separate from stored message retention

// 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 is enabled (the default), overflow can be summarized asynchronously. A summary can omit detail or fail; persist a separate transcript if the original messages must be retained. maxMessages vs maxTokens: use maxMessages for simplicity (predictable, easy to reason about). Use maxTokens when message lengths vary wildly and you want to budget history when message lengths vary. Account separately for instructions, tools, memory context, and output.

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
Facts about the person, across all their conversations	User Facts

Cross-references

Memory Overview — how all the stores fit together
Summaries — what happens to overflow messages
Incremental Sessions — append-only session storage for high write throughput
Storage Backends — where sessions are persisted

Build

Agent applications

Harness runtime

Teams and workflows

Data and capabilities

Interfaces and jobs

Voice and telephony

Verify and manage

Sessions & History

In plain terms

When to use it

When you don’t need it

Configuration

Sessions vs other stores

Cross-references

​In plain terms

​When to use it

​When you don’t need it

​Configuration

​Sessions vs other stores

​Cross-references

In plain terms

When to use it

When you don’t need it

Configuration

Sessions vs other stores

Cross-references