# Session Management Implementation Guide

## Overview

The Codex MCP Server provides advanced session management with native Codex CLI v0.50.0+ integration, enabling persistent conversational context and sophisticated AI coding assistance.

Sessions are created on first use when a sessionId is provided. If no sessionId is supplied, this request does not create a session (so it won't appear in listSessions).

## Architecture

### Session Storage

* **In-memory Map-based storage** with automatic cleanup
* **UUID-based session IDs** for unique identification
* **TTL management** - 24 hour automatic session expiration
* **Session limit enforcement** - maximum 100 concurrent sessions

### Enhanced Session Data Structure

```typescript
interface SessionData {
  id: string;
  createdAt: Date;
  lastAccessedAt: Date;
  turns: ConversationTurn[];
  codexConversationId?: string; // Native Codex conversation ID
}

interface ConversationTurn {
  prompt: string;
  response: string;
  timestamp: Date;
}
```

### Native Codex Integration

* **Automatic conversation ID extraction** from Codex CLI output (supports both "session id" and "conversation id" formats)
* **Resume functionality** using `codex exec resume <conversation-id>`
* **Fallback context building** when native resume unavailable
* **Model consistency** across session interactions

### Tool Enhancements

#### Enhanced Codex Tool

* **sessionId** (optional): Session ID for conversational context
* **resetSession** (optional): Reset session history before processing
* **model** (optional): Model selection (defaults to `gpt-5.2-codex`)
* **reasoningEffort** (optional): Control reasoning depth (low/medium/high)
* **Smart context building**: Uses native resume or fallback context
* **Robust error handling**: Graceful degradation for various failure modes

#### ListSessions Tool

* **Session enumeration**: Returns all active session IDs with comprehensive metadata
* **Session introspection**: Creation time, last access, turn count, conversation ID
* **Management interface**: Enables session lifecycle monitoring

## Implementation Status ✅

### ✅ Completed Features

1. **Session Storage System**
   * InMemorySessionStorage with TTL and cleanup
   * Defensive programming against data corruption
   * Conversation ID tracking and management
2. **Enhanced Codex Tool Handler**
   * Native resume functionality with fallback
   * GPT-5.2-Codex as intelligent default model
   * Model and reasoning effort parameter support
   * Comprehensive error handling and validation
3. **ListSessions Tool**
   * Complete session metadata exposure
   * JSON-formatted session information
   * Real-time session status tracking
4. **Robust Testing Suite**
   * 54 comprehensive tests covering all functionality
   * Edge case handling and error scenario validation
   * Integration testing with Codex CLI interactions

## Advanced Benefits

* **Native Codex Resume**: Optimal conversation continuity using Codex CLI's built-in resume feature
* **Intelligent Defaults**: GPT-5.2-Codex model selection for superior agentic coding assistance
* **Production-Ready**: Comprehensive error handling, data validation, and graceful degradation
* **Enterprise-Scale**: Session management suitable for professional development workflows
* **Flexible Configuration**: Per-request model and reasoning effort customization

## Usage Patterns

### Basic Session Usage

```bash
# Explicit session management (creates the session on first use)
codex --sessionId "auth-review" "Continue analysis"
codex --sessionId "auth-review" --resetSession true "Start fresh review"
```

### Advanced Configuration

```bash
# Model and reasoning control
codex --model "gpt-4" --reasoningEffort "high" "Complex architectural analysis"

# Session with custom parameters
codex --sessionId "deep-dive" --model "gpt-4" --reasoningEffort "high" "Advanced optimization review"

# Session management
listSessions  # View all active sessions
```

## Technical Architecture

### Command Flow

{% @mermaid/diagram content="graph TD
A\[User Request] --> B{Session ID provided?}
B -->|Yes| C\[Ensure Session Exists]
C --> D{Reset Session?}
B -->|No| M\[Execute with Default Model]
D -->|Yes| E\[Clear Session History]
D -->|No| F{Codex Conversation ID exists?}
E --> G\[Execute with Default Model]
F -->|Yes| H\[Use Codex Resume]
F -->|No| I\[Build Enhanced Context]
H --> J\[Execute with Parameters]
I --> J
G --> K\[Extract Conversation ID]
J --> L\[Save Turn to Session]
K --> L
M --> N\[Return Response]
L --> N" %}

### Error Handling Strategy

* **Graceful Degradation**: System continues operation even with corrupted session data
* **Defensive Programming**: Validates array structures and handles null/undefined gracefully
* **Comprehensive Logging**: Error context preserved for debugging and monitoring
* **Fallback Mechanisms**: Manual context building when native resume fails

### Performance Considerations

* **Memory Management**: In-memory, per-process sessions with automatic cleanup of expired sessions (24hr TTL)
* **Session Limits**: Maximum 100 concurrent sessions to prevent memory exhaustion
* **Context Optimization**: Only recent turns (last 2) used for manual context building
* **Efficient Storage**: Minimal session metadata for optimal memory usage


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.tuannvm.com/docs/session-management.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.