Valkey — Chat session store

Chat sessions are persisted under the chat:session:* namespace. Each session holds the full ordered conversation history for one browser tab.

Relevant files: chat-agent/src/chat_agent/session.py, chat-agent/src/chat_agent/schemas/chat.py

Key schema

Key pattern	Type	TTL	Description
`chat:session:{session_id}`	String (JSON)	7 days	Full chat session (messages + metadata)

session_id is a UUID v4 string generated client-side and passed in the POST /chat/message request body. It is stored in st.session_state for the lifetime of the browser tab.

TTL is refreshed on every write. The key is deleted automatically when it expires — there is no explicit delete path.

For the user:{user_id}:sessions list that tracks which sessions belong to a user, see overview.md.

Data structure

Stores the full serialised ChatSession object.

{
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "messages": [
    {
      "role": "user",
      "content": "What pathways involve ATP?",
      "route": null,
      "confidence": null
    },
    {
      "role": "assistant",
      "content": "ATP is involved in ...",
      "route": "agent",
      "confidence": 0.92
    }
  ]
}

Field	Type	Description
`session_id`	string (UUID)	Session identifier
`messages`	array	Ordered conversation history
`messages[].role`	`"user"` \| `"assistant"`	Message author
`messages[].content`	string	Message text
`messages[].route`	`"lookup"` \| `"agent"` \| null	Intent route chosen by the router (assistant messages only)
`messages[].confidence`	float \| null	Router confidence score (assistant messages only)

Read / write pattern

POST /chat/message  {message, session_id?}
  │
  ├─ session_id present → GET chat:session:{session_id}
  │     not found → create empty ChatSession (new session_id generated)
  │
  ├─ append user message
  └─ SETEX chat:session:{session_id}  604800  <json>   ← job enqueued, returns 202

Background worker:
  ├─ GET chat:session:{session_id}
  ├─ run intent router + handler (emitting events to session along the way)
  ├─ append assistant message
  └─ SETEX chat:session:{session_id}  604800  <json>

Sessions are never explicitly deleted — they expire after 7 days of inactivity.