Sessions and Memory

Liya Engine maintains conversational context through sessions. Each session is a persistent conversation thread tied to a user_id and a domain. The engine uses session history to deliver more relevant, contextual responses.

How sessions work

1. On your first call, omit session_id — the engine creates a new session and returns its ID.
2. On follow-up calls, pass the same session_id to continue the conversation.
3. Sessions expire after a period of inactivity (default: 30 days — configurable via Data Retention).

# First call — no session_id
POST /v1/hiring/resume_analysis
{
  "input": { "resume": { ... }, "user_id": "user_001" }
}
 
# Returns:
{ "sessionId": "sess_01HZ...", ... }
 
# Follow-up — pass session_id
POST /v1/hiring/skill_gap_analysis
{
  "input": { "resume": { ... }, "job_description": { ... }, "user_id": "user_001" },
  "options": { "session_id": "sess_01HZ..." }
}

What the engine remembers

Within a session, the engine retains:

• All prior messages (user inputs + assistant responses)
• Intent results from earlier in the session
• User context fields like user_id and preferences

This means if you've already run resume_analysis, a subsequent career_path_planning call in the same session will reference the analysis without you resending the resume.

Session scope

Sessions are scoped to a single domain. Mixing intents from different domains in the same session is not supported — create a new session when switching domains.

Sessions are also scoped by tenant_id — no session data is shared between tenants.

Starting a fresh session

To force a new context, omit session_id on your next call:

{
  "input": { "resume": { ... }, "user_id": "user_001" }
}

The old session remains accessible via GET /dashboard/sessions/:sessionId until it expires.

Agentic sessions

When agenticConfig.mode is "auto" or "always", the engine can autonomously chain multiple intents within a session to complete a complex goal. In this mode:

• The engine may call several intents internally before responding
• Token usage reflects all internal steps
• The session messageCount increments for each internal step

See Feature Configuration to configure agentic behaviour.

Memory and data retention

Set any retention field to null to disable automatic purging.

Opt-out per request

Individual requests can opt out of storage entirely using the consent block:

{
  "input": { ... },
  "consent": {
    "allow_data_storage": false,
    "allow_session_memory": false
  }
}

When allow_data_storage: false, the request is processed but no messages or session data are stored. The session ID returned will be ephemeral.

See Data Retention for the full consent schema.

Inspecting sessions

Use the Dashboard API to review session history:

# List recent sessions
GET /dashboard/sessions?domain=hiring&limit=10
 
# Inspect a specific session
GET /dashboard/sessions/sess_01HZ...

See Sessions API.