Resume session

Resume is implicit. The platform never asks "create new or resume?" — every $prompt either continues an existing session for (targetKey, profileKey) or creates one. The user-facing concept of "resume" is just "the next prompt in the same conversation."

How resume is triggered

When $prompt arrives at AgentsRoot:

1. The root resolves (targetKey, profileKey) from the incoming message.
2. It calls AgentsStore.listSessions(targetKey) (AgentsStore.ts:468-472), which returns sessions ordered by last_active DESC.
3. The most recent session whose profile_key matches is reused. Its session id flows into the spawned AgentActor.

What gets restored on resume

The agent loop's resume path is built by OraclePromptBuilder.buildResumeContext (the IResumePromptContext* types in oracle/OraclePromptBuilder.ts). It pulls together:

Resource	Source
Prior messages	AgentsStore.loadMessages(sessionId)
REPL state (omega-lisp)	AgentsStore.loadSessionState(sessionId, 'repl_state')
Target snapshot	AgentsStore.loadSessionState(sessionId, 'snapshot')
Activity frames (for $traceQuery)	IAgentSessionStore.loadActivityFrames(sessionId)

The system prompt is rebuilt fresh — only the conversation state and the target snapshot are restored.

Manual session listing

If a caller wants to choose explicitly which session to resume, the surface is:

matrix invoke system.agents '$sessionList' '{ "targetKey": "system.registry" }'

$sessionList returns SessionMeta[] (AgentsStore.ts:63-72) sorted by last_active.

What does NOT trigger a resume

• A different targetKey (different actor) — always creates a new session.
• A different profileKey (e.g. switching from default to explain) — always creates a new session under the new profile.
• Calling $prompt after $sessionDelete of the most recent session — the next-most-recent (if any) is reused, otherwise a fresh session is created.

Cross-shell visibility

Because the session record lives in the system.agents.memory SQLite store, it is visible across shells: a session created in Director is the same row Chat sees, provided both shells target the same (targetKey, profileKey). The cross-surface session-list UX in Chat is partial today (see Status note in Sessions overview).

See also

• Create session
• Session context
• Session lifecycle

Source: projects/matrix-3/packages/agents/src/AgentsStore.ts:468-484 (session list), resume-context types in projects/matrix-3/packages/agents/src/oracle/OraclePromptBuilder.ts.