Skip to main content

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

​
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

PropertyTypeDefaultWhat it controls
maxMessagesnumber50How many messages are kept in the active thread. Oldest are trimmed first
maxTokensnumberundefinedTrim 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 conversationSessions (this page)
A short recap of older parts of this conversationSummaries
Facts about the person, across all their conversationsUser Facts

​
Cross-references