Chapter 12 System Design

Context Window Management

Keeping conversations alive beyond the token limit

src/services/compact/compact.tsLines 170
1
import { feature } from 'bun:bundle'
2
import type { UUID } from 'crypto'
3
import uniqBy from 'lodash-es/uniqBy.js'
4
 
5
/* eslint-disable @typescript-eslint/no-require-imports */
6
const sessionTranscriptModule = feature('KAIROS')
7
  ? (require('../sessionTranscript/sessionTranscript.js') as typeof import('../sessionTranscript/sessionTranscript.js'))
8
  : null
9
 
10
import { APIUserAbortError } from '@anthropic-ai/sdk'
11
import { markPostCompaction } from 'src/bootstrap/state.js'
12
import { getInvokedSkillsForAgent } from '../../bootstrap/state.js'
13
import type { QuerySource } from '../../constants/querySource.js'
14
import type { CanUseToolFn } from '../../hooks/useCanUseTool.js'
15
import type { Tool, ToolUseContext } from '../../Tool.js'
16
import type { LocalAgentTaskState } from '../../tasks/LocalAgentTask/LocalAgentTask.js'
17
import { FileReadTool } from '../../tools/FileReadTool/FileReadTool.js'
18
import {
19
  FILE_READ_TOOL_NAME,
20
  FILE_UNCHANGED_STUB,
21
} from '../../tools/FileReadTool/prompt.js'
22
import { ToolSearchTool } from '../../tools/ToolSearchTool/ToolSearchTool.js'
23
import type { AgentId } from '../../types/ids.js'
24
import type {
25
  AssistantMessage,
26
  AttachmentMessage,
27
  HookResultMessage,
28
  Message,
29
  PartialCompactDirection,
30
  SystemCompactBoundaryMessage,
31
  SystemMessage,
32
  UserMessage,
33
} from '../../types/message.js'
34
import {
35
  createAttachmentMessage,
36
  generateFileAttachment,
37
  getAgentListingDeltaAttachment,
38
  getDeferredToolsDeltaAttachment,
39
  getMcpInstructionsDeltaAttachment,
40
} from '../../utils/attachments.js'
41
import { getMemoryPath } from '../../utils/config.js'
42
import { COMPACT_MAX_OUTPUT_TOKENS } from '../../utils/context.js'
43
import {
44
  analyzeContext,
45
  tokenStatsToStatsigMetrics,
46
} from '../../utils/contextAnalysis.js'
47
import { logForDebugging } from '../../utils/debug.js'
48
import { hasExactErrorMessage } from '../../utils/errors.js'
49
import { cacheToObject } from '../../utils/fileStateCache.js'
50
import {
51
  type CacheSafeParams,
52
  runForkedAgent,
53
} from '../../utils/forkedAgent.js'
54
import {
55
  executePostCompactHooks,
56
  executePreCompactHooks,
57
} from '../../utils/hooks.js'
58
import { logError } from '../../utils/log.js'
59
import { MEMORY_TYPE_VALUES } from '../../utils/memory/types.js'
60
import {
61
  createCompactBoundaryMessage,
62
  createUserMessage,
63
  getAssistantMessageText,
64
  getLastAssistantMessage,
65
  getMessagesAfterCompactBoundary,
66
  isCompactBoundaryMessage,
67
  normalizeMessagesForAPI,
68
} from '../../utils/messages.js'
69
import { expandPath } from '../../utils/path.js'
70
import { getPlan, getPlanFilePath } from '../../utils/plans.js'
Annotations (click the dots)

Long conversations eventually fill the context window. src/services/compact/compact.ts handles this by calling Claude itself to summarize the conversation — replacing the full history with a dense summary that preserves key decisions and results.

🔑Key Insight

The compaction prompt is a meta-call to Claude: Claude summarizes what Claude has done so far. The prompt is tuned to preserve tool results and decision rationale — the most important parts for continuing a task.

Auto-compact (src/services/compact/autoCompact.ts) monitors token usage after each turn. When it crosses the threshold (~80%), it schedules a compact before the next user message. The user sees a brief notification but doesn't lose context.

💡Tip

MicroCompact is a lighter version that summarizes just the most recent tool calls rather than the entire history. It's used when the context is getting full but a full compact would be too disruptive to the current task.

KEY TAKEAWAYS
  • Auto-compact triggers when the context window reaches ~80% capacity
  • Compaction calls Claude to summarize the conversation, replacing history with the summary
  • MicroCompact is a lighter-weight version for less aggressive summarization
  • Pre/post compact hooks fire — allowing users to save the full history before compaction
  • The compact prompt is carefully tuned to preserve tool results and decision rationale
AI Assistant

Ask anything about Context Window Management

Powered by Groq · Enter to send, Shift+Enter for newline

12/12Prev