Context management - Chat - CLI - Docs - Kiro Loading image... Product * About Kiro * IDE * CLI * Web * Mobile * Crew * Pricing * Downloads For * Enterprise * Startups * Students Community * Overview * Ambassadors * Discord * Events * Powers * Shop * Showcase Resources * Docs * Blog * Changelog * FAQs * Report a bug * Suggest an idea * Billing support Social * * * * * * * English Site Terms License Responsible AI Policy Legal Privacy Policy Cookie Preferences English Loading image... * Apps * CLI * Web * Enterprise * Pricing * Docs * Community * Resources SIGN IN DOWNLOADS Loading image... Get Started Installation Authentication Your first project Models Overview Available models Reasoning effort Features How Kiro works Specs Steering Hooks MCP Permissions Custom agents Agent Skills Powers Cloud sessions Compaction Kiroignore Checkpoints and rewind Built-in tools Configuration scopes IDE 1.x What's new in 1.0 Setup & First Run Editor Chat Experimental Troubleshooting 0.x reference CLI What's new in 3.0 Setup & First Run Terminal UI Chat Session management Goal Queue steering In-session settings Prompts File references Context management Responding to messages Working with Git Images Custom diff tools Voice mode Headless mode ACP Auto complete Experimental 2.x reference Crew Quick start Installation Running 24/7 Chat Agent Capabilities Features Interfaces Apps System & storage Configuration Security Troubleshooting Web Setup & First Run Identity Center Connect your repositories Working with the agent Autonomous mode Automations Memory Configuration Sync Sandbox Mobile - Preview Overview Commands and Reference CLI commands Slash commands Built-in tools Exit codes Settings Billing Overview Managing your subscription Upgrading your plan Downgrading your plan Cancelling your plan Purchasing add-on credits Managing your payments Managing usage notifications Managing your taxes Contacting billing support Deleting your account Related questions Enterprise Concepts Onboarding quickstart Connecting your identity provider Deployment options Subscribe your team Manage subscriptions Governance Monitor and track Settings Managed updates Billing IAM Supported regions Privacy and Security Overview Data protection Code references Compliance validation Infrastructure security IAM permissions Firewalls, proxies, and data perimeters VPC endpoints (AWS PrivateLink) Guides Overview Language support Learn by playing Migration Migrating from Q Developer Migrating from VSCode Upgrading from Q CLI * Docs * * CLI * * Chat * * Context management Copy page View as Markdown Context management Copy page View as Markdown Choosing the right context approach Kiro offers three ways to provide context, each optimized for different use cases: Approach Context Window Impact Persistence Best For Agent Resources Always active (consumes tokens) Persistent across sessions Essential project files, standards, configs Skills On demand Persistent across sessions Large guides, reference docs, specialized knowledge Session Context Always active (consumes tokens) Current session only Temporary files, quick experiments Knowledge Bases Only when searched Persistent across sessions Large codebases, extensive documentation Decision flowchart * Use this decision tree to choose the appropriate context approach: * Is your content larger than 10MB or contains thousands of files? * Yes → Use Knowledge Bases * No → Continue to step 2 * Do you need this context in every conversation? * Yes → Use Agent Resources * No → Use Session Context Quick reference * Essential project files (README, configs, standards) → Agent Resources * Large codebases or documentation sets → Knowledge Bases * Temporary files for current task → Session Context Understanding context window impact Kiro automatically includes your working directory and operating system as context in every session. You don't need to configure this. * Context files and agent resources consume tokens from your context window on every request, whether referenced or not. bash > /context show Agent - .kiro/steering/**/*.md < project-root > /.kiro/steering/product.md < project-root > /.kiro/steering/structure.md < project-root > /.kiro/steering/tech.md < project-root > /.kiro/steering/testing.md - README.md < project-root > /snake/README.md - ~/.kiro/steering/**/*.md ( no matches ) Session ( temporary ) < none > 5 matched files in use - < project-root > /.kiro/steering/testing.md ( 0.1 % of context window ) - < project-root > /snake/.kiro/steering/tech.md ( 0.1 % of context window ) - < project-root > /snake/README.md ( 0.1 % of context window ) - < project-root > /snake/.kiro/steering/structure.md ( 0.2 % of context window ) - < project-root > /snake/.kiro/steering/product.md ( 0.1 % of context window ) Context files total: 0.5 % of context window * The output shows: * Agent : Persistent context from your agent's resources field * Session : Temporary context added during the current session * Context files are limited to 75% of your model's context window. Files exceeding this limit are automatically dropped. * Knowledge bases don't consume context window space until searched, making them ideal for large reference materials. For more information, see Knowledge base context (for large datasets). Managing context Context files contain information you want Kiro to consider during your conversations. These can include project requirements, coding standards, development rules, or any other information that helps Kiro provide more relevant responses. Configuring persistent context with agent resources The recommended way to configure context is through the resources field in your agent configuration file. This creates persistent context that is available every time you use the agent. Add file paths or glob patterns to the resources array in your agent config: json { "name" : "my-agent" , "description" : "My development agent" , "resources" : [ "file://README.md" , "file://docs/**/*.md" , "file://src/config.py" ] } Resources use URI schemes to specify the type: * file:// — Files loaded directly into context at startup * skill:// — Skills with metadata loaded at startup, full content loaded on demand * knowledgeBase — Indexed content searched on demand (configured as objects, not URI strings) These files will be automatically available in all chat sessions using this agent. For more details on resource types, see the Agent Configuration Reference . Adding temporary session context You can temporarily add files to your current chat session using the /context add command. These additions are only available for the current session and will not persist when you start a new chat session. bash > /context add README.md Added 1 path ( s ) to context. Note : Context modifications via slash command is temporary. You can also add multiple files at once using glob patterns: bash > /context add docs/*.md Added 3 path ( s ) to context. To make context changes permanent, add the files to your agent's resources field instead. For more information, see Configuring persistent context with agent resources. Knowledge base context (for large datasets) For large codebases, documentation sets, or reference materials that would exceed context window limits, use knowledge bases. Knowledge bases provide semantic search capabilities without consuming context window space until searched. Enable knowledge bases: kiro-cli settings chat.enableKnowledge true Add content to a knowledge base: kiro-cli chat /knowledge add /path/to/large-codebase --include " /*.py" --exclude "node_modules/ " Knowledge bases are searched on-demand by Kiro when relevant information is needed, making them ideal for large reference materials. Conversation compaction Compaction summarizes older messages while retaining recent ones, freeing up context window space. * Manual : Run /compact * Automatic : Triggers when context window overflows Configuration Setting Default Description compaction.excludeMessages 2 Minimum message pairs to retain compaction.excludeContextWindowPercent 2 Minimum % of context window to retain Both settings are evaluated, and the more conservative (larger) value wins. Compaction will create a new session. You can resume the original via /chat resume . Context % updates after your next prompt After running /compact , the context usage percentage shown in the status bar may not change immediately. The accurate usage is only calculated when you send your next message, because the backend determines actual token counts during request processing. Send a prompt after compacting to see the updated percentage. Viewing context usage To view your current context, use the /context show command: bash > /context show Current context window ( 5.9 % used ) || | ████████████████████████████████████████████████████████████████ 5.9 % █ Context files 0.9 % █ Tools 0.5 % █ Kiro responses 0.7 % █ Your prompts 3.8 % The output shows glob patterns for context entries, making it easier to identify and remove them. Removing context To remove files from your current session context: bash > /context remove src/temp-file.py Removed 1 path ( s ) from context. To clear all session context, use the /context clear command: bash > /context clear Cleared context Note: Context modifications via slash command is temporary. Note: You cannot remove agent-defined context using /context commands. To permanently remove context, edit your agent's resources field. Context management actions Here are some common reasons for actively managing your context window: * If you find yourself repeatedly adding the same context files using /context add commands, consider moving them to your agent's resources field for persistence: bash # Instead of running these commands every session: > /context add README.md > /context add docs/*.md # Add them to your agent config once: { "resources" : [ "file://README.md" , "file://docs/**/*.md" ] } You can configure a default agent that includes your preferred context files. This ensures your context is automatically available in new chat sessions without needing to specify the agent each time. bash > kiro-cli settings chat.defaultAgent my-project-agent * If you have large context files (consume significant part of context window) consider using knowledge base instead of including those files as is. Use cases to consider knowledge: * You have large codebases or documentation sets * You need semantic search across extensive materials * You want to avoid constant context window consumption * Example: Instead of adding a large codebase as context files: bash # This would consume too many tokens: > /context add src/**/*.py # Use knowledge base instead: > /knowledge add src/ --include "**/*.py" --exclude "__pycache__/**" Best practices Context file organization * Keep context files focused and relevant to avoid token limits * Use descriptive filenames that indicate their purpose * Organize rules and documentation in logical directory structures * Consider file size - very large files may consume significant tokens Performance considerations * Monitor token usage with /context show to stay within limits * Use specific glob patterns rather than overly broad ones * Remove unused context files from agent configurations * Consider splitting large context files into smaller, focused files * Use knowledge bases for large datasets to avoid context window consumption Security considerations * Avoid including sensitive information in context files * Use .gitignore to prevent accidental commits of sensitive context * Review context files regularly to ensure they don't contain outdated information * Be mindful of what information is shared when using context in conversations Related documentation * Slash Commands - In-chat context commands * CLI Commands - Terminal context commands * Interactive Chat Mode - Using context in chat Page updated: August 4, 2026 File references Responding to messages