Create session

A session is created in one of two ways: an explicit session.create call, or implicitly on the first $prompt for a target that has no existing session.

Explicit: `session.create`

Op declared on AgentsRoot (AgentsRoot.ts:104):

'session.create': {
  description: 'Create or ensure an agent session record',
  sessionId: 'string',
  targetKey: 'string',
  principalId: 'string?',
}

Behavior is idempotent: AgentsStore.createSession (AgentsStore.ts:455-460) uses INSERT OR IGNORE. If the row already exists, the call is a no-op and returns success. If it does not exist, a new row is written with:

Column	Source
`id`	the `sessionId` argument
`target_key`	the `targetKey` argument
`profile_key`	argument or default `"default"`
`principal_id`	argument or `null`
`turn_count`	`0`
`created_at`, `last_active`	`Date.now()`

Example

bash

matrix invoke system.agents session.create '{
  "sessionId": "ses_2026-05-05-abc",
  "targetKey": "system.registry",
  "principalId": "richard@nimbletec.com"
}'

Implicit: first `$prompt` for a target

When $prompt arrives at AgentsRoot and no active session matches (targetKey, profileKey), the root creates one before spawning the child agent. The session id is generated server-side. The first user message is appended via appendMessages, which also derives a title (the first 72 chars of the prompt — _deriveSessionTitle in AgentsStore.ts:640-644).

This is the path Director and Chat use. Callers do not need to call session.create first — $prompt is the canonical entry point.

What's NOT created

Inference credentials. The provider config is hydrated from system.inference defaults in AgentsRoot.onBootstrap (AgentsRoot.ts:196-212); per-session creds do not exist.
Activity frame log. Frames are appended on demand the first time appendActivityFrames runs.
Memory rows. Memories are explicit (memory.save), not auto-generated from session activity.

Create session ​

Explicit: session.create ​

Example ​

Implicit: first $prompt for a target ​

What's NOT created ​

See also ​

Create session

Explicit: `session.create`

Example

Implicit: first `$prompt` for a target

What's NOT created

See also