Session Environment

The Session Environment manages work sessions across Claude Code conversations.

Environment Details

Key Concepts

Session IDs

Format: YYYYMMDD_HHMM_XXXX where XXXX is a random 4-char suffix. Example: 20251228_1847_pjcc

Stable Session IDs

Derived from suffix: s_ + suffix = s_pjcc

Session Hierarchy

Session (20251228_1847_pjcc)
├── Title: "Stable ID Migration Work"
├── Summary: "Migrated 4000+ keys..."
├── Subsessions (work blocks)
│   ├── sub_001: "Phase 1 - User Helper"
│   └── sub_002: "Phase 2 - Server Updates"
└── Items (linked work)
    ├── track:project:c3c50944
    ├── kb:node:37be7989
    └── file:session_helper.py

Session Helper Module

Location: /opt/mcp-servers/shared/session_helper.py

Key Functions

from session_helper import get_session_helper, link_item

# Get helper instance
helper = get_session_helper('u_z1p5')

# Start new session
result = helper.start_session()
# Returns: {session_id, stable_id, suffix, started, status}

# Link item to session
helper.link_item(
    item_type='kb',
    item_key='kb:u_z1p5:node:abc123',
    action='created',
    note='Session documentation'
)

# Get current session
current = helper.get_current_session()

# Migrate items between sessions (preserves chain)
helper.migrate_items_to_session(
    from_session_id='20251228_1847_pjcc',
    to_session_id='20260102_1900_xyz1'
)

Session Chaining

When items are migrated between sessions, they accumulate session IDs:

# After migration:
{
    'session_ids': ['s_pjcc', 's_xyz1', 's_abc2'],
    'origin_session': 's_pjcc',
    'migrated_at': '2026-01-02T19:00:00',
    'migrated_from': '20251228_1847_pjcc'
}

This enables: - Origin tracking: Where did this work start? - Work timeline: How many sessions touched this? - Completion context: When/where was it finished?

Auto-Agenda Updates

When items are linked, the session agenda updates automatically: - task_completed → agenda.completed - task created → agenda.in_progress - blocker → agenda.blockers - track created → agenda.track_projects - kb created → agenda.context_keys