Sessions

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

Sessions

Sessions in RadarOS 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.

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 "@radaros/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 "@radaros/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.