What Events Are Captured in Context-Mode Sessions and How Are They Prioritized?

Context-mode captures structured session events from Claude Code hooks, assigns each a priority level from 1 (critical) to 5 (lowest) based on category, and uses these priorities to guide context compaction when building resumable XML snapshots.

The mksglu/context-mode repository implements a session recording system that tracks every interaction during a Claude Code session. Understanding what events are captured during a session and how they are prioritized in the context-mode snapshot is essential for optimizing context windows and ensuring critical information survives compaction.

Event Categories and Capture Mechanism

Events are extracted by pure functions in src/session/extract.ts and grouped by category in src/session/snapshot.ts. Each event type receives a specific priority value where lower numbers indicate higher importance.

File Operations and Rules (Priority 1)

File system interactions and rule applications receive the highest priority (1) because they represent direct modifications to the workspace. According to the source code in extractFileAndRule (lines 71-100), the following events are captured:

• file_read, file_write, file_edit — Priority 1
• rule, rule_content — Priority 1 (critical, must survive compaction)

File glob and search operations receive lower priority (3) and are handled separately in extractFileAndRule (lines 141-148 for glob, lines 151-160 for grep).

Working Directory and Environment (Priority 2)

Contextual state changes that affect execution but don't modify files directly receive priority 2:

• cwd — Emitted by extractCwd (lines 71-85)
• env (setup commands) — Emitted by extractEnv (lines 77-92)
• worktree (EnterWorktree) — Emitted by extractWorktree (lines 88-96)
• git operations — Emitted by extractGit (lines 39-51)

Error events (error_tool) also receive priority 2 via extractError (lines 93-110).

Planning and Task Management (Priority 1-2)

Core workflow events use a mixed priority scheme:

• task_create, task_update, task — Priority 1 (core work items), emitted by extractTask (lines 58-73)
• plan_enter, plan_exit, plan_file_write — Priority 2
• plan_approved — Priority 1 (critical milestone)

These plan events are extracted by extractPlan (lines 86-133, 135-146).

Subagents and Decisions (Priority 2-3)

Agent delegation and user decision points:

• subagent_completed — Priority 2 (kept), emitted by extractSubagent (lines 24-31)
• subagent_launched — Priority 3 (may be trimmed), emitted by extractSubagent (lines 24-30)
• decision_question (AskUserQuestion) — Priority 2, emitted by extractDecision (lines 62-80)
• decision (user-message patterns) — Priority 2, emitted by extractUserDecision (lines 14-22)

Low-Priority Context (Priority 3-5)

Peripheral information that can be sacrificed first during compaction:

• role (persona directives) — Priority 3, emitted by extractRole (lines 38-46)
• skill (Skill tool) — Priority 3, emitted by extractSkill (lines 2-8)
• mcp (any mcp__* tool) — Priority 3, emitted by extractMcp (lines 38-55)
• intent (session mode) — Priority 4, emitted by extractIntent (lines 62-70)
• data (large pasted payload > 1 KB) — Priority 5 (lowest), emitted by extractData (lines 78-84)

How Event Prioritization Works

The priority system is implemented across three core files: extract.ts, snapshot.ts, and db.ts.

Priority Assignment: In src/session/extract.ts, each extractor function assigns a priority value when creating SessionEvent objects. For example, file edits receive priority 1 while data payloads receive priority 5.

Snapshot Building: In src/session/snapshot.ts (lines 998-1025), events are grouped by category and rendered into XML. The buildResumeSnapshot function (lines 981-1004) includes the priority field in each event's representation but does not filter events based on these values.

Compaction Strategy: The priority field exists specifically for downstream consumers. When the LLM's context compaction step needs to trim the snapshot to fit a token budget, it uses the priority values to determine which events to preserve (lower numbers) and which to remove (higher numbers).

Accessing Event Data in Practice

Extracting Events from Hook Payloads

To capture events from a raw hook input, import the extractor functions from src/session/extract.ts:

import { extractFileAndRule, extractCwd, extractError, extractTask, extractPlan } from "./session/extract";
import type { SessionEvent } from "./types";

function extractAll(input: HookInput): SessionEvent[] {
  const events: SessionEvent[] = [];
  
  // Critical file and rule events (priority 1)
  events.push(...extractFileAndRule(input));
  
  // Environment context (priority 2)
  events.push(...extractCwd(input));
  events.push(...extractEnv(input));
  
  // Workflow tracking (priority 1-2)
  events.push(...extractTask(input));
  events.push(...extractPlan(input));
  
  // Error handling (priority 2)
  events.push(...extractError(input));
  
  // Additional extractors follow the same pattern...
  return events;
}

Building a Resumable Snapshot

Convert stored events into an XML snapshot using the builder from src/session/snapshot.ts:

import { buildResumeSnapshot } from "./session/snapshot";
import type { StoredEvent } from "./session/db";

// Load events from the SQLite session database
const storedEvents: StoredEvent[] = await db.getSessionEvents(sessionId);

const snapshotXml = buildResumeSnapshot(storedEvents, {
  compactCount: 1,
  searchTool: "ctx_search",
});

// snapshotXml contains prioritized event data for the LLM context window
console.log(snapshotXml);

Querying Event Priorities in the Database

Inspect the priority assignments directly via SQL. The priority column is defined in src/session/db.ts (line 70):

SELECT 
  type, 
  category, 
  priority, 
  data 
FROM session_events 
WHERE session_id = ? 
ORDER BY priority ASC, id ASC;

This query returns events sorted by priority, showing critical priority 1 events (file operations, tasks) before lower priority context (intents, data payloads).

Summary

• Event capture occurs in src/session/extract.ts through specialized functions like extractFileAndRule, extractTask, and extractPlan.
• Priority levels range from 1 (critical file edits, rules, approved plans) to 5 (large data payloads), with intermediate levels for environment state and decisions.
• Snapshot construction in src/session/snapshot.ts preserves all events but includes priority metadata to guide downstream compaction when token limits are reached.
• Storage happens in SQLite with the schema defined in src/session/db.ts, allowing SQL-based inspection of event priorities.

Frequently Asked Questions

What priority level is assigned to file operations?

File reads, writes, and edits receive priority 1 (the highest level), while file glob and search operations receive priority 3. This distinction ensures that actual file modifications survive context compaction, while expensive search operations may be trimmed if needed.

How does context-mode use priority values when building snapshots?

The snapshot builder in src/session/snapshot.ts does not drop events based on priority during initial construction. Instead, it embeds the priority field into the XML representation so that downstream context compaction algorithms can use these values to intelligently trim the snapshot when fitting it within token budgets.

Where are session events stored and how can I query them?

Events persist in a SQLite database with the schema defined in src/session/db.ts. The session_events table includes columns for type, category, priority, and data, allowing you to query specific event types or filter by priority level using standard SQL.

What is the difference between event extraction and snapshot building?

Extraction happens in src/session/extract.ts and transforms raw Claude Code hook payloads into typed SessionEvent objects with assigned priorities. Snapshot building happens in src/session/snapshot.ts and groups these events by category to create a resumable XML representation that preserves the priority metadata for later compaction decisions.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}