Run

Agent sessions

An agent session is one durable conversation with an agent. It lets a new message build on earlier messages, tool use, and remembered context instead of starting from nothing.

Sessions make the channel secondary. A conversation can begin in the Mobius app, Slack, Telegram, a product interface, or a loop step and still have the same basic shape: one agent, one coherent history, and a record you can inspect.

The most important session decision is the boundary. Reuse a session when new work should understand what happened before. Start a new one when the subject, audience, or agent behavior should be independent.

Useful boundaries include:

One Slack or Telegram conversation.
One customer support case.
One account or project inside your product.
One pull request across review and follow-up runs.
One fresh execution when prior history would bias the result.

A stable session boundary gives the agent useful continuity without mixing unrelated work.

Sessions and runs

Sessions and runs preserve different kinds of history:

Resource	What it remembers	Use it to understand
Agent session	Messages, tool activity, and summarized conversation history	What the agent and user knew and said
Loop run	Inputs, step progress, waits, results, and stop reason	What the process did

An agent step can use a session inside a run. The run owns process progress; the session owns conversational context.

Inspect a conversation in the app

Open Build > Agents, choose an agent, then select Sessions. The list shows where each conversation came from and when it was last active.

Open a session to read the transcript, inspect tool activity, and follow links back to its loop, run, or messaging source. Continue a direct conversation from Chat. Sessions owned by a loop or provider conversation stay tied to that source so an unrelated manual message cannot disturb their routing.

The completed transcript is the durable record. Live previews make an active turn responsive, but reconnecting does not erase the committed answer.

Keep long conversations useful

Long conversations eventually contain more detail than an agent should reread on every turn. Compaction summarizes older history while keeping recent messages available.

Choice	Use it when
Auto	The conversation is ongoing and Mobius should keep its context manageable.
Manual	A person should decide when older history becomes a summary.
Disabled	The session is short or exact raw history must remain in context.

Auto is the normal choice. Presets range from 10% (XS) to 80% (XL) of the session model's context window, so long-context models can retain substantially more raw conversation. Choose Exact tokens when a workload needs a fixed trigger instead. Open Compaction on a session to see its current policy, change it, or compact it now.

Model-relative presets retain more raw history than the previous fixed thresholds, especially on long-context models. That improves continuity, but can increase per-turn input cost until compaction runs. Use a smaller preset or an exact threshold when predictable input usage matters more than raw history.

Defaults from an agent, loop, or messaging binding apply when a session is created. An existing session keeps its own policy so changing a default does not unexpectedly rewrite an active conversation.

Choose loop history

For an agent step, history decides which runs reuse a session. Reuse history around a stable subject such as a pull request, customer, or incident when earlier work should inform the next run. Choose a fresh session when each run should make an independent judgment.

Set the common boundary on the loop and override an individual step only when its responsibility is different. History decides which work shares context; compaction decides how much of that context remains raw.

Bound the lifetime of a one-shot session

Sessions are permanent by default, which is right for conversations. A machine-to-machine caller that mints a fresh session per invocation, such as an augmentation call, a classification, or a one-shot generation, accumulates a permanent transcript nobody rereads after the result is consumed. A retention policy bounds that.

Set retention when a session is first created (like compaction_policy, it is ignored when an existing session is resolved):

{
  "session": {
    "mode": "new",
    "visibility": "private",
    "retention": { "mode": "bounded", "ttl_seconds": 86400 }
  }
}

standard (the default) retains the session forever. bounded expires it after it has been idle past ttl_seconds, measured from the last message activity, not creation, so continuing the session before it expires simply extends its life. The TTL runs from one hour to 30 days. Within the window nothing changes: streaming, transcript reads, idempotent retry, and failure diagnostics behave exactly like any session. The session reports expires_at so you can see the clock; it is null for standard sessions.

After a bounded session expires, its transcript is pruned from every read path and the session reads as deleted. What survives is the audit layer: a tombstone session row with its token totals, and the turn rows with their status, error, usage, and timings. This means "did it run, how did it fail, what did it cost" is still answerable, while the content is gone. Usage debits are unaffected. Because the TTL is at least an hour, a retried idempotency key after expiry mints a fresh session rather than deduplicating against a pruned one.

Retention and visibility are independent axes: visibility controls where a session appears in project surfaces, retention controls how long it lives. Bounded sessions do not contribute to agent memory.

Start fresh when history stops helping

Archive a session when its transcript has become misleading, the subject has changed, or a clean boundary is more useful than continuity. Mobius keeps the old session readable and creates a new active conversation when the same entry point is used again.

Force-unlock is a recovery tool for a turn that is genuinely stuck after normal cancellation fails. It is not a routine way to start a new topic, especially for a session owned by a loop.

The Sessions and turns API guide covers streaming, replay, compaction requests, and recovery behavior for applications. The CLI command reference covers terminal operation.

Recover detail from large tool results

Tool responses larger than 32 KiB can crowd out the conversation that explains why the agent requested them. For summarizable tools, Mobius automatically stores a compact result of about 2,000 tokens in the transcript and preserves the full response temporarily outside the model context.

The compact result identifies what was omitted and gives the agent a handle for the built-in fetch_tool_result tool. The agent can retrieve an exact byte range, continue from a returned offset, or search the full response with a regular expression. Each fetch returns at most 32 KiB, so instructions should encourage narrow searches instead of pulling the entire result back into the context window.

Full spilled results expire after about seven days. The compact result remains the durable transcript record. If exact source data must remain available longer, save it as an artifact or in your own system instead of relying on the temporary spill.

Tools whose output must remain verbatim, such as shell and file inspection tools, are not summarized by this path. The behavior is automatic; there is no per-agent UI setting to configure.

Connect conversations with agent messaging.
Decide how the agent behaves with agent definitions.
Compare conversational and process history in runs.
Control session history and turns through the Sessions and turns API.