Sessions and turns

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.

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.

POST /api/v1/{context_id}/sessions
API-KEY: <key>
Content-Type: application/json

{
  "scope": ["org=acme", "user=u_alice", "agent=support"],
  "metadata": { "channel": "web" }
}

spectron sessions create --scope org=acme --scope user=u_alice

What is a turn?

A turn is one message with a role:

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:

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=u_alice"]
}

Harness adapters (LangChain, Vercel AI, OpenAI Agents) use this path with platform-derived Idempotency-Key values.

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 a structured diff and trace_id

You do not call a separate “process” endpoint.

Introspection

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

spectron sessions list
spectron sessions show sess_01hw…

See Creating sessions and Adding turns for operational detail aligned with the current API.