paolomoz/session-context

Session Context

Quick Reference

| Category | Trigger | Complexity | Source | |----------|---------|------------|--------| | patterns | "session tracking", "conversation context", "multi-turn sessions", "user journey tracking" | Medium | 4 projects |

Manage user session context across multi-turn interactions by combining client-side sessionStorage for immediate state and server-side KV storage for persistence and cross-page sharing. Enables journey-stage tracking, query history, and context propagation without traditional databases.

When to Use

• Building a conversational interface that needs to remember previous queries within a session
• Implementing journey stage tracking (exploring, comparing, deciding, supporting)
• Passing context between pages without a backend session store
• Creating recommendation engines that improve with each interaction

Instructions

Step 1: Client-Side SessionContextManager

Create a class wrapping sessionStorage with structured context management:

class SessionContextManager {
  static STORAGE_KEY = 'session-context'
  static MAX_QUERIES = 10

  static getContext() {
    const stored = sessionStorage.getItem(this.STORAGE_KEY)
    return stored ? JSON.parse(stored) : {
      queries: [], sessionStart: Date.now(),
      lastUpdated: Date.now(), sessionId: crypto.randomUUID()
    }
  }

  static addQuery(entry) {
    const context = this.getContext()
    context.queries.push({ ...entry, timestamp: Date.now() })
    if (context.queries.length > this.MAX_QUERIES) {
      context.queries = context.queries.slice(-this.MAX_QUERIES)
    }
    context.lastUpdated = Date.now()
    sessionStorage.setItem(this.STORAGE_KEY, JSON.stringify(context))
    return context
  }
}

Key rules:

• Cap query history with MAX_QUERIES (default 10). SessionStorage has a 5MB limit and unbounded growth silently fails.
• Use crypto.randomUUID() for session IDs, never sequential counters.
• Always update lastUpdated on every write for staleness checks.

Step 2: Query History Entry Structure

Each entry in the queries array:

{
  query: "What's the best laptop for video editing?",
  intent: "product_comparison",
  timestamp: 1709123456789,
  entities: ["laptop", "video editing"],
  journeyStage: "comparing",
  recommendedProducts: ["macbook-pro-m3", "dell-xps"],
  confidence: 0.87,
  nextBestAction: "show_comparison_table"
}

At minimum include query, timestamp, and journeyStage. The remaining fields are populated by your classification pipeline and consumed by recommendation logic.

Step 3: Journey Stage Tracking

Stages form a linear progression:

exploring → comparing → deciding → supporting

| Stage | User Behavior | System Behavior | |-------|--------------|-----------------| | exploring | Broad questions, browsing | Show categories, discovery content | | comparing | Feature questions, "vs" queries | Comparison tables, differentiators | | deciding | Price, availability, "should I" | CTAs, pricing, reviews, social proof | | supporting | How-to, troubleshooting | Documentation, tutorials, support |

Simple heuristic classification:

function classifyJourneyStage(query, previousStage) {
  if (/\bhow to|setup|install|fix|error|help\b/i.test(query)) return 'supporting'
  if (/\bprice|cost|buy|order|worth|should i\b/i.test(query)) return 'deciding'
  if (/\bvs\b|compare|difference|better|which/i.test(query)) return 'comparing'
  return previousStage || 'exploring'
}

Stages should only advance forward or stay. Never regress within a single session unless the user explicitly starts a new topic.

Step 4: Server-Side KV Storage

Use KV (Cloudflare KV, Redis, DynamoDB) for context that must survive across page navigations.

Key format: ctx_{shortId} where short IDs are generated as:

const contextId = 'ctx_' + crypto.randomUUID().replace(/-/g, '').slice(0, 12)

Store with TTL (1 hour):

await kv.put(contextId, JSON.stringify(context), { expirationTtl: 3600 })

Retrieve:

const stored = await kv.get(contextId, { type: 'json' })
if (!stored) return null  // Expired or missing

TTL rules:

• Default: 3600s (1 hour), covering a typical browsing session.
• Never exceed 24 hours -- session context is ephemeral. Use a database for persistent user data.
• Always handle null returns: entries may expire between URL generation and click.

Step 5: Context Propagation Between Pages

Method A -- Inline (context under 2KB):

// Build URL with encoded context
const encoded = btoa(JSON.stringify(context))
const url = `${baseUrl}?ctx=${encodeURIComponent(encoded)}`

// Read on receiving page
const ctx = JSON.parse(atob(decodeURIComponent(params.get('ctx'))))

Method B -- Context ID (context over 2KB):

// Store in KV, pass ID in URL
const contextId = await storeContext(kv, context)
const url = `${baseUrl}?ctx=${contextId}`

// Read on receiving page: detect by prefix
const ctx = params.get('ctx')
if (ctx.startsWith('ctx_')) {
  return await kv.get(ctx, { type: 'json' })
}

The ctx_ prefix acts as a discriminator so the receiving page auto-detects which method was used.

Step 6: Page Load Initialization

Establish context from all sources with priority ordering:

async function initializeContext(kv) {
  // 1. URL-propagated context (highest priority)
  const urlContext = await readContextFromUrl(window.location.href, kv)
  if (urlContext) {
    SessionContextManager.saveContext(urlContext)
    window.history.replaceState({}, '', window.location.pathname)
    return urlContext
  }
  // 2. Existing sessionStorage context
  const existing = SessionContextManager.getContext()
  if (existing.queries.length > 0) return existing
  // 3. Fresh context
  return SessionContextManager.getContext()
}

On each interaction, update both tiers -- client synchronously, server asynchronously:

async function recordInteraction(kv, entry) {
  const context = SessionContextManager.addQuery(entry)  // sync
  storeContext(kv, context).catch(console.warn)           // async, non-blocking
  return context
}

Always treat KV sync as non-blocking. The client store is the source of truth; KV is the durability layer.

Troubleshooting

| Problem | Cause | Fix | |---------|-------|-----| | setItem silently fails | Storage quota exceeded (5MB) | Reduce MAX_QUERIES or strip large fields before storing | | Context lost on navigation | Different origin or wrong storage type | Verify same origin; use KV + URL for cross-origin | | KV returns null for valid ID | TTL expired | Handle null gracefully; re-initialize from sessionStorage | | Context URL truncated | Inline method with large context | Switch to Context ID method (Method B) for contexts over 2KB | | Journey stage regresses | Classifier ignores previous stage | Always pass previousStage and only advance forward |

Cross-References

• cloudflare-fullstack -- KV binding setup and Cloudflare Workers integration
• multi-model-orchestrator -- Intent classification and entity extraction for query entries
• generative-page-pipeline -- Consuming session context to personalize generated pages