Knowledge management 让 Kiro CLI 把项目文件、文档和文本资料沉淀为可检索的 knowledge base。本文梳理 /knowledge 的添加、更新、删除、查询和取消操作，解释 Fast 与 Best 索引、文件过滤、agent 隔离和性能限制。

Kiro CLI Experimental Knowledge Management：为 agent 建立可检索长期上下文

Knowledge management 解决的是一个常见问题：Kiro 不可能每次都自动知道你的项目背景、内部文档、错误日志和团队约定。通过 /knowledge，你可以把这些资料加入 knowledge base，让 Kiro 在后续会话中用 semantic search 或关键词检索找回相关上下文。

它特别适合长期维护的项目：例如架构文档、API 规范、配置说明、历史故障记录、需求材料、研究笔记等。相比每次手动粘贴上下文，knowledge base 更稳定，也更适合跨会话复用。

启用 knowledge 功能

Knowledge management 仍属于 Experimental 功能，需要先启用：

kiro-cli settings chat.enableKnowledge true

启用后，在聊天会话中使用 /knowledge 命令：

/knowledge add --name myproject --path /path/to/project
/knowledge show

核心命令

/knowledge show

展示当前 agent 的所有 knowledge entries，包括创建时间、条目数量、持久化状态，以及正在后台索引的任务进度和预计剩余时间。

/knowledge show

这是排障和日常管理的第一条命令。搜索不到内容时，先用它确认索引是否完成、内容是否真的加入了 knowledge base。

/knowledge add

把文件或目录加入 knowledge base。添加目录时，Kiro 会递归扫描支持的文件类型，并根据 include/exclude pattern 过滤。

语法：

/knowledge add --name <name> --path <path> [--include pattern] [--exclude pattern] [--index-type Fast|Best]

必填参数：

• --name 或 -n：这条 knowledge entry 的可读名称。
• --path 或 -p：要索引的文件或目录路径。

示例：

/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

选择索引模式：Fast 还是 Best？

Fast：Lexical / bm25

Fast 使用关键词检索，适合追求速度和资源占用低的场景。

优点：

• 索引速度快，适合大量文件。
• 查询响应快。
• CPU 和内存占用较低。
• 适合日志、配置和大型代码库。

缺点：

• 语义理解较弱，通常需要命中相近关键词。

Best：Semantic / all-minilm-l6-v2

Best 使用 semantic search，更适合自然语言和概念检索。

优点：

• 能理解上下文和语义。
• 支持用完整句子搜索。
• 没有完全相同关键词时，也可能找到相关内容。
• 适合文档、研究资料和混合内容。

缺点：

• 索引更慢。
• CPU 和内存占用更高。

如何选择？

场景	推荐类型	原因
日志、错误信息	Fast	关键词明确，文件量可能很大
配置文件	Fast	常查参数名和值
大型代码库	Fast	符号、函数、文件名检索更重要
产品文档	Best	更依赖语义理解
研究论文	Best	更适合概念检索
混合资料	Best	整体搜索体验更好

可以设置默认索引类型：

kiro-cli settings knowledge.indexType Fast   # 或 Best

之后不指定 --index-type 时，会使用默认配置。

使用 include/exclude pattern 控制索引范围

不要把整个项目无脑加入 knowledge base。更好的做法是明确包含有价值文件，并排除构建产物、依赖目录和缓存目录。

示例：

/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：

• *.rs：递归匹配所有 Rust 文件，等同于 **/*.rs。
• **/*.py：递归匹配所有 Python 文件。
• target/**：排除 target 目录下所有内容。
• node_modules/**：排除 node_modules 目录下所有内容。

也可以配置默认 patterns：

kiro-cli settings knowledge.defaultIncludePatterns '["**/*.rs", "**/*.py"]'
kiro-cli settings knowledge.defaultExcludePatterns '["target/**", "__pycache__/**"]'

支持的文件类型

Knowledge management 主要处理文本内容：

• 文本：.txt、.log、.rtf、.tex、.rst
• Markdown：.md、.markdown、.mdx
• JSON：.json
• 配置：.ini、.conf、.cfg、.properties、.env
• 数据：.csv、.tsv
• Web 文本格式：.svg
• 代码：.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
• 特殊文件：Dockerfile、Makefile、LICENSE、CHANGELOG、README 等无扩展名文件

不支持的文件可能仍会被记录，但不会抽取可搜索文本内容。

删除、更新和清空

/knowledge remove

按名称、路径或 context ID 删除条目：

/knowledge remove "project-docs"
/knowledge remove /path/to/old/project

/knowledge update

更新已有条目的内容，原有 include/exclude patterns 会保留：

/knowledge update /path/to/updated/project

/knowledge clear

清空所有 knowledge entries：

/knowledge clear

该操作需要确认，而且不可撤销。执行前请确认不再需要这些上下文。

/knowledge cancel

取消后台索引任务，可以取消指定 operation，也可以取消全部：

/knowledge cancel abc12345
/knowledge cancel all

配置项

常用配置包括：

# 每个 knowledge base 最大文件数
kiro-cli settings knowledge.maxFiles 10000

# 文本切块大小
kiro-cli settings knowledge.chunkSize 1024

# 相邻 chunk 的重叠大小
kiro-cli settings knowledge.chunkOverlap 256

# 默认索引类型
kiro-cli settings knowledge.indexType Fast

# 默认 include patterns
kiro-cli settings knowledge.defaultIncludePatterns '["**/*.rs", "**/*.md"]'

# 默认 exclude patterns
kiro-cli settings knowledge.defaultExcludePatterns '["target/**", "node_modules/**"]'

如果项目很大，优先通过 include/exclude 控制范围，再考虑降低 maxFiles 或调整 chunk 大小。

Agent-specific knowledge base

为什么要按 agent 隔离？

每个 agent 都有自己的 knowledge base。这样可以避免“前端 agent 误用后端上下文”“安全审计 agent 看到无关产品资料”等问题，也能让不同 agent 保持更清晰的上下文边界。

存储位置

Knowledge base 会存放在系统本地数据目录：

• 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/
│   ├── contexts.json
│   ├── context-id-1/
│   │   ├── data.json
│   │   └── bm25_data.json
│   └── context-id-2/
│       └── data.json
├── my-custom-agent_<code>/
│   ├── contexts.json
│   └── context-id-3/
│       └── data.json
└── another-agent_<code>/
    ├── contexts.json
    └── context-id-4/
        └── data.json

切换 agent 时会发生什么？

/knowledge 命令总是作用于当前 agent 的 knowledge base：

# 默认 agent
/knowledge add /path/to/docs

# 切换到 custom agent
kiro chat --agent my-custom-agent

# 为 custom agent 创建独立 knowledge base
/knowledge add /path/to/agent/docs

# 切回默认 agent
kiro chat

# 这里只能看到默认 agent 的 docs
/knowledge show

索引和搜索机制

索引过程大致包括：

1. 根据 include/exclude patterns 过滤文件。
2. 递归发现支持的文件类型。
3. 从文件中抽取文本。
4. 把大文件切成可搜索 chunks。
5. 在后台异步处理。
6. 对需要 semantic search 的内容生成 embedding。

搜索时，Kiro 会按相关性排序结果，而不仅仅看关键词是否完全一致。

最佳实践

组织 knowledge base

• 名称要具体：用 api-documentation，不要只叫 docs。
• 先按主题整理目录，再加入 knowledge。
• 使用 include/exclude pattern 聚焦真正有用的文件。
• 定期用 /knowledge update 更新过期内容。

提升搜索效果

• 用自然语言提问，例如“how to handle authentication errors using the knowledge tool”。
• 尽量具体，例如“database connection configuration”。
• 搜不到时换几种表达。
• 明确要求 Kiro 使用 knowledge base，例如“find database connection configuration using your knowledge bases”。

管理大型项目

• 优先添加目录，而不是零散添加大量文件。
• 排除构建产物：--exclude "target/**" --exclude "node_modules/**"。
• 用 /knowledge show 观察索引进度。
• 把大型项目拆成几个逻辑子目录分别加入。

限制

文件类型限制

• 二进制文件不会有可搜索文本。
• 特别大的文件可能被切块，相关内容可能被拆散。
• 专有格式不一定能正确抽取文本。

性能限制

• 大目录索引可能耗时较长。
• 后台任务受并发处理能力限制。
• knowledge base 越大，搜索性能越可能波动。
• 良好的 pattern filtering 能明显改善性能。

存储限制

• 没有明确的存储上限，但存在实际资源限制。
• 不会自动清理旧的或不用的 contexts。
• clear 不可撤销，也没有自动备份。

常见排障

文件没有被索引怎么办？

1. 检查 include patterns 是否覆盖目标文件。
2. 检查 exclude patterns 是否误排除了目标文件。
3. 确认文件类型受支持。
4. 用 /knowledge show 查看索引进度。
5. 确认路径存在且可访问。
6. 查看 CLI 输出中的错误信息。

搜不到预期内容怎么办？

1. 等待索引完成。
2. 换几种自然语言查询方式。
3. 用 /knowledge show 确认内容已添加。
4. 检查文件类型是否能抽取文本。

性能变差怎么办？

1. 用 /knowledge show 查看是否有大量后台任务。
2. 必要时用 /knowledge cancel 取消异常任务。
3. 拆分大型目录。
4. 增加 exclude patterns，减少无效文件。
5. 降低 maxFiles 或调整 chunkSize。

相关功能

• Context Management
• Custom Agents
• Settings Configuration
• Experimental Features

常见问题

Knowledge management 和普通上下文有什么区别？

普通上下文主要存在于当前对话里，knowledge base 可以跨会话保留，并支持检索。它更适合长期复用的项目资料。

Fast 和 Best 应该怎么选？

日志、配置、大型代码库优先 Fast；文档、研究资料、自然语言问答优先 Best。如果不确定，可以先用 Fast 控制成本，再对关键文档使用 Best。

不同 agent 能共享 knowledge 吗？

默认不能。每个 agent 的 knowledge base 是隔离的，这是为了减少上下文冲突。如果需要同一份资料，需要分别添加到对应 agent。