Skip to content

Commit fc99d39

Browse files
chaynaborschaynabors
authored
docs: knowledge and tools docs (#2299)
* add agent documentation * docs changes * add more docs * fix typo
1 parent f3b4967 commit fc99d39

File tree

4 files changed

+282
-10
lines changed

4 files changed

+282
-10
lines changed

‎docs/SUMMARY.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,3 +4,4 @@
44

55
- [The Agent Format](./the-agent-format.md)
66
- [Native Tools](./native-tools.md)
7+
- [Knowledge Management](./knowledge-management.md)

‎docs/introduction.md

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,8 @@
22

33
Welcome to the Amazon Q CLI developer documentation.
44

5-
These docs are a work in progress and subject to change.
5+
These docs are a work in progress and subject to change. As of now, they do not represent latest stable builds, instead documenting the functionality of development builds.
66

77
For information on configuring agents, see [The Agent Format](./the-agent-format.md)
8+
9+
For information on managing knowledge, see [Knowledge Management](./knowledge-management.md)

‎docs/knowledge-management.md

Lines changed: 169 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,169 @@
1+
# Knowledge Management
2+
3+
The /knowledge command provides persistent knowledge base functionality for Amazon Q CLI, allowing you to store, search, and manage contextual information that persists across chat sessions.
4+
5+
> Note: This is a beta feature that must be enabled before use.
6+
7+
## Getting Started
8+
9+
Enable the Knowledge Feature
10+
11+
The knowledge feature is experimental and disabled by default. Enable it with:
12+
13+
`q settings chat.enableKnowledge true`
14+
15+
## Basic Usage
16+
17+
Once enabled, you can use `/knowledge` commands within your chat session:
18+
19+
`/knowledge add myproject /path/to/project`
20+
`/knowledge show`
21+
22+
## Commands
23+
24+
#### `/knowledge show`
25+
26+
Display all entries in your knowledge base with detailed information including creation dates, item counts, and persistence status.
27+
28+
#### `/knowledge add <name> <path>`
29+
30+
Add files or directories to your knowledge base. The system will recursively index all supported files in directories.
31+
32+
`/knowledge add "project-docs" /path/to/documentation`
33+
`/knowledge add "config-files" /path/to/config.json`
34+
35+
Supported file types:
36+
37+
- Text files: .txt
38+
- Markdown: .md, .markdown
39+
- JSON: .json
40+
- Code files: .rs, .py, .js, .jsx, .ts, .tsx, .java, .c, .cpp, .h, .hpp, .go, .rb, .php, .swift, .kt, .kts, .cs, .sh, .bash, .zsh, .html, .htm, .xml, .css, .scss, .sass, .less, .sql, .yaml, .yml, .toml
41+
42+
> Important: Unsupported files are indexed without text content extraction.
43+
44+
#### `/knowledge remove <identifier>`
45+
46+
Remove entries from your knowledge base. You can remove by name, path, or context ID.
47+
48+
`/knowledge remove "project-docs"` # Remove by name
49+
`/knowledge remove /path/to/old/project` # Remove by path
50+
51+
#### `/knowledge update <path>`
52+
53+
Update an existing knowledge base entry with new content from the specified path.
54+
55+
`/knowledge update /path/to/updated/project`
56+
57+
#### `/knowledge clear`
58+
59+
Remove all entries from your knowledge base. This action requires confirmation and cannot be undone.
60+
61+
You'll be prompted to confirm:
62+
63+
> ⚠️ This will remove ALL knowledge base entries. Are you sure? (y/N):
64+
65+
#### `/knowledge status`
66+
67+
View the status of background indexing operations, including progress and queue information.
68+
69+
#### `/knowledge cancel [operation_id]`
70+
71+
Cancel background operations. You can cancel a specific operation by ID or all operations if no ID is provided.
72+
73+
`/knowledge cancel abc12345 # Cancel specific operation`
74+
`/knowledge cancel all # Cancel all operations`
75+
76+
## How It Works
77+
78+
#### Indexing Process
79+
80+
When you add content to the knowledge base:
81+
82+
1. File Discovery: The system recursively scans directories for supported file types
83+
2. Content Extraction: Text content is extracted from each supported file
84+
3. Chunking: Large files are split into smaller, searchable chunks
85+
4. Background Processing: Indexing happens asynchronously in the background
86+
5. Semantic Embedding: Content is processed for semantic search capabilities
87+
88+
#### Search Capabilities
89+
90+
The knowledge base uses semantic search, which means:
91+
92+
- You can search using natural language queries
93+
- Results are ranked by relevance, not just keyword matching
94+
- Related concepts are found even if exact words don't match
95+
96+
#### Persistence
97+
98+
- Persistent contexts: Survive across chat sessions and CLI restarts
99+
- Context persistence is determined automatically based on usage patterns
100+
101+
#### Best Practices
102+
103+
Organizing Your Knowledge Base
104+
105+
- Use descriptive names when adding contexts: "api-documentation" instead of "docs"
106+
- Group related files in directories before adding them
107+
- Regularly review and update outdated contexts
108+
109+
#### Effective Searching
110+
111+
- Use natural language queries: "how to handle authentication errors using the knowledge tool"
112+
- Be specific about what you're looking for: "database connection configuration"
113+
- Try different phrasings if initial searches don't return expected results
114+
- Prompt Q to use the tool with prompts like "find database connection configuration using your knowledge bases" or "using your knowledge tools can you find how to replace your laptop"
115+
116+
#### Managing Large Projects
117+
118+
- Add project directories rather than individual files when possible
119+
- Use /knowledge status to monitor indexing progress for large directories
120+
- Consider breaking very large projects into logical sub-directories
121+
122+
## Limitations
123+
124+
#### File Type Support
125+
126+
- .mdx files are not currently supported for content extraction
127+
- Binary files are ignored during indexing
128+
- Very large files may be chunked, potentially splitting related content.
129+
130+
#### Performance Considerations
131+
132+
- Large directories may take significant time to index
133+
- Background operations are limited by concurrent processing limits
134+
- Search performance may vary based on knowledge base size
135+
- Currently there’s a hard limit of 5k files per knowledge base (getting removed soon as on Jul 12th, 2025).
136+
137+
#### Storage and Persistence
138+
139+
- No explicit storage size limits, but practical limits apply
140+
- No automatic cleanup of old or unused contexts
141+
- Clear operations are irreversible with no backup functionality
142+
143+
## Troubleshooting
144+
145+
#### Files Not Being Indexed
146+
147+
If your files aren't appearing in search results:
148+
149+
1. Check file types: Ensure your files have supported extensions
150+
2. Monitor status: Use /knowledge status to check if indexing is still in progress
151+
3. Verify paths: Ensure the paths you added actually exist and are accessible
152+
4. Check for errors: Look for error messages in the CLI output
153+
154+
#### Search Not Finding Expected Results
155+
156+
If searches aren't returning expected results:
157+
158+
1. Wait for indexing: Use /knowledge status to ensure indexing is complete
159+
2. Try different queries: Use various phrasings and keywords
160+
3. Verify content: Use /knowledge show to confirm your content was added
161+
4. Check file types: Unsupported file types won't have searchable content
162+
163+
#### Performance Issues
164+
165+
If operations are slow:
166+
167+
1. Check queue status: Use /knowledge status to see operation queue
168+
2. Cancel if needed: Use /knowledge cancel to stop problematic operations
169+
3. Add smaller chunks: Consider adding subdirectories instead of entire large projects

‎docs/native-tools.md

Lines changed: 109 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -28,29 +28,129 @@ Execute the specified bash command.
2828
#### Example
2929

3030
```json
31-
{}
31+
{
32+
"allowedCommands": ["git status", "git fetch"],
33+
"allowReadOnly": true
34+
}
3235
```
3336

3437
## fs_read
3538

36-
Tool for reading files, directories and images. Always provide an 'operations' array.
39+
Tool for reading files, directories and images.
40+
41+
### Config
42+
43+
#### Schema
3744

38-
For single operation: provide array with one element.
39-
For batch operations: provide array with multiple elements.
45+
```json
46+
{
47+
"type": "object",
48+
"properties": {
49+
"allowedPaths": {
50+
"type": "array",
51+
"items": {
52+
"type": "string"
53+
},
54+
"default": []
55+
}
56+
}
57+
}
58+
```
4059

41-
Available modes:
60+
#### Example
4261

43-
- Line: Read lines from a file
44-
- Directory: List directory contents
45-
- Search: Search for patterns in files
46-
- Image: Read and process image
62+
```json
63+
{
64+
"allowedPaths": ["~"]
65+
}
66+
```
4767

4868
## fs_write
4969

70+
Tool for creating and editing files.
71+
72+
### Config
73+
74+
#### Schema
75+
76+
```json
77+
{
78+
"type": "object",
79+
"properties": {
80+
"allowedPaths": {
81+
"type": "array",
82+
"items": {
83+
"type": "string"
84+
},
85+
"default": []
86+
}
87+
}
88+
}
89+
```
90+
91+
#### Example
92+
93+
```json
94+
{
95+
"allowedPaths": [
96+
"~/file-to-create.txt",
97+
"~/editable-file.txt",
98+
"~/my-workspace/"
99+
]
100+
}
101+
```
102+
50103
## gh_issue
51104

105+
Opens the browser to our GitHub template for reporting issues with `q`.
106+
107+
### Config
108+
109+
This tool has no configuration.
110+
52111
## knowledge
53112

113+
Store and retrieve information in knowledge base across chat sessions
114+
115+
### Config
116+
117+
This tool has no configuration.
118+
54119
## thinking
55120

121+
Thinking is an internal reasoning mechanism improving the quality of complex tasks by breaking their atomic actions down.
122+
123+
### Config
124+
125+
This tool has no configuration.
126+
56127
## use_aws
128+
129+
Make an AWS CLI api call with the specified service, operation, and parameters.
130+
131+
### Config
132+
133+
#### Schema
134+
135+
```json
136+
{
137+
"type": "object",
138+
"properties": {
139+
"allowedServices": {
140+
"type": "array",
141+
"items": {
142+
"type": "string"
143+
},
144+
"default": []
145+
}
146+
}
147+
}
148+
```
149+
150+
#### Example
151+
152+
```json
153+
{
154+
"allowedServices": ["s3", "iam"]
155+
}
156+
```

0 commit comments

Comments
 (0)