Sessions

An agent session is the durable record of one conversation between a caller (a human or another agent) and a (targetKey, profileKey) pair. Sessions are persisted in the agents SQLite database and addressed by id.

Session record

From AgentsStore.ts:63-72 (SessionMeta) and schema.sql:146-155 (sessions table):

Field	Type	Notes
id	string	session id, generated when the session is created
targetKey	string	the actor the conversation is about (e.g. system.registry)
profileKey	string	the agency profile in use (default "default")
principalId	string | null	the user/agent who created the session
title	string | null	derived from the first user message
turnCount	integer	incremented on each user turn
createdAt, lastActive	epoch-ms	timestamps

Two child tables are tied to a session id: session_messages (schema.sql:159-176) and session_state (schema.sql:178-184).

Identity = (targetKey, profileKey)

Sessions are scoped to a target. Two distinct targets, even for the same user, give two distinct sessions. profileKey further partitions sessions per agency profile (default, explain, edit, propose, evaluate, monitor — see BUILT_IN_AGENCY_PROFILES in profiles/AgencyProfile.ts).

What's stored

• Messages. role (user/assistant/tool), content, plus full tool call shape (tool_name, tool_target, tool_op, tool_args, tool_result, tool_duration_ms) and OpenTelemetry trace IDs (trace_id, span_id).
• State. Free-form JSON keyed by string. Used today for repl_state (the embedded omega-lisp REPL snapshot) and snapshot (the target's introspect tree at session start).
• Activity frames. The IAgentSessionStore interface (IAgentSessionStore.ts:79-80) defines appendActivityFrames / loadActivityFrames for per-request trace logs. Two backends ship today: FileAgentSessionStore (filesystem) and RecordBackedSessionStore (observability record store adapter).

What's NOT stored

• The agent's intermediate thinking is replayed from activity frames, not from a separate "thoughts" table.
• Embeddings are stored under the memory record they describe (memory_embeddings), not the session.
• Inference provider credentials are never persisted in the session — they live in Factotum.

Lifecycle

1. Create. First $prompt for a target without an active session creates a row via session.create (AgentsStore.createSession).
2. Append. Every turn appends user/assistant/tool messages via appendMessages. The trigger updates last_active and bumps turn_count.
3. Resume. Subsequent $prompts for the same (targetKey, profileKey) resume the most recent session.
4. Delete. Either single ($sessionDelete) or bulk ($sessionClearAll). Both cascade into session_messages and session_state.

Target state

Today, the session-list UI in Director Chat tab shows live sessions but the dedicated session list, session persistence across restarts, and session resume UX in ChatPanel are listed as missing in the working notes (MEMORY.md § ConversationSurface). The agent-side persistence is solid — the gap is on the surface side.

See also

• Sessions section for create/resume/attach-artifact pages
• Reference: session schema

Source: projects/matrix-3/packages/agents/schema.sql lines 146-184 (the three session tables); projects/matrix-3/packages/agents/src/AgentsStore.ts:455-580 (session CRUD).