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:

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

// 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), 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
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

Memory Stores Summaries

​Sessions & History

​In plain terms

​When to use it

​When you don’t need it

​Configuration

​Sessions vs other stores

​Cross-references