Reference
Agent sessions
A session is a saved conversation for one agent in one project. It contains messages, turns, and recorded action activity.
A turn is one request to the agent and the work it does in response. One session can contain many turns. Reusing a session lets a later turn use the earlier conversation as context.
Mobius keeps conversations separate with three pieces of information:
| Part | Meaning |
|---|---|
| Agent | The agent that receives the turn |
| Scope | Where the conversation belongs, such as direct messaging or a particular loop |
| History key | The identifier for one conversation inside that scope, such as a Slack thread or ticket ID |
If there is an active session for that combination, Mobius can reuse it. If there is not, Mobius creates one. Sessions do not move between projects or agents.
How different work chooses a session
| Work | How the conversation is identified |
|---|---|
| New chat in the app | Mobius creates a new history key after you send the first message |
| Existing app chat | Continue chat opens the same session ID |
| Messaging integration | The integration uses the provider's conversation identifier, such as a Slack thread |
| Agent step in a loop | The step's History setting supplies or selects the history key |
One loop run can contain several agent steps and therefore several sessions. The reverse is also possible: one session can span agent steps from several runs when those steps use the same stable history key.
Verify the boundary in the app
Select the project and use an agent that already exists. If you do not have an agent, follow Create your first agent.
- Open Build > Agents and select the agent.
- Open Sessions.
- Click New chat session. This opens an empty chat but does not create the session record yet.
- Send
The code name for this test is Cedar. - After the reply finishes, return to Sessions. Open the most recent row's action menu and choose Copy session ID. Keep this first ID for the final comparison, then choose Continue chat.
- Send
What is the code name for this test?The new reply and both of your messages remain in the same transcript. - Return to Sessions. The row shows the message count, total recorded token usage, and last-message time.
- Click New chat session again and send
What is the code name for this test? - Return to Sessions. Copy the newest row's session ID and confirm that it differs from the first ID. Open Session details and confirm that this transcript contains only the message sent after the second New chat session and its reply. It must not contain the earlier Cedar statement.
The second chat has a different session ID and a new transcript. That visible ID and transcript, rather than the wording of the agent's answer, prove that the conversations are separate. Agent memory can supply facts across sessions, so do not use the answer alone as proof of session reuse.
To inspect a row, open its action menu and choose Session details. The page shows the session ID, its association with a chat or loop, the saved transcript, turn statuses, and action activity. Use Continue chat only on direct app or messaging conversations that Mobius allows you to continue. A loop-owned session opens as a read-only record with a link to its run.
If a control is missing or disabled, confirm that you are in the correct project and ask a project administrator whether your role can manage sessions.
Choose history for loop steps
Open the loop editor and use the History setting on the loop or on one Agent step.
| Choice | Behavior |
|---|---|
| Auto | Let the run source choose its normal boundary. Use an explicit option when continuity is important. |
| Pull request | Reuse one history key for the same pull request across runs. |
| Fresh run | Create a different history key for every run. |
| Custom | Set a boundary and a key template, such as ticket:${{ event.ticket.id }}. |
Start with Fresh run when each run should be an independent judgment. Reuse history only when you can name the subject that should connect the runs.
For a custom key, make sure every triggering event contains the referenced field. Test two events with different IDs and confirm that their session IDs differ. Then test the same ID twice and confirm that it reuses the session you expected.
History and memory are different. History selects messages from one conversation. Agent memory can add selected facts to turns in separate sessions.
Saved transcript versus model context
The session detail page is the saved record. The text sent to the model for a new turn is built from that record and the agent's current configuration.
That model context can include:
- current agent instructions;
- configured agent memory;
- messages and recorded action activity from the selected session;
- a summary in place of older messages after compaction; and
- shortened action results when a full result is too large.
For this reason, the saved transcript is not a byte-for-byte display of the next model request. The token totals in the Sessions list are cumulative usage recorded for the session, not the size of the context for the next turn.
Session or run?
An agent step in a loop produces both records.
| Record | Use it to answer |
|---|---|
| Session | Which messages, turns, and action activity were in the agent conversation? |
| Run | Which loop steps ran, waited, failed, or completed? |
Open the run to follow the whole process. Open the session to inspect the agent conversation used by one or more agent steps.
Compact a long conversation
Long conversations can exceed the amount of context a model accepts. Compaction writes a summary of older messages. Later turns use the summary and recent messages instead of sending the entire older conversation to the model.
Compaction does not delete the original messages from the saved transcript. The session detail page places the older messages behind a compaction divider, where you can expand and inspect them.
| Strategy | Behavior |
|---|---|
| Auto | Compact when the session reaches a saved percentage of the model's context capacity or an exact token threshold |
| Manual | Do not compact at a threshold, but keep Compact now available |
| Disabled | Do not compact and make Compact now unavailable |
With Manual or Disabled, a long session can reach the model's context limit and cause a later turn to fail. Disabled is different from Manual because it also prevents a person from starting compaction.
To change one session:
- Open Session details.
- Click the Session settings icon in the session header.
- Choose the compaction strategy, threshold, and summary model.
- Click Save.
The confirmation reads Session settings updated. These settings affect only this session. Changing an agent's default later does not change sessions that already exist.
Click Compact now to summarize messages since the previous compaction. A Compaction started confirmation appears, and the transcript shows a compaction divider after the operation finishes. Compaction can run again as the conversation grows. It cannot reconstruct details that the summary omitted from a later model context, although the original saved messages remain readable.
Archive or delete a session
From the active Sessions list, open a row's action menu. Depending on its source, the menu calls the record a conversation or a run transcript:
- Archive changes its status and removes it from the active list. Mobius retains the transcript, but the current app list has no archived filter. Copy the session ID before archiving if you may need to retrieve it through the Sessions API.
- Delete opens a confirmation. The app removes the session from normal views and warns that it cannot be restored. Do not use Delete when Archive is sufficient.
In a direct chat, Session actions > Archive & start fresh archives the current session and opens an empty chat. The confirmation says Session archived. The replacement session is created only after you send the first message, and it receives a new session ID.
Recover a stuck direct chat
Use the normal Stop control first when a direct-chat turn is still running. Consider Force-unlock (stuck turn) only when the turn remains non-terminal and blocks new messages after that stop attempt.
From the chat or session header:
- Open Session actions.
- Choose Force-unlock (stuck turn).
- Read the confirmation and choose Force-unlock only if you accept the stated risk.
Success is reported as Session unlocked, and the composer becomes available for another message. Force-unlock stops every in-flight turn for that session. It cannot undo an external action that already completed.
Do not use this as the first recovery step for a loop-owned session. Open the associated run, inspect its Timeline and the destination of any external actions, then cancel or reconcile the run as needed. Force-unlocking a loop-owned turn can leave the run waiting for work that was stopped outside the normal loop flow.
Large action results
For actions configured as safe to shorten, Mobius keeps about 2,000 tokens in the transcript context and stores a reference to the larger result. The agent can fetch narrow ranges from that result, but the larger stored copy expires after about seven days. The compact transcript entry remains.
Save source files or results that must remain available as an artifact or in the system that owns them. The Sessions and turns API guide documents streaming, compaction, result retrieval, and recovery behavior for applications.
Next
- Control the agent's behavior with agent definitions.
- Connect conversations to other services with agent messaging.
- Compare conversation history with process history in runs.
- Use sessions from code with the Sessions and turns API.