Lesson 2

Context Management

What This Lesson Is About

Every time you send a message, Kiro assembles a context window - the complete set of information the model can see when generating a response. Understanding what goes in, in what order, and what happens when space runs out is the difference between Kiro working with full awareness vs. working half-blind.

What Goes Into the Context Window

Here's everything that can end up in the context, roughly in the order Kiro assembles it:

Not everything here is present every time. Only items 1, 2 (if they exist), 6, and 7 are guaranteed. Everything else depends on what's active, what you've referenced, and what the agent has done.

Context Keys: The # Menu

When you type # in the chat input, you get a menu of things you can explicitly pull into context. These are the built-in context keys:

These are additive - each one you select injects more content into the context for that message. Choose deliberately; each one uses tokens.

The Token Budget

The context window has a fixed size (determined by the model - up to 1M tokens for the latest Claude models, though some models still use 200K). Everything listed above competes for space in that window. This is why always-on steering should be concise: it takes up space on every single message, leaving less room for the actual work.

Here's a rough sense of the cost:

You don't need to count tokens manually. The point is: context is a finite resource, and everything in the diagram above shares it.

What Happens When Space Runs Out: Compaction

As a conversation gets long, the accumulated history eventually approaches the context window limit. When this happens, Kiro performs compaction - it summarises older parts of the conversation into a condensed form, freeing up space for new content.

What gets compacted:

• Older conversation turns - early messages and their responses get summarised
• Tool results from earlier turns - the full file contents Kiro read earlier get condensed into summaries of what was learned

What is never compacted:

• Steering files - they're re-injected fresh every message, never summarised
• Your current message - always present in full
• The system prompt - always present in full

The Active Editor File

Kiro automatically includes your currently active editor tab as context. You've seen this in our sessions - the <ACTIVE-EDITOR-FILE> section that appears in the environment context.

This is significant because:

• It triggers fileMatch steering without you explicitly referencing anything
• It gives Kiro awareness of what you're looking at, even if you don't mention it
• Switching tabs changes what Kiro sees - if you switch to a CSS file, any TS-specific fileMatch steering deactivates

Files that are merely open in background tabs are not included. Only the active (focused) tab counts.

Split editor layouts

If you have two files side-by-side in a split layout, only the pane with focus (the one with the blinking cursor) counts as active. The other pane is treated the same as a background tab - Kiro sees its name in the open files list but not its content.

The "unwanted active file" problem

The active file is determined by whether an editor pane has focus. If you click into the chat input to type your message, the editor loses focus and Kiro reports no active file - meaning no file content is sent.

So in practice: if you click into the chat panel before sending, no active file is included. The active file only gets sent if you had an editor pane focused when you triggered the message (e.g. via a keyboard shortcut that doesn't move focus from the editor).

This makes it less intrusive than it might sound - but it's still worth being aware of, especially if you use keyboard shortcuts that keep editor focus.

Open Editor Files vs Active File

Kiro also receives a list of the names of files you have open in editor tabs (the <OPEN-EDITOR-FILES> list). This gives Kiro awareness of what you're working on - useful for understanding your context - but it does not include their contents. Only the active file's content is injected.

You can't see the raw context Kiro receives - there's no "show context" panel in the IDE. But you can infer its effect: Kiro may reference files you have open without you explicitly mentioning them, because it can see their names in this list.

How This Connects to Steering

Now you can see the full picture from Lesson 1:

• Always-on steering - occupies space on every message, regardless. Budget it carefully.
• fileMatch steering - only enters the context when a matching file is the active tab, is referenced via #, or is read by the agent. Free when not relevant.
• Manual steering - only enters the context when you invoke it. Zero cost by default.

This is why the inclusion modes exist: they're tools for managing a scarce resource (context window space) efficiently.

Practical Tips

• Start sessions with context, not history. In a new session, Kiro has no memory of previous sessions. If you need continuity, use steering files or reference key files - don't rely on Kiro "remembering."
• Use #File deliberately. Adding a large file uses tokens. If you only need Kiro to see a function, mention the function name and let the agent read just that part.
• Watch for stale context in long sessions. If Kiro seems to forget earlier decisions, it's likely been compacted. Re-state what matters or re-reference the file.
• Steering is your session memory. Anything you want Kiro to always know should be in steering, not repeated in chat. Steering is re-injected fresh; chat history gets compacted.

Your Tangible Win

You now understand the full lifecycle of context in Kiro: what goes in, what triggers conditional content, what happens in long sessions, and how to manage it. You can make informed decisions about where to put information (steering vs. chat vs. explicit references) based on how long it needs to persist and how often it's relevant.

Quiz