Sessions

Una session es una unidad lógica de trabajo para un user_id. Tiene started_at, opcional ended_at, opcional summary, y un status de active o completed. Las observations pertenecen a la sesión que las escribió por última vez (Braess #4).

Lifecycle

1. Abrir o reutilizar

mem_session_start(user_id) devuelve un SessionStartResponse. Si el usuario tiene una sesión activa no expirada, se reutiliza (is_new=False). Si no, se crea una nueva (is_new=True).

2. Guardar observations

Cada mem_save y mem_session_summary toca la sesión activa — su last_activity_at avanza. La ventana de timeout se resetea.

3. Cerrar (manual o auto)

Llamá mem_session_end(user_id, summary=...) para cerrar la sesión con un summary humano. Si te olvidás y se cumple el timeout, el próximo mem_session_start va a auto-cerrar la sesión vieja con un summary rudimentario marcado is_auto_generated=true y abrir una nueva.

Qué devuelve mem_session_start

from ilab_memory import ILabMemory

mem = ILabMemory.from_path("./mem.db")
resp = mem.mem_session_start(user_id="alice")

print(resp.session_id)        # uuid string
print(resp.is_new)             # True si recién creada, False si reutilizada
print(len(resp.sessions_context))  # summaries de sesiones pasadas (hasta 5)
print(len(resp.memories))      # ObservationCompacts recientes (hasta ~10)

La response es un SessionStartResponse frozen con cuatro campos:

Campo	Qué es	Para qué sirve
session_id	uuid string	Pasalo como header / anchor de contexto en tu app.
is_new	bool	Decile al agente si saluda o si continúa.
sessions_context	list[SessionSummaryCompact]	Summaries de sesiones recientes — mostrar o alimentar al LLM.
memories	list[ObservationCompact]	Observations recientes scored con ContextScore.

nota

memories[] están scored con ContextScore, no SearchScore. Los dos no son comparables — ver Scoring y Architecture / Braess #5.

Session reuse — sin sesiones espurias

El timeout default es 24 horas de inactividad. Mientras el usuario siga interactuando (o tu app siga llamando mem_session_start dentro de esa ventana), se reutiliza la misma sesión.

tip

Llamar mem_session_start es idempotente y barato — llamalo en cada evento "el usuario apareció" en tu app. No vas a tener sesiones duplicadas.

Auto-close por timeout

Cuando llamás mem_session_start y la última sesión del usuario estuvo inactiva más tiempo que session_timeout_hours, la librería:

1. Cierra la sesión vieja con un summary sintético tipo Memorias registradas: [type] title, [type] title, ... (armado a partir de las observations registradas en esa sesión).
2. Marca Session.is_auto_generated = True para que el código downstream pueda distinguir summaries auto vs humanos (Braess #2).
3. Abre una nueva sesión y la devuelve.

aviso

Distinguí summaries auto vs narrativos antes de mostrarlos al usuario. El summary auto es una lista de fragmentos, no una historia — existe para que la próxima sesión tenga algo desde donde hidratarse.

Creación implícita de sesión

Si llamás mem_save (o mem_session_summary) sin haber llamado mem_session_start antes, la librería crea una sesión activa implícita. Es a propósito — el modo embebido no debe castigar al caller por saltearse el handshake.

Dicho esto, llamar mem_session_start explícito es lo recomendado porque es la única forma de obtener sessions_context y memories para hidratar antes de responderle al usuario.

Cierre manual con mem_session_end

closed = mem.mem_session_end(
    user_id="alice",
    summary="Capturé el saludo preferido de Alice y confirmé que el agente usará 'Ali'.",
)

print(closed.id)
print(closed.ended_at)             # ISO 8601, UTC
print(closed.is_auto_generated)    # False — este es un summary humano

Si no hay sesión activa para user_id, mem_session_end levanta LookupError. Eso mapea a 404 en la capa HTTP.

Siguiente

• Observations — qué vive dentro de las sesiones.
• Privacy — qué pasa con los bloques <private> a lo largo del lifecycle.
• Architecture — Braess #2 (auto vs narrativo) y #4 (session_id de la última actualización) explicados.