The /knowledge command provides persistent knowledge base functionality for Kiro CLI, allowing you to store, search, and manage contextual information that persists across chat sessions.
V3 enables knowledge by default. To turn it off, set chat.enableKnowledge to false:
kiro-cli settings chat.enableKnowledge false
In the V1 and V2 agent harnesses, knowledge is experimental and must be enabled before use:
kiro-cli settings chat.enableKnowledge true
Once enabled, use /knowledge commands within your chat session:
/knowledge add --name myproject --path /path/to/project /knowledge show
Display all entries in your knowledge base with detailed information including creation dates, item counts, and persistence status. Also shows any active background indexing operations with progress and ETA.
This unified command provides a complete view of both your stored knowledge and ongoing operations.
/knowledge show
Add files or directories to your knowledge base. The system recursively indexes all supported files in directories.
Syntax:
/knowledge add --name <name> --path <path> [--include pattern] [--exclude pattern] [--index-type Fast|Best]
Required Parameters:
--nameor-n: Descriptive name for the knowledge entry--pathor-p: Path to file or directory to index
Examples:
/knowledge add --name "project-docs" --path /path/to/documentation /knowledge add -n "config-files" -p /path/to/config.json /knowledge add --name "fast-search" --path /path/to/logs --index-type Fast /knowledge add -n "semantic-search" -p /path/to/docs --index-type Best
Choose the indexing approach that best fits your needs:
Advantages:
- ✅ Lightning-fast indexing - processes files quickly
- ✅ Instant search - keyword-based with immediate results
- ✅ Low resource usage - minimal CPU and memory
- ✅ Perfect for logs, configs, and large codebases
Disadvantages:
- ❌ Less intelligent - requires exact keyword matches
Advantages:
- ✅ Intelligent search - understands context and meaning
- ✅ Natural language queries - search with full sentences
- ✅ Finds related concepts - even without exact keywords
- ✅ Perfect for documentation and research
Disadvantages:
- ❌ Slower indexing - requires AI model processing
- ❌ Higher resource usage - more CPU and memory intensive
| Use Case | Recommended Type | Why |
|---|---|---|
| Log files, error messages | Fast | Quick keyword searches, large volumes |
| Configuration files | Fast | Exact parameter/value lookups |
| Large codebases | Fast | Fast symbol and function searches |
| Documentation | Best | Natural language understanding |
| Research papers | Best | Concept-based searching |
| Mixed content | Best | Better overall search experience |
If you don't specify --index-type, the system uses your configured default:
# Set your preferred default kiro-cli settings knowledge.indexType Fast # or Best # This will use your default setting /knowledge add "my-project" /path/to/project
Control which files are indexed using include and exclude patterns:
/knowledge add "rust-code" /path/to/project --include "*.rs" --exclude "target/**" /knowledge add "docs" /path/to/project --include "**/*.md" --include "**/*.txt" --exclude "node_modules/**"
Pattern Examples:
*.rs- All Rust files recursively (equivalent to**/*.rs)**/*.py- All Python files recursivelytarget/**- Everything in target directorynode_modules/**- Everything in node_modules
Default Pattern Behavior:
When you don't specify patterns, the system uses configured defaults:
kiro-cli settings knowledge.defaultIncludePatterns '["**/*.rs", "**/*.py"]' kiro-cli settings knowledge.defaultExcludePatterns '["target/**", "__pycache__/**"]' # Uses default patterns /knowledge add "my-project" /path/to/project # Overrides defaults /knowledge add "docs-only" /path/to/project --include "**/*.md"
Text files: .txt, .log, .rtf, .tex, .rst
Markdown: .md, .markdown, .mdx
JSON: .json (treated as text for searchability)
Configuration: .ini, .conf, .cfg, .properties, .env
Data files: .csv, .tsv
Web formats: .svg (text-based)
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
Special files: Dockerfile, Makefile, LICENSE, CHANGELOG, README (files without extensions)
Note: Unsupported files are indexed without text content extraction.
Remove entries from your knowledge base by name, path, or context ID.
/knowledge remove "project-docs" # Remove by name /knowledge remove /path/to/old/project # Remove by path
Update (re-index) an existing knowledge base entry with new content. Original include/exclude patterns are preserved.
# Re-index a single entry /knowledge update /path/to/updated/project # Re-index every entry at once /knowledge update
Run /knowledge update with no arguments to re-index every entry in your knowledge base at once, instead of updating one path at a time.
Remove all entries from your knowledge base. Requires confirmation and cannot be undone.
/knowledge clear
You'll be prompted:
⚠️ This will remove ALL knowledge base entries. Are you sure? (y/N):
Cancel background operations. Cancel specific operation by ID or all operations.
/knowledge cancel abc12345 # Cancel specific operation /knowledge cancel all # Cancel all operations
Configure knowledge base behavior:
# Maximum files per knowledge base kiro-cli settings knowledge.maxFiles 10000 # Text chunk size for processing kiro-cli settings knowledge.chunkSize 1024 # Overlap between chunks kiro-cli settings knowledge.chunkOverlap 256 # Default index type kiro-cli settings knowledge.indexType Fast # Default include patterns kiro-cli settings knowledge.defaultIncludePatterns '["**/*.rs", "**/*.md"]' # Default exclude patterns kiro-cli settings knowledge.defaultExcludePatterns '["target/**", "node_modules/**"]'
Each agent maintains its own isolated knowledge base, ensuring knowledge contexts are scoped to the specific agent you're working with. This provides better organization and prevents knowledge conflicts.
Knowledge bases are stored in your system's local data directory:
- macOS:
~/Library/Application Support/kiro-cli/knowledge_bases/ - Linux:
~/.local/share/kiro-cli/knowledge_bases/ - Windows:
%LOCALAPPDATA%\kiro-cli\knowledge_bases\
knowledge_bases/ ├── kiro_cli_default/ # Default agent │ ├── contexts.json │ ├── context-id-1/ │ │ ├── data.json │ │ └── bm25_data.json │ └── context-id-2/ │ └── data.json ├── my-custom-agent_<code>/ # Custom agent │ ├── contexts.json │ └── context-id-3/ │ └── data.json └── another-agent_<code>/ # Another agent ├── contexts.json └── context-id-4/ └── data.json
- Automatic Scoping:
/knowledgecommands operate on current agent's knowledge base - No Cross-Agent Access: Agent A cannot access Agent B's knowledge
- Independent Configuration: Each agent has different settings and contexts
- Migration Support: Legacy knowledge bases migrate to default agent
When you switch agents, knowledge commands automatically work with that agent's knowledge base.
# Working with default agent /knowledge add /path/to/docs # Switch to custom agent kiro chat --agent my-custom-agent # Creates separate knowledge base for my-custom-agent /knowledge add /path/to/agent/docs # Switch back to default kiro chat # Only sees original docs, not agent-specific docs /knowledge show
- Pattern Filtering: Files filtered by include/exclude patterns
- File Discovery: Recursive scan for supported file types
- Content Extraction: Text extracted from each file
- Chunking: Large files split into searchable chunks
- Background Processing: Asynchronous indexing
- Semantic Embedding: Content processed for semantic search
Knowledge bases use semantic search:
- Natural language queries
- Results ranked by relevance, not just keywords
- Related concepts found even without exact word matches
- Contexts survive across chat sessions and CLI restarts
- Persistence determined automatically by usage patterns
- Include/exclude patterns stored and reused during updates
- Use descriptive names: "api-documentation" not "docs"
- Group related files in directories before adding
- Use include/exclude patterns to focus on relevant files
- Regularly review and update outdated contexts
- Use natural language: "how to handle authentication errors using the knowledge tool"
- Be specific: "database connection configuration"
- Try different phrasings if initial searches don't work
- Prompt Kiro to use the tool: "find database connection configuration using your knowledge bases"
- Add project directories rather than individual files
- Use patterns to avoid build artifacts:
--exclude "target/**" --exclude "node_modules/**" - Use
/knowledge showto monitor indexing progress - Consider breaking large projects into logical sub-directories
- Be specific: Use precise patterns to avoid over-inclusion
- Exclude build artifacts: Always exclude
target/**,node_modules/**,.git/** - Include relevant extensions: Focus on file types you need
- Test patterns: Verify patterns match expected files before large operations
- Binary files ignored during indexing
- Very large files may be chunked, potentially splitting related content
- Some specialized formats may not extract content optimally
- Large directories may take significant time to index
- Background operations limited by concurrent processing
- Search performance varies by knowledge base size
- Pattern filtering improves performance for large directories
- No explicit storage size limits, but practical limits apply
- No automatic cleanup of old or unused contexts
- Clear operations are irreversible with no backup
- Check patterns: Ensure include patterns match your files
- Verify exclude patterns: Make sure they're not filtering desired files
- Check file types: Ensure files have supported extensions
- Monitor progress: Use
/knowledge showto check indexing status - Verify paths: Ensure paths exist and are accessible
- Check for errors: Look for error messages in CLI output
- Wait for indexing: Use
/knowledge showto ensure completion - Try different queries: Use various phrasings and keywords
- Verify content: Confirm content was added with
/knowledge show - Check file types: Unsupported types won't have searchable content
- Check operations: Use
/knowledge showfor progress - Cancel if needed: Use
/knowledge cancelfor problematic operations - Add smaller chunks: Consider subdirectories instead of entire projects
- Use better patterns: Exclude unnecessary files
- Adjust settings: Lower
maxFilesorchunkSizefor better performance
- Test patterns: Start simple, then add complexity
- Check syntax: Ensure glob patterns use correct syntax (
**for recursive) - Verify paths: Make sure patterns match actual file paths
- Use absolute patterns: Consider full paths for precision
Knowledge management