AWS amazonq documentation change
Summary
Expanded documentation about context management approaches, added knowledge base integration details, and introduced security best practices section
Security assessment
The changes add a 'Security considerations' subsection advising against including sensitive information in context files and recommending .gitignore usage. While this demonstrates security awareness, there's no evidence of addressing a specific security vulnerability or incident. The guidance is preventive rather than reactive.
Diff
diff --git a/amazonq/latest/qdeveloper-ug/command-line-context.md b/amazonq/latest/qdeveloper-ug/command-line-context.md index 90843242b..7aa388321 100644 --- a//amazonq/latest/qdeveloper-ug/command-line-context.md +++ b//amazonq/latest/qdeveloper-ug/command-line-context.md @@ -5 +5 @@ -Managing contextCommon use cases +Choosing the right context approachUnderstanding context window impactManaging contextCommon use casesBest practices @@ -9 +9 @@ Managing contextCommon use cases -## Managing context +## Choosing the right context approach @@ -11 +11,23 @@ Managing contextCommon use cases -Context files contain information you want Amazon Q to consider during your conversations. These can include project requirements, coding standards, development rules, or any other information that helps Amazon Q provide more relevant responses. +Amazon Q 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 +**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: + + 1. **Is your content larger than 10MB or contains thousands of files?** + + * **Yes** → Use Knowledge Bases + + * **No** → Continue to step 2 + + 2. **Do you need this context in every conversation?** + + * **Yes** → Use Agent Resources + + * **No** → Use Session Context @@ -13 +34,0 @@ Context files contain information you want Amazon Q to consider during your conv -There are two ways to configure context: @@ -15 +35,0 @@ There are two ways to configure context: - * **Agent resources** (recommended): Persistent context defined in your agent configuration file @@ -17 +36,0 @@ There are two ways to configure context: - * **Session context** : Temporary context added during a chat session using `/context` commands @@ -18,0 +38 @@ There are two ways to configure context: +**Quick reference:** @@ -19,0 +40 @@ There are two ways to configure context: + * Essential project files (README, configs, standards) → Agent Resources @@ -20,0 +42,23 @@ There are two ways to configure context: + * Large codebases or documentation sets → Knowledge Bases + + * Temporary files for current task → Session Context + + + + +## Understanding context window impact + +Context files and agent resources consume tokens from your context window on every request, whether referenced or not. Use `/context show` to monitor token usage: + + + q chat + > /context show + Total: ~1100 tokens + +**Token limits** : 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 Amazon Q to consider during your conversations. These can include project requirements, coding standards, development rules, or any other information that helps Amazon Q provide more relevant responses. @@ -60 +104,24 @@ You can also add multiple files at once using glob patterns: -To make context changes permanent, add the files to your agent's `resources` field instead. +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: + + + q settings chat.enableKnowledge true + +Add content to knowledge base: + + + q chat + > /knowledge add /path/to/large-codebase --include "**/*.py" --exclude "node_modules/**" + +Search knowledge base: + + + q chat + > /knowledge search "authentication patterns" + +Knowledge bases are searched on-demand by Amazon Q when relevant information is needed, making them ideal for large reference materials. @@ -162 +229 @@ If you find yourself repeatedly adding the same context files using `/context ad - 2. Edit your agent configuration file + 2. Edit your agent configuration file using `/agent edit` or by directly modifying the file @@ -187,0 +255,76 @@ Example migration: +### When to use knowledge bases + +Consider knowledge bases when: + + * Your context files exceed the token limit (75% of context window) + + * 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: + + + # This would consume too many tokens: + > /context add src/**/*.py + + # Use knowledge base instead: + > /knowledge add src/ --include "**/*.py" --exclude "__pycache__/**" + +### Setting a default agent with context + +You can configure a default agent that includes your preferred context files: + + + q settings chat.defaultAgent my-project-agent + +This ensures your context is automatically available in new chat sessions without needing to specify the agent each time. + +## 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 + + + +