# Sessions and turns

How conversations map to sessions, turns, and provenance.

**Episodic memory** is the raw, ordered conversational record: sessions and turns as authored, including **anaphora** (pronouns and phrases like “he” or “that project” that refer back to something said earlier). Extracted identity, knowledge, context, instructions, and uncertainty records cite this layer through provenance (`source.ref`, `source.span`, `source.trust`). See [Memory categories](/docs/agent-memory/mental-model/memory-categories.md).

## What is a session?

A session is a conversation container with a stable id, scope paths, and metadata. Memory extracted from the conversation references the session for audit and transcript views.

```http
POST /api/v1/{context_id}/sessions
Authorization: Bearer <key>
Content-Type: application/json

{
  "scope": ["org/acme/user/alice", "agent/support"],
  "metadata": { "channel": "web" }
}
```

```bash
spectron sessions list
spectron sessions show <session_id>
```

## What is a turn?

A turn is one message with a **role**:

| Role | Description |
| --- | --- |
| `user` | Human participant |
| `assistant` | Model output |
| `system` | Injected system prompt |
| `tool` | Tool result |

Turns are ordered within a session. The episodic record is the source of truth for lexical attribution.

## Recommended ingest: `/facts/batch`

For new integrations, send the full message list in one call instead of appending turns one HTTP request at a time:

```http
POST /api/v1/{context_id}/facts/batch
Content-Type: application/json

{
  "session_id": "sess_01hw…",
  "messages": [
    { "role": "user", "content": "My name is Alice and I work at Acme Corp." },
    { "role": "assistant", "content": "Hello Alice! How can I help?" }
  ],
  "scope": ["org/acme/user/alice"]
}
```

Harness adapters (LangChain, Vercel AI, OpenAI Agents) use this path with platform-derived `Idempotency-Key` values. Default **`extract`** is **`whole_conversation`**; set **`per_message`** for one extraction pass per message.

## Extraction pipeline

Each ingest path runs the same reconciler:

1. Extract entities, attributes, and relations from new text
2. Reconcile against existing records (authority, temporal, calibration)
3. Persist with provenance
4. Return **`extractions`** (batch) or nested **`extraction`** (single fact), plus `sessionId` and `turnIds`

You do not call a separate “process” endpoint.

## Introspection

```http
GET /api/v1/{context_id}/sessions/{session_id}
GET /api/v1/{context_id}/sessions/{session_id}/turns
GET /api/v1/{context_id}/sessions/{session_id}/context
POST /api/v1/{context_id}/state
```

Session-scoped **state** and **diff** endpoints support debugging what changed across turns.

## CLI transcript tooling

```bash
spectron sessions list
spectron sessions show sess_01hw…
```

See [Creating sessions](/docs/agent-memory/sessions/creating-sessions.md) and [Adding turns](/docs/agent-memory/sessions/adding-turns.md) for operational detail aligned with the current API.