rai session
Gestiona sesiones de trabajo. Las sesiones realizan el seguimiento de la actividad del desarrollador, habilitan la carga de contexto para agentes de IA y capturan decisiones incrementales mediante el diario.
rai session start¶
Inicia una nueva sesión de trabajo. Incrementa el contador de sesiones y establece el estado de sesión activa. Verifica si existen sesiones huérfanas y advierte si se encuentran.
Con --context, genera un paquete compacto de contexto desde el perfil del
desarrollador, el estado de sesión, el registro de misiones/worktrees, pistas de
backlog y el knowledge graph. El paquete está pensado para consumo del agente de
IA al inicio del trabajo.
| Flag | Corta | Descripción |
|---|---|---|
--name |
-n |
Tu nombre (requerido para la configuración inicial) |
--project |
-p |
Ruta del proyecto a asociar con esta sesión |
--agent |
Tipo de agente (ej. claude-code, cursor). Por defecto: unknown |
|
--context |
Genera un paquete de contexto para consumo del agente de IA |
# Configuración inicial
rai session start --name "Alice" --project .
# Iniciar sesión con paquete de contexto
rai session start --project . --context
# Inicio simple
rai session start
Semántica del paquete de contexto¶
Cuando hay una misión o un worktree registrado activo, rai session start
--context mantiene estas señales separadas:
| Señal | Significado |
|---|---|
| Continuidad | Qué sesión previa aportó la narrativa o el contexto pendiente |
| Misión | El contenedor de trabajo activo/vinculado a la sesión |
| Worktree | El checkout registrado, rama, merge target y stories vinculadas |
| Trabajo actual | La story/épica/rama inferida como trabajo en curso |
La misión no es automáticamente el donor de continuidad. Un donor local del
worktree gana primero cuando existe; si no, el historial local de la misión puede
aportar continuidad. Cuando existe una misión activa, los fallbacks globales del
desarrollador no pueden cruzar ese límite de misión. Si no hay donor válido en
ese scope, la continuidad queda en none. La sección # Provenance muestra la
fuente seleccionada para que el desarrollador pueda verificar el contexto de
inicio en vez de confiar en heurísticas ocultas.
rai session close¶
Finaliza la sesión de trabajo actual. Con --summary o --state-file, realiza un cierre estructurado completo — registra la sesión, patrones, correcciones y actualiza el estado. Todas las escrituras son atómicas.
| Flag | Corta | Descripción |
|---|---|---|
--summary |
-s |
Resumen de la sesión |
--type |
-t |
Tipo de sesión (feature, research, maintenance, etc.) |
--pattern |
Descripción de pattern a registrar | |
--correction |
Corrección de coaching observada | |
--correction-lesson |
Lección aprendida de la corrección | |
--state-file |
Archivo YAML con la salida completa estructurada de la sesión | |
--session |
ID de sesión a cerrar (ej. SES-177). Recae en la variable de entorno RAI_SESSION_ID |
|
--project |
-p |
Ruta del proyecto |
# Cierre simple
rai session close
# Cierre con resumen
rai session close --summary "Implemented auth module" --type feature
# Cierre con pattern aprendido
rai session close --summary "Refactored tests" --type maintenance \
--pattern "Use fixtures for database setup"
rai session context¶
Carga secciones de priming de contexto relevantes para la tarea. Úsalo después de rai session start --context para cargar priming detallado para un tipo de trabajo específico.
Secciones disponibles: governance, behavioral, coaching, deadlines, progress.
| Flag | Corta | Descripción |
|---|---|---|
--sections |
-s |
Nombres de secciones separados por comas a cargar (requerido) |
--project |
-p |
Ruta del proyecto (requerido) |
# Trabajo de funcionalidad: patrones de gobernanza + comportamiento
rai session context -s governance,behavioral -p .
# Cerca de una fecha límite: verificar urgencia
rai session context -s deadlines,progress -p .
rai session journal add¶
Añade una entrada al diario de la sesión actual. Las entradas capturan decisiones, insights y tareas completadas de forma incremental.
| Argumento | Descripción |
|---|---|
CONTENT |
Contenido a persistir (requerido) |
| Flag | Corta | Descripción |
|---|---|---|
--type |
-t |
Tipo de entrada: decision, insight, task_done, note. Por defecto: note |
--tags |
Etiquetas separadas por comas (ej. arch,spike) |
|
--project |
-p |
Ruta del proyecto |
# Registrar una decisión
rai session journal add "Use JSONL for journal" --type decision
# Registrar tarea completada
rai session journal add "T1 complete" --type task_done
# Registrar un insight con etiquetas
rai session journal add "Compaction loses rationale" --type insight --tags "compaction,memory"
rai session journal show¶
Muestra las entradas del diario de la sesión actual.
| Flag | Corta | Descripción |
|---|---|---|
--last |
-n |
Muestra solo las últimas N entradas |
--compact |
Salida en formato compacto para inyección de contexto | |
--project |
-p |
Ruta del proyecto |
# Mostrar todas las entradas
rai session journal show
# Mostrar las últimas 5 entradas
rai session journal show --last 5
# Formato compacto para restauración post-compactación
rai session journal show --compact
Identidad de Sesión (v2.3.0)¶
A partir de v2.3.0, las sesiones usan un formato de ID determinístico basado en timestamp vinculado al desarrollador que las inició.
Formato del ID de Sesión¶
Por ejemplo, una sesión iniciada por el desarrollador E el 23 de marzo de 2026 a las 11:00 produce S-E-260323-1100. El formato tiene 16 caracteres, no requiere coordinación entre desarrolladores y es único por desarrollador con granularidad de minuto. La colisión en el mismo minuto se previene mediante la verificación de sesión activa — no se puede iniciar una nueva sesión mientras haya una activa.
Registro de Prefijos de Desarrollador¶
Cada desarrollador tiene un prefijo corto (típicamente su primera inicial) registrado en .raise/rai/prefixes.yaml:
E: {name: "Emilio Osorio", registered: "2026-03-22"}
J: {name: "Juan Pérez", registered: "2026-03-25"}
Los prefijos se registran automáticamente en el primer rai session start. Si dos desarrolladores comparten la misma inicial, la detección de colisiones sugiere un prefijo extendido (ej. E está tomado por Emilio, así que Elena obtiene EG). Este archivo se confirma en git para que todo el equipo pueda ver los prefijos registrados.
Almacenamiento de Sesión por Proyecto¶
Los datos de sesión se almacenan por proyecto en .raise/rai/personal/ (en gitignore):
| Ruta | Propósito |
|---|---|
.raise/rai/personal/active-session |
Puntero a la sesión actual (JSON) |
.raise/rai/personal/sessions/{prefix}/index.jsonl |
Registro de sesiones por desarrollador |
.raise/rai/personal/sessions/{session-id}/ |
Estado de trabajo por sesión |
Solo .raise/rai/prefixes.yaml se confirma en git. Todos los datos de sesión permanecen locales por defecto. Los equipos pueden optar por compartir los índices de sesión modificando .gitignore.
El puntero de sesión activa lleva los metadatos (ID, nombre, timestamp de inicio) desde el inicio hasta el cierre, por lo que el comando de cierre no necesita reconstruir el estado.
:::caution[Cambio incompatible — Ruta de Datos de Sesión]
El almacenamiento de datos de sesión se movió del ~/.rai/developer.yaml global al .raise/rai/personal/ por proyecto. No existe migración automática.
Antes (v2.2.x): El estado de sesión se almacenaba globalmente en ~/.rai/developer.yaml. Los IDs de sesión usaban el formato SES-NNN con un contador por proyecto.
Después (v2.3.0): El estado de sesión se almacena por proyecto en .raise/rai/personal/. Los IDs de sesión usan el formato S-{prefix}-{YYMMDD}-{HHMM}.
Las sesiones antiguas SES-NNN siguen siendo legibles, pero las nuevas sesiones usan exclusivamente el nuevo formato. Para conservar los datos de sesión anteriores, mantén tu ~/.rai/developer.yaml existente — no se modifica ni elimina.
:::
Ver también: rai session start, rai signal emit-session