Context management

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.

There are two ways to configure context:

• Agent resources (recommended): Persistent context defined in your agent configuration file

• Session context: Temporary context added during a chat session using /context commands

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:

{
  "name": "my-agent",
  "description": "My development agent",
  "resources": [
    "file://README.md",
    "file://.amazonq/rules/**/*.md",
    "file://docs/**/*.md",
    "file://src/config.py"
  ]
}

Resources must be prefixed with file:// to be included as context files. These files will be automatically available in all chat sessions using this agent.

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.

q chat
> /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:

q chat
> /context add docs/*.md
Added 3 path(s) to context.
Note: Context modifications via slash command is temporary.

To make context changes permanent, add the files to your agent's resources field instead.

Viewing context

To view your current context, use the /context show command:

q chat
> /context show
👤 Agent (my-agent):
    README.md (1 match)
    .amazonq/rules/**/*.md (3 matches)
    docs/**/*.md (5 matches)

💬 Session (temporary):
    <none>

5 matched files in use:
👤 README.md (~250 tkns)
👤 .amazonq/rules/security.md (~180 tkns)
👤 .amazonq/rules/coding-standards.md (~320 tkns)
👤 docs/architecture.md (~150 tkns)
👤 docs/best-practices.md (~200 tkns)

Total: ~1100 tokens

The output shows:

• 👤 Agent: Persistent context from your agent's resources field

• 💬 Session: Temporary context added during the current session

Removing context

To remove files from your current session context, use the /context rm command:

q chat
> /context rm src/temp-file.py
Removed 1 path(s) from context.
Note: Context modifications via slash command is temporary.

To clear all session context, use the /context clear command:

q chat
> /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.

Common use cases

Here are some common use cases for context management:

Using project rules

Amazon Q supports project-level rules that can define security guidelines and restrictions. These rules are defined in Markdown files in the .amazonq/rules directory of your project.

For example, you can create rules that specify:

• Which directories Amazon Q should avoid accessing

• Security requirements for generated code

• Coding standards and best practices

The recommended way to include project rules is through your agent configuration:

{
  "name": "my-project-agent",
  "resources": [
    "file://.amazonq/rules/**/*.md",
    "file://README.md",
    "file://docs/architecture.md"
  ]
}

You can also temporarily add project rules to your current session:

q chat
> /context add .amazonq/rules/*.md
Added 3 path(s) to context.
Note: Context modifications via slash command is temporary.

For more information about creating and using project rules, see Creating project rules for use with Amazon Q Developer chat in the IDE documentation.

Migrating from session context to agent resources

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:

1. Note the files you frequently add with /context add

2. Edit your agent configuration file

3. Add the file paths to the resources array with file:// prefix

4. Save the agent configuration

Example migration:

# Instead of running these commands every session:
> /context add README.md
> /context add docs/*.md
> /context add .amazonq/rules/*.md

# Add them to your agent config once:
{
  "resources": [
    "file://README.md",
    "file://docs/**/*.md", 
    "file://.amazonq/rules/**/*.md"
  ]
}