| name | hermes-knowledge-bases |
| description | Use Hermes Dashboard knowledge bases (vector FAISS + GraphRAG) from the agent: list bases, run semantic or graph search, respect indexing status. |
| version | 1.0.0 |
| author | Hermes Agent |
| license | MIT |
| metadata | {"hermes":{"tags":["Research","Knowledge","RAG","Hermes","Dashboard","Vector","GraphRAG","PDF"],"related_skills":["ocr-and-documents"]}} |
Hermes 知识库（向量 + GraphRAG）
在对话中主动使用本机 ~/.hermes（或当前 profile）下与 Dashboard → 知识库 相同的数据：先列库（knowledge_catalog 含 mode），再对 ready 的 vector 库调用 knowledge_vector_query，或对 graphrag 库调用 knowledge_graphrag_query（每次恰好一个 kb_id）。
前置条件
summary_routing_mode（二选一）：在 Dashboard 为每个库选择 — manual（仅手写 agent_summary，索引不跑摘要 LLM，不写 routing_summary.txt；knowledge_catalog 里 routing_summary 恒为 null）、auto（索引成功后由 LLM 写入 routing_summary.txt，手写字段不参与路由）。默认 auto。全局开关 knowledge.routing_summary.enabled: false 时，auto 也不会调用摘要 LLM。routing_summary.txt（自动生成）：在 auto 且全局未关闭时，每次成功向量重建索引末尾由 LLM 写入 knowledge/bases/<kb_id>/routing_summary.txt。REST GET /bases 始终返回磁盘内容（便于调试）；knowledge_catalog 在 manual 下不把该文件放进 routing_summary。agent_summary（手写）：注册表字段；仅在 manual 下用于 Agent 选库（配合名称）。- 工具：默认
hermes-cli / hermes-cron 工具集已通过 includes 并入 knowledge（含 knowledge_catalog、knowledge_list_bases、knowledge_vector_query、knowledge_graphrag_query）。若你的 toolsets 里没有使用 hermes-cli，或显式用了其它组合，再按需加上 knowledge 工具集。
- 向量：需要 embedding（如
OPENAI_API_KEY）与 FAISS（pip install -e ".[web,knowledge]" 等）；不满足时 knowledge_vector_query 会从 schema 中隐藏。GraphRAG：需 [knowledge-graphrag] 与 OPENAI_* / GRAPHRAG_API_KEY；不满足时 knowledge_graphrag_query 隐藏。索引 auto 且全局未关时，重建还需 聊天补全。
- 目标库
indexing_status 为 ready；vector 走 FAISS 工具，graphrag 走 GraphRAG 工具；未就绪时让用户在 Dashboard 上传并「重建索引」。
config.yaml → knowledge.retrieval（与 Dashboard / CLI 共用）：默认 two_stage: true — 服务端先按 recall_per_kb 加宽各库向量召回，合并去重至 max_candidates，再在候选上做 BM25 + 向量分混合（lexical_weight 为 BM25 权重，不是分数阈值）；two_stage: false 与早期行为一致（每库只取请求的 top_k 再合并）。工具返回里 score 为最终排序分；若启用混合，常有 recall_score 表示粗排向量分。详见 docs/zh/knowledge-api.md §1.4、§2.9、§4。
与联网检索（web_search 等）的关系
- 知识库工具只在模型主动调用时运行；没有在每轮对话前自动注入整库内容（横切
pre_llm_call 注入仍为规划项）。
- 检索范围是 本机已上传并建索引的文档，不是公网全文；需要实时新闻、官网说明、股价等应使用
web_search / web_extract（或浏览器工具），与知识库互补，不是二选一互斥，但不要用 knowledge_vector_query 代替公网搜索。
- 调用
knowledge_vector_query 时会走 embedding API（与 Dashboard 一致），这是访问嵌入服务端点的网络请求，与「网页搜索」不是同一路能力。
推荐流程（先摘要选库，再按 mode 检索）
先读轻量路由信息，再 RAG：knowledge_catalog 返回 mode、summary_routing_mode、routing_summary（按模式可能为 null）、agent_summary。按 hint 与摘要选库后：mode=vector → knowledge_vector_query（可多库）；mode=graphrag → knowledge_graphrag_query（单次调用只能一个 kb_id；graphrag_method 常用 auto，由 knowledge.graphrag.auto_method 在 local/global/basic 间启发式选择，响应里带 resolved_graphrag_method）。
与联网的关系（软性）：若问题有可能落在已索引材料里，可先 knowledge_catalog → 对应查询工具，再视需要补 web_search / web_extract。
| 步骤 | 工具 | 说明 |
|---|
| 1 | knowledge_catalog | 含 mode、summary_routing_mode；manual 时只用 agent_summary；auto 用 routing_summary |
| 2 | knowledge_vector_query 或 knowledge_graphrag_query | vector：多 kb_ids + query；graphrag：单 id + query + 可选 graphrag_method |
| （可选） | knowledge_list_bases | 调试分块等完整元数据 |
若某库 manual 且 agent_summary 为空，则主要依赖 name。
kb_ids 为空：若运行环境设置了 HERMES_ACTIVE_KB_IDS（逗号分隔），向量工具可使用多个 id；GraphRAG 工具仅支持恰好一个 id（多库请分次调用或显式传一个 uuid）。top_k（向量）：默认 8；回答时注明来源与相关性。
与纯网页操作的区别
- 工具走 本机 Python 管线（
query_vector_bases），不经过浏览器 HTTP，适合 CLI / TUI / Gateway。
- 若用户只在 Dashboard 勾选知识库而未设置环境变量，CLI 中需自行从列表选 id 填入
kb_ids。
不要做的事
- 不要在
indexing_status 不是 ready 的库上反复查询（先提醒用户重建索引）。
- 不要把整段工具返回无筛选地贴进回答；选取与问题最相关的几条并摘要。
- 不要把知识库当成 公网实时检索；用户问「网上最新」「官网」时用
web_search。
