Sessions

A session is a stateful execution context that persists across multiple runs within the Agent Server. Sessions maintain conversation history, tool result caches, and accumulated metadata — enabling multi-turn interactions and long-running tasks with checkpoint resumption.

Why Sessions?

Agents often need to maintain state beyond a single request-response cycle. Sessions solve several challenges that arise in production agent deployments:

Multi-Turn Conversations

Maintain context across back-and-forth exchanges without replaying the entire history on each request. The agent remembers what was discussed, what decisions were made, and what tasks are in progress.

Long-Running Tasks

Complex operations — document analysis pipelines, multi-step research workflows, iterative code generation — can span minutes or hours. Sessions preserve progress so that work is never lost to transient failures.

Checkpoint Resumption

If a run fails midway through execution, the Agent Server resumes from the last successful checkpoint rather than starting over. This is critical for workflows that involve expensive LLM calls or external API interactions.

Context Accumulation

Over the course of a session, the agent accumulates relevant information: user preferences, resolved entities, intermediate results, and task progress. This growing context enables increasingly informed responses.

Session State

A session encapsulates four categories of state:

Message History

An ordered list of user and assistant messages that form the conversation thread. Each message includes:

• Role — user, assistant, or system
• Content — The message text or structured content
• Timestamp — When the message was created
• Run ID — Which run produced this message

The message history provides the conversational context that the agent uses to generate coherent, contextually appropriate responses across turns.

Tool Result Cache

Cached outputs from tool invocations, keyed by tool name and input parameters. The cache prevents redundant tool calls when the same operation is requested within a session.

When a tool is invoked, the Agent Server checks the cache first. If a valid cached result exists, it is returned immediately without executing the tool again.

Metadata

Accumulated key-value pairs that track session-level information:

• User preferences — Formatting choices, language, output verbosity
• Resolved entities — Names, identifiers, and references resolved during conversation
• Task progress — Status of multi-step operations
• Custom data — Application-specific metadata set via the API

Metadata persists for the lifetime of the session and is available to all runs within it.

Checkpoint References

Links to checkpoint snapshots that capture the full execution state at specific points in time. Checkpoints enable recovery and resumption, described in detail below.

Persistence

Sessions are durably stored to survive server restarts, deployments, and failures.

Conversation State

Session data is persisted in PostgreSQL via ConversationState, which stores:

• Message history as a JSONB array
• Tool result cache entries with TTL metadata
• Session metadata as a JSONB document
• References to associated checkpoints

Checkpoint Storage

Checkpoint snapshots are managed by PostgresCheckpointStore and stored in the workflow_checkpoints table:

workflow_checkpoints
├── id              UUID PRIMARY KEY
├── session_id      UUID REFERENCES sessions(id)
├── run_id          UUID REFERENCES runs(id)
├── state           JSONB        -- Full execution state snapshot
├── step_index      INTEGER      -- Position in execution sequence
├── created_at      TIMESTAMPTZ
└── updated_at      TIMESTAMPTZ

Checkpoints are indexed by updated_at for efficient retrieval of the most recent snapshot. The state column stores the complete execution context as JSONB, including the agent’s internal state, pending tool calls, and intermediate results.

Automatic Checkpointing

The Agent Server creates checkpoints at configurable intervals during run execution:

• After each tool call — Default behavior, captures state after every tool invocation
• At step boundaries — Checkpoint at defined execution steps
• Time-based — Checkpoint every N seconds of execution
• Manual — Triggered explicitly via the API

Memory Integration

Sessions integrate with M3 Forge’s memory system to provide layered context that extends beyond a single session’s lifetime.

Memory Scopes

How Scope Affects Agent Behavior

none — The agent treats every request as independent. No prior context is available. Suitable for simple, self-contained operations like format conversion or single-query lookups.

session — The agent remembers everything discussed within the current session. When the session ends or expires, session-scoped memories are discarded. This is the default scope for most interactions.

user — The agent recalls information from previous sessions with the same user. Preferences set in one session (“always use metric units”) carry forward to future sessions. User-scoped memory persists independently of session lifecycle.

group — The agent accesses memories shared across all agents in its memory group. Research findings from one agent are available to analysis agents in the same group. Group memory is powered by marie-mem0 with semantic search capabilities.

Scope Configuration

Memory scope is configured at the assistant level and applies to all sessions created for that assistant:

assistant:
  name: customer-support-agent
  memory:
    scope: user
    retention: 30d
    max_entries: 1000

Sessions inherit the memory scope from their parent assistant. Individual sessions cannot override the scope, ensuring consistent behavior across the assistant’s interactions.

Session Management

Create a Session

POST /sessions

{
  "assistant_id": "asst_abc123",
  "metadata": {
    "customer_id": "cust_456",
    "channel": "web"
  }
}

Returns a session object with a unique id that is used to associate subsequent runs with this session.

List Sessions

GET /sessions

Query parameters for filtering:

Get Session

GET /sessions/{id}

Returns the full session state including message history, metadata, and checkpoint references. The tool result cache is not included in the response by default — pass ?include=cache to include it.

Delete Session

DELETE /sessions/{id}

Deletes the session and all associated checkpoints. This is a soft delete — the session is marked as deleted and excluded from list queries. Hard deletion occurs after the retention period.

Session Lifecycle

Created → Active → Paused → Active → Expired → Deleted
                                  ↘ Deleted

TTL and Expiration

Sessions have a configurable time-to-live based on inactivity:

• Default TTL — 7 days since last activity
• Per-assistant override — Configure shorter or longer TTL per assistant
• Activity reset — Any run within a session resets the TTL clock

Expired sessions are soft-deleted and excluded from active queries. After the retention period (configurable, default 30 days), expired sessions are permanently purged along with their checkpoints and cached data.

Sessions vs Chat Threads

The distinction matters for understanding where state lives:

A Chat Thread creates a new Session when:

• The user starts a conversation with an assistant for the first time
• The previous session has expired
• The assistant configuration requires a fresh session per interaction

Human-in-the-Loop

Sessions provide the state management foundation for HITL workflows within the Agent Server.

Pause and Resume

When a run encounters a step requiring human review, the session transitions to the paused status:

1. Run encounters HITL step — The agent identifies a decision requiring human input
2. Session pauses — Full execution state is checkpointed and the session status changes to paused
3. HITL request created — A review request is routed to the appropriate queue
4. Human provides input — Reviewer approves, rejects, or provides corrections
5. Session resumes — The agent resumes from the checkpoint with the human’s input incorporated

State Preservation During Pause

While paused, the session retains:

• Complete message history up to the pause point
• All tool result cache entries (TTLs continue to tick)
• Metadata accumulated during the run
• The checkpoint snapshot from immediately before the pause

No data is lost during the pause. The agent resumes exactly where it left off.

HITL Decision Recording

Human decisions made during HITL review are recorded in the session metadata:

{
  "hitl_decisions": [
    {
      "step": "document_classification",
      "decision": "approved",
      "reviewer": "user_789",
      "timestamp": "2026-03-24T14:30:00Z",
      "notes": "Classification correct, proceed with extraction"
    }
  ]
}

This audit trail is preserved for the lifetime of the session and is available for compliance reporting and model improvement.

Best Practices

Session Granularity

One session per logical conversation. Do not reuse sessions across unrelated tasks. A customer support interaction about billing should be a separate session from a product inquiry, even if it is the same user.

TTL Configuration

Set TTL based on your use case:

• Interactive chat — 1-2 hours (short conversations)
• Multi-day research — 7 days (extended investigations)
• Compliance workflows — 90 days (audit trail retention)

Cache Management

Monitor tool result cache size for sessions with heavy tool usage. If an agent calls dozens of unique tools per run, the cache can grow large. Configure max_entries on the assistant to cap cache size and rely on LRU eviction to keep the most relevant entries.

Checkpoint Frequency

Balance checkpoint frequency against storage costs:

• After every tool call — Maximum recoverability, higher storage usage
• At step boundaries — Good balance for most workflows
• Time-based (every 60s) — Suitable for long-running computations

Next Steps

• Runs — Understand how runs execute within sessions
• Assistants — Configure session behavior at the assistant level
• Scheduled Runs — Automate recurring runs within sessions
• Architecture — Learn how sessions fit into the Agent Server’s architecture