CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

session-context

Track user session context across multi-turn interactions using browser sessionStorage and server-side KV caching with TTL. Use when implementing "session tracking", "conversation context", "multi-turn sessions", or "user journey tracking".

Quality

81%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Passed

No findings from the security scan

SKILL.md
Quality
Evals
Security

Session Context

Quick Reference

CategoryTriggerComplexitySource
patterns"session tracking", "conversation context", "multi-turn sessions", "user journey tracking"Medium4 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
StageUser BehaviorSystem Behavior
exploringBroad questions, browsingShow categories, discovery content
comparingFeature questions, "vs" queriesComparison tables, differentiators
decidingPrice, availability, "should I"CTAs, pricing, reviews, social proof
supportingHow-to, troubleshootingDocumentation, 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

ProblemCauseFix
setItem silently failsStorage quota exceeded (5MB)Reduce MAX_QUERIES or strip large fields before storing
Context lost on navigationDifferent origin or wrong storage typeVerify same origin; use KV + URL for cross-origin
KV returns null for valid IDTTL expiredHandle null gracefully; re-initialize from sessionStorage
Context URL truncatedInline method with large contextSwitch to Context ID method (Method B) for contexts over 2KB
Journey stage regressesClassifier ignores previous stageAlways 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
Repository

paolomoz/skills

Path

skills/session-context/SKILL.md

Last updated
First committed

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.